[groff] 06/06: groff_man*(7): Fix content nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit edb2c96383fa5f9d2edc057a5499eac959b4f011
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue May 30 09:07:29 2023 -0500

    groff_man*(7): Fix content nits.
    
    * Discuss "left margin" more explicitly, and its placement with respect
      to section and subsection headings and then what we might term the
      "base paragraph indentation" subsequently.  Call out use of `IN`
      register to place the left margin for the setting of the base
      paragraph indentation, to prepare for a planned change where we
      decouple that register therefrom.  See Savannah #64018.
    * Recast a couple of points in `TH` description for clarity.
---
 tmac/groff_man.7.man.in | 86 ++++++++++++++++++++++---------------------------
 1 file changed, 39 insertions(+), 47 deletions(-)

diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 1197e44e1..4f286ac37 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -529,7 +529,7 @@ option is given).
 .
 This feature is intended only for formatting multiple
 .I man
-documents.
+documents in sequence.
 .
 .
 .IP
@@ -546,7 +546,8 @@ _ifstyle()dnl
 .IP
 By convention,
 .I footer-middle
-is the most recent modification date of the man page source document,
+is the date of the most recent modification to the man page source
+document,
 and
 .I footer-inside
 is the name and version or release of the project providing it.
@@ -567,10 +568,9 @@ text on the next line
 becomes
 .I heading-text.
 .
-This text is set at the left margin,
-in bold
+The left margin is reset to zero to set the heading text in bold
 (or the font specified by the string
-.BR HF )
+.BR HF ),
 and,
 on typesetting devices,
 slightly larger than the base type size.
@@ -582,7 +582,10 @@ use of an italic style in
 .I heading-text
 is mapped to the bold-italic style if available in the font family.
 .
-The inset level is reset to 1 and paragraph indentation to the default.
+The inset level is reset to 1,
+setting the left margin to the value of the
+.B IN \" TODO: future: BP or BI register ("base paragraph indentation")
+register.
 .
 Text after
 .I heading-text
@@ -630,9 +633,6 @@ as a subsection heading indented between a section heading 
and an
 ordinary paragraph
 .RB ( .P ).
 .
-See subsection \(lqHorizontal and vertical spacing\(rq below for the
-indentation amount.
-.
 If no argument is given,
 a one-line input trap is planted;
 text on the next line
@@ -640,7 +640,9 @@ text on the next line
 becomes
 .I subheading-text.
 .
-This text is set in bold
+The left margin is reset to the value of the
+.B SN
+register to set the heading text in bold
 (or the font specified by the string
 .BR HF ).
 .
@@ -651,7 +653,10 @@ use of an italic style in
 .I subheading-text
 is mapped to the bold-italic style if available in the font family.
 .
-The inset level is reset to 1 and paragraph indentation to the default.
+The inset level is reset to 1,
+setting the left margin to the value of the
+.B IN \" TODO: future: BP or BI register ("base paragraph indentation")
+register.
 .
 Text after
 .I subheading-text
@@ -738,16 +743,18 @@ installation.
 .IR inset-amount ]
 Start a new relative inset level.
 .
-The left margin moves right by
+The position of the left margin is saved,
+then moved right by
 .I inset-amount,
 if specified,
-and by a default amount otherwise;
-see subsection \(lqHorizontal and vertical spacing\(rq below.
+and by the amount of the
+.B IN
+register otherwise.
 .
 Calls to
 .B .RS
 can be nested;
-each increments \" by\~1
+each increments by\~1
 the inset level used by
 .BR .RE .
 .
@@ -759,12 +766,14 @@ calls is\~1.
 .TP
 .BR .RE " ["\c
 .IR level ]
-End a relative inset;
-move the left margin back to that corresponding to inset level
-.I level.
+End a relative inset.
+.
+The left margin corresponding to inset level
+.I level
+is restored.
 .
 If no argument is given,
-move the left margin one level back.
+the inset level is reduced by\~1.
 .
 .
 .\" ====================================================================
@@ -854,8 +863,9 @@ escape sequence.
 Subsequent text is indented by
 .I indentation,
 if specified,
-and by a default amount otherwise;
-see subsection \(lqHorizontal and vertical spacing\(rq below.
+and by the amount of the
+.B IN
+register otherwise.
 .
 If the tag is not as wide as the indentation,
 the paragraph starts on the same line as the tag,
@@ -1982,36 +1992,15 @@ or
 or its synonyms is called;
 these clear the indentation entirely.
 .
-A relative inset created by
-.B .RS
-saves the current indentation,
-resets it to zero,
-and
-moves the left margin.
-.
-The new left margin persists until
-.BR .RS ,
-.BR .RE ,
-.BR .SH ,
-or
-.B .SS
-is called.
-.
 .
 .P
-The indentation amount exhibited by ordinary paragraphs set with
+The left margin used by ordinary paragraphs set with
 .B .P
 (and its synonyms)
 not within an
 .BR .RS / .RE
-relative inset,
-and the default used when
-.BR .IP ,
-.BR .RS ,
-.BR .TP ,
-and the deprecated
-.B .HP
-are not given an indentation argument,
+relative inset
+.\" TODO: future: BP or BI register ("base paragraph indentation")
 is 7.2n for typesetting devices
 and 7n for terminal devices
 (but see the
@@ -2024,7 +2013,9 @@ footers
 .BR .TH ),
 and section headings
 .RB ( .SH )
-are set at the left margin,
+are set at the page offset
+(see
+.MR groff @MAN7EXT@ )
 and subsection headings
 .RB ( .SS )
 indented from it by 3n
@@ -2032,7 +2023,8 @@ indented from it by 3n
 .B \-rSN
 option).
 .
-HTML output devices ignore indentation.
+.\" XXX: This is not true, but they do handle it badly.
+.\" HTML output devices ignore indentation.
 _ifstyle()dnl
 .
 .