[groff] 07/08: [man pages]: Update font desc file utility pages.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 2cd15707be35993824ad87b50f9ba5e78ccc0aad
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Jan 28 01:29:40 2022 +1100

    [man pages]: Update font desc file utility pages.
    
    * src/utils/afmtodit/afmtodit.1.man:
    * src/utils/hpftodit/hpftodit.1.man:
    * src/utils/tfmtodit/tfmtodit.1.man:
      - Rename metasyntactic variable for output file from "font" to
        "font-description".
      - Recast mention of "downloadable" fonts to make it clear what it
        refers to and what direction the potential file transfer is in.  (I
        found this confusing on first exposure, being accustomed to a
        "download" as something that arrives on a host.)
      - Say "adapt" instead of "convert"; what results is _not_ an artifact
        capable of drawing font glyphs.
      - Migrate to font _description_ file terminology.
      - Migrate terminology from "character" to "glyph".
      - Migrate terminilogy from "character code" to "index" for glyph
        tables.  Many old font technologies use bespoke or arbitrary
        encodings.
      - Parallelize discussion of `-s` option between afmtodit(1) and
        tfmtodit(1).  hpftodit(1) handles special fonts differently.
      - Quote multi-word example input literals.
      - Tighten wording.
    
    Fix markup nits.
    - Fix missing markup around "numspecial" (tfmtodit).
    - Migrate some `LP` macro calls to `P`.
---
 src/utils/afmtodit/afmtodit.1.man | 130 ++++++++++++++++++++++----------------
 src/utils/hpftodit/hpftodit.1.man |  94 ++++++++++-----------------
 src/utils/tfmtodit/tfmtodit.1.man |  45 ++++++-------
 3 files changed, 134 insertions(+), 135 deletions(-)

diff --git a/src/utils/afmtodit/afmtodit.1.man 
b/src/utils/afmtodit/afmtodit.1.man
index a1839556..b9fc749f 100644
--- a/src/utils/afmtodit/afmtodit.1.man
+++ b/src/utils/afmtodit/afmtodit.1.man
@@ -50,7 +50,7 @@ afmtodit \- adapt Adobe Font Metrics files for groff \-Tps 
and \-Tpdf
 .IR output-file ]
 .I afm-file
 .I map-file
-.I font
+.I font-description
 .YS
 .
 .
@@ -64,7 +64,7 @@ afmtodit \- adapt Adobe Font Metrics files for groff \-Tps 
and \-Tpdf
 .\" ====================================================================
 .
 .I afmtodit
-converts an
+adapts an
 Adobe Font Metric
 file,
 .IR afm-file ,
@@ -78,10 +78,12 @@ output devices of
 .I map-file
 associates a
 .I groff
-character name with a PostScript character name.
+glyph name with a PostScript glyph name.
 .
-Output is written to
-.IR font ,
+Output is written in
+.MR groff_font @MAN5EXT@
+format to
+.I font-description,
 a file named for the intended
 .I groff
 font name
@@ -96,26 +98,26 @@ should contain a sequence of lines of the form
 .
 .RS
 .EX
-.I ps-char groff-char
+.I ps-glyph groff-glyph
 .EE
 .RE
 .
 where
-.I ps-char
-is the PostScript name of the character and
-.I groff-char
+.I ps-glyph
+is the PostScript glyph name and
+.I groff-glyph
 is the
 .I groff
-name of the character
+special character identifier for the glyph
 (as used in the
 .I groff
-font file).
+font description file).
 .
 The same
-.I ps-char
+.I ps-glyph
 can occur multiple times in the file;
 each
-.I groff-char
+.I groff-glyph
 must occur at most once.
 .
 Lines starting with \[lq]#\[rq] and blank lines are ignored.
@@ -127,7 +129,7 @@ subdirectory of the default font directory.
 .
 .
 .LP
-If a PostScript character is not mentioned in
+If a PostScript glyph is not mentioned in
 .IR map-file ,
 and a generic
 .I groff
@@ -137,10 +139,10 @@ built into
 .IR afmtodit ),
 then
 .I afmtodit
-puts the PostScript character into the
+puts the PostScript glyph into the
 .I groff
-font file as an unnamed character which can only be accessed by the
-\[lq]\eN\[rq] escape sequence in a
+font description file as an unnamed glyph which can only be accessed
+by the \[lq]\eN\[rq] escape sequence in a
 .I roff
 document.
 .
@@ -156,7 +158,7 @@ is specified,
 the encoding defined in the AFM file
 (i.e.,
 entries
-with non-negative character codes)
+with non-negative codes)
 is used.
 .
 Refer to section \[lq]Using Symbols\[rq] in
@@ -170,56 +172,56 @@ glyph names are constructed.
 .
 .
 .LP
