Home > Docbook, Java > DocBook

DocBook

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 docbook-xml-4.5.zip)
  • 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”>

<book>

<bookinfo>

<title>A Test Book</title>

<author>

<firstname>Panos</firstname>

<surname>Konstantinidis</surname>

</author>

<copyright>

<year>2008</year>

<holder>pkons</holder>

</copyright>

</bookinfo>

<chapter>

<title>A title</title>

<para>

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

</para>

<para>

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

</para>

</chapter>

</book>

  • 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=

to

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.

set LOCALCLASSPATH=%LOCALCLASSPATH%;C:\java\Jimi\JimiProClasses.zip)

  • 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 libxml2-2.6.30+.win32.zip, the libxslt-1.1.22.win32.zip and the zlib-1.2.3.win32.zip 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.

Advertisements
Categories: Docbook, Java
  1. No comments yet.
  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: