[groff] 06/08: [docs]: Clarify font description material.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit c982424d709190974b4ffe42741cde44afa05e88
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Jan 28 00:58:52 2022 +1100

    [docs]: Clarify font description material.
    
    * doc/groff.texi:
    * man/groff_font.5.man:
      - Put option brackets around the parameters that follow commas in
        glyph metrics, since the comma and the (supplementary) parameter are
        both optional and the latter must follow the former if present.
        Yes, it looks busy, but it's how the parser works.
      - Clarify how `\w` escape sequences uses character/glyph types.
      - Rename metasyntactic variables used to describe kerning pairs to
        suggest glyphs instead of characters.
      - Tighten wording.
    
    * man/groff_font.5.man: Recast to stop applying term "font file(s)" to
      groff font _description_ files.  The map is not the territory.
---
 doc/groff.texi       | 17 +++++++++--------
 man/groff_font.5.man | 25 +++++++++++++------------
 2 files changed, 22 insertions(+), 20 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index cf2b34a9..d08f474b 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -18406,7 +18406,7 @@ corresponds to the @code{troff} input 
character@tie{}@var{c}.  If
 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
+glyphs can only be accessed by 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
@@ -18440,8 +18440,8 @@ The form of the @var{metrics} field is as follows.
 
 @display
 @group
-@var{width}[@code{,}@var{height}[@code{,}@var{depth}[@code{,}@var{italic-correction}
-  [@code{,}@var{left-italic-correction}[@code{,}@var{subscript-correction}]]]]]
+@var{width}[@code{,}[@var{height}[@code{,}[@var{depth}[@code{,}[@var{italic-correction}
+  
[@code{,}[@var{left-italic-correction}[@code{,}[@var{subscript-correction}]]]]]]]]]]
 @end group
 @end display
 
@@ -18474,8 +18474,9 @@ For fonts used with typesetting devices, the @var{type} 
field gives a
 featural description of the glyph: it is a bit mask recording whether
 the glyph is an ascender, descender, both, or neither.  When a @code{\w}
 escape sequence is interpolated, these values are bitwise and-ed
-together and stored in the @code{nr} register.  In fonts for
-@code{nroff}-mode output devices, all glyphs might have a type of zero.
+together for each glyph and stored in the @code{nr} register.  In fonts
+for @code{nroff}-mode output devices, all glyphs might have a type of
+zero.
 
 @table @code
 @item 0
@@ -18527,12 +18528,12 @@ made to adjacent glyph pairs from this font.  It 
contains a sequence of
 lines formatted as follows.
 
 @Example
-@var{c1} @var{c2} @var{n}
+@var{g1} @var{g2} @var{n}
 @endExample
 
 @noindent
-The foregoing means that when glyph @var{c1} is typeset immediately
-before @var{c2}, the space between them should be increased
+The foregoing means that when glyph @var{g1} is typeset immediately
+before @var{g2}, the space between them should be increased
 by@tie{}@var{n}.  Most kerning pairs should have a negative value
 for@tie{}@var{n}.
 @c END Keep parallel with groff_font(5).
diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index 7944bdf9..8567c2f3 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -732,7 +732,7 @@ special character escape sequence
 A name consisting of three minus signs,
 .RB \[lq] \-\-\- \[rq],
 indicates that the glyph is unnamed:
-such glyphs can only be accessed by means of the
+such glyphs can only be accessed by the
 .B \[rs]N
 escape sequence in
 .IR troff . \" generic; \N is portable
@@ -775,11 +775,11 @@ it may be broken here for readability).
 .
 .IP
 .I width\/\c
-.RI [\fB, \:height\/\c
-.RI [\fB, \:depth\/\c
-.RI [\fB, \:\%italic-correction\/\c
-.RI [\fB, \:\%left-italic-correction\/\c
-.RI [\fB, \:\%subscript-correction ]]]]]
+.RI [\fB,\fP[ \:height\/\c
+.RI [\fB,\fP[ \:depth\/\c
+.RI [\fB,\fP[ \:\%italic-correction\/\c
+.RI [\fB,\fP[ \:\%left-italic-correction\/\c
+.RI [\fB,\fP[ \:\%subscript-correction ]]]]]]]]]]
 .
 .
 .P
@@ -856,6 +856,7 @@ When a
 .B \[rs]w
 escape sequence is interpolated,
 these values are bitwise and-ed together
+for each glyph
 and stored in the
 .B ct
 register.
@@ -979,14 +980,14 @@ It contains a sequence of lines formatted as follows.
 .
 .
 .IP
-.I c1 c2 n
+.I g1 g2 n
 .
 .
 .P
 The foregoing means that when glyph
-.I c1
+.I g1
 is typeset immediately before
-.IR c2 ,
+.IR g2 ,
 the space between them should be increased
 .RI by\~ n .
 .
@@ -1059,10 +1060,10 @@ and device-independent output format.
 .P
 .MR groff @MAN1EXT@ ,
 subsection \[lq]Utilities\[rq],
-lists programs available for preparing font files in a variety of
-formats for use with
+lists programs available for describing fonts in a variety of formats
+such that
 .I groff
-output drivers.
+output drivers can use them.
 .
 .
 .P