Next: Miscellaneous, Previous: I/O, Up: GNU troff Reference [Contents][Index]
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).
"
]contents'
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.
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).
Reserved for internal use.
Next: Miscellaneous, Previous: I/O, Up: GNU troff Reference [Contents][Index]