gbranden pushed a commit to branch master
in repository groff.
commit d88767c587124d35fc73f5ed65e74ad256455787
Author: G. Branden Robinson <[email protected]>
AuthorDate: Mon Dec 1 21:35:33 2025 -0600
[doc,man]: Add/update "page control" section.
* Add it to the man page, syncing material from our Texinfo manual.
* Sync input line breaks--more or less--between the two.
---
doc/groff.texi.in | 30 +++++++++++++++++-------
man/groff.7.man | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 91 insertions(+), 9 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 7cb4d65e3..e1b9bc670 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -11121,9 +11121,10 @@ We most often see titles used in page header and
footer traps.
@cindex break, page
@cindex page ejection
@cindex ejection, page
-Discretionary page breaks can prevent the unwanted separation of
-content. A new page number takes effect during page ejection; see
-@ref{The Implicit Page Trap}.
+Discretionary page breaks
+can prevent the unwanted separation of content.
+A new page number takes effect during page ejection;
+see @ref{The Implicit Page Trap}.
@DefreqList {bp, [@Var{page-number}]}
@DefreqItem {bp, @t{+}@Var{page-number}}
@@ -11175,8 +11176,9 @@ output.
@cindex conditional page break (@code{ne})
@cindex page break, conditional (@code{ne})
@cindex need vertical space request (@code{ne})
-Force a page break if insufficient vertical space is available (assert
-``needed'' space). @code{ne} tests the distance to the next page
+Force a page break if insufficient vertical space is available
+(it asserts ``needed'' space).
+@code{ne} tests the distance to the next page
location trap; see @ref{Page Location Traps}, and breaks the page if
that amount is less than @var{space}. The default scaling unit is
@samp{v}. If @var{space} is invalid, GNU @code{troff} emits a warning
@@ -11226,10 +11228,20 @@ parameters for widow and orphan management.
@DefreqList {sv, [@Var{space}]}
@DefreqListEndx {os, }
@cindex @code{ne} request, comparison with @code{sv}
-@code{sv} requires vertical space as @code{ne} does, but also
-@slanted{saves} it for later output by the @code{os} request. If
-@var{space} is available before the next page location trap, it is
-output immediately. Both requests ignore a partially collected line,
+@code{sv}
+requires vertical space as
+@code{ne}
+does,
+but also
+@slanted{saves}
+it for later output by the
+@code{os}
+request.
+If
+@var{space}
+is available before the next page location trap,
+it is output 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
diff --git a/man/groff.7.man b/man/groff.7.man
index 4852c4e18..08b12b861 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2033,6 +2033,76 @@ except that it does not cancel a pending end-of-sentence
state.
.\" END Keep (roughly) parallel with groff.texi node "Dummy Characters".
.
.
+.\" ====================================================================
+.SH "Page control"
+.\" ====================================================================
+.
+.\" BEGIN Keep (roughly) parallel with groff.texi node "Page Control".
+Discretionary page breaks
+can prevent the unwanted separation of content.
+.
+A new page number takes effect during page ejection;
+see subsection \[lq]The implicit page trap\[rq] below.
+.
+The
+.B bp
+request breaks the page,
+incrementing the page number by one
+(or setting it per the supplied argument).
+.
+The
+.B ne
+request forces a page break if insufficient vertical space is available
+(it asserts \[lq]needed\[rq] space).
+.
+.B sv
+requires vertical space as
+.B ne
+does,
+but also
+.I saves
+it for later output by the
+.B os
+request.
+.
+.
+.P
+The
+.B nl
+register interpolates the vertical drawing position
+as of the most recently typeset output line.
+.
+It does not necessarily
+(and often does not)
+represent that of the pending output line,
+because the formatter does not determine the position of its baseline
+until it is output.
+.\" recall @ref{Manipulating Spacing}.
+.
+Assigning a value to
+.B nl
+sets the vertical drawing position
+in advance of further modifications to baseline positioning
+arising from alterations to type size,
+changes to vertical spacing,
+or application of extra pre- or post-vertical spacing.
+.
+.
+.P
+When the formatter starts,
+the transition to the first page
+.RB "has not yet happened\[em]" nl
+is negative.
+If you plant a page location trap at vertical position
+.RB \[lq] 0 \[rq]
+(idiomatically to format a header),
+you can assign a negative value to
+.B nl
+to spring that trap even if the page has already started
+(see subsection \[lq]Page location traps\[rq] below).
+.\" END Keep (roughly) parallel with groff.texi node "Page Control".
+.
+.
.\" TODO: Add sections here about characters (including custom
.\" defintions with the `char` request family) and fonts (including
.\" special fonts and the character resolution process).
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
