[groff] 35/49: [docs]: Update and sync discussion of identifiers.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 25d759cdffdc74955614022d3662f94b5428176c
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Sep 24 15:17:26 2022 -0500

    [docs]: Update and sync discussion of identifiers.
    
    Content:
    * Use a more precise cross-reference when discussing warning categories.
    * Note unusability of identifier '(' as a register or macro name in CSTR
      #54 interpolation forms.
    * Use @codequote* Texinfo commands to mark entire node as reviewed for
      correct ' and ` glyph usage.
    * Recast description of `\A` escape sequence.  Make the example more
      practical/realistic.
    * Drop redundant material.
    * Revise and expand discussion of unrecognized identifier handling.
      Cover identifiers that aren't requests/macros/strings/diversions or
      registers.
    * Further clarify name spaces.
    
    Style:
    * In our Texinfo manual, refer to "refer" program with the g- prefix
      since as that's the "house style" for the document.
    * Tighten wording.
    * Fix typos.
    
    Markup:
    * Add sync comment brackets.
    
    As usual, sync groff(7) with our Texinfo manual, omitting examples and
    foootnotes.
---
 doc/groff.texi  | 124 ++++++++++++++++++++++-----------------------
 man/groff.7.man | 154 +++++++++++++++++++++++++++++++++++++++++---------------
 2 files changed, 175 insertions(+), 103 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index daa1f36c8..e967aff52 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -6243,17 +6243,21 @@ not qualify, so our first attempt got a warning.
 
 @c =====================================================================
 
+@c BEGIN Keep (roughly) parallel with section "Identifiers" of groff(7).
 @node Identifiers, Formatter Instructions, Numeric Expressions, gtroff 
Reference
 @section Identifiers
 @cindex identifiers
 
 GNU @code{troff} has rules for properly formed
 @dfn{identifiers}---labels for objects with syntactical importance, like
-registers, names (macros, strings, or diversions), environments, fonts,
-styles, colors, character classes, glyphs, and streams.  An identifier
-consists of one or more characters with the exception of spaces, tabs,
-newlines, and invalid input characters.
-
+registers, names (macros, strings, or diversions), typefaces, glyphs,
+colors, character classes, environments, and streams.  An identifier
+consists of one or more characters excepting spaces, tabs, newlines, and
+invalid input characters.
+
+@c XXX: We might move this discussion earlier since it is applicable to
+@c troff input in general, and include a reference to the `trin`
+@c request.
 @cindex invalid input characters
 @cindex input characters, invalid
 @cindex characters, invalid input
@@ -6261,8 +6265,8 @@ newlines, and invalid input characters.
 Invalid input characters are a subset of control characters (from the
 sets ``C0 Controls'' and ``C1 Controls'' as Unicode describes them).
 When GNU @code{troff} encounters one in an identifier, it produces a
-warning in category @samp{input} (@pxref{Debugging}).  They are removed
-during intepretation; an identifier @samp{foo}, followed by an invalid
+warning in category @samp{input} (@pxref{Warnings}).  They are removed
+during interpretation: an identifier @samp{foo}, followed by an invalid
 character and then @samp{bar}, is processed as @samp{foobar}.
 
 On a machine using the ISO 646, 8859, or 10646 character encodings,
@@ -6315,81 +6319,74 @@ An identifier with a closing bracket (@samp{]}) in its 
name can't be
 accessed with bracket-form escape sequences that expect an identifier as
 a parameter.  For example, @samp{\[foo]]} accesses the glyph @samp{foo},
 followed by @samp{]} in whatever the surrounding context is, whereas
