[groff] 13/14: [docs]: Fix font desc file content and style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d837b0e5b0279b7a91a84997747a7177f9327bd9
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Nov 1 14:34:29 2021 +1100

    [docs]: Fix font desc file content and style nits.
    
    Content:
    * Directives aren't strictly "one per line"; a few can span more than
      one line.
    * Correct and clarify explanation of character/glyph repertoire
      definitions.
      - These entities have to be printable.
      - Fix error: special character glyph names generally _don't_ start
        with a backslash here.  Problem introduced by me on 17 July.
      - Discuss the three cases of a charset entry beginning with a
        backslash worth mentioning.  (The backslash glyph itself requires no
        special treatment here, though in our font descriptions "rs" always
        either aliases it or duplicates its definition.)
    
    Style:
    * Use imperative mood when explaining device description directives only
      when they have more to do with changing formatter operation (a lot of
      grohtml stuff) than with _describing the device_.
    * Postprocessors don't "store" information in device description files,
      they obtain it.
    * Refer to "device control" instead of "special" commands.  I complain
      yet again of the reckless overloading of the word "special" in *roff
      documentation.
    * Say "font _description_ file" more reliably.
    * Say "directive" instead of "keyword".
    * Tighten wording.
    * Add comment about the weirdness of glyph names starting with \; worth
      noting for source divers but too obscure even for a footnote.
    
    Sync groff.texi with groff_font(5).
---
 doc/groff.texi       | 119 +++++++++++++++++++++++++++------------------------
 man/groff_font.5.man | 100 ++++++++++++++++++++++++-------------------
 2 files changed, 121 insertions(+), 98 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 3767954..2d30c1c 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -17910,16 +17910,16 @@ extensions of those used by @acronym{AT&T} 
device-independent
 @code{groff} lacks a binary format; all files are text
 files.@footnote{Plan@tie{}9 @code{troff} has also abandoned the binary
 format.}  The device and font description files for a device @var{name}
-are stored in a directory called @file{dev@var{name}}.  The device
+are stored in a @file{dev@var{name}} directory.  The device
 description file is called @file{DESC}, and, for each font@tie{}@var{f}
-supported by the device, a font file called@tie{}@file{@var{f}}, where
-@var{f}@tie{}is usually an abbreviation of a font's name and/or style.
-For example, the @code{ps} (PostScript) device has @code{groff} font
-description files for Times roman (@file{TR}) and Zapf Chancery Medium
-italic (@file{ZCMI}), among many others, while the @code{utf8} device
-(for terminal emulators) has only font descriptions for the roman,
-italic, bold, and bold-italic styles (@file{R}, @file{I}, @file{B}, and
-@file{BI}, respectively).
+supported by the device, a font description file is
+called@tie{}@file{@var{f}}, where @var{f}@tie{}is usually an
+abbreviation of a font's name and/or style.  For example, the @code{ps}
+(PostScript) device has @code{groff} font description files for Times
+roman (@file{TR}) and Zapf Chancery Medium italic (@file{ZCMI}), among
+many others, while the @code{utf8} device (for terminal emulators) has
+only font descriptions for the roman, italic, bold, and bold-italic
+styles (@file{R}, @file{I}, @file{B}, and @file{BI}, respectively).
 
 @menu
 * DESC File Format::
