This post is, more or less, a note to self so that I can look up how to do this later on. I use docbook to write documentation for some of my projects and I have a set of shell scripts set up to render the docs as HTML and PDF. I use Xalan as my XSLT processor. Every once in a while I find myself wanting to change some aspect of the output. E.g. changing the heading styles in the HTML output, or adjusting the number of levels of section headings that will appear in the table of contents.

Today I decided that I wanted my PDFs to be generated with those handy bookmarks in the left margin of the page so that I could more easily navigate to the various parts of the manual.

I found most of my answer here. All I had to do was enable fop extensions when running XALAN. Here is the shell script that I have patched together over time to run Xalan with all of my preferred XSLT settings:

Note that this source uses fop1.extensions 1 rather than fop.extensions 1 as recommended in aforementioned article. This is because fop.extensions activates a namespace for FOP extensions that was in use prior to version 0.9. If you are using 1.0 or higher (as I apparently am), you need to specify fop1.extensions or you’ll get a nasty exception stack trace like this:

Thanks to this thread for pointing this out.

If you’re not using Docbook to write your manuals, then you owe it to yourself to look into it. It took me a month of Sundays to get my setup just right, but it was worth it.

After this modification, I have my beautiful PDF with a bookmarked table of contents: