[groff] 21/38: soelim(1): Fix content and style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 8aaabf5af1c0272a3f2b4d0927dcc8efd99161af
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Aug 31 16:17:10 2022 -0500

    soelim(1): Fix content and style nits.
    
    Content:
    * Explanatory material about the pic(1) diagram using "generic" names
      for troff(1) and soelim(1) was getting included when it didn't need to
      be, because the sequence '@g@', storing the command prefix, that
      undergoes replacement by sed(1) during make(1) is never strictly empty
      anymore; it always starts with (or consists of) a hyphenation control
      escape sequence (to prevent command names from being hyphenated when
      man pages are formatted).  This was regressed by commit d84d9e1d85, 21
      February, which added the \%.
    * Note suitability for general text files in summary description.
    
    Style:
    * Recast to reduce use of quotation around escape sequences.
    * Drop leading dot from *roff request names `lf`, `if` and `so`; but
      quote the latter two because they are also English words.
    * Refer to "the roff language" as a singular entity; see commit
      80afae9f4, 13 April.
    * Set "Name" section's summary-description terms in italics as needed.
---
 src/preproc/soelim/soelim.1.man | 43 +++++++++++++++++++++--------------------
 1 file changed, 22 insertions(+), 21 deletions(-)

diff --git a/src/preproc/soelim/soelim.1.man b/src/preproc/soelim/soelim.1.man
index b6af9d755..260debd5c 100644
--- a/src/preproc/soelim/soelim.1.man
+++ b/src/preproc/soelim/soelim.1.man
@@ -1,7 +1,9 @@
 '\" p
 .TH @g@soelim @MAN1EXT@ "@MDATE@" "groff @VERSION@"
 .SH Name
-@g@soelim \- recursively interpolate source requests in roff files
+@g@soelim \- recursively interpolate source requests in
+.I roff
+or other text files
 .
 .
 .\" ====================================================================
@@ -92,7 +94,7 @@ recursively.
 .
 By default,
 it writes
-.B .lf
+.B lf
 requests as well to record the name and line number of each
 .I input-file
 and
@@ -115,14 +117,14 @@ Output is written to the standard output stream.
 .
 .
 .PP
-To embed a backslash
-.RB \[lq] \[rs] \[rq]
-in the name of a
-.IR macro-file ,
-write
-.RB \[lq] \[rs]\[rs] \[rq]
+If the name of a
+.I macro-file
+contains a backslash,
+use
+.B \[rs]\[rs]
 or
-.RB \[lq] \[rs]e \[rq].
+.B \[rs]e
+to embed it.
 .
 To embed a space,
 write
@@ -149,7 +151,7 @@ This convention allows source requests to be 
\[lq]protected\[rq] from
 processing by
 .IR @g@soelim ,
 for instance as part of macro definitions or
-.B .if
+.RB \[lq] if \[rq]
 requests.
 .
 .
@@ -168,9 +170,9 @@ option overrides this requirement.
 .PP
 The foregoing is the limit of
 .IR @g@soelim 's
-understanding of
+understanding of the
 .I roff
-languages;
+language;
 it does not,
 for example,
 replace the input line
@@ -214,7 +216,7 @@ is as follows.
 .\"
 .\" 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@'' \{\
+.if !'@g@'\%' \{\
 In the diagrams below,
 the traditional names for
 .I soelim
@@ -276,12 +278,11 @@ box invisible width 0.5 height 0.4 "output" "file"
 .PP
 That is,
 files sourced with
-.B .so
+.RB \[lq] so \[rq]
 are normally read
 .I only
-by
-.I @g@troff
-(the actual formatter).
+by the formatter,
+.IR @g@troff .
 .
 .I @g@soelim
 is
@@ -365,9 +366,9 @@ all exit afterward.
 .
 .TP
 .B \-C
-Recognize
+Recognize an input line starting with
 .B .so
-even when followed by a character other than space or newline.
+even if a character other than a space or newline follows.
 .
 .TP
 .BI \-I\~ dir
@@ -395,7 +396,7 @@ it is otherwise searched last.
 .B \-r
 Write files \[lq]raw\[rq];
 do not add
-.B .lf
+.B lf
 requests.
 .
 .
@@ -405,7 +406,7 @@ Emit \*[tx] comment lines starting with
 .RB \[lq] % \[rq]
 indicating the current file and line number,
 rather than
-.B .lf
+.B lf
 requests for the same purpose.
 .
 .