[groff] 07/16: [docs]: Clarify device, font desc file syntax.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit dae936714108f2f005c4d2c387c103bead5359c7
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Nov 5 02:00:50 2021 +1100

    [docs]: Clarify device, font desc file syntax.
    
    * doc/groff.texi (Device and Font Files):
    * man/groff_font.5.man:
      - Clarify which font names are valid.
      - Describe how spaces and tabs are handled.
      - Only font description file `charset` sections determine character
        mappings, removing inferrable conflict with claim that the (DESC
        file's) charset section is ignored.
      - Don't re-explain the unit-width concept in the `spacewidth`
        description.
      - Explain what the kernpairs section is for less circularly.
    
    * man/groff_font(5): Fix missing ellipsis in `papersize` synopsis.
---
 doc/groff.texi       | 32 +++++++++++++++++++-------------
 man/groff_font.5.man | 45 ++++++++++++++++++++++++++++++++-------------
 2 files changed, 51 insertions(+), 26 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 509b111..ac2f816 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -17942,6 +17942,7 @@ line.  Their order is not important, with two 
exceptions: (1) the
 directive name is repeated, later entries in the file override previous
 ones (except that the paper dimensions are computed based on the
 @code{res} directive last seen when @code{papersize} is encountered).
+Spaces and/or tabs separate words and are ignored at line boundaries.
 @cindex comments in device description files
 @cindex device description files, comments
 @kindex #
@@ -18073,9 +18074,10 @@ instead of glyphs.
 
 If @code{unicode} is present, no @code{charset} section is required in
 the font description files since the Unicode handling built into
-@code{groff} is used.  However, if there are entries in a @code{charset}
-section, they either override the default mappings for those particular
-characters or add new mappings (normally for composite characters).
+@code{groff} is used.  However, if there are entries in a font
+description file's @code{charset} section, they either override the
+default mappings for those particular characters or add new mappings
+(normally for composite characters).
 
 The @code{utf8}, @code{html}, and @code{xhtml} output devices use this
 directive.
@@ -18152,24 +18154,27 @@ in the font description files to be expressed as 
integers.}
 A font description file has two sections.  The first is a sequence of
 directives, and is parsed similarly to the @file{DESC} file described
 above.  Except for the directive names that begin the second section,
-their ordering is immaterial; later directives of the same name override
-earlier ones;
+their ordering is immaterial.   Later directives of the same name
+override earlier ones, spaces and tabs are handled in the same way,
 @cindex comments in font description files
 @cindex font description files, comments
 @kindex #
-and the same comment syntax is supported.  Empty lines are ignored in
-both sections.
+and the same comment syntax is supported.  Empty lines are ignored
+throughout.
 
 @table @code
 @item name @var{f}
 @kindex name
-The name of the font is@tie{}@var{f}.  @samp{DESC} and @samp{0} are
-invalid font names.
+The name of the font is@tie{}@var{f}.  @samp{DESC} is an invalid font
+name.  Simple integers are valid, but their use is
+discouraged.@footnote{@code{groff} requests and escape sequences
+interpret non-negative font names as mounting positions instead.
+Further, a font named @samp{0} cannot be automatically mounted by the
+@code{fonts} directive of a @file{DESC} file.}
 
 @item spacewidth @var{n}
 @kindex spacewidth
-The width of a normal, unadjusted space is @var{n}@tie{}basic units at
-a type size of @var{unit-width} points.
+The width of an unadjusted inter-word space is @var{n}@tie{}basic units.
 @end table
 
 The directives above are mandatory in the first section; those below are
@@ -18346,8 +18351,9 @@ This notation indicates that @var{name} is another name 
for the glyph
 named on the preceding line.  Such aliases can be chained.
 
 @kindex kernpairs
-The word @code{kernpairs} starts a section listing kerning pairs.  It
-contains a sequence of lines formatted as follows.
+The word @code{kernpairs} starts a list of kerning adjustments to be
+made to specific glyph pairs.  It contains a sequence of lines formatted
+as follows.
 
 @Example
 @var{c1} @var{c2} @var{n}
diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index 33f880c..a533403 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -122,6 +122,8 @@ directive last seen when
 .B \%papersize
 is encountered).
 .
+Spaces and/or tabs separate words and are ignored at line boundaries.
+.
 Comments start with the
 .RB \[lq] # \[rq]
 character and extend to the end of a line.
@@ -194,7 +196,8 @@ instead).
 .
 .
 .TP
-.BI papersize\~ format-or-dimension-pair-or-file-name
+.BI papersize\~ format-or-dimension-pair-or-file-name\c
+\~.\|.\|.
 The dimensions of the physical output medium are as according to the
 argument,
 which is either
@@ -412,7 +415,7 @@ handling built into
 is used.
 .
 However,
-if there are entries in a
+if there are entries in a font description file's
 .B charset
 section,
 they either override the default mappings for those particular
@@ -563,11 +566,13 @@ and is parsed similarly to the
 file described above.
 .
 Except for the directive names that begin the second section,
-their ordering is immaterial;
-later directives of the same name override earlier ones;
+their ordering is immaterial.
+.
+Later directives of the same name override earlier ones,
+spaces and tabs are handled in the same way,
 and the same comment syntax is supported.
 .
-Empty lines are ignored in both sections.
+Empty lines are ignored throughout.
 .
 .
 .TP
@@ -576,18 +581,30 @@ The name of the font
 .RI is\~ F .
 .
 .RB \[lq] DESC \[rq]
-and
+is an invalid font name.
+.
+Simple integers are valid,
+but their use is discouraged.
+.
+.RI ( groff
+requests and escape sequences interpret non-negative font names as
+mounting positions instead.
+.
+Further,
+a font named
 .RB \[lq] 0 \[rq]
-are invalid font names.
+cannot be automatically mounted by the
+.B fonts
+directive of a
+.I DESC
+file.)
 .
 .
 .TP
 .BI spacewidth\~  n
-The width of a normal,
-unadjusted space is
+The width of an unadjusted inter-word space is
 .IR n \~basic
-units at a type size of
-.IR unit-width \~points.
+units.
 .
 .
 .P
@@ -907,7 +924,9 @@ is ignored.
 .
 .
 .P
-A line in the charset section can also have the following format.
+A line in the
+.B charset
+section can also have the following format.
 .
 .
 .IP
@@ -925,7 +944,7 @@ Such aliases can be chained.
 .P
 The word
 .B kernpairs
-starts the kernpairs section.
+starts a list of kerning adjustments to be made to specific glyph pairs.
 .
 It contains a sequence of lines formatted as follows.
 .