[groff] 08/15: grodvi(1): Fix style problems.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 930216c1b6d706368422a750e40134f8c1e34b46
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Oct 19 02:43:28 2020 +1100

    grodvi(1): Fix style problems.
    
    * Set program names in italics.
    * Use groff-style string escapes.
    * Quote multi-word in-line code examples so that they are clear even if
      the rendering device doesn't support bold.
    * Break input lines after commas and semicolons.
    * Use two empty requests where inter-paragraph space is expected.
    * Set macro names with a leading dot.
    * Set the abbreviation TFM (Tex Font Metrics) in full capitals.  It is
      the file extension that is normally lowercase.
    * Recast to avoid implication that the \N escape is a groffism.
    * Set multi-word parentheticals on their own input line(s).
    * Set the "hcode" request in bold and with a leading dot.
    * Set the abbreviation DVI in full capitals.
    * Suppress hyphenation of configurably-prefixed command name in-line
      code example and man page cross-references.
    * Suppress hyphenation of "tfm·todit" in man page cross-reference.
    * Add hyphenation points before dots in file names.
---
 src/devices/grodvi/grodvi.1.man | 202 ++++++++++++++++++++++++++--------------
 1 file changed, 130 insertions(+), 72 deletions(-)

diff --git a/src/devices/grodvi/grodvi.1.man b/src/devices/grodvi/grodvi.1.man
index 073dd34..387e78b 100644
--- a/src/devices/grodvi/grodvi.1.man
+++ b/src/devices/grodvi/grodvi.1.man
@@ -73,39 +73,48 @@ grodvi \- convert groff output to TeX DVI format
 .SH Description
 .\" ====================================================================
 .
-.B grodvi
+.I grodvi
 is a driver for
