[groff] 04/11: [docs]: Revise and simplify `pline` description.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit ae4a217cf73ad5cf3534e1b533c4a78ac97523c4
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue May 7 17:10:47 2024 -0500

    [docs]: Revise and simplify `pline` description.
    
    Now that `pline` intepretation no longer _puts_ a junk newline on the
    input, we can observe the full pending output line.
    
    $ nroff
    foo bar
    .pline
    { line_start_node  nest level 0 }
    { glyph_node [f nest level 0]}
    { glyph_node [o nest level 0]}
    { glyph_node [o nest level 0]}
    { word_space_node  nest level 0 }
    { glyph_node [b nest level 0]}
    { glyph_node [a nest level 0]}
    { glyph_node [r nest level 0]}
    baz\c
    qux
    .pline
    { line_start_node  nest level 0 }
    { glyph_node [f nest level 0]}
    { glyph_node [o nest level 0]}
    { glyph_node [o nest level 0]}
    { word_space_node  nest level 0 }
    { glyph_node [b nest level 0]}
    { glyph_node [a nest level 0]}
    { glyph_node [r nest level 0]}
    { word_space_node  nest level 0 }
    { glyph_node [b nest level 0]}
    { glyph_node [a nest level 0]}
    { glyph_node [z nest level 0]}
    { transparent_dummy_node  nest level 0 }
    { glyph_node [q nest level 0]}
    { glyph_node [u nest level 0]}
    { glyph_node [x nest level 0]}
    
    Much better!
---
 ChangeLog            | 18 ++++++++----------
 NEWS                 |  5 ++---
 doc/groff.texi.in    | 23 +++++++++++------------
 man/groff.7.man      |  6 ++----
 man/groff_diff.7.man |  6 ++----
 5 files changed, 25 insertions(+), 33 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 02571cc90..7a1eb7804 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -148,24 +148,22 @@
 2024-04-30  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * src/roff/troff/node.cpp (node::debug_node): Report list of
-       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 appending to a singly-linked list.}
+       pending output nodes in forward order, likely corresponding to
+       user intuition.  (Internally, the formatter stores the nodes in
+       LIFO order, for the convenience of appending to 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 the previous input line.
+       [troff]: Add new request `pline` to dump list of nodes in the
+       pending output 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 previous input line
-       was productive of output.
+       function calls `debug_node_list()`.
        (print_node_list): New function dumps list of nodes
-       pending in the environment and produced by the previous input
-       line.
+       in the environment's pending output line.
        (init_env_requests): Wire up `pline` request to
        `print_node_list()`.
 
diff --git a/NEWS b/NEWS
index f5f433eec..a18a6e7bd 100644
--- a/NEWS
+++ b/NEWS
@@ -86,9 +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 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.
+  of output nodes (an internal data structure) corresponding to
+  the pending output line.  The list is empty if no such nodes exist.
 
 o The `hla` request, when invoked with no arguments, now clears the
   hyphenation language, disabling automatic hyphenation.
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 5e5af0aef..f2fb8c34b 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -8355,10 +8355,10 @@ 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 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
+@code{pline} request before and after it 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
 Continuation}.}
 
 @Example
@@ -17145,14 +17145,13 @@ suffixed with a tab and asterisk (@code{*}).
 @endDefreq
 
 @Defreq {pline, }
-@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
-@ref{Manipulating Filling and Adjustment}.
+@cindex dumping pending output line node list (@code{pline})
+@cindex node list, of pending output line, dumping (@code{pline})
+@cindex output line, node list of pending, dumping (@code{pline})
+@cindex pending node list of output line, dumping (@code{pline})
+Report, to the standard error stream, the list of output nodes
+corresponding to the pending output line.  The list is empty if there
+are none.
 @endDefreq
 
 @Defreq {pm, }
diff --git a/man/groff.7.man b/man/groff.7.man
index 61c89e3ff..b687d8e78 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3986,11 +3986,9 @@ Change page length to
 .REQ .pline
 Report,
 to the standard error stream,
-the list of pending output nodes corresponding to the previous input
-line.
+the list of output nodes corresponding to the pending output line.
 .
-The list is empty if there was no previous input line or if it was not
-productive.
+The list is empty if there are none.
 .
 .TPx
 .REQ .pm
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index d98e38952..bb0515ccf 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -3200,11 +3200,9 @@ are suffixed with a tab and asterisk
 .B .pline
 Report,
 to the standard error stream,
-the list of pending output nodes corresponding to the previous input
-line.
+the list of output nodes corresponding to the pending output line.
 .
-The list is empty if there was no previous input line or if it was not
-productive.
+The list is empty if there are none.
 .
 .
 .TP