Generating PDF versions of the KDE documentation

Installation

1. Download and unpack the modified dblatex package.
2. Modify the dblatex-install/bin/dblatex script to contain the directory in which you ran the unpack command.
3. Add dblatex-install/bin to your $PATH

4. Make sure that $KDEDIR is set correctly, and run:

   dblatex -d -b pdftex --style kdestyle -o output.pdf \
   		-P latex.output.revhistory=0  -P newtbl.use=1 \
   		-P imagedata.default.scale=pagebound \
   		-P literal.width.ignore=1 \
   		-I $KDEDIR/share/doc/HTML/en/ \
   		-X \
   		index.docbook
   

   for some doc's index.docbook file. You'll probably want to wrap this in some script. You might find testonepdf.sh and testallpdfs.sh useful.

Known Issues

Here's what I can think of off the top of my head:

• Only English output is working. If some other language works, it's down to the work of the original dblatex author, or to dumb luck. I will work on this soon, but I want to get English output ready first. Any help is welcome.
• There are various problems with rendering. If you'd like to help with fixing these issues (requires LaTeX knowledge, and perhaps XSL too), drop me a line and I'll tell you what issues I know already.
• A few docs don't work, and I don't plan to fix them at the moment because they're broken or in some ways special cases. Currently:
  • kdebase/kioslave
  • kdebase/glossary
  • kdemultimedia/artsbuilder
  • kdewebdev/quanta
  • kdewebdev/xsldbg
• I can't get kdegraphics/kolourpaint to build, and I don't know why. If you can work it out, tell me :-).

Mini-FAQ

We want to distribute this with KDE so PDF docs can be generated at compile time. That rules out Java-based apps. I had trouble getting a FOP toolchain running, and even when I did, the output wasn't great. Jade-based stuff was used previously for the KDE docs, and removed because it was too hard to distribute. db2latex was really nice, but unmaintained. That left dblatex as almost the only choice. As it turns out, I have most of the issues fixed, with help from the very co-operative maintainer.

Contact

You can contact me on the KDE doc list kde-doc-english or directly: phil at kde dot org.