[groff] 14/18: [docs]: Amplify explanation of font glyph "type".

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit fdc10d16f8d29cd59b06a04494e0a1996e5520e4
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Jan 1 09:59:31 2022 +1100

    [docs]: Amplify explanation of font glyph "type".
    
    * Explicitly notate that the "character type" of all glyphs in
      nroff-mode fonts is typically zero.  This is a convention that goes
      back at least as far as Unix V7 troff.
    * Explicitly document it as a bit mask.
    * Illuminate its relationship with the `\w` escape and `ct` register.
    
    * Also clarify glyph names in font description files for people who
      think like parsers.
    
    * Also adjust dead-tree typography in groff_font(5).
---
 doc/groff.texi       | 23 +++++++++++++++++------
 man/groff_font.5.man | 50 +++++++++++++++++++++++++++++++++++++++-----------
 2 files changed, 56 insertions(+), 17 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 87d4ab77..6313e60d 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -18345,7 +18345,7 @@ follows.
 @c since it defines an output entity.}
 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
+@var{name} is a multi-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
@@ -18413,18 +18413,29 @@ 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.
+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.
 
 @table @code
+@item 0
+means the glyph lies entirely between the baseline and a horizontal line
+at the ``x-height'' of the font;
+typical examples are @samp{a}, @samp{c}, and @samp{x};
+
 @item 1
-means the glyph has a descender (for example, @samp{p});
+means the glyph descends below the baseline, like @samp{p};
 
 @item 2
-means the glyph has an ascender, (for example, @samp{b}); and
+means the glyph ascends above the font's x-height, like @samp{A} or
+@samp{b}; and
 
 @item 3
-means the glyph has both an ascender and a descender (for example,
-parentheses in some fonts).
+means the glyph is both an ascender and a descender---this is true of
+parentheses in some fonts.
 @end table
 
 The @var{code} field gives a numeric identifier that the postprocessor
diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index 3b47c18e..79b1f793 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -720,7 +720,7 @@ input
 .
 If
 .I name
-is a character sequence not beginning with
+is a multi-character sequence not beginning with
 .BR \[rs] ,
 it corresponds to the GNU
 .I troff \" GNU
@@ -843,31 +843,57 @@ it should be less than the italic correction.
 .
 .
 .P
-The
+For fonts used with typesetting devices,
+the
 .I type
-field gives a featural description of the glyph.
+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
+.B \[rs]w
+escape sequence is interpolated,
+these values are bitwise and-ed together
+and stored in the
+.B ct
+register.
+.
+In fonts for
+.IR nroff -mode \" generic
+output devices,
+all glyphs might have a type of zero.
+.
+.
+.TP
+0
+means the glyph lies entirely between the baseline and
+a horizontal line at the \[lq]x-height\[rq] of the font;
+typical examples are \[lq]a\[rq],
+\[lq]c\[rq],
+and
+\[lq]x\[rq];
 .
 .
 .TP
 1
-means the glyph has a descender
-(for example,
-\[lq]p\[rq]);
+means the glyph descends below the baseline,
+like \[lq]p\[rq];
 .
 .
 .TP
 2
-means the glyph has an ascender
-(for example,
+means the glyph ascends above the font's x-height,
+like \[lq]A\[rq] or
 \[lq]b\[rq]);
 and
 .
 .
 .TP
 3
-means the glyph has both an ascender and a descender
-(for example,
-parentheses in some fonts).
+means the glyph is both an ascender and a descender\[em]this is true of
+parentheses in some fonts.
 .
 .
 .P
@@ -968,6 +994,8 @@ Most kerning pairs should have a negative value
 .\" END Keep parallel with groff.texi node "Device and Font Files".
 .
 .
+.br
+.ne 4v
 .\" ====================================================================
 .SH Files
 .\" ====================================================================