gbranden pushed a commit to branch master
in repository groff.
commit c8229d9e65e7fbd49aa8d6679cd2fe85d317d200
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sat Oct 31 09:41:17 2026 -0500
[doc,man]: Clarify `ne` request behavior.
* Flesh out motivation of feature.
* Move documentation of "implied" argument earlier.
* Drop stale/incorrect claim of warning emission on invalid argument.
* Document behavior difference with AT&T troffs (tested with DWB 3.3,
Solaris 10, Heirloom Doctools, and Plan 9 from User Space) when
request is given invalid argument.
* Break Texinfo input lines in convenient places for roffing and
diffing.
---
doc/groff.texi.in | 39 ++++++++++++++++++++++++++++++++-------
man/groff_diff.7.man | 17 +++++++++++++++++
2 files changed, 49 insertions(+), 7 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 592e2f405..7ca56014e 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -12920,13 +12920,22 @@ not when it is output.
@cindex page break, conditional (@code{ne})
@cindex need vertical space request (@code{ne})
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
-in category @samp{number} and ignores the argument. If @var{space} is
-not specified, @samp{1v} is assumed.
+the request asserts that the document ``needs'' vertical space
+for forthcoming material on the page,
+like a table,
+figure,
+or the start of a paragraph.
+@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}.
+Omitting
+@var{space}
+implies
+@samp{1v}.
We can require space for at least the first two output lines of a
paragraph, preventing its first line from being isolated at the page
@@ -24302,6 +24311,22 @@ and Plan@tie{}9 from User Space
do not;
they remove objects named by any subsequent valid arguments.
+@c XXX: The following is likely true of other requests as well.
+@cindex @code{ne} request, incompatibilities with @acronym{AT&T} @code{troff}
+When
+GNU
+@command{troff}'s @c GNU
+@code{ne}
+request is given an invalid argument,
+it emits an error diagnostic and ignores the
+@emph{request};
+@acronym{AT&T}
+@code{troff}s @c AT&T
+ignore the
+@emph{argument},
+interpreting the invalid request as
+@samp{ne 1v}.
+
GNU
@command{troff} @c GNU
does not emit output if it has nothing to format.
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 347d50ba2..33cfe3522 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -6797,6 +6797,23 @@ they remove objects named by any subsequent valid
arguments.
.
.
.P
+.\" XXX: The following is likely true of other requests as well.
+When
+GNU
+.IR troff 's \" GNU
+.B ne
+request is given an invalid argument,
+it emits an error diagnostic and ignores the
+.I request;
+AT&T
+.IR troff s \" AT&T
+ignore the
+.I argument,
+interpreting the invalid request as
+.RB \[lq] "ne 1v" \[rq].
+.
+.
+.P
GNU
.I troff \" GNU
does not emit output if it has nothing to format.
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit