[groff] 11/72: Document a CSTR #54 erratum re: \n(st and \n(sb.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit ff137021cbfb678cba95417e1160e46305824905
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Oct 18 16:40:15 2022 -0500

    Document a CSTR #54 erratum re: \n(st and \n(sb.
    
    * doc/groff.texi (Page Motions):
    * man/groff.7.man (Writable registers):
    * man/groff_diff.7.man (New registers): Do it.
    
    * PROBLEMS: Further clarify.  Note DWB and Heirloom behavior.
---
 ChangeLog            | 10 ++++++++++
 PROBLEMS             | 20 +++++++++++++++-----
 doc/groff.texi       | 45 +++++++++++++++++++++++++++------------------
 man/groff.7.man      | 24 ++++++++++++------------
 man/groff_diff.7.man | 26 +++++++++++++++++++++-----
 5 files changed, 85 insertions(+), 40 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 3cc93fff7..c66b6bce4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2022-10-18  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       Document a CSTR #54 erratum regarding \n(st and \n(sb.
+
+       * doc/groff.texi (Page Motions):
+       * man/groff.7.man (Writable registers):
+       * man/groff_diff.7.man (New registers): Do it.
+
+       * PROBLEMS: Further clarify.  Note DWB and Heirloom behavior.
+
 2022-10-18  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * src/preproc/eqn/main.cpp (read_line): Fix switched test
diff --git a/PROBLEMS b/PROBLEMS
index 13ce8be7e..697c3c486 100644
--- a/PROBLEMS
+++ b/PROBLEMS
@@ -229,11 +229,21 @@ You need version 1.42 or newer.
   them to the height and depth of its argument, but the registers
   always seem to be 0.
 
-\n(st and \n(sb aren't supposed to give the height and depth of the
-string rather they give the minimum and maximum vertical displacement
-of the baseline.  For example for \v'2u'\v'-3u', \n(st is 1 and \n(sb
-is -2.  The height and depth of the string is available in the \n[rst]
-and \n[rsb] registers: these are groff extensions.
+\n(st and \n(sb don't give the height and depth of the argument to \w,
+but the maximum vertical displacements of the text baseline above
+(\n(st) and below (\n(sb) its original position.  Consider an example
+where no text is formatted, but small vertical motions are used.
+
+  \w"\v'-1u'\v'3u'"
+  .tm st=\n(st, sb=\n(sb
+    st=1, sb=-2
+
+Observe that the sign convention of these registers is opposite that of
+relative vertical motion.  (This is how Documenter's Workbench troff
+and Heirloom Doctools troff work as well.)
+
+The height and depth of formatted text in the \w argument are available
+in the \n[rst] and \n[rsb] registers; these are groff extensions.
 
 ----------------------------------------------------------------------
 
diff --git a/doc/groff.texi b/doc/groff.texi
index 63214bb58..004b87dcc 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -13685,7 +13685,7 @@ Horizontal motions are not discarded at the end of an 
output line as
 word and supplementary inter-sentence spaces are.  @xref{Manipulating
 Filling and Adjustment}.
 
-@DefescList {\\w, @code{'}, text, @code{'}}
+@DefescList {\\w, @code{'}, anything, @code{'}}
 @DefregItemx {st}
 @DefregItemx {sb}
 @DefregItemx {rst}
@@ -13694,9 +13694,9 @@ Filling and Adjustment}.
 @DefregItemx {ssc}
 @DefregListEndx {skw}
 @cindex width escape (@code{\w})
-Interpolate the width of the specified @var{text} in basic units.  This
-allows horizontal movement based on the width of some arbitrary text
-(e.g., given as an argument to a macro).
+Interpolate the width of @var{anything} in basic units.  This escape
+sequence allows several properties of formatted output to be measured
+without writing it out.
 
 @Example
 The length of the string 'abc' is \w'abc'u.
@@ -13705,39 +13705,48 @@ The length of the string 'abc' is \w'abc'u.
 
 @cindex dummy environment, used by @code{\w} escape sequence
 @cindex environment, dummy, used by @code{\w} escape sequence
-The @var{text} argument to @code{\w} is processed in a dummy
-environment; font changes may occur within it without any affect on the
-surrounding output.
+@var{anything} is processed in a dummy environment:@: this means that
+font and type size changes, for example, may occur within it without
+affecting subsequent output.
 
-After use, @code{\w} sets several registers.
+@need 500
+After each use, @code{\w} sets several registers.
 
+@cindex CSTR@tie{}#54 errata
+@cindex CSTR@tie{}#54 erratum, @code{sb} register
+@cindex CSTR@tie{}#54 erratum, @code{st} register
 @table @code
 @item st
 @itemx sb
-The highest and lowest point of the baseline, respectively, in
-@var{text}.
+The maximum vertical displacements of the text baseline above and below,
+respectively.  The sign convention is opposite that of relative vertical
+motions; that is, depth below the (original) baseline is negative.
+These registers are incorrectly documented in the @acronym{AT&T}
+@code{troff} manual as ``the highest and lowest extent of [the argument
+to @code{\w}] relative to the baseline''.
 
 @item rst
 @itemx rsb
-Like the @code{st} and @code{sb} registers, but takes account of the
-heights and depths of glyphs.  In other words, this gives the highest
-and lowest point of @var{text}.  Values below the baseline are negative.
+Like @code{st} and @code{sb}, but taking account of the heights and
+depths of glyphs.  In other words, these registers store the highest and
+lowest vertical positions attained by @var{anything}, doing what
+@acronym{AT&T} @code{troff} documented @code{st} and @code{sb} as doing.
 
 @item ct
-Defines the kinds of glyphs occurring in @var{text}:
+Characterizes the geometry of glyphs occurring in @var{anything}.
 
 @table @asis
 @item 0
-only short glyphs, no descenders or tall glyphs.
+only short glyphs, no descenders or tall glyphs
 
 @item 1
-at least one descender.
+at least one descender
 
 @item 2
-at least one tall glyph.
+at least one tall glyph
 
 @item 3
-at least one each of a descender and a tall glyph.
+at least one each of a descender and a tall glyph
 @end table
 
 @item ssc
diff --git a/man/groff.7.man b/man/groff.7.man
index 9bd775e11..dc6096707 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -5795,21 +5795,21 @@ or
 .
 .TPx
 .REG rsb
-Like register
-.BR sb ,
-but takes account of the heights and depths of glyphs.
+As
+.register sb ,
+adding maximum glyph height to measurement.
 .
 .TPx
 .REG rst
-Like register
-.BR st ,
-but takes account of the heights and depths of glyphs.
+As
+.register st ,
+adding maximum glyph depth to measurement.
 .
 .TPx
 .REG sb
-Depth of string below baseline
-(generated by width function
-.esc w ).
+Maximum displacement of text baseline below its original position
+in the argument to
+.esc w .
 .
 .TPx
 .REG seconds
@@ -5847,9 +5847,9 @@ function
 .
 .TPx
 .REG st
-Height of string above baseline
-(generated by width function
-.esc w ).
+Maximum displacement of text baseline above its original position
+in the argument to
+.esc w .
 .
 .TPx
 .REG systat
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 8cc248e3c..fe4f1d50a 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -4240,20 +4240,36 @@ These four read/\:write registers are set by the
 request and contain the bounding box values (in PostScript units) of a
 given PostScript image.
 .
+.
 .P
 The following read/\:write registers are set by the
 .B \[rs]w
-escape sequence:
+escape sequence.
+.
 .
 .TP
 .B \[rs]n[rst]
 .TQ
 .B \[rs]n[rsb]
-Like the
-.B st
+Like
+.B \[rs]n[st]
 and
-.B sb
-registers, but take account of the heights and depths of glyphs.
+.BR \[rs]n[sb] ,
+but taking account of the heights and depths of glyphs.
+.
+In other words,
+these registers store the highest and lowest vertical positions attained
+by the argument formatted by the
+.B \[rs]w
+escape sequence,
+doing what AT&T
+.I troff \" AT&T
+documented
+.B \[rs]n[st]
+and
+.B \[rs]n[sb]
+as doing.
+.
 .
 .TP
 .B \[rs]n[ssc]