@@ -17935,9 +17935,9 @@ italic, bold, and bold-italic styles (@file{R}, 
@file{I}, @file{B}, and
 @cindex format of font description file
 @pindex DESC@r{ file format}
 
-The @file{DESC} file contains a series of directives, one per line.
-Except for the @code{charset} directive, which must come last (if at
-all), the order of the lines is not important.  If a directive name is
+The @file{DESC} file contains a series of directives; each begins a
+line.  Except for the @code{charset} directive, which must come last (if
+at all), their order is not important.  If a directive name is
 duplicated, however, later entries in the file override previous ones.
 @cindex comments in device description files
 @cindex device description files, comments
@@ -17976,8 +17976,8 @@ this directive.
 
 @item paperlength @var{n}
 @kindex paperlength
-The vertical dimension of the output medium is @var{n}@tie{}basic units.
-Deprecated: use @code{papersize} instead.
+The vertical dimension of the output medium is @var{n}@tie{}basic units
+(deprecated: use @code{papersize} instead).
 
 @item papersize @var{format-or-dimension-pair-or-file-name} @r{@dots{}}
 @kindex papersize
@@ -18012,7 +18012,7 @@ left to right and uses the first valid paper 
specification.
 @item paperwidth @var{n}
 @kindex paperwidth
 The horizontal dimension of the output medium is @var{n}@tie{}basic
-units.  Deprecated: use @code{papersize} instead.
+units (deprecated: use @code{papersize} instead).
 
 @item pass_filenames
 @kindex pass_filenames
@@ -18089,9 +18089,9 @@ The @code{grohtml} driver uses this directive.
 
 @item use_charnames_in_special
 @kindex use_charnames_in_special
-This directive indicates that GNU @code{troff} should encode special
-characters inside special commands; @xref{Postprocessor Access}.  The
-@code{grohtml} driver uses this directive.
+GNU @code{troff} should encode special characters inside device control
+commands; @xref{Postprocessor Access}.  The @code{grohtml} driver uses
+this directive.
 
 @item vert @var{n}
 @kindex vert
@@ -18116,7 +18116,7 @@ GNU @code{troff} recognizes but ignores the directives 
@code{spare1},
 
 The @code{res}, @code{unitwidth}, @code{fonts}, and @code{sizes} lines
 are mandatory.  Directives not listed above are ignored by GNU
-@code{troff} but may be used by postprocessors to store arbitrary
+@code{troff} but may be used by postprocessors to obtain arbitrary
 information about a device in the @file{DESC} file.
 
 @c ---------------------------------------------------------------------
@@ -18195,10 +18195,10 @@ property.
 @end table
 
 Other directives in this section are ignored by GNU @code{troff}, but
-may be used by postprocessors to store arbitrary information about the
+may be used by postprocessors to obtain arbitrary information about the
 font in the file.
 
-The second section contains one or two subsections. These can appear in
+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
@@ -18207,7 +18207,7 @@ is optional.
 
 @kindex charset
 The directive @code{charset} starts the character set
-subsection.@footnote{For typesetter devices, this keyword is misnamed
+subsection.@footnote{For typesetter devices, this directive is misnamed
 since it starts a list of glyphs, not characters.}  It precedes a series
 of glyph descriptions, one per line.  Each such glyph description
 comprises a set of fields separated by spaces or tabs and organized as
@@ -18234,13 +18234,27 @@ follows.
 @c glyphs, is not clearly separated in the terminology of @code{groff};
 @c for example, the @code{char} request should be called @code{glyph}
 @c since it defines an output entity.}
-if @var{name} is a single character@tie{}@var{c}, it corresponds to the
-@code{troff} input character@tie{}@var{c}.  Otherwise, it must be of the
-form @samp{\@var{name}} where @var{name} is at least one character; it
-then corresponds to the GNU @code{troff} special character escape
-sequence @samp{\[@var{name}]},
-or the one-sixth and one-twelfth unbreakable space escape sequences,
-@code{\|} and @code{\^} (``thin'' and ``hair'' spaces, respectively).
+if @var{name} is a single printable character@tie{}@var{c}, it
+corresponds to the @code{troff} input character@tie{}@var{c}.  If
+@var{name} is a character sequence not beginning with @code{\}, it
+corresponds to the GNU @code{troff} special character escape sequence
+@samp{\[@var{name}]}.  A name consisting of three minus signs,
+@samp{---}, is special and indicates that the glyph is unnamed: such
+glyphs can only be accessed by means of the @code{\N} escape sequence in
+@code{troff}.  A special character named @samp{---} can still be defined
+using @code{char} and similar requests.  The @var{name} @samp{\-}
+defines the minus sign glyph.  Finally, @var{name} can be the
+unbreakable one-sixth and one-twelfth space escape sequences, @code{\|}
+and @code{\^} (``thin'' and ``hair'' spaces, respectively), in which
+case only the width metric described below is interpreted; a font can
+thus customize the widths of these spaces.
+@c XXX: For exhaustivity purposes...you can define "\whatever", which
+@c has to be accessed with \C'\\whatever' or \[\\whatever], but the
+@c parser matches predefined escape sequences before looking up special
+@c characters.  Most such definitions are inaccessible from the
+@c language, because nearly every '\x', where 'x' is a Unicode basic
+@c Latin character, is a predefined groff escape sequence.
+@c
 @c XXX: Commented out because the charXXX feature is very legacy, and as
 @c noted below, discouraged in font description files.
 @c
@@ -18255,11 +18269,6 @@ or the one-sixth and one-twelfth unbreakable space 
escape sequences,
 @c related to input, not output.  Otherwise, you get hard-coded
 @c connections between input and output encoding, which prevents use of
 @c different (input) character sets.
-A name consisting of three minus signs, @samp{---}, is special and
-indicates that the glyph is unnamed: such glyphs can only be accessed by
-means of the @code{\N} escape sequence in @code{troff}.  A special
-character named @samp{---} can still be defined using @code{char} and
-similar requests.
 
 The form of the @var{metrics} field is as follows.
 
@@ -18271,27 +18280,27 @@ The form of the @var{metrics} field is as follows.
 @end display
 
 @noindent
-There must not be any spaces between these subfields (it has been split
-here into two lines only for better legibility).  Missing subfields are
-assumed to be@tie{}@code{0}.  The subfields are all decimal integers.
-Since there is no associated binary format, these values are not
-required to fit into the C language data type @samp{char} as they are in
-@acronym{AT&T} device-independent @code{troff}.  The @var{width}
-subfield gives the width of the glyph.  The @var{height} subfield gives
-the height of the glyph (upwards is positive); if a glyph does not
-extend above the baseline, it should be given a zero height, rather than
-a negative height.  The @var{depth} subfield gives the depth of the
-glyph, that is, the distance below the baseline to which the glyph
-extends (downwards is positive); if a glyph does not extend below the
-baseline, it should be given a zero depth, rather than a negative depth.
-Italic corrections are relevant to glyphs in italic or oblique styles.
-The @var{italic-correction} is the amount of space that should be added
-after an oblique glyph to be followed immediately by an upright glyph.
-The @var{left-italic-correction} is the amount of space that should be
-added before an oblique glyph to be preceded immediately by an upright
-glyph.  The @var{subscript-correction} is the amount of space that
-should be added after an oblique glyph to be followed by a subscript; it
-should be less than the italic correction.
+There must not be any spaces, tabs, or newlines between these subfields
+(it has been split here into two lines only for better legibility).
+Missing subfields are assumed to be@tie{}@code{0}.  The subfields are
+all decimal integers.  Since there is no associated binary format, these
+values are not required to fit into the C language data type @samp{char}
+as they are in @acronym{AT&T} device-independent @code{troff}.  The
+@var{width} subfield gives the width of the glyph.  The @var{height}
+subfield gives the height of the glyph (upwards is positive); if a glyph
+does not extend above the baseline, it should be given a zero height,
+rather than a negative height.  The @var{depth} subfield gives the depth
+of the glyph, that is, the distance below the baseline to which the
+glyph extends (downwards is positive); if a glyph does not extend below
+the baseline, it should be given a zero depth, rather than a negative
+depth.  Italic corrections are relevant to glyphs in italic or oblique
+styles.  The @var{italic-correction} is the amount of space that should
+be added after an oblique glyph to be followed immediately by an upright
+glyph.  The @var{left-italic-correction} is the amount of space that
+should be added before an oblique glyph to be preceded immediately by an
+upright glyph.  The @var{subscript-correction} is the amount of space
+that should be added after an oblique glyph to be followed by a
+subscript; it should be less than the italic correction.
 
 The @var{type} field gives a featural description of the glyph.
 
diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index 221501a..0b15d88 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -49,8 +49,9 @@ has also abandoned the binary format.)
 .
 The device and font description files for a device
 .I name
