[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 27/35: gropdf(1), grops(1): Update "font installation".
From: |
G. Branden Robinson |
Subject: |
[groff] 27/35: gropdf(1), grops(1): Update "font installation". |
Date: |
Tue, 21 Jun 2022 14:26:31 -0400 (EDT) |
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
.
.
.\" ====================================================================
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 27/35: gropdf(1), grops(1): Update "font installation".,
G. Branden Robinson <=