[groff] 15/16: [man pages]: Fix content/style/markup nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 665cb7f881f9bf56624416610faac936ebaad41d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Nov 6 15:04:00 2021 +1100

    [man pages]: Fix content/style/markup nits.
    
    Revise afmtodit(1) and grops(1).
    
    Content:
    * Name the correct file when describing its format.
    
    Style:
    * Say "font _description_ file" more consistently.
    * Say "(groff) basic units" instead of "groff units".
    * Set command names in italics, not bold or roman.
    * Set inline code examples in bold, and double-quote them where obvious
      computer glyphs (like the backslash) don't cue the reader for a
      context switch.
    * Set "x" and "y" in italics when used as algebraic objects.
    * Recast to stop chaining multiple subordinate clauses with semicolons.
    * Perform several Kemper notectomies.
    * Tighten wording.
    
    Markup:
    * Use \~ escape instead of \SP.
    * Use hyphens in metasyntactic variable names instead of underscores.
    * Break (some) input lines after commas and around multi-word
      parentheticals.
---
 src/devices/grops/grops.1.man     | 160 ++++++++++++++++++++++++--------------
 src/utils/afmtodit/afmtodit.1.man |   2 +-
 2 files changed, 103 insertions(+), 59 deletions(-)

diff --git a/src/devices/grops/grops.1.man b/src/devices/grops/grops.1.man
index b3added..32581ff 100644
--- a/src/devices/grops/grops.1.man
+++ b/src/devices/grops/grops.1.man
@@ -366,22 +366,26 @@ for more information.
 .LP
 Each font description file must contain a command
 .IP
-.BI internalname\  psname
+.BI internalname\~ psname
 .LP
 which says that the PostScript name of the font is
 .IR psname .
 .
 It may also contain a command
 .IP
-.BI encoding\  enc_file
+.BI encoding\~ enc-file
 .LP
 which says that
 the PostScript font should be reencoded using the encoding described in
-.IR enc_file ;
+.IR enc-file ;
 this file should consist of a sequence of lines of the form:
+.
+.
 .IP
 .I
 pschar code
+.
+.
 .LP
 where
 .I pschar
@@ -395,39 +399,47 @@ Lines starting with
 .B #
 and blank lines are ignored.
 .
-The code for each character given in the font file must correspond
-to the code for the character in encoding file,
+The code for each character given in the font description file must
+correspond to the code for the character in encoding file,
 or to the code in the default encoding for the font if the PostScript
 font is not to be reencoded.
 .
 This code can be used with the
 .B \[rs]N
 escape sequence in
-.B troff
+.I \%@g@troff
 to select the character,
-even if the character does not have a groff name.
+even if the character does not have a
+.I groff
+glyph name.
 .
-Every character in the font file must exist in the PostScript font, and
-the widths given in the font file must match the widths used
-in the PostScript font.
+Every character in the font descripiton file must exist in the
+PostScript font,
+and the widths given in the font descripiton file must match the widths
+used in the PostScript font.
 .
-.B grops
-assumes that a character with a groff name of
+.I grops
+assumes that a character with a
+.I groff
+name of
 .B space
-is blank (makes no marks on the page);
+is blank
+(makes no marks on the page);
 it can make use of such a character to generate more efficient and
 compact PostScript output.
 .
 .
 .LP
-Note that
-.B grops
-is able to display all glyphs in a PostScript font, not only 256.
-.I enc_file
-(or the default encoding if no encoding file specified) just defines the
-order of glyphs for the first 256 characters; all other glyphs are
-accessed with additional encoding vectors which
-.B grops
+.I grops
+is able to display all glyphs in a PostScript font;
+it is not limited to 256 of them.
+.
+.I enc-file
+(or the default encoding if no encoding file specified)
+just defines the
+order of glyphs for the first 256 characters;
+all other glyphs are accessed with additional encoding vectors which
+.I grops
 produces on the fly.
 .
 .
@@ -450,7 +462,7 @@ this should consist of lines of the form
 .
 .IP
 .I
-font filename
+font file
 .
 .
 .LP
@@ -458,20 +470,23 @@ where
 .I font
 is the PostScript name of the font,
 and
-.I filename
+.I file
 is the name of the file containing the font;
 lines beginning with
 .B #
 and blank lines are ignored;
 fields may be separated by tabs or spaces;
-.I filename
-is searched for using the same mechanism that is used
-for groff font metric files.
+.I file
+is sought for using the same mechanism as that for
+.I groff
+font description files.
 .
 The
 .I download
-file itself is also searched for using this mechanism;
-currently, only the first found file in the font path is used.
+file itself is also sought using this mechanism;
+currently,
+only the matching file found in the device and font description search
+path is used.
 .
 .
 .LP
@@ -810,7 +825,6 @@ is used, for \[oq]cmy\[cq] and \[oq]cmyk\[cq]
 and for \[oq]gray\[cq]
 .BR setgray .
 .
