[groff] 08/19: groff_man*(7): Discuss input traps explicitly.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d8bf49720b7f38ed9c3abcfdd9f8453a4a6e487f
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Jul 6 04:08:14 2022 -0500

    groff_man*(7): Discuss input traps explicitly.
    
    ...now that I understand them.[citation needed]
    
    The behavior of input traps is sufficiently subtle that there's no point
    trying to avoid mentioning them.  Be forthright and document when
    they're used.
    
    In groff_man_style(7), add an introductory paragraph attempting to
    demystify them enough for practical understanding.
---
 tmac/groff_man.7.man.in | 85 +++++++++++++++++++++++++++++++++++--------------
 1 file changed, 61 insertions(+), 24 deletions(-)

diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 0cb1218e..1b1cd097 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -299,6 +299,25 @@ the verb \(lqto set\(rq is frequently used below in the 
sense \(lqto
 typeset\(rq.
 .
 .
+.P
+We describe below several
+.I man
+macros that plant one-line
+.I input traps:
+the next input line that directly produces formatted output is treated
+specially.
+.
+For
+.I man
+documents written in the language subset described in section
+\[lq]Portability\[rq] below,
+this means that control lines using the empty request
+and uncommented input lines ending with an escaped newline or the
+.B \[rs]c
+escape sequence do not spring the trap;
+anything else does.
+.
+.
 _endif()dnl
 .\" ====================================================================
 .SS "Document structure macros"
@@ -459,11 +478,14 @@ Set
 .I heading-text
 as a section heading.
 .
-Its argument,
-or the text on the next input line if
-.B .SH
-is given none,
-is set at the left margin,
+If no argument is given,
+a one-line input trap is planted;
+text on the next line
+.\", which can be formatted with a macro, \" true but discouraged
+becomes
+.I heading-text.
+.
+This text is set at the left margin,
 in bold
 (or the font specified by the string
 .BR HF )
@@ -529,11 +551,14 @@ ordinary paragraph
 See subsection \(lqHorizontal and vertical spacing\(rq below for the
 indentation amount.
 .
-Its argument,
-or the text on the next input line if
-.B .SS
-is given none,
-is set in bold
+If no argument is given,
+a one-line input trap is planted;
+text on the next line
+.\", which can be formatted with a macro, \" true but discouraged
+becomes
+.I subheading-text.
+.
+This text is set in bold
 (or the font specified by the string
 .BR HF ).
 .
@@ -740,10 +765,11 @@ is not.
 Set a paragraph with a leading tag,
 and the remainder of the paragraph indented.
 .
-The input line following this macro,
-known as the
-.I tag,
-is printed at the current left margin.
+A one-line input trap is planted;
+text on the next line,
+which can be formatted with a macro,
+becomes the tag,
+which is placed at the current left margin.
 .
 Subsequent text is indented by
 .I indentation,
@@ -785,8 +811,7 @@ Set an additional tag for a paragraph tagged with
 .
 The pending output line is broken.
 .
-The tag on the input line following this macro and subsequent lines are
-handled as with
+A one-line input trap is planted as with
 .BR .TP .
 .
 .
@@ -1496,8 +1521,11 @@ Set
 .I text
 in bold.
 .
-If the macro is given no arguments,
-the text of the next input line is set in bold.
+If no argument is given,
+a one-line input trap is planted;
+text on the next line,
+which can be further formatted with a macro,
+is set in bold.
 .
 .
 _ifstyle()dnl
@@ -1527,8 +1555,11 @@ Set
 .I text
 in an italic or oblique face.
 .
-If the macro is given no arguments,
-the text of the next input line is set in an italic or oblique face.
+If no argument is given,
+a one-line input trap is planted;
+text on the next line,
+which can be further formatted with a macro,
+is set in an italic or oblique face.
 .
 .
 _ifstyle()dnl
@@ -1568,8 +1599,11 @@ Set
 .I text
 one point smaller than the default type size on typesetter devices.
 .
-If the macro is given no arguments,
-the text of the next input line is set smaller.
+If no argument is given,
+a one-line input trap is planted;
+text on the next line,
+which can be further formatted with a macro,
+is set smaller.
 .
 .
 _ifstyle()dnl
@@ -1596,8 +1630,11 @@ in bold and
 (on typesetter devices)
 one point smaller than the default type size.
 .
-If the macro is given no arguments,
-the text of the next input line is set smaller and in bold.
+If no argument is given,
+a one-line input trap is planted;
+text on the next line,
+which can be further formatted with a macro,
+is set smaller and in bold.
 .
 .
 _ifstyle()dnl