[groff] 07/09: [docs]: Fix unit error in `\[dru]` descriptions.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit c709a70a6b2bb2bbeb7991c4e8dff7cd7e7c9031
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Nov 23 23:57:51 2021 +1100

    [docs]: Fix unit error in `\[dru]` descriptions.
    
    * doc/groff.texi (Page Motions): Fix error: the `\r`, `\u`, and `\d`
      escape sequences move in ems, not vees, despite being vertical
      motions.  Add discussion and example.
    
    Problem dates back to import of Texinfo manual, commit af2d6f8e (26
    December 1999).
    
    Also reverts commit c6a01c81 by me, 20 May 2021.
---
 ChangeLog       | 14 ++++++--------
 doc/groff.texi  | 55 +++++++++++++++++++++++++++++++++++--------------------
 man/groff.7.man | 12 +++++++-----
 3 files changed, 48 insertions(+), 33 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 3376271..9f361ad 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2021-11-23  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * doc/groff.texi (Page Motions): Fix error: the `\r`, `\u`, and
+       `\d` escape sequences move in ems, not vees, despite being
+       vertical motions.  Add discussion and example.
+
 2021-11-20  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * src/include/error.h: Drop `extern` storage class from
@@ -4857,14 +4863,6 @@
 
 2021-05-20  G. Branden Robinson <g.branden.robinson@gmail.com>
 
-       * man/groff.7.man (Escape Sequences/Escape short reference): Fix
-       errors in descriptions of \d, \r, \u escapes; they move in vees,
-       not ems.
-
-       Fixes <https://savannah.gnu.org/bugs/?60602>.
-
-2021-05-20  G. Branden Robinson <g.branden.robinson@gmail.com>
-
        * tmac/an-old.tmac (an-header): Fix missing brace escape.
 
 2021-05-20  G. Branden Robinson <g.branden.robinson@gmail.com>
diff --git a/doc/groff.texi b/doc/groff.texi
index c879bd8..e9d5834 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -12712,7 +12712,8 @@ sequence for the minus sign glyph.
 @cindex motions, page
 
 @xref{Manipulating Spacing}, for a discussion of the most commonly used
-request for vertical motion, @code{sp}, which spaces down by one line.
+request for vertical motion, @code{sp}, which spaces downward by one
+vee.
 
 @DefreqList {mk, [@Var{reg}]}
 @DefreqListEndx {rt, [@Var{dist}]}
@@ -12768,7 +12769,6 @@ A simple implementation of a macro to set text in two 
columns follows.
 .    rt
 .  \@}
 ..
-.
 @endExample
 
 Now let us apply our two-column macro.
@@ -12795,7 +12795,7 @@ macro.
 @endExample
 @endDefreq
 
-The following escapes give fine control of movement about the page.
+Several escape sequences enable fine control of movement about the page.
 
 @Defesc {\\v, @code{'}, expr, @code{'}}
 @cindex vertical motion (@code{\v})
@@ -12813,26 +12813,41 @@ consider a page bottom trap macro that prints a 
marker in the margin to
 indicate continuation of a footnote or something similar.
 @endDefesc
 
-@cindex CSTR@tie{}#54 errata
-There are some special-case escapes for vertical motion by lines or
-half-lines.  They were incorrectly documented in the @acronym{AT&T}
-@code{troff} manual as causing vertical motions in @samp{m} units,
-rather than @samp{v}.
-
-@cindex CSTR@tie{}#54 erratum, @code{\r} escape
-@Defesc {\\r, , , }
-Move upward@tie{}1@dmn{v}.
+A few escape sequences that produce vertical motion are unusual.  They
+are thought to originate early in AT&T @code{nroff} history to achieve
+super- and sub-scripting by half-line motions on line printers and
+teletypewriters before the phototypesetter made more precise positioning
+available.  They are reckoned in ems---not vees---to maintain continuity
+with their original purpose of moving relative to the size of the type
+rather than the distance between text baselines (vees).@footnote{At the
+@code{grops} defaults of 10-point type on 12-point vertical spacing, the
+difference between half a vee and half an em can be subtle: large
+spacings like @samp{.vs 3v} make it obvious.}
+
+@DefescList {\\r, , , }
+@DefescItemx {\\u, , , }
+@DefescListEndx {\\d, , , }
+Move upward@tie{}1@dmn{m}, upward@tie{}.5@dmn{m}, and
+downward@tie{}.5@dmn{m}, respectively.
 @endDefesc
 
-@cindex CSTR@tie{}#54 erratum, @code{\u} escape
-@Defesc {\\u, , , }
-Move upward@tie{}.5@dmn{v}.
-@endDefesc
+@noindent
+Let us see these escape sequences in use.
 
-@cindex CSTR@tie{}#54 erratum, @code{\d} escape
-@Defesc {\\d, , , }
-Move down@tie{}.5@dmn{v}.
-@endDefesc
+@Example
+Obtain 100 cm\u3\d of \ka\d\092\h'|\nau'\r233\dU.
+@endExample
+
+In the foregoing we have paired @code{\u} and @code{\d} to place a
+subscript, then used a full em negative (``reverse'') motion to place a
+superscript above a subscript.  A digit-width unbreakable escape
+sequence aligns the proton and nucleon numbers, while @code{\k} marks a
+horizontal position to which @code{\h} returns so that we could stack
+them.  (We shall discuss these horizontal motion escape sequences
+presently.)  In serious applications, we often want to alter the type
+size of the -scripts and to fine-tune the vertical motions, as the
+@code{groff} @file{ms} package does with its super- and subscripting
+string definitions.
 
 @Defesc {\\h, @code{'}, expr, @code{'}}
 @cindex inserting horizontal space (@code{\h})
diff --git a/man/groff.7.man b/man/groff.7.man
index e9d5019..70d5d2b 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3873,9 +3873,10 @@ implementations.
 .
 .TP
 .ESC d
-Move downward \[12]\~vee
+Move downward \[12]\~em
 (\[12]\~line in
-.IR nroff ).
+.I nroff
+contingent on device support).
 .
 .
 .TP
@@ -4159,7 +4160,7 @@ adjust if applicable.
 .
 .TP
 .ESC r
-Move \[lq]in reverse\[rq] (upward) 1\~vee
+Move \[lq]in reverse\[rq] (upward) 1\~em
 (reverse linefeed in
 .IR nroff ).
 .
@@ -4248,9 +4249,10 @@ interpolate tab character.
 .
 .TP
 .ESC u
-Move upward \[12]\~vee
+Move upward \[12]\~em
 (\[12]\~line in
-.IR nroff ).
+.I nroff
+contingent on device support).
 .
 .
 .TP