gbranden pushed a commit to branch master
in repository groff.
commit 3efda655c1a987d985279d6cdccc5e3c739fa447
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sun Nov 1 22:58:19 2026 -0600
doc/groff.texi.in: Clarify sv/os request behavior.
* Add material.
* Recast `sv` and `os` request descriptions for clarity.
* Favor active voice over passive.
* Break Texinfo input lines in convenient places for roffing and
diffing.
Bump document date.
---
doc/groff.texi.in | 56 ++++++++++++++++++++++++++++++++++++++++++++++++-------
1 file changed, 49 insertions(+), 7 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 7ca56014e..c764b0930 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -506,7 +506,7 @@ Documentation License''.
@title groff
@subtitle The GNU implementation of @code{troff}
@subtitle version @VERSION@
-@subtitle October 2026
+@subtitle November 2026
@author Trent@tie{}A.@: Fisher
@author Werner Lemberg
@author G.@tie{}Branden Robinson
@@ -12977,6 +12977,32 @@ implement keeps and displays; see @ref{Diversions}.
They may also offer
parameters for widow and orphan management.
@endDefreq
+@cindex saved vertical space
+@cindex vertical space, saved
+@cindex space, vertical, saved
+Occasionally,
+when vertically spacing with
+@code{sp},
+you may wish to exactly preserve the amount of space you requested,
+and not let the formatter discard any excess
+as it does when breaking a page.
+The
+@code{sv}
+request
+works like
+@code{sp}
+if it has room to vertically space,
+but instead
+@dfn{saves vertical space}
+if the requested amount would move the vertical drawing position
+beyond the next
+page location trap.@footnote{@xref{Page Location Traps}.}
+The
+@code{os}
+request outputs the saved vertical space as if with the
+@code{sp}
+request.
+
@DefreqList {sv, [@Var{space}]}
@DefreqListEndx {os, }
@cindex @code{ne} request, comparison with @code{sv}
@@ -12984,7 +13010,7 @@ parameters for widow and orphan management.
requires vertical space as
@code{ne}
does,
-but also
+but if that amount is not available,
@slanted{saves}
it for later output by the
@code{os}
@@ -12992,15 +13018,31 @@ request.
If
@var{space}
is available before the next page location trap,
-it is output immediately.
+the formatter outputs it immediately.
Both requests ignore a partially collected line,
taking effect at the next break.
@cindex @code{sv} request, and no-space mode
@cindex @code{os} request, and no-space mode
-@code{sv} and @code{os} ignore no-space mode (recall @ref{Manipulating
-Spacing}). While the @code{sv} request allows negative values for
-@var{space}, @code{os} ignores them. The default scaling unit is
-@samp{v}. If @var{space} is not specified, @samp{1v} is assumed.
+@code{sv}
+and
+@code{os}
+ignore no-space mode
+(recall @ref{Manipulating Spacing}).
+While the
+@code{sv}
+request allows negative values for
+@var{space},
+@code{os}
+ignores them.
+The default scaling unit is
+@samp{v}.
+If
+@var{space}
+is not specified,
+the formatter assumes @samp{1v}.
+There is only one,
+global,
+saved space amount.
@endDefreq
@Defreg {nl}
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit