[groff] 27/35: gropdf(1), grops(1): Update "font installation".

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 6fbe65f9e36e0656b2e1544dd8e69d63b8d0d784
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Jun 20 17:46:17 2022 -0500

    gropdf(1), grops(1): Update "font installation".
    
    * Use a tested, real-world example.
    * Show how to test usage of a new font in a groff document.
    * Recast to clarify and tighten wording.
    * Adjust dead-tree typography (page breaks).
---
 src/devices/gropdf/gropdf.1.man |  88 ++++++++++++-------
 src/devices/grops/grops.1.man   | 187 ++++++++++++++++++++++++++--------------
 2 files changed, 177 insertions(+), 98 deletions(-)

diff --git a/src/devices/gropdf/gropdf.1.man b/src/devices/gropdf/gropdf.1.man
index bf5b5d08..2dde504b 100644
--- a/src/devices/gropdf/gropdf.1.man
+++ b/src/devices/gropdf/gropdf.1.man
@@ -1357,9 +1357,7 @@ understands.
 This is a PostScript Type\~1 font in PFA or PFB format,
 together with an AFM file.
 .
-.
-.IP
-The first line in a PFA/PFB file is as follows.
+A PFA file begins as follows.
 .
 .RS
 .RS \" two RS calls to get inboard of IP indentation
@@ -1369,11 +1367,18 @@ The first line in a PFA/PFB file is as follows.
 .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.
+preceded by some non-printing bytes.
+.
+In the following example steps,
+we will consider the use of CTAN's
+.UR https://\:ctan.org/\:tex\-archive/\:fonts/\:brushscr
+BrushScriptX-Italic
+.UE
+font in PFA format.
 .RE \" now restore left margin
 .
 .
