[groff] 02/02: groff_man(7): Clarify left margin vs. indentation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 110decc7eecfa2a9b0d56f293bb934e4bd09d1ba
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Jul 18 13:06:37 2020 +1000

    groff_man(7): Clarify left margin vs. indentation.
    
    * tmac/groff_man.7.man (.PP, .LP, .P): Fix error; these macros
      do not reset the left margin.
    
      The mis-statement dates back to
      da3b71378ea6e291864f1dc4efe088c069777ed9 (6 March 2000).  Exploring
      the history of what we now call an-old.tmac, the file has undergone
      mutliple renames, but the definition of .LP has been very stable.
      Since James Clark's implementation as of June 1991 (the horizon of our
      Git repository), it has changed only by dropping a .br request at the
      beginning and adding an .ns request at the end.
    
      .LP typesets the subsequent text _at_ the current left margin setting,
      but does not _change_ that left margin.  In 2003, groff_man(7) was
      updated to accurately document the fact that the macro resets the
      indentation ("prevailing indent", as it is termed in the
      implementation), but the old incorrect claim regarding the left margin
      was left in place.
    
      Here's what the relevant part of (what is now) an-old.tmac looked like
      back then.  The 1991 James Clark implementation differs only
      cosmetically, by not indenting the macro body.
    
    .de LP
    .  br
    .  sp \\n[PD]u
    .  ps \\n[PS]u
    .  vs \\n[VS]u
    .  ft R
    .  in \\n[an-margin]u
    .  nr an-prevailing-indent \\n[IN]
    ..
    .
    .als PP LP
    .als P LP
    
      (.TP): Clarify summary description.
    
      (Horizontal and vertical spacing):  Add lengthy example of
      manipulation of left margin and indentation with appropriate macros.
      This is tutorial material to be excluded from the groff_man(7)
      reference page in the planned "branching" of this document.
    
      Relatedly, mark the paragraph encouraging use of tbl(1) for tables
      instead of weird hacks with tagged paragraphs or tabs (or, so
      horrendous I dare not mention them and give bad people bad ideas, the
      \w escape) as tutorial and style guide material.
---
 ChangeLog            |   5 ++
 tmac/groff_man.7.man | 147 +++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 149 insertions(+), 3 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index f9ffa69..36902c3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2020-07-18  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * tmac/groff_man.7.man (.PP, .LP, .P): Fix error; these macros
+       do not reset the left margin.
+
 2020-07-16  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * doc/groff.texi (Strings): Document behavior of .ds request
diff --git a/tmac/groff_man.7.man b/tmac/groff_man.7.man
index 4b1dfd0..24ad9f1 100644
--- a/tmac/groff_man.7.man
+++ b/tmac/groff_man.7.man
@@ -629,14 +629,20 @@ see subsection \(lqFont style macros\(rq below.
 Begin a new paragraph;
 these macros are synonymous.
 .
-The left margin and indentation are reset to default values.
+The indentation is reset to the default value;
+the left margin,
+as affected by
+.B .RS
+and
+.BR .RE,
+is not.
 .
 .
 .TP
 .BR .TP " ["\c
 .IR indent ]
-Set a tagged,
-indented paragraph.
+Set a paragraph with a leading tag,
+and the remainder of the pargraph indented.
 .
 The input line following this macro,
 known as the
@@ -1602,6 +1608,140 @@ are indented 3n
 (but see the
 .B \-rSN
 option).
+.\" BEGIN STYLE
+.
+.
+.PP
+It may be helpful to think of the left margin and indentation as related
+but distinct concepts;
+.IR groff 's
+implementation of the
+.I man
+macro package tracks them separately.
+.
+The left margin is manipulated by
+.B .RS
+and
+.B .RE
+(and by
+.\".BR .TH ,\" True but not to be encouraged within a document.
+.B .SH
+and
+.BR .SS ,
+which reset it to the default).
+.
+.
+The other kind of indentation is controlled by the paragraphing macros
+(though,
+again,
+.\".BR .TH ,
+.B .SH
+and
+.BR .SS
+reset it).
+.
+Indentation is imposed by the
+.BR .TP ,
+.BR .IP ,
+and deprecated
+.B .HP
+macros,
+and cancelled by
+.B .PP
+and its synonyms.
+.
+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.
+.
+.
+.RS
+.PP
+Now we have moved the left margin with
+.B .RS
+and started another block paragraph with
+.BR .PP .
+.
+.TP
+.B tag
+This tagged paragraph,
+set with
+.BR .TP ,
+is still within the
+.B .RS
+region,
+but lines after the first have a supplementary indentation that the
+tag lacks.
+.
+.
+.IP
+A paragraph like this one,
+set with
+.BR .IP ,
+will appear to the reader as also associated with the tag above,
+because
+.B .IP
+re-uses the previous pargraph's indentation unless given an argument
+to change it.
+.
+This paragraph is affected both by the moved left margin
+.RB ( .RS )
+and ordinary indentation
+.RB ( .IP ).
+.
+.
+.TS
+box;
+l.
+This table is affected both by
+the left margin and the indent.
+.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;
+only the former affects the tag,
+but both affect the text of the paragraph.
+.
+.
+.PP
+This normal
+.RB ( .PP )
+paragraph resets the indentation,
+but the left margin is still in place.
+.
+.
+.TS
+box;
+l.
+This table is affected only
+by the left margin.
+.TE
+.RE
+.
+.
+.PP
+Finally,
+we have ended the relative indent by using
+.BR .RE ,
+which
+(because we only used one
+.BR .RS / .RE
+pair)
+has reset the left margin to the default.
+.
+This is an ordinary
+.B .PP
+paragraph.
 .
 .
 .PP
@@ -1619,6 +1759,7 @@ or which is developed in the future.
 The table preprocessor
 .IR @g@tbl (@MAN1EXT@)
 can likely meet your needs.
+.\" END STYLE
 .
 .
 .PP