-Characters not encoded in the AFM file
+Glyphs not encoded in the AFM file
 (i.e.,
-entries which have \[lq]\-1\[rq] as the character code)
+entries indexed as \[lq]\-1\[rq])
 are still available in
 .IR groff ;
 they get glyph index values greater than 255
-(or greater than the biggest character code used in the AFM file in the
-unlikely case that it is greater than 255)
+(or greater than the biggest code used in the AFM file in the unlikely
+case that it is greater than 255)
 in the
 .I groff
-font file.
+font description file.
 .
-Glyph indices of unencoded characters don't have a specific order;
+Unencoded glyph indices don't have a specific order;
 it is best to access them with glyph names only.
 .
 .
-.LP
-If there is a downloadable font file for the font,
+.P
+If the font is downloadable to the device as a file,
 it may be listed in the file
 .IR \%@FONTDIR@/\:\%devps/\:\%download ;
 see
 .MR grops @MAN1EXT@ .
 .
 .
-.LP
+.P
 If the
 .B \-i
 option is used,
 .I afmtodit
 automatically generates an italic correction,
 a left italic correction,
-and a subscript correction for each character
+and a subscript correction for each glyph
 (the significance of these is explained in
 .MR groff_font @MAN5EXT@ );
-they can be specified for individual characters by
+they can be specified for individual glyphs by
 adding to the
 .I afm-file
 lines of the form:
 .
 .RS
 .EX
-.RI italicCorrection \~ps-char\~n
-.RI leftItalicCorrection \~ps-char\~n
-.RI subscriptCorrection \~ps-char\~n
+.RI italicCorrection \~ps-glyph\~n
+.RI leftItalicCorrection \~ps-glyph\~n
+.RI subscriptCorrection \~ps-glyph\~n
 .EE
 .RE
 .
 where
-.I ps-char
-is the PostScript name of the character,
+.I ps-glyph
+is the PostScript glyph name,
 and
 .I n
 is the desired value of the corresponding parameter in thousandths of an
@@ -230,6 +232,28 @@ Such parameters are normally needed only for italic
 fonts.
 .
 .
+.P
+The
+.B \-s
+option should be given if the font is \[lq]special\[rq],
+meaning that
+.I groff
+should search it whenever a glyph is not found in the current font.
+.
+In that case,
+.I font-description
+should be listed as an argument to the
+.B fonts
+directive in the output device's
+.I DESC
+file;
+if it is not special,
+there is no need to do so,
+since
+.MR @g@troff @MAN1EXT@
+will automatically mount it when it is first used.
+.
+.
 .\" ====================================================================
 .SH Options
 .\" ====================================================================
@@ -238,7 +262,7 @@ fonts.
 .BI \-a\~ n
 Use
 .I n
-as the slant parameter in the font file;
+as the slant parameter in the font description file;
 this is used by
 .I groff
 in the positioning of accents.
@@ -251,8 +275,8 @@ specified in the AFM file;
 with true italic fonts it is sometimes desirable to use a slant that is
 less than this.
 .
-If you find that characters from an italic font have accents placed too
-far to the right over them,
+If you find that glyph from an italic font have accents placed too far
+to the right over them,
 then use the
 .B \-a
 option to give the font a smaller slant.
@@ -260,7 +284,7 @@ option to give the font a smaller slant.
 .
 .TP
 .B \-c
-Include comments in the font file in order to identify the PostScript
+Include comments in the font description file identifying the PostScript
 font.
 .
 .
@@ -307,12 +331,12 @@ font is set to
 .
 .TP
 .BI \-i\~ n
-Generate an italic correction for each character so that the
-character's width plus the character's italic correction is equal to
+Generate an italic correction for each glyph so that its width plus its
+italic correction is equal to
 .I n
 thousandths of an em
-plus the amount by which the right edge of the character's bounding box
-is to the right of the character's origin.
+plus the amount by which the right edge of the glyph's bounding box is
+to the right of its origin.
 .
 If this would result in a negative italic correction,
 use a zero italic correction instead.
@@ -329,12 +353,11 @@ use a subscript correction equal to the italic correction 
instead.
 .
 .
 .IP
-Also generate a left italic correction for each character
-equal to
+Also generate a left italic correction for each glyph equal to
 .I n
 thousandths of an em
-plus the amount by which the left edge of the character's bounding box
-is to the left of the character's origin.
+plus the amount by which the left edge of the glyph's bounding box is to
+the left of its origin.
 .
 The left italic correction may be negative unless option
 .B \-m
@@ -346,7 +369,7 @@ This option is normally needed only with italic
 (or oblique)
 fonts.
 .
-The font files distributed with
+The font description files distributed with
 .I groff
 were created using an option of
 .B \-i50
@@ -355,10 +378,10 @@ for italic fonts.
 .
 .TP
 .BI \-o\~ output-file
