docbook to pdf made easy

DocBook to PDF can be a bit convoluted. Here’s the recipe I settled on for my dissertation, which has produced nice enough looking output. Why DocBook over a word processor? Well, I was originally using OpenOffice but quickly got frustrated with how the formatting kept drifting slightly out of sync across the chapters. My own fault, probably, but DocBook worked well enough for me and I can turn it into a reasonable website in future.

Unfortunately the free “docbook2pdf” script I found on my PC didn’t work too well. So I went hunting for a better solution.

Step 1 – make sure the DocBook XSL stylesheets are installed. On SUSE Linux the package name is “docbook-xsl-stylesheets”, the names and paths may differ on your setup

Step 2 – make sure xsltproc is installed

Step 3 – Now go grab RenderX XEP. This is a commercial Java product but they have a free personal edition, which sticks a little logo and notice at the bottom of each page. That’s kinda sucky, but it’s very easy to use and I had no luck with the free PDF generation tools I tried. It also didn’t come out when printing for some reason. This is the simplest way.

Step 4 – Use a command line “xsltproc -o document.fo /usr/share/xml/docbook/stylesheets/nwalsh/current/fo/docbook.xsl document.xml” to generate a .fo intermediate file

Step 5 – Run XEP on that file. You should get a nice looking PDF document as the output. You can customize the docbook stylesheets using a variety of knobs to get better/worse looking output, see the guide to DocBook XSL.

One gotcha that had me stumped for a few minutes is that XEP will try and download things from the net as it works, so make sure Java knows about your HTTP proxy (-Dhttp.proxyHost=’whatever’ -Dhttp.proxyPort=8080).