Archive for the ‘Docbook’ Category


12 March 2008 Leave a comment

DocBook is a technology that helps you write documentation in an XML file and then convert this XML file into any format you like, like PDF, HTML, HTML Help and so on, as long as you have the right converter. Since I have used docbook to create documentation before I would like to share my experience and show a step by step guide on how to setup docbook and create the documentation you want. I will concentrate on creating PDF and HTML from a simple docbook XML file, on Windows platform.

To create a PDF file

  • Download the DocBook DTD from here (you need the file
  • Unzip the file somewhere on your local disk.
  • Create a sample XML file like the following:

<?xml version=”1.0″ encoding=”UTF-8″?>

<!DOCTYPE book PUBLIC “-//OASIS//DTD DocBook V3.1//EN” “C:/docbook/docbookdtds/docbookx.dtd”>



<title>A Test Book</title>











<title>A title</title>


This is a paragraph that tests the docbook Formatting Objects (FO) functionality.



And yet another paragraph. Nibble nibble little mouse who is nibbling at my house?




  • Save this file as DocBooktest.xml. Make sure that the DTD points to the right file on your computer.
  • Download the Apache Formatting Objects (FOP) from here.
  • Unzip the file onto the local disk.
  • Edit the fop.bat script and alter the following line:



set LOCAL_FOP_HOME=C:\java\fop-0.94 (this should be the location where you installed FOP)

  • If you also want to manage images in the PDf files you will have to download Jimi, extract it and add the JimiProClasses in the classpath as well.


  • Download the hyphenation package for FOP. Due to licensing issues it is available as a separate download form here. You will need the file offo-hyphenation-fop-stable if you have downloaded FOP-0.9x.
  • Unzip the file and put the fop-hyph.jar in the build/ folder of your FOP installation. On my computer this is c:\java\fop-0.94\build
  • Now issue the following command from the folder where the fop.bat file is

fop -xml c:\DocBookTest.xml -xsl c:\docbook\docbook-xsl-1.73.2\fo\docbook.xsl -pdf DocBookTest.pdf

  • Make sure that you use the right paths, they are probably different on your computer. The file docbook.xsl is the stylesheet that converts the XML to PDF.
  • When done you should have a DocBookTest.pdf file with the same content as the XML.
To create HTML file
In addition to the DTD above you will also need the xsltproc file as well as the zlib and the libxml libraries. All these libraries can be found here.
  • Download the, the and the files. Extract all of them. You will need to copy the following DLLs libxml2.dll and Zlib1.dll into the WINDOWS/System32 folder where all the DLLs are. These files can be found in the bin/ folder of the installations.
  • Now issue the following command from within the libxslt-1.1.22.win32\bin folder

xsltproc –output DocBook.html c:\docbook\docbook-xsl-1.73.2\html\docbook.xsl c:\DocBookTest.xml

(of course you will need to change the paths to reflect the location of the files on your local filesystem). This will result in a DocBook.html file.

Categories: Docbook, Java