-are stored in a directory called
-.IR dev name.
+are stored in a
+.IR dev name
+directory.
 .
 The device description file is called
 .IR DESC ,
@@ -58,7 +59,7 @@ and,
 for each
 .RI font\~ f
 supported by the device,
-a font file
+a font description file is
 .RI called\~\[lq] f \[rq],
 where
 .IR f \~is
@@ -97,15 +98,15 @@ respectively).
 .
 The
 .I DESC
-file contains a series of directives,
-one per line.
+file contains a series of directives;
+each begins a line.
 .
 Except for the
 .B charset
 directive,
 which must come last
 (if at all),
-the order of the lines is not important.
+their order is not important.
 .
 If a directive name is duplicated,
 however,
@@ -175,17 +176,16 @@ driver uses this directive.
 .BI paperlength\~ n
 The vertical dimension of the physical output medium is
 .IR n \~basic
-units.
-.
-Deprecated:
+units
+(deprecated:
 use
 .B papersize
-instead.
+instead).
 .
 .
 .TP
 .BI papersize\~ format-or-dimension-pair-or-file-name
-Set the dimensions of the physical output medium according to the
+The dimensions of the physical output medium are as according to the
 argument,
 which is either
 a standard paper format,
@@ -268,12 +268,11 @@ scans from left to right and uses the first valid paper 
specification.
 .BI paperwidth\~ n
 The horizontal dimension of the physical output medium is
 .IR n \~basic
