[groff] 04/15: [docs]: Update box/diversion minutia.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 62274f0d2b248ad1269803302abc22b2d151422a
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Aug 12 02:45:14 2021 +1000

    [docs]: Update box/diversion minutia.
    
    * doc/groff.texi (Diversions): Strengthen generalization about how boxes
      are handled.
      <asciify>: Tighten wording and import a sentence from groff_diff(7).
      Say "escape sequence" instead of "escape".
      <unformat>: Coalesce single-sentence paragraph into its predecessor.
      Say "type size" instead of "font size".
    
    * doc/groff_diff.7.man (Language/New requests) <asciify, unformat>: Sync
      with our Texinfo manual.
---
 doc/groff.texi       | 24 +++++++++++-------------
 man/groff_diff.7.man | 40 ++++++++++++++--------------------------
 2 files changed, 25 insertions(+), 39 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 2bf9209..d6663d2 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -13817,9 +13817,9 @@ After the box.
 @endDefreq
 
 Apart from pending output line inclusion and the request names that
-populate them, boxes are handled almost exactly as diversions are.  All
-of the following @code{groff} language elements can be used with them
-interchangeably; any exceptions are noted.
+populate them, boxes are handled exactly as diversions are.  All of the
+following @code{groff} language elements can be used with them
+interchangeably.
 
 @DefregList {.z}
 @DefregListEndx {.d}
@@ -14022,22 +14022,20 @@ register@tie{}@code{n} to@tie{}1.
 .x
 @endExample
 
-@code{asciify} cannot return all items in a diversion back to their
-source equivalent; nodes such as those produced by the @code{\N} escape
-will remain nodes, so the result cannot be guaranteed to be a pure
-string.  @xref{Copy Mode}.
+@code{asciify} cannot return all items in a diversion to their source
+equivalent: nodes such as those produced by the @code{\N} escape
+sequence will remain nodes, so the result cannot be guaranteed to be a
+pure string.  @xref{Copy Mode}.  Glyph parameters such as the type face
+and size are not preserved; use @code{unformat} to achieve that.
 @endDefreq
 
 @Defreq {unformat, div}
 Like @code{asciify}, unformat the diversion @var{div}.  However,
 @code{unformat} handles only tabs and spaces between words, the latter
 usually arising from spaces or newlines in the input.  Tabs are treated
-as input tokens, and spaces become adjustable again.
-
-The vertical sizes of lines are not preserved, but glyph information
-(font, font size, space width, and so on) is retained.  @code{unformat}
-can be useful in conjunction with the @code{box} and @code{boxa}
-requests.
+as input tokens, and spaces become adjustable again.  The vertical sizes
+of lines are not preserved, but glyph information (font, type size,
+space width, and so on) is retained.
 @endDefreq
 
 @codequotebacktick off
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 978dc76..30529c7 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1154,22 +1154,19 @@ to\~1.
 .
 .IP
 .B .asciify
-cannot return all items in a diversion back to their source equivalent;
+cannot return all items in a diversion to their source equivalent:
 nodes such as those produced by
 .BR \[rs]N[ .\|.\|.\& ]
 will remain nodes,
 so the result cannot be guaranteed to be a pure string.
 .
+See section \[lq]Copy mode\[rq] in
+.IR groff (@MAN7EXT@).
 .
-.IP
-Glyph information
-(font,
-point size,
-etc.)
-is not preserved;
+Glyph parameters such as the type face and size are not preserved;
 use
 .B .unformat
-instead to achieve that.
+to achieve that.
 .
 .
 .TP
@@ -3333,36 +3330,27 @@ request.
 .
 .TP
 .BI .unformat\~ div
-\[lq]Unformat\[rq]
-the diversion
+Like
+.BR .asciify ,
+unformat the diversion
 .IR div .
 .
-In contrast to the
-.B .asciify
-request,
-which tries to convert formatted elements of the diversion back to input
-tokens as much as possible,
+However,
 .B .unformat
 handles only tabs and spaces between words,
 the latter usually arising from spaces or newlines in the input.
 .
 Tabs are treated as input tokens,
-and spaces become are stretchable again.
-.
-Note that the vertical size of lines is not preserved.
+and spaces become adjustable again.
 .
 The vertical sizes of lines are not preserved,
 but glyph information
-(font, font size, space width, etc.\&)
+(font,
+type size,
+space width,
+and so on)
 is retained.
 .
-.B .unformat
-can be useful in conjunction with the
-.B .box
-and
-.B .boxa
-requests.
-.
 .
 .TP
 .BI .vpt\~ n