5.35 Postprocessor Access

Beyond the cf and trf requests (recall Host System Service 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 ["]character-sequence

Escape sequence: \X'contents …'

Embed character-sequence into GNU troff output as parameters to an ‘x X’ device extension command.¹⁷⁶ The output driver or other postprocessor interprets character-sequence as it sees fit.

GNU troff removes a leading neutral double quote ‘"’ from contents, permitting initial embedded spaces in it, and reads it to the end of the input line in copy mode. Recall Copy Mode.

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.¹⁷⁷ 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. Recall Using Symbols.

GNU troff does not write special characters without a Unicode representation and escape sequences that do not interpolate a sequence of ordinary and/or special characters as arguments to device extension commands.¹⁷⁸

GNU troff also permits the interpolation of macro or string 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 correspond to ‘.device \*[name]’ and ‘\X'\*[name]'’ (one-character name n, two-character name nm), respectively. They differ from their counterparts in that GNU troff does not interpret the contents of the string or macro name; 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-independent page description language, and their presence confuses drivers that do not know about it.¹⁷⁹

Request: .tag name

Request: .taga name

Reserved for internal use.