[groff] 16/17: groff(7), groff_diff(7): Fix content nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit b3b83807498e5aa42c3f3000a0f621da0fb01a0c
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Jun 7 16:57:50 2023 -0500

    groff(7), groff_diff(7): Fix content nits.
    
    * Clarify and use terminology with more discipline in short references.
    * Migrate from page-local `request` macro when it doesn't affect the
      output.
    * Use more meaningful metasyntactic variable names.
    * Tighten wording, buying back a page in groff(7).
---
 man/groff.7.man      | 78 +++++++++++++++++++++++++++-------------------------
 man/groff_diff.7.man | 61 ++++++++++++++++++++--------------------
 2 files changed, 71 insertions(+), 68 deletions(-)

diff --git a/man/groff.7.man b/man/groff.7.man
index 661c5b7df..251ce4dc7 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2805,9 +2805,9 @@ occurs at the start of a control line in the current 
conditional block.
 Define or redefine
 .I macro
 until
-.BI . end
-is called at the start of a control line in the current conditional
-block.
+.I end
+is invoked or called at the start of a control line in the current
+conditional block.
 .
 .
 .TPx
@@ -2819,7 +2819,8 @@ but disable compatibility mode during macro expansion.
 .TPx
 .REQ .de1 "macro end"
 As
-.request ".de\~\f[I]macro\~end\f[]" ,
+.RB \[lq] .de
+.IR "macro end" \[rq],
 but disable compatibility mode during macro expansion.
 .
 .
@@ -3198,16 +3199,20 @@ to
 .IR font2 .
 .
 .TPx
-.REQ .fzoom "font"
-Don't magnify
+.REQ .fzoom font
+.TQ
+.REQ .fzoom font\~\f[CB]0\f[]
+Stop magnifying
 .IR font .
 .
 .TPx
-.REQ .fzoom "font zoom"
+.REQ .fzoom "font z"
 Set zoom factor for
 .I font
-(in multiples of 1/1000th).
-.
+.RI to\~ z
+(in thousandths;
+default:
+1000).
 .
 .TPx
 .REQ .gcolor
@@ -3265,20 +3270,19 @@ Append hyphenation patterns from
 .
 .TPx
 .REQ .hpfcode "a b \fR[\fPc d\fR] .\|.\|.\fP"
-Define mapping values for character codes in pattern files read with the
+Define mappings for character codes in hyphenation pattern files read
+with
 .request .hpf
 and
-.request .hpfa
-requests.
+.request .hpfa .
 .
 .TPx
 .REQ .hw "word \fR.\|.\|.\fP"
-Define how each
-.I  word
-is to be hyphenated,
-with each hyphen
+Define hyphenation overrides for each
+.I word;
+a hyphen
 .RB \[lq] \- \[rq]
-indicating a hyphenation point.
+indicates a hyphenation point.
 .
 .
 .TPx
@@ -3322,13 +3326,13 @@ Set the hyphenation space to
 .
 .TPx
 .REQ .hys hyphenation-space
-Suppress hyphenation of the line in adjustment modes
+Suppress automatic hyphenation in adjustment modes
 .RB \[lq] b \[rq]
 or
 .RB \[lq] n \[rq]
-if it can be justified by adding no more than
+if the line can be justified with the addition of up to
 .I hyphenation-space
-extra space to each inter-word space
+to each inter-word space
 (default scaling unit\~\c
 .scaleindicator m ).
 .
@@ -4132,16 +4136,16 @@ is
 .REQ .ss n
 Set minimal inter-word spacing to
 .IR n \~12ths
-of the space width of the current font.
+of current font's space width.
 .
 .TPx
 .REQ .ss "n m"
 As
-.B .ss\~\c
-.IR n ,
+.RB \[lq] .ss\~\c
+.IR n \[rq],
 and set additional inter-sentence space to
 .IR m \~12ths
-of the space width of the current font.
+of current font's space width.
 .
 .TPx
 .REQ .stringdown stringvar
@@ -4281,7 +4285,7 @@ Enable track kerning for
 .TPx
 .REQ .tl "\f[CB]\[aq]\f[]left\f[CB]\[aq]\f[]center\f[CB]\[aq]\f[]right\
 \f[CB]\[aq]\f[]"
-Three-part title.
+Format three-part title.
 .
 .TPx
 .REQ .tm message
@@ -4307,14 +4311,14 @@ without emitting a newline.
 .
 .TPx
 .REQ .tr "abcd\fR\&.\|.\|.\&\fP"
-Translate
+Translate ordinary or special characters
 .I a
 to
 .IR b ,
 .I c
 to
 .IR d ,
-etc.\& on output.
+and so on prior to output.
 .
 .TPx
 .REQ .trf file
@@ -4329,19 +4333,17 @@ are rejected.
 .
 .TPx
 .REQ .trin "abcd\fR\&.\|.\|.\&\fP"
-This is the same as the
-.request .tr
-request except that the
-.B asciify
-request uses the character code (if any) before the character
-translation.
+As
+.request .tr ,
+except that
+.request .asciify
+ignores the translation when a diversion is interpolated.
 .
 .TPx
 .REQ .trnt "abcd\fR\&.\|.\|.\&\fP"