-The output file is
+Write to
 .I output-file
 instead of
-.IR font .
+.I font-description.
 .
 .
 .TP
@@ -373,10 +396,10 @@ use only for monospaced (constant-width) fonts.
 .B \-m
 Prevent negative left italic correction values.
 .
-Roman font files distributed with
+Font description files for roman styles distributed with
 .I groff
 were created with
-.B \-i0\ \-m
+.RB \[lq] \-i0\~\-m \[rq]
 to improve spacing with
 .MR @g@eqn @MAN1EXT@ .
 .
@@ -391,10 +414,9 @@ use with monospaced (constant-width) fonts.
 .
 .TP
 .B \-s
-The font is special;
-add the
+Add the
 .B special
-command to the font file.
+directive to the font description file.
 .
 .
 .TP
diff --git a/src/utils/hpftodit/hpftodit.1.man 
b/src/utils/hpftodit/hpftodit.1.man
index 6a20b283..90a4c59d 100644
--- a/src/utils/hpftodit/hpftodit.1.man
+++ b/src/utils/hpftodit/hpftodit.1.man
@@ -40,7 +40,7 @@ hpftodit \- create font description files for use with groff 
\-Tlj4
 .IR n ]
 .I tfm-file
 .I map-file
-.I output-font
+.I font-description
 .YS
 .
 .
@@ -69,7 +69,8 @@ hpftodit \- create font description files for use with groff 
\-Tlj4
 .\" ====================================================================
 .
 .I hpftodit
-creates a font file for use with a Hewlett-Packard LaserJet\~4-\%series
+creates a font description file for use with a Hewlett-Packard
+LaserJet\~4-\%series
 (or newer)
 printer with the
 .MR grolj4 @MAN1EXT@ ,
@@ -78,14 +79,14 @@ output driver of
 using data from an HP tagged font metric (TFM) file.
 .
 .I tfm-file
-is the name of the TFM file for the font;
+is the name of the font's TFM file;
 Intellifont and TrueType TFM files are supported,
 but symbol set TFM files are not.
 .
 .I map-file
 is a file giving the
 .I groff
-names for characters in the font;
+special character identifiers for glyphs in the font;
 this file should consist of a sequence of lines of the form
 .RS
 .EX
@@ -94,17 +95,17 @@ this file should consist of a sequence of lines of the form
 .RE
 where
 .I m
-is a decimal integer giving the MSL
+is a decimal integer giving the glyph's MSL
 (Master Symbol List)
-number of the character,
+number,
 .I u
-is a hexadecimal integer giving the Unicode value of the character,
+is a hexadecimal integer giving its Unicode character code,
 and
 .IR c1 ,
 .IR c2 ", .\|.\|."
-are the
+are its
 .I groff
-names of the character
+glyph names
 (see
 .MR groff_char @MAN7EXT@
 for a list).
@@ -123,9 +124,9 @@ e.g.,
 becomes
 .RB \[lq] u0041_0300 \[rq].
 .
-The name for a glyph without a
+A glyph without a
 .I groff
-name may be given as
+special character identifier may be named
 .BI u XXXX
 if the glyph corresponds to a Unicode value,
 or as an unnamed glyph
@@ -188,35 +189,17 @@ which will treat the first
 as the beginning of the comment.
 .
 .
-.LP
-The
+.P
+Output is written in
+.MR groff_font @MAN5EXT@
+format to
+.I font-description,
+a file named for the intended
 .I groff
-font file is written to the specified
-.IR output-font ;
+font name;
 if this operand is
 .RB \[lq] \- \[rq],
-the font file is written to the standard output stream.
-.
-.
-.LP
-The
-.B \-s
-option should be given if the font is special
-(a font is \[lq]special\[rq] if
-.I groff
-should search it whenever a character is not found in the current font).
-.
-If the font is special,
-it should be listed in the
-.B fonts
-command in the
-.I DESC
-file;
-if it is not special,
-there is no need to list it,
-since
-.I groff
-can automatically mount it when it's first used.
+the font description is written to the standard output stream.
 .
 .
 .LP
@@ -225,8 +208,8 @@ If the
 option is used,
 .I hpftodit
 automatically will generate an italic correction,
-a left italic correction and a subscript correction
-for each character
+a left italic correction,
+and a subscript correction for each glyph
 (the significance of these parameters is explained in
 .MR groff_font @MAN5EXT@ ).
 .
@@ -247,7 +230,7 @@ all exit afterward.
 .
 .TP
 .B \-a
-Include characters in the TFM file that are not included in
+Include glyphs in the TFM file that are not included in
 .IR map-file .
 .
 A glyph with corresponding Unicode value is given the name
@@ -340,11 +323,11 @@ is ignored if given.
 .
 .TP
 .BI \-i\~ n
