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). In no case can an escape sequence parameter contain an unescaped newline. 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 the character that follows the escape character does not identify a valid operation, the formatter ignores the escape character.⁹¹ In copy mode, the escape character can be used to quote the escape or control characters.⁹²

$ groff -T ps -ww
.nr N 12
.ds co white
.ds animal elephant
I have \fI\nN \*(co \*[animal]s,\f[]
said \P.\&\~Pseudo Pachyderm.
    error→ warning: ignoring escape character 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
Choose 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 formatter interprets \e even in copy mode.⁹⁴

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.⁹⁵

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. If o (or ‘\’ if o is invalid) is already the control or no-break control character, an error is diagnosed and the request ignored.

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.