[groff] 06/23: [docs]: Fix content and style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 22f7ce37467303547cdd37259f0f4f5735ae98c6
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu May 4 06:59:33 2023 -0500

    [docs]: Fix content and style nits.
    
    * Recast description of `bd`, `backtrace`, and `lf` requests.
    * Explicitly associate `bd` request with `.b` register.
    * Introduce metasyntactic variable `message` for use with `ab` and
      `tm`-family requests, since it is interpreted differenly from the
      `contents` argument of string assignment and appendment requests.
      Document that special character escape sequences in a `message` are
      not interpreted.
    * Clarify that groff_diff(7) details only GNU troff extensions.
    * Set default argument assumed by `af` request in bold.
    * Document behavior of `ce` and `rj` requests when used with negative
      agument.
    * Fully discuss `ce`, `cf`, and `trf`'s interfaces before presenting
      examples.
    * Use "file" instead of "filename" as metasyntactic variable name with
      requests.
---
 doc/groff.texi  | 131 ++++++++++++++++++++++++++--------------------------
 man/groff.7.man | 140 +++++++++++++++++++++++++++++++++++++-------------------
 2 files changed, 158 insertions(+), 113 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index bc4bcd084..2db5aea19 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -8144,8 +8144,14 @@ Break (unless the no-break control character is used), 
center the output
 of the next @var{nnn} productive input lines without filling, then break
 again (regardless of the control character).  The count of lines
 remaining to be centered is stored in the read-only register @code{.ce}
-and is associated with the environment
-(@pxref{Environments}).
+and is associated with the environment (@pxref{Environments}).
+@var{nnn} specifies the number of lines to be centered.  If the argument
+is not positive, centering is disabled.  Omitting the argument implies
+an @var{nnn} of @samp{1}.
+
+The basis for centering text is the line length (as set with the
+@code{ll} request) minus the indentation (as set with the @code{in}
+request).  Temporary indentation is ignored.
 
 @cindex @code{ce} request, difference from @w{@samp{.ad c}}
 While the @w{@samp{.ad c}} request also centers text, it fills the text
@@ -8172,14 +8178,6 @@ between the `.ce' and the `.ad c' requests.
     @result{}         the @quoteleft{}.ad c@quoteright{} requests.
 @endExample
 
-With no arguments, @code{ce} centers the next line of text.  @var{nnn}
-specifies the number of lines to be centered.  If the argument is zero
-or negative, centering is disabled.
-
-The basis for centering text is the line length (as set with the
-@code{ll} request) minus the indentation (as set with the @code{in}
-request).  Temporary indentation is ignored.
-
 The previous example illustrates a common idiom of turning centering on
 for a quantity of lines far in excess of what is required, and off again
 after the text to be centered.  This technique relieves humans of
@@ -8197,7 +8195,9 @@ of the next @var{nnn} productive input lines to the right 
margin without
 filling, then break again (regardless of the control character).  The
 count of lines remaining to be right-aligned is stored in the read-only
 register @code{.rj} and is associated with the environment
-(@pxref{Environments}).
+(@pxref{Environments}).  @var{nnn} specifies the number of lines to
+right-align.  If the argument is not positive, right-alignment is
+disabled.  Omitting the argument implies an @var{nnn} of @samp{1}.
 @endDefreq
 
 @DefreqList {ss, word-space-size [@Var{additional-sentence-space-size}]}
@@ -11328,8 +11328,8 @@ a non-negative font position or the name of a font.
 @DefregListEndx {.b}
 @cindex imitating boldface (@code{bd})
 @cindex boldface, imitating (@code{bd})
-Artificially create a bold font by printing each glyph twice, slightly
-offset.
+Embolden @var{font} by overstriking its glyphs offset by @var{offset}
+units minus one.
 
 Two syntax forms are available.
 
@@ -15714,8 +15714,27 @@ vice versa.
 Transparently output the contents of @var{file}.  Each line is output as
 if it were preceded by @code{\!}; however, the lines are @emph{not}
 subject to copy mode interpretation.  If the file does not end with a
