[groff] 08/16: doc/groff.texi (Page Motions): Fix style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 6c12efe2707842fdd119f926deade6e9d43458fb
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Aug 21 22:45:44 2021 +1000

    doc/groff.texi (Page Motions): Fix style nits.
    
    * Remove break opportunities from long two-column macro example; the
      blank space inserted by TeX could be confusing and, currently, it fits
      on a page.
    * Add linking sentence between set up and usage of two-column macro
      example.
    * Use Texinfo @result command for output of two-column macro example.
    * Use "expr" instead of "e" for metasyntactic variable name.
    * Relocate example of TeX logo to immediately follow \h and \v escape
      sequence presentation.
    * Recast unbreakable space escape sequence descriptions to front their
      unbreakability instead of their width.
    * Document and describe the dummy environment used by the \w escape
      sequence, and add a concept index entry for it.  troff throws a
      diagnostic using this term, so we had best discuss it somewhere.
---
 doc/groff.texi | 93 +++++++++++++++++++++++++++-------------------------------
 1 file changed, 43 insertions(+), 50 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index b2ede97..87fa241 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -12606,8 +12606,6 @@ A simple implementation of a macro to set text in two 
columns follows.
 .nr column-gap 4m
 .nr bottom-margin 1m
 .
-@endExample
-@Example
 .de 2c
 .  br
 .  mk
@@ -12616,8 +12614,6 @@ A simple implementation of a macro to set text in two 
columns follows.
 .  nr right-side 0
 ..
 .
-@endExample
-@Example
 .de 2c-trap
 .  ie \\n[right-side] \@{\
 .    nr right-side 0
@@ -12634,6 +12630,9 @@ A simple implementation of a macro to set text in two 
columns follows.
 ..
 .
 @endExample
+
+Now let us apply our two-column macro.
+
 @Example
 .pl 1.5i
 .ll 4i
@@ -12645,34 +12644,29 @@ Starting here, text is typeset in two columns.
 Note that this implementation isn't robust
 and thus not suited for a real two-column
 macro.
-@endExample
-
-Result:
-
-@Example
-This is a small test that shows how the
-rt request works in combination with mk.
-
-Starting  here,    isn't    robust
-text is typeset    and   thus  not
-in two columns.    suited  for   a
-Note that  this    real two-column
-implementation     macro.
+    @result{} This is a small test that shows how the
+    @result{} rt request works in combination with mk.
+    @result{}
+    @result{} Starting  here,    isn't    robust
+    @result{} text is typeset    and   thus  not
+    @result{} in two columns.    suited  for   a
+    @result{} Note that  this    real two-column
+    @result{} implementation     macro.
 @endExample
 @endDefreq
 
-The following escapes give fine control of movements about the page.
+The following escapes give fine control of movement about the page.
 
-@Defesc {\\v, @code{'}, e, @code{'}}
+@Defesc {\\v, @code{'}, expr, @code{'}}
 @cindex vertical motion (@code{\v})
 @cindex motion, vertical (@code{\v})
 Move vertically; usually from the current location on the page (if no
-absolute position operator @samp{|} is used).  The argument@tie{}@var{e}
-specifies the distance to move; positive is downwards and negative
-upwards.  The default scaling indicator 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.
+absolute position operator @samp{|} is used).  The
+argument@tie{}@var{expr} specifies the distance to move; positive is
+downwards and negative upwards.  The default scaling indicator 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
@@ -12700,14 +12694,14 @@ Move upwards@tie{}.5@dmn{v}.
 Move down@tie{}.5@dmn{v}.
 @endDefesc
 
-@Defesc {\\h, @code{'}, e, @code{'}}
+@Defesc {\\h, @code{'}, expr, @code{'}}
 @cindex inserting horizontal space (@code{\h})
 @cindex horizontal space (@code{\h})
 @cindex space, horizontal (@code{\h})
 @cindex horizontal motion (@code{\h})
 @cindex motion, horizontal (@code{\h})
 Move horizontally; usually from the current location (if no absolute
-position operator @samp{|} is used).  The expression@tie{}@var{e}
+position operator @samp{|} is used).  The expression@tie{}@var{expr}
 indicates how far to move: positive is rightwards and negative
 leftwards.  The default scaling indicator for this escape is @samp{m}.
 
@@ -12715,6 +12709,14 @@ 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.
 @endDefesc
 
+The following string definition sets the @TeX{}
+logo.@footnote{@xref{Strings}, for an explanation of the trailing
+@samp{\"}.}
+
+@Example
+.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X\"
+@endExample
+
 There are a number of special-case escapes for horizontal motion.
 
 @Defesc {\\@key{SP}, , , }
@@ -12732,23 +12734,19 @@ An unbreakable space that is adjustable like a normal 
inter-word space.
 @cindex thin space
 @cindex space, thin
 @Defesc {\\|, , , }
-A one-sixth @dmn{em} unbreakable (``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).
+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).
 @endDefesc
 
 @cindex hair space
 @cindex space, hair
 @Defesc {\\^, , , }
-A one-twelfth @dmn{em} unbreakable (``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).
+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).
 @endDefesc
 
 @Defesc {\\0, , , }
@@ -12758,14 +12756,6 @@ instead (even on terminals).
 An unbreakable space the width of a numeral in the current font.
 @endDefesc
 
-The following string definition sets the @TeX{}
-logo.@footnote{@ref{Strings}, for an explanation of the trailing
-@samp{\"}.}
-
-@Example
-.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X\"
-@endExample
-
 @DefescList {\\w, @code{'}, text, @code{'}}
 @DefregItemx {st}
 @DefregItemx {sb}
@@ -12784,10 +12774,13 @@ The length of the string 'abc' is \w'abc'u.
     @result{} The length of the string 'abc' is 72u.
 @endExample
 
-Font changes may occur in @var{text}, which don't affect current
-settings.
+@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.
 
-After use, @code{\w} sets several registers:
+After use, @code{\w} sets several registers.
 
 @table @code
 @item st