[groff] 11/26: [doc,man]: Clarify behavior of pi and sy requests.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit be20537c1b69d3d778cb7ce61c30a6953127bc86
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Nov 12 08:26:15 2024 -0600

    [doc,man]: Clarify behavior of pi and sy requests.
    
    Refer to each request's argument as "contents" to indicate for
    consistency with the way string-populating requests are handled, and to
    aid the reader to recall that the argument will be read to the end of
    the input line in copy mode.
    
    There's one difference: `pi` and `sy` don't handle a leading double
    quote the way `ds` and `as` do.  But I'm about to change that.
    
    * doc/groff.texi.in: Bump document date.
---
 doc/groff.texi.in | 34 +++++++++++++++++++++-------------
 man/groff.7.man   | 26 ++++++++++++++++++--------
 2 files changed, 39 insertions(+), 21 deletions(-)

diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 81c1203d8..770e13c71 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -464,7 +464,7 @@ Documentation License''.
 @title groff
 @subtitle The GNU implementation of @code{troff}
 @subtitle version @VERSION@
-@subtitle October 2024
+@subtitle November 2024
 @author Trent@tie{}A.@: Fisher
 @author Werner Lemberg
 @author G.@tie{}Branden Robinson
@@ -16430,7 +16430,7 @@ Dear Mr. Adollar,
 .ex
 @endExample
 
-@Defreq {pi, pipe}
+@Defreq {pi, contents}
 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.
@@ -16441,6 +16441,13 @@ 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}
+and passes it to @cite{popen@r{(3)}}.  Output produced by the
+command(s) is not captured by GNU @command{troff}.
+
+Multiple @code{pi} requests construct a multi-stage pipeline in the same
+order as the formatter encounters the requests.
+
 @code{pi} must be invoked before GNU @command{troff} writes any nodes
 to its output.@footnote{@xref{Gtroff Internals}.}  The formatter reports
 an error and ignores the request if @code{pi} is invoked ``too late''.
@@ -16456,13 +16463,9 @@ Use of this request in safer mode (GNU 
@command{troff}'s default) is
 erroneous.  Invoke GNU @command{troff} or a front end with the
 @option{-U} option to enable unsafe mode.
 
-Multiple calls to @code{pi} are allowed, acting as a chain.  For
-example,
-
 @Example
 .pi foo
 .pi bar
-@r{@dots{}}
 @endExample
 
 is the same as @w{@samp{.pi foo | bar}}.
@@ -16470,10 +16473,12 @@ is the same as @w{@samp{.pi foo | bar}}.
 
 @cindex system commands, running
 @cindex running system commands
-@DefreqList {sy, cmds}
+@DefreqList {sy, contents}
 @DefregListEndx {systat}
-Execute the shell command(s) specified by @var{cmds}.  The output is not
-saved anywhere, so it is up to the user to do so.
+Execute the specified shell command(s).  The formatter reads the
+remainder of the input line into @var{contents} and passes it to
+@cite{system@r{(3)}}.  Output produced by the command(s) is not captured
+by GNU @command{troff}.
 
 @cindex safer mode
 @cindex mode, safer
@@ -16483,6 +16488,13 @@ It is an error to use this request in safer mode; this 
is the default.
 Give GNU @code{troff} or a front end program the @option{-U} option to
 enable unsafe mode.
 
+@cindex @code{system()} return value register (@code{systat})
+The writable register @code{systat} contains the return value of the
+@cite{system@r{(3)}} function executed by the most recent @code{sy}
+request.
+
+@c XXX: This is a really lame example because we already have built-in
+@c registers for this.  Come up with something better.
 The following code fragment introduces the current time into a document.
 
 @pindex perl
@@ -16514,10 +16526,6 @@ output.
 \n[hours]:\n[minutes]:\n[seconds]
     @result{} 02:17:54
 @endExample
-
-@cindex @code{system()} return value register (@code{systat})
-The writable register @code{systat} contains the return value of the
-@code{system()} function executed by the last @code{sy} request.
 @endDefreq
 
 @DefreqList {open, stream file}
diff --git a/man/groff.7.man b/man/groff.7.man
index d4b53aefb..39d2fb773 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -4028,9 +4028,19 @@ are suffixed with a tab and asterisk
 .RB ( * ).
 .
 .TPx
-.REQ .pi command
-Pipe output to
-.IR command .
+.REQ .pi contents
+Pipe GNU
+.I troff \" GNU
+output through
+.I contents
+(which is read in copy mode)
+by passing it to
+.MR popen 3 .
+.
+Multiple
+.B pi
+requests construct a multi-stage pipeline in the same order as the
+formatter encounters the requests.
 .
 Unsafe request;
 disabled by default.
@@ -4504,12 +4514,12 @@ request
 .\" XXX: negative values accepted; check AT&T troff
 .
 .TPx
-.REQ .sy command-line
+.REQ .sy contents
 Execute
-.IR command-line ,
-a sequence of ordinary characters,
-.\" ...limiting the shell commands you can express; see Savannah #65108.
-with
+.I contents
+(which is read in copy mode)
+in the operating environment
+by passing it to
 .MR system 3 .
 .
 Unsafe request;