[groff] 20/49: doc/groff.texi: Introduce Texinfo @deffn notation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit cc0a808a9c141b94cb2653c2a99db8d2436f6dc3
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Sep 20 12:52:15 2022 -0500

    doc/groff.texi: Introduce Texinfo @deffn notation.
---
 doc/groff.texi  |  16 ++++++
 man/groff.7.man | 158 ++++++++++++++++++++++++++++++++++++++++++++------------
 2 files changed, 141 insertions(+), 33 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index ee935552a..bbbbcda1d 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -795,6 +795,22 @@ system, and the command of that name.  In the first sense, 
@code{groff}
 is an extended dialect of the @code{roff} language, for which many
 similar implementations exist.
 
+The @code{roff} language features several major categories for which
+many items are predefined.  Presentations of these items feature the
+form in which the item is most commonly used on the left, and, aligned
+to the right margin, the name of the category in brackets.
+
+@deffn Register \n[example]
+The register @samp{example} is one that that @code{groff} @emph{doesn't}
+predefine.  You can create it yourself, though; see @ref{Setting
+Registers}.
+@end deffn
+
+To make this document useful as a reference and not merely amiable
+bedtime reading, we tend to present these syntax items in exhaustive
+detail when they arise.  References to topics discussed later in the
+text are frequent; skip material you don't understand yet.
+
 We use Texinfo's ``result'' (@result{}) and @error{} notations to
 present output written to the standard output and standard error
 streams, respectively.  Diagnostic messages from the GNU @code{troff}
diff --git a/man/groff.7.man b/man/groff.7.man
index 77923c598..2b64715df 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1602,40 +1602,122 @@ an increment or decrement is applied as if to\~0.
 .SH Requests
 .\" ====================================================================
 .
-In
-.IR groff ,
+.\" XXX: This is more of a groff_diff(7) sort of observation.
+In GNU
+.IR troff , \" GNU
 identifier names,
 including those of requests,
 can be arbitrarily long.
 .
-No bracketing or marking of long names is needed in request invocation
-syntax.
+Unlike register and string interpolations,
+long request names require no specialized syntax.
+.
+.
+.\" BEGIN Keep (roughly) parallel with groff.texi node "Requests".
+.P
+Invoke a request by specifying its name after a control character and
+zero or more spaces or tabs.
+.
+The invocation of an unrecognized request is interpreted as a macro
+call.
+.
+Defining a macro with the same name as a request replaces the request.
+.
+Deleting a request name with the
+.request .rm
+request makes it unavailable.
+.
+Requests can be aliased with
+.request .als ,
+permitting them to be wrapped or non-destructively replaced.
 .
 .
 .P
 Most requests take one or more arguments.
 .
-Tabs are permitted after a request name,
-before its first argument
+Tabs are permitted after a request name and before its first argument
 (if any),
 but arguments themselves must be separated only by space characters.
 .
+(Plan\~9
+.I troff \" Plan 9
+allows tabs to separate arguments.)
+.
 There is no inherent limit on argument length or quantity.
 .
+Generally,
+a space
+.I within
+a request argument is not relevant,
+not meaningful,
+or is supported by bespoke provisions,
+as with the
+.request .tl
+request's delimiters.
+.
+Some requests,
+like
+.request .ds ,
+interpret the remainder of the control line as a single argument.
+.
 .
 .P
-Not all details of request behavior are outlined here.
+Since spaces and tabs are ignored after a control character,
+they are commonly used to structure the source of documents or macro
+files with indentation.
 .
-Refer to the
-.I groff
-Texinfo manual or
-.MR groff_diff @MAN7EXT@ .
+.
+.P
+To prevent interpretation of a control character as such,
+prefix it with
+.RB \[lq] \[rs]& \[rq].
+.
+Since a control character is recognized only at the beginning of an
+input line or the branch of a control structure such as the
+.request .if
+request,
+this dummy character
+(or non-printing input break)
+evades that special context without affecting the output.
+.
+.
+.P
+Test the
+.register .br
+register inside a macro definition to determine which control character
+was used when calling it.
+.
+.
+.P
+There is no way to invoke an undefined request;
+such syntax is interpreted as a macro call instead.
+.
+If a macro of the desired name does not exist,
+it is created,
+assigned an empty definition,
+and a warning in category
+.B mac
+is emitted.
+.
+Calling an undefined macro
+.I does
+end a macro definition naming it as its end macro.
+.\" END Keep (roughly) parallel with groff.texi node "Requests".
 .
 .
 .\" ====================================================================
 .SS "Request short reference"
 .\" ====================================================================
 .
+Not all details of each request's behavior are outlined here.
+.
+Refer to the
+.I groff
+Texinfo manual or
+.MR groff_diff @MAN7EXT@ .
+.
+.
+.P
 .LS
 .
 .TPx
@@ -3544,23 +3626,40 @@ to the stream named
 .LE
 .
 .
-.P
-Besides these standard groff requests, there might be further macro
-calls.
-They can originate from a macro package (see
-.MR roff @MAN7EXT@
-for an overview) or from a preprocessor.
-.
+.br
+.ne 6v
+.\" ====================================================================
+.SH "Preprocessor tokens"
+.\" ====================================================================
 .
-.P
 Most preprocessors enclose content between a pair of characteristic
-macros.
+tokens.
+.
+Such a token must occur at the beginning of an input line and use the
+dot control character.
+.
+Spaces and tabs must not follow the control character or precede the
+end of the input line.
+.
+Deviating from these rules defeats a token's recognition by the
+preprocessor.
 .
+Tokens are generally preserved in preprocessor output and interpreted as
+macro calls subsequently by
+.IR @g@troff .
+.
+The
+.I @g@ideal
+preprocessor is not yet available in
+.IR groff .
+.
+.
+.P
 .TS
 box, center, tab (^);
 c | c | c
 CfCB | CfCB | CfCB.
-preprocessor^start macro^ end macro
+preprocessor^starting token^ending token
 =
 @g@chem^.cstart^.cend
 @g@eqn^.EQ^.EN
@@ -3574,7 +3673,6 @@ grap^.G1^.G2
 ^^.PF
 ^^.PY
 @g@refer^.R1^.R2
-@g@soelim^\f[I]none^\f[I]none
 @g@tbl^.TS^.TE
 _
 glilypond^.lilypond start^.lilypond stop
@@ -3583,14 +3681,6 @@ gpinyin^.pinyin start^.pinyin stop
 .TE
 .
 .
-.P
-The
-.I @g@ideal
-preprocessor is not available in
-.I groff
-yet.
-.
-.
 .\" ====================================================================
 .SH "Escape sequences"
 .\" ====================================================================
@@ -3716,6 +3806,8 @@ except for those defined as infix operators in numerical 
expressions,
 about which more below.
 .
 .
+.br
+.ne 2v
 .P
 The following escape sequences are handled similarly to characters since
 they don't take arguments and thus are allowed as delimiters:
@@ -4623,7 +4715,7 @@ formatted in a dummy environment.
 .
 .TP
 .ESCq x N
-Increase required line space by
+Increase vertical spacing of current output line by
 .IR N \~vees
 (or specified units;
 negative before,
@@ -5006,8 +5098,8 @@ is active.
 .
 .TPx
 .REG .br
-Within a macro, set to\~1 if macro called with the \[oq]normal\[cq]
-control character, and to\~0 otherwise.
+Interpolates\~1 if the currently executing macro was called using the
+normal control character and\~0 otherwise.
 .
 .TPx
 .REG .c