[groff] 16/23: [docs]: Update font/DESC details.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 6062497dbad172882fa9e6e9f192e366f89b4a49
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Sep 23 15:04:37 2021 +1000

    [docs]: Update font/DESC details.
    
    * Say "font _description_ file" more consistently.
    * Reorganize presentation of font description file structure.
    * Sync groff_font(5) with corresponding nodes from our Texinfo manual.
    * Tighten wording.
---
 doc/groff.texi       | 66 +++++++++++++++++++++------------------------
 man/groff_font.5.man | 76 +++++++++++++++++++++++++---------------------------
 2 files changed, 68 insertions(+), 74 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 4bb40ca..cec6387 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -18009,8 +18009,8 @@ directive.
 
 @item unitwidth @var{n}
 @kindex unitwidth
-Quantities in the font files are given in basic units for fonts whose
-point size is @var{n}@tie{}scaled points.
+Quantities in the font description files are in basic units for fonts
+whose point size is @var{n}@tie{}scaled points.
 
 @item unscaled_charwidths
 @kindex unscaled_charwidths
@@ -18076,10 +18076,13 @@ wide at a notional type size of 
800@tie{}points.@footnote{800-point type
 is not practical for most purposes, but using it enables the quantities
 in the font description files to be expressed as integers.}
 
-A font description file has two sections; empty lines are ignored in
-both.  The first section is a sequence of lines, each containing a
-sequence of space-delimited words; the first word in the line is a key,
-and subsequent words associate a value with that key.
+A font description file has two sections.  The first is a sequence of
+directives;
+@cindex comments in font description files
+@cindex font description files, comments
+@kindex #
+it can contain comments, which start with the @samp{#} character and
+extend to the end of a line.  Empty lines are ignored in both sections.
 
 @table @code
 @item name @var{f}
@@ -18095,14 +18098,14 @@ a type size of @var{unit-width} points.
 The @code{name} directive is mandatory, and @code{spacewidth} is
 recommended for any font expected to be current when a space is
 encountered in @code{roff} input.@footnote{Thus, ``symbol'' or
-``dingbats'' fonts might safely omit it.}  Other directives in this
-section are optional.
+``dingbats'' fonts might safely omit it.}  The following directives are
+optional.
 
 @table @code
 @item slant @var{n}
 @kindex slant
-The glyphs of the font have a slant of @var{n}@tie{}degrees, where a
-positive @var{n} slants in the direction of text flow.
+The font's glyphs have a slant of @var{n}@tie{}degrees; a positive
+@var{n} slants in the direction of text flow.
 
 @item ligatures @var{lig1} @r{@dots{}} @var{lign} @r{[}0@r{]}
 @kindex ligatures
@@ -18115,34 +18118,29 @@ must not extend over more than one line.
 @item special
 @cindex special fonts
 @kindex special
-The font is @dfn{special}; this means that when a glyph is requested
-that is not present in the current font, it is searched for in any
-special fonts that are mounted.
+The font is @dfn{special}: when a glyph is requested that is not present
+in the current font, it is sought in any mounted fonts that bear this
+property.
 @end table
 
-Other directives are ignored by GNU @code{troff} but may be used by
-postprocessors to store arbitrary information about the font in the
-file.
-
-@cindex comments in font description files
-@cindex font description files, comments
-@kindex #
-The first section can contain comments, which start with the @samp{#}
-character and extend to the end of a line.
+Other directives in this section are ignored by GNU @code{troff}, but
+may be used by postprocessors to store arbitrary information about the
+font in the file.
 
-The second section contains one or two subsections.  A @code{charset}
+The second section contains one or two subsections. These can appear in
+either order; the first one encountered commences the second section.
+Each starts with a directive on a line by itself.  A @code{charset}
 subsection is mandatory unless the associated @file{DESC} file contains
-the @code{unicode} directive.  It may also contain a @code{kernpairs}
-subsection.  These subsections can appear in either order.  Each
-subsection starts with a directive on a line by itself.
+the @code{unicode} directive.  Another subsection, @code{kernpairs},
+is optional.
 
 @kindex charset
 The directive @code{charset} starts the character set
-subsection.@footnote{This keyword is misnamed since it starts an ordered
-list of glyphs, not characters.}  The @code{charset} line is followed by
-a sequence of lines, each with information about one glyph.  A line
-comprises a number of fields separated by spaces or tabs.  The format is
-as follows.
+subsection.@footnote{For typesetter devices, this keyword is misnamed
+since it starts an ordered list of glyphs, not characters.}  The
+@code{charset} line is followed by a sequence of lines, each with
+information about one glyph.  A line comprises a number of fields
+separated by spaces or tabs.  The format is as follows.
 
 @quotation
 @var{name} @var{metrics} @var{type} @var{code} [@var{entity-name}]
@@ -18252,10 +18250,8 @@ driver could encode its character set.  For example, 
the glyph
 @samp{\[Po]} is represented by @samp{&pound;} in @acronym{HTML} 4.0.
 For efficiency, these data are now compiled directly into
 @code{grohtml}.  @code{grops} uses the field to build sub-encoding
-arrays for PostScript fonts containing more than 256 glyphs.
-
-Anything on the line after the @var{entity-name} field or @samp{--} is
-ignored.
+arrays for PostScript fonts containing more than 256 glyphs.  Anything
+on the line after the @var{entity-name} field or @samp{--} is ignored.
 
 A line in the @code{charset} section can also have the following format.
 
diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index 64aaf76..f15fa1a 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -424,8 +424,8 @@ output devices use this directive.
 .
 .TP
 .BI unitwidth\~ n
-Quantities in the font files are given in basic units for fonts whose
-point size is
+Quantities in the font description files are in basic units for fonts
+whose point size is
 .IR n \~scaled
 points.
 .
@@ -456,6 +456,8 @@ The vertical resolution is
 .IR n \~basic
 units.
 .
+All vertical quantities are rounded to multiples of this value.
+.
 .
 .TP
 .B charset
@@ -546,13 +548,15 @@ expressed as integers.)
 .
 .
 .P