-.B groff
-that produces \*(tx DVI format.
+.I groff
+that produces \*[tx] DVI format.
 .
-Normally it should be run by
-.BR "groff \-Tdvi" .
+Normally it should be run via
+.RB \[lq] "groff \-Tdvi" \[rq].
 .
 This will run
-.BR "@g@troff \-Tdvi" ;
-it will also input the macros in
-.IR \%@MACRODIR@/\:dvi.tmac .
+.BR \[lq] "\%@g@troff \-Tdvi" \[rq],
+read the macros in
+.IR \%@MACRODIR@/\:dvi\:.tmac ,
+and pipe the output to
+.IR grodvi .
+.
 .
 .LP
 The DVI file generated by
-.B grodvi
+.I grodvi
 can be printed by any correctly-written DVI driver.
 .
-The troff drawing primitives are implemented
-using the tpic version\~2 specials.
+.I troff
+drawing primitives are implemented using
+.I tpic
+version\~2 specials.
 .
-If the driver does not support these, the
+If the driver does not support these,
+the
 .B \[rs]D
 commands will not produce any output.
 .
+.
 .LP
 There is an additional drawing command available:
 .
+.
 .TP
 .BI \[rs]D\[aq]R\~ "dh dv" \[aq]
-Draw a rule (solid black rectangle), with one corner
-at the current position, and the diagonally opposite corner
-at the current position
+Draw a rule
+(solid black rectangle),
+with one corner at the current position,
+and the diagonally opposite corner at the current position
 .RI +( dh , dv ).
 .
 Afterwards the current position will be at the opposite corner.
@@ -115,58 +124,72 @@ driver that does not support the tpic specials unlike the 
other
 .B \[rs]D
 commands.
 .
+.
 .LP
-The groff command
+The
+.I groff
+command
 .BI \[rs]X\[aq] anything \[aq]
 is translated into the same command in the DVI file as would be
 produced by
 .BI \%\[rs]special{ anything }
-in \*(tx;
+in \*[tx];
 .I anything
 may not contain a newline.
 .
+.
 .LP
 For inclusion of EPS image files,
 .B \-Tdvi
 loads
 .I pspic.tmac
-automatically, providing the
-.B PSPIC
+automatically,
+providing the
+.B .PSPIC
 macro.
 .
-Please check
-.BR groff_tmac (@MAN5EXT@)
+See
+.IR groff_tmac (@MAN5EXT@)
 for a detailed description.
 .
+.
 .LP
 Font files for
-.B grodvi
-can be created from tfm files using
-.BR tfmtodit (@MAN1EXT@).
+.I grodvi
+can be created from TFM
+(\*[tx] font metrics)
+files using
+.IR tfmtodit (@MAN1EXT@).
 .
 The font description file should contain the following
 additional commands:
 .
+.
 .TP
 .BI internalname\~ name
-The name of the tfm file (without the
+The name of the TFM file
+(without the
 .I .tfm
 extension) is
 .IR name .
 .
+.
 .TP
 .BI checksum\~ n
-The checksum in the tfm file is
+The checksum in the TFM file is
 .IR n .
 .
+.
 .TP
 .BI designsize\~ n
-The designsize in the tfm file is
+The designsize in the TFM file is
 .IR n .
 .
+.
 .LP
 These are automatically generated by
-.B tfmtodit.
+.I tfmtodit.
+.
 .
 .LP
 The default color for
@@ -175,33 +198,43 @@ and
 .B \[rs]M
 is black.
 .
-Currently, the drawing color for
+Currently,
+the drawing color for
 .B \[rs]D
-commands is always black, and fill color values are translated to gray.
+commands is always black,
+and fill color values are translated to gray.
+.
 .
 .LP
 In
-.B troff
+.IR groff ,
+as in AT&T
+.IR troff , \" AT&T
 the
 .B \[rs]N
 escape sequence can be used to access characters by their position
-in the corresponding tfm file;
-all characters in the tfm file can be accessed this way.
+in the corresponding TFM file;
+all characters in the TFM file can be accessed this way.
+.
 .
 .LP
-By design, the DVI format doesn't care about physical dimensions of the
-output medium.
+By design,
+the DVI format doesn't care about physical dimensions of the output
+medium.
 .
 Instead,
-.B grodvi
+.I grodvi
 emits the equivalent to \*[tx]'s
 .BI \%\[rs]special{\:\%papersize= width , length }
 on the first page;
-.B dvips
-(and possibly other DVI drivers) then sets the page size accordingly.
+.I dvips
+(and possibly other DVI drivers)
+then sets the page size accordingly.
 .
-If either the page width or length is not positive, no papersize special
-is output.
+If either the page width or length is not positive,
+no
+.B papersize
+special is output.
 .
 .
 .\" ====================================================================
@@ -226,19 +259,23 @@ Horizontal and vertical lines will be implemented by 
rules.
 .
 Other drawing commands will be ignored.
 .
+.
 .TP
 .BI \-F dir
 Prepend directory
 .RI dir /dev name
 to the search path for font and device description files;
 .I name
-is the name of the device, usually
+is the name of the device,
+usually
 .BR dvi .
 .
+.
 .TP
 .B \-l
 Specify landscape orientation.
 .
+.
 .TP
 .BI \-p papersize
 Specify paper dimensions.
@@ -250,20 +287,23 @@ and
 .B paperwidth
 commands in the
 .I DESC
-file; it accepts the same arguments as the
+file;
+it accepts the same arguments as the
 .B papersize
-command (see
-.BR groff_font (@MAN5EXT@)
+command
+(see
+.IR groff_font (@MAN5EXT@)
 for details).
 .
+.
 .TP
 .BI \-w n
 Set the default line thickness to
 .I n
 thousandths of an em.
 .
-If this option isn't specified, the line thickness defaults to
-0.04\~em.
+If this option isn't specified,
+the line thickness defaults to 0.04\~em.
 .
 .
 .\" ====================================================================
@@ -284,6 +324,7 @@ and
 .B H
 having members in each of these styles:
 .
+.
 .RS
 .TP
 .B TR
@@ -334,9 +375,11 @@ CM Slanted Sans Serif Bold Extended (cmssbxo10)
 .FT
 .RE
 .
+.
 .LP
 There are also the following fonts which are not members of a family:
 .
+.
 .RS
 .TP
 .B CW
@@ -351,6 +394,7 @@ CM Italic Typewriter Text (cmitt10)
 .FT
 .RE
 .
+.
 .LP
 Special fonts are
 .B MI
@@ -360,9 +404,11 @@ Special fonts are
 .B EX
 (cmex10),
 .B SC
-(cmtex10, only for
+(cmtex10,
+only for
 .BR CW ),
-and, perhaps surprisingly,
+and,
+perhaps surprisingly,
 .BR TR ,
 .BR TI ,
 and
@@ -374,6 +420,7 @@ For italic fonts,
 is used instead of
 .BR CW .
 .
+.
 .LP
 Finally,
 the symbol fonts of the American Mathematical Society are available as
@@ -385,6 +432,7 @@ special fonts
 .
 These two fonts are not mounted by default.
 .
+.
 .LP
 Using the option
 .B \-mec
@@ -393,12 +441,17 @@ Using the option
 provides the EC and TC fonts.
 .
 The design of the EC family is very similar to that of the CM fonts;
-additionally, they give a much better coverage of groff symbols.
+additionally,
+they give a much better coverage of
+.I groff
+symbols.
 .
 Note that
 .I ec.tmac
-must be called before any language-specific files; it doesn't take
-care of hcode values.
+must be called before any language-specific files;
+it doesn't take care of
+.B .hcode
+values.
 .
 .
 .\" ====================================================================
@@ -412,9 +465,9 @@ A list of directories in which to search for the
 directory in addition to the default ones.
 .
 See
-.BR @g@troff (@MAN1EXT@)
+.IR \%@g@troff (@MAN1EXT@)
 and
-.BR \%groff_font (@MAN5EXT@)
+.IR \%groff_font (@MAN5EXT@)
 for more details.
 .
 .
@@ -423,21 +476,24 @@ for more details.
 .\" ====================================================================
 .
 .TP
-.I \%@FONTDIR@/devdvi/DESC
+.I \%@FONTDIR@/\:\%devdvi/\:DESC
 Device description file.
 .
+.
 .TP
-.IR \%@FONTDIR@/devdvi/ F
+.IR \%@FONTDIR@/\:\%devdvi/ F
 Font description file for font
 .IR F .
 .
+.
 .TP
-.I \%@MACRODIR@/dvi.tmac
+.I \%@MACRODIR@/\:dvi\:.tmac
 Macros for use with
-.BR grodvi .
+.IR grodvi .
+.
 .
 .TP
-.I \%@MACRODIR@/ec.tmac
+.I \%@MACRODIR@/\:ec\:.tmac
 Macros to switch to EC fonts.
 .
 .
@@ -445,15 +501,17 @@ Macros to switch to EC fonts.
 .SH Bugs
 .\" ====================================================================
 .
-Dvi files produced by
-.B grodvi
-use a different resolution (57816 units per inch) from those produced by
-\*(tx.
+DVI files produced by
+.I grodvi
+use a different resolution
+(57816 units per inch)
+from those produced by \*[tx].
 .
-Incorrectly written drivers which assume the resolution used by \*(tx,
+Incorrectly written drivers which assume the resolution used by \*[tx],
 rather than using the resolution specified in the DVI file will not
 work with
-.BR grodvi .
+.IR grodvi .
+.
 .
 .LP
 When using the
@@ -461,7 +519,7 @@ When using the
 option with boxed tables,
 vertical and horizontal lines can sometimes protrude by one pixel.
 .
-This is a consequence of the way \*(tx requires that the heights
+This is a consequence of the way \*[tx] requires that the heights
 and widths of rules be rounded.
 .
 .
@@ -469,13 +527,13 @@ and widths of rules be rounded.
 .SH "See Also"
 .\" ====================================================================
 .
-.BR tfmtodit (@MAN1EXT@),
-.BR groff (@MAN1EXT@),
-.BR @g@troff (@MAN1EXT@),
-.BR groff_out (@MAN5EXT@),
-.BR groff_font (@MAN5EXT@),
-.BR groff_char (@MAN7EXT@),
-.BR groff_tmac (@MAN5EXT@)
+.IR \%tfmtodit (@MAN1EXT@),
+.IR groff (@MAN1EXT@),
+.IR \%@g@troff (@MAN1EXT@),
+.IR groff_out (@MAN5EXT@),
+.IR groff_font (@MAN5EXT@),
+.IR groff_char (@MAN7EXT@),
+.IR groff_tmac (@MAN5EXT@)
 .
 .
 .\" Restore compatibility mode (for, e.g., Solaris 10/11).