-Generate an italic correction for each character so that the character's
-width plus the character's italic correction is equal to
+Generate an italic correction for each glyph so that its width plus its
+italic correction is equal to
 .I n
 thousandths of an em plus the amount by which the right edge of the
-character's bounding is to the right of the character's origin.
+glyphs's bounding box is to the right of its origin.
 .
 If this would result in a negative italic correction,
 use a zero italic correction instead.
@@ -360,10 +343,10 @@ use a subscript correction equal to the italic correction 
instead.
 .
 .
 .IP
-Also generate a left italic correction for each character equal to
+Also generate a left italic correction for each glyph equal to
 .I n
 thousandths of an em plus the amount by which the left edge of the
-character's bounding box is to the left of the character's origin.
+glyphs's bounding box is to the left of its origin.
 .
 The left italic correction may be negative.
 .
@@ -377,8 +360,8 @@ usually is a reasonable choice.
 .
 .TP
 .B \-q
-Suppress warnings about characters in the map file that were not found
-in the TFM file.
+Suppress warnings about glyphs in the map file that were not found in
+the TFM file.
 .
 Warnings never are given for unnamed glyphs or by glyphs named by their
 Unicode values.
@@ -390,23 +373,16 @@ to the standard output stream.
 .
 .TP
 .B \-s
-The font is special.
-.
-This option adds the
+Add the
 .B special
-command to the font file,
-and affects the order in which HP symbol sets are searched for each
-glyph.
+directive to the font description file,
+affecting the order in which HP symbol sets are searched for each glyph.
 .
-Without the
-.B \-s
-option,
+Without this option,
 the \[lq]text\[rq] sets are searched before the \[lq]mathematical\[rq]
 symbol sets.
 .
-With the
-.B \-s
-option,
+With it,
 the search order is reversed.
 .
 .
diff --git a/src/utils/tfmtodit/tfmtodit.1.man 
b/src/utils/tfmtodit/tfmtodit.1.man
index 08cbe1be..80942737 100644
--- a/src/utils/tfmtodit/tfmtodit.1.man
+++ b/src/utils/tfmtodit/tfmtodit.1.man
@@ -50,7 +50,7 @@ tfmtodit \- adapt TeX Font Metrics files for groff \-Tdvi
 .IR skew-char ]
 .I tfm-file
 .I map-file
-.I font
+.I font-description
 .YS
 .
 .
@@ -72,7 +72,7 @@ tfmtodit \- adapt TeX Font Metrics files for groff \-Tdvi
 .\" ====================================================================
 .
 .I tfmtodit
-creates a font file for use with the
+creates a font description file for use with the
 .B dvi
 output driver of
 .MR groff @MAN1EXT@ .
@@ -83,7 +83,7 @@ is the name of the \*(tx font metric file for the font.
 .I map-file
 is a file giving the
 .I groff
-names for characters in the font;
+special character identifiers for glyphs in the font;
 this file should consist of a sequence of lines of the form
 .
 .RS
@@ -92,50 +92,52 @@ this file should consist of a sequence of lines of the form
 .
 where
 .I i
-is a decimal integer giving the position of the character in the font,
+is a decimal integer giving the position of the glyph in the font,
 and
 .I c1
 through
 .I cn
 are
-are the
 .I groff
-names of the character.
+special character identifiers for the glyph.
 .
-If a character has no
+If a glyph has no
 .I groff
 names but exists in
 .IR tfm-file ,
-then it will be put in the
+it is put in the
 .I groff
-font file as an unnamed character.
+font description file as an unnamed character.
 .
-The
+Output is written in
+.MR groff_font @MAN5EXT@
+format to
+.I font-description,
+a file named for the intended
 .I groff
-font file is written to
-.IR font .
+font name.
 .
 .
-.LP
+.P
 The
 .B \-s
 option should be given if the font is \[lq]special\[rq],
 meaning that
 .I groff
-should search it whenever a character is not found in the current font.
+should search it whenever a glyph is not found in the current font.
 .
 In that case,
-.I font
+.I font-description
 should be listed as an argument to the
 .B fonts
-directive in the
+directive in the output device's
 .I DESC
 file;
 if it is not special,
-there is no need to list it,
+there is no need to do so,
 since
-.I groff
-can automatically mount it when it is first used.
+.MR @g@troff @MAN1EXT@
+will automatically mount it when it is first used.
 .
 .
 .LP
@@ -236,7 +238,7 @@ Use the
 produced by Metafont containing
 .RB \[lq] special \[rq]
 and
-numspecial
+.RB \[lq] numspecial \[rq]
 commands to obtain additional font metric information.
 .
 .
@@ -260,8 +262,7 @@ are ignored.
 .B \-s
 Add the
 .B special
-directive to the generated file
-.IR font .
+directive to the font description file.
 .
 .
 .\" ====================================================================