-This is the same as the
-.request .tr
-request except that the translations do not apply to text that is
-transparently throughput into a diversion with
+As
+.request .tr ,
+except that translations are suppressed in the argument to
 .esc ! .
 .
 .TPx
@@ -5559,7 +5561,7 @@ These are useful for
 exercising device-specific capabilities that the
 .I groff
 language does not abstract or generalize;
-examples include the embedding of hyperlinks and image files.
+such functions include the embedding of hyperlinks and image files.
 .
 Device-specific functions are documented in
 each output driver's man page.
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 38d5eb1e1..fe74bafca 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -447,11 +447,11 @@ is a Unicode basic Latin character;
 a
 .I groff
 special character
-.BI \[rs]( xx
+.BI \[rs]( ch
 or
-.BI \[rs][ xxx\c
+.BI \[rs][ char\c
 .BR ] ;
-.BI \[rs]N\[aq] xxx\c
+.BI \[rs]N\[aq] idx\c
 .BR \[aq] ;
 or has been defined by any of the
 .BR .char ,
@@ -580,7 +580,7 @@ and then by symbol roughly in Unicode code point order.
 .\" order more agreeable to the development of a topic.
 .
 .
-.TP
+.TP 7.5 \" sinfully obtain better pagination on typesetters
 .BI \[rs]A\[aq] anything \[aq]
 Interpolate 1 if
 .I anything
@@ -607,7 +607,7 @@ and\~0 otherwise.
 You might use
 .B \[rs]B
 along with the
-.RB \[lq] if \[rq]
+.RB \[lq]\| if \|\[rq]
 request to filter out invalid macro or string arguments.
 .
 .
@@ -720,7 +720,7 @@ it selects the previous font.
 .TQ
 .BI \[rs]F( fm
 .TQ
-.BI \[rs]F[ fam ]
+.BI \[rs]F[ family ]
 Select font family.
 .
 See the
@@ -747,11 +747,11 @@ or arbitrarily long
 .
 .
 .TP
-.BI \[rs]m x
+.BI \[rs]m c
 .TQ
-.BI \[rs]m( xx
+.BI \[rs]m( cl
 .TQ
-.BI \[rs]m[ xxx ]
+.BI \[rs]m[ col ]
 Set the stroke color.
 .
 .B \[rs]m[]
@@ -759,11 +759,11 @@ restores the previous stroke color.
 .
 .
 .TP
-.BI \[rs]M x
+.BI \[rs]M c
 .TQ
-.BI \[rs]M( xx
+.BI \[rs]M( cl
 .TQ
-.BI \[rs]M[ xxx ]
+.BI \[rs]M[ col ]
 Set the fill color.
 .
 .B \[rs]M[]
@@ -771,9 +771,9 @@ restores the previous fill color.
 .
 .
 .TP
-.BI \[rs]n[ xxx ]
+.BI \[rs]n[ reg ]
 Interpolate register
-.IR xxx .
+.IR reg .
 .
 .
 .TP
@@ -928,13 +928,13 @@ is a numeric expression with a default scaling unit
 .br
 .ne 5v
 .TP
-.BI \[rs]V x
+.BI \[rs]V e
 .TQ
-.BI \[rs]V( xx
+.BI \[rs]V( ev
 .TQ
-.BI \[rs]V[ xxx ]
+.BI \[rs]V[ env ]
 Interpolate the contents of the environment variable
-.IR xxx ,
+.IR env ,
 as returned by
 .MR getenv 3 .
 .
@@ -1010,17 +1010,18 @@ is currently employed only by
 .
 .
 .TP
-.BI \[rs]Y x
+.BI \[rs]Y m
 .TQ
-.BI \[rs]Y( xx
+.BI \[rs]Y( ma
 .TQ
-.BI \[rs]Y[ xxx ]
+.BI \[rs]Y[ mac ]
 This is approximately equivalent to
-.BI \[rs]X\[aq]\[rs]*[ xxx ]\[aq]\f[R].
+.BI \[rs]X\[aq]\[rs]*[ mac ]\[aq]\f[R].
 However the contents of the string or macro
-.I xxx
-are not interpreted; also it is permitted for
-.I xxx
+.I mac
+are not interpreted;
+also it is permitted for
+.I mac
 to have been defined as a macro and thus contain newlines (it is not
 permitted for the argument to
 .B \[rs]X
@@ -1123,10 +1124,10 @@ does not.
 .
 .
 .TP
-.BI \[rs]*[ "xxx arg1 arg2\~"\c
+.BI \[rs]*[ "string arg1 arg2\~"\c
 \&.\|.\|.]
-Interpolate string
-.IR xxx ,
+Interpolate
+.IR string ,
 taking
 .IR arg1 ,
 .IR arg2 ,
@@ -1262,9 +1263,9 @@ prints\~\c
 .BR 4 .
 .
 .TP
-.BI \[rs][ xxx ]
+.BI \[rs][ char ]
 Typeset the special character (glyph)
-.IR xxx .
+.IR char .
 .
 .TP
 .BI \[rs][ "base-char combining-component\~"\c