[groff] 09/21: grodvi(1): Organize and clarify.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 00aeacfe9846348e7b20692d620ad6c34d84fbdb
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Aug 21 07:20:11 2022 -0500

    grodvi(1): Organize and clarify.
    
    Impose more structure on output driver man pages, part 1.
    
    Fix content nits.
    * Discuss "interpretation" of DVI more, and "printing" less.
    * Migrate terminology: (troff) "commands" -> "escape sequences".
    * Apply terminology: (nothing) -> (troff) "escape sequences".
    * Apply terminology: "command" -> "device control" (escape sequence).
    * Migrate terminology: "drawing color" -> "stroke color".
    * Drop "Usage" section heading in favor of subsections "Typefaces",
      "Font description files", and "Drawing commands".
    * Align discussion of groff styles with grotty(1).
    * Explain "CM" abbreviation.
    * Clarify what's going on with "TR", "TI", and "CW" fonts being special
      for this output device.
    * Migrate terminology: macro files are "loaded", not "called".
    * Migrate terminology: "current position" -> "drawing position".  We
      have our own lexicon and it is not PostScript's.
    * Clarify what dvi.tmac does.
    
    Fix style nits.
    * Set "Name" section's summary-description terms in italics as needed.
    * Identify troff macro names without leading dot.
    * Recast sentence fragments to eliminate dangling colons.
    * Use active voice and imperative mood to instruct the user in the
      creation of font description files for groff.
    * Say "design size" in prose.
    * Discuss behavior of 'R' drawing command in present tense, not future.
    * Put a space between "-F' option and its argument when presenting it.
    * (Environment) Begin sentences with the paragraph tag, to economize and
      align with section "Files".
    * Use English thousands separator in large magnitude in prose.
    * Set off long restrictive adverbial phrase with commas on both sides.
    * Tighten wording.
    
    Fix markup nits.
    * Prevent hyphenation of font description file directive names.
    * Protect "troffrc" from hyphenation.
    * Migrate from macro `LP` to `P`.
    * Adjust dead-tree typography (pagination).
---
 src/devices/grodvi/grodvi.1.man | 204 ++++++++++++++++++++++------------------
 1 file changed, 111 insertions(+), 93 deletions(-)

diff --git a/src/devices/grodvi/grodvi.1.man b/src/devices/grodvi/grodvi.1.man
index 087ef3afe..49c50320d 100644
--- a/src/devices/grodvi/grodvi.1.man
+++ b/src/devices/grodvi/grodvi.1.man
@@ -1,13 +1,15 @@
 .TH grodvi @MAN1EXT@ "@MDATE@" "groff @VERSION@"
 .SH Name
-grodvi \- groff output driver for TeX DVI format
+grodvi \-
+.I groff
+output driver for TeX DVI format
 .
 .
 .\" ====================================================================
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 1989-2020 Free Software Foundation, Inc.
+.\" Copyright (C) 1989-2020, 2022 Free Software Foundation, Inc.
 .\"
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
@@ -114,7 +116,7 @@ Output is written to the standard output stream.
 .P
 The DVI file generated by
 .I grodvi
-can be printed by any correctly written DVI driver.
+can interpreted by any correctly written DVI driver.
 .
 .I troff \" generic
 drawing primitives are implemented using
@@ -122,55 +124,52 @@ drawing primitives are implemented using
 version\~2 specials.
 .
 If the driver does not support these,
-the
 .B \[rs]D
-commands will not produce any output.
+escape sequences will not produce any output.
 .
 .
-.LP
-For inclusion of EPS image files,
-.B \-Tdvi
-loads
-.I pspic.tmac
-automatically,
-providing the
-.B .PSPIC
+.P
+Encapsulated PostScript (EPS) files can be easily included;
+use the
+.B PSPIC
 macro.
 .
+.I pspic.tmac
+is loaded automatically by
+.IR dvi.tmac .
+.
 See
-.MR groff_tmac @MAN5EXT@
-for a detailed description.
+.MR groff_tmac @MAN5EXT@ .
 .
 .
-.LP
-The default color for
+.P
+The default color used by the
 .B \[rs]m
 and
 .B \[rs]M
-is black.
+escape sequences is black.
 .
 Currently,
-the drawing color for
+the stroke color for
 .B \[rs]D
-commands is always black,
-and fill color values are translated to gray.
+drawing escape sequences is black;
+fill color values are translated to gray.
 .
 .
-.LP
+.P
 In
 .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.
+escape sequence can be used to access any glyph in the current font by
+its position in the corresponding TFM file.
 .
 .
-.LP
+.P
 By design,
-the DVI format doesn't care about physical dimensions of the output
+the DVI format doesn't care about the physical dimensions of the output
 medium.
 .
 Instead,
@@ -179,45 +178,48 @@ emits the equivalent to \*[tx]'s
 .BI \%\[rs]special{\:\%papersize= width , length }
 on the first page;
 .I dvips
-(and possibly other DVI drivers)
+(or another DVI driver)
 then sets the page size accordingly.
 .
 If either the page width or length is not positive,
 no
-.B papersize
+.B \%papersize
 special is output.
 .
 .
-.LP
-The
-.I groff
-command
+.P
+A device control escape sequence
 .BI \[rs]X\[aq] anything \[aq]
-is translated into the same command in the DVI file as would be
-produced by
+is translated to the same DVI file instructions as would be produced by
 .BI \%\[rs]special{ anything }
 in \*[tx];
 .I anything
-may not contain a newline.
+cannot contain a newline.
 .
 .
 .\" ====================================================================
-.SH Usage
+.SS Typefaces
 .\" ====================================================================
 .
