[groff] 02/80: doc/groff.texi.in (I/O): Revise.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 4e635f6d9bb8256a353fffa3e3439b8406db7d17
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Nov 21 17:57:28 2024 -0600

    doc/groff.texi.in (I/O): Revise.
---
 doc/groff.texi.in | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 8d5a738af..97ac73216 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -16245,7 +16245,11 @@ escape sequences.
 @cindex requests for input and output
 @cindex output and input requests
 
-@command{gtroff} has several requests for including files:
+Occasionally a document wants to access the file system or other
+services provided by the operating environment.  GNU @command{troff}
+permits the reading of files and, when unsafe mode is enabled at the
+command line, the execution of an external commands, with or without
+inclusion of their output in the document.
 
 @DefreqList {so, [@code{"}]@Var{file}}
 @DefreqListEndx {soquiet, [@code{"}]@Var{file}}
@@ -16266,12 +16270,12 @@ of a book to be kept in a separate file.  However, 
files interpolated
 with @code{so} are not preprocessed; to overcome this limitation, see
 the @cite{gsoelim@r{(1)}} man page.
 
-@strong{Caution:@:} Since GNU @code{troff} replaces the entire control
-line with the contents of a file, @var{file} must end with a newline, or
-the formatter will continue reading the next input line of the
-@code{roff} file as if were part of the last line of the sourced file.
-Consider a file @file{xxx} containing only the word @samp{foo} without a
-trailing newline.
+@strong{Caution:@:} Since the formatter replaces the entire control line
+with the contents of a file, @var{file} must end with a newline, or the
+formatter will continue reading the next input line of the @code{roff}
+file as if were part of the last line of the sourced file.  Consider a
+file @file{xxx} containing only the word @samp{foo} without a trailing
+newline.
 
 @Example
 $ printf 'foo' > xxx
@@ -16287,9 +16291,9 @@ EOF
 issues no warning diagnostic if @var{file} does not exist.
 @endDefreq
 
-@Defreq {pso, command}
-Read the standard output from the specified @var{command} and include
-it in place of the @code{pso} request.
+@Defreq {pso, [@code{"}]command}
+Read the standard output from the specified @var{command} when passed to
+@cite{popen@r{(3)}} and include it in place of the @code{pso} request.
 
 @cindex safer mode
 @cindex mode, safer
@@ -16299,8 +16303,8 @@ It is an error to use this request in safer mode, which 
is the
 default.  Invoke GNU @code{troff} or a front end with the @option{-U}
 option to enable unsafe mode.
 
-The cautionary note regarding a final newline for the @code{so} request
-applies to @code{pso} as well.
+The cautionary note regarding a final newline in the stream read by the
+@code{so} request applies to @code{pso} as well.
 @endDefreq
 
 @DefreqList {mso, [@code{"}]@Var{file}}