-@samp{\C'foo]'} formats a glyph named @samp{foo]}.
+@samp{\C'foo]'} formats a glyph named @samp{foo]}.  Similarly, the
+identifier @samp{(} can't be interpolated @emph{except} with bracket
+forms.
 
 @cindex @code{refer}, and macro names starting with @code{[} or @code{]}
 @cindex @code{[}, macro names starting with, and @code{refer}
 @cindex @code{]}, macro names starting with, and @code{refer}
 @cindex macro names, starting with @code{[} or @code{]}, and @code{refer}
 If you begin a macro, string, or diversion name with either of the
-characters @samp{[} or @samp{]}, you foreclose use of the @code{refer}
-preprocessor, which recognizes @samp{.[} and @samp{.]} as bilbilographic
+characters @samp{[} or @samp{]}, you foreclose use of the @code{grefer}
+preprocessor, which recognizes @samp{.[} and @samp{.]} as bibliographic
 reference delimiters.
 
-@codequotebacktick off
-@codequoteundirected off
-
 @Defesc {\\A, @code{'}, ident, @code{'}}
-Test whether an identifier @var{ident} is valid in @code{gtroff}.  It
-expands to the character@tie{}1 or@tie{}0 according to whether its
-argument (usually delimited by quotes) is or is not acceptable as the
-name of a string, macro, diversion, register, environment, or font.  It
-returns@tie{}0 if no argument is given.  This is useful for looking up
-user input in some sort of associative table.
-
-@Example
-\A'end-list'
-    @result{} 1
+Interpolate@tie{}1 if @var{ident} is a valid identifier in GNU
+@code{troff}, and@tie{}0 otherwise.  The delimiter need not be an
+apostrophe; see @ref{Escape Sequences}.  Because invalid input
+characters are removed (see above), invalid identifiers are empty or
+contain spaces, tabs, or newlines.
+
+You can employ @code{\A} to validate a macro argument before using it to
+construct another escape sequence or identifier.
+
+@Example
+.\" usage: init-coordinate-pair name val1 val2
+.\" Create a coordinate pair where name!x=val1 and
+.\" name!y=val2.
+.de init-coordinate-pair
+.  if \A'\\$1' \@{\
+.    if \B'\\$2' .nr \\$1!x \\$2
+.    if \B'\\$3' .nr \\$1!y \\$3
+.  \@}
+..
+.init-coordinate-pair center 5 10
+The center is at (\n[center!x], \n[center!y]).
+.init-coordinate-pair "poi@arrow{}nt" trash garbage \" ignored
+.init-coordinate-pair point trash garbage \" ignored
+    @result{} The center is at (5, 10).
 @endExample
-@endDefesc
-
-@xref{Escape Sequences}, for details on parameter delimiting characters.
-
-Identifiers in @code{gtroff} can be any length, but, in some contexts,
-@code{gtroff} needs to be told where identifiers end and text begins
-(and in different ways depending on their length):
-
-@itemize @bullet
-@item
-Single character.
 
-@cindex @code{(}, starting a two-character identifier
-@item
-Two characters.  Must be prefixed with @samp{(} in some situations.
-
-@cindex @code{[}, starting an identifier
-@cindex @code{]}, ending an identifier
-@item
-Arbitrary length (@code{gtroff} only).  Must be bracketed with @samp{[}
-and@tie{}@samp{]} in some situations.  Any length identifier can be put
-in brackets.
-@end itemize
+@noindent
+In this example, we also validated the numeric arguments; the registers
+@samp{point!x} and @samp{point!y} remain undefined.  @xref{Numeric
+Expressions} for the @code{\B} escape sequence.
+@endDefesc
 
 @cindex undefined identifiers
 @cindex identifiers, undefined
-Unlike many other programming languages, undefined identifiers are
-silently ignored or expanded to nothing.  When @code{gtroff} finds an
-undefined identifier, it emits a warning, doing the following:
-
-@itemize @bullet
-@item
-If the identifier is a string, macro, or diversion, @code{gtroff}
-defines it as empty.
-
-@item
-If the identifier is a register, @code{gtroff} defines it with a
-value of@tie{}0.
-@end itemize
-
-@xref{Warnings}, @ref{Interpolating Registers}, and @ref{Strings}.
+How GNU @code{troff} handles the interpretation of an undefined
+identifier depends on the context.  There is no way to invoke an
+undefined request; such syntax is interpreted as a macro call instead.
+If the identifier is being interpreted as a string, macro, or diversion,
+GNU @code{troff} emits a warning in category @samp{mac}, defines it as
+empty, and interpolates nothing.  If the identifier is being interpreted
+as a register, GNU @code{troff} emits a warning in category @samp{reg},
+initializes it to zero, and interpolates that value.  @xref{Warnings},
+@ref{Interpolating Registers}, and @ref{Strings}.  Attempting to use an
+undefined typeface, glyph, color, character class, environment, or
+stream generally provokes an error diagnostic.
 
+@need 1000
 @cindex name space, common, of macros, diversions, and strings
 @cindex common name space of macros, diversions, and strings
 @cindex macros, shared name space with strings and diversions
 @cindex strings, shared name space with macros and diversions
 @cindex diversions, shared name space with macros and strings
 Identifiers for requests, macros, strings, and diversions share a name
-space.
+space.  No other object types do.
 
 @Example
 .de xxx
@@ -6406,9 +6403,10 @@ bar
 @endExample
 
 @noindent
-As the previous example shows, GNU @code{troff} reuses the identifier
+The foregoing example shows that GNU @code{troff} reuses the identifier
 @samp{xxx}, changing it from a macro to a diversion.  No warning is
-emitted!  The contents of the first macro definition are lost.
+emitted, and the previous contents of @samp{xxx} are lost.
+@c END Keep (roughly) parallel with section "Identifiers" of groff(7).
 
 
 @c =====================================================================
diff --git a/man/groff.7.man b/man/groff.7.man
index 30d791d6a..add97c126 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1230,31 +1230,36 @@ containing them is surrounded by parentheses.
 .SH Identifiers
 .\" ====================================================================
 .
-An identifier is a label for an object of syntactical importance like
-a register,
-a name
-(macro,
-string,
-or diversion),
-an environment,
-a font,
-a style,
-a character class,
-a glyph,
-or a stream,
-comprising a sequence of one or more characters with the following
-exceptions.
-.
-.
-.IP \[bu]
-Spaces,
+.\" BEGIN Keep (roughly) parallel with groff.texi node "Identifiers".
+GNU
+.I troff \" GNU
+has rules for properly formed
+.IR identifiers \[em]labels
+for objects with syntactical importance,
+like registers,
+names
+(macros,
+strings,
+or diversions),
+typefaces,
+glyphs,
+colors,
+character classes,
+environments,
+and streams.
+.
+An identifier consists of one or more characters excepting
+spaces,
 tabs,
-or newlines.
+newlines,
+and invalid input characters.
 .
 .
-.IP \[bu]
-Invalid input characters;
-these are certain control characters
+.\" XXX: We might move this discussion earlier since it is applicable to
+.\" troff input in general, and include a reference to the `trin`
+.\" request.
+.P
+Invalid input characters are subset of control characters
 (from the sets \[lq]C0 Controls\[rq] and \[lq]C1 Controls\[rq] as
 Unicode describes them).
 .
@@ -1262,12 +1267,18 @@ When
 .I @g@troff
 encounters one in an identifier,
 it produces a warning in category
-.RB \[lq] input \[rq]
+.RB \%\[lq] input \[rq]
 (see section \[lq]Warnings\[rq] in
 .MR @g@troff @MAN1EXT@ ).
 .
+They are removed during interpretation:
+an identifier \[lq]foo\[rq],
+followed by an invalid
+character and then \[lq]bar\[rq],
+is processed as \[lq]foobar\[rq].
+.
 .
-.IP
+.P
 On a machine using the ISO 646,
 8859,
 or 10646 character encodings,
@@ -1279,8 +1290,6 @@ invalid input characters are
 and
 .BR 0x80 \[en] 0x9F .
 .
-.
-.IP
 On an EBCDIC host,
 they are
 .BR 0x00 \[en] 0x01 ,
@@ -1292,27 +1301,92 @@ they are
 and
 .BR 0x30 \[en] 0x3F .
 .
-.
-.IP
 Some of these code points are used by
 .I @g@troff
 internally,
 making it non-trivial to extend the program to accept UTF-8 or other
 encodings that use characters from these ranges.
 .
-(Consider what happens when a C1 control
-.BR 0x80 \[en] 0x9F
-is necessary as a continuation byte in a UTF-8 sequence.)
 .
+.P
+An identifier with a closing bracket (\[lq]]\[rq]) in its name can't be
+accessed with bracket-form escape sequences that expect an identifier as
+a parameter.
+.
+Similarly,
+the
+identifier \[lq](\[rq] can't be interpolated
+.I except
+with bracket forms.
+.
+.
+.P
+If you begin a macro,
+string,
+or diversion name with either of the characters \[lq][\[rq] or
+\[lq]]\[rq],
+you foreclose use of the
+.MR @g@refer @MAN1EXT@
+preprocessor,
+which recognizes \[lq].[\[rq] and \[lq].]\[rq] as bibliographic
+reference delimiters.
+.
+.
+.P
+The escape sequence
+.B \[rs]A
+tests its argument for validity as an identifier.
+.
+.
+.P
+How GNU
+.I troff \" GNU
+handles the interpretation of an undefined identifier depends on the
+context.
+.
+There is no way to invoke an undefined request;
+such syntax is interpreted as a macro call instead.
+.
+If the identifier is being interpreted as a string,
+macro,
+or diversion,
+.I @g@troff
+emits a warning in category
+.RB \[lq] mac \[rq],
+defines it as empty,
+and interpolates nothing.
+.
+If the identifier is being interpreted as a register,
+.I @g@troff
+emits a warning in category
+.RB \[lq] reg \[rq],
+initializes it to zero,
+and interpolates that value.
+.
+See section \[lq]Warnings\[rq] in
+.MR @g@troff @MAN1EXT@ ,
+and subsection \[lq]Interpolating registers\[rq] and section
+\[lq]Strings\[rq] below.
+.
+Attempting to use an undefined
+typeface,
+style,
+glyph,
+color,
+character class,
+environment,
+or stream generally provokes an error diagnostic.
+.
+.
+.P
+Identifiers for requests,
+macros,
+strings,
+and diversions share a name
+space.
 .
-.IP
-Invalid characters are removed during interpretation;
-an identifier
-.RB \[lq] foo \[rq],
-followed by an invalid character and then
-.RB \[lq] bar \[rq],
-is processed as
-.RB \[lq] foobar \[rq] .
+No other object types do.
+.\" END Keep (roughly) parallel with groff.texi node "Identifiers".
 .
 .
 .\" ====================================================================
@@ -1785,7 +1859,7 @@ If a macro of the desired name does not exist,
 it is created,
 assigned an empty definition,
 and a warning in category
-.B mac
+.RB \[lq] mac \[rq]
 is emitted.
 .
 Calling an undefined macro