[groff] 08/26: groff_man*(7): Fix content and style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit bc4abc17116e7b12c03aa4d4917102ef6c44534c
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Nov 12 12:00:10 2021 +1100

    groff_man*(7): Fix content and style nits.
    
    Content:
    * Consistently say "escape sequence(s)" instead of "escape(s)".
    * Swap parenthesization order when presenting "recto" and "verso"; give
      the typographical terms first and then explain them in parentheses on
      the presumption that most man page authors don't have a background in
      publishing or typography.
    * Generalize claims of syntactical traditions regarding '-' and '\';
      they are on the order of 50 years old.
    * De-document support for positive FT register settings; we un-supported
      them in commit 5a76dfb9 (17 May) and I'm guessing that few people use
      them intentionally.
    
    Style:
    * Make a relative inset's indentation less garish.
    * Use passive voice consistently within a clause.
---
 tmac/groff_man.7.man.in | 67 +++++++++++++++++++++++++------------------------
 1 file changed, 34 insertions(+), 33 deletions(-)

diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 90c1469..d6ac5b4 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -23,9 +23,9 @@ These man pages serve multiple goals, one of which is to 
serve as a
 model for good man page writing by people who examine their sources.
 
 After processing by m4, both child pages in the above case will carry \c
-escapes followed by text lines starting with punctuation one normally
-does not find in that position (and in the case of the period, which has
-to be protected from interpretation as a control line).
+escape sequences followed by text lines starting with punctuation one
+normally does not find in that position (and in the case of the period,
+which has to be protected from interpretation as a control line).
 
 This is ugly, fragile, and unnecessary; all of these traits are
 offensive to good pedagogy.
@@ -219,7 +219,7 @@ and employ the Unix line-ending convention
 .\" The above distinction works well with filling.
 .\" Don't fill your input text yourself; let groff do the work.
 .\" Also good for diffs.
-.\" escapes--pretty much just "see Portability"
+.\" escape sequences--pretty much just "see Portability"
 .\"
 .\" ====================================================================
 .\" .SS "Why have a tutorial and style guide?"
@@ -385,8 +385,8 @@ is positioned at the bottom left.
 .
 Otherwise,
 .I footer-inside
-appears at the bottom left on odd-numbered (recto) pages,
-and at the bottom right on even-numbered (verso) pages.
+appears at the bottom left on recto (odd-numbered) pages,
+and at the bottom right on verso (even-numbered) pages.
 .
 The outside footer is the page number,
 except in the continuous-rendering mode enabled by the option
@@ -499,7 +499,7 @@ must be the first section after the
 .B .TH
 call,
 and must contain only a line of the form
-.RS \" Invisibly move left margin to current .IP indent.
+.RS \" Invisibly move left margin to current .IP indentation.
 .RS \" Now indent further, visibly.
 .IR topic [\c
 .BI , " another-topic"\c
@@ -819,8 +819,8 @@ Two convenient uses for
 are
 .
 .
-.RS \" Invisibly move left margin to current .IP indent.
-.RS \" Now indent further, visibly.
+.RS \" Invisibly move left margin to current .IP indentation.
+.RS 4n \" Now indent further, visibly.
 .IP (1) 4n
 to start a new paragraph with the same indentation as an immediately
 preceding
@@ -1624,7 +1624,7 @@ see the
 .BR \e(oq ,
 and
 .B \e(cq
-escapes in subsection \(lqPortability\(rq below.
+escape sequences in subsection \(lqPortability\(rq below.
 .
 .
 _endif()dnl
@@ -2236,13 +2236,13 @@ _ifstyle()dnl
 .
 The two major syntactical categories of
 .I roff
-languages are requests and escapes.
+languages are requests and escape sequences.
 .
 Since the
 .I man
 macros are implemented in terms of
 .I groff
-requests and escapes,
+requests and escape sequences,
 one can,
 in principle,
 supplement the functionality of
@@ -2295,7 +2295,7 @@ in section \(lqFiles\(rq below.
 .
 .
 .P
-Similar caveats apply to escapes.
+Similar caveats apply to escape sequences.
 .
 Some escape sequences are however required for correct typesetting
 even in man pages and usually do not cause portability problems.
@@ -2306,8 +2306,9 @@ in the Unicode basic Latin range
 that are handled specially in
 .I roff
 input;
-the escapes below must be used to render them correctly and portably
-when documenting material that uses them syntactically\(emnamely,
+the escape sequences below must be used to render them correctly and
+portably when documenting material that uses them
+syntactically\(emnamely,
 any of the set
 .B \(aq \- \(rs \(ha \(ga \(ti
 (apostrophe,
@@ -2437,8 +2438,9 @@ This escape sequence produces the Unix command-line 
option dash in the
 output.
 .
 .RB \(lq \- \(rq
-is a hyphen to
-.IR roff ;
+is a hyphen in
+.I roff
+languages;
 some output devices replace it with U+2010
 (hyphen)
 or similar.
@@ -2541,9 +2543,9 @@ or similar.
 Reverse solidus
 (backslash).
 .
-The backslash is the default
-.I groff
-escape character,
+The backslash is the default escape character in
+.I roff
+languages,
 so it does not represent itself in output.
 .
 Also see
@@ -2586,7 +2588,7 @@ examples.
 Anything after
 .B \ec
 on the input line
-.\" ...except for \R escapes, which shouldn't appear in man pages...
+.\" ...except for \R, which shouldn't appear in man pages...
 is ignored.
 .
 The next line is interpreted as usual and can `include' a macro call
@@ -2695,13 +2697,13 @@ is needed when three different font styles are required 
in a word.
 .
 .
 .IP
-Style escapes may be more portable than
+Style escape sequences may be more portable than
 .BR \ec .
 .
 As shown above,
 it is up to you to account for italic corrections with
-.\" Normally we don't quote escapes, but these use potentially-confusing
-.\" prose punctuation.
+.\" Normally we don't quote escape sequences, but these use
+.\" potentially-confusing prose punctuation.
 .RB \(lq \e/ \(rq
 and
 .RB \(lq \e, \(rq,
@@ -2730,7 +2732,7 @@ usually result in more readable
 .I roff
 source than
 .B \ef
-escapes do.
+escape sequences do.
 .
 .
 .P
@@ -2806,7 +2808,7 @@ The first argument
 can be:
 .
 .
-.RS \" Invisibly move left margin to current .IP indent.
+.RS \" Invisibly move left margin to current .IP indentation.
 .RS \" Now indent further, visibly.
 .TP
 3
@@ -2969,7 +2971,7 @@ The argument
 can be:
 .
 .
-.RS \" Invisibly move left margin to current .IP indent.
+.RS \" Invisibly move left margin to current .IP indentation.
 .RS \" Now indent further, visibly.
 .TP
 3
@@ -3184,10 +3186,9 @@ in subsection \(lqDocument structure macros\(rq above.
 .
 .TP
 .BI \-rFT= footer-distance
-Set distance of the footer,
-relative to the bottom of the page if negative or top if positive,
-to
-.IR footer-distance .
+Set distance of the footer relative to the bottom of the page to
+.IR footer-distance ;
+this amount is always negative.
 .
 At twice this distance,
 the page text is broken before writing the footer.
@@ -3470,9 +3471,9 @@ so they will replace any macros of the same names 
preceding it in your
 file.
 .
 If you use your own implementations of these macros,
-they must be defined after calling
+they must be defined after
 .B .TH
-to have any effect.
+is called to have any effect.
 .
 Furthermore,
 it is wise to `define' such page-local macros