File: groff.info,  Node: Postprocessor Access,  Next: Miscellaneous,  Prev: I/O,  Up: GNU troff Reference

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 (*note
     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; '\' and '\~' are converted to single space characters;
     and '\\' has its escape character stripped.  So that the basic
     Latin subset of the Unicode character set(1) (*note Postprocessor
     Access-Footnote-1::) 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.(2)  (*note Postprocessor
     Access-Footnote-2::) 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 (*note Device Control Commands::).

 -- Request: .tag name
 -- Request: .taga name
     Reserved for internal use.