-Note that
 .B setcmykcolor
 is a PostScript LanguageLevel\~2 command and thus not available on some
 older printers.
@@ -837,12 +851,18 @@ command before executing
 .IR code .
 .
 The origin is at the top left corner of the page,
-and y\~coordinates increase down the page.
+.IR x \~coordinates
+increase to the right,
+and
+.IR y \~coordinates
+down the page.
 .
 A procedure\~\c
 .B u
-is defined that converts groff units to the coordinate system in
-effect (provided the user doesn't change the scale).
+is defined that converts
+.I groff
+basic units to the coordinate system in effect
+(provided the user doesn't change the scale).
 .
 For example,
 .
@@ -900,10 +920,15 @@ For example,
 .LP
 is another way to draw a horizontal line one inch long.
 .
-Note the single backslash before \[oq]nx\[cq] \[en] the only reason to
-use a register while defining the macro \[oq]y\[cq] is to
-convert a user-specified dimension \[oq]1i\[cq] to internal groff
-units which are in turn converted to PS units with the
+The single backslash before
+.RB \[lq] nx \[rq]\[em]the
+only reason to use a register while defining the macro
+.RB \[lq] y \[rq]\[em]is
+to convert a user-specified dimension
+.RB \[lq] 1i \[rq]
+to
+.I groff
+basic units which are in turn converted to PostScript units with the
 .B u
 procedure.
 .
@@ -988,21 +1013,31 @@ The arguments
 and
 .I ury
 give the bounding box of the graphic in the default PostScript
-coordinate system; they should all be integers;
+coordinate system.
+.
+They should all be integers:
 .I llx
 and
 .I lly
-are the x and y\~coordinates of the lower left
-corner of the graphic;
+are the
+.I x
+and
+.IR y \~coordinates
+of the lower left corner of the graphic;
 .I urx
 and
 .I ury
-are the x and y\~coordinates of the upper right corner of the graphic;
+are the
+.I x
+and
+.IR y \~coordinates
+of the upper right corner of the graphic;
 .I width
 and
 .I height
-are integers that give the desired width and height in groff
-units of the graphic.
+are integers that give the desired width and height in
+.I groff
+basic units of the graphic.
 .
 .IP
 The graphic is scaled so that it has this width and height
@@ -1012,7 +1047,11 @@ located at the position associated with
 command.
 .
 If the height argument is omitted it is scaled uniformly in the
-x and y\~directions so that it has the specified width.
+.I x
+and
+.IR y \~axes
+so that it has the specified width.
+.
 .
 .IP
 The contents of the
@@ -1382,16 +1421,21 @@ and
 .BR TBI .
 .
 .IP \(bu
-Install both the groff font description files and the fonts in a
+Install both the
+.I groff
+font description files and the fonts in a
 .I devps
-subdirectory of the font path which groff finds.
+subdirectory of the font path which
+.I groff
+finds.
 .
 See section \[lq]Environment\[rq] in
 .MR troff @MAN1EXT@
 for the actual value of the font path.
 .
-Note that groff doesn't use the AFM files (but it is a good idea
-to store them anyway).
+.I groff
+doesn't use the AFM files,
+but it is a good idea to store them anyway.
 .
 .IP \(bu
 Register all fonts which must be downloaded to the printer in the
@@ -1425,27 +1469,27 @@ thus the following line should be added to
 .SH "Old fonts"
 .\" ====================================================================
 .
-groff versions 1.19.2 and earlier contain a slightly different set of
-the 35 Adobe core fonts; the difference is mainly the lack of the
-\[oq]Euro\[cq] glyph and a reduced set of kerning pairs.
-.
-For backwards compatibility, these old fonts are installed also in the
+.I groff
+versions 1.19.2 and earlier contained descriptions of a slightly
+different set of the 35 Adobe core fonts;
+the differences are mainly the lack of a Euro glyph and a reduced set of
+kerning pairs.
 .
-.IP
+For backwards compatibility,
+these old font descriptions are also installed in the
 .I @OLDFONTDIR@/devps
-.
-.LP
 directory.
 .
 .
 .LP
-To use them, make sure that
-.B grops
+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
-.B grops
+.I grops
 .
 .IP
 .B groff \-Tps \-P\-F \-P@OLDFONTDIR@ .\|.\|.
diff --git a/src/utils/afmtodit/afmtodit.1.man 
b/src/utils/afmtodit/afmtodit.1.man
index aecf9e4..a183955 100644
--- a/src/utils/afmtodit/afmtodit.1.man
+++ b/src/utils/afmtodit/afmtodit.1.man
@@ -91,7 +91,7 @@ option).
 .
 .
 .LP
-.I afm-file
+.I map-file
 should contain a sequence of lines of the form
 .
 .RS