[groff] 15/19: [docs]: Clarify .ig and .de behavior.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 3bfd4798f24d0c9eac56d7802749e1e0ee86e53d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Nov 9 09:27:39 2021 +1100

    [docs]: Clarify .ig and .de behavior.
    
    * Note that `ig`s and macro definitions must end at the same brace scope
      at which they began.
    * Note that end tokens/macros must occur at the beginning of a control
      line ('if 1 ..' won't finish your macro definition).
    * Point out that .ig is parsed as .de is.
    * Explicitly point out that end macros can be called with arguments.
    * Drop redundancy in footnote.
---
 doc/groff.texi  | 37 ++++++++++++++-------------
 man/groff.7.man | 78 ++++++++++++++++++++++++++++++++++++---------------------
 2 files changed, 68 insertions(+), 47 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 8a38313..0a7f5ad 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -6465,14 +6465,13 @@ Test
 @endDefesc
 
 @Defreq {ig, [@Var{end}]}
-Ignore input until the macro @var{end} is called on a control line by
-itself (or @samp{..} is encountered if @var{end} is not
-specified).@footnote{Exception: auto-incrementing registers defined
-outside the ignored region @emph{will} be modified if interpolated with
-@code{\n�} inside it.  @xref{Auto-increment}.}  Spaces and tabs are
-allowed between the control character and @samp{.} or @var{end}.
-@code{ig} is useful for commenting out large regions of input.  The
-ignored region does not cause a break.
+Ignore input until, at the current brace scope, the macro @var{end} is
+called at the start of a control line, or the control line @samp{..} is
+encountered if @var{end} is not specified.  @code{ig} is parsed as if it
+were a macro definition, but its contents are discarded, not
+stored.@footnote{Exception: auto-incrementing registers defined outside
+the ignored region @emph{will} be modified if interpolated with
+@code{\n�} inside it.  @xref{Auto-increment}.}
 
 @c Wrap example at 56 columns.
 @Example
@@ -12107,13 +12106,15 @@ request, macro, string, or diversion called 
@var{name}.  GNU
 @code{troff} enters ``copy mode'', storing subsequent input lines as the
 macro definition.  If the optional second argument is not specified, the
 definition ends with the control line @samp{..} (two dots).
-Alternatively, @var{end} identifies a macro whose call syntax ends the
-definition of @var{name}; @var{end} is then called normally.  Spaces or
-tabs are permitted after the control character in the line containing
-this ending token (either @samp{.} or @samp{@var{end}}), but a tab
-immediately after the token prevents its recognition as the end of a
-macro definition.@footnote{While it is possible to define and call a
-macro @samp{.}, you can't use it as an end macro: during a macro
+Alternatively, @var{end} identifies a macro that, if called at the start
+of a control line, ends the definition of @var{name}; @var{end} is then
+called normally.  A macro definition must end at the same brace scope at
+which it began.  Spaces or tabs are permitted after the control
+character in the line containing this ending token (either @samp{.} or
+@samp{@var{end}}), but a tab immediately after the token prevents its
+recognition as the end of a macro definition.  The macro @var{end} can
+be called with arguments.@footnote{While it is possible to define and
+call a macro @samp{.}, you can't use it as an end macro: during a macro
 definition, @samp{..} is never handled as calling @samp{.}, even if
 @samp{.de @var{name} .} explicitly precedes it.}
 @c
@@ -12149,9 +12150,9 @@ unique end macro.
 An end macro need not be defined until it is called.  This fact enables
 a nested macro definition to begin inside one macro and end inside
 another.  Consider the following example.@footnote{The structure of this
-example is adapted from, and structurally isomorphic to, part of a
-solution by Tadziu Hoffman to the problem of reflowing text multiple
-times to find an optimal configuration for it.
+example is adapted from, and isomorphic to, part of a solution by Tadziu
+Hoffman to the problem of reflowing text multiple times to find an
+optimal configuration for it.
 @uref{https://lists.gnu.org/archive/html/groff/2008-12/msg00006.html}}
 
 @Example
diff --git a/man/groff.7.man b/man/groff.7.man
index c9c8d08..e3288df 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1683,12 +1683,13 @@ Append output to diversion
 .
 .
 .TPx
-.REQ .de "macro"
+.REQ .de macro
 Define or redefine
 .I macro
 until
-.B ..\&
-is encountered.
+.RB \[lq] ..\& \[rq]
+occurs at the start of a control line at the current brace scope.
+.
 .
 .TPx
 .REQ .de "macro end"
@@ -1696,19 +1697,20 @@ Define or redefine
 .I macro
 until
 .BI . end
-is called.
+is called at the start of a control line at the current brace scope.
+.
 .
 .TPx
 .REQ .de1 "macro"
-Same as
-.request .de
-but with compatibility mode switched off during macro expansion.
+As
+.request .de ,
+but disable compatibility mode during macro expansion.
 .
 .TPx
 .REQ .de1 "macro end"
-Same as
-.request .de
-but with compatibility mode switched off during macro expansion.
+As
+.request ".de\~\f[I]macro\~end\f[]" ,
+but disable compatibility mode during macro expansion.
 .
 .
 .TPx
@@ -1766,33 +1768,41 @@ that cannot be redefined.
 .
 .TPx
 .REQ .dei "macro"
-Define or redefine a macro whose name is contained in the string
-register
+Define macro indirectly.
+.
+As
+.request .de ,
+but use interpolation of string
 .I macro
-until
-.B ..\&
-is encountered.
+as the name of the defined macro.
+.
 .
 .TPx
 .REQ .dei "macro end"
-Define or redefine a macro indirectly.
+Define macro indirectly.
+.
+As
+.request .de ,
+but use interpolations of strings
 .I macro
 and
 .I end
-are string registers whose contents are interpolated for the macro name
-and the end macro, respectively.
+as the names of the defined and end macros.
+.
 .
 .TPx
 .REQ .dei1 "macro"
-Same as
-.request .dei
-but with compatibility mode switched off during macro expansion.
+As
+.request .dei ,
+but disable compatibility mode during macro expansion.
+.
 .
 .TPx
 .REQ .dei1 "macro end"
-Same as
-.request .dei
-but with compatibility mode switched off during macro expansion.
+As
+.request ".dei\~\f[I]macro\~end\f[]" ,
+but disable compatibility mode during macro expansion.
+.
 .
 .TPx
 .REQ .device "anything"
@@ -2218,15 +2228,25 @@ as if it were an input line.
 .
 .TPx
 .REQ .ig
-Ignore text until
-.B ..\&
-is encountered.
+Ignore input
+(except for side effects of
+.B \[rs]R
+on auto-incrementing registers)
+until
+.RB \[lq] ..\& \[rq]
+occurs at the start of a control line at the current brace scope.
+.
 .
 .TPx
 .REQ .ig "end"
-Ignore text until
+Ignore input
+(except for side effects of
+.B \[rs]R
+on auto-incrementing registers)
+until
 .BI . end
-is called.
+is called at the start of a control line at the current brace scope.
+.
 .
 .TPx
 .REQ .in