[groff] 13/40: [docs]: Revise presentation of `ne` request.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 92e829a6fba134389fe7e336abd0e14cb69c1431
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Dec 10 03:38:58 2022 -0600

    [docs]: Revise presentation of `ne` request.
---
 doc/groff.texi  | 44 ++++++++++++++++++++++++++++++--------------
 man/groff.7.man |  6 +++---
 2 files changed, 33 insertions(+), 17 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 50cfc84f8..62243a848 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -9976,24 +9976,40 @@ The register @code{.pe} is set to@tie{}1 while 
@code{bp} is active.
 @cindex orphan lines, preventing with @code{ne}
 @cindex conditional page break (@code{ne})
 @cindex page break, conditional (@code{ne})
-It is often necessary to force a certain amount of space before a new
-page occurs.  This is most useful to make sure that there is not a
-single @dfn{orphan} line left at the bottom of a page.  The @code{ne}
-request ensures that there is a certain distance, specified by the first
-argument, before the next page is triggered (@pxref{Traps}).  The
-default scaling indicator for @code{ne} is @samp{v}; the default value
-of @var{space} is@tie{}1@dmn{v} if no argument is given.
+You may require a certain amount of vertical space before a page break
+occurs.  For instance, you may wish to ensure that the first output line
+of a paragraph is not @dfn{orphaned} at the bottom of a page.  The
+@code{ne} request tests the amount of distance to the next page location
+trap (at the page bottom of none is planted earlier; see @ref{Traps}),
+and breaks the page if less than @var{space} is available.  The default
+scaling unit for @code{ne} is @samp{v}.  If @var{space} is not
+specified, @samp{1v} is assumed.
 
-For example, to make sure that no fewer than 2@tie{}lines get orphaned,
-do the following before each paragraph:
+For example, to require room for at least the first two output lines of
+a paragraph, you can do the following.
 
 @Example
 .ne 2
-text text text
-@endExample
-
-@code{ne} then automatically causes a page break if there is space for
-one line only.
+Considering how common illness is,
+how tremendous the spiritual change that it brings,
+how astonishing,
+when the lights of health go down,
+the undiscovered countries that are then disclosed,
+@endExample
+
+@c XXX: Some of this might be better placed in a revised Chapter 3.
+@code{ne} then causes a page break if there is room for only one output
+line.  This method is most reliable if a break has already occurred, but
+when macro packages are used this is often not the case; their
+paragraphing macros perform the break.  You may need to experiment with
+placing the @code{ne} after the paragraphing macro, or with placing
+@code{br} and @code{ne} requests before it.
+
+You can use @code{ne} with larger arguments to force grouping of section
+headings with their subsequent paragraphs, or tables with their captions
+and/or explanations.  Macro packages often use @code{ne} to implement
+more flexible keeps and displays.  They may also offer parameters for
+widow and orphan management.
 @endDefreq
 
 @DefreqList {sv, [@Var{space}]}
diff --git a/man/groff.7.man b/man/groff.7.man
index 9ef836a85..53633b1bb 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3402,13 +3402,13 @@ Disable output line adjustment.
 .
 .TPx
 .REQ .ne
-Need a one-line vertical space.
+Break page if distance to next page location trap is less than one vee.
 .
 .TPx
 .REQ .ne "N"
-Need
+Break page if distance to next page location trap is less than
 .I N
-vertical space (default scaling indicator\~\c
+(default scaling unit:
 .scaleindicator v ).
 .
 .