[groff] 11/17: [docs]: Fix style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 799752358a3924883be05038d9a7f73243192e51
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Jan 18 09:31:53 2024 -0600

    [docs]: Fix style nits.
    
    * doc/groff.texi (Diversions): Recast description of `output` request.
      (I/O): Recast description of `write` and `writec` requests.
      (Debugging): Recast description of `tm1` request.
      (gtroff Output): Wean the language I wrote off of the term
      "intermediate" (output), leaving it as a marker for stuff that needs
      to be rewritten in idiomatic English.
    
    * man/groff.7.man:
    * man/groff_diff.7.man:
    * man/groff_out.5.man: Sync with the foregoing.
---
 doc/groff.texi       | 50 ++++++++++++++++++++++-----------------------
 man/groff.7.man      | 49 ++++++++++++++++++++++++++------------------
 man/groff_diff.7.man | 57 ++++++++++++++++++++++++++++++++--------------------
 man/groff_out.5.man  |  4 ++--
 4 files changed, 92 insertions(+), 68 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 8c85a1f0b..b42958da7 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -15579,14 +15579,15 @@ at all; its argument is simply ignored.
 @cindex @code{output} request, and copy mode
 @cindex copy mode, and @code{output} request
 @cindex mode, copy, and @code{output} request
-@Defreq {output, contents}
-Emit @var{contents} directly to GNU @code{troff}'s intermediate output
-(subject to copy mode interpretation); this is similar to @code{\!} used
-at the top level.  An initial neutral double quote in @var{contents} is
-stripped to allow embedding of leading spaces.
-
-This request can't be used before the first page has started---if you
-get an error, simply insert @code{.br} before the @code{output} request.
+@Defreq {output, [@code{"}]@Var{contents}}
+Emit @var{contents} directly to GNU @code{troff}'s output; this usage is
+similar to that of @code{\!} in the top-level diversion.  An initial
+neutral double quote in the argument is stripped, allowing embedded
+leading spaces in @var{contents}, which is read in copy mode and
+continues to the end of the input line.  This request can't be used
+before the first page has started---if an error is reported, or
+@var{contents} fails to appear in GNU @command{troff}'s output, simply
+insert a @code{.br} line before the @code{output} request.
 
 Use with caution!  It is normally only needed for mark-up used by a
 postprocessor that does something with the output before sending it to
@@ -16377,15 +16378,13 @@ enable unsafe mode.
 @cindex mode, copy, and @code{writec} request
 @cindex write to file stream (@code{write}, @code{writec})
 @cindex file stream, write to (@code{write}, @code{writec})
-Write to the file associated with the specified @var{stream}.  The
-stream must previously have been the subject of an open request.  The
-remainder of the line is interpreted as the @code{ds} request reads its
-second argument: an initial neutral double quote in @var{contents} is
-stripped to allow embedding of leading spaces, and it is read in copy
-mode.
+Write @var{contents} to @var{stream}, which must previously have been
+the subject of an @code{open} request.  A leading neutral double quote
+in the second argument is stripped, allowing embedded leading spaces in
+@var{contents}, which is read in copy mode until the end of the line.
 
 The @code{writec} request is like @code{write}, but only @code{write}
-appends a newline to the data.
+appends a newline to @var{contents}.
 @endDefreq
 
 @Defreq {writem, stream xx}
@@ -16956,8 +16955,7 @@ cannot contain special characters, to the standard 
error stream,
 followed by a newline.  Leading spaces in @var{message} are ignored.
 
 @code{tm1} is similar, but recognizes and strips a leading neutral
-double quote from @var{message} to allow the embedding of leading
-spaces.
+double quote, allowing embedded spaces in @var{message}.
 
 @code{tmc} works as @code{tm1}, but does not append a newline.
 @endDefreq
@@ -17853,20 +17851,22 @@ used any longer by @command{gtroff}.
 @node Language Concepts, Command Reference, gtroff Output, gtroff Output
 @subsection Language Concepts
 
+@c BEGIN Keep parallel with introductory paragraph of groff_out(5).
 The fundamental operation of the GNU @code{troff} formatter is the
 translation of the @code{groff} input language into a device-independent
 form primarily concerned with what has to be written or drawn at
 specific positions on the output device.  This language is simple and
 imperative.  In the following discussion, the term @dfn{command} always
-refers to this intermediate output language, and never to the
+refers to this device-independent output language, and never to the
 @code{groff} language intended for direct use by document authors.
-Intermediate output commands comprise several categories: glyph output;
-font, color, and text size selection; motion of the printing position;
-page advancement; drawing of geometric objects; and device control
-commands, a catch-all for operations not easily classified as any of the
-foregoing, such as directives to start and stop output, identify the
-intended output device, or place URL hyperlinks in supported output
-formats.
+Device-independent output commands comprise several categories: glyph
+output; font, color, and text size selection; motion of the printing
+position; page advancement; drawing of geometric objects; and device
+control commands, a catch-all for operations not easily classified as
+any of the foregoing, such as directives to start and stop output,
+identify the intended output device, or place URL hyperlinks in
+supported output formats.
+@c END Keep parallel with introductory paragraph of groff_out(5).
 
 @menu
 * Separation::
diff --git a/man/groff.7.man b/man/groff.7.man
index 7e2c977f3..f8394c85a 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3817,15 +3817,17 @@ Output vertical distance that was saved by the
 request.
 .
 .TPx
-.REQ .output anything
+.REQ .output contents
 Emit
-.I anything
-directly to intermediate output,
-allowing leading whitespace if
-.I string
-starts with
-\&\f[CB]\[dq]\f[]
-(which is stripped off).
+.I contents
+directly to
+.IR @g@troff 's
+output.
+.
+An initial neutral double quote in the argument is stripped,
+allowing embedded leading spaces in
+.IR contents ,
+which is read in copy mode and continues to the end of the input line.
 .
 .TPx
 .REQ .pc
@@ -4400,10 +4402,9 @@ to the standard error stream.
 .REQ .tm1 message
 As
 .request .tm ,
-but an initial neutral double quote in
-.I message
-is removed,
-allowing it to contain leading spaces.
+but recognizes and strips a leading neutral double quote,
+allowing embedded spaces in
+.IR message .
 .
 .TPx
 .REQ .tmc message
@@ -4570,17 +4571,27 @@ unless and until
 evaluates false.
 .
 .TPx
-.REQ .write "stream anything"
+.REQ .write "stream contents"
 Write
-.I anything
+.I contents
 to
-.IR stream .
+.IR stream ,
+which must previously have been the subject of an
+.request .open
+request,
+followed by a newline.
+.
+An initial neutral double quote in the second argument is stripped,
+allowing embedded leading spaces in
+.IR contents ,
+which is read in copy mode until the end of the line.
 .
 .TPx
-.REQ .writec "stream anything"
-Similar to
-.request .write
-without emitting a final newline.
+.REQ .writec "stream contents"
+As
+.request .write ,
+but does not append a newline to
+.IR contents .
 .
 .TPx
 .REQ .writem "stream name"
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 0c323ea5b..33214a008 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -3082,16 +3082,31 @@ append to it instead of truncating it.
 .TP
 .BI .output\~ contents
 Emit
-.IR contents ,
-which are read in copy mode,
-to the formatter output;
-this is similar to
+.I contents
+directly to
+.IR @g@troff 's
+output;
+this usage is similar to that of
 .B \[rs]!\&
-used in the top-level diversion.
+in the top-level diversion.
 .
-An initial neutral double quote in
+An initial neutral double quote in the argument is stripped,
+allowing embedded leading spaces in
+.IR contents ,
+which is read in copy mode and continues to the end of the input line.
+.
+This request can't be used before the first page has started\[em]if an
+error is reported,
+or
 .I contents
-is stripped to allow the embedding of leading spaces.
+fails to appear in
+.IR @g@troff 's
+output,
+simply insert a
+.B .br
+line before the
+.B output
+request.
 .
 .
 .TP
@@ -3543,11 +3558,10 @@ the increase in width is a linear function of the type 
size.
 .TP
 .BI .tm1\~ message
 As
-.B tm
-request,
-but strips a leading neutral double quote from
-.I message
-to allow the embedding of leading spaces.
+.BR tm ,
+but recognizes and strips a leading neutral double quote,
+allowing embedded spaces in
+.IR message .
 .
 .
 .TP
@@ -3785,9 +3799,9 @@ loop's flow of control.
 .
 .
 .TP
-.BI .write\~ stream\~anything
+.BI .write\~ stream\~contents
 Write
-.I anything
+.I contents
 to
 .IR stream ,
 which must previously have been the subject of an
@@ -3795,19 +3809,18 @@ which must previously have been the subject of an
 request,
 followed by a newline.
 .
-.I anything
-is read in copy mode.
-.
-An initial neutral double quote in
-.I anything
-is stripped to allow the embedding of leading spaces.
+An initial neutral double quote in the second argument is stripped,
+allowing embedded leading spaces in
+.IR contents ,
+which is read in copy mode until the end of the line.
 .
 .
 .TP
-.BI .writec\~ stream\~anything
+.BI .writec\~ stream\~contents
 As
 .BR write ,
-but without a trailing newline.
+but does not append a newline to
+.IR contents .
 .
 .
 .TP
diff --git a/man/groff_out.5.man b/man/groff_out.5.man
index a552be97c..5b26656de 100644
--- a/man/groff_out.5.man
+++ b/man/groff_out.5.man
@@ -127,12 +127,12 @@ rectangular page.
 In the following discussion,
 the term
 .I command
-refers to this intermediate output language,
+refers to this device-independent output language,
 never to the
 .MR groff @MAN7EXT@
 language intended for use by document authors.
 .
-Intermediate output commands comprise several categories:
+Device-independent output commands comprise several categories:
 glyph output;
 font,
 color,