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).
