# 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

Makefile:

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$@

# Garamond
# 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" \
$<$@

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

The garamond.xml I also had to write:

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

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"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<article>
<title>My Article</title>
<author><firstname>Alex</firstname>
<surname>Schroeder</surname></author>
<sect1><title>Testing</title>
<para>This is an ordinary paragraph with some <emphasis role="bold">bold</emphasis>
and <emphasis>italic</emphasis> words.</para>
</sect1>
</article>

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

Tags:

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.

Or have a look at a Wiki-based solution, for example Confluence 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. 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.