[groff] 10/15: doc/groff.texi, groff_diff(7): Resynchronize.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit ea0dfae690f849c348419ebf2b7cefde8c896e34
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Oct 19 04:34:22 2020 +1100

    doc/groff.texi, groff_diff(7): Resynchronize.
    
    The descriptions of .asciify, .unformat, and .char had diverged in the
    two documents.  Parallelize them, taking the clearer language from each
    (and doing some light recasting of my own).
---
 doc/groff.texi       | 77 ++++++++++++++++++++++---------------------
 man/groff_diff.7.man | 93 ++++++++++++++++++++++++++++++++++------------------
 2 files changed, 102 insertions(+), 68 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 944225f..7a29ce6 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -9505,31 +9505,31 @@ on the right doesn't get examined.
 @cindex @code{\&}, and glyph definitions
 @cindex @code{\e}, and glyph definitions
 @cindex @code{hcode} request, and glyph definitions
-Define a new glyph@tie{}@var{g} to be @var{string} (which can be
-empty).@footnote{@code{char} is a misnomer since an output glyph is
-defined.}  Every time glyph@tie{}@var{g} needs to be printed,
-@var{string} is processed in a temporary environment and the result is
-wrapped up into a single object.  Compatibility mode is turned off and
-the escape character is set to @samp{\} while @var{string} is being
-processed.  Any emboldening, constant spacing or track kerning is
-applied to this object rather than to individual characters in
-@var{string}.
-
-A glyph defined by these requests can be used just like a normal glyph
+Define a new character or glyph@tie{}@var{g} to be @var{string}, which
+can be empty.  More precisely, @code{char} defines (or redefines an
+existing) @code{groff} object that is accessed with the
+name@tie{}@var{g} on input, and produces @var{string} on output.  Every
+time glyph@tie{}@var{g} needs to be printed, @var{string} is processed
+in a temporary environment and the result is wrapped up into a single
+object.  Compatibility mode is turned off and the escape character is
+set to@tie{}@code{\} while @var{string} is processed.  Any emboldening,
+constant spacing, or track kerning is applied to this object rather than
+to individual glyphs in @var{string}.
+
+An object defined by these requests can be used just like a normal glyph
 provided by the output device.  In particular, other characters can be
 translated to it with the @code{tr} or @code{trin} requests; it can be
-made the leader character by the @code{lc} request; repeated patterns
-can be drawn with the glyph using the @code{\l} and @code{\L} escape
-sequences; words containing the glyph can be hyphenated correctly if the
-@code{hcode} request is used to give the glyph's symbol a hyphenation
-code.
+made the leader character with the @code{lc} request; repeated patterns
+can be drawn with it using the @code{\l} and @code{\L} escape sequences;
+and words containing@tie{}@var{g}  can be hyphenated correctly if the
+@code{hcode} request is used to give the object a hyphenation code.
 
-There is a special anti-recursion feature: Use of @code{g} within the
-glyph's definition is handled like normal characters and symbols not
-defined with @code{char}.
+There is a special anti-recursion feature: use of the object within its
+own definition is handled like a normal character (not
+defined with @code{char}).
 
-Note that the @code{tr} and @code{trin} requests take precedence if
-@code{char} accesses the same symbol.
+The @code{tr} and @code{trin} requests take precedence if @code{char}
+accesses the same symbol.
 
 @Example
 .tr XY
@@ -13003,12 +13003,14 @@ the output device, filtering out @var{string} again.
 @cindex unformatting diversions (@code{asciify})
 @cindex diversion, unformatting (@code{asciify})
 @cindex @code{trin} request, and @code{asciify}
-@dfn{Unformat} the diversion specified by @var{div} in such a way that
-@acronym{ASCII} characters, characters translated with the @code{trin}
-request, space characters, and some escape sequences that were formatted
-and diverted are treated like ordinary input characters when the
-diversion is reread.  It can be also used for gross hacks; for example,
-the following sets register@tie{}@code{n} to@tie{}1.
+@dfn{Unformat} the diversion @var{div} in a way such that Unicode basic
+Latin (@acronym{ASCII}) characters, characters translated with the
+@code{trin} request, space characters, and some escape sequences, that
+were formatted and diverted into @var{div} are treated like ordinary
+input characters when @var{div} is reread.  Doing so can be useful in
+conjunction with the @code{writem} request.  @code{asciify} can be also
+used for gross hacks; for example, the following sets
+register@tie{}@code{n} to@tie{}1.
 
 @Example
 .tr @@.