-A font description file has two sections;
-empty lines are ignored in both.
+A font description file has two sections.
+.
+The first is a sequence of directives;
+it can contain comments,
+which start with the
+.RB \[lq] # \[rq]
+character and extend to the end of a line.
 .
-The first section is a sequence of lines,
-each containing a sequence of space-delimited words;
-the first word in the line is a key,
-and subsequent words associate a value with that key.
+Empty lines are ignored in both sections.
 .
 .
 .TP
@@ -584,14 +588,14 @@ input.
 (Thus,
 \[lq]symbol\[rq] or \[lq]dingbats\[rq] fonts might safely omit it.)
 .
-Other directives in this section are optional.
+The following directives are optional.
 .
 .
 .TP
 .BI slant\~ n
-The glyphs of the font have a slant of
-.IR n \~degrees,
-where a positive
+The font's glyphs have a slant of
+.IR n \~degrees;
+a positive
 .I n
 slants in the direction of text flow.
 .
@@ -625,28 +629,25 @@ The list of ligatures must not extend over more than one 
line.
 .TP
 .B special
 The font is
-.IR special ;
-this means that when a glyph is requested that is not present in
-the current font,
-it is searched for in any special fonts that are mounted.
+.IR special :
+when a glyph is requested that is not present in the current font,
+it is sought in any mounted fonts that bear this property.
 .
 .
 .P
-Other directives are ignored by
-.I \%@g@troff
-but may be used by postprocessors to store arbitrary information
-about the font in the file.
+Other directives in this section are ignored by
+.IR \%@g@troff ,
+but may be used by postprocessors to store arbitrary information about
+the font in the file.
 .
 .
 .P
-The first section can contain comments,
-which start with the
-.RB \[lq] # \[rq]
-character and extend to the end of a line.
+The second section contains one or two subsections.
 .
+These can appear in either order;
+the first one encountered commences the second section.
 .
-.P
-The second section contains one or two subsections.
+Each starts with a directive on a line by itself.
 .
 A
 .B charset
@@ -656,13 +657,9 @@ file contains the
 .B unicode
 directive.
 .
-It may also contain a
-.B kernpairs
-subsection.
-.
-These subsections can appear in either order.
-.
-Each subsection starts with a directive on a line by itself.
+Another subsection,
+.BR kernpairs ,
+is optional.
 .
 .
 .P
@@ -670,7 +667,8 @@ The directive
 .B charset
 starts the charset subsection.
 .
-(This keyword is a misnomer since it starts an ordered list of glyphs,
+(For typesetter devices,
+this keyword is a misnomer since it starts an ordered list of glyphs,
 not characters.)
 .
 The
@@ -685,7 +683,7 @@ The format is as follows.
 .
 .IP
 .I name metrics type code
-.RI [ entity_name ]
+.RI [ entity-name ]
 .RB [ \-\-
 .IR comment ]
 .
@@ -855,7 +853,7 @@ function).
 .
 .P
 The
-.I entity_name
+.I entity-name
 field defines an identifier for the glyph that the postprocessor
 uses to print the
 .I \%@g@troff
@@ -882,9 +880,9 @@ these data are now compiled directly into
 uses the field to build sub-encoding arrays for PostScript fonts
 containing more than 256 glyphs.
 .
-.
-.P
-Anything on the line after the encoding field or
+Anything on the line after the
+.I entity-name
+field or
 .RB \[lq] \-\- \[rq]
 is ignored.
 .