2010-06-27 Docbook Mess

I was looking for an alternative to LaTeX. I recently learned how to setup DocBook. There’s a book explaining what DocBook is and how to use it; the old version of the book is available online. I also followed the instructions in the DocBook XSL book on how to install FOP, so in theory I had the entire tool chain to write an XML file, translate it to FO format using xsltproc and translating that to PDF format using fop.

It looked very ugly. I felt like going back to LaTeX – and that’s pretty ugly, too!

I found that by default, FO processors only know about Times Roman, Helvetica, and Courier by default. So I decided to try and get the article font switched to Garamond before continuing my delve into Docbook. I got followed the instructions on adding a font and wasted some time tracking down jar files that were not needed and tracking down a copy of the Garamond font I could embed. In the end I got it all working! I had an ugly document, but it was A4, two columns, had some bold, and some italic, and my name on it.

But I also felt that maybe – just maybe – LaTeX and OpenOffice were not such a bad ideas after all.

Maybe I should just stick to OpenOffice and focus on getting things done.

Technical Details


all: test.pdf

%.fo: %.xml Makefile
	xsltproc \
	--output $@ \
	--stringparam fop1.extensions 1 \
	--stringparam paper.type A4 \
	--stringparam column.count.body 2 \
	--stringparam body.font.family Garamond \
	/usr/local/share/xml/docbook-xsl/fo/docbook.xsl \

%.pdf: %.fo
	fop -c garamond.xml -fo $< -pdf $@

1. Garamond
1. curl http://garamond.org/font/urw/GaramondNo8.Files.txt | xargs wget

fonts: GaramondNo8-Ita.xml GaramondNo8-MedIta.xml GaramondNo8-Med.xml GaramondNo8-Reg.xml

GaramondNo8-%.xml: GaramondNo8-%.ttf
	java -cp "/usr/local/share/xml/fop/build/fop.jar:/usr/local/share/xml/fop/lib/commons-io-1.3.1.jar:/usr/local/share/xml/fop/lib/commons-logging-1.0.4.jar:/usr/local/share/xml/fop/lib/xmlgraphics-commons-1.3.1.jar" \
	org.apache.fop.fonts.apps.TTFReader \
	$< $@

/usr/local/share/xml/fop is a symlink to fop-0.95.

The garamond.xml I also had to write:

<fop version="1.0">
    <renderer mime="application/pdf">
	<font metrics-url="GaramondNo8-Ita.xml" kerning="yes" embed-url="GaramondNo8-Ita.ttf">
	  <font-triplet name="Garamond" style="italic" weight="normal"/>
	<font metrics-url="GaramondNo8-Med.xml" kerning="yes" embed-url="GaramondNo8-Med.ttf">
	  <font-triplet name="Garamond" style="normal" weight="bold"/>
	<font metrics-url="GaramondNo8-MedIta.xml" kerning="yes" embed-url="GaramondNo8-MedIta.ttf">
	  <font-triplet name="Garamond" style="italic" weight="bold"/>
	<font metrics-url="GaramondNo8-Reg.xml" kerning="yes" embed-url="GaramondNo8-Reg.ttf">
	  <font-triplet name="Garamond" style="normal" weight="normal"/>

I also got fop-hyph.jar from OFFO and I got jai_codec.jar and jai_core.jar from the Java Advanced Imaging Downloads. I copied all three into /usr/local/share/xml/fop/lib.

Uhm... That’s it, I think.

My test file:

<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  <title>My Article</title>
<para>This is an ordinary paragraph with some <emphasis role="bold">bold</emphasis>
and <emphasis>italic</emphasis> words.</para>

Oh, and this required the installation of the DocBook 4.5 XSL files and an entry in my catalog file. I got it from here: http://www.oasis-open.org/docbook/xml/4.5/ and followed my own instructions on how to update the catalog file.

All of this seems mighty complicated compared to just starting OpenOffice and writing a document or two. Sure, I don’t like working with it. But I don’t like working with all these arcane files and formats either. I can already see myself trying to get a title page or a little table just right in a three page document. It’ll never be worth my time. I’d be a gazillion times faster using Emacs and plain text! :)



Check out docutils and rst2pdf. And yes, as soon as images are in the mix, you may want to consider something with a UI.

Harald Wagener 2010-06-27 07:19 UTC

Rst is definitely a good idea for 90% of articles. Also, if you want to publish it online, check out Sphinx.

RadomirDopieralski 2010-06-27 12:54 UTC

Or have a look at a Wiki-based solution, for example Confluence+Scroll Wiki Exporter.

– Stefan Kleineikenscheidt 2010-06-28 15:54 UTC

Thanks for all the suggestions. I guess I just need to start producing a few small PDF documents for me to evaluate the various solutions.

AlexSchroeder 2010-06-28 23:45 UTC

Please make sure you contribute only your own work, or work licensed under the GNU Free Documentation License. Note: in order to facilitate peer review and fight vandalism, we will store your IP number for a number of days. See Privacy for more information. See Info for text formatting rules. You can edit the comment page if you need to fix typos. You can subscribe to new comments by email without leaving a comment.

To save this page you must answer this question:

Please say HELLO.