5.4 Identifiers

Like any other language, gtroff has rules for properly formed identifiers. In gtroff, an identifier can be made up of almost any printable character, with the exception of the following characters:

• Whitespace characters (spaces, tabs, and newlines).
• Backspace (ASCII 0x08 or EBCDIC 0x16) and character code 0x01.
• The following input characters are invalid and are ignored if groff runs on a machine based on ASCII, causing a warning message of type ‘input’ (see Debugging, for more details): 0x00, 0x0B, 0x0D-0x1F, 0x80-0x9F.

  And here are the invalid input characters if groff runs on an EBCDIC host: 0x00, 0x08, 0x09, 0x0B, 0x0D-0x14, 0x17-0x1F, 0x30-0x3F.

  Currently, some of these reserved codepoints are used internally, thus making it non-trivial to extend gtroff to cover Unicode or other character sets and encodings that use characters of these ranges.

  Note that invalid characters are removed before parsing; an identifier foo, followed by an invalid character, followed by bar is treated as foobar.

For example, any of the following is valid.

br
PP
(l
end-list
@_

Note that identifiers longer than two characters with a closing bracket (‘]’) in its name can’t be accessed with escape sequences that expect an identifier as a parameter. For example, ‘\[foo]]’ accesses the glyph ‘foo’, followed by ‘]’, whereas ‘\C'foo]'’ really asks for glyph ‘foo]’.

To avoid problems with the refer preprocessor, macro names should not start with ‘[’ or ‘]’. Due to backwards compatibility, everything after ‘.[’ and ‘.]’ is handled as a special argument to refer. For example, ‘.[foo’ makes refer to start a reference, using ‘foo’ as a parameter.

Escape: \A'ident'

Test whether an identifier ident is valid in gtroff. It expands to the character 1 or 0 according to whether its argument (usually delimited by quotes) is or is not acceptable as the name of a string, macro, diversion, number register, environment, or font. It returns 0 if no argument is given. This is useful for looking up user input in some sort of associative table.

\A'end-list'
    ⇒ 1

See Escapes, for details on parameter delimiting characters.

Identifiers in gtroff can be any length, but, in some contexts, gtroff needs to be told where identifiers end and text begins (and in different ways depending on their length):

• Single character.
• Two characters. Must be prefixed with ‘(’ in some situations.
• Arbitrary length (gtroff only). Must be bracketed with ‘[’ and ‘]’ in some situations. Any length identifier can be put in brackets.

Unlike many other programming languages, undefined identifiers are silently ignored or expanded to nothing. When gtroff finds an undefined identifier, it emits a warning, doing the following:

• If the identifier is a string, macro, or diversion, gtroff defines it as empty.
• If the identifier is a number register, gtroff defines it with a value of 0.

See Warnings., Interpolating Registers, and Strings.

Note that macros, strings, and diversions share the same name space.

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

As can be seen in the previous example, gtroff reuses the identifier ‘xxx’, changing it from a macro to a diversion. No warning is emitted! The contents of the first macro definition is lost.

See Interpolating Registers, and Strings.