Postprocessor Access (The GNU Troff Manual)

### 5.34 Postprocessor Access

Two escape sequences and two requests enable documents to pass information directly to a postprocessor. These are useful for exercising device-specific capabilities that the `groff` language does not abstract or generalize; examples include the embedding of hyperlinks and image files. Device-specific functions are documented in each output driver’s man page, such as gropdf(1), grops(1), or grotty(1).

Request: `.device` xxx … ¶
Escape sequence: `\X`'``xxx …``'`` ¶

  Embed all xxx arguments into GNU `troff` output as parameters to a device control command ‘`x X`’. The meaning and interpretation of such parameters is determined by the output driver or other postprocessor.

  The `device` request processes its arguments in copy mode (see Copy Mode). An initial neutral double quote in contents is stripped to allow embedding of leading spaces. By contrast, within `\X` arguments, the escape sequences `\&`, `\)`, `\%`, and `\:` are ignored; `\`SP`` and `\~` are converted to single space characters; and `\\` has its escape character stripped. So that the basic Latin subset of the Unicode character set115 can be reliably encoded in device control commands, seven special character escape sequences (‘`\-`’, ‘`\[aq]`’, ‘`\[dq]`’, ‘`\[ga]`’, ‘`\[ha]`’, ‘`\[rs]`’, and ‘`\[ti]`’,) are mapped to basic Latin characters; see the groff_char(7) man page. For this transformation, character translations and special character definitions are ignored.116 The use of any other escape sequence in `\X` parameters is normally an error.

  If the `use_charnames_in_special` directive appears in the output device’s `DESC` file, the use of special character escape sequences is not an error; they are simply output verbatim (with the exception of the seven mapped to Unicode basic Latin characters, discussed above). `use_charnames_in_special` is currently employed only by `grohtml`.

Request: `.devicem` name ¶
Escape sequence: `\Y`n`` ¶
Escape sequence: `\Y(`nm`` ¶
Escape sequence: `\Y[`name`]` ¶

  This is approximately equivalent to ‘`\X'\*[name]'`’ (one-character name n, two-character name nm). However, the contents of the string or macro name are not interpreted; also it is permitted for name to have been defined as a macro and thus contain newlines (it is not permitted for the argument to `\X` to contain newlines). The inclusion of newlines requires an extension to the AT&T `troff` output format, and confuses drivers that do not know about this extension (see Device Control Commands).

Request: `.tag` name ¶
Request: `.taga` name ¶

  Reserved for internal use.