[groff] 09/09: soelim(1): Fix style problems.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 7eca9c3c6d0efdbb29dcedad51d18d4c4993a22a
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Oct 8 22:11:38 2020 +1100

    soelim(1): Fix style problems.
    
    * Update apropos summary.  Expand ".so" request to its mnemonic
      (source), and characterize input as "troff" instead of "groff" since,
      in contrast to some GNU roff preprocessors, GNU soelim should work
      fine for traditional troff input.
    * Define and use string for rendering the TeX logo correctly on
      typesetter devices, like other groff man pages.
    * Stop using .OP macro in favor of font macros.  Also place explicit
      space between option flag and its argument.
    * Rename "file" parameter to "input-file" for disambiguation.
    * Recast description to clearly distinguish arguments to soelim from
      arguments to .so requests in the processed input.
    * Note that soelim works recursively.
    * Note how soelim treats standard input and output.
    * Use font changes as well as quotation marks to clarify discussion of
      escape sequences recognized by soelim.
    * Call out "\[rs]" as _not_ recognized.
    * Remove unneeded "Note that" construction (here's to you, Dave Kemper).
    * Set command names in italics.
    * Use command prefix consistently; it was neglected in places.
    * The command prefix creates pain for the diagrams used in this man
      page; if there is a command prefix, add language noting the different
      usage in the diagram, guarded by an .if request.  Put a dollar in the
      man page swear jar.  Add comment explaining what's going on.
    * Replace .nf and .fi requests with .EX and .EE macros.
    * Use arrow and bracket-building glyphs instead of ASCII art for arrows
      in terminal versions of diagrams.
    * Recast description of -I option in imperative mood.  Also place
      explicit space between option flag and its argument.
    * Break input lines after commas and semicolons.
    * Put parenthetical asides on their own input lines.
---
 src/preproc/soelim/soelim.1.man | 195 ++++++++++++++++++++++++++--------------
 1 file changed, 130 insertions(+), 65 deletions(-)

diff --git a/src/preproc/soelim/soelim.1.man b/src/preproc/soelim/soelim.1.man
index 958c371..8715cb4 100644
--- a/src/preproc/soelim/soelim.1.man
+++ b/src/preproc/soelim/soelim.1.man
@@ -1,7 +1,7 @@
 '\" p
 .TH @g@soelim @MAN1EXT@ "@MDATE@" "groff @VERSION@"
 .SH Name
-@g@soelim \- interpret .so requests in groff input
+@g@soelim \- interpret source (.so) requests in troff input
 .
 .
 .\" ====================================================================
@@ -29,17 +29,27 @@
 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
 .do nr *groff_soelim_1_man_C \n[.cp]
 .cp 0
+.\" Man pages are seldom preprocessed with pic(1).
 .mso pic.tmac
 .
 .
 .\" ====================================================================
+.\" Definitions
+.\" ====================================================================
+.
+.ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
+.el   .ds tx TeX
+.
+.
+.\" ====================================================================
 .SH Synopsis
 .\" ====================================================================
 .
 .SY @g@soelim
-.OP \-Crt
-.OP \-I dir
-.RI [ file
+.RB [ \-Crt ]
+.RB [ \-I
+.IR dir ]
+.RI [ input-file
 \&.\|.\|.\&]
 .YS
 .
@@ -61,56 +71,101 @@
 .SH Description
 .\" ====================================================================
 .
-.B @g@soelim
-reads
-.I files
-and replaces lines of the form
-.IP
-.BI .so\~ file
-.LP
-by the contents of
-.IR file .
+.I @g@soelim
+replaces lines of the form
+.RB \[lq] .so
+.IR macro-file \[rq]
+within each
+.I input-file
+with the contents of
+.IR macro-file ,
+recursively.
 .
 It is useful if files included with
 .B .so
 need to be preprocessed.
 .
+Output is written to the standard output stream.
+.
 Normally,
-.B @g@soelim
-should be invoked with the
+.I @g@soelim
+should be invoked with
+.IR groff 's
 .B \-s
-option of
-.BR groff .
+option.
 .
+In the absence of
+.I input-file
+arguments,
+.I soelim
+reads the standard input stream.
 .
-.PP
-To embed \[oq]\[rs]\[cq] in the file name, write \[oq]\[rs]\[rs]\[cq]
-or \[oq]\[rs]e\[cq].
 .
-To embed a space, write \[oq]\[rs]\ \[cq].
+.PP
+To embed a backslash
+.RB \[lq] \[rs] \[rq]
+in the name of a
+.IR macro-file ,
+write
+.RB \[lq] \[rs]\[rs] \[rq]
+or
+.RB \[lq] \[rs]e \[rq].
+.
+To embed a space,
+write
+.RB \[lq] \[rs]\~ \[rq]
+(backslash followed by a space).
 .
 Any other escape sequence in
-.I file
+.IR macro-file ,
+including
+.RB \[lq] \[rs][rs] \[rq],
 makes
-.B soelim
+.I @g@soelim
 ignore the whole line.
 .
 .
 .PP
-Note that there must be no whitespace between the leading dot and the
-two characters \[oq]s\[cq] and \[oq]o\[cq].
+There must be no whitespace between the leading dot and the two
+characters \[lq]s\[rq] and \[lq]o\[rq].
 .
-Otherwise, only
-.B groff
-interprets the
+Otherwise,
+only
+.I groff
+will interpret the
 .B .so
-request (and
-.B soelim
-ignores it).
+request;
+.I @g@soelim
+will ignore it
+(but see the
+.B \-C
+option below).
 .
 .
 .PP
-The normal processing sequence of groff is this:
+The normal processing sequence of
+.I groff
+is as follows.
+.
+.\" Does this groff installation use a command prefix?  In installed
+.\" pages, this comparison will not look like it needs to be dynamically
+.\" decided.
+.\"
+.\" This is done so that the box sizes (in the pic(1) diagram) and arrow
+.\" alignments (in the text alternative) can remain fixed.
+.if !'@g@'' \{\
+In the diagrams below,
+the traditional names for
+.I soelim
+and
+.I troff
+are used;
+on this system,
+the GNU versions are installed as
+.I @g@soelim
+and
+.IR @g@troff .
+.\}
 .
 .
 .PP
@@ -145,33 +200,33 @@ box invisible width 0.5 height 0.4 "output" "file"
 .PE
 .\}
 .el \{\
-.nf
+.EX
           input        sourced
           file          file
-            |             |
-            v             v
-        preprocessor -> troff -> postprocessor
-                                      |
-                                      v
+            \[bv]             \[bv]
+            \[da]             \[da]
+        preprocessor \[an]\[->] troff \[an]\[->] postprocessor
+                                      \[bv]
+                                      \[da]
                                    output
                                     file
-.fi
+.EE
 .\}
 .PP
