gbranden pushed a commit to branch master
in repository groff.
commit ef5ef6bc2bfbf466d02f2e0e888efce5e818aae6
Author: G. Branden Robinson <[email protected]>
AuthorDate: Fri Mar 14 22:41:46 2025 -0500
[doc,man]: Fix content and style nits.
Clarify and tighten discussions of reading the rest of the input line
into request arguments (again). Parallelize wording. Favor active
voice over passive.
---
doc/groff.texi.in | 108 ++++++++++++++++++++++++++++++++-------------------
man/groff.7.man | 51 ++++++++++++------------
man/groff_diff.7.man | 58 ++++++++++++++-------------
3 files changed, 124 insertions(+), 93 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 8e3fcd455..37f739cbd 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -9005,7 +9005,7 @@ hyphenation patterns with the new ones. Invoking
@code{hpf} or
loaded at startup, or in a macro package), GNU @code{troff} won't
automatically hyphenate at all.
-@cindex trailing spaces in file name arguments
+@cindex spaces in file name arguments
@cindex comments, after file name arguments
@cindex @code{hpf} request, and comments
@cindex @code{hpfa} request, and comments
@@ -9016,7 +9016,7 @@ and
@code{hpfa}
requests interpret the remainder of the input line as the file name
argument,
-including trailing spaces,
+including any spaces,
up to a newline or comment escape sequence.
Suffixing the file name with a comment,
even an empty one,
@@ -11429,7 +11429,7 @@ after the character can't be suppressed since the
neighboring character
on the right doesn't get examined.
@endDefreq
-@cindex trailing spaces in character definitions
+@cindex spaces in character definitions
@cindex comments, after character definitions
@cindex @code{char} request, and comments
@cindex @code{fchar} request, and comments
@@ -11468,9 +11468,11 @@ the character is defined with empty contents.
GNU
@command{troff} @c GNU
-removes a leading neutral double quote from
-@var{contents}
-permitting initial embedded spaces,
+removes a leading neutral double quote
+@samp{"}
+from
+@var{contents},
+permitting initial embedded spaces in it,
and reads it to the end of the input line in copy mode.
@xref{Copy Mode}.
@@ -11534,9 +11536,11 @@ request, but before the already mounted special fonts.
@xref{Character Classes}.
@strong{Caution:@:}
-These requests treats the remainder of the input line
+These requests remove a leading neutral double quote
+@samp{"}
+and treat the remainder of the input line
as their second argument,
-including trailing spaces,
+including any spaces,
up to a newline or comment escape sequence.
See the discussion of the
@code{ds}
@@ -12775,7 +12779,7 @@ Gray codes are explored in \*[cite Morgan 1998].
@c @result{} I see a big, hairy wildebeest.
@c @endExample
-@cindex trailing spaces in string definitions and appendments
+@cindex spaces in string definitions and appendments
@cindex comments, with string definitions and appendments
@cindex @code{as} request, and comments
@cindex @code{as1} request, and comments
@@ -12785,7 +12789,7 @@ Gray codes are explored in \*[cite Morgan 1998].
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,
+including any spaces,
up to a newline or comment escape sequence.
Ending string definitions
(and appendments)
@@ -12827,8 +12831,9 @@ you can retain it while using a comment to document an
empty string.
The formatter removes a leading neutral double quote
@samp{"}
from
-@var{contents}
-to permit the embedding of leading spaces.
+@var{contents},
+permitting initial embedded spaces in it.
+@c We briefly introduce and discuss "copy mode" below.
It interprets any other
@samp{"}
literally,
@@ -12836,7 +12841,7 @@ 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}.
+recall @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"
@@ -12933,7 +12938,7 @@ Strings can be queried (@code{length}) and modified
(@code{chop},
can be manipulated through renaming, removal, and aliasing (@code{rn},
@code{rm}, @code{als}).
-@cindex trailing spaces in string length measurement
+@cindex spaces in string length measurement
@cindex comments, with string length measurements
@cindex @code{length} request, and comments
@Defreq {length, reg [[@code{"}]@Var{contents}]}
@@ -12947,8 +12952,13 @@ in the register @var{reg}. If @var{reg} doesn't
exist, it is created.
GNU
@command{troff} @c GNU
-removes a leading neutral double quote from the argument to the request,
-permitting embedded leading spaces.
+removes a leading neutral double quote
+@samp{"}
+from
+@var{length},
+permitting initial embedded spaces in it,
+and reads it to the end of the input line in copy mode.
+@xref{Copy Mode}.
@Example
.ds xxx abcd\h'3i'efgh
@@ -12957,10 +12967,13 @@ permitting embedded leading spaces.
@result{} 14
@endExample
+@cindex @code{length} request, arguments starting with double quote @code{"},
and comments
@strong{Caution:@:}
-GNU
-@command{troff} @c GNU
-reads the second argument to the end of the line in copy mode.
+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.
@@ -15993,9 +16006,11 @@ is similar to that of @code{\!} in the top-level
diversion.
GNU
@command{troff} @c GNU
-removes a leading neutral double quote from
-@var{contents}
-permitting initial embedded spaces,
+removes a leading neutral double quote
+@samp{"}
+from
+@var{anything}, @c TODO: -> character-sequence
+permitting initial embedded spaces in it,
and reads it to the end of the input line in copy mode.
Recall @ref{Copy Mode}.
@@ -16501,7 +16516,7 @@ Enabling unsafe mode at the command line permits
the writing of files and execution of external commands,
with or without inclusion of their output in the document.
-@cindex trailing spaces in file name or system command arguments
+@cindex spaces in file name or system command arguments
@cindex comments, after file name or system command arguments
@cindex @code{"}, at the start of a request argument
@cindex double quote, at the start of a request argument
@@ -16519,7 +16534,7 @@ with or without inclusion of their output in the
document.
@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,
-including trailing spaces,
+including any spaces,
up to a newline or comment escape sequence.
Suffixing the file name or command with a comment,
even an empty one,
@@ -16527,12 +16542,12 @@ 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,
+removes a leading neutral double quote
+@samp{"}
+from such an argument,
+permitting initial embedded spaces in it,
and reads it to the end of the input line in copy mode.
-Recall the discussion of the
-@code{ds}
-request in @ref{Strings}.
+Recall @ref{Copy Mode}.
@DefreqList {so, [@code{"}]@Var{file}}
@DefreqListEndx {soquiet, [@code{"}]@Var{file}}
@@ -17044,9 +17059,11 @@ or other postprocessor.
@cindex @code{device} request, arguments starting with double quote @code{"},
and comments
GNU
@command{troff} @c GNU
-removes a leading neutral double quote from
-@var{contents}
-permitting initial embedded spaces,
+removes a leading neutral double quote
+@samp{"}
+from
+@var{contents},
+permitting initial embedded spaces in it,
and reads it to the end of the input line in copy mode.
Recall @ref{Copy Mode}.
@@ -17583,9 +17600,11 @@ is a sequence of ordinary characters and/or spaces.
@c ...limiting the file names you can express; see Savannah #65108.
GNU
@command{troff} @c GNU
-removes a leading neutral double quote from
-@var{file-identifier}
-permitting initial embedded spaces,
+removes a leading neutral double quote
+@samp{"}
+from
+@var{file-identifier},
+permitting initial embedded spaces in it,
and reads it to the end of the input line in copy mode.
Recall @ref{Copy Mode}.
@@ -17606,7 +17625,8 @@ Send
@var{terminal-message}
to the standard error stream.
The formatter reads the argument
-to the end of the input line in copy mode,
+to the end of the input line in copy mode
+(@pxref{Copy Mode}),
but does
@emph{not}
removing a leading double quote;
@@ -17614,9 +17634,11 @@ contrast
@code{tm1}.
@code{tm1}
-removes a leading neutral double quote from
-@var{message},
-allowing leading embedded spaces.
+removes a leading neutral double quote
+@samp{"}
+from
+@var{contents},
+permitting initial embedded spaces in it.
@code{tmc} works as
@code{tm1},
@@ -18534,7 +18556,9 @@ each rounded down to the nearest multiple of@tie{}12.
@cindex @code{sy} request, incompatibilities with @acronym{AT&T} @code{troff}
GNU
@command{troff}
-removes a leading neutral double quote from the argument to the
+removes a leading neutral double quote
+@samp{"}
+from the argument to the
@code{cf},
@code{nx},
@code{pi},
@@ -18547,7 +18571,9 @@ and the second argument
to the
@code{lf}
request,
-permitting embedded leading spaces.
+permitting initial embedded spaces in it,
+and reads it to the end of the input line in copy mode.
+Recall @ref{Copy Mode}.
@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 2eb25c7fc..8df70d755 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2466,14 +2466,27 @@ and
.I message
in copy mode
(see section \[lq]Copy Mode\[rq] below)
-until the end of the input line;
-they thus can contain embedded spaces.
+until the end of the input line.
+.
+A
+.I character-sequence
+comprises one or more ordinary,
+special,
+or indexed characters;
+spaces;
+or escape sequences that interpolate only these.
+.\" XXX: or tabs, leaders, backspace, and delete characters
+.
+The remaining argument names named for clarity;
+they are also
+.I character-sequences.
.
A neutral double quote
.RB \[oq] \[dq] \[cq] \" single quotes around double quote
-can optionally prefix these;
+can optionally prefix a
+.I character-sequence;
the formatter discards one if present,
-permitting leading spaces in the argument.
+permitting initial embedded spaces in the argument.
.
.
.P
@@ -3756,22 +3769,14 @@ The argument becomes the input line number of the
line the formatter reads.
.
.TPx
-.REQ .lf "input-line-number file-identifier"
+.REQ .lf "input-line-number character-sequence"
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
+.IR character-sequence .
.\" ...limiting the file names you can express; see Savannah #65108.
.
-GNU
-.I troff \" GNU
-removes a leading leading neutral double quote from
-.IR file-identifier ,
-allowing it to contain embedded leading spaces.
-.
.TPx
.REQ .lg
Enable ligature mode
@@ -4783,9 +4788,12 @@ As
.REQ .tm1 message
As
.request .tm ,
-but removes a leading neutral double quote from
+but removes a leading neutral double quote
+.RB \[oq] \[dq] \[cq]
+from
.IR message ,
-allowing embedded leading spaces.
+permitting initial embedded spaces in it,
+and reads it to the end of the input line in copy mode.
.
.TPx
.REQ .tmc
@@ -6202,6 +6210,7 @@ The formatter removes a leading neutral 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,
@@ -6241,13 +6250,7 @@ argument interpolations must be escaped if they are to
reference
parameters from the calling context;
see section \[lq]Parameters\[rq] below.
.
-.
-.P
-The formatter removes a leading neutral double quote
-.B \[dq]
-in the string contents to permit the embedding of leading spaces.
-.
-Any other
+Any non-initial neutral double quote
.B \[dq]
is interpreted literally,
but it is wise to use the special character escape sequence
@@ -6327,7 +6330,7 @@ string is later interpolated.
.I Caution:
These requests treat the remainder of the input line
as their second argument,
-including trailing spaces,
+including any spaces,
up to a newline or comment escape sequence.
.
Ending string definitions
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index fd0020a63..6b7891a58 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1771,9 +1771,6 @@ nodes such as those produced by
will remain nodes,
so the result cannot be guaranteed to be a pure string.
.
-See section \[lq]Copy mode\[rq] in
-.MR groff @MAN7EXT@ .
-.
Glyph parameters such as the type face and size are not preserved;
use
.B unformat
@@ -2066,12 +2063,12 @@ the character is defined with empty contents.
.
GNU
.I troff \" GNU
-removes a leading neutral double quote from
+removes a leading neutral double quote
+.RB \[oq] \[dq] \[cq]
+from
.IR contents ,
-permitting initial embedded spaces,
+permitting initial embedded spaces in it,
and reads it to the end of the input line in copy mode.
-See section \[lq]Copy Mode\[rq] of
-.MR groff @MAN7EXT@ .
.
.
.IP
@@ -3856,9 +3853,11 @@ the increase in width is a linear function of the type
size.
As
.BR tm ,
but
-removes a leading neutral double quote from
+removes a leading neutral double quote
+.RB \[oq] \[dq] \[cq]
+from
.IR message ,
-permitting initial embedded spaces.
+permitting initial embedded spaces in it.
.
.
.TP
@@ -4190,13 +4189,11 @@ this behavior is so anomalous that it must be
considered a bug.
.IP
GNU
.I troff \" GNU
-removes a leading neutral double quote from the argument,
-permitting initial embedded spaces.
-.
-Further,
-spaces in
-.I file
-are accepted as part of the file name.
+removes a leading neutral double quote
+.RB \[oq] \[dq] \[cq]
+from the argument,
+permitting initial embedded spaces in it,
+and reads it to the end of the input line in copy mode.
.
.
.br
@@ -4254,9 +4251,12 @@ 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.
+removes a leading neutral double quote
+.RB \[oq] \[dq] \[cq]
+from
+.IR contents ,
+permitting initial embedded spaces in it,
+and reads it to the end of the input line in copy mode.
.
.
.TP
@@ -4264,13 +4264,12 @@ permitting initial embedded spaces.
.IR file ]
GNU
.I troff \" GNU
-removes a leading neutral double quote from the optional argument,
-permitting initial embedded spaces.
-.
-Further,
-spaces in
-.I file
-are accepted as part of the file name.
+removes a leading neutral double quote
+.RB \[oq] \[dq] \[cq]
+from
+.IR file ,
+permitting initial embedded spaces in it,
+and reads it to the end of the input line in copy mode.
.
.
.TP
@@ -6289,7 +6288,9 @@ inter-sentence space each to the nearest multiple of\~12.
.P
GNU
.I troff \" GNU
-removes a leading neutral double quote from the argument to the
+removes a leading neutral double quote
+.RB \[oq] \[dq] \[cq]
+from the argument to the
.BR cf ,
.BR nx ,
.BR pi ,
@@ -6302,7 +6303,8 @@ and the second argument
to the
.B lf
request,
-permitting initial embedded spaces.
+permitting initial embedded spaces in it,
+and reads it to the end of the input line in copy mode.
.
.
.P
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
