Beyond the
cf
and
trf
requests
(recall
I/O),
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).
.device ["]contents ¶\X'contents …'Embed contents into GNU troff output as parameters to an
‘x X’ device extension command.146
The interpretation of such parameters is determined by the output driver
or other postprocessor.
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 (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.
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;
when encountered,
these produce warnings in category ‘char’.
See Warnings.
GNU
troff also permits the interpolation of macro or string contents
as a device extension command.
.devicem name ¶\Yn\Y(nm\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
(see Device Control Commands).