gbranden pushed a commit to branch master
in repository groff.
commit be64094237d6bed923666ca89e934aad446e2686
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sat Mar 29 23:30:24 2025 -0500
[doc,man]: Fix botched description of "unitwidth".
I had made a hash of this exposition, replacing a different hash that
came before, and which even Kernighan did not illuminate clearly in AT&T
troff documentation--at least not for me.
The most important fact--either omitted, contradicted, or woefully
underemphasized in earlier device-independent troff documentation--is
that the "unit width" is _not_ "basic units per point". It _could_ be,
but need not be, otherwise the unit width would have to be coupled to
the device resolution, which is in basic units per _inch_, and a point
is 1/72 inch.
But no such constraint exists, and none is necessary. I explain why.
Everybody should learn at least unit analysis, and ideally its more
abstract cousin, dimensional analysis. They prevent errors like these.
---
doc/groff.texi.in | 71 ++++++++++++++++++++++++++++++++++++++++------------
man/groff_font.5.man | 63 +++++++++++++++++++++++++++-------------------
2 files changed, 92 insertions(+), 42 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 215362416..5edaaf019 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -19944,8 +19944,8 @@ directive.
@item unitwidth @var{n}
@kindex unitwidth
-Quantities in the font description files are in basic units for fonts
-whose type size is @var{n}@tie{}scaled points.
+Arbitary basis with respect to which font metrics are proportionally
+scaled when rendering glyphs at a type size of one point.
@item unscaled_charwidths
@kindex unscaled_charwidths
@@ -20001,20 +20001,59 @@ information about the device.
On typesetting output devices, each font is typically available at
multiple sizes. While paper measurements in the device description file
are in absolute units, measurements applicable to fonts must be
-proportional to the type size. @code{groff} achieves this using the
-precedent set by @acronym{AT&T} device-independent @code{troff}: one
-font size is chosen as a norm, and all others are scaled linearly
-relative to that basis. The ``unit width'' is the number of basic units
-per point when the font is rendered at this nominal size.
-
-For instance, @code{groff}'s @code{lbp} device uses a @code{unitwidth}
-of@tie{}800. Its Times roman font @samp{TR} has a @code{spacewidth}
-of@tie{}833; this is also the width of its comma, period, centered
-period, and mathematical asterisk, while its @samp{M} is 2,963 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.}
+proportional to the type size.
+The font's
+@slanted{unit width}
+establishes a numerical basis
+that permits all of its metrics to be expressed as integers
+if rendered at one point.
+When the formatter configures a type size,
+it scales the metrics linearly relative to that basis.
+The unit width has no inherent relationship to the device resolution;
+all it does is provide a basis for the magnitudes of the font metrics.
+The same division procedure applies to all font metrics.
+One observes that whatever unit might select for the unit width,
+the division operation cancels them out,
+leaving a dimensionless quantity.
+
+For instance,
+@code{groff}'s
+@code{lbp}
+device uses a
+@code{unitwidth}
+directive with an argument
+of@tie{}800.
+Its Times roman font
+@samp{TR}
+has a
+@code{spacewidth}
+of@tie{}833;
+this is also the width of its comma,
+period,
+centered period,
+and mathematical asterisk,
+while its
+@samp{M}
+has a width of 2,963.
+Thus,
+an
+@samp{M}
+on the
+@code{lbp}
+device is 2,963 � 800 times the unit width
+(approximately 3.7).
+At a type size of 10 points,
+a Times roman
+@samp{M}
+is therefore 37 units wide.
+
+@Example
+$ groff -T lbp
+.ps 10
+.nr Mw \w'M'
+.tm width of 'M' at 10 points=\n(Mw
+ @result{} width of 'M' at 10 points=37
+@endExample
A font description file has two sections. The first is a sequence of
directives, and is parsed similarly to the @file{DESC} file described
diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index 9374b7533..5dde0142f 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -458,10 +458,8 @@ output devices use this directive.
.
.TP
.BI unitwidth\~ n
-Quantities in the font description files are in basic units for fonts
-whose type size is
-.IR n \~scaled
-points.
+Arbitrary basis with respect to which font metrics are proportionally
+scaled when rendering glyphs at a type size of one point.
.
.
.TP
@@ -543,43 +541,56 @@ While paper measurements in the device description file
are in absolute
units,
measurements applicable to fonts must be proportional to the type size.
.
-.I groff
-achieves this using the precedent set by AT&T device-independent
-.IR troff : \" AT&T
-one font size is chosen as a norm,
-and all others are scaled linearly relative to that basis.
+The font's
+.I "unit width"
+establishes a numerical basis
+that permits all of its metrics to be expressed as integers
+if rendered at one point.
+.
+When the formatter configures a type size,
+it scales the metrics linearly relative to that basis.
+.
+The unit width has no inherent relationship to the device resolution;
+all it does is provide a basis for the magnitudes of the font metrics.
+.
+The same division procedure applies to all font metrics.
.
-The \[lq]unit width\[rq] is the number of basic units per point when the
-font is rendered at this nominal size.
+One observes that whatever unit might select for the unit width,
+the division operation cancels them out,
+leaving a dimensionless quantity.
.
.
.P
For instance,
-.IR groff 's
+.BR groff 's
.B lbp
device uses a
-.B unitwidth
-of\~800.
-.
+.B \%unitwidth
+directive with an argument
+.RB of\~ 800 .
Its Times roman font
-.RB (\[lq] TR \[rq])
+.B TR
has a
-.B spacewidth
-of\~833;
+.B \%spacewidth
+.RB of\~ 833 ;
this is also the width of its comma,
period,
centered period,
and mathematical asterisk,
-while its \[lq]M\[rq] is 2,963 basic units.
-.
+while its
+.RB \[lq] M \[rq]
+has a width of 2,963.
Thus,
-an \[lq]M\[rq] on the
+an
+.RB \[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.)
+device is 2,963 \[tdi] 800 times the unit width
+(approximately 3.7).
+At a type size of 10 points,
+a Times roman
+.RB \[lq] M \[rq]
+is therefore 37 units wide.
.
.
.P
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