@@ -13021,21 +13023,22 @@ the following sets register@tie{}@code{n} to@tie{}1.
 .x
 @endExample
 
-Note that @code{asciify} cannot return all items in a diversion back
-to their source equivalent, nodes such as @code{\N[...]} will still
-remain as nodes, so the result cannot be guaranteed to be a pure string.
+@code{asciify} cannot return all items in a diversion back to their
+source equivalent; nodes such as those produced by @code{\N[...]} will
+remain nodes, so the result cannot be guaranteed to be a pure string.
 
 @xref{Copy-in Mode}.
 @endDefreq
 
 @Defreq {unformat, div}
-Like @code{asciify}, unformat the specified diversion.  However,
-@code{unformat} only unformats spaces and tabs between words.
-Unformatted tabs are treated as input tokens, and spaces are stretchable
-again.
-
-The vertical size of lines is not preserved; glyph information (font,
-font size, space width, etc.)@: is retained.
+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 stretchable again.
+
+The vertical sizes of lines are not preserved, but glyph information
+(font, font size, space width, etc.)@: is retained.  @code{unformat} can
+be useful in conjunction with the @code{box} and @code{boxa} requests.
 @endDefreq
 
 
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 4f07514..3f5a664 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1065,21 +1065,33 @@ and
 .
 .
 .TP
-.BI .asciify\~ xx
-This request \[oq]unformats\[cq] the diversion
-.I xx
-in such a way that ASCII and space characters (and some escape
-sequences) that were formatted
-and diverted into
-.I xx
+.BI .asciify\~ div
+.I Unformat
+the diversion
+.I div
+in a way such that Unicode basic Latin (ASCI) characters,
+characters translated with the
+.B .trin
+request,
+space characters,
+and some escape sequences,
+that were formatted and diverted into
+.I div
 are treated like ordinary input characters when
-.I xx
+.I div
 is reread.
-Useful for diversions in conjunction with the
-.B writem
+.
+Doing so can be useful in conjunction with the
+.B .writem
 request.
 .
-It can be also used for gross hacks; for example, this
+.B .asciify
+can be also used for gross hacks;
+for example,
+the following sets
+.RB register\~ n
+to\~1.
+.
 .
 .RS
 .IP
@@ -1096,15 +1108,26 @@ It can be also used for gross hacks; for example, this
 .EE
 .RE
 .
+.
 .IP
-sets register\~\c
-.B n
-to\~1.
+.B .asciify
+cannot return all items in a diversion back 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.
+.
 .
-Note that glyph information (font, font size, etc.) is not preserved;
+.IP
+Glyph information
+(font,
+point size,
+etc.)
+is not preserved;
 use
 .B .unformat
-instead.
+instead to achieve that.
+.
 .
 .TP
 .B .backtrace
@@ -3150,32 +3173,40 @@ This undoes the effect of the
 .B nroff
 request.
 .
+.
 .TP
-.BI .unformat\~ xx
-This request \[oq]unformats\[cq] the diversion
-.IR xx .
+.BI .unformat\~ div
+\[lq]Unformat\[rq]
+the diversion
+.IR div .
 .
-Contrary to the
-.B asciify
-request, which tries to convert formatted elements of the diversion
-back to input tokens as much as possible,
+In contrast to the
+.B .asciify
+request,
+which tries to convert formatted elements of the diversion back to input
+tokens as much as possible,
 .B .unformat
-only handles tabs and spaces between words (usually caused by spaces
-or newlines in the input) specially.
+handles only tabs and spaces between words,
+the latter usually arising from spaces or newlines in the input.
 .
-The former are treated as if they were input tokens, and the latter
-are stretchable again.
+Tabs are treated as input tokens,
+and spaces become are stretchable again.
 .
 Note that the vertical size of lines is not preserved.
 .
-Glyph information (font, font size, space width, etc.) is retained.
+The vertical sizes of lines are not preserved,
+but glyph information
+(font, font size, space width, etc.\&)
+is retained.
 .
-Useful in conjunction with the
-.B box
+.B .unformat
+can be useful in conjunction with the
+.B .box
 and
-.B boxa
+.B .boxa
 requests.
 .
+.
 .TP
 .BI .vpt\~ n
 Enable vertical position traps if