[groff] 03/06: groff_man(7): Revise indentation discussions.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 74791544e756fc1027e8d1aad8badac26d72407f
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Aug 9 15:55:03 2020 +1000

    groff_man(7): Revise indentation discussions.
    
    This continues 3ae458abcc1be083055568ae3eaad32e5f48a98a (6 August).
    
    * Characterize .RS as "creating an inset level".
    * Say "inset level" instead "indentation level".
    * Stop using "indent" as a noun except when it is a metasyntactic
      argument name.  Nouning weirds language as much as verbing does...
    * Adjust paragraphing of subsection "Horizontal and vertical spacing".
      The first paragraph now concerns itself with explaining the syntax and
      semantics of "indent" arguments to those requests which take them,
      and which requests reset the indentation so requested.  The second
      paragraph concerns itself with the default indentation amounts, their
      connection to the IN and SN registers, and supplies forward references
      to the -r option.  Move the caveat that HTML ignores indentation to
      the end of the paragraph.
    * Rename metasyntactic argument to -rIN flag to "standard-indent".
    * Undocument .TQ as being affected by the IN register.  This is true
      only indirectly; it takes no "indent" argument and instead reuses the
      indent of the previous .TP call.
    * Drop extraneous words.
---
 tmac/groff_man.7.man | 101 ++++++++++++++++++++++++++-------------------------
 1 file changed, 51 insertions(+), 50 deletions(-)

