[groff] 01/02: Clarify new `pline` request behavior.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 7fcde85b7f1746c476dd6f0a41f940aae5c27ea4
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Apr 30 17:19:31 2024 -0500

    Clarify new `pline` request behavior.
---
 ChangeLog            | 14 +++++++-------
 NEWS                 |  4 ++--
 doc/groff.texi.in    | 19 ++++++++++---------
 man/groff.7.man      |  6 ++++--
 man/groff_diff.7.man |  6 ++++--
 5 files changed, 27 insertions(+), 22 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index a64698c65..d5086e8a7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,23 +1,23 @@
 2024-04-30  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * src/roff/troff/node.cpp (node::debug_node): Report list of
-       nodes produced by most recent input line in forward order,
-       likely corresponding to user intuition.  (Internally, the
-       formatter stores the nodes in LIFO order, for the convenience of
-       traversing a singly-list list.)
+       pending output nodes produced by the previous input line in
+       forward order, likely corresponding to user intuition.
+       {Internally, the formatter stores the nodes in LIFO order, for
+       the convenience of traversing a singly-linked list.}
 
 2024-04-30  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [troff]: Add new request `pline` to dump list of nodes
-       corresponding to most recently seen input line.
+       corresponding to the previous input line.
 
        * src/roff/troff/env.h (class environment): Declare new
        `dump_node_list` member function.
        * src/roff/troff/env.cpp (environment::dump_node_list): New
-       function calls `debug_node_list()` if the most recent input line
+       function calls `debug_node_list()` if the previous input line
        was productive of output.
        (print_node_list): New function dumps list of nodes
-       pending in the environment and produced by the most recent input
+       pending in the environment and produced by the previous input
        line.
        (init_env_requests): Wire up `pline` request to
        `print_node_list()`.
diff --git a/NEWS b/NEWS
index 11d5e7994..9f23db5a6 100644
--- a/NEWS
+++ b/NEWS
@@ -86,8 +86,8 @@ o A new request, `phw`, reports to the standard error stream 
the current
   list of hyphenation exceptions.
 
 o A new request, `pline`, reports to the standard error stream the list
-  of nodes (an internal data structure) corresponding to the most
-  recently seen input line.  The list is empty if there was no previous
+  of pending output nodes (an internal data structure) corresponding to
+  the previous input line.  The list is empty if there was no previous
   input line or if it was not productive.
 
 o The `hla` request, when invoked with no arguments, now clears the
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 1f6b17622..62570bfcb 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -8355,7 +8355,7 @@ requests and escape sequences that define registers or 
strings or alter
 the formatting environment (as with changes to the size, face, height,
 slant, or color of the type) are not productive.@footnote{If you're not
 sure whether an input line has been productive, you can use the
-@code{pline} request to see whether it produced any formatting nodes.
+@code{pline} request to see whether it produced any output nodes.
 @xref{Debugging}.}  We will also preview the output line continuation
 escape sequence, @code{\c}, which ``connects'' two input lines that
 would otherwise be counted separately.  @footnote{@xref{Line
@@ -17029,8 +17029,8 @@ exit codes respectively, to halt further processing 
when continuing
 would be fruitless.  Examine the state of the formatter with requests
 that write lists of defined names (macros, strings, and diversions),
 colors, composite characters, environments, hyphenation exceptions,
-registers, page location traps, and a list of nodes corresponding to
-the most recent input line to the standard error stream.
+registers, page location traps, and a list of pending output nodes
+corresponding to the previous input line to the standard error stream.
 @c END Keep parallel with section "Debugging" of groff(7).
 
 @Defreq {lf, line [@Var{file}]}
@@ -17145,12 +17145,13 @@ suffixed with a tab and asterisk (@code{*}).
 @endDefreq
 
 @Defreq {pline, }
-@cindex dumping node list of most recent input line (@code{pline})
-@cindex node list of most recent input line, dumping (@code{pline})
-@cindex most recent input line, dumping node list of (@code{pline})
-Report, to the standard error stream, the list of nodes corresponding to
-the most recently seen input line.  The list is empty if there was no
-previous input line or if it was not productive; recall
+@cindex dumping pending node list of previous input line (@code{pline})
+@cindex node list, pending, dumping that of previous input line (@code{pline})
+@cindex pending node list of previous input line, dumping (@code{pline})
+@cindex previous input line, dumping pending node list of (@code{pline})
+Report, to the standard error stream, the list of pending output nodes
+corresponding to the previous input line.  The list is empty if there
+was no previous input line or if it was not productive; recall
 @xref{Manipulating Filling and Adjustment}.
 @endDefreq
 
diff --git a/man/groff.7.man b/man/groff.7.man
index 3b0c336dd..61c89e3ff 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3986,7 +3986,8 @@ Change page length to
 .REQ .pline
 Report,
 to the standard error stream,
-the list of nodes corresponding to the most recently seen input line.
+the list of pending output nodes corresponding to the previous input
+line.
 .
 The list is empty if there was no previous input line or if it was not
 productive.
@@ -8425,7 +8426,8 @@ registers
 .RB ( .pnr );
 page location traps
 .RB ( .ptr );
-and a list of nodes corresponding to the most recent input line
+and a list of pending output nodes corresponding to the previous input
+line
 .RB ( .pline )
 to the standard error stream.
 .\" END Keep (roughly) parallel with groff.texi node "Debugging".
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 7f6ba35f5..32d967fe1 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -3200,7 +3200,8 @@ are suffixed with a tab and asterisk
 .B .pline
 Report,
 to the standard error stream,
-the list of nodes corresponding to the most recently seen input line.
+the list of pending output nodes corresponding to the previous input
+line.
 .
 The list is empty if there was no previous input line or if it was not
 productive.
@@ -5354,7 +5355,8 @@ registers
 .RB ( pnr ),
 page location traps
 .RB ( ptr ),
-and a list of nodes corresponding to the most recent input line
+and a list of pending output nodes corresponding to the previous input
+line
 .RB ( .pline )
 to the standard error stream.
 .