[groff] 21/30: [docs]: Revise discussion of spaces and motions.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit bf6ff8f2a57f6064ac1f0c9cb6144f247e3e7630
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Jun 15 02:51:55 2022 -0500

    [docs]: Revise discussion of spaces and motions.
    
    Draw a sharper distinction between "spaces", which are adjustable and
    discardable, and horizontal motions, which are not.
    
    * doc/groff.texi: Relocate presentation of `\~` escape sequence...
      (Page Motions): ...from here...
      (Manipulating Filling and Adjustment): ...to here, much earlier.
    
      (Page Motions): Recast descriptions of `\v`, `\h`, `\space`, `\|`,
      `\^`, `\0`.
    
    * man/groff.7.man:
    * man/groff_diff.7.man:
    * man/groff_font.5.man: Sync with updated descriptions above.
---
 doc/groff.texi       | 109 +++++++++++++++++++++++++++++----------------------
 man/groff.7.man      |  48 +++++++++++------------
 man/groff_diff.7.man |   6 ++-
 man/groff_font.5.man |  10 +++--
 4 files changed, 94 insertions(+), 79 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 924a4343..978bff5c 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -7699,6 +7699,22 @@ qux
 @endExample
 @endDefreq
 
+Sometimes you want to prevent a break within a phrase or between a
+quantity and its units.
+
+@Defesc {\\~, , , }
+@cindex unbreakable space (@code{\~})
+@cindex space, unbreakable (@code{\~})
+Insert an unbreakable space that is adjustable like an ordinary space.
+It is discarded from the end of an output line if a break is forced.
+
+@Example
+Set the output speed to\~1.
+There are 1,024\~bytes in 1\~KiB.
+J.\~F.\~Ossanna wrote the original CSTR\~#54.
+@endExample
+@endDefesc
+
 By default, GNU @code{troff} fills text and adjusts it to both margins.
 Filling can be disabled via the @code{nf} request and re-enabled with
 the @code{fi} request.
@@ -13346,17 +13362,18 @@ Several escape sequences enable fine control of 
movement about the page.
 @Defesc {\\v, @code{'}, expr, @code{'}}
 @cindex vertical motion (@code{\v})
 @cindex motion, vertical (@code{\v})
-Move vertically relative to the drawing position.@footnote{unless the
-boundary-relative motion operator @samp{|} is used---see @ref{Numeric
-Expressions})}  @var{expr} indicates the magnitude of motion: positive
-is downward and and negative upward.  The default scaling unit is
-@samp{v}.  Beware, however, that GNU @code{troff} continues text
-processing at the point where the motion ends, so you should always
-balance motions to avoid interference with text processing.
-
-@code{\v} doesn't trigger a trap.  This can be useful; for example,
-consider a page bottom trap macro that prints a marker in the margin to
-indicate continuation of a footnote or something similar.
+Vertically move the drawing position.  @var{expr} indicates the
+magnitude of motion: positive is downward and and negative upward.  The
+default scaling unit is @samp{v}.  The motion is relative to the current
+drawing position unless @var{expr} begins with the boundary-relative
+motion operator @samp{|}.  @xref{Numeric Expressions}.
+
+Text processing continues at the new drawing position; usually, vertical
+motions should be in balanced pairs to avoid a confusing page layout.
+
+@code{\v} will not spring a vertical position trap.  This can be useful;
+for example, consider a page bottom trap macro that prints a marker in
+the margin to indicate continuation of a footnote.  @xref{Traps}.
 @endDefesc
 
 A few escape sequences that produce vertical motion are unusual.  They
@@ -13384,12 +13401,12 @@ Let us see these escape sequences in use.
 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.  An unbreakable digit-width space 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
+In the foregoing we have paired @code{\u} and @code{\d} to typeset a
+superscript, and later a full em negative (``reverse'') motion to place
+a superscript above a subscript.  A numeral-width horizontal motion
+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
@@ -13401,14 +13418,11 @@ string definitions.
 @cindex space, horizontal (@code{\h})
 @cindex horizontal motion (@code{\h})
 @cindex motion, horizontal (@code{\h})
