[groff] 03/09: [man pages]: Fix content, style, formatting nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 7ac5f533683eb83cbd5bb198990a5843eb387cb9
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Oct 11 03:15:54 2021 +1100

    [man pages]: Fix content, style, formatting nits.
    
    Content:
    * groff(7): Parallelize descriptions of box and diversion requests and
      make it clearer that, and how, boxes differ only in pending output
      line handling.
    * We say that macros are "called", not "invoked".
    * Add `PF` as a recognized pic(1)-related macro.
    
    Style:
    * Tighten wording.
    * Drop copy-and-paste cruft.
    * Close parenthetical with a parenthesis, not a brace.
    * Fix typos.
    
    Formatting:
    * Repair missing space.
    * Keep table heading in groff_me(7) together with first data row.
---
 man/groff.7.man                 | 60 ++++++++++++++++++++++-------------------
 man/roff.7.man                  |  2 +-
 src/devices/grotty/grotty.1.man |  6 +++--
 tmac/groff_man.7.man.in         |  2 +-
 tmac/groff_me.7.man             |  1 +
 5 files changed, 40 insertions(+), 31 deletions(-)

diff --git a/man/groff.7.man b/man/groff.7.man
index 9e3ec8d..5fcf1ca 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -987,7 +987,7 @@ line
 It is frequently desirable for a control structure to govern more than
 one request,
 call more than one macro,
-span more than one input line of text,
+span more than one text line,
 or mix the foregoing.
 .
 The opening and closing brace escapes
@@ -1477,25 +1477,26 @@ Set blank line macro (trap) to
 .
 .TPx
 .REQ .box
-Stop directing output to current box diversion.
+Stop directing output to current diversion;
+any pending output line is discarded.
 .
 .
 .TPx
-.REQ .box "name"
-Divert output to
+.REQ .box name
+Direct output to diversion
 .IR name ,
 omitting a partially collected line.
 .
 .
 .TPx
 .REQ .boxa
-Stop appending output to current box diversion.
+Stop appending output to current diversion;
+any pending output line is discarded.
 .
 .
 .TPx
-.REQ .boxa "name"
-Divert output,
-appending it to
+.REQ .boxa name
+Append output to diversion
 .IR name ,
 omitting a partially collected line.
 .
@@ -1568,14 +1569,14 @@ and so on.
 .
 .
 .TPx
-.REQ .ch "name N"
-Change location of page location trap by moving macro
+.REQ .ch "name \fR[\fPN\fR]"
+Change a planted page location trap
 .I name
-to new location
+by moving its location to
 .IR N ,
 or by unplanting it altogether if
 .I N
-absent.
+is absent.
 .
 .
 .TPx
@@ -1654,14 +1655,17 @@ Continuous underline in nroff, like
 .request .ul
 in troff.
 .
+.
 .TPx
 .REQ .da
-End current diversion.
+Stop appending output to current diversion.
+.
 .
 .TPx
-.REQ .da "macro"
-Divert and append to
-.IR macro .
+.REQ .da name
+Append output to diversion
+.IR name .
+.
 .
 .TPx
 .REQ .de "macro"
@@ -1787,17 +1791,17 @@ Write contents of macro or string
 .I name
 uninterpreted to the intermediate output as a device control function.
 .
+.
 .TPx
 .REQ .di
-End current diversion.
+Stop directing output to current diversion.
+.
 .
 .TPx
-.REQ .di "macro"
-Divert to
-.IR macro .
-See
-.MR groff_tmac @MAN5EXT@
-for more details.
+.REQ .di name
+Direct output to diversion
+.IR name .
+.
 .
 .TPx
 .REQ .do "name \fR\&.\|.\|.\&\fP"
@@ -1886,7 +1890,7 @@ request was false.
 .
 .TPx
 .REQ .em name
-Invoke macro
+Call macro
 .I name
 after the end of input.
 .
@@ -3147,7 +3151,9 @@ grap^.G1^.G2
 .\" Keep the .IF line below the @g@ideal line.
 @g@ideal^.IS^.IE
 ^^.IF
+.\" Keep the .PF line below the @g@pic line.
 @g@pic^.PS^.PE
+^^.PF
 @g@refer^.R1^.R2
 @g@soelim^\f[I]none^\f[I]none
 @g@tbl^.TS^.TE
@@ -3704,7 +3710,6 @@ Interpolate format of register with one-character
 .ESC g( rg
 Interpolate format of register with two-character
 .RI name\~ rg .
-.IR rg .
 .
 .
 .TP
@@ -3725,7 +3730,8 @@ right
 .TP
 .ESCq H N
 Set height of current font to
-.IR N \~scaled points
+.IR N \~scaled
+points
 (or specified units).
 .
 .
@@ -4163,7 +4169,7 @@ character encodings that use characters from these ranges.
 .
 (Consider what happens when a C1 control
 .BR 0x80 \[en] 0x9F
-is necessary as a continuation byte in a UTF-8 sequence.}
+is necessary as a continuation byte in a UTF-8 sequence.)
 .
 .
 .IP
diff --git a/man/roff.7.man b/man/roff.7.man
index 23a70c1..abf9064 100644
--- a/man/roff.7.man
+++ b/man/roff.7.man
@@ -758,7 +758,7 @@ pipelines may have to be simulated.)
 .
 .
 .P
-One all preprocessors have run,
+Once all preprocessors have run,
 they deliver a pure
 .I roff
 document to the formatter,
diff --git a/src/devices/grotty/grotty.1.man b/src/devices/grotty/grotty.1.man
index 3deb9de..4a3aa7c 100644
--- a/src/devices/grotty/grotty.1.man
+++ b/src/devices/grotty/grotty.1.man
@@ -390,7 +390,7 @@ Use
 legacy output format
 (see subsection \[lq]Legacy output format\[rq] above).
 .
-OSC\~8 hyperlink terminal escape sequences are not emitted.
+SGR and OSC escape sequences are not emitted.
 .
 .
 .TP
@@ -531,7 +531,9 @@ and
 .I GROFF_NO_SGR
 If set,
 .IR grotty 's
-legacy output format is used;
+legacy output format is used just as if the
+.B \-c
+option were specified;
 see subsection \[lq]Legacy output format\[rq] above.
 .
 .
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 500fabb..31a2f4e 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -1138,7 +1138,7 @@ Hyperlinked text is supported on the
 and
 .B tty
 output devices;
-terminals and pager programs must support EMCA-48 OSC\~8 escape
+terminals and pager programs must support ECMA-48 OSC\~8 escape
 sequences
 (see
 .MR grotty @MAN1EXT@ ).
diff --git a/tmac/groff_me.7.man b/tmac/groff_me.7.man
index bf8aab7..64e78f5 100644
--- a/tmac/groff_me.7.man
+++ b/tmac/groff_me.7.man
@@ -197,6 +197,7 @@ See the \[lq]\-me Reference Manual\[rq] for further details.
 .
 .
 .P
+.ne 3v \" Keep at least the first entry together with the heading.
 .TS
 lB lB lB lBx
 lB lB lB lBx