[groff] 12/14: [docs]: Clarify box behavior with pending output.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit e8bea989fd9e10687e0463904b6d66bc10652956
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Jul 19 15:16:22 2021 +1000

    [docs]: Clarify box behavior with pending output.
    
    * doc/groff.texi (Diversions): Explicitly note that an output line
      pending while inside a box diversion is discarded when it is closed.
      (Appending to it later won't recover it.)  Illustrate this in the
      example.
    
    * man/groff_diff.7.man (Language/New requests) <box, boxa>: Sync with
      the foregoing.
---
 doc/groff.texi       | 9 +++++----
 man/groff_diff.7.man | 4 ++--
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 6d442b0..e055edf 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -13764,15 +13764,17 @@ known as a @dfn{box}.
 @DefreqListEndx {boxa, [@Var{name}]}
 Divert (or append) output to @var{name}, similarly to the @code{di} and
 @code{da} requests, respectively.  Any output line pending when these
-requests are invoked is @emph{not} included in the box.  @code{box} or
-@code{boxa} without an argument stops diverting output to the box named
-by the most recent corresponding request.
+requests are invoked is @emph{not} included in the box.  Calling
+@code{box} or @code{boxa} without an argument stops diverting output to
+the box named by the most recent corresponding request; a pending output
+line inside a diversion is discarded.
 
 @Example
 Before the box.
 .box xxx
 In the box.
 .br
+Hidden treasure.
 .box
 After the box.
 .br
@@ -13780,7 +13782,6 @@ After the box.
 .xxx
     @result{} In the box.
 @endExample
-
 @endDefreq
 
 Apart from pending output line inclusion and the request names that
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 7c683d4..3b0cc77 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1210,9 +1210,9 @@ respectively,
 with the exception that any pending output line does not become part of
 the diversion
 (i.e.,
-the diversion always starts with a new line)
+a box diversion always starts on a new output line)
 but is restored after ending the diversion,
-discarding any partially collected line pending in the diversion.
+discarding any partially collected line in the diversion.
 .
 .
 .TP