gbranden pushed a commit to branch master
in repository groff.
commit 16935b78eefbd7c2cc10dd3fec9a641ed06ed8e4
Author: G. Branden Robinson <[email protected]>
AuthorDate: Wed Jan 1 22:51:44 2025 -0600
[doc,man]: Doc generalized multi-word arg syntax.
...more comprehensively.
NEWS: Clarify item.
---
NEWS | 6 +++---
doc/groff.texi.in | 36 ++++++++++++++++++++++++++----------
man/groff.7.man | 27 ++++++++++++++++++++++-----
man/groff_diff.7.man | 2 ++
4 files changed, 53 insertions(+), 18 deletions(-)
diff --git a/NEWS b/NEWS
index 13741f5dc..71d733c52 100644
--- a/NEWS
+++ b/NEWS
@@ -70,9 +70,9 @@ troff
leading spaces.
* GNU troff now accepts space characters in the argument to the `cf`,
- `hpf`, `hpfa`, `mso`, `msoquiet`, `nx`, `so`, `soquiet`, and `trf`
- requests, and the second argument to the `open` and `opena` requests.
- See "soelim" below.
+ `hpf`, `hpfa`, `mso`, `msoquiet`, `nx`, `pi`, `so`, `soquiet`, and
+ `trf` requests, and the second argument to the `open` and `opena`
+ requests. See "soelim" below.
* The "el" warning category has been withdrawn. If enabled (which it
was not by default), the formatter would emit a diagnostic if it
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index c81fb02b3..7f9a1064e 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -16384,7 +16384,7 @@ and the request has no further effect.
@xref{Warnings}, for
information about the enablement and suppression of warnings.
GNU @command{troff} strips a leading neutral double quote from the
-argument, allowing embedded leading spaces in @var{contents}.
+argument, allowing embedded leading spaces in @var{file}.
@code{so} can be useful for large documents; e.g., allowing each chapter
of a book to be kept in a separate file. However, files interpolated
@@ -16465,6 +16465,9 @@ Both requests break the line before reading
@var{file},
unless invoked with the no-break control character.
+GNU @command{troff} strips a leading neutral double quote from the
+argument, allowing embedded leading spaces in @var{file}.
+
When used in a diversion, these requests embed a node (@pxref{Gtroff
Internals}) in it that, when interpolated, causes the contents of
@var{file} to be copied to the output. In @acronym{AT&T} @code{troff},
@@ -16512,6 +16515,9 @@ from becoming part of the diversion
(@pxref{Diversions}).
@cindex next file, read (@code{nx})
Stop processing the input file. If @var{file} is specified, read it;
otherwise, read the next pending input file, if any.
+
+GNU @command{troff} strips a leading neutral double quote from the
+argument, allowing embedded leading spaces in @var{file}.
@endDefreq
@Defreq {rd, [@Var{prompt} [@Var{arg1} @Var{arg2} @dots{}]]}
@@ -16583,7 +16589,7 @@ Dear Mr. Adollar,
.ex
@endExample
-@Defreq {pi, [@code{"}]@Var{contents}}
+@Defreq {pi, [@code{"}]@Var{command}}
Use GNU @command{troff}'s device-independent output as the input to the
commands specified in @var{pipe} and emit their output to the standard
output stream instead of GNU @command{troff}'s usual output.
@@ -16594,12 +16600,12 @@ language,@footnote{@xref{gtroff Output}.} using this
request without
specifying the @option{-Z} option to @command{groff} is likely to
provoke fatal errors from an output driver.
-The formatter reads the remainder of the input line into @var{contents}
+The formatter reads the remainder of the input line into @var{command}
and passes it to @cite{popen@r{(3)}}. Output produced by the
command(s) is not captured by GNU @command{troff}.
GNU @command{troff} strips a leading neutral double quote from the
-argument, allowing embedded leading spaces in @var{contents}.
+argument, allowing embedded leading spaces in @var{command}.
Multiple @code{pi} requests construct a multi-stage pipeline in the same
order as the formatter encounters the requests.
@@ -16629,15 +16635,15 @@ is the same as @w{@samp{.pi foo | bar}}.
@cindex system commands, running
@cindex running system commands
-@DefreqList {sy, [@code{"}]@Var{contents}}
+@DefreqList {sy, [@code{"}]@Var{command}}
@DefregListEndx {systat}
Execute the specified shell command(s). The formatter reads the
-remainder of the input line into @var{contents} and passes it to
+remainder of the input line into @var{command} and passes it to
@cite{system@r{(3)}}. Output produced by the command(s) is not captured
by GNU @command{troff}.
GNU @command{troff} strips a leading neutral double quote from the
-argument, allowing embedded leading spaces in @var{contents}.
+argument, allowing embedded leading spaces in @var{command}.
@cindex safer mode
@cindex mode, safer
@@ -18141,12 +18147,22 @@ Unlike @acronym{AT&T} @code{troff}, GNU @code{troff}
does not ignore the
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{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 @code{pi}, @code{so}, and @code{sy} requests, allowing
-it to contain embedded leading spaces.
+GNU
+@command{troff}
+strips a leading neutral double quote from the argument to the
+@code{cf},
+@code{nx},
+@code{pi},
+@code{so},
+and
+@code{sy}
+requests,
+allowing it to contain 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 a9c24c31b..4e426ed2f 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2272,6 +2272,17 @@ denotes a single input character,
ordinary or special.
.
.TPx
+.I command
+is a sequence of ordinary characters and/or spaces
+to be passed to the system as a command
+(potentially with arguments).
+.\" ...limiting the file names you can express; see Savannah #64071.
+.
+A leading leading neutral double quote is stripped,
+allowing embedded leading spaces.
+.
+.
+.TPx
.I div
is a diversion identifier.
.
@@ -2283,7 +2294,10 @@ is an environment identifier.
.I file
is a sequence of ordinary characters and/or spaces
naming a file on the system.
-.\" ...limiting the file names you can express; see Savannah #64071.
+.\" ...limiting the file names you can express; see Savannah #65108.
+.
+A leading leading neutral double quote is stripped,
+allowing embedded leading spaces.
.
GNU
.I troff \" GNU
@@ -2319,6 +2333,9 @@ is a sequence of ordinary characters and/or spaces
to emit on the standard error stream.
.\" ...limiting the messages you can express; see Savannah #62787.
.
+A leading leading neutral double quote is stripped,
+allowing embedded leading spaces.
+.
.TPx
.I n
is a numeric expression that evaluates to a non-negative integer.
@@ -4069,11 +4086,11 @@ are suffixed with a tab and asterisk
.RB ( * ).
.
.TPx
-.REQ .pi contents
+.REQ .pi command
Pipe GNU
.I troff \" GNU
output through
-.I contents
+.I command
(which is read in copy mode)
by passing it to
.MR popen 3 .
@@ -4559,9 +4576,9 @@ request
.\" XXX: negative values accepted; check AT&T troff
.
.TPx
-.REQ .sy contents
+.REQ .sy command
Execute
-.I contents
+.I command
(which is read in copy mode)
in the operating environment
by passing it to
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 6089841af..467fcf07f 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -6154,6 +6154,8 @@ inter-sentence space each to the nearest multiple of\~12.
GNU
.I troff \" GNU
strips a leading neutral double quote from the argument to the
+.BR cf ,
+.BR nx ,
.BR pi ,
and
.BR so ,
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
