[groff] 02/35: [man pages]: Fix content, style, markup nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 922751f8bf764b513e61ac634f7e52aaa6565d6e
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Feb 14 18:43:15 2022 +1100

    [man pages]: Fix content, style, markup nits.
    
    Content:
    * Improve example in grops(1) to be more effective; just setting an
      unexported environment variable won't work.  Show the command
      following it on the same input line.
    * groff_me(7) (Files): Document use of refer-me.tmac file.
    * groff_ms(7) (Files): Documsnt use of refer-ms.tmac file.
    * grops(1): Fix missing colon after tag in device control command
      example.
    
    Style:
    * When joining two independent clauses with a colon, the second is not
      to be capitalized as a sentence.
    * Stop dangling an example command line as the incomplete end of a
      sentence.
    * Recast and tighten.
    
    Markup:
    * grops(1): Use RS/EX/EE/RE to bracket examples, not IP/B.  Reduce use
      of vertical spacing around examples that are inlined into sentences.
      Set command names in italics, not bold.  Try a new idiom for
      multi-paragraph tagged item discussions with embedded examples.
    * groff_tmac(5): Mark up man(1) and (g)soelim references with `MR` and
      `I`, respectively.
    * Break lines before multi-word parentheticals and after commas.
    * Use `P` paragraphing macro instead of `LP`.
    
    Partially addresses <https://savannah.gnu.org/bugs/?61958>.
---
 man/groff_tmac.5.man          | 11 ++++--
 src/devices/grops/grops.1.man | 87 ++++++++++++++++++++++++++-----------------
 tmac/groff_me.7.man           | 20 ++++++++--
 tmac/groff_ms.7.man           | 15 ++++++--
 tmac/groff_www.7.man          | 14 +++++--
 5 files changed, 98 insertions(+), 49 deletions(-)

diff --git a/man/groff_tmac.5.man b/man/groff_tmac.5.man
index df08774c..2599e071 100644
--- a/man/groff_tmac.5.man
+++ b/man/groff_tmac.5.man
@@ -1069,11 +1069,14 @@ the roff preprocessor
 must be called if the files to be included need preprocessing.
 .
 This can be done either directly by a pipeline on the command line or
-by using the troff/groff option
-.BR \-s .
+by giving the formatter the
+.B \-s
+option.
 .
-.I man
-calls soelim automatically.
+.MR man 1
+calls
+.I \%@g@soelim
+automatically.
 .
 .
 .P
diff --git a/src/devices/grops/grops.1.man b/src/devices/grops/grops.1.man
index 855a39da..8ad8d65b 100644
--- a/src/devices/grops/grops.1.man
+++ b/src/devices/grops/grops.1.man
@@ -832,19 +832,22 @@ is a PostScript LanguageLevel\~2 command and thus not 
available on some
 older printers.
 .
 .
-.LP
-.B grops
-understands various X\~commands produced using the
+.P
+.I grops
+recognizes
+.BR X \~commands
+produced by the
 .B \[rs]X
-escape sequence;
-.B grops
-only interprets commands that begin with a
+escape sequence,
+but interprets only those that begin with a
 .B ps:
 tag.
 .
+.
 .TP
 .BI "\[rs]X\[aq]ps: exec\~" code \[aq]
-This executes the arbitrary PostScript commands in
+.RS
+Execute the arbitrary PostScript commands
 .IR code .
 .
 The PostScript currentpoint is set to the position of the
@@ -869,14 +872,12 @@ basic units to the coordinate system in effect
 For example,
 .
 .RS
-.IP
 .EX
 \&.nr x 1i
 \[rs]X\[aq]ps: exec \[rs]nx u 0 rlineto stroke\[aq]
 .EE
 .RE
 .
-.IP
 draws a horizontal line one inch long.
 .
 .I code
@@ -887,13 +888,13 @@ A dictionary containing the definitions specified by the
 .B def
 and
 .B mdef
-is on top of the dictionary stack.
+commands is on top of the dictionary stack.
 .
 If your code adds definitions to this dictionary,
 you should allocate space for them using
-.BI "\[rs]X\[aq]ps mdef\~" n \[aq]\c
-\&.
-.
+.RB \[lq] "\[rs]X\[aq]ps: mdef\~"
+.IB n \[aq]\c
+\[rq].
 .
 Any definitions persist only until the end of the page.
 .
@@ -905,9 +906,7 @@ can extend over multiple lines.
 .
 For example,
 .
-.
 .RS
-.IP
 .EX
 \&.nr x 1i
 \&.de y
@@ -917,9 +916,8 @@ For example,
 \&..
 \&\[rs]Yy
 .EE
