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 set¹¹⁵ 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.¹¹⁶ 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: \Yn

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.