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

Reply via email to