-Move horizontally relative to the drawing postition.@footnote{unless the
-boundary-relative motion operator @samp{|} is used---see @ref{Numeric
-Expressions})}  @var{expr} indicates the magnitude of motion: positive
-is rightward and negative leftward.  The default scaling unit is
-@samp{m}.
-
-This horizontal space is not discarded at the end of a line.  To insert
-discardable space of a certain length, use the @code{ss} request.
+Horizontally move the drawing position.  @var{expr} indicates the
+magnitude of motion: positive is rightward and negative leftward.  The
+default scaling unit is @samp{m}.  The motion is relative to the current
+drawing position unless @var{expr} begins with the boundary-relative
+motion operator @samp{|}.  @xref{Numeric Expressions}.
 @endDefesc
 
 The following string definition sets the @TeX{}
@@ -13423,43 +13437,44 @@ There are a number of special-case escape sequences 
for horizontal
 motion.
 
 @Defesc {\\@key{SP}, , , }
-@cindex space, unbreakable
-@cindex unbreakable space
+@cindex space, unbreakable and unadjustable (@code{\SP})
+@cindex unbreakable and unadjustable space (@code{\SP})
+@cindex unadjustable and unbreakable space (@code{\SP})
 @esindex \@slanted{space}
-An unbreakable, non-adjustable space.  (This is a backslash followed by
-a space.)  Usually you want one of the following escape sequences
-instead, often @code{\~}.
-@endDefesc
-
-@Defesc {\\~, , , }
-An unbreakable space that is adjustable like a normal inter-word space.
+Move right one word space.  (The input is a backslash followed by a
+space.)  This escape sequence can be thought of as a non-adjustable,
+unbreakable space.  Usually you want @code{\~} instead; see
+@ref{Manipulating Filling and Adjustment}.
 @endDefesc
 
-@cindex thin space
-@cindex space, thin
+@cindex thin space (@code{\|})
+@cindex space, thin (@code{\|})
 @Defesc {\\|, , , }
-An unbreakable one-sixth @dmn{em} (``thin'') space.  Ignored (rounded to
-zero width) on terminal output devices.  However, if there is a glyph
-defined in the current font with name @code{\|} (note the leading
-backslash), the width of this glyph is used instead (even on terminals).
+Move one-sixth @dmn{em} to the right on typesetting output devices.  If
+a glyph named @samp{\|} is defined in the current font, its width is
+used instead, even on terminal output devices.
 @endDefesc
 
-@cindex hair space
-@cindex space, hair
+@cindex hair space (@code{\^})
+@cindex space, hair (@code{\^})
 @Defesc {\\^, , , }
-An unbreakable one-twelfth @dmn{em} (``hair'') space.  Ignored (rounded
-to zero width) on terminal output devices.  However, if there is a glyph
-defined in the current font with name @code{\^} (note the leading
-backslash), the width of this glyph is used instead (even on terminals).
+Move one-twelfth @dmn{em} to the right on typesetting output devices.
+If a glyph named @samp{\^} is defined in the current font, its width is
+used instead, even on terminal output devices.
 @endDefesc
 
 @Defesc {\\0, , , }
 @cindex space, width of a digit (numeral) (@code{\0})
 @cindex digit-width space (@code{\0})
+@cindex figure space (@code{\0})
 @cindex numeral-width space (@code{\0})
-An unbreakable space the width of a numeral in the current font.
+Move right by the width of a numeral in the current font.
 @endDefesc
 
+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{'}}
 @DefregItemx {st}
 @DefregItemx {sb}
diff --git a/man/groff.7.man b/man/groff.7.man
index df85ce0d..92b48123 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3736,37 +3736,31 @@ read in copy mode,
 in a diversion.
 .
 .
-.\" ========= spacing [sic; \& and \) don't really space] =========
+.\" ========= spaces and fixed-width horizontal motions =========
 .
 .TP
-.ESC \& space
-Unbreakable,
-non-adjustable word space.
+.ESC \f[I]space
+Move right one word space.
 .
 .
 .TP
 .ESC \[ti]
-Unbreakable,
-adjustable space.
+Insert an unbreakable, adjustable space.
 .
 .
 .TP
 .ESC 0
-Unbreakable digit-width space.
+Move right by the width of a numeral in the current font.
 .
 .
 .TP
 .ESC |
-Unbreakable 1/6\~em (\[lq]thin\[rq]) space glyph;
-zero-width in
-.IR nroff .
+Move one-sixth em to the right on typesetters.
 .
 .
 .TP
 .ESC \[ha]
-Unbreakable 1/12\~em (\[lq]hair\[rq]) space glyph;
-zero-width in
-.IR nroff .
+Move one-twelfth em to the right on typesetters.
 .
 .
 .TP
@@ -3920,10 +3914,12 @@ implementations.
 .
 .TP
 .ESC d
-Move downward \[12]\~em
-(\[12]\~line in
-.I nroff
-contingent on device support).
+Move downward \[12]\~em on typesetters.
+.\" XXX: No current groff nroff-mode output driver supports half-line
+.\" motions.
+.\" (\[12]\~line in
+.\" .I nroff
+.\" contingent on device support).
 .
 .
 .TP
@@ -4018,7 +4014,7 @@ Interpolate format of register with arbitrarily long name
 .
 .TP
 .ESCq h N
-Move drawing postition horizontally by
+Horizontally move the drawing position by
 .IR N \~ems
 (or specified units);
 .B \[or]
@@ -4212,9 +4208,7 @@ adjust if applicable.
 .
 .TP
 .ESC r
-Move \[lq]in reverse\[rq] (upward) 1\~em
-(reverse linefeed in
-.IR nroff ).
+Move \[lq]in reverse\[rq] (upward) 1\~em.
 .
 .
 .TP
@@ -4301,15 +4295,17 @@ interpolate tab character.
 .
 .TP
 .ESC u
-Move upward \[12]\~em
-(\[12]\~line in
-.I nroff
-contingent on device support).
+Move upward \[12]\~em on typesetters.
+.\" XXX: No current groff nroff-mode output driver supports half-line
+.\" motions.
+.\" (\[12]\~line in
+.\" .I nroff
+.\" contingent on device support).
 .
 .
 .TP
 .ESCq v N
-Move drawing position vertically by
+Vertically move the drawing position by
 .IR N \~vees
 (or specified units);
 .B \[or]
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index d82d3c3e..862d3bf6 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1078,10 +1078,12 @@ and
 .MR groff_char @MAN7EXT@
 for a list of glyph name components used in composite glyph names.
 .
+.
 .TP
 .B \[rs]\[ti]
-This produces an unbreakable space that stretches like a normal
-inter-word space when a line is adjusted.
+Insert an unbreakable space that is adjustable like an ordinary space.
+.
+It is discarded from the end of an output line if a break is forced.
 .
 .
 .\" ====================================================================
diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index 250b3806..031132d7 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -754,14 +754,16 @@ The
 .RB \[lq] \[rs]\- \[rq]
 defines the minus sign glyph.
 .
+.\" TODO: Withdraw support for this.  No one seems to use it.
 Finally,
 .I name
-can be the unbreakable one-sixth and one-twelfth space escape
-sequences,
-\[rs]| and \[rs]\[ha]
+can be the horizontal motion escape sequences,
+.B \[rs]|
+and
+.B \[rs]\[ha]
 (\[lq]thin\[rq] and \[lq]hair\[rq] spaces,
 respectively),
-in which case only the width metric described below is interpreted;
+in which case only the width metric described below is applied;
 a font can thus customize the widths of these spaces.
 .\" XXX: For exhaustivity purposes...you can define "\whatever", which
 .\" has to be accessed with \C'\\whatever' or \[\\whatever], but the