Some notes about installing DocBook tools on OS X Lion.
I used to write my documents and slides almost exclusively with $\LaTeX$ and Context. Needless to say, this means tweaking default layout a lot (who said that $\LaTeX$ allows for a perfect separation between layout and content?!), so that for small-size documents I now tend to rely on Pandoc.
Lastly, I tried to use Pandoc for outputing DocBook document which I find pretty convenient for web display. It’s been almost three years now since the latest time I wrote xml files. Pandoc is already very helpful for $\LaTeX$ (with or without the
xetex backend), and I even created basic templates for writing Beamer slides in Markdown. For DocBook, I can produce a fairly decent output using xsltproc which comes with OS X. In the
Makefile for a tutorial on exploratory data analysis with R, I put something like
xsltproc --xinclude --stringparam html.stylesheet docbook-xsl.css -o eda_r.html \ http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl eda_r.xml
and it works like a charm. However, I would like to use xmlto which is built around
xsltproc but handles everything in a smoother way.
Installing the pre-requisites
We need to install
getopt (with support for
--longoptions, contrary to the default
/usr/bin/getopt that ships with OS X).
First of all, get the latest source tarball of
gettext from GNU website.
gettext 0.18.1.1, you have to run the classical
$ ./configure $ make $ make check $ sudo make install
although I had to patch
gettext-tools/gnulib-lib/stpncpy.c as follows:
#ifndef weak_alias -# define __stpncpy stpncpy +# define __stpncpy gnu_stpncpy #endif
Then, go forward with
getopt, which is available at http://software.frodo.looijaard.name/getopt/.
$ wget http://software.frodo.looijaard.name/getopt/files/getopt-1.1.4.tar.gz $ tar xzvf getopt-1.1.4.tar.gz $ cd getopt-1.1.4
Makefile, update the
LDFLAGS so it reads
LDFLAGS=-lintl (which is used for internationalization support in other packages). Then, simply run
(An alternative would be to type directly
LDFLAGS="-lintl" make -e.)
Yes, that’s a bunch of external dependencies for a small program that basically acts as a wrapper around xsltproc…
Now, we can install
xmlto. Before that, we need to install the Docbook stylesheets, as well as DocBook 4.2 files. This is well explained here and I follow those instructions. Basically, this means to:
Create a catalog file in
$ sudo mkdir /etc/xml $ sudo xmlcatalog --noout --create /etc/xml/catalog
Install the latest
/usr/local/share/docbook/(I only download 4.2 and 4.4). In my case, it is
xml/4.2 xml/4.4 xsl/1.76.1
Update the XML catalog
$ sudo xmlcatalog --noout --add 'nextCatalog' '' \ 'file:///usr/local/share/docbook/xsl/1.76.1/catalog.xml' --create /etc/xml/catalog $ sudo xmlcatalog --noout --add 'nextCatalog' '' \ 'file:///usr/local/share/docbook/xml/4.2/catalog.xml' --create /etc/xml/catalog $ sudo xmlcatalog --noout --add 'nextCatalog' '' \ 'file:///usr/local/share/docbook/xml/4.4/catalog.xml' --create /etc/xml/catalog
which results in
/etc/xml/catalog reading like this:
$ less /etc/xml/catalog <?xml version="1.0"?> <!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"> <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> <nextCatalog catalog="file:///usr/local/share/docbook/xsl/1.76.1/catalog.xml"/> <nextCatalog catalog="file:///usr/local/share/docbook/xml/4.2/catalog.xml"/> <nextCatalog catalog="file:///usr/local/share/docbook/xml/4.4/catalog.xml"/> </catalog>
Testing the installation
I used a template (article) I found and tested
xmlto by running the following command:
$ xmlto html-nochunks sample.xml
$ xsltproc --xinclude --output sample.fo \ /usr/local/share/docbook/xsl/1.76.1/fo/docbook.xsl \ sample.xml $ fop sample.fo sample.pdf
There are other tools that can be installed for those interested in managing DocBook documents, especially when PDF is the expected output format. I can think of
jade, but there are also
dbcontext, see DocBook to LaTeX Publishing. Apache fop works well too.