+.RE
 .
-.
-.LP
 is another way to draw a horizontal line one inch long.
 .
 The single backslash before
@@ -935,20 +933,23 @@ basic units which are in turn converted to PostScript 
units with the
 procedure.
 .
 .
-.LP
-.B grops
-wraps user-specified PostScript code into a dictionary, nothing more.
+.P
+.I grops
+wraps user-specified PostScript code into a dictionary,
+nothing more.
 .
-In particular, it doesn't start and end the inserted code with
+In particular,
+it doesn't start and end the inserted code with
 .B save
 and
 .BR restore ,
 respectively.
 .
-This must be supplied by the user, if necessary.
-.
+This must be supplied by the user,
+if necessary.
 .RE
 .
+.
 .TP
 .BI "\[rs]X\[aq]ps: file\~" name \[aq]
 This is the same as the
@@ -1483,24 +1484,42 @@ these old font descriptions are also installed in the
 directory.
 .
 .
-.LP
+.P
 To use them,
 make sure that
 .I grops
-finds the fonts before the default system fonts (with the same names):
-Either add command-line option
-.B \-F
-to
+finds the fonts before the default system fonts
+(with the same names):
+either give
 .I grops
+the
+.B \-F
+command-line option,
 .
-.IP
-.B groff \-Tps \-P\-F \-P@OLDFONTDIR@ .\|.\|.
+.RS
+.EX
+$ \c
+.B groff \-Tps \-P\-F \-P@OLDFONTDIR@ \c
+\&.\|.\|.
+.EE
+.RE
 .
-.LP
-or add the directory to groff's font path environment variable
+or add the directory to
+.IR groff 's
+font and device description search path environment variable,
 .
-.IP
-.B GROFF_FONT_PATH=@OLDFONTDIR@
+.RS
+.EX
+$ \c
+.B GROFF_FONT_PATH=\:@OLDFONTDIR@ \[rs]
+.RS
+.B groff \-Tps \c
+\&.\|.\|.
+.RE
+.EE
+.RE
+.
+when the command runs.
 .
 .
 .\" ====================================================================
diff --git a/tmac/groff_me.7.man b/tmac/groff_me.7.man
index ee46462f..bf33983a 100644
--- a/tmac/groff_me.7.man
+++ b/tmac/groff_me.7.man
@@ -454,11 +454,23 @@ wc        term for \(lqchapter\(rq used by \fB.$c*
 .SH Files
 .\" ====================================================================
 .
-.I @MACRODIR@/me.tmac
-(a wrapper for
-.IR e.tmac )
-.br
+.TP
 .I @MACRODIR@/e.tmac
+implements the package.
+.
+.
+.TP
+.I @MACRODIR@/refer\-me.tmac
+implements
+.MR @g@refer @MAN1EXT@
+support for
+.IR me .
+.
+.
+.TP
+.I @MACRODIR@/me.tmac
+is a wrapper enabling the package to be loaded with
+.RB \[lq] "groff \-m me" \[rq].
 .
 .
 .\" ====================================================================
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 4cbb74fa..2db807c6 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -2563,14 +2563,21 @@ Names containing only uppercase letters and digits.
 .
 .TP
 .I \%@MACRODIR@/\:@TMAC_S_PREFIX@s\:.tmac
-.I groff
-implementation of manuscript macros.
+implements the package.
+.
+.
+.TP
+.I @MACRODIR@/refer\-ms.tmac
+implements
+.MR @g@refer @MAN1EXT@
+support for
+.IR ms .
 .
 .
 .TP
 .I \%@MACRODIR@/\:ms\:.tmac
-Wrapper to load
-.IR s.tmac .
+is a wrapper enabling the package to be loaded with
+.RB \[lq] "groff \-m ms" \[rq].
 .
 .
 .
diff --git a/tmac/groff_www.7.man b/tmac/groff_www.7.man
index 94d8b44e..99204c19 100644
--- a/tmac/groff_www.7.man
+++ b/tmac/groff_www.7.man
@@ -682,9 +682,17 @@ for details of how to switch this off or alter the 
position).
 .SH "Limitations of \f[I]grohtml\f[]"
 .\" ====================================================================
 .
-.LP
-.B tbl
-information is currently rendered as a PNG image.
+.MR @g@tbl @MAN1EXT@
+tables are rendered as PNG images.
+.
+Paul DuBois's approach with
+.MR tblcvt 1 ,
+part of the
+.UR http://\:www\:.snake\:.net/\:software/\:troffcvt/
+.I troffcvt
+distribution
+.UE ,
+should be explored.
 .
 .
 .\" ====================================================================