[groff] 07/25: [docs]: Tweak discussions of `\h` and `\v`.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 393816786279c11ac52512a1ec51686bd73ebbf7
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Mar 29 00:04:39 2022 +1100

    [docs]: Tweak discussions of `\h` and `\v`.
    
    * (groff(7)): Fix error: the default scaling unit for `\h` is ems, not
      ens.  Problem introduced by me in 6527dca9, 22 August.  Our Texinfo
      manual was out of sync (and correct).
    * (groff(7)): Indicate direction of positive movements.
    * Migrate terminology: "scaling indicator" -> "scaling unit"; "current
      location" -> "drawing position"; "absolute position operator" ->
      "boundary-relative motion operator"; "escape" -> "escape sequence".
    * Parallelize wording as much as possible when describing `\h` and `\v`.
    * Add comma after lengthy dependent clause.
---
 doc/groff.texi  | 19 ++++++++++---------
 man/groff.7.man | 22 +++++++++++++---------
 2 files changed, 23 insertions(+), 18 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index fd70507e..437a5955 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -13227,10 +13227,10 @@ 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; usually from the current location on the page (if no
-absolute position operator @samp{|} is used).  The
-argument@tie{}@var{expr} specifies the distance to move; positive is
-downward and negative upward.  The default scaling indicator is
+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.
@@ -13282,13 +13282,14 @@ string definitions.
 @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{expr}
-indicates how far to move: positive is rightward and negative leftward.
-The default scaling indicator for this escape is @samp{m}.
+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.
+discardable space of a certain length, use the @code{ss} request.
 @endDefesc
 
 The following string definition sets the @TeX{}
diff --git a/man/groff.7.man b/man/groff.7.man
index 983b986b..1349ad90 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -4007,11 +4007,13 @@ Interpolate format of register with arbitrarily long 
name
 .
 .TP
 .ESCq h N
-Horizontally move
-.IR N \~ens
-(or specified units)
-right
-(left if negative).
+Move drawing postition horizontally by
+.IR N \~ems
+(or specified units);
+.BR |
+may be used.
+.
+Positive motion is rightward.
 .
 .
 .TP
@@ -4293,11 +4295,13 @@ contingent on device support).
 .
 .TP
 .ESCq v N
-Vertically move
+Move drawing position vertically by
 .IR N \~vees
-(or specified units)
-down
-(up if negative).
+(or specified units);
+.BR |
+may be used.
+.
+Positive motion is downward.
 .
 .
 .TP