-units.
-.
-Deprecated:
+units
+(deprecated:
 use
 .B papersize
-instead.
+instead).
 .
 .
 .TP
@@ -303,14 +302,11 @@ Use
 .I program
 as a preprocessor.
 .
-Currently,
-this keyword is used only when
-.I \%@g@troff
-is directed to use the
+The
 .B html
-or
+and
 .B xhtml
-output devices.
+output devices use this directive.
 .
 .
 .TP
@@ -413,6 +409,7 @@ they either override the default mappings for those 
particular
 characters or add new mappings
 (normally for composite characters).
 .
+.
 .IP
 The
 .BR utf8 ,
@@ -441,9 +438,8 @@ driver uses this directive.
 .
 .TP
 .B use_charnames_in_special
-This directive indicates that
 .I \%@g@troff
-should encode named glyphs inside special commands.
+should encode named glyphs inside device control commands.
 .
 The
 .I \%grohtml
@@ -492,8 +488,8 @@ lines are mandatory.
 .
 Directives not listed above are ignored by
 .I \%@g@troff
-but may be used by postprocessors to store arbitrary information about
-a device in the
+but may be used by postprocessors to obtain arbitrary information about
+the device described in the
 .I DESC
 file.
 .
@@ -635,8 +631,8 @@ it is sought in any mounted fonts that bear this property.
 .P
 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.
+but may be used by postprocessors to obtain arbitrary information about
+the font described in the file.
 .
 .
 .P
@@ -666,7 +662,7 @@ The directive
 starts the character set subsection.
 .
 (For typesetter devices,
-this keyword is a misnomer since it starts a list of glyphs,
+this directive is misnamed since it starts a list of glyphs,
 not characters.)
 .
 It precedes a series of glyph descriptions,
@@ -688,28 +684,23 @@ spaces or tabs and organized as follows.
 identifies the glyph:
 if
 .I name
-is a single
+is a single printable
 .RI character\~ c ,
 it corresponds to the
 .I troff \" generic
 input
 .RI character\~ c .
 .
-Otherwise,
-it must be of the form
-.BI \[rs] name
-where
+If
 .I name
-is at least one character;
-it then corresponds to the
-.I groff
+is a character sequence not beginning with
+.BR \[rs] ,
+it corresponds to the GNU
+.I troff \" GNU
 special character escape sequence
+\[lq]\c
 .BI \[rs][ name ]\c
-\&,
-or the one-sixth and one-twelfth unbreakable space escape sequences,
-\[rs]| and \[rs]\[ha]
-(\[lq]thin\[rq] and \[lq]hair\[rq] spaces,
-respectively).
+\[rq].
 .
 A name consisting of three minus signs,
 .RB \[lq] \-\-\- \[rq],
@@ -725,13 +716,34 @@ can still be defined using
 .B .char
 and similar requests.
 .
+The
+.I name
+.RB \[lq] \[rs]\- \[rq]
+defines the minus sign glyph.
+.
+Finally,
+.I name
+can be the unbreakable one-sixth and one-twelfth space escape
+sequences,
+\[rs]| and \[rs]\[ha]
+(\[lq]thin\[rq] and \[lq]hair\[rq] spaces,
+respectively),
+in which case only the width metric described below is interpreted;
+a font can thus customize the widths of these spaces.
+.\" XXX: For exhaustivity purposes...you can define "\whatever", which
+.\" has to be accessed with \C'\\whatever' or \[\\whatever], but the
+.\" parser matches predefined escape sequences before looking up special
+.\" characters.  Most such definitions are inaccessible from the
+.\" language, because nearly every '\x', where 'x' is a Unicode basic
+.\" Latin character, is a predefined groff escape sequence.
+.
 .
 .P
 The form of the
 .I metrics
 field is as follows
 (on one line;
-it may be broken here for the sake of readability).
+it may be broken here for readability).
 .
 .
 .IP
@@ -744,7 +756,9 @@ it may be broken here for the sake of readability).
 .
 .
 .P
-There must not be any spaces between these subfields.
+There must not be any spaces,
+tabs,
+or newlines between these subfields.
 .
 Missing subfields are assumed to
 .RB be\~ 0 .