[groff] 15/19: [docs]: Fix content, style, and markup nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit ca6a16874bd6f8103f838750ce6eae4542e4e727
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon May 29 05:55:19 2023 -0500

    [docs]: Fix content, style, and markup nits.
    
    * doc/groff.texi:
      - Soften the distinction between boxes and diversions more.
      - Use man page cross reference style for `getenv` and `strtol`.
      - Fix typo.
      - Recast descriptions of `tm`, `tm1`, `tmc` for economy.
      - Mark metasyntactic variable with slanted face in example.
      - Remove characterization of internal detail of macro/string/diversion
        storage.
      - Adjust dead-tree pagination.
    
    * man/groff_diff.7.man: Sync with the foregoing.
---
 doc/groff.texi       | 39 +++++++++++++++++----------------------
 man/groff_diff.7.man | 41 +++++++++++++++++++++++------------------
 2 files changed, 40 insertions(+), 40 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index be1864aa0..8b587e751 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -15058,18 +15058,15 @@ After the diversion.
 @endDefreq
 
 @cindex box (diversion operation)
-Because it is often desirable to exclude the partially collected line
-from a diversion, @code{groff} supports an alternative form of diversion
-known as a @dfn{box}.
+GNU @code{troff} supports @dfn{box} requests to exclude a partially
+collected line from a diversion, as this is often desirable.
 
 @DefreqList {box, [@Var{name}]}
 @DefreqListEndx {boxa, [@Var{name}]}
 Divert (or append) output to @var{name}, similarly to the @code{di} and
-@code{da} requests, respectively.  Any output line pending when these
-requests are invoked is @emph{not} included in the box.  Calling
-@code{box} or @code{boxa} without an argument stops diverting output to
-the box named by the most recent corresponding request; a pending output
-line inside a diversion is discarded.
+@code{da} requests, respectively.  Any pending output line is @emph{not}
+included in the diversion.  Without an argument, stop diverting output;
+any pending output line inside the diversion is discarded.
 
 @Example
 Before the box.
@@ -16087,8 +16084,8 @@ Here a simple macro to write an index entry.
 @cindex mode, copy, and @code{\V}
 Interpolate the contents of the specified environment variable @var{env}
 (one-character name@tie{}@var{e}, two-character name @var{ev}) as
-returned by the function @code{getenv}.  @code{\V} is interpreted even
-in copy mode (@pxref{Copy Mode}).
+returned by the function @cite{getenv@r{(3)}}.  @code{\V} is interpreted
+even in copy mode (@pxref{Copy Mode}).
 @endDefesc
 
 
@@ -16530,6 +16527,7 @@ restore tokens are removed.
 
 @c =====================================================================
 
+@need 1000
 @c BEGIN Keep parallel with section "Debugging" of groff(7).
 @node Debugging, Implementation Differences, Gtroff Internals, GNU troff 
Reference
 @section Debugging
@@ -16578,7 +16576,7 @@ request is ignored.
 
 @code{lf}'s primary purpose is to aid the debugging of documents that
 undergo preprocessing.  Programs like @command{tbl} that transform input
-in their own languages intoto @code{roff} requests use it so that any
+in their own languages into @code{roff} requests use it so that any
 diagnostic messages emitted by @code{troff} correspond to the source
 document.
 @endDefreq
@@ -16589,15 +16587,14 @@ document.
 @cindex printing to stderr (@code{tm}, @code{tm1}, @code{tmc})
 @cindex stderr, printing to (@code{tm}, @code{tm1}, @code{tmc})
 Send @var{message}, which consumes the remainder of the input line and
-cannot contain special characters, to the standard error stream.
+cannot contain special characters, to the standard error stream,
+followed by a newline.  Leading spaces in @var{message} are ignored.
 
-The @code{tm} request ignores leading spaces of @var{contents};
-@code{tm1} handles its argument similarly to the @code{ds} request: an
-initial neutral double quote is stripped to allow embedding of leading
+@code{tm1} is similar, but recognizes and strips a leading neutral
+double quote from @var{message} to allow the embedding of leading
 spaces.
 
-The @code{tmc} request is similar to @code{tm1} but does not append a
-newline (as is done in @code{tm} and @code{tm1}).
+@code{tmc} works as @code{tm1}, but does not append a newline.
 @endDefreq
 
 @Defreq {ab, [@Var{message}]}
@@ -16627,7 +16624,7 @@ To activate such statements, use the @option{-r} option 
to set the
 register.
 
 @Example
-groff -rDB=1 file
+groff -rDB=1 @slanted{file}
 @endExample
 
 If it is known in advance that there are many errors and no useful
@@ -16645,9 +16642,7 @@ other environments to the standard error stream.
 @cindex dumping symbol table (@code{pm})
 @cindex symbol table, dumping (@code{pm})
 Report, to the standard error stream, the names of all defined macros,
-strings, and diversions with their sizes in bytes.  Since GNU
-@code{troff} sometimes adds nodes by itself, the returned sizes can be
-larger than expected.
+strings, and diversions with their sizes in bytes.
 @endDefreq
 
 @Defreq {pnr, }
@@ -18729,7 +18724,7 @@ The @var{code} field gives a numeric identifier that 
the postprocessor
 uses to render the glyph.  The glyph can be specified to @code{troff}
 using this code by means of the @code{\N} escape sequence.  @var{code}
 can be any integer.@footnote{that is, any integer parsable by the C
-standard library's @code{strtol} function}
+standard library's @cite{strtol@r{(3)}} function}
 
 The @var{entity-name} field defines an identifier for the glyph that the
 postprocessor uses to print the GNU @code{troff} glyph @var{name}.  This
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 1bc125549..5eea57ac9 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1445,18 +1445,24 @@ the default blank line behavior is (re-)established.
 .BI .box\~ name
 .TQ
 .BI .boxa\~ name
-These requests are similar to the
+Divert
+(or append)
+output to
+.I name,
+similarly to the
 .B di
 and
 .B da
 requests,
-respectively,
-with the exception that any pending output line does not become part of
-the diversion
-(i.e.,
-a box diversion always starts on a new output line)
-but is restored after ending the diversion,
-discarding any partially collected line in the diversion.
+respectively.
+.
+Any pending output line is
+.I not
+included in the diversion.
+.
+Without an argument,
+stop diverting output;
+any pending output line inside the diversion is discarded.
 .
 .
 .TP
@@ -3444,21 +3450,20 @@ and less than or equal to
 the increase in width is a linear function of the type size.
 .
 .TP
-.BI .tm1\~ contents
-Similar to the
+.BI .tm1\~ message
+As
 .B tm
 request,
-.I contents
-is read in copy mode and written on the standard error,
-but an initial neutral double quote in
-.I contents
-is stripped off to allow embedding of leading spaces.
+but recognizes and strips a leading neutral double quote from
+.I message
+to allow the embedding of leading spaces.
 .
 .TP
-.BI .tmc\~ contents
-Similar to
+.BI .tmc\~ message
+As
 .B tm1
-but without writing a final newline.
+request,
+but does not append a newline.
 .
 .TP
 .BI .trf\~ filename