-.
-That is, files sourced with
+That is,
+files sourced with
 .B .so
 are normally read
 .I only
 by
-.B troff
+.I @g@troff
 (the actual formatter).
 .
-.B soelim
+.I @g@soelim
 is
 .I not
 required for
-.B troff
+.I @g@troff
 to source files.
 .
 .
@@ -181,8 +236,8 @@ it must already be read
 .I before
 the input file passes through the preprocessor.
 .
-This is handled by
-.BR soelim :
+.I @g@soelim
+handles this.
 .
 .PP
 .ie t \{\
@@ -213,17 +268,18 @@ box invisible width 0.5 height 0.4 "output" "file"
 .PE
 .\}
 .el \{\
-.nf
+.EX
           input
           file
-            |
-            v
-          soelim -> preprocessor -> troff -> postprocessor
-            ^                                     |
-            |                                     v
+            \[bv]
+            \[da]
+          soelim \[an]\[->] preprocessor \[an]\[->] troff \[an]\[->] \
+postprocessor
+            \[ua]                                     \[bv]
+            \[bv]                                     \[da]
          sourced                               output
           file                                  file
-.fi
+.EE
 .\}
 .
 .
@@ -248,20 +304,23 @@ Recognize
 even when followed by a character other than space or newline.
 .
 .TP
-.BI \-I dir
-This option may be used to add a directory to the search path for
-files (both those on the command line and those named in
+.BI \-I\~ dir
+Add the directory
+.I dir
+to the search path for macro files
+(both those on the command line and those named in
 .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).
+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, add
-.B \-I.\&
+If you want to search the current directory before other directories,
+add
+.RB \[lq] \-I\~.\& \[rq]
 at the appropriate place.
 .
 .IP
@@ -271,14 +330,20 @@ No directory search is performed for files with an 
absolute file name.
 .B \-r
 Do not add
 .B .lf
-requests (for general use, with non-groff files).
+requests
+(for general use,
+with
+.RI non- groff
+files).
 .
 .TP
 .B \-t
-Don't emit
+Emit \*[tx] comment lines starting with
+.RB \[lq] % \[rq]
+indicating the current file and line number,
+rather than
 .B .lf
-requests but TeX comment lines (starting with \[oq]%\[cq]) giving the
-current file and line number.
+requests for the same purpose.
 .
 .
 .\" ====================================================================