-There are styles called
-.BR R ,
-.BR I ,
-.BR B ,
+.I grodvi
+supports the standard four styles:
+.B R
+(roman),
+.B I
+.RI ( italic ),
+.B B
+.RB ( bold ),
 and
 .B BI
-mounted at font positions 1 to\~4.
+(\f[BI]bold-italic\f[]).
 .
-The fonts are grouped into families
+Fonts are grouped into families
 .B T
 and
 .B H
-having members in each of these styles:
+having members in each style.
+.
+\[lq]CM\[rq] abbreviates \[lq]Computer Modern\[rq].
 .
 .
 .RS
@@ -272,7 +274,7 @@ CM Slanted Sans Serif Bold Extended (cmssbxo10)
 .
 .
 .LP
-There are also the following fonts which are not members of a family:
+The following fonts are not members of a family.
 .
 .
 .RS
@@ -290,8 +292,8 @@ CM Italic Typewriter Text (cmitt10)
 .RE
 .
 .
-.LP
-Special fonts are
+.P
+Special fonts include
 .B MI
 (cmmi10),
 .B S
@@ -308,7 +310,10 @@ perhaps surprisingly,
 .BR TI ,
 and
 .BR CW ,
-due to the different font encodings of text fonts.
+.\" See font/devdvi/generate/Makefile for details.
+because \*[tx] places some glyphs in text fonts that
+.I troff \" generic
+generally does not.
 .
 For italic fonts,
 .B CWI
@@ -316,7 +321,7 @@ is used instead of
 .BR CW .
 .
 .
-.LP
+.P
 Finally,
 the symbol fonts of the American Mathematical Society are available as
 special fonts
@@ -325,18 +330,23 @@ special fonts
 .B SB
 (msbm10).
 .
-These two fonts are not mounted by default.
+They are are not mounted by default.
 .
 .
-.LP
-Using the option
+.br
+.ne 2v
+.P
+The
+.I @g@troff
+option
 .B \-mec
-(which loads the file
-.IR ec.tmac )
-selects the EC and TC fonts.
+loads the
+.I ec.tmac
+macro file,
+employing the EC and TC fonts instead of CM.
 .
-The EC fonts are designed similarly to the CM fonts;
-additionally,
+These are designed similarly to the Computer Modern fonts;
+further,
 they provide Euro
 .B \[rs][Eu]
 and per mille
@@ -344,22 +354,27 @@ and per mille
 glyphs.
 .
 .I ec.tmac
-must be called before any language-specific files;
-it doesn't take care of
-.B .hcode
-values.
+must be loaded before any language-specific macro files because it does
+not set up the codes necessary for automatic hyphenation.
 .
 .
-.LP
-Font files for
-.I grodvi
-can be created from TFM
+.\" ====================================================================
+.SS "Font description files"
+.\" ====================================================================
+.
+Use
+.MR tfmtodit @MAN1EXT@
+to create
+.I groff
+font description files from TFM
 (\*[tx] font metrics)
-files using
-.MR tfmtodit @MAN1EXT@ .
+files.
 .
-The font description file should contain the following
-additional commands:
+The font description file should contain the following additional
+directives,
+which
+.I tfmtodit
+generates automatically.
 .
 .
 .TP
@@ -379,33 +394,32 @@ The checksum in the TFM file is
 .
 .TP
 .BI designsize\~ n
-The designsize in the TFM file is
+The design size in the TFM file is
 .IR n .
 .
 .
-.LP
-These are automatically generated by
-.I tfmtodit.
-.
+.\" ====================================================================
+.SS "Drawing commands"
+.\" ====================================================================
 .
-.LP
-There is an additional drawing command available:
+.I grodvi
+supports an additional drawing command.
 .
 .
 .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
-.RI +( dh , dv ).
-.
-Afterwards the current position will be at the opposite corner.
+with one corner at the drawing position,
+and the diagonally opposite corner at the drawing position
+.RI +( dh , dv ),
+which becomes the new drawing position afterward.
 .
-This produces a rule in the DVI file and so can be printed even with a
-driver that does not support the
+This command produces a rule in the DVI file and so can be printed even
+with a driver that does not support
 .I tpic
-specials unlike the other
+specials,
+unlike the other
 .B \[rs]D
 commands.
 .
@@ -430,13 +444,13 @@ Do not use
 .I tpic
 specials to implement drawing commands.
 .
-Horizontal and vertical lines will be implemented by rules.
+Horizontal and vertical lines are implemented by rules.
 .
-Other drawing commands will be ignored.
+Other drawing commands are ignored.
 .
 .
 .TP
-.BI \-F dir
+.BI \-F\~ dir
 Prepend directory
 .RI dir /dev name
 to the search path for font and device description files;
@@ -488,7 +502,9 @@ The default thickness is
 .
 .TP
 .I GROFF_FONT_PATH
-A list of directories in which to seek the selected output device's
+lists directories in which to search for
+.IR devdvi ,
+.IR grodvi 's
 directory of device and font description files.
 .
 See
@@ -518,12 +534,14 @@ on device
 .
 .TP
 .I @MACRODIR@/\:dvi\:.tmac
-defines macros for use with the
+defines font mappings,
+special characters,
+and colors for use with the
 .B dvi
 output device.
 .
 It is automatically loaded by
-.I troffrc
+.I \%troffrc
 when the
 .B dvi
 output device is selected.
@@ -545,12 +563,12 @@ the EC and TC font families instead of CM
 DVI files produced by
 .I grodvi
 use a different resolution
-(57816 units per inch)
+(57,816 units per inch)
 from those produced 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
+rather than using the resolution specified in the DVI file,
+will not work with
 .IR grodvi .
 .
 .