[groff] 19/35: gropdf(1): Fix style and markup nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit cc5c33851c53dd086d85bc6a35b8cbf49dc98af3
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Jun 20 12:33:02 2022 -0500

    gropdf(1): Fix style and markup nits.
    
    * Revise section "Font installation"; try to clarify.
    * Use sentence case in internal section cross references.
    * Set "ghostscript" and "gropdf" in italics, not bold.
    * Break input lines after commas and semicolons.
    * Break input lines around multi-word parentheticals.
---
 src/devices/gropdf/gropdf.1.man | 195 ++++++++++++++++++++++++----------------
 1 file changed, 120 insertions(+), 75 deletions(-)

diff --git a/src/devices/gropdf/gropdf.1.man b/src/devices/gropdf/gropdf.1.man
index ff31d1a5..bf5b5d08 100644
--- a/src/devices/gropdf/gropdf.1.man
+++ b/src/devices/gropdf/gropdf.1.man
@@ -110,7 +110,7 @@ Output is written to the standard output stream.
 .
 .
 .P
-See section \[lq]Font Installation\[rq] below for a guide to installing
+See section \[lq]Font installation\[rq] below for a guide to installing
 fonts for
 .IR gropdf .
 .
@@ -136,7 +136,7 @@ Also produces an uncompressed PDF.
 .TP
 .B \-e
 Forces
-.B gropdf
+.I gropdf
 to embed
 .I all
 fonts (even the 14 base PDF fonts).
@@ -262,7 +262,7 @@ The device description file must contain a valid paper 
size; see
 .MR groff_font @MAN5EXT@
 for more information.
 .
-.B gropdf
+.I gropdf
 uses the same Type\~1 Adobe PostScript fonts as the
 .B grops
 device driver.
@@ -280,7 +280,7 @@ PDF.
 .
 .
 .LP
-.B gropdf
+.I gropdf
 supports the concept of foundries,
 that is different versions of basically the same font.
 .
@@ -324,7 +324,7 @@ in the PostScript font.
 .
 .LP
 Note that
-.B gropdf
+.I gropdf
 is currently only able to display the first 256 glyphs in any font.
 This restriction will be lifted in a later version.
 .
@@ -342,7 +342,7 @@ This restriction will be lifted in a later version.
 .
 .
 .LP
-.B gropdf
+.I gropdf
 can automatically include the downloadable fonts necessary
 to print the document.
 .
@@ -350,7 +350,7 @@ Fonts may be in PFA or PFB format.
 .LP
 .
 Any downloadable fonts which should, when required, be included by
-.B gropdf
+.I gropdf
 must be listed in the file
 .IR @FONTDIR@/\:\%devpdf/\:\%download ;
 this should consist of lines of the form
@@ -384,14 +384,16 @@ font metric 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 first file found in the font search path is read.
 .
-Foundry names are usually a single character (such as \[oq]U\[cq] for
-the URW Foundry) or blank for the default foundry.
+Foundry names are usually a single character
+(such as \[oq]U\[cq] for the URW foundry)
+or empty for the default foundry.
 .
 This default uses the same fonts as
-.B ghostscript
+.I ghostscript
 uses when it embeds fonts in a PDF file.
 .
 .
@@ -648,7 +650,7 @@ and
 is black.
 .
 .LP
-.B gropdf
+.I gropdf
 understands some of the X\~commands produced using the
 .B \[rs]X
 escape sequences supported by
@@ -724,7 +726,7 @@ so you should not need to use \[oq]\-m pdfmark\[cq] for 
using most of
 the PDF functionality.
 .
 .LP
-.B gropdf
+.I gropdf
 also supports a subset of the commands introduced in present.tmac.
 Specifically it supports:-
 .IP
@@ -778,7 +780,7 @@ slides with
 .BR mom .
 .LP
 If you use present.tmac with
-.B gropdf
+.I gropdf
 there is no need to run the program
 .MR presentps @MAN1EXT@
 since the output will already be a presentation pdf.
@@ -807,14 +809,14 @@ for details.
 .
 This means that you can alter the page size at will within the PDF file
 being created by
-.BR gropdf .
+.IR gropdf .
 .
 If you do want to change the paper size,
 it must be done before you start creating the page.
 .
 .LP
 In addition,
-.B gropdf
+.I gropdf
 supports its own suite of
 .B pdf:
 tags.
@@ -1282,7 +1284,7 @@ see
 .SS "Importing graphics"
 .\" ====================================================================
 .
-.B gropdf
+.I gropdf
 only supports importing other PDF files as graphics.
 .
 But that PDF file may contain any of the graphic formats supported by
@@ -1290,7 +1292,7 @@ the PDF standard (such as JPEG, PNG, GIF, etc.).
 .
 So any application which outputs PDF can be used as an embedded file
 in
-.BR gropdf .
+.IR gropdf .
 .
 The PDF file you wish to insert must be a single page and the drawing
 must just fit inside the media size of the PDF file.
@@ -1304,7 +1306,7 @@ or
 .
 .LP
 The PDF parser used in
-.B gropdf
+.I gropdf
 has not been rigorously tested with all possible applications which
 produce PDFs.
 .
@@ -1334,37 +1336,42 @@ will now load successfully.
 .SS "TrueType and other font formats"
 .\" ====================================================================
 .
-.B gropdf
-does not support any other fonts except Adobe Type 1 (PFA or PFB).
+.I gropdf
+does not yet support any font formats besides Adobe Type 1
+(PFA or PFB).
 .
 .
 .\" ====================================================================
 .SH "Font installation"
 .\" ====================================================================
 .
