[groff] 02/02: groff_man(7): Add NOTES section to aid authors.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit db0c2bb27142ddc6286f6224852fadbd2ac7d82a
Author: G. Branden Robinson <address@hidden>
Date:   Thu Jun 21 08:16:14 2018 -0400

    groff_man(7): Add NOTES section to aid authors.
    
    Discuss asymmetry of .RS/.RE arguments and their consequences when
    misunderstood.  This came up recently in the quilt(1) man page and I
    know I've seen it multiple times before.
    
    Signed-off-by: G. Branden Robinson <address@hidden>
---
 tmac/groff_man.7.man | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/tmac/groff_man.7.man b/tmac/groff_man.7.man
index 2499ba6..5c06e2a 100644
--- a/tmac/groff_man.7.man
+++ b/tmac/groff_man.7.man
@@ -1551,6 +1551,45 @@ Local changes and customizations should be put into this 
file.
 .
 .
 .\" ====================================================================
+.SH NOTES
+.\" ====================================================================
+.
+Some tips on troubleshooting your man pages follow.
+
+.TP
+.RB \(bu " .RE" " doesn't reset the indent to the expected level
+.TQ
+\(bu warning: scale indicator invalid in this context
+.TQ
+\(bu warning: number register 'an\-saved\-margin2' not defined
+.TQ
+\(bu warning: number register 'an\-saved\-prevailing\-indent2' not \
+defined
+The
+.B .RS
+macro takes an indentation
+.I amount
+as an argument;
+the
+.B .RE
+macro's argument is an indentation
+.IR level .
+In other words,
+.BR .RE 's
+argument tells it the number of previous
+.B .RS
+calls you want to undo.
+.
+If you desire symmetry in your macro calls,
+simply issue one
+.B .RE
+without an argument
+for each
+.B .RS
+that precedes it.
+.
+.
+.\" ====================================================================
 .SH AUTHORS
 .\" ====================================================================
 The GNU version of the