[groff] 24/47: man pages: Parallelize descriptions of -I option.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 7e1fa0a62d896a9d8cd81f1ee397186e94203663
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Jan 9 22:59:39 2022 +1100

    man pages: Parallelize descriptions of -I option.
    
    Also synchronize our Texinfo manual's description of groff's "-I" option
    with the man pages.
---
 doc/groff.texi                  | 31 +++++++++++++++++++------------
 src/devices/gropdf/gropdf.1.man | 13 +++++++++----
 src/devices/grops/grops.1.man   | 13 ++++++-------
 src/preproc/soelim/soelim.1.man | 11 +++++------
 src/roff/troff/troff.1.man      |  2 +-
 5 files changed, 40 insertions(+), 30 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 3393e79a..875f7f59 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -1114,27 +1114,34 @@ Read the standard input after all the named input files 
have been
 processed.
 
 @item -I@var{dir}
-This option may be used to specify a directory to search for files.
-It is passed to the following programs:
+Search @var{dir} for files named in several contexts; implies
+@option{-g} and @option{-s}.  Files are sought for several purposes.
 
 @itemize
 @item
-@code{gsoelim} (@pxref{gsoelim} for more details);
-it also implies @code{groff}'s @option{-s} option.
+@code{gsoelim} replaces @code{so} requests with the contents of their
+file name arguments (@pxref{gsoelim} for more details).
 
 @item
-@code{gtroff}; it is used to search files named in the @code{psbb} and
-@code{so} requests.
+@code{gtroff} searches for files named as operands in its command line
+and as arguments to @code{psbb}, @code{so}, and @code{soquiet} requests.
 
 @item
-@code{grops}; it is used to search files named in the
-@samp{\X'ps: import @r{@dots{}}'} and @samp{\X'ps: file @r{@dots{}}'}
-escape sequences.
+Output drivers may search for files; for instance, @code{grops} looks
+for files named in @samp{\X'ps: import @r{@dots{}}'} and @samp{\X'ps:
+file @r{@dots{}}'} escape sequences.
 @end itemize
 
-The current directory is always searched first.  This option may be
-specified more than once; the directories are searched in the order
-specified.
+This option may be specified more than once; the directories are
+searched in the order specified.  If you want to search the current
+directory before others, add @samp{-I .} at the appropriate place.  The
+current working directory is otherwise searched last.  @option{-I} works
+similarly to, and is named for, the ``include'' option of Unix C
+compilers.
+
+@option{-I} options are passed to @code{gsoelim}, @code{gtroff}, and
+output drivers; with the flag letter changed to @option{-M}, they are
+also passed to @code{ggrn}.
 
 @item -j
 Preprocess with @code{gchem}.  Implies @option{-p}.
diff --git a/src/devices/gropdf/gropdf.1.man b/src/devices/gropdf/gropdf.1.man
index 57b0d8a8..e2814824 100644
--- a/src/devices/gropdf/gropdf.1.man
+++ b/src/devices/gropdf/gropdf.1.man
@@ -156,12 +156,17 @@ is the name of the device, usually
 This option may be used to add a directory to the search path for
 files named in
 .B \[rs]X\[aq]pdf: pdfpic\[aq]
-escape sequence.
+escape sequences.
 .
-The current directory is always searched first.
+This option may be specified more than once;
+the directories are then searched in the order specified.
 .
-This option may be specified more than once; the directories are then
-searched in the order specified.
+If you want to search the current directory before others,
+add
+.RB \[lq] "\-I .\&" \[rq]
+at the appropriate place.
+.
+The current working directory is otherwise searched last.
 .
 .
 .TP
diff --git a/src/devices/grops/grops.1.man b/src/devices/grops/grops.1.man
index 634cd696..a8e24980 100644
--- a/src/devices/grops/grops.1.man
+++ b/src/devices/grops/grops.1.man
@@ -273,17 +273,16 @@ and
 .B \[rs]X\[aq]ps: file\[aq]
 escape sequences.
 .
-The search path is initialized with the current directory.
+This option may be specified more than once;
+the directories are then searched in the order specified.
 .
-This option may be specified more than once; the directories are then
-searched in the order specified (but before the current directory).
-.
-If you want to make the current directory be read before other
-directories,
+If you want to search the current directory before others,
 add
-.B \-I.\&
+.RB \[lq] "\-I .\&" \[rq]
 at the appropriate place.
 .
+The current working directory is otherwise searched last.
+.
 .
 .TP
 .B \-l
diff --git a/src/preproc/soelim/soelim.1.man b/src/preproc/soelim/soelim.1.man
index dbc99104..676e1b90 100644
--- a/src/preproc/soelim/soelim.1.man
+++ b/src/preproc/soelim/soelim.1.man
@@ -378,17 +378,16 @@ to the search path for macro files
 .B .so
 requests).
 .
-The search path is initialized with the current directory.
-.
 This option may be specified more than once;
-the directories are then searched in the order specified
-(but before the current directory).
+the directories are searched in the order specified.
 .
-If you want to search the current directory before other directories,
+If you want to search the current directory before others,
 add
-.RB \[lq] \-I\~.\& \[rq]
+.RB \[lq] "\-I .\&" \[rq]
 at the appropriate place.
 .
+The current working directory is otherwise searched last.
+.
 .
 .TP
 .B \-r
diff --git a/src/roff/troff/troff.1.man b/src/roff/troff/troff.1.man
index 055818ef..8d1c9244 100644
--- a/src/roff/troff/troff.1.man
+++ b/src/roff/troff/troff.1.man
@@ -280,7 +280,7 @@ and
 escape sequences).
 .
 This option may be specified more than once;
-the directories are then searched in the order specified.
+the directories are searched in the order specified.
 .
 If you want to search the current directory before others,
 add