[groff] 30/31: [man page]: Parallelize output driver intros.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 52f661f080f99c8b6e2985bb4a5e874c97de32c1
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Feb 1 02:06:26 2022 +1100

    [man page]: Parallelize output driver intros.
    
    ...except for grohtml and xditview, which are too weird.
    
    * Consistently present the default output device.
    * Consistently mention groff's -P option.
    * Consistently mention use of standard input and output streams.
    
    Also fix some style and markup nits.
    * Migrate to 'P' paragraphing macro.
    * Cancel hyphenation of adverbially enhanced attributive phrase.
    * Set man page topic names (when not cross referenced) in italics.
    * Fix missing space before trailing punctuation argument in an MR call.
    
    This also disposes of an `if` request in man page sources, which my
    internal Ingo Schwarze homunculus celebrates.
---
 src/devices/grodvi/grodvi.1.man | 46 +++++++++++++++++-------
 src/devices/grolbp/grolbp.1.man | 50 ++++++++++++++++++++------
 src/devices/grolj4/grolj4.1.man | 47 +++++++++++++++++++-----
 src/devices/gropdf/gropdf.1.man | 64 ++++++++++++++++-----------------
 src/devices/grops/grops.1.man   | 79 +++++++++++++++++++++--------------------
 src/devices/grotty/grotty.1.man | 19 +++++++---
 6 files changed, 200 insertions(+), 105 deletions(-)

diff --git a/src/devices/grodvi/grodvi.1.man b/src/devices/grodvi/grodvi.1.man
index f4800f60..3065105f 100644
--- a/src/devices/grodvi/grodvi.1.man
+++ b/src/devices/grodvi/grodvi.1.man
@@ -75,26 +75,46 @@ grodvi \- groff output driver for TeX DVI format
 .SH Description
 .\" ====================================================================
 .
+The GNU
+.I roff
+DVI output driver translates the output of
+.MR @g@troff @MAN1EXT@
+into \*[tx] DVI format.
+.
+Normally,
 .I grodvi
-is a driver for
-.I groff
-that produces \*[tx] DVI format.
+is invoked by
+.MR groff @MAN1EXT@
+when the latter is given the
+.RB \[lq] \-T\~dvi \[rq]
+option.
+.
+(In this installation,
+.B @DEVICE@
+is the default output device.)
+.
+Use
+.IR groff 's
+.B \-P
+option to pass any options shown above to
+.IR grodvi .
 .
-Normally it should be run via
-.RB \[lq] "groff \-Tdvi" \[rq].
+If no
+.I file
+arguments are given,
+or if
+.I file
+is \[lq]\-\[rq],
+.I grodvi
+reads the standard input stream.
 .
-This will run
-.RB \[lq] "\%@g@troff \-Tdvi" \[rq],
-read the macros in
-.IR \%@MACRODIR@/\:dvi\:.tmac ,
-and pipe the output to
-.IR grodvi .
+Output is written to the standard output stream.
 .
 .
-.LP
+.P
 The DVI file generated by
 .I grodvi
-can be printed by any correctly-written DVI driver.
+can be printed by any correctly written DVI driver.
 .
 .I troff \" generic
 drawing primitives are implemented using
diff --git a/src/devices/grolbp/grolbp.1.man b/src/devices/grolbp/grolbp.1.man
index 04771433..8d976739 100644
--- a/src/devices/grolbp/grolbp.1.man
+++ b/src/devices/grolbp/grolbp.1.man
@@ -91,17 +91,47 @@ grolbp \- groff output driver for Canon CaPSL printers
 .SH Description
 .\" ====================================================================
 .
