[groff] 16/20: [docs]: Reform "reread" terminology.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 0579cb68a724eaaafbece62aea2143fe69d74094
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Aug 2 10:51:40 2023 -0500

    [docs]: Reform "reread" terminology.
    
    From the _user's_ perspective, diversions interpolate as other things do
    (registers, strings, macros).  Use this same term for consistency with
    other documentation and to emphasize the parallelism to the reader of
    our documentation.  "Reread[ing]" (of diversions) is internal
    implementation terminology.
---
 NEWS                 |  4 ++--
 doc/groff.texi       | 29 +++++++++++++++--------------
 man/groff_diff.7.man | 12 ++++++------
 src/roff/troff/TODO  |  6 +++---
 4 files changed, 26 insertions(+), 25 deletions(-)

diff --git a/NEWS b/NEWS
index 65136349a..398e2ec08 100644
--- a/NEWS
+++ b/NEWS
@@ -2509,7 +2509,7 @@ o The `asciify' request has been extended to `unformat' 
space characters
   unbreakable space character.
 
 o The new `unformat' request is similar to `asciify' but only handles
-  space characters and tabs specially if the diversion is reread,
+  space characters and tabs specially if the diversion is interpolated,
   retaining font information.  This makes it possible to reformat
   diversions; for example the following
 
@@ -3569,7 +3569,7 @@ vertical position trap to be sprung.
 
 The `cf' request now behaves sensibly in a diversion.  If used in a
 diversion, it now arranges for the file to be copied to the output when
-the diversion is reread.
+the diversion is interpolated.
 
 There is a new request `trf' (transparent file) similar to `cf', but
 more like `\!'.
diff --git a/doc/groff.texi b/doc/groff.texi
index 8ede70bbd..605d526f9 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -15388,9 +15388,9 @@ the output device, filtering out @var{contents} again.
 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
+input characters when @var{div} is interpolated.  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
@@ -15928,8 +15928,8 @@ subject to copy mode interpretation.  If the file does 
not end with a
 newline, @code{trf} adds one.  Both requests cause a break.
 
 When used in a diversion, these requests embed a node (@pxref{Gtroff
-Internals}) in it that, when reread, causes the contents of @var{file}
-to be transparently copied to the output.  In @acronym{AT&T}
+Internals}) in it that, when interpolated, causes the contents of
+@var{file} to be transparently copied to the output.  In @acronym{AT&T}
 @code{troff}, the contents of @var{file} are immediately copied to the
 output regardless of whether there is a current diversion; this
 behaviour is so anomalous that it must be considered a bug.
@@ -16574,8 +16574,8 @@ Elements 1, 7, and@tie{}8 are inserted by 
@code{gtroff}; the latter two
 (which are always present) specify the vertical extent of the last line,
 possibly modified by @code{\x}.  The @code{br} request finishes the
 pending output line, inserting a newline input token, which is
-subsequently converted to a space when the diversion is reread.  Note
-that the word space node has a fixed width that isn't adjustable
+subsequently converted to a space when the diversion is interpolated.
+Note that the word space node has a fixed width that isn't adjustable
 anymore.  To convert horizontal space nodes back to input tokens, use
 the @code{unformat} request.
 
@@ -17428,10 +17428,10 @@ the input
 @noindent
 produces @samp{\\} in GNU @code{troff}.  Each pair of backslashes
 becomes one backslash @emph{glyph}; the resulting backslashes are thus
-not interpreted as escape @emph{characters} when they are reread as the
-diversion is output.  @acronym{AT&T} @code{troff} @emph{would} interpret
-them as escape characters when rereading them and end up printing one
-@samp{\}.
+not interpreted as escape @emph{characters} when they are interpolated
+as the diversion is output.  @acronym{AT&T} @code{troff} @emph{would}
+interpret them as escape characters when interpolating them and end up
+printing one @samp{\}.
 
 @cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
 @cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
@@ -17459,9 +17459,10 @@ in those of its lineal descendant, Heirloom Doctools 
@code{troff}, as of
 the latter's 060716 release (July 2006).}
 
 To store an escape sequence in a diversion that is interpreted when the
-diversion is reread, either use the traditional @code{\!} transparent
-output facility, or, if this is unsuitable, the new @code{\?} escape
-sequence.  @xref{Diversions} and @ref{Gtroff Internals}.
+diversion is interpolated, either use the traditional @code{\!}
+transparent output facility, or, if this is unsuitable, the new
+@code{\?} escape sequence.  @xref{Diversions} and @ref{Gtroff
+Internals}.
 
 In the somewhat pathological case where a diversion exists containing a
 partially collected line and a partially collected line at the top-level
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 4941e7211..08045124c 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1259,7 +1259,7 @@ in the diversion.
 .I anything
 is read in copy mode.
 .
-When the diversion is reread,
+When the diversion is interpolated,
 .I anything
 is interpreted.
 .I anything
@@ -1538,7 +1538,7 @@ that were formatted in the diversion
 .I div
 are treated like ordinary input characters when
 .I div
-is reread.
+is interpolated.
 .
 Doing so can be useful in conjunction with the
 .B writem
@@ -4000,7 +4000,7 @@ is read in copy mode.
 .BI .cf\~ file
 In a diversion,
 embed an object which,
-when reread,
+when interpolated,
 will cause the contents of
 .I file
 to be copied verbatim to the output.
@@ -5992,12 +5992,12 @@ Each pair of backslashes becomes one backslash
 .I glyph;
 the resulting backslashes are thus not interpreted as escape
 .I characters
-when they are reread as the diversion is output.
+when they are interpolated as the diversion is output.
 .
 AT&T
 .I troff \" AT&T
 .I would
-interpret them as escape characters when rereading them and end up
+interpret them as escape characters when interpolating them and end up
 printing one
 .RB \[lq] \[rs] \[rq].
 .
@@ -6043,7 +6043,7 @@ as of its 060716 release (July 2006).]
 .
 .P
 To store an escape sequence in a diversion that is interpreted when the
-diversion is reread,
+diversion is interpolated,
 either use the traditional
 .B \[rs]!\&
 transparent output facility,
diff --git a/src/roff/troff/TODO b/src/roff/troff/TODO
index 533167a40..517677cb3 100644
--- a/src/roff/troff/TODO
+++ b/src/roff/troff/TODO
@@ -29,9 +29,9 @@ Add a discretionary break escape sequence. \='...'...'...' 
like TeX.
 Think about kerning between characters and spaces. (Need to implement
 get_breakpoints and split methods for kern_pair_node class.)
 
-In troff, if .L > 1 when a diversion is reread in no-fill mode, then
-extra line-spacing is added on. Groff at the moment treats line-spacing
-like vertical spacing and doesn't do this. 
+In AT&T troff, if .L > 1 when a diversion is interpolated in no-fill
+mode, then extra line spacing is added on.  GNU troff at the moment
+treats line spacing like vertical spacing and doesn't do this.
 
 Suppose \(ch comes from a special font S, and that the current font is
 R. Suppose that R contains a hyphen character and that S does not.