gbranden pushed a commit to branch master
in repository groff.
commit 9c54f6d03839ae02cc106065527016b31335ed24
Author: G. Branden Robinson <[email protected]>
AuthorDate: Mon Dec 1 21:48:17 2025 -0600
[doc,man]: Revise description of `sp` request.
* Respell metasyntactic name of argument as "vertical-distance".
* Sync paragraph regarding use of `|` operator with request argument
from groff(7) to our Texinfo manual. As Peter Schaffter has
emphasized, it's an important caveat, and can be confusing when
considering the coordinate system used by the formatter (and by the
page description language of its output). `.sp |0` doesn't set the
vertical drawing position to zero, but to zero plus one vee--this was
apparently a design choice by Ossanna, perhaps representing a strong
aversion to letting typeset text encroach beyond the page top.
* Speak of "formatter" behavior, since no GNU troff-specific behaviors
are implicated here.
* Favor active voice over passive.
* Favor present tense over future.
* Sync input line breaks between our Texinfo manual and groff(7).
* doc/groff.texi.in: Bump revision date.
---
doc/groff.texi.in | 47 +++++++++++++++++++++++++++++++++++------------
man/groff.7.man | 43 ++++++++++++++++++++++++-------------------
2 files changed, 59 insertions(+), 31 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index da941a6fe..7c54efffd 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -467,7 +467,7 @@ Documentation License''.
@title groff
@subtitle The GNU implementation of @code{troff}
@subtitle version @VERSION@
-@subtitle November 2025
+@subtitle December 2025
@author Trent@tie{}A.@: Fisher
@author Werner Lemberg
@author G.@tie{}Branden Robinson
@@ -9980,18 +9980,27 @@ The hyphenation space adjustment threshold is available
in the
A break causes the formatter to update the vertical drawing position at
which the new text baseline is placed; you can alter this location.
-@Defreq {sp, [@Var{distance}]}
-Break and move the next text baseline down by @var{distance}, or until
-springing a page location trap.@footnote{@xref{Page Location Traps}.}
-If invoked with the no-break control character, @code{sp} moves the
-text baseline applied to the entire pending output line by
-@var{distance}.@footnote{To shift the text baseline for
+@Defreq {sp, [@Var{vertical-distance}]}
+Break and move the next text baseline down by
+@var{distance},
+or until springing a page location trap.@footnote{@xref{Page Location Traps}.}
+If invoked with the no-break control character,
+@code{sp}
+moves the text baseline applicable to the entire pending output line by
+@var{vertical-distance}.@footnote{To shift the text baseline for
@emph{part} of an output line---to set super- or subscripts, for
-instance--use the @code{\v} escape sequence. @xref{Page Motions}.} A
-negative @var{distance} will not reduce the position of the text
-baseline below zero. Inside a diversion, any @var{distance} argument is
-ignored. The default scaling unit is @samp{v}. If @var{distance} is
-not specified, @samp{1v} is assumed.
+instance--use the @code{\v} escape sequence. @xref{Page Motions}.}
+A negative
+@var{vertical-distance}
+cannot reduce the position of the text baseline below zero.
+Inside a diversion,
+the formatter ignores any argument.
+The default scaling unit is
+@samp{v}.
+Omitting
+@var{vertical-distance}
+implies
+@samp{1v}.
@Example
.pl 5v \" Set page length to 5 vees.
@@ -10033,6 +10042,20 @@ baseline on the page (recall @ref{Numeric
Expressions}).
@noindent
The input @samp{.y-from-bot-up 10c} sets the next text baseline
10@tie{}cm from the bottom edge of the paper.
+
+@cindex boundary-relative measurement operator (@code{|}), use with @code{sp}
request
+@cindex @code{|}) operator, use with @code{sp} request
+Applying the boundary-relative measurement operator
+@code{|}
+operator to
+@var{vertical-distance},
+as in
+@code{|}@var{N},
+moves to a position relative to the page top for positive
+@var{N},
+and the bottom if
+@var{N}
+is negative.
@endDefreq
@DefreqList {ls, [@Var{count}]}
diff --git a/man/groff.7.man b/man/groff.7.man
index 207966619..4852c4e18 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -4790,33 +4790,38 @@ does not exist.
Break and move the next text baseline down by one vee,
or until springing a page location trap.
.
+If invoked with the no-break control character,
+.B sp
+moves the text baseline applicable to the entire pending output line.
+.
.TPx
-.REQ .sp dist
-Break and move the next text baseline down by
-.IR dist ,
-or until springing a page location trap
-(default scaling unit\~\c
-.scaleindicator v ).
+.REQ .sp vertical-distance
+As
+.BR sp ,
+but move by
+.I vertical-distance
+instead of
+.BR 1v .
+.
+Inside a diversion,
+the formatter ignores any argument.
.
A negative
-.I dist
-will not reduce the position of the text baseline below zero.
+.I vertical-distance
+cannot reduce the position of the text baseline below zero.
.
-Prefixing
-.I dist
-with the
+Applying the boundary-relative measurement operator
.B \[or]
-operator moves to a position relative to the page top for positive
+operator to
+.I vertical-distance,
+as in
+.RB \[lq] \[or]\c
+.IR N \[rq],
+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\~ dist .
-.
-.I dist
-is ignored inside a diversion.
+is negative.
.
.TPx
.REQ .special
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
