5.6.4 Using Escape Sequences

Whereas requests must occur on control lines, escape sequences can occur intermixed with text and may appear in arguments to requests, macros, and other escape sequences. An escape sequence is introduced by the escape character, a backslash \ (but see the ec request below). The next character selects the escape’s function.

Escape sequences vary in length. Some take an argument, and of those, some have different syntactical forms for a one-character, two-character, or arbitrary-length argument. Others accept only an arbitrary-length argument. In the former scheme, a one-character argument follows the function character immediately, an opening parenthesis ‘(’ introduces a two-character argument (no closing parenthesis is used), and an argument of arbitrary length is enclosed in brackets ‘[]’. In the latter scheme, the user selects a delimiter character. A few escape sequences are idiosyncratic, and support both of the foregoing conventions (\s), designate their own termination sequence (\?), consume input until the next newline (\!, \", \#), or support an additional modifier character (\s again, and \n). As with requests, use of some escape sequences in source documents may interact poorly with a macro package you use; consult its documentation to learn of “safe” sequences or alternative facilities it provides to achieve the desired result.

If an escape character is followed by a character that does not identify a defined operation, the escape character is ignored (producing a diagnostic of the ‘escape’ warning category, which is not enabled by default) and the following character is processed normally.

$ groff -Tps -ww
.nr N 12
.ds co white
.ds animal elephant
I have \fI\nN \*(co \*[animal]s,\f[]
said \P.\&\~Pseudo Pachyderm.
    error→ warning: escape character ignored before 'P'
    ⇒ I have 12 white elephants, said P. Pseudo Pachyderm.

Escape sequence interpolation is of higher precedence than escape sequence argument interpretation. This rule affords flexibility in using escape sequences to construct parameters to other escape sequences.

.ds family C\" Courier
.ds style I\" oblique
Choice a typeface \f(\*[family]\*[style]wisely.
    ⇒ Choose a typeface wisely.

In the above, the syntax form ‘\f(’ accepts only two characters for an argument; the example works because the subsequent escape sequences are interpolated before the selection escape sequence argument is processed, and strings family and style interpolate one character each.⁴⁶

The escape character is nearly always interpreted when encountered; it is therefore desirable to have a way to interpolate it, disable it, or change it.

Escape sequence: \e

Interpolate the escape character.

The \[rs] special character escape sequence formats a backslash glyph. In macro and string definitions, the input sequences \\ and \E defer interpretation of escape sequences. See Copy Mode.

Request: .eo

Disable the escape mechanism except in copy mode. Once this request is invoked, no input character is recognized as starting an escape sequence in interpretation mode.

Request: .ec [o]

Recognize the ordinary character o as the escape character. If o is absent or invalid, the default escape character ‘\’ is selected.

Switching escape sequence interpretation off to define a macro and back on afterward can obviate the need to double the escape character within the definition. See Writing Macros. This technique is not available if your macro needs to interpolate values at the time it is defined—but many do not.

.\" simplified `BR` macro from the man(7) macro package
.eo
.de BR
.  ds result \&
.  while (\n[.$] >= 2) \{\
.    as result \fB\$1\fR\$2\"
.    shift 2
.  \}
.  if \n[.$] .as result \fB\$1\"
\*[result]
.  rm result
.  ft R
..
.ec

Request: .ecs

Request: .ecr

The ecs request stores the escape character for recall with ecr. ecr sets the escape character to ‘\’ if none has been saved.

Use these requests together to temporarily change the escape character.

Using a different escape character, or disabling it, when calling macros not under your control will likely cause errors, since GNU troff has no mechanism to “intern” macros—that is, to convert a macro definition into a form independent of its representation.⁴⁷ When a macro is called, its contents are interpreted literally.