Groff PDF featuresDeri Jamesderi@chuzzlewit.myzen.co.ukJuly 2026
1. IntroductionThis is an attempt to draw together information gleaned from pdf.tmac, gropdf(1), and the various fullservice macros which manage pdf features.Previously groff contained pdfmark.tmac and spdf.tmac (to integrate pdf features into the ms macros).Since these have now been dropped from groff and are now supported by Keith Marshall at hisgroff-pdfmark site.PDF features can either be controlled at a low level, using the macros defined in pdf.tmac or rely on thesemacros being integrated into a full-service macro package. Currently this is the state of play with regard tofull-service:- Link MacroMetadataBookmarkInternalExternalNamedDestination mom man2 ms me mm The macros outlined below cannot be mix’n’matched between full service macro sets, but the informationgiven for pdf.tmac can be used in any document, particularly if a full macro set is missing a particular fa-cility.2. Meta Data2.1. Document InfoA PDF document can contain meta data such as “Created Date”, “Author”, “Title”, etc..2.1.1. pdf.tmacpdf.tmacTo enter pdf meta data use:.pdfinfo /<label> "text"Where /<label> can be:-/Title, /Author, /Subject, /KeywordsAnd text can be multi-line if you use:-\*[PDFLB] where you want the line-break.These entries are stored in the pdf and can be seen if you run the command:-pdfinfo filenameOr are probably visible if you look at “Document Properties” in your favourite pdf viewer. 1 In a man page collection the MR macro can be used to link to other entries in the collection, otherwise it is an external link.
2July 20262.1.2. mommomIn mom you can use:-.DOCTITLE textor more usually.PDF_TITLE textThe text given to:-.AUTHOR textWill be added to the pdf meta data.2.1.3. msms.TL and .AU Provide the Title and Author for the pdf.2.2. Annotation NotesThese are the clickable/hoverable icons which appear in the document which can contain pop-up commentson the text. Only the pdf.tmac macros provide access to this facility.2.2.1. pdf.tmacpdf.tmac.pdfnote [ -T title ] textThe popup note in the left margin was created with:-.pdfnote -T "Deri James" Just an exampleThe colour of the icon is set by setting the register PDFNOTE.COLOUR (or PDFNOTE.COLOR) to three num-bers each in the range 0.0 ⇒ 1.0 representing red, green, blue values, so:-.ds PDFNOTE.COLOUR 1.0 1.0 0.0Produces a yellow icon. The opacity of the icon is controlled by:-.ds PDFNOTE.OPACITY 0.0 ⇒ 1.0Where the default value is 0.6.Again you can use \*[PDFLB] in the text.
Groff PDF features33. BookmarksFor PDFs, bookmarks are the entries in the outline panel. Each bookmark has a hierarchical level, and, op-tionally, can be “named” so that they can be linked to from elsewhere in the documentBookmarks in the panel can be open or closed, setting:-.ds PDFOUTLINE.FOLDLEVEL 1will “close” all bookmarks below the first level. The default is to open all bookmarks.3.1. pdf.tmacpdf.tmacpdf.tmac defines this macro for bookmarks:-.pdfbookmark [-T name] level descriptive text ...Where “level” is the mandatory nesting level for this “bookmark”. All the “descriptive text” form the entryin the outline panel. If the -T flag is given this becomes a “named destination” which can be linked to fromelsewhere in the document3.2. mommommom uses the .HEADING macro to populate the outline panel:-.HEADING level [NAMED name] descriptive text ...“level”, “name” and “descriptive text” have the same meanings as above.3.3. msmsThere are two separate ways of providing outline bookmarks in ms. First there is the traditional heading:-.NH level [name3]This is then followed by input which is used as “descriptive text”.Although there could be several lines of input text, it is the accumulated output line which is used as “de-scriptive text”.So this input:.NH 1 usingUsing.BI groffwith the.BI msMacro Package.XSUsing.BI groffwith the.BI msMacro Package.XEWould create a named (“using”) level 1 bookmark “Using groff with the ms Macro Package”, and also create
4July 20262 If the “level” is “S” (a Berkeley extension) you cannot have a “named” bookmark.
Groff PDF features5a TOC entry. Note if the input text results in multiple output lines it is only the first output line which is usedas the bookmark text.The second method, which combined the “heading” with populating a TOC, is the .XN command which mustimmediately follow the .NH command:-.XN descriptive textPreviously the .NH and following heading text had to be followed with .XS/.XE commands with the sametext to separately populate the TOC.So the equivalent code to the above using .XN is:-.NH 1 using.XN Using \fIgroff\fP with the \fIms\fP Macro PackageIn both cases the bookmark is named “using”, and clicking on the overview panel or the hotspot link in theTOC will jump to the correct part of the document. You can also use the to jump to the section named “us-ing”:-.XR using ). (to enter this hotlink “(see: Using groff with the ms Macro Package)”.3.4. manmanThe.TH identifier sectionmacro creates (via first call to .PT) a named heading with name id of “identifier(section)”. It is normallygiven a level 1 bookmark, which can be controlled by setting “an*bookmark-base-level” on the commandline to increase the level, this can be used in man page collections where the pages are split into separate sec-tions.The .SH and .SS macros create unnamed bookmarks at the appropriate level.4. Named DestinationIn order to insert hotspot links which jump to other parts of the document, the destination must be “named”.In the section on it showed how they can be “named”.If you want to jump to a place in the document which has not got a bookmark, you can name any particularplace in the document, for example, a table or a figure to which you may want to refer. See information be-low.4.1. pdf.tmacpdf.tmacThis macro will plant a named destination without inserting a bookmark..pdfhref M [-N name] [-E] [descriptive text]If no name is specified, the first word of “descriptive text” is used as the “name”, which means that if the -Nflag is not used then there must be at least one word in the text.The “descriptive text”, if any, is saved as the “value” of the destination, and can be used when specifying ahotspot linkIf the -E flag is used, the text is output to the document as well.
6July 20264.2. mommomThe mom macro:-.PDF_TARGET name [descriptive text]You can now use name as the destination of any hotspot link4.3. msmsThe ms macro.XM name [descriptive text]Marks a position in the document to which .XR can place a hotspot link5. Internal Hotspot LinksAn internal link is to a “named destination” within the document, are links using a URI.A hotspot link is a clickable piece of text which will cause the viewer to jump to a The colour of the hotspotis controlled by setting the register PDFHREF.COLOUR (or PDFHREF.COLOR) to three numbers each in therange 0.0 ⇒ 1.0 representing red, green, blue values, so:-.ds PDFHREF.COLOUR 0.00 0.35 0.60Uses a turquoise text, which can be referenced as\m[\*[PDFHREF.TEXT.COLOUR]].Hotspots can have a border drawn around them, which is controlled by setting the register PDFHREF.BORDERto an array of 3 numbers which represent – horizontal corner radius, vertical corner radius, and border width.A zero radius gives square (not rounded) corners. The default is:-.ds PDFHREF.BORDER 0 0 0Which produces no border around the hotspot.5.1. pdf.tmacpdf.tmacTo plant a hotspot link:-.pdfhref L [-D name] [-P prefix-text] [-A affixed-text] [--] [hotlink text]The target for the link is given by name which should be a destination you have namedThe prefix-text and affixed-text are placed around the hotlink text.If you used a descriptive text when naming a destination, you can retrieve the value with this code:-.pdf:lookup name.ie !’\*[pdf:lookup-result]’’ \. ds desc-txt \*[pdf:lookup-value].el \. ds desc-txt UnknownThis technique is used by some of the full service macros to provide the “expando” characters “*” and “+”.When they are the final character in “hotlink text” the expando is replaced by desc-text, surrounded by dou-ble quotes if the expando character is “+”.
Groff PDF features75.2. mommommom uses this macro:-.PDF_LINK name [PREFIX text] [SUFFIX text] hotlink textIf the hotlink text is terminated with an it is replaced by the value of the descriptive text when the targetname was created.5.3. msmsAn addition to the ms macro set is the .XR command, originally found in some versions of Keith Marshall’sspdf.tmac, our version now uses.XR name [ post [ pre [hotlink text] ] ]If hotlink text is missing, the contents of \*[spdf:txt_default] is used instead. This defaults to“see: +” so, with the use of the terminating expando, the code.XR intro ), (would add a link if the first section of this document was:-.NH 1 intro.XN Introduction5.4. manmanThe.MR name sectionmacro normally creates an external link suitable for linking to another man page, but if the other man page itis calling is part of the same man page collection, it creates an internal link within the document.6. External Hotspot LinksExternal links are often links to resources on the internet such as website URLs.6.1. pdf.tmacpdf.tmacThe macro to link to internet resources is:-.pdfhref W [-D URI] [-P prefix-text] [-A affixed-text] [--] [hotlink text]If a URI is not specified the hotlink text must be a valid URI itself, and the complete URI will be visible inthe document. If a URI is given by specifying -D URI then only the hotlink text will be visible, but clickingit will launch the URI.The -P and -A flags operate in the same way as in .pdfhref L
8July 20266.2. mommomExternal links are supported by:-.PDF_WWW_LINK URI [PREFIX text] [SUFFIX text] hotlink textIf no hotlink text is given, the URI is used as the hotlink text. can be used as the last character of hotlinktext and will insert the URI.6.3. manmanThe macro.MR name sectionGenerates an appropriate external URI such as:-man:/groff(1)except if the link is to another man page in the same collection.7. Table of ContentsSome full service macro sets offer macros for building a Table of Contents, with PDF features these TOCshave clickable entries.7.1. pdf.tmacpdf.tmacpdf.tmac has no specific macros to build Table of Contents, but it does have two macros which can insert aTOC into the appropriate position in the document:-.pdfpagename nameThis assigns a name to the current page being rendered which can then be used in the second macro:-.pdfswitchtopage [when] nameWhere name is a previously named page, and the optional when can be “before” or “after”, default is “be-fore”. Alternatively the positions “top” and “bottom” can be used instead of a named page. This macroshould be used before a new page is started.7.2. mommomThe macro.AUTO_RELOCATE_TOC(must come before .START) will position the TOC appropriately in the document.Pease see the mom documentation for details of TOC generation, by default the TOC entries are clickable.
Groff PDF features97.3. msmsThe traditional way of populating a TOC was to use the .XS/.XA/.XE macros.Groff 1.23.0 introduced the .XN macro which combined producing headings with adding a TOC entry.In either case the entry will be clickable.If the document has an .RP entry, so a title page is produced, the TOC will be repositioned after the TitlePage.8. Slideshow PresentationsThe groff pdf driver understands how to create pdfs to be used for slideshow presentations. An alternative isto use the postscript driver and gpresent which is downloadable because the original website is having diffi-culty downloading files larger than 32kb.groff documents written to work with present.tmac may work with -Tpdf with minor alteration (and noneed to run presentps and ps2pdf).8.1. pdf.tmacpdf.tmacThere are just two macros which control the slide presentation:-.pdftransition feature mode duration dimension motion direction scale boolThese parameters are explained in the gropdf(1) man page, many of them are not required!There are two “events” which trigger a transition: when a slide is first drawn ( feature = SLIDE) and when anew element is added to the slide ( feature = BLOCK). Both can have a different transition mode, such as"Split | Blinds | Box | Wipe | Dissolve | Glitter | R" all of which are explained (andsome more!) in the man page.Whenever you want the presentation to pause (because you have added a new element to the slide) use themacro:-.pdfpauseand the new element will appear using the current transition set for BLOCK.8.2. mommommom has full integration with pdf presentation mode, the documentation is here.In addition the mom example documents include slide-demo.mom and its resultant pdf, so should be in-cluded in the examples/mom directory in the groff documentation.
10July 20268.3. msmsAn example of using ms to create a slideshow is here. 9. Boxes and PDF paper colourPDF viewers usually show contents on a white background, the actual background in the PDF is really trans-parent (so it appears white), however it is possible to specify a colour for the page background.In addition it is possible to specify framed coloured boxes on the page to contain the running contents. Theseboxes will flow onto following pages.9.1. pdf.tmacpdf.tmacThe relevent macros are:-.pdfbackground cmd left top right bottom weight.pdfbackground off.pdfbackground footnote bottomwhich produce a background rectangle on the page. The meanings of the parameters are explained in thegropdf(1) man page.9.2. msmsIf you include the macro file -msboxes in the groff command, you will have access to these macros:-.BOXSTART SHADED colour OUTLINED colour INDENT size WEIGHT sizebegins a box, where the argument after SHADED gives the fill colour and that after OUTLINED the bordercolour. Omit the former to get a borderless filled box and the latter for a border with no fill. The specifiedWEIGHT (line thickness) is used if the box is OUTLINED.INDENT precedes a value that leaves a gap between the border and the contents inside the box.Each colour must be a defined groff colour name, and each size a valid groff numeric expression. The key-word/value pairs can be specified in any order.Boxes can be stacked, so you can start a box within another box; usually the later boxes would be smallerthan the containing box, but this is not enforced. When using BOXSTART, the left position is the current in-dent minus the INDENT in the command, and the right position is the left position (calculated above) plus thecurrent line length and twice the indent.BOXSTOPtakes no parameters. It closes the most recently started box at the current vertical position after adding itsINDENT spacing.
Groff PDF features119.3. mommommom has comprehensive control of boxes see the mom documentation. 10. For macro developersIf you want to add PDF features to your own macro packages here is some information which may be help-ful.10.1. Stop/Start hotlink.pdfmarksuspend/.pdfmarkresumeIf there is a piece of “hotlink text” which appears right at the bottom of the page and continues across to thestart of the next page these macros can stop/restart the hotlink. Typically they appear at the start of a pagefooter macro (to prevent the footer text becoming part of the hotlink), and at the end of a page header macro(to restart the hotlinking from the previous page).10.2. Forward ReferencesSince groff is a single pass interpreter when it finds an it cannot plant a link if it has not “seen”the to whichit links, and the link will appear as Unknown resisting all mouse clicks - the same happens if the destinationof the link is mis-typed and does not exist. The forward link problem can be solved: instead of:-groff -Tpdf ...use:-pdfmom --roff ...The command was originally developed for satisfying forward references in mom files (hence the name), butwith the --roff flag it drops its reliance on mom and you can place any macro package on the command line.10.3. Marking HotlinksThe.pdfhref commandgeneral purpose macro, supports these commands:-O(Outline) This is the command which calls.M(Mark) Setup aL(Local) Mark anW(WWW URI) Form anThese “low-level” calls all expect “descriptive text” or “hotlink text” to be passed as part of the macro call.Sometimes this is not convenient, consider the man macro pair .MT/.ME where.MT jh@\:axis\:.seJ\[o ad]rgen H\[a ad]gg.METhe mail-to URI is on the .MT line, but the text to use for a hotlink is everything up to the following .ME.The .pdfhref macro allows an -S flag, not documented above, which just turns on hotlinking text. It isthen up to the macro author to arrange for it to be turned off at the appropriate point. In this example itshould be “turned off” in the .ME macro.The code to turn off the “hotlinking” and restore the text colour to what it was before the “hotlinking” startedis:-\X’pdf: markend’\m[\*[pdf:curcol]]
12July 2026
Groff PDF featuresiTable of ContentsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Meta Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Document Info . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1pdf.tmac ............................. 1mom .............................. 2ms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Annotation Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . 2pdf.tmac ............................. 2Bookmarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3pdf.tmac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3mom ............................... 3ms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3man ...............................5Named Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . 5pdf.tmac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5mom ............................... 6ms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Internal Hotspot Links . . . . . . . . . . . . . . . . . . . . . . . . . . 6pdf.tmac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6mom ............................... 7ms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7man ...............................7External Hotspot Links . . . . . . . . . . . . . . . . . . . . . . . . . . 7pdf.tmac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7mom ............................... 8man ...............................8Table of Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8pdf.tmac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8mom ............................... 8ms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Slideshow Presentations . . . . . . . . . . . . . . . . . . . . . . . . . . 9pdf.tmac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9mom ............................... 9ms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Boxes and PDF paper colour . . . . . . . . . . . . . . . . . . . . . . . . 10pdf.tmac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10ms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10mom ...............................11For macro developers . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Stop/Start hotlink . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Forward References . . . . . . . . . . . . . . . . . . . . . . . . . . 11Marking Hotlinks . . . . . . . . . . . . . . . . . . . . . . . . . . . 11