Executing PostScript code in a groff document

Last-Updated: 2023-12-19

Sources:

What is \X?

\X is used at the beginning of a line to execute PostScript code. \X'…' passes "x X …" transparently to the post-processor (device driver) except that escape sequences are processed by troff (1999-10/msg00028).

To pass raw PS code straight to the printer (i.e. immune from grops) you need to use \X'ps: exec …' (1999-10/msg00029).

For details of X commands produced using \X, refer to the man page of each post-processor (e.g. grops(1), gropdf(1) or grodvi(1)).

Using \X with pdfmark

To embed PDF file metadata like bookmarks, notes, links, info directory entries, etc. into PostScript files, you can use the pdfmark PostScript operator. For example to create a bookmark, in PostScript you can do (1999-10/msg00033):

[ /Title (1. Introduction) /OUT pdfmark

With our previous knowledge, in groff, we can use:

\X'ps: exec [ /Title (1. Introduction) /OUT pdfmark'\c

Macro package for easy \X operations

The pdfmark.tmac macro set has been written to integrate the pdfmark PostScript operator inside groff. It can be used with any other macro set like ms, mm, me, etc. and there is also a spdf.tmac macro set to provide bindings between ms and pdfmark.tmac. As such, if you choose to use pdfroff, and desire -ms with -mpdfmark bindings, you should invoke "pdfroff -mspdf …", rather than "pdfroff -ms -mpdfmark …" (2021-07/msg00103).

← Go back