[groff] 12/31: [docs]: Revise .so request description.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d3e57b36d60f3a380817f828470d825b861abb5a
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri May 28 22:22:52 2021 +1000

    [docs]: Revise .so request description.
    
    * doc/groff.texi (I/O) <.so>: Recast and reorganize, fronting the
      specification (including the influence of the -I option).
      Characterize operation more precisely as replacing the request's
      control line; this makes the relevance of a trailing newline in the
      sourced file more obvious.  Fix comma splice and follow Latin
      abbreviation "e.g." with a comma.  Note that source files are not
      processed, supplying a motivation for the otherwise sudden cross
      reference to soelim.  Redirect said cross reference to the (g)soelim
      man page instead of the internal "gsoelim" node, which has been empty
      for over 20 years (af2d6f8e5, 26 December 1999).  Revise example to be
      slightly less generic and use the Texinfo @result command.
    
    * man/groff.7.man (Requests/Request short reference): Replace
      description with corresponding lead sentence from our Texinfo manual
      (with some minor economy applied).
---
 doc/groff.texi  | 40 ++++++++++++++++++++--------------------
 man/groff.7.man |  5 +++--
 2 files changed, 23 insertions(+), 22 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 4d6c94a..81fe513 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -14235,32 +14235,32 @@ environment (@pxref{Environments}).
 @DefreqListEndx {soquiet, file}
 @cindex including a file (@code{so})
 @cindex file, inclusion (@code{so})
-Read in the specified @var{file} and include it in place of the
-@code{so} request.  If @var{file} does not exist, a warning of type
-@samp{file} is emitted and the request has no other effect.
-@xref{Debugging}, for information about warnings.  This is quite useful
-for large documents, e.g.@: keeping each chapter in a separate file.
-@xref{gsoelim}, for more information.
+Replace the @code{so} request's control line with the contents of the
+file named by the argument, ``sourcing'' it.  @var{file} is sought in
+the directories specified by @option{-I} command-line option.  If
+@var{file} does not exist, a warning of type @samp{file} is emitted and
+the request has no further effect.  @xref{Debugging}, for information
+about warnings.
 
-Since @code{gtroff} replaces the @code{so} request with the contents of
-@code{file}, it makes a difference whether the data is terminated with a
-newline or not: Assuming that file @file{xxx} contains the word
-@samp{foo} without a final newline, this
+@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
+with @code{so} are not preprocessed; to overcome this limitation, see
+the @cite{gsoelim@r{(1)}} man page.
+
+Since GNU @code{troff} replaces the entire control line with the
+contents of a file, it matters whether @code{file} is terminated with a
+newline or not.  Assume that file @file{xxx} contains only the word
+@samp{foo} without a trailing newline.
 
 @Example
-This is
+The situation is
 .so xxx
-bar
+bar.
+    @result{} The situation is foobar.
 @endExample
 
-@noindent
-yields @samp{This is foobar}.
-
-The search path for @var{file} can be controlled with the @option{-I}
-command-line option.
-
-@code{soquiet} works the same way, except that no warning diagnostic
-is issued if @var{file} does not exist.
+@code{soquiet} works the same way, except that no warning diagnostic is
+issued if @var{file} does not exist.
 @endDefreq
 
 @Defreq {pso, command}
diff --git a/man/groff.7.man b/man/groff.7.man
index 917460a..76dfffe 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2678,8 +2678,9 @@ file.
 .
 .TPx
 .REQ .so file
-Interpolate (\[lq]source\[rq])
-.IR file .
+Replace the request's control line with the contents of
+.IR file ,
+\[lq]sourcing\[rq] it.
 .
 .
 .TPx