gbranden pushed a commit to branch master
in repository groff.
commit db8cc6c230099dfd676909320e00401ba2a5940e
Author: G. Branden Robinson <g.branden.robin...@gmail.com>
AuthorDate: Sat Jul 12 09:53:37 2025 -0500
doc/*,man/*: Impose terminological reform.
For many years our documentation has cautioned the reader: "Do not
confuse the 's' and 'z' scaling units."
Perhaps that admonition was thought necessarily because our own
presentation of the two units has been confusing!
"Scaled points", which I'd like to rename to "subdivided points" after
groff 1.24, is always an integral value, as the relatively new examples
illustrate (behavior is unchanged going back many years, exposing the
misleading wording). They thus correspond to the 's' unit.
However, adopting that association leaves us with a terminological
gap--what do we call the 'z' scaling unit?
My feeble solution is to call it a "typographical point", to distinguish
it from the scaling unit "p", which traditionally admitted only integral
measurements.
---
doc/groff.texi.in | 87 +++++++++++++++++++++++++++++++++++++++++-----------
man/groff.7.man | 14 ++++++---
man/groff_diff.7.man | 54 ++++++++++++++------------------
3 files changed, 102 insertions(+), 53 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 8cbbe7108..c1c09dfcc 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -6356,6 +6356,10 @@ Centimeter; a centimeter is about 0.3937@tie{}inches.
@cindex scaling unit @code{p}
Point; a typesetter's unit used for measuring type size.
There are 72@tie{}points to an inch.
+Also called an ``integral'' point because historical
+@code{roff}
+systems used only integral values of
+@code{p}.
@item P
@cindex pica scaling unit (@code{P})
@@ -6366,8 +6370,24 @@ Pica; another typesetter's unit. There are 6@tie{}picas
to an inch and
12@tie{}points to a pica.
@item s
-@itemx z
-@xref{Using Fractional Type Sizes}, for a discussion of these units.
+@cindex scaled point scaling unit (@code{s})
+@cindex point, scaled, scaling unit (@code{s})
+@cindex @code{s} scaling unit
+@cindex unit, scaling, @code{s}
+@cindex scaling unit @code{s}
+Scaled point; see @ref{Using Fractional Type Sizes}.
+
+@item z
+@cindex typographical point scaling unit (@code{z})
+@cindex point, typographical, scaling unit (@code{z})
+@cindex @code{z} scaling unit
+@cindex unit, scaling, @code{z}
+@cindex scaling unit @code{z}
+Typographical point;
+like
+@code{p},
+but permits non-integral quantities.
+@c TODO: Make "p" truncate to integer like AT&T if -C?
@item f
GNU @code{troff} defines this unit to scale decimal fractions in the
@@ -13002,9 +13022,13 @@ to support, for instance, ten and a half-point type.
In GNU
subdivides a point into ``scaled points''. A type size expressed in
scaled points can thus represent a non-integral size in points.
+@cindex scaled point scaling unit (@code{s})
+@cindex point, scaled, scaling unit (@code{s})
@cindex @code{s} scaling unit
@cindex unit, scaling, @code{s}
@cindex scaling unit @code{s}
+@cindex typographical point scaling unit (@code{z})
+@cindex point, typographical, scaling unit (@code{z})
@cindex @code{z} scaling unit
@cindex unit, scaling, @code{z}
@cindex scaling unit @code{z}
@@ -13013,17 +13037,45 @@ scaled points can thus represent a non-integral size
in points.
@cindex @code{tkf} request, with fractional type sizes
@cindex @code{\H}, with fractional type sizes
@cindex @code{\s}, with fractional type sizes
-A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points, where
-@var{sizescale} is specified in the device description file @file{DESC},
-and defaults to@tie{}1.@footnote{@xref{Device and Font Description
-Files}.} Requests and escape sequences in GNU @code{troff} interpret
-arguments that represent a type size in scaled points, which the
-formatter multiplies by @var{sizescale} and converts to an integer.
-Arguments treated in this way comprise those to the escape sequences
-@code{\H} and @code{\s}, to the request @code{ps}, the third argument to
-the @code{cs} request, and the second and fourth arguments to the
-@code{tkf} request. Scaled points may be specified explicitly with the
-@code{z} scaling unit.
+A
+@dfn{scaled point},
+scaling unit
+@code{s},
+is equal to
+@math{1/@var{sizescale}}
+points,
+where the device description file
+@file{DESC}
+specifies
+@var{sizescale}
+and otherwise defaults to@tie{}1.@footnote{@xref{Device and Font
+Description Files}.}
+Requests and escape sequences in GNU
+@command{troff}
+interpret arguments that represent a type size in typographical points,
+which the formatter multiplies by
+@var{sizescale}
+and converts to an integer.
+The scaling unit
+@code{z}
+explicitly specifies these typographical points of potentially
+non-integral measure.
+Arguments GNU
+@command{troff} @c GNU
+interprets in
+@code{z}
+units by default comprise those to the escape sequences
+@code{\H}
+and
+@code{\s},
+to the request
+@code{ps},
+the third argument to the
+@code{cs}
+request,
+and the second and fourth arguments to the
+@code{tkf}
+request.
For example, if @var{sizescale} is@tie{}1000, then a scaled point is one
thousandth of a point. The request @samp{.ps 10.5} is synonymous with
@@ -13033,13 +13085,12 @@ thousandth of a point. The request @samp{.ps 10.5}
is synonymous with
@Defreg {.ps}
This read-only register interpolates the type size in scaled points.
+@samp{\n[.ps]s}
+is equal to
+@samp{1m}
+by definition.
@endDefreg
-Another GNU @code{troff} scaling unit, @samp{s}, multiplies by the
-number of basic units in a scaled point. Thus, @samp{\n[.ps]s} is equal
-to @samp{1m} by definition. Do not confuse the @samp{s} and @samp{z}
-scaling units.
-
@Example
.tm device=\*[.T]
.tm A: .s=\n[.s]z, .ps=\n[.ps]s
diff --git a/man/groff.7.man b/man/groff.7.man
index 747c706ac..abce9eee4 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -895,6 +895,10 @@ Point;
a typesetter's unit used for measuring type size.
.
There are 72\~points to an inch.
+Also called an \[lq]integral\[rq] point because historical
+.I roff
+systems used only integral values of
+.BR p .
.
.TP
.B P
@@ -905,13 +909,15 @@ There are 6\~picas to an inch and 12\~points to a pica.
.
.TP
.B z
-Scaled points.
+Typographical point;
+like
+.BR p ,
+but permits non-integral quantities.
+.\" TODO: Make "p" truncate to integer like AT&T if -C?
.
.TP
.B s
-The device's \[lq]sizescale\[rq] units;
-see
-.MR groff_font @MAN5EXT@ .
+Scaled point.
.
.TP
.B f
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 6aa74fd4d..da04d4255 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -379,26 +379,37 @@ size in points.
.
.P
A
-.I scaled point
+.I "scaled point,"
+scaling unit
+.BR s ,
is equal to
.RI 1/ sizescale
points,
-where
+where the device description file,
+.I DESC
+specifies
.I sizescale
-is specified in the device description file,
-.IR DESC ,
-and defaults to\~1;
+and otherwise defaults to\~1;
see
.MR groff_font @MAN5EXT@ .
.
Requests and escape sequences in GNU
.I troff \" GNU
-interpret arguments that represent a type size in points,
+interpret arguments that represent a type size in typographical points,
which the formatter multiplies by
.I sizescale
and converts to an integer.
.
-Arguments treated in this way comprise those to the escape sequences
+The scaling unit
+.B z
+explicitly specifies these typographical points of potentially
+non-integral measure.
+.
+Arguments GNU
+.I troff \" GNU
+interprets in
+.B z
+units by default comprise those to the escape sequences
.B \[rs]H
and
.BR \[rs]s ,
@@ -411,10 +422,6 @@ and the second and fourth arguments to the
.B tkf
request.
.
-Scaled points may be specified explicitly with the
-.B z
-scaling unit.
-.
In GNU
.IR troff , \" GNU
the register
@@ -425,6 +432,11 @@ The register
.B \[rs]n[.ps]
interpolates the type size in scaled points.
.
+.RB \[lq] \[rs]n[.ps] \[rq]
+is equal to
+.RB \[lq] 1m \[rq]
+by definition.
+.
.
.P
For example,
@@ -441,26 +453,6 @@ both set the type size to 10,500\~scaled points,
or 10.5\~points.
.
.
-.br
-.ne 2v
-.P
-Another new scaling unit,
-.RB \[lq] s \[rq],
-multiplies by the number of basic units in a scaled point.
-.
-Thus,
-.RB \[lq]\^ \[rs]n[.ps]s \[rq]
-is equal to
-.RB \[lq] 1m \[rq]
-by definition.
-.
-Do not confuse the
-.RB \[lq] s \[rq]
-and
-.RB \[lq] z \[rq]
-scaling units.
-.
-.
.P
It makes no sense to use the
.RB \[lq] z \[rq]\~scaling
_______________________________________________
groff-commit mailing list
groff-commit@gnu.org
https://lists.gnu.org/mailman/listinfo/groff-commit
