Docbook Stylesheets

I'd been using openjade to process the B Tree Library API documentation from Docbook XML to HTML for the web site. I noticed that the HTML output had changed subtly when I had moved from Redhat to Debian Linux.

The minor changes were that the background on tables, and the include file line on the API descriptions, were no longer shaded.

The differences were tracked down to changes in the Docbook Stylesheet Layer file, docbook-utils.dsl, used by default in the Debian port of the Docbook DTDs et al. These elements has been defined differently in the Redhat version of the stylesheet, redhat-docbook-utils.dsl (natch).

The DSL file is written in a language called DSSSL, based on Scheme (a Lisp variant). I therefore copied the default Debian DSL file from /usr/share/sgml/docbook/utils-0.6.13/docbook-utils.dsl to my local Docbook directory and made the following changes in the HTML settings section of the DSL file:

      (define %shade-verbatim% #t)
      (define %funcsynopsis-decoration% #t)

I also requested html output be placed in a subdirectory called html, using the following setting:

      (define use-output-dir #t)   ;; output in separate directory?
      (define %output-dir% "html") ;; if output in directory, it's called HTML

To run the XML to HTML conversion process, I used the docbook2html command, which is a front-end to jade. The command is as follows (the -d argument defines the DSL file to use in preference to the default):

      docbook2html -d ~/doc/docbook-utils.dsl\#html bt.xml

The equivalent openjade command would be:

      openjade1.3 -t sgml -i html -d ~/doc/docbook-utils.dsl\#html \
          /usr/share/sgml/declaration/xml.dcl bt.xml

N.B. I've gone back to using jade, since it's about ten times faster at processing the Docbook XML than openjade.

The DSL file requested all generated HTML files to be placed in the html subdirectory. However, it will not create this directory if it does not exist, so make sure it is present before issuing the docbook2html command.

Note: A very useful introduction to Docbook can be found in Eric S. Raymond's "The Art of Unix Programming". The book is available on-line, but I recommend buying a copy (I did).