[groff] 08/08: [docs]: Explain font unitwidth and spacewidth.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 7ae6d67b7c310c54bb7176c761b1f9719e64201a
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Jul 30 14:56:56 2021 +1000

    [docs]: Explain font unitwidth and spacewidth.
    
    Thanks to Dave Kemper and Bjarni Ingi Gislason for their feedback.
    
    Addresses Savannah #58581 but does not yet fix it, because I also want
    to tackle the somewhat related issue of "sizescale", a groff extension
    to the AT&T device-independent troff description files.
---
 doc/groff.texi       | 25 ++++++++++++++++++----
 man/groff_font.5.man | 60 ++++++++++++++++++++++++++++++++++++++++++++--------
 2 files changed, 72 insertions(+), 13 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 5ab47d3..acc36e8 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -17913,9 +17913,7 @@ extend over more than one line.
 @item sizescale @var{n}
 @kindex sizescale
 Set the scale factor for point sizes to one divided by@tie{}@var{n}.
-The default is@tie{}@code{1}.  The arguments to the @code{unitwidth} and
-@code{sizes} directives are given in scaled points.  @xref{Fractional
-Type Sizes}.
+The default is@tie{}@code{1}.  @xref{Fractional Type Sizes}.
 
 @item styles @var{S1} @r{@dots{}} @var{Sm}
 @kindex styles
@@ -17986,6 +17984,24 @@ information about a device in the @file{DESC} file.
 @cindex format of font files
 @cindex format of font description files
 
+On typesetting output devices, each font is typically available at
+multiple sizes.  While paper size measurements in the device description
+file are in absolute units, measurements applicable to fonts must be
+proportionate to the type size.  @code{groff} achieves this using the
+system pioneered by @acronym{AT&T} device-independent @code{troff} one
+size of a font is chosen as a norm, and all other sizes are scaled
+linearly relative to that basis.  The ``unit width'' is the number of
+basic units per point.
+
+For instance, @code{groff}'s @code{lbp} device uses a @code{unitwidth}
+of@tie{}800.  In its Times roman font @samp{TR}, its @code{spacewidth}
+is@tie{}833; this is also the width of its comma, period, centered
+period, and mathematical asterisk, while its @samp{M} is 2963 basic
+units.  Thus, an @samp{M} on the @code{lbp} device is 2,963 basic units
+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,
@@ -17998,7 +18014,8 @@ The name of the font is@tie{}@var{f}.
 
 @item spacewidth @var{n}
 @kindex spacewidth
-The normal width of a space is@tie{}@var{n} basic units.
+The width of a normal, unadjusted space is @var{n}@tie{}basic units at
+a type size of @var{unit-width} points.
 @end table
 
 The above directives are mandatory; the remaining ones in the first
diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index 6706fcb..622f744 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -375,12 +375,6 @@ Set the scale factor for point sizes to one divided
 The default
 .RB is\~ 1 .
 .
-The arguments to the
-.B unitwidth
-and
-.B sizes
-directives are given in scaled points.
-.
 .
 .TP
 .BI styles\~ S1\~\c
@@ -502,6 +496,52 @@ file.
 .SH "Font description file format"
 .\" ====================================================================
 .
+On typesetting output devices,
+each font is typically available at multiple sizes.
+.
+While paper size measurements in the device description file are in
+absolute units,
+measurements applicable to fonts must be proportionate to the type size.
+.
+.I groff
+achieves this using the system pioneered by AT&T device-independent
+.IR troff ; \" AT&T
+one size of a font is chosen as a norm,
+and all other sizes are scaled linearly relative to that basis.
+.
+The \[lq]unit width\[rq] is the number of basic units per point.
+.
+.
+.P
+For instance,
+.IR groff 's
+.B lbp
+device uses a
+.B unitwidth
+of\~800.
+.
+In its Times roman font
+.RB (\[lq] TR \[rq]),
+its
+.B spacewidth
+is\~833;
+this is also the width of its comma,
+period,
+centered period,
+and mathematical asterisk,
+while its \[lq]M\[rq] is 2963 basic units.
+.
+Thus,
+an \[lq]M\[rq] on the
+.B lbp
+device is 2,963 basic units wide at a notional type size of 800\~points.
+.
+(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.)
+.
+.
+.P
 A font description file has two sections;
 empty lines are ignored in both.
 .
@@ -519,9 +559,11 @@ The name of the font
 .
 .TP
 .BI spacewidth\~  n
-The normal width of a space
-.RI is\~ n
-basic units.
+The width of a normal,
+unadjusted space is
+.IR n \~basic
+units at a type size of
+.IR unit-width \~points.
 .
 .
 .P