diff --git a/tmac/groff_man.7.man b/tmac/groff_man.7.man
index 09ee62e..6f19ca0 100644
--- a/tmac/groff_man.7.man
+++ b/tmac/groff_man.7.man
@@ -468,7 +468,7 @@ ordinary paragraph
 .RB ( .PP ).
 .
 See subsection \(lqHorizontal and vertical spacing\(rq below for the
-precise indentation amount.
+indentation amount.
 .
 The text following
 .B .SS
@@ -548,8 +548,8 @@ installation.
 .TP
 .BR .RS " ["\c
 .IR indent ]
-Start a relative inset;
-move the left margin to the right by the value
+Start a new relative inset level,
+moving the left margin right by
 .IR indent ,
 if specified,
 and by a default amount otherwise;
@@ -558,10 +558,10 @@ see subsection \(lqHorizontal and vertical spacing\(rq 
below.
 Calls to
 .B .RS
 can be nested;
-each call increments by\~1 the indentation level used by
+each call increments by\~1 the inset level used by
 .BR .RE .
 .
-The indentation level prior to any
+The inset level prior to any
 .B .RS
 calls is\~1.
 .
@@ -570,7 +570,7 @@ calls is\~1.
 .BR .RE " ["\c
 .IR level ]
 End a relative inset;
-move the left margin back to that corresponding to indentation level
+move the left margin back to that corresponding to inset level
 .IR level .
 .
 If no argument is given,
@@ -586,7 +586,7 @@ An ordinary paragraph
 .\" BEGIN STYLE
 like this one
 .\" END STYLE
-is set without a first-line indent at the current left margin,
+is set without a first-line indentation at the current left margin,
 which by default is indented from the leftmost position of the output
 device.
 .
@@ -597,7 +597,7 @@ these can be set as \(lqtagged paragraphs\(rq
 and
 .BR .TQ ),
 which have one or more leading tags followed by a paragraph that has an
-additional left indent.
+additional left indentation.
 .
 The indented paragraph
 .RB ( .IP )
@@ -1569,13 +1569,14 @@ called
 (see section \(lqNumerical Expressions\(rq in
 .IR groff (@MAN7EXT@)).
 .
-An indent specified in a call to
+An indentation specified in a call to
 .BR .IP ,
 .BR .TP ,
 or the deprecated
 .B .HP
 persists until
-(1) another of these macros is called with an explicit indent
+(1) another of these macros is called with an explicit
+.I indent
 argument,
 or
 (2)
@@ -1584,11 +1585,9 @@ or
 or
 .B .PP
 or its synonyms is called;
-these clear the indent entirely.
-.
+these clear the indentation entirely.
 .
-.PP
-Indents set by
+Relative insets created by
 .B .RS
 move the left margin and persist until
 .BR .RS ,
@@ -1599,26 +1598,25 @@ or
 is called.
 .
 .
-The default indentation,
-exhibited by ordinary
+.PP
+The indentation amount exhibited by ordinary paragraphs set with
 .B .PP
-paragraphs not within an
+(and its synonyms)
+not within an
 .BR .RS / .RE
 relative inset,
-is 7.2n for typesetter devices
-and 7n for terminal devices.
-.
-The HTML output device is an exception;
-it ignores indentation completely.
-.
-This same indentation is used again
-(additively)
-for the defaults of
+and the default used when
 .BR .IP ,
-.BR .TP ,
 .BR .RS ,
+.BR .TP ,
 and the deprecated
-.BR .HP .
+.B .HP
+are not given an indentation argument,
+is 7.2n for typesetter devices
+and 7n for terminal devices
+(but see the
+.B \-rIN
+option).
 .
 Headers,
 footers
@@ -1633,6 +1631,9 @@ are indented 3n
 (but see the
 .B \-rSN
 option).
+.
+However,
+the HTML output device ignores indentation completely.
 .\" BEGIN STYLE
 .
 .
@@ -1679,21 +1680,22 @@ An extensive example follows.
 .
 .
 .PP
-This
-.B .PP
-paragraph has neither a left-margin offset nor an indent;
-if it is sufficiently long,
-or the output device sufficiently narrow,
-it is set like a block.
+This ordinary
+.RB ( .PP )
+paragraph is not in a relative inset nor does it possess an indentation.
 .
 .
 .RS
 .PP
-Now we have moved the left margin with
-.B .RS
+Now we have created a relative inset
+(in other words,
+moved the left margin)
+with
+.BR .RS
 and started another block paragraph with
 .BR .PP .
 .
+.
 .TP
 .B tag
 This tagged paragraph,
@@ -1725,14 +1727,14 @@ and ordinary indentation
 box;
 l.
 This table is affected both by
-the left margin and the indent.
+the left margin and indentation.
 .TE
 .
 .
 .IP \(bu
 This indented paragraph has a bullet for a tag,
 making it more obvious that the left margin and the paragraph
-indent are distinct;
+indentation are distinct;
 only the former affects the tag,
 but both affect the text of the paragraph.
 .
@@ -1741,7 +1743,7 @@ but both affect the text of the paragraph.
 This ordinary
 .RB ( .PP )
 paragraph resets the indentation,
-but the left margin is still in place.
+but the left margin is still inset.
 .
 .TS
 box;
@@ -2796,7 +2798,7 @@ and\~6 otherwise.
 .
 .
 .TP
-.BI \-rIN= indent
+.BI \-rIN= standard-indent
 Set the amount of indentation used for ordinary paragraphs
 .RB ( .PP
 and its synonyms)
@@ -2804,14 +2806,12 @@ and the default indentation amount used by
 .BR .IP ,
 .BR .RS ,
 .BR .TP ,
-.BR .TQ ,
+.\" .TQ inherits its indentation from the preceding .TP.
 and the deprecated
-.B .HP
-to
-.IR indent .
+.BR .HP .
 .
 See subsection \(lqHorizontal and vertical spacing\(rq above for the
-default indentation value.
+default.
 .
 For
 terminal devices,
@@ -3072,7 +3072,7 @@ values.
 .
 .
 .TP
-.RB \(bu " .RE" " doesn't reset the indent to the expected level"
+.RB \(bu " .RE" " doesn't move the inset back to the expected level"
 .TQ
 \(bu warning: scale indicator invalid in this context
 .TQ
@@ -3083,13 +3083,14 @@ values.
 .IR n "\(aq not defined"
 The
 .B .RS
-macro takes an indentation
-.I amount
+macro takes an
+.I indentation amount
 as an argument;
 the
 .B .RE
-macro's argument is a specific indentation
-.IR level .
+macro's argument is a specific
+.IR "inset level" .
+.
 .B .RE\~1
 goes to the level before any
 .B .RS