-This section gives a summary of the above explanations; it can serve
-as a step-by-step font installation guide for
-.BR gropdf .
+The following is a step-by-step font installation guide for
+.I gropdf.
 .
-.IP \(bu
+.
+.IP \[bu] 2n
 Convert your font to something
 .I groff
 understands.
 .
-This is either a PostScript Type\~1 font in either PFA or PFB,
+This is a PostScript Type\~1 font in PFA or PFB format,
 together with an AFM file.
 .
+.
 .IP
-The very first line in a PFA/PFB file contains this:
+The first line in a PFA/PFB file is as follows.
 .
 .RS
-.IP
-.B %!PS\-AdobeFont\-1.0:
-.RE
+.RS \" two RS calls to get inboard of IP indentation
+.EX
+%!PS\-AdobeFont\-1.0:
+.EE
+.RE \" but only one to get back to it
+.
+A PFB file contains this string as well,
+but it is preceded with some non-printing bytes.
+.RE \" now restore left margin
 .
-.IP
-A PFB file has this also in the first line, but the string is
-preceded with some binary bytes.
 .
 .IP \(bu
 Convert the AFM file to a
@@ -1373,91 +1380,129 @@ font description file with the
 .MR afmtodit @MAN1EXT@
 program.
 .
-An example call is
+For instance,
 .
 .RS
-.IP
+.RS \" two RS calls to get inboard of IP indentation
+.EX
 afmtodit Foo\-Bar\-Bold.afm map/textmap FBB
-.RE
+.EE
+.RE \" but only one to get back to it
 .
-.IP
-which converts the metric file \[oq]Foo\-Bar\-Bold.afm\[cq] to the
+converts the metric file
+.I Foo\-Bar\-Bold.afm
+to the
 .I groff
-font \[oq]FBB\[cq].
+font description file
+.IR FBB .
+.RE \" now restore left margin
 .
-If you have a font family which comes with normal, bold, italic, and
-bold italic faces, it is recommended to use the letters
+.
+.IP
+If you have a font family which provides normal upright (roman),
+bold,
+italic,
+and
+bold-italic faces,
+we recommend using
 .BR R ,
 .BR B ,
 .BR I ,
 and
 .BR BI ,
-respectively, as postfixes in the
-.I groff font names to make
+respectively,
+as suffixes to the
+.I groff
+font family name to enable
 .IR groff 's
-\[oq].fam\[cq] request work.
+font family and style selection features.
 .
 An example is
 .IR groff 's
-built-in Times-Roman font: The font family
-name is
+built-in support for Times:
+the font family
+name is abbreviated as
 .BR T ,
 and the
 .I groff
-font names are
+font names are therefore
 .BR TR ,
 .BR TB ,
 .BR TI ,
 and
 .BR TBI .
 .
+.
 .IP \(bu
-Install both the
+Install the
 .I groff
-font description files and the fonts in a
-\[oq]devpdf\[cq] subdirectory of the font path which
+font description files in a
+.I devpdf
+subdirectory in the search path that
 .I groff
-finds.
+uses for device and font file descriptions.
 .
-See section \[lq]Environment\[rq] in
+See the
+.I GROFF_FONT_PATH
+entry in section \[lq]Environment\[rq] of
 .MR @g@troff @MAN1EXT@
-for the actual value of the font path.
+for the current value of the font search path.
 .
-Note that
+While
 .I groff
-doesn't use the AFM files (but it is a good idea to
-store them anyway).
+doesn't directly use AFM files,
+it is a good idea to store them alongside its font description files.
+.
 .
 .IP \(bu
-Register all fonts which must be downloaded to the printer in the
+Register fonts in the
 .I devpdf/download
-file.
+file so that they can located for embedding PDF files
+.I gropdf
+generates.
 .
-Only the first occurrence of this file in the font path is read.
+Only the first
+.I download
+file encountered in the font search path is read.
 .
-This means that you should copy the default
+If in doubt,
+copy the default
 .I download
-file to the first directory in your font path and add your fonts there.
+file
+(see section \[lq]Files\[rq] below)
+to the first directory in the font search path and add your fonts there.
 .
-To continue the above example we assume that the PS font name for
-Foo\-Bar\-Bold.pfa is \[oq]XY\-Foo\-Bar\-Bold\[cq] (the PS font name is
-stored in the
+To continue the above example,
+we assume that the PostScript font name for
+.I Foo\-Bar\-Bold.pfa
+is \[oq]XY\-Foo\-Bar\-Bold\[cq].
+.
+This font name is stored in the
 .B internalname
 field in the
 .I FBB
-file) and belongs to foundry \[oq]F\[cq]
-thus the following line should be added to
-.IR download :
+file.
+.
+If this file belongs to a foundry named
+.BR F ,
+the following line should be added to
+.IR download .
 .
 .RS
-.IP
-.B F XY\-Foo\-Bar\-Bold Foo\-Bar\-Bold.pfa
+.RS \" two RS calls to get inboard of IP indentation
+.EX
+F\[->]XY\-Foo\-Bar\-Bold\[->]Foo\-Bar\-Bold.pfa
+.EE
+.RE \" but only one to get back to it
 .
+A tab character,
+depicted as \[->],
+separates the fields.
 .
-.LP
-Use a tab character to separate the fields, and the \[oq]foundry\[cq]
-field should be null for the default foundry.
-.RE
+The default foundry has no name,
+so its field is empty;
+the entries corresponding to it thus start with a tab character.
+.RE \" now restore left margin
 .
 .
 .br
@@ -1487,7 +1532,7 @@ and
 .TP
 .I GROPDF_NOSLIDE
 If this is set true,
-.B gropdf
+.I gropdf
 will ignore all commands which produce a presentation pdf,
 and produce a normal pdf instead.
 .