[groff] 08/37: [doc,man]: Fix content and style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit f937c63e041e1edd5950856de6caa1df2a6f04a4
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Sep 26 21:52:19 2024 -0500

    [doc,man]: Fix content and style nits.
    
    Content:
    * Since spaces normally separate request arguments, use fixed language
      recognizing that fact when documenting the few exceptions.
    * Use idiomatic metasyntactic var "str" to refer to presumptively
      already defined strings in request synopses.
    * man/groff_diff.7.man: Retitle section "Extended requests" to "Altered
      requests", since not every behavior change is a compatible extension.
    
    Style:
    * Quote "warn" in addition to boldfacing it where it could be
      misinterprted as part of a sentence with formatting stripped.
    * man/groff_diff.7.man: Spell request names without leading dot when
      used inline.
    * Tighten wording.
---
 doc/groff.texi.in    | 34 +++++++++++++++++-----------------
 man/groff_diff.7.man | 29 +++++++++++++++--------------
 2 files changed, 32 insertions(+), 31 deletions(-)

diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 1572bd9d1..2a6c40d7e 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -11207,9 +11207,9 @@ have different properties.  The only ones known to GNU 
@code{troff} are
 those in its font's description file.  Recall @ref{Using Fonts}.}  These
 properties can be modified with this request.  The first argument is the
 sum of the desired flags and the remaining arguments are the characters
-to be assigned those properties.  Spaces between the @var{cn} arguments
-are optional.  Any argument @var{cn} can be a character class defined
-with the @code{class} request rather than an individual character.
+to be assigned those properties.  Spaces need not separate the @var{cn}
+arguments.  Any argument @var{cn} can be a character class defined with
+the @code{class} request rather than an individual character.
 @xref{Character Classes}.
 
 The non-negative integer @var{n} is the sum of any of the following.
@@ -11354,18 +11354,18 @@ Define an ordinary or special character@tie{}@var{c} 
as @var{contents}.
 If @var{contents} is absent, an existing character definition made with
 the same request is deleted.
 
-Defining (or redefining) a character @var{c} creates an object in the
-formatter that is recognized like any other ordinary or special
-character on input, and produces @var{contents} on output.  Every time
-@var{c} is to be output, @var{contents} is processed in a temporary
-environment and the result encapsulated in a node.@footnote{@xref{Gtroff
-Internals}.} A leading neutral double quote in the final argument is
-stripped from it, allowing embedded leading spaces in @var{contents},
-which is read in copy mode and continues to the end of the input line.
-Further, compatibility mode is disabled and the escape character set to
-@code{\} while @var{contents} is interpreted.  Any emboldening, constant
-spacing, or track kerning is applied to this object rather than to
-individual glyphs in @var{contents}.
+Defining (or redefining) a character @var{c} creates a formatter object
+that is recognized like any other ordinary or special character on
+input, and produces @var{contents} on output.  Every time @var{c} is to
+be output, @var{contents} is processed in a temporary environment and
+the result encapsulated in a node.@footnote{@xref{Gtroff Internals}.} A
+leading neutral double quote in the final argument is stripped from it,
+allowing embedded leading spaces in @var{contents}, which is read in
+copy mode and continues to the end of the input line.  Further,
+compatibility mode is disabled and the escape character set to @code{\}
+while @var{contents} is interpreted.  Any emboldening, constant spacing,
+or track kerning is applied to this object rather than to individual
+glyphs in @var{contents}.
 
 A character defined by these requests can be used just like a glyph
 provided by the output device.  In particular, other characters can be
@@ -11422,7 +11422,7 @@ request, but before the already mounted special fonts.
 Remove definition of each ordinary or special character @var{c},
 undoing the effect of a @code{char}, @code{fchar}, or @code{schar}
 request.  Those supplied by font description files cannot be removed.
-Spaces and tabs may separate @var{c}@tie{}arguments.
+Spaces need not separate @var{c}@tie{}arguments.
 
 The request @code{rfschar} removes glyph definitions defined with
 @code{fschar} for font@tie{}@var{f}.
@@ -17803,7 +17803,7 @@ helpful in avoiding use of these escape sequences in 
names.
 @cindex end-of-sentence detection, cancellation, on @acronym{AT&T} @code{troff}
 @cindex sentence, cancelling detection of end of, on @acronym{AT&T} 
@code{troff}
 @acronym{AT&T} @command{troff} discards trailing spaces from input
-lines, like GNU @command{troff}, but if it does so, @acronym{AT&T}
+lines, like GNU @command{troff}, but when it does so, @acronym{AT&T}
 @command{troff} also cancels end-of-sentence detection.  Use of the
 dummy character escape sequence @code{\&} is more portable.
 
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index aa5e941ea..a006e8549 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1806,9 +1806,9 @@ see
 The first argument is the sum of the desired flags and the remaining
 arguments are the characters to be assigned those properties.
 .
-Spaces between the
+Spaces need not separate the
 .I cn
-arguments are optional.
+arguments.
 .
 Any argument
 .I cn
@@ -1991,7 +1991,7 @@ Defining
 (or redefining)
 a
 .RI character\~ c
-creates an object in the formatter that is recognized like any other
+creates a formatter object that is recognized like any other
 ordinary or special character on input,
 and produces
 .I contents
@@ -2031,8 +2031,9 @@ not to each character in
 .
 .
 .IP
-A character defined by this request can be used just like a glyph
-provided by the output device.
+A character defined by
+.B char
+can be used just like a glyph provided by the output device.
 .
 In particular,
 other characters can be translated to it with the
@@ -3472,7 +3473,7 @@ Remove each fallback special
 for font
 .IR f .
 .
-Spaces and tabs may separate
+Spaces need not separate
 .I c
 arguments.
 .
@@ -3691,10 +3692,10 @@ with non-negative font mounting
 .
 .
 .TP
-.BI .substring\~ "string start\~"\c
+.BI .substring\~ "str start\~"\c
 .RI [ end ]
 Replace the string named
-.I string
+.I str
 with its substring bounded by the indices
 .I start
 and
@@ -4037,10 +4038,9 @@ is read in copy mode.
 .br
 .ne 6v
 .\" ====================================================================
-.SS "Extended requests"
+.SS "Altered requests"
 .\" ====================================================================
 .
-.\" XXX: .cf might better belong in "Implementation differences".
 .TP
 .BI .cf\~ file
 In a diversion,
@@ -4129,7 +4129,8 @@ Negative values are erroneous.
 .IR "n1 n2\~" .\|.\|.\~ nn \~]\c
 .BR T \~\c \" space in roman because we must use 2-font macro with \c
 .IR "r1 r2\~" .\|.\|.\~ rn ]
-.I groff
+GNU
+.I troff \" GNU
 supports an extended syntax to specify repeating tab stops after
 the
 .RB \[lq] T \[rq]
@@ -5483,7 +5484,7 @@ GNU
 emits more error diagnostics when syntactical or semantic nonsense is
 encountered and supports several warning categories;
 the output of these can be selected with
-.BR warn .
+.RB \[lq] warn \[rq].
 .
 Also see the
 .BR \-E ,
@@ -5524,7 +5525,7 @@ hyphenation exceptions
 registers
 .RB ( pnr ),
 open streams
-.RB ( .pstream ),
+.RB ( pstream ),
 page location traps
 .RB ( ptr ),
 and a list of output nodes corresponding to the pending input
@@ -5696,7 +5697,7 @@ AT&T
 discards trailing spaces from input lines,
 like GNU
 .IR troff , \" GNU
-but if it does so,
+but when it does so,
 AT&T
 .I troff \" AT&T
 also cancels end-of-sentence detection.