5.5 Identifiers

An identifier labels a GNU troff datum such as a register, name (macro, string, or diversion), typeface, color, special character, character class, environment, or stream. Valid identifiers consist of one or more ordinary characters. An ordinary character is an input character that is not the escape character, a leader, tab, newline, or invalid as GNU troff input.

Invalid input characters are a subset of control characters (from the sets “C0 Controls” and “C1 Controls” as Unicode describes them). When GNU troff encounters one in an identifier, it produces a warning in category ‘input’ (see Warnings). They are removed during interpretation: an identifier ‘foo’, followed by an invalid character and then ‘bar’, is processed as ‘foobar’.

On a machine using the ISO 646, 8859, or 10646 character encodings, invalid input characters are 0x00, 0x08, 0x0B, 0x0D–0x1F, and 0x80–0x9F. On an EBCDIC host, they are 0x00–0x01, 0x08, 0x09, 0x0B, 0x0D–0x14, 0x17–0x1F, and 0x30–0x3F.⁴⁰ Some of these code points are used by GNU troff internally, making it non-trivial to extend the program to accept UTF-8 or other encodings that use characters from these ranges.⁴¹

Thus, the identifiers ‘br’, ‘PP’, ‘end-list’, ‘ref*normal-print’, ‘|’, ‘@_’, and ‘!"#$%'()*+,-./’ are all valid. Discretion should be exercised to prevent confusion. Identifiers starting with ‘(’ or ‘[’ require care.

.nr x 9
.nr y 1
.nr (x 2
.nr [y 3
.nr sum1 (\n(x + \n[y])
    error→ a space character is not allowed in an escape
    error→   sequence parameter
A:2+3=\n[sum1]
.nr sum2 (\n((x + \n[[y])
B:2+3=\n[sum2]
.nr sum3 (\n[(x] + \n([y)
C:2+3=\n[sum3]
    ⇒ A:2+3=1 B:2+3=5 C:2+3=5

An identifier with a closing bracket (‘]’) in its name can’t be accessed with bracket-form escape sequences that expect an identifier as a parameter. For example, ‘\[foo]]’ accesses the glyph ‘foo’, followed by ‘]’ in whatever the surrounding context is, whereas ‘\C'foo]'’ formats a glyph named ‘foo]’. Similarly, the identifier ‘(’ can’t be interpolated except with bracket forms.

If you begin a macro, string, or diversion name with either of the characters ‘[’ or ‘]’, you foreclose use of the grefer preprocessor, which recognizes ‘.[’ and ‘.]’ as bibliographic reference delimiters.

Escape sequence: \A'anything'

Interpolate 1 if anything is a valid identifier, and 0 otherwise. The delimiter need not be a neutral apostrophe; see Delimiters. Because invalid input characters are removed (see above), invalid identifiers are empty or contain spaces, tabs, or newlines.

You can employ \A to validate a macro argument before using it to construct another escape sequence or identifier.

.\" 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→nt" trash garbage \" ignored
.init-coordinate-pair point trash garbage \" ignored
    ⇒ The center is at (5, 10).

In this example, we also validated the numeric arguments; the registers ‘point!x’ and ‘point!y’ remain undefined. See Numeric Expressions for the \B escape sequence.

How GNU 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 interpreted as a string, macro, or diversion, GNU troff emits a warning in category ‘mac’, defines it as empty, and interpolates nothing. If the identifier is interpreted as a register, GNU troff emits a warning in category ‘reg’, initializes it to zero, and interpolates that value. See Warnings, Interpolating Registers, and Strings. Attempting to use an undefined typeface, special character, color, character class, environment, or stream generally provokes an error diagnostic.

Identifiers for requests, macros, strings, and diversions share one name space; special characters and character classes another. No other object types do.

.de xxx
.  nop foo
..
.di xxx
bar
.br
.di
.
.xxx
    ⇒ bar

The foregoing example shows that GNU troff reuses the identifier ‘xxx’, changing it from a macro to a diversion. No warning is emitted, and the previous contents of ‘xxx’ are lost.