gbranden pushed a commit to branch master
in repository groff.
commit 7e8ea73418fed81a13cd9294408f3a1b9a495950
Author: G. Branden Robinson <g.branden.robin...@gmail.com>
AuthorDate: Sun Mar 2 08:54:31 2025 -0600
[doc,man]: Fix content and style nits.
Clarify and tighten discussions of reading the rest of the input line
into request arguments. Update examples. Parallelize wording. Favor
active voice over passive.
---
doc/groff.texi.in | 193 ++++++++++++++++++++++++++++++++-------------------
man/groff.7.man | 101 ++++++++++++++++++---------
man/groff_diff.7.man | 66 ++++++++++--------
3 files changed, 228 insertions(+), 132 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index b954bf528..138610c73 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -7430,8 +7430,6 @@ Start a comment; read everything up to the next newline
in copy mode
It can be tricky to keep the comments from interfering with the
appearance of the output.
-@cindex @code{ds}, @code{ds1} requests, and comments
-@cindex @code{as}, @code{as1} requests, and comments
If the escape sequence is to the right of some text or a request, that
portion of the line is ignored, but GNU @command{troff} processes spaces
preceding it normally. This affects requests that read the remainder of
@@ -11468,9 +11466,13 @@ If
is absent,
the character is defined with empty contents.
-A leading neutral double quote in the second argument is stripped from
-it, allowing embedded leading spaces in @var{contents}, which is read to
-the end of the input line in copy mode.
+GNU
+@command{troff} @c GNU
+removes a leading neutral double quote from
+@var{contents}
+permitting initial embedded spaces,
+and reads it to the end of the input line in copy mode.
+@xref{Copy Mode}.
Defining (or redefining) a character @var{c} creates a formatter object
that is recognized like any other ordinary or special character on
@@ -12780,9 +12782,9 @@ Gray codes are explored in \*[cite Morgan 1998].
@cindex @code{ds} request, and comments
@cindex @code{ds1} request, and comments
@strong{Caution:@:}
-The
-@code{ds}
-request treats the remainder of the input line as its second argument,
+After the formatter has read the space character that ends the first
+argument,
+it treats the remainder of the input line as the second argument,
including trailing spaces,
up to a newline or comment escape sequence.
Ending string definitions
@@ -12793,37 +12795,48 @@ prevents unwanted space from creeping into them
during source document
maintenance.
@Example
-.ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O \" water
+.ds Si silicon \" use chemical symbol
+We observed a \*[Si]-based life form.
+ @result{} We observed a silicon -based life form.
@endExample
@noindent
-Instead, place the comment on another line or put the comment escape
-sequence immediately adjacent to the last character of the string.
+Instead,
+place the comment on another line
+or put the comment escape sequence immediately adjacent
+to the last character of the string.
@Example
-.ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O\" water
+.ds Si silicon\" use chemical symbol
+We observed a \*[Si]-based life form.
+ @result{} We observed a silicon-based life form.
@endExample
-Ending string definitions (and appendments) with a comment, even an
-empty one, prevents unwanted space from creeping into them during source
-document maintenance.
+Because the first space after the string name separates the arguments,
+you can retain it while using a comment to document an empty string.
@Example
.ds author Alice Pleasance Liddell\"
.ds friends \" empty; append to with .as
@endExample
-@cindex trailing double quotes in strings
-@cindex double quotes, trailing, in strings
-@cindex @code{ds} request, and double quotes
-@cindex leading spaces with @code{ds}
-@cindex spaces with @code{ds}
-@cindex @code{ds} request, and leading spaces
-The formatter removes a leading neutral double quote @code{"} in
-@var{contents} to permit the embedding of leading spaces. Any other
-@code{"} is interpreted literally, but it is wise to use the special
-character escape sequence @code{\[dq]} instead if the string might be
-interpolated as part of a macro argument; see @ref{Calling Macros}.
+@cindex @code{ds} and @code{ds1} requests, arguments starting with double
quote @code{"}, and comments
+@cindex leading spaces in @code{ds} and @code{ds1} argument
+@cindex spaces in @code{ds} and @code{ds1} argument, leading
+@cindex @code{ds} and @code{ds1} request, and leading spaces
+The formatter removes a leading neutral double quote
+@samp{"}
+from
+@var{contents}
+to permit the embedding of leading spaces.
+It interprets any other
+@samp{"}
+literally,
+but the wise author uses the special character escape sequence
+@code{\[dq]}
+instead if the string
+might be interpolated as part of a macro argument;
+see @ref{Calling Macros}.
@c Examples should be more accessible than Unix nerd stuff like this,
@c but in general document authors shouldn't want to use "straight"
@@ -12898,6 +12911,17 @@ the string).
.as salutation " with shallots, onions and garlic,\"
@endExample
+@cindex @code{as} and @code{as1} requests, arguments starting with double
quote @code{"}, and comments
+@strong{Caution:@:}
+The formatter reads the second argument to the end of the line
+in copy mode,
+omitting any leading neutral double quote
+@samp{"}
+character.
+See the discussion of the
+@code{ds}
+request above.
+
The @code{as1} request works as does @code{as}, but like @code{ds1}, it
brackets @var{contents} with @slanted{compatibility save} and
@slanted{restore} tokens.
@@ -12921,9 +12945,10 @@ can be manipulated through renaming, removal, and
aliasing (@code{rn},
Compute the number of characters in @var{contents} and store the count
in the register @var{reg}. If @var{reg} doesn't exist, it is created.
-A leading neutral double quote in the argument is stripped from it,
-allowing embedded leading spaces in @var{contents}, which is read to
-the end of the input line in copy mode.
+GNU
+@command{troff} @c GNU
+removes a leading neutral double quote from the argument to the request,
+permitting embedded leading spaces.
@Example
.ds xxx abcd\h'3i'efgh
@@ -12933,11 +12958,9 @@ the end of the input line in copy mode.
@endExample
@strong{Caution:@:}
-The
-@code{length}
-request treats the remainder of the input line as its second argument,
-including trailing spaces,
-up to a newline or comment escape sequence.
+GNU
+@command{troff} @c GNU
+reads the second argument to the end of the line in copy mode.
See the discussion of the
@code{ds}
request above.
@@ -15968,9 +15991,13 @@ no output at all; its argument is simply ignored.
Emit @var{contents} directly to GNU @command{troff}'s output; this usage
is similar to that of @code{\!} in the top-level diversion.
-A leading neutral double quote in the argument to @code{output} is
-stripped from it, allowing embedded leading spaces in @var{contents},
-which is read to the end of the input line in copy mode.
+GNU
+@command{troff} @c GNU
+removes a leading neutral double quote from
+@var{contents}
+permitting initial embedded spaces,
+and reads it to the end of the input line in copy mode.
+Recall @ref{Copy Mode}.
@strong{Caution:@:} Use of these features can put syntactically invalid
content into GNU @command{troff}'s output, which @code{groff}'s output
@@ -16467,17 +16494,19 @@ with or without inclusion of their output in the
document.
@cindex trailing spaces in file name or system command arguments
@cindex comments, after file name or system command arguments
-@cindex @code{cf} request, and comments
-@cindex @code{mso} request, and comments
-@cindex @code{msoquiet} request, and comments
-@cindex @code{nx} request, and comments
-@cindex @code{open} request, and comments
-@cindex @code{opena} request, and comments
-@cindex @code{pi} request, and comments
-@cindex @code{so} request, and comments
-@cindex @code{soquiet} request, and comments
-@cindex @code{sy} request, and comments
-@cindex @code{trf} request, and comments
+@cindex @code{"}, at the start of a request argument
+@cindex double quote, at the start of a request argument
+@cindex @code{cf} request, arguments starting with double quote @code{"}, and
comments
+@cindex @code{mso} request, arguments starting with double quote @code{"}, and
comments
+@cindex @code{msoquiet} request, arguments starting with double quote
@code{"}, and comments
+@cindex @code{nx} request, arguments starting with double quote @code{"}, and
comments
+@cindex @code{open} request, arguments starting with double quote @code{"},
and comments
+@cindex @code{opena} request, arguments starting with double quote @code{"},
and comments
+@cindex @code{pi} request, arguments starting with double quote @code{"}, and
comments
+@cindex @code{so} request, arguments starting with double quote @code{"}, and
comments
+@cindex @code{soquiet} request, arguments starting with double quote @code{"},
and comments
+@cindex @code{sy} request, arguments starting with double quote @code{"}, and
comments
+@cindex @code{trf} request, arguments starting with double quote @code{"}, and
comments
@strong{Caution:@:}
The requests discussed below that accept a file name or system command
as an argument treat the remainder of the input line as that argument,
@@ -16487,6 +16516,11 @@ Suffixing the file name or command with a comment,
even an empty one,
prevents unwanted space from creeping into it during source document
maintenance.
+GNU
+@command{troff} @c GNU
+removes a leading neutral double quote from such arguments
+permitting initial embedded spaces,
+and reads it to the end of the input line in copy mode.
Recall the discussion of the
@code{ds}
request in @ref{Strings}.
@@ -16940,11 +16974,12 @@ or other postprocessor.
@cindex @code{device} request, and copy mode
@cindex copy mode, and @code{device} request
@cindex mode, copy, and @code{device} request
+@cindex @code{device} request, arguments starting with double quote @code{"},
and comments
GNU
@command{troff} @c GNU
-strips a leading neutral double quote from
+removes a leading neutral double quote from
@var{contents}
-to permit initial embedded spaces,
+permitting initial embedded spaces,
and reads it to the end of the input line in copy mode.
Recall @ref{Copy Mode}.
@@ -17442,6 +17477,7 @@ error stream.
@cindex assign input line number request (@code{lf})
@cindex input line number, assignment, request (@code{lf})
@cindex number, input line, assignment request (@code{lf})
+@cindex @code{lf} request, arguments starting with double quote @code{"}, and
comments
Set the input line number
(and,
optionally,
@@ -17449,22 +17485,20 @@ the file name)
GNU
@command{troff}
uses when reporting diagnostics.
-@var{line}
-is the input line number of the
+The argument becomes the input line number of the
@emph{next}
-line.
+line the formatter reads.
@var{file-identifier}
is a sequence of ordinary characters and/or spaces.
@c XXX: or tabs, leaders, backspace, and delete characters
@c ...limiting the file names you can express; see Savannah #65108.
GNU
-@command{troff}
-strips a leading leading neutral double quote from
-@var{file-identifier},
-which it reads in copy mode
-(recall
-@ref{Copy Mode}),
-allowing it to contain embedded leading spaces.
+@command{troff} @c GNU
+removes a leading neutral double quote from
+@var{file-identifier}
+permitting initial embedded spaces,
+and reads it to the end of the input line in copy mode.
+Recall @ref{Copy Mode}.
@code{lf}'s primary purpose is to aid the debugging of documents that
undergo preprocessing. Programs like @command{tbl} that transform input
@@ -17473,20 +17507,31 @@ diagnostic messages emitted by @code{troff}
correspond to the source
document.
@endDefreq
-@DefreqList {tm, message}
+@DefreqList {tm, terminal-message}
@DefreqItemx {tm1, [@code{"}]message}
@DefreqListEndx {tmc, [@code{"}]message}
@cindex print to the standard error stream (@code{tm}, @code{tm1}, @code{tmc})
@cindex standard error stream, write to (@code{tm}, @code{tm1}, @code{tmc})
@cindex stream, standard error, write to (@code{tm}, @code{tm1}, @code{tmc})
-Send @var{message}, which consumes the remainder of the input line and
-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, allowing leading embedded spaces in @var{message}.
-
-@code{tmc} works as @code{tm1}, but does not append a newline.
+Send
+@var{terminal-message}
+to the standard error stream.
+The formatter reads the argument
+to the end of the input line in copy mode,
+but does
+@emph{not}
+removing a leading double quote;
+contrast
+@code{tm1}.
+
+@code{tm1}
+removes a leading neutral double quote from
+@var{message},
+allowing leading embedded spaces.
+
+@code{tmc} works as
+@code{tm1},
+but does not append a newline.
@endDefreq
@Defreq {ab, [@Var{message}]}
@@ -18378,13 +18423,14 @@ values of minimum inter-word and additional
inter-sentence space are
each rounded down to the nearest multiple of@tie{}12.
@cindex @code{cf} request, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{lf} request, incompatibilities with @acronym{AT&T} @code{troff}
@cindex @code{nx} request, incompatibilities with @acronym{AT&T} @code{troff}
@cindex @code{pi} request, incompatibilities with @acronym{AT&T} @code{troff}
@cindex @code{so} request, incompatibilities with @acronym{AT&T} @code{troff}
@cindex @code{sy} request, incompatibilities with @acronym{AT&T} @code{troff}
GNU
@command{troff}
-strips a leading neutral double quote from the argument to the
+removes a leading neutral double quote from the argument to the
@code{cf},
@code{nx},
@code{pi},
@@ -18392,7 +18438,12 @@ strips a leading neutral double quote from the
argument to the
and
@code{sy}
requests,
-allowing it to contain embedded leading spaces.
+and the second argument
+(if present)
+to the
+@code{lf}
+request,
+permitting embedded leading spaces.
@cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff}
@cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff}
diff --git a/man/groff.7.man b/man/groff.7.man
index e024d385e..79a557190 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -435,15 +435,35 @@ The neutral double quote can be used to enclose arguments
to macros and
strings,
and is required if those arguments contain space or tab characters.
.
-In the
+The requests
+.RB \[lq] as \[rq],
+.request as1 ,
+.request cf ,
+.request char ,
.request ds ,
.request ds1 ,
-.RB \[lq] as \[rq],
+.request fchar ,
+.request fschar ,
+.request mso ,
+.request msoquiet ,
+.request nx ,
+.RB \[lq] open \[rq],
+.request opena ,
+.request pi ,
+.request schar ,
+.RB \[lq] so \[rq],
+.request soquiet ,
+.request sy ,
and
-.request as1
-requests,
-a leading neutral double quote in the second argument is stripped off
+.request trf
+strip a leading neutral double quote
+from their final arguments
to allow embedding of leading spaces.
+All such arguments are \[lq]strings\[rq] in a general sense,
+representing character sequences,
+file names,
+operating system commands,
+or parameters to an output device extension command.
.
To include a double quote inside a quoted argument,
use the
@@ -2444,12 +2464,15 @@ reads arguments named
.I file,
and
.I message
-in copy mode until the end of the input line;
+in copy mode
+(see section \[lq]Copy Mode\[rq] below)
+until the end of the input line;
they thus can contain embedded spaces.
.
-They can also be optionally prefixed with a neutral double quote
-.BR \[dq] ,
-which the formatter discards if present,
+A neutral double quote
+.RB \[oq] \[dq] \[cq] \" single quotes around double quote
+can optionally prefix these;
+the formatter discards one if present,
permitting leading spaces in the argument.
.
.
@@ -3723,15 +3746,21 @@ expression
.IR b .
.
.TPx
-.REQ .lf n
-Set number of next input line to
-.IR n .
+.REQ .lf input-line-number
+Set the input line number
+GNU
+.I troff \" GNU
+uses when reporting diagnostics.
+The argument becomes the input line number of the
+.I next
+line the formatter reads.
.
.TPx
-.REQ .lf "n file-identifier"
-Set number of next input line to
-.I n
-and report input file name as
+.REQ .lf "input-line-number file-identifier"
+As
+.B lf
+with one argument,
+but also update the reported file name to
.IR file-identifier ,
a sequence of ordinary characters and/or spaces.
.\" XXX: or tabs, leaders, backspace, and delete characters
@@ -3739,7 +3768,7 @@ a sequence of ordinary characters and/or spaces.
.
GNU
.I troff \" GNU
-strips a leading leading neutral double quote from
+removes a leading leading neutral double quote from
.IR file-identifier ,
allowing it to contain embedded leading spaces.
.
@@ -4718,17 +4747,16 @@ Write a newline to the standard error stream.
.
.TPx
.REQ .tm terminal-message
-Write
-.I terminal-message,
+Send
+.IR terminal-message ,
followed by a newline,
to the standard error stream.
-.
-.I terminal-message
-is read in copy mode to the end of the input line,
+The formatter reads the argument
+to the end of the input line in copy mode,
but does
.I not
-recognize and strip a leading double quote;
-see
+remove a leading double quote;
+contrast
.BR .tm1 .
.
.TPx
@@ -4740,9 +4768,9 @@ As
.REQ .tm1 message
As
.request .tm ,
-but recognizes and strips a leading neutral double quote,
-allowing embedded leading spaces in
-.IR message .
+but removes a leading neutral double quote from
+.IR message ,
+allowing embedded leading spaces.
.
.TPx
.REQ .tmc
@@ -4752,7 +4780,7 @@ No operation.
.REQ .tmc message
As
.request .tm1 ,
-without emitting a newline.
+but does not append a newline.
.
.TPx
.REQ .tr abcd\fR\&.\|.\|.\&\fP
@@ -6154,10 +6182,19 @@ If
is called with only one argument,
the named string becomes empty.
.
-Otherwise,
-.I @g@troff
-stores the remainder of the control line in copy mode;
-see subsection \[lq]Copy mode\[rq] below.
+The formatter removes a leading neutral double quote
+.RB \[oq] \[dq] \[cq] \" single quotes around double quote
+from
+.I contents
+to permit the embedding of leading spaces.
+It interprets any other
+.RB \[oq] \[dq] \[cq] \" single quotes around double quote
+literally,
+but the wise author uses the special character escape sequence
+.B \[rs][dq]
+instead if the string
+might be interpolated as part of a macro argument;
+see section \[lq]Calling macros\[rq] above.
.
.
.P
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 2ad254ea1..419d3c6ea 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -2062,6 +2062,15 @@ If
is absent,
the character is defined with empty contents.
.
+GNU
+.I troff \" GNU
+removes a leading neutral double quote from
+.IR contents ,
+permitting initial embedded spaces,
+and reads it to the end of the input line in copy mode.
+See section \[lq]Copy Mode\[rq] of
+.MR groff @MAN7EXT@ .
+.
.
.IP
Defining
@@ -2266,11 +2275,11 @@ request.
Close the named
.IR stream ,
invalidating it as an argument to the
-.B write
+.RB \[lq] write \[rq]
request.
.
See
-.BR open .
+.RB \[lq] open \[rq].
.
.
.TP
@@ -3301,7 +3310,7 @@ and
.RB [ \[dq] ]\c
.I file
As
-.BR open ,
+.RB \[lq] open \[rq],
but if
.I file
exists,
@@ -3831,17 +3840,17 @@ the increase in width is a linear function of the type
size.
.IR message ]
As
.BR tm ,
-but recognizes and strips a leading neutral double quote,
-allowing embedded leading spaces in
-.IR message .
+but
+removes a leading neutral double quote from
+.IR message ,
+permitting initial embedded spaces.
.
.
.TP
.BR .tmc \~[[ \[dq] ]\c
.IR message ]
As
-.B tm1
-request,
+.BR tm1 ,
but does not append a newline.
.
.
@@ -4101,7 +4110,7 @@ flushes the stream after writing to it.
.RB [[ \[dq] ]\c
.IR character-sequence ]
As
-.BR write ,
+.RB \[lq] write \[rq],
but does not append a newline to
.IR contents .
.
@@ -4166,8 +4175,8 @@ this behavior is so anomalous that it must be considered
a bug.
.IP
GNU
.I troff \" GNU
-strips a leading neutral double quote from the argument,
-allowing it to contain embedded leading spaces.
+removes a leading neutral double quote from the argument,
+permitting initial embedded spaces.
.
Further,
spaces in
@@ -4221,18 +4230,18 @@ request is selected.
.
.
.TP
-.BI .lf\~ next-line-number\~\c
+.BI .lf\~ input-line-number\~\c
.RB [[ \[dq] ]\c
.IR file-identifier ]
-GNU
+In GNU
.I troff \" GNU
-strips a leading neutral double quote from the optional second argument,
-allowing it to contain embedded leading spaces.
-.
-Further,
-non-leading spaces in
-.I file-identifier
-are also accepted.
+the first argument becomes the input line number of the
+.I next
+line the formatter reads.
+It also
+removes a leading neutral double quote from
+.IR file-identifier ,
+permitting initial embedded spaces.
.
.
.TP
@@ -4240,8 +4249,8 @@ are also accepted.
.IR file ]
GNU
.I troff \" GNU
-strips a leading neutral double quote from the optional argument,
-allowing it to contain embedded leading spaces.
+removes a leading neutral double quote from the optional argument,
+permitting initial embedded spaces.
.
Further,
spaces in
@@ -4255,7 +4264,7 @@ are accepted as part of the file name.
GNU
.I troff \" GNU
strips a leading neutral double quote from the argument,
-allowing it to contain embedded leading spaces.
+permitting initial embedded spaces.
.
.
.TP
@@ -4264,7 +4273,7 @@ allowing it to contain embedded leading spaces.
GNU
.I troff \" GNU
strips a leading neutral double quote from the argument,
-allowing it to contain embedded leading spaces.
+permitting initial embedded spaces.
.
Further,
spaces in
@@ -4298,7 +4307,7 @@ Negative values are erroneous.
GNU
.I troff \" GNU
strips a leading neutral double quote from the argument,
-allowing it to contain embedded leading spaces.
+permitting initial embedded spaces.
.
.
.TP
@@ -6263,12 +6272,11 @@ inter-sentence space each to the nearest multiple
of\~12.
.P
GNU
.I troff \" GNU
-strips a leading neutral double quote from the argument to the
+removes a leading neutral double quote from the argument to the
.BR cf ,
.BR nx ,
.BR pi ,
-and
-.BR so ,
+.RB \[lq] so \[rq],
and
.B sy
requests,
@@ -6277,7 +6285,7 @@ and the second argument
to the
.B lf
request,
-allowing it to contain embedded leading spaces.
+permitting initial embedded spaces.
.
.
.P
_______________________________________________
groff-commit mailing list
groff-commit@gnu.org
https://lists.gnu.org/mailman/listinfo/groff-commit