-newline, then a newline is added (@code{trf} only).  For example, to
-define a macro@tie{}@code{x} containing the contents of
+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}
+@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.
+
+@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 @code{gtroff} input characters (@pxref{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
+@code{\!\\!}.
+
+To define a macro@tie{}@code{x} containing the contents of
 file@tie{}@file{f}, use
 
 @Example
@@ -15729,28 +15748,6 @@ file@tie{}@file{f}, use
 @noindent
 The calls to @code{ev} prevent the partially collected output line
 from becoming part of the diversion (@pxref{Diversions}).
-
-Both @code{trf} and @code{cf}, when used in a diversion, 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} @code{troff}, the contents of @var{file} are immediately
-copied through to the output regardless of whether there is a current
-diversion; this behaviour is so 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 @code{gtroff} input characters (@pxref{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
-@code{\!\\!}.
-
-Both requests cause a line break.
 @endDefreq
 
 @Defreq {nx, [@Var{file}]}
@@ -16302,23 +16299,23 @@ But we can fake it with `\&'.  |
 @endExample
 @endDefreq
 
-@DefreqList {psbb, filename}
+@DefreqList {psbb, file}
 @DefregItemx {llx}
 @DefregItemx {lly}
 @DefregItemx {urx}
 @DefregListEndx {ury}
 @cindex PostScript, bounding box
 @cindex bounding box
-Retrieve the bounding box of the PostScript image found in
-@var{filename}.  The file must conform to Adobe's @dfn{Document
-Structuring Conventions} (DSC); the command searches for a
-@code{%%BoundingBox} comment and extracts the bounding box values into
-the registers @code{llx}, @code{lly}, @code{urx}, and @code{ury}.  If an
-error occurs (for example, @code{psbb} cannot find the
-@code{%%BoundingBox} comment), it sets the four registers to zero.
-
-The search path for @var{filename} can be controlled with the
-@option{-I} command-line option.
+Retrieve the bounding box of the PostScript image found in @var{file},
+which must conform to Adobe's @dfn{Document Structuring Conventions}
+(DSC).  The request searches for a @code{%%BoundingBox} comment and
+extracts the bounding box values into the registers @code{llx},
+@code{lly}, @code{urx}, and @code{ury}.  If an error occurs (for
+example, @code{psbb} cannot find the @code{%%BoundingBox} comment), it
+sets the four registers to zero.
+
+The search path for @var{file} can be controlled with the @option{-I}
+command-line option.
 @endDefreq
 
 
@@ -16498,32 +16495,32 @@ environments, registers, and page location traps to 
the standard error
 stream.
 @c END Keep parallel with section "Debugging" of groff(7).
 
-@Defreq {lf, line [@Var{filename}]}
+@Defreq {lf, line [@Var{file}]}
 @pindex soelim
 @cindex multi-file documents
 @cindex documents, multi-file
 @cindex setting input line number (@code{lf})
 @cindex input line number, setting (@code{lf})
 @cindex number, input line, setting (@code{lf})
-Change the line number and optionally the file name GNU @code{troff}
-shall use for error and warning messages.  @var{line} is the input line
-number of the @emph{next} line.  Without an argument, the request is
-ignored.
-
-This request is primarily a debugging aid for documents that undergo
-preprocessing.  Programs like @command{tbl} that transform input in
-their own languages to @code{roff} requests use it so that any
-diagnostic messages emitted by @code{troff} correspond to the original
-source document.
+Set the input line number (and, optionally, the file name) GNU
+@code{troff} shall use for error and warning messages.  @var{line} is
+the input line number of the @emph{next} line.  Without an argument, the
+request is ignored.
+
+@code{lf}'s primary purpose is to aid the debugging of documents that
+undergo preprocessing.  Programs like @command{tbl} that transform input
+in their own languages intoto @code{roff} requests use it so that any
+diagnostic messages emitted by @code{troff} correspond to the source
+document.
 @endDefreq
 
-@DefreqList {tm, contents}
-@DefreqItemx {tm1, contents}
-@DefreqListEndx {tmc, contents}
+@DefreqList {tm, message}
+@DefreqItemx {tm1, message}
+@DefreqListEndx {tmc, message}
 @cindex printing to stderr (@code{tm}, @code{tm1}, @code{tmc})
 @cindex stderr, printing to (@code{tm}, @code{tm1}, @code{tmc})
-Send @var{contents}, which consumes the remainder of the input line, to
-the standard error stream.
+Send @var{message}, which consumes the remainder of the input line and
+cannot contain special characters, to the standard error stream.
 
 The @code{tm} request ignores leading spaces of @var{contents};
 @code{tm1} handles its argument similarly to the @code{ds} request: an
@@ -16534,9 +16531,9 @@ The @code{tmc} request is similar to @code{tm1} but 
does not append a
 newline (as is done in @code{tm} and @code{tm1}).
 @endDefreq
 
-@Defreq {ab, [@Var{contents}]}
+@Defreq {ab, [@Var{message}]}
 @cindex aborting (@code{ab})
-Write any @var{contents} to the standard error stream (like @code{tm})
+Write any @var{message} to the standard error stream (like @code{tm})
 and then abort GNU @code{troff}; that is, stop processing and terminate
 with a failure status.
 @endDefreq
@@ -16624,7 +16621,7 @@ This request causes a line break.
 @Defreq {backtrace, }
 @cindex backtrace of input stack (@code{backtrace})
 @cindex input stack, backtrace (@code{backtrace})
-Write a backtrace of the input stack to the standard error stream.
+Write the state of the input stack to the standard error stream.
 
 Consider the following in a file @file{test}.
 
diff --git a/man/groff.7.man b/man/groff.7.man
index a13b546a2..19951296c 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2240,6 +2240,14 @@ Escape sequences may generally be used freely in
 except when it is read in copy mode.
 .
 .TPx
+.I message
+is a character sequence to be emitted on the standard error stream.
+.
+Special character escape sequences are
+.I not
+interpreted.
+.
+.TPx
 .I n
 is a numeric expression.
 .
@@ -2317,7 +2325,9 @@ Not all details of request behavior are outlined here.
 .
 See the
 .I groff
-Texinfo manual or
+Texinfo manual or,
+for features new to GNU
+.IR troff , \" GNU
 .MR groff_diff @MAN7EXT@ .
 .
 .
@@ -2377,8 +2387,8 @@ indicate Roman numerals and basic Latin alphabetics,
 respectively,
 in the lettercase specified.
 .
-The default is \[lq]0\[rq].
-.
+The default is
+.BR 0 .
 .
 .TPx
 .REQ .aln "new old"
@@ -2490,28 +2500,49 @@ Unformat ASCII characters, spaces, and some escape 
sequences in
 .
 .TPx
 .REQ .backtrace
-Write a backtrace of the input stack to the standard error stream.
+Write the state of the input stack to the standard error stream.
 .
-Also see the
+See the
 .B \-b
 option of
 .MR groff @MAN1EXT@ .
 .
 .TPx
+.REQ .bd font
+Stop emboldening font
+.I font.
+.
+.TPx
 .REQ .bd "font N"
 Embolden
 .I font
-by
+by overstriking its glyphs offset by
 .IR N \-1
 units.
 .
+See
+.register .b .
+.
 .TPx
-.REQ .bd "S font N"
-Embolden Special Font
-.I S
-when current font is
-.IR font .
+.REQ .bd "special-font font"
+Stop emboldening
+.I special-font
+when
+.I font
+is selected.
+.
+.TPx
+.REQ .bd "special-font font N"
+Embolden
+.I special-font,
+overstriking its glyphs offset by
+.IR N \-1
+units when
+.I font
+is selected.
 .
+See
+.register .b .
 .
 .TPx
 .REQ .blm
@@ -2612,14 +2643,15 @@ productive input lines without filling,
 then break again.
 .
 If
-.IR npl =0,
+.I npl
+\[<=] 0,
 stop centering.
 .
 .TPx
-.REQ .cf "filename"
-Copy contents of file
-.I filename
-unprocessed to stdout or to the diversion.
+.REQ .cf file
+Copy contents of
+.I file
+without formatting to the (top-level) diversion.
 .
 .TPx
 .REQ .cflags "n c1 c2 \fR\&.\|.\|.\&\fP"
@@ -3659,23 +3691,24 @@ See
 Immediately jump to end of current file.
 .
 .TPx
-.REQ .nx "filename"
-Immediately continue processing with file
-.IR file .
+.REQ .nx file
+Stop formatting current file and begin reading
+.I file.
 .
 .TPx
-.REQ .open "stream filename"
+.REQ .open "stream file"
 Open
-.I filename
+.I file
 for writing and associate the stream named
 .I stream
 with it.
 .
 .TPx
-.REQ .opena "stream filename"
-Like
-.request .open
-but append to it.
+.REQ .opena "stream file"
+As
+.request .open ,
+but append to
+.I file.
 .
 .TPx
 .REQ .os
@@ -3779,9 +3812,16 @@ also see
 .esc[] s \[+-]N .
 .
 .TPx
-.REQ .psbb "filename"
-Get the bounding box of a PostScript image
-.IR filename .
+.REQ .psbb file
+Retrieve the bounding box of the PostScript image found in
+.I file,
+which must conform to Adobe's Document Structuring Conventions (DSC).
+.
+See registers
+.BR llx ,
+.BR lly ,
+.BR urx ,
+.BR ury .
 .
 .TPx
 .REQ .pso "command"
@@ -3857,7 +3897,8 @@ productive input lines without filling,
 then break again.
 .
 If
-.IR npl =0,
+.I npl
+\[<=] 0,
 stop right-aligning.
 .
 .TPx
@@ -4183,25 +4224,26 @@ Enable track kerning for
 Three-part title.
 .
 .TPx
-.REQ .tm contents
-Print
-.I contents
-on stderr.
+.REQ .tm message
+Write
+.I message,
+followed by a newline,
+to the standard error stream.
 .
 .TPx
-.REQ .tm1 contents
-Print
-.I anything
-on stderr,
+.REQ .tm1 message
+As
+.request .tm ,
 but an initial neutral double quote in
-.I contents
-is stripped off to allow embedding of leading spaces.
+.I message
+is removed,
+allowing it to contain leading spaces.
 .
 .TPx
-.REQ .tmc contents
-Similar to
-.request .tm1
-without emitting a final newline.
+.REQ .tmc message
+As
+.request .tm1 ,
+without emitting a newline.
 .
 .TPx
 .REQ .tr "abcd\fR\&.\|.\|.\&\fP"
@@ -4215,9 +4257,15 @@ to
 etc.\& on output.
 .
 .TPx
-.REQ .trf "filename"
-Transparently output the contents of file
-.IR filename .
+.REQ .trf file
+Transparently output the contents of
+.I file.
+.
+Unlike
+.request .cf ,
+invalid input characters in
+.I file
+are rejected.
 .
 .TPx
 .REQ .trin "abcd\fR\&.\|.\|.\&\fP"