-.B grolbp
-is a driver for
-.B groff
-that produces output in CaPSL and VDM format suitable for Canon LBP-4
-and LBP-8 printers.
-.
-.
-.LP
+The GNU
+.I roff
+LBP output driver translates the output of
+.MR @g@troff @MAN1EXT@
+into a CaPSL and VDM format suitable for Canon LBP-4 and LBP-8 printers.
+.
+Normally,
+.I grolbp
+is invoked by
+.MR groff @MAN1EXT@
+when the latter is given the
+.RB \[lq] \-T\~lbp \[rq]
+option.
+.
+(In this installation,
+.B @DEVICE@
+is the default output device.)
+.
+Use
+.IR groff 's
+.B \-P
+option to pass any options shown above to
+.IR grolbp .
+.
+If no
+.I file
+arguments are given,
+or if
+.I file
+is \[lq]\-\[rq],
+.I grolbp
+reads the standard input stream.
+.
+Output is written to the standard output stream.
+.
+.
+.P
 For compatibility with
-.MR grolj4 @MAN1EXT@
-there is an additional drawing command available:
+.MR grolj4 @MAN1EXT@ ,
+an additional drawing command is available.
+.
 .
 .TP
 .BI \[rs]D\[aq]R\~ "dh dv" \[aq]
diff --git a/src/devices/grolj4/grolj4.1.man b/src/devices/grolj4/grolj4.1.man
index 01e110a2..22e94ed4 100644
--- a/src/devices/grolj4/grolj4.1.man
+++ b/src/devices/grolj4/grolj4.1.man
@@ -67,15 +67,46 @@ grolj4 \- groff output driver for HP LaserJet 4 family 
printers
 .SH Description
 .\" ====================================================================
 .
-.B grolj4
-is a driver for
-.B groff
-that produces output in PCL5 format suitable for an HP LaserJet 4
-printer.
-.
+The GNU
+.I roff
+LJ4 output driver translates the output of
+.MR @g@troff @MAN1EXT@
+into a PCL5 format suitable for an HP LaserJet 4 printer.
+.
+Normally,
+.I grolj4
+is invoked by
+.MR groff @MAN1EXT@
+when the latter is given the
+.RB \[lq] \-T\~lj4 \[rq]
+option.
+.
+(In this installation,
+.B @DEVICE@
+is the default output device.)
+.
+Use
+.IR groff 's
+.B \-P
+option to pass any options shown above to
+.IR grolj4 .
+.
+If no
+.I file
+arguments are given,
+or if
+.I file
+is \[lq]\-\[rq],
+.I grolj4
+reads the standard input stream.
+.
+Output is written to the standard output stream.
+.
+.
+.P
+An additional drawing command is available beyond those documented in
+.MR groff @MAN7EXT@ .
 .
-.LP
-There is an additional drawing command available:
 .
 .TP
 .BI \[rs]D\[aq]R\~ "dh dv" \[aq]
diff --git a/src/devices/gropdf/gropdf.1.man b/src/devices/gropdf/gropdf.1.man
index c9c759a4..459236e7 100644
--- a/src/devices/gropdf/gropdf.1.man
+++ b/src/devices/gropdf/gropdf.1.man
@@ -73,46 +73,46 @@ gropdf \- groff output driver for Portable Document Format
 .SH Description
 .\" ====================================================================
 .
-.B gropdf
-translates the output of GNU
-.B troff
-to PDF.
+The GNU
+.I roff
+PDF output driver translates the output of
+.MR @g@troff @MAN1EXT@
+into Portable Document Format.
 .
-Normally
-.B gropdf
-should be invoked by using the groff command
-with a
-.B \-Tpdf
+Normally,
+.I gropdf
+is invoked by
+.MR groff @MAN1EXT@
+when the latter is given the
+.RB \[lq] \-T\~pdf \[rq]
 option.
 .
-If no files are given,
-.B gropdf
-reads the standard input.
+(In this installation,
+.B @DEVICE@
+is the default output device.)
 .
-A filename of
-.B \-
-also causes
-.B gropdf
-to read the standard input.
+Use
+.IR groff 's
+.B \-P
+option to pass any options shown above to
+.IR gropdf .
 .
-PDF output is written to the standard output.
+If no
+.I file
+arguments are given,
+or if
+.I file
+is \[lq]\-\[rq],
+.I gropdf
+reads the standard input stream.
 .
-When
-.B gropdf
-is run by
-.B groff
-options can be passed to
-.B gropdf
-using
-.BR groff 's
-.B \-P
-option.
+Output is written to the standard output stream.
 .
 .
