[groff] 19/35: [doc,man]: Update descriptions of `cf`, `trf`.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 20ea55958e008d6ffbe407b4360280c075807d24
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Dec 8 12:23:25 2024 -0600

    [doc,man]: Update descriptions of `cf`, `trf`.
---
 doc/groff.texi.in    | 28 ++++++++++++++++++++--------
 man/groff.7.man      | 34 ++++++++++++++++++++++++++--------
 man/groff_diff.7.man | 29 ++++++++++++-----------------
 3 files changed, 58 insertions(+), 33 deletions(-)

diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 228d52d8b..8b35fea70 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -16338,11 +16338,24 @@ option.
 @cindex @code{trf} request, and copy mode
 @cindex copy mode, and @code{trf} request
 @cindex mode, copy, and @code{trf} request
-Transparently output the contents of @var{file}.  Each line is output as
-if preceded by @code{\!}, but is not read in copy mode.  If @var{file}
-does not end with a newline, @code{trf} appends one.  Both requests
-break the line before reading @var{file}, unless invoked with the
-no-break control character.
+Copy
+@var{file}
+as ``throughput'' to GNU
+@command{troff}
+output.
+Each line of
+@var{file}
+is output as if preceded by
+@code{\!},
+but is not interpreted by the formatter.
+If
+@var{file}
+does not end with a newline,
+@code{trf}
+appends one.
+Both requests break the line before reading
+@var{file},
+unless invoked with the no-break control character.
 
 When used in a diversion, these requests embed a node (@pxref{Gtroff
 Internals}) in it that, when interpolated, causes the contents of
@@ -16353,9 +16366,8 @@ anomalous that it must be considered a bug.
 @cindex @code{trf} request, and invalid characters
 @cindex characters, invalid for @code{trf} request
 @cindex invalid characters for @code{trf} request
-While @code{cf} copies the contents of @var{file} completely
-unprocessed, @code{trf} disallows characters such as NUL that are not
-valid @command{gtroff} input characters (@pxref{Identifiers}).
+@code{trf} discards invalid input characters;
+recall @ref{Identifiers}.
 
 For @code{cf}, within a diversion, ``completely unprocessed'' means that
 each line of a file to be inserted is handled as if it were preceded by
diff --git a/man/groff.7.man b/man/groff.7.man
index 9e43fecbe..4a5f77f58 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2768,13 +2768,20 @@ stop centering.
 .
 .TPx
 .REQ .cf file
-Transparently output the contents of
-.I file.
+Break and copy
+.I file
+as \[lq]throughput\[rq] to GNU
+.I troff \" GNU
+output
+(see
+.MR groff_out @MAN5EXT@ ).
 .
-Each of its lines is output
+Each line of
+.I file
+is output
 as if preceded by
 .BR \[rs]!\& ,
-but is not read in copy mode.
+but is not interpreted by the formatter.
 .
 .TPx
 .REQ .cflags "n c1 c2 \fR\&.\|.\|.\&\fP"
@@ -4682,14 +4689,25 @@ and so on prior to output.
 .
 .TPx
 .REQ .trf file
-Transparently output the contents of
-.I file.
+Break and copy
+.I file
+as \[lq]throughput\[rq] to GNU
+.I troff \" GNU
+output
+(see
+.MR groff_out @MAN5EXT@ ).
 .
 Unlike
 .request .cf ,
-invalid input characters in
+characters invalid as input to GNU
+.I troff \" GNU
+are discarded.
+.
+If
 .I file
-are rejected.
+does not end with a newline,
+.B trf
+appends one.
 .
 .TPx
 .REQ .trin abcd\fR\&.\|.\|.\&\fP
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index a7f8c6aa9..3fa55b7cb 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -3790,12 +3790,20 @@ but does not append a newline.
 .
 .TP
 .BI .trf\~ file
-Transparently output the contents of
-.IR file .
+Break and copy
+.I file
+as \[lq]throughput\[rq] to GNU
+.I troff \" GNU
+output,
+discarding characters that are invalid as input;
+contrast with
+.BR cf .
 .
-Each line is output as if preceded by
+Each line of
+.I file
+is output as if preceded by
 .BR \[rs]! ,
-but is not read in copy mode.
+but is not interpreted by the formatter.
 .
 If
 .I file
@@ -3803,19 +3811,6 @@ does not end with a newline,
 .B trf
 appends one.
 .
-Like
-.BR cf ,
-.B trf
-breaks the line unless invoked with the no-break control character.
-.
-Characters in
-.I file
-that are invalid as input to GNU
-.I troff \" GNU
-are discarded;
-contrast with
-.BR cf .
-.
 .
 .TP
 .BI .trin\~ abcd