-.IP \(bu
+.IP \[bu]
 Convert the AFM file to a
 .I groff
 font description file with the
@@ -1385,25 +1390,27 @@ For instance,
 .RS
 .RS \" two RS calls to get inboard of IP indentation
 .EX
-afmtodit Foo\-Bar\-Bold.afm map/textmap FBB
+$ \c
+.B afmtodit BrushScriptX\-Italic.afm textmap BSI
 .EE
 .RE \" but only one to get back to it
 .
-converts the metric file
-.I Foo\-Bar\-Bold.afm
+converts the Adobe Font Metric file
+.I BrushScriptX\-Italic.afm
 to the
 .I groff
 font description file
-.IR FBB .
+.IR BSI .
 .RE \" now restore left margin
 .
 .
 .IP
-If you have a font family which provides normal upright (roman),
+If you have a font family which provides regular upright (roman),
 bold,
 italic,
 and
-bold-italic faces,
+bold-italic styles,
+(where \[lq]italic\[rq] may be \[lq]oblique\[rq] or \[lq]slanted\[rq]),
 we recommend using
 .BR R ,
 .BR B ,
@@ -1432,11 +1439,16 @@ font names are therefore
 and
 .BR TBI .
 .
+In our example,
+however,
+the BrushScriptX font is available in a single style only,
+italic.
 .
-.IP \(bu
+.
+.IP \[bu]
 Install the
 .I groff
-font description files in a
+font description file(s) in a
 .I devpdf
 subdirectory in the search path that
 .I groff
@@ -1454,10 +1466,10 @@ doesn't directly use AFM files,
 it is a good idea to store them alongside its font description files.
 .
 .
-.IP \(bu
+.IP \[bu]
 Register fonts in the
 .I devpdf/download
-file so that they can located for embedding PDF files
+file so they can be located for embedding in PDF files
 .I gropdf
 generates.
 .
@@ -1472,26 +1484,25 @@ 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 PostScript font name for
-.I Foo\-Bar\-Bold.pfa
-is \[oq]XY\-Foo\-Bar\-Bold\[cq].
-.
-This font name is stored in the
+The PostScript font name used by
+.I gropdf
+is stored in the
 .B internalname
 field in the
-.I FBB
-file.
+.I groff
+font description file.
 .
-If this file belongs to a foundry named
-.BR F ,
-the following line should be added to
+(This name does not necessarily resemble the font's file name.)
+.
+If the font in our example had originated from a foundry named
+.BR Z ,
+we would add the following line to
 .IR download .
 .
 .RS
 .RS \" two RS calls to get inboard of IP indentation
 .EX
-F\[->]XY\-Foo\-Bar\-Bold\[->]Foo\-Bar\-Bold.pfa
+Z\[->]BrushScriptX\-Italic\[->]BrushScriptX\-Italic.pfa
 .EE
 .RE \" but only one to get back to it
 .
@@ -1499,14 +1510,29 @@ A tab character,
 depicted as \[->],
 separates the fields.
 .
-The default foundry has no name,
-so its field is empty;
-the entries corresponding to it thus start with a tab character.
+The default foundry has no name:
+its field is empty and
+entries corresponding to it start with a tab character,
+as will the one in our example.
 .RE \" now restore left margin
 .
 .
+.IP \[bu]
+Test the selection and embedding of the new font.
+.
+.RS
+.RS \" two RS calls to get inboard of IP indentation
+.EX
+printf "\[rs]\[rs]f[BSI]Hello, world!\[rs]n" \
+| groff \-T pdf \-P \-e >hello.pdf
+see hello.pdf
+.EE
+.RE
+.RE
+.
+.
 .br
-.ne 3v
+.ne 5v
 .\" ====================================================================
 .SH Environment
 .\" ====================================================================
diff --git a/src/devices/grops/grops.1.man b/src/devices/grops/grops.1.man
index 3b68a905..329d8baf 100644
--- a/src/devices/grops/grops.1.man
+++ b/src/devices/grops/grops.1.man
@@ -130,7 +130,7 @@ previewer.
 .
 .
 .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 grops .
 .
@@ -1376,35 +1376,45 @@ option.
 .SH "Font installation"
 .\" ====================================================================
 .
-This section summarizes the above explanations;
-it can serve as a step-by-step font-installation guide for
-.IR grops .
+The following is a step-by-step font installation guide for
+.I grops.
 .
 .
-.IP \(bu 2n
+.IP \[bu] 2n
 Convert your font to something
 .I groff
 understands.
 .
-This is either a PostScript Type\~1 font in PFA format or a PostScript
+This is a PostScript Type\~1 font in PFA format or a PostScript
 Type\~42 font,
 together with an AFM file.
 .
 A PFA file begins as follows.
 .
 .RS
-.RS \" We need two RS calls to get inboard of the paragraph indentation.
+.RS \" two RS calls to get inboard of IP indentation
 .EX
 %!PS\-AdobeFont\-1.0:
 .EE
 .RE
 .
-A PFB file similar,
-but the string is preceded with some binary bytes.
+A PFB file contains this string as well,
+preceded by some non-printing bytes.
+.
+If your font is in PFB format,
+use
+.IR groff 's
+.MR pfbtops @MAN1EXT@
+program to convert it to PFA.
+.
+For TrueType and other font formats,
+we recommend
+.IR fontforge ,
+which can convert most outline font formats.
 .
 A Type\~42 font file begins as follows.
 .
-.RS \" We need two RS calls to get inboard of the paragraph indentation.
+.RS
 .EX
 %!PS\-TrueTypeFont
 .EE
@@ -1415,53 +1425,48 @@ This is a wrapper format for TrueType fonts.
 Old PostScript printers might not support them
 (that is,
 they might not have a built-in TrueType font interpreter).
-.RE
-.
 .
-.IP
-If your font is in PFB format
-(such fonts normally have a file extension of
-.IR .pfb ),
-you might use
-.IR groff 's
-.MR pfbtops @MAN1EXT@
-program to convert it to PFA.
-.
-For TrueType and other font formats,
-we recommend
-.IR fontforge ,
-which can convert most outline font formats.
+In the following example steps,
+we will consider the use of CTAN's
+.UR https://\:ctan.org/\:tex\-archive/\:fonts/\:brushscr
+BrushScriptX-Italic
+.UE
+font in PFA format.
+.RE \" now restore left margin
 .
 .
-.IP \(bu
+.IP \[bu]
 Convert the AFM file to a
 .I groff
 font description file with the
 .MR afmtodit @MAN1EXT@
 program.
 .
-For example,
-the invocation
+For instance,
 .
 .RS
-.RS \" We need two RS calls to get inboard of the paragraph indentation.
+.RS \" two RS calls to get inboard of IP indentation
 .EX
 $ \c
-.B afmtodit Foo\-Bar\-Bold.afm textmap FBB
+.B afmtodit BrushScriptX\-Italic.afm textmap BSI
 .EE
 .RE
 .
-converts the metric file
-.I Foo\-Bar\-Bold.afm
+converts the Adobe Font Metric file
+.I BrushScriptX\-Italic.afm
 to the
 .I groff
-font description
-.IR FBB .
+font description file
+.IR BSI .
+.RE \" now restore left margin
+.
 .
-If you have a font family which comes with normal,
+.IP
+If you have a font family which provides regular upright (roman),
 bold,
 italic,
-and bold-italic faces
+and
+bold-italic styles
 (where \[lq]italic\[rq] may be \[lq]oblique\[rq] or \[lq]slanted\[rq]),
 we recommend using the letters
 .BR R ,
@@ -1470,62 +1475,110 @@ we recommend using the letters
 and
 .BR BI ,
 respectively,
-as suffixes in their
+as suffixes to the
 .I groff
-font names to enable
+font family name to enable
 .IR groff 's
-font family and style composition feature to work.
-.RE
+font family and style selection features.
+.
+An example is
+.IR groff 's
+built-in support for Times:
+the font family
+name is abbreviated as
+.BR T ,
+and the
+.I groff
+font names are therefore
+.BR TR ,
+.BR TB ,
+.BR TI ,
+and
+.BR TBI .
+.
+In our example,
+however,
+the BrushScriptX font is available in a single style only,
+italic.
 .
 .
-.IP \(bu
-Install both the
+.IP \[bu]
+Install the
 .I groff
-font description files and the fonts in a
+font description file(s) in a
 .I devps
-subdirectory of the font path which
+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.
 .
+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
+.IP \[bu]
+Register fonts in the
 .I devps/download
-file.
+file so they can be located for embedding in PostScript files
+.I grops
+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 PostScript font name for
-.I Foo-Bar-Bold.pfa
-is \[lq]XY\-Foo\-Bar\-Bold\[rq]\[em]the PostScript font name is supplied
-by the
+The PostScript font name used by
+.I grops
+is stored in the
 .B internalname
-directive in the
-.I FBB
-file\[em]
-thus the following line should be added to
+field in the
+.I groff
+font description file.
+.
+(This name does not necessarily resemble the font's file name.)
+.
+We add the following line to
 .IR download .
 .
 .RS
-.RS \" We need two RS calls to get inboard of the paragraph indentation.
+.RS \" two RS calls to get inboard of IP indentation
 .EX
-XY\-Foo\-Bar\-Bold Foo\-Bar\-Bold.pfa
+BrushScriptX\-Italic\[->]BrushScriptX\-Italic.pfa
+.EE
+.RE \" but only one to get back to it
+.
+A tab character,
+depicted as \[->],
+separates the fields.
+.RE \" now restore left margin
+.
+.
+.IP \[bu]
+Test the selection and embedding of the new font.
+.
+.RS
+.RS \" two RS calls to get inboard of IP indentation
+.EX
+printf "\[rs]\[rs]f[BSI]Hello, world!\[rs]n" \
+| groff \-T ps \-P \-e >hello.ps
+see hello.pdf
 .EE
 .RE
-.RE
+.RE \" now restore left margin
 .
 .
 .\" ====================================================================