4.6.7 Using PDF features with ms

If you run an ms document with -Tpdf and -rPDFFEAT=1 the PDF features shown in this document will be incorporated. The PDF produced will show an overview bookmark panel, the pdf “properties” information will include the document title and author(s), any TOC included will have clickable entries which can navigate the document, and if the document has a cover page (introduced with RP) the TOC will be relocated to after the cover.

There are also two new macro calls available.

Macro: .XR name [post [pre [hotlink-text]]]

The name parameter should match a name given to a NH or SH section/subsection, See Headings in ms, or a name set by a XM command. The hotlink-text is the text which will be clickable. If the text ends with “+” or “*” (the expansion characters), the text associated with the section heading will replace the character (enclosed with double quotes if the final character is “+”). If no hotlink-text is given, the value of \*[spdf:txt_default] is used. Which is initially set to “see: +”. (Note the expansion character). But you can change it.

Macro: .XM name [text]

Mark a particular position in the document with a name. Any text given will be used to replace a trailing expansion character in an XR command which references the name. It is useful if you wish to name an arbitrary location in the document, so you can setup a link to a picture, diagram or even a single paragraph.

Using XR for a “forward” link (where the destination is “later” in the document), will not work properly if the link uses expansion characters and groff only sees a single pass of the document. So either use the full text, without a trailing expansion character in the forward link, or use the multi-pass command

pdfmom --roff -ms -rPDFFEAT=1 file.ms > file.pdf

The command can be shortened to pdfms -rPDFFEAT=1 ... if you have created a link to the pdfmom command called pdfms.

Running an ms document with nroff, is only a single pass, so the above advice about not using expansion characters with forward links also applies.

All of the PDF features mentioned in this document can be disabled if the groff command includes -rPDFFEAT=0.