Recipe: DocBook PDF Conversion

Recently I had to create a PDF version of a DocBook document. "Easy, I naively thought", and used the already installed docbook2pdf command:

docbook2pdf file.dbk

docbook2pdf is one in a suite of conversion programs which you get on Debian via

apt-get install docbook-utils

The problem with the result: It is ugly as hell.

Throwing a Key into its Lock

The font is far too small, the space between paragraphs and other blocks too big, no table of contents, ...

"Easy, I naively thought" assuming that I could control all this via some parameters. And indeed the manual page of jw promises such:

jw ....
     [ -V variable[=value] ]
     ....

As the documentation in

/usr/share/doc/docbook-utils/html/...

is very, very silent about any specific DocBook parameters, I had to scratch them out of

/usr/share/sgml/docbook/stylesheet/dsssl/modular/print/dbparam.dsl

But all my attempts to pass in something which took effect were in vain:

docbook2pdf -V bf-size=11pt ...
docbook2pdf -V bf.size=11pt ...
docbook2pdf -V %bf-size%=11pt ...
...

"Not easy, I thought." I cursed the programmer, and gave up on throwing a key into its lock.

Brute Force

After a while I discovered that the whole process is controlled via the DSSSL file:

/usr/share/docbook-utils/docbook-utils.dsl

I cloned a local copy and modified that:

cp /usr/share/docbook-utils/docbook-utils.dsl my.dsl
vi my.dsl

Things I added to the PRINT section (you will find it):

(define %bf-size%  11pt)
(define %para-sep%  (/ %bf-size%  4.0))
(define %block-sep% (* %para-sep% 1.0))

What remained is to name that DSSSL file in the invocation:

docbook2pdf --dsl my.dsl#print file.dbk

Table of Contents

Simply setting

(define %generate-article-toc%      "1")

was not enough (I have a DocBook article, not a book). I also had to add a <toc/> empty element to the DocBook. And according to the grammar it must follow all sections.

Strangely, the table of contents appears at the beginning. But in my case that was wanted anyway.

Parting Advice

In a weak moment I fell for the theory (never hope for anything!) that the parameters were the same as those for xsltproc, as listed in

/usr/share/doc/docbook-xsl/doc/param.html

They look so strikingly similar. But that is exactly what the devil wanted to fool us. I almost could hear him sneeringly laughing when I tried:

(define %draft-mode% yes)
(define %draft-watermark-image% file:draft.png)


And all the useless things these hands have done.
-- Leonard Cohen

DSSSL - DocBook PDF Conversion

Thanks for discovering (albeit unintentionally) another DSSSL stylesheet. Unfortunate that DSSSL never attracted the support that has gone into re-inventing some of its capabilities for XML.

Patrick Durusau (not verified) | Sun, 09/06/2009 - 14:09