[groff] 08/17: [ms]: Document cautionary note about .in better.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit eb5055b8bf7ed87977865fb036a4d7d6d2536e70
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Jun 25 09:14:39 2021 +1000

    [ms]: Document cautionary note about .in better.
    
    An ms "reset" is only meaningful to macro package source divers and the
    advice that was given implied that it's up to the user to figure out
    which macros cause `par@reset` (not even identified by name) to be
    called.  Try to be a little more generous to the general user.
---
 doc/groff.texi      | 13 +++++++------
 doc/ms.ms           | 25 +++++++++++++++++++++++++
 tmac/groff_ms.7.man | 29 +++++++++++++++++------------
 3 files changed, 49 insertions(+), 18 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 1f0282d..8bcacda 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -4315,12 +4315,13 @@ put the date, in U.S.@: traditional format (e.g., 
``January 1, 2021''),
 in the center footer (the @code{CF} string).
 
 @item
-Macros that cause a reset (paragraphs, headings, etc.@:) may change the
-indentation.  Macros that change the indentation do not increment or
-decrement the indentation, but rather set it absolutely.  This can cause
-problems for documents that define additional macros of their own.  The
-solution is to use not the @code{in} request but instead the @code{RS}
-and @code{RE} macros.
+Macros that cause @code{groff} @file{ms} to internally reset its
+paragraph rendering parameters (paragraphs, headings, and displays,
+among others) may change the indentation; they do so not by incrementing
+or decrementing it, but set it absolutely.  This can cause problems for
+documents that define additional macros of their own that try to
+manipulate indentation.  The solution is to use, not the @code{in}
+request, but the @file{ms} @code{RS} and @code{RE} macros.
 
 @item
 To make @code{groff} @file{ms} use the default page offset (which also
diff --git a/doc/ms.ms b/doc/ms.ms
index 6e523b7..915f3a6 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -2756,6 +2756,31 @@ string).
 .
 .
 .PP
+Macros that cause
+.I "groff ms"
+to internally reset its paragraph rendering parameters
+(paragraphs,
+headings,
+and displays,
+among others)
+may change the indentation;
+they do so not by incrementing or decrementing it,
+but set it absolutely.
+.
+This can cause problems for documents that define additional macros of
+their own that try to manipulate indentation.
+.
+The solution is to use,
+not the
+.CW in
+request,
+but
+.CW .RS
+and
+.CW .RE .
+.
+.
+.PP
 Displays are left-adjusted by default,
 not indented.
 .
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 065735d..991e19a 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -1814,23 +1814,28 @@ string).
 .
 .
 .IP \[bu]
-Macros that cause a reset
-(paragraphs, headings, etc.\&)
-may change the indent.
-.
-Macros that change the indent do not increment or decrement the
-indent, but rather set it absolutely.
+Macros that cause
+.I groff ms
+to internally reset its paragraph rendering parameters
+(paragraphs,
+headings,
+and displays,
+among others)
+may change the indentation;
+they do so not by incrementing or decrementing it,
+but set it absolutely.
 .
 This can cause problems for documents that define additional macros of
-their own.
+their own that try to manipulate indentation.
 .
-The solution is to use not the
+The solution is to use,
+not the
 .B in
-request but instead the
-.B RS
+request,
+but
+.B .RS
 and
-.B RE
-macros.
+.BR .RE .
 .
 .
 .IP \[bu]