-.LP
-See section \[lq]Font Installation\[rq] below for a guide how to install
+.P
+See section \[lq]Font Installation\[rq] below for a guide to installing
 fonts for
-.BR gropdf .
+.IR gropdf .
 .
 .
 .\" ====================================================================
@@ -1270,7 +1270,7 @@ An
 .I sboxes
 macro file is also available;
 see
-.MR groff_tmac @MAN5EXT@.
+.MR groff_tmac @MAN5EXT@ .
 .RE
 .
 .
diff --git a/src/devices/grops/grops.1.man b/src/devices/grops/grops.1.man
index 85e8a0a9..28059626 100644
--- a/src/devices/grops/grops.1.man
+++ b/src/devices/grops/grops.1.man
@@ -80,56 +80,59 @@ grops \- groff output driver for PostScript
 .SH Description
 .\" ====================================================================
 .
-.B grops
-translates the output of GNU
-.B troff
-to PostScript.
+The GNU
+.I roff
+PostScript output driver translates the output of
+.MR @g@troff @MAN1EXT@
+into PostScript.
 .
-Normally
-.B grops
-should be invoked by using the groff command with a
-.B \-Tps
+Normally,
+.I grops
+is invoked by
+.MR groff @MAN1EXT@
+when the latter is given the
+.RB \[lq] \-T\~ps \[rq]
 option.
 .
-.if '@DEVICE@'ps' (Actually, this is the default for groff.)
+(In this installation,
+.B @DEVICE@
+is the default output device.)
 .
-If no files are given,
-.B grops
-reads the standard input.
+Use
+.IR groff 's
+.B \-P
+option to pass any options shown above to
+.IR grops .
 .
-A filename of
-.B \-
-also causes
-.B grops
-to read the standard input.
+If no
+.I file
+arguments are given,
+or if
+.I file
+is \[lq]\-\[rq],
+.I grotty
+reads the standard input stream.
 .
-PostScript output is written to the standard output.
+Output is written to the standard output stream.
 .
-When
-.B grops
-is run by
-.B groff
-options can be passed to
-.B grops
-using
-.BR groff 's
-.B \-P
-option.
 .
+.P
+When called with multiple
+.I file
+arguments,
+.I grops
+doesn't produce a valid document structure
+(one conforming to the Document Structuring Convention).
 .
-.LP
-Note that
-.B grops
-doesn't produce a valid document structure (conforming to the
-Document Structuring Convention) if called with multiple file
-arguments.
+To print such concatenated output,
+it is necessary to deactivate DSC handling in the printing program or
+previewer.
 .
-To print such concatenated output it is necessary to deactivate DSC
-handling in the printing program or previewer.
 .
-See section \[lq]Font Installation\[rq] below for a guide how to install
+.P
+See section \[lq]Font Installation\[rq] below for a guide to installing
 fonts for
-.BR grops .
+.IR grops .
 .
 .
 .\" ====================================================================
diff --git a/src/devices/grotty/grotty.1.man b/src/devices/grotty/grotty.1.man
index c1e952ae..162144ee 100644
--- a/src/devices/grotty/grotty.1.man
+++ b/src/devices/grotty/grotty.1.man
@@ -82,17 +82,28 @@ Normally,
 is invoked by
 .MR groff @MAN1EXT@
 when the latter is given one of the
-.BR \-Tascii ,
+.RB \[lq] \-T\~ascii \[rq],
+.RB \[lq] \-T\~latin1 \[rq],
 .BR \-Tlatin1 ,
 or
-.B \-Tutf8
+.RB \[lq] \-T\~utf8 \[rq]
 options on systems using ISO character encoding standards,
 or with
-.B \-Tcp1047
+.RB \[lq] \-T\~cp1047 \[rq]
 or
-.B \-Tutf8
+.RB \[lq] \-T\~utf8 \[rq]
 on EBCDIC-based hosts.
 .
+(In this installation,
+.B @DEVICE@
+is the default output device.)
+.
+Use
+.IR groff 's
+.B \-P
+option to pass any options shown above to
+.IR grotty .
+.
 If no
 .I file
 arguments are given,