[groff] 14/26: [docs]: Update discussion of `sp` request.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit f7bbcd8fae43c41bf495697f056eb02bd4b9aa8e
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Nov 14 01:59:21 2021 +1100

    [docs]: Update discussion of `sp` request.
    
    * Explicitly refer to the "drawing position".  I anticipate using this
      term much more.
    * Document the fact that the argument is ignored in a diversion.  (You
      can have any vector of vertical space you like, as long as it's +1v.)
    * Move concept index entries to precede the beginning of the relevant
      discussion.
    * Use Texinfo @result command idiomatically, to present example output.
    * Tighten and clarify--shrink and grow.
---
 doc/groff.texi  | 56 +++++++++++++++++++++++++-------------------------------
 man/groff.7.man | 28 +++++++++++++++++++++++-----
 2 files changed, 48 insertions(+), 36 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 40ef73b..f70f721 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -8008,17 +8008,16 @@ The hyphenation space adjustment threshold is available 
in the
 @cindex spacing, manipulating
 
 @Defreq {sp, [@Var{distance}]}
-Space downwards @var{distance}.  With no argument it advances
-1@tie{}line.  A negative argument causes @code{gtroff} to move up the
-page the specified distance.  If the argument is preceded by a @samp{|}
-then @code{gtroff} moves that distance from the top of the page.  This
-request causes a line break, and that adds the current line spacing to
-the space you have just specified.  The default scaling indicator is
-@samp{v}.
+Space downwards by @var{distance}.  With no argument, the drawing
+position is advanced downward by one vee.  Inside a diversion, any
+@var{distance} argument is ignored.  Otherwise, a negative argument
+moves the drawing position up the page.   If the argument is preceded by
+the @samp{|} operator, GNU @code{troff} moves that distance from the top
+of the page, plus the current line spacing.  The default scaling
+indicator is @samp{v}.  This request causes a break.
 
-For convenience you may wish to use the following macros to set the
-height of the next line at a given distance from the top or the bottom
-of the page:
+You may wish to use the following macros to set the baseline of the next
+output text at a given distance from the top or the bottom of the page.
 
 @Example
 .de y-from-top-down
@@ -8031,11 +8030,15 @@ of the page:
 @endExample
 
 @noindent
-A call to @samp{.y-from-bot-up 10c} means that the bottom of the next
-line will be at 10@tie{}cm from the paper edge at the bottom.
+A call to @samp{.y-from-bot-up 10c} means that the next text baseline
+will be at 10@tie{}cm from the bottom edge of the paper.
 
-If a vertical trap is sprung during execution of @code{sp}, the amount
-of vertical space after the trap is discarded.  For example, this
+@cindex @code{sp} request, and traps
+@cindex discarded space in traps
+@cindex space, discarded, in traps
+@cindex traps, and discarded space
+If a vertical position trap is sprung during execution of @code{sp}, the
+amount of vertical space after the trap is discarded.
 
 @Example
 .de xxx
@@ -8049,28 +8052,19 @@ foo
 bar
 .sp 50
 baz
+    @result{} foo
+    @result{}
+    @result{}
+    @result{} bar
+    @result{}
+    @result{} baz
 @endExample
 
-@noindent
-results in
-
-@Example
-foo
-
-
-bar
-
-baz
-@endExample
-
-@cindex @code{sp} request, and traps
-@cindex discarded space in traps
-@cindex space, discarded, in traps
-@cindex traps, and discarded space
 The amount of discarded space is available in the register
 @code{.trunc}.
 
-To protect @code{sp} against vertical traps, use the @code{vpt} request:
+To protect @code{sp} against vertical position traps, use the @code{vpt}
+request to disable them.
 
 @Example
 .vpt 0
diff --git a/man/groff.7.man b/man/groff.7.man
index 273eac4..1ada6ce 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2977,17 +2977,35 @@ does not exist.
 .
 .TPx
 .REQ .sp
-Skip one line vertically.
+Move the drawing position down one vee.
+.
 .
 .TPx
-.REQ .sp "N"
-Space vertical distance
-.I N
-up or down according to sign of
+.REQ .sp N
+Move the drawing position vertically by
 .I N
 (default scaling indicator\~\c
 .scaleindicator v ).
 .
+Positive values are downwards.
+.
+Prefixing
+.I N
+with the
+.B |
+operator moves to a position relative to the page top for positive
+.IR N ,
+and the bottom if
+.I N
+is negative;
+in all cases,
+one line height (vee) is added
+.RI to\~ N .
+.
+.I N
+is ignored inside a diversion.
+.
+.
 .TPx
 .REQ .special
 Reset global list of special fonts to be empty.