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 ["]contents
Escape sequence: \X'contents '

Embed contents into GNU troff output as parameters to an ‘x X device extension command.137 The interpretation of such parameters is determined by the output driver or other postprocessor.

A leading neutral double quote in the argument to device is stripped from it, allowing embedded leading spaces in contents, which is read to the end of the input line in copy mode.

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.

The groff special character repertoire is unknown to output drivers outside of glyphs named in a device’s fonts, and even then they may not possess complete coverage of the names documented in the groff_char(7) man page. Further, escape sequences that produce horizontal or vertical motions, hyphenation breaks, or that are dummy characters may appear in strings or be converted to nodes, particularly in diversions (see gtroff Internals). These are not representable when interpolated directly into device-independent output, as might be done when writing out tag names for PDF bookmarks, which can appear in a viewer’s navigation pane.

So that documents or macro packages do not have to laboriously “sanitize” strings destined for interpolation in device extension commands, the \X escape sequence performs certain transformations on its argument. For these transformations, character translations and definitions are ignored.

GNU troff converts several ordinary characters that typeset as non-basic Latin code points to code points outside that range so that they are used consistently whether they are formatted as glyphs or used in a device extension command argument. These ordinary characters are ‘'’, ‘-’, ‘^’, ‘`’, and ‘~’; others are written as-is.

Special characters that typeset as Unicode basic Latin characters are translated to basic Latin characters accordingly. So that any Unicode code point can be represented in device extension commands, for example in an author’s name in document metadata or as a usefully named bookmark or hyperlink anchor, GNU troff maps other special characters to Unicode special character notation. See Using Symbols.

Special characters without a Unicode representation, and escape sequences that do not interpolate a sequence of ordinary and/or special characters, produce warnings in category ‘char’.

GNU troff also permits the interpolation of macro contents as a device extension command.

Request: .devicem name
Escape sequence: \Yn
Escape sequence: \Y(nm
Escape sequence: \Y[name]

The devicem request and \Y escape sequence are each approximately equivalent to ‘\X'\*[name]'’ (one-character name n, two-character name nm). They differ from that construction in that the contents of the string or macro name are not interpreted; further, name may be a macro and thus contain newlines. (There is no way to embed a newline in the arguments to device or \X.) The inclusion of newlines requires an extension to the AT&T troff device-independen page description language; their presence confuses drivers that do not know about it (see Device Control Commands).

Request: .tag name
Request: .taga name

Reserved for internal use.