Working with Docbook on Windows natively

Setting up a set of tools for working with Docbook on Windows often requires setting things up using Cygwin. Many people (e.g. myself) are not willing to do that, and it seems there isn’t much information outta there over the internet.

This tutorial will show you how to set up a native environment to work with Docbook, and show you how to make CHM and PDF files on Windows as well.

Step 1 – Get the tools

The tools you need to work with Docbook XML and XSTL are all available on Windows. The first thing you need to do is visit http://www.zlatkovic.com/pub/libxml/ and grab the latest versions of

  • libxml2
  • libxslt
  • iconv

Download each and unzip the contents of the folder to c:\windows or another location on your path. For reference, these files are the ones you’re looking for:

  • iconv.exe
  • libexslt.dll
  • libxml2.dll
  • libxslt.dll
  • xmlcatalog.exe
  • xmllint.exe
  • xsltproc.exe

If you feel better about putting these in their own folder, that’s fine as long as you add the new folder to your path.

Step 2 – Get the Stylesheets

In order to build a book, you need to have the XSLT stylesheets so you can transform your XML into a pretty-looking book with a table of contents and nicely formatted text.
Download the docbook-xml-ns files from sourceforge: http://sourceforge.net/project/showfiles.php?group_id=21935, it’s named docbook-xsl-ns-1.77.1 by the time I’m writing this article.

Unpack to your c:\ drive and then rename the extracted folder to c:\docbook-xsl

Step 3 – Generate PDF

In order to create a PDF, you have to first convert to the FO format and then use a Java library to convert the FO to a PDF. Apache FOP does this for you. You’ll need to have a JRE (Java Runtime) installed though. Visit http://java.sun.com/ for that.

Download FOP at http://xmlgraphics.apache.org/fop/download.html (fop-1.0-bin.zip) and unzip it to a temp location. Copy all .jar files in build/ and lib/ to your Java installation’s lib/ext folder. On my system it’s C:\Program Files\Java\jre1.5.0_11\lib\ext. Your system will differ depending on your installed version of Java.

Next, download OFFO-hyphenation from http://offo.sourceforge.net/index.html and grab the offo-hyphenation-fop-stable.zip file from the downloads page and put the jar files in the same folder as the FOP files.

Step 4 – Build your first book

Create a project folder called “my_book” and create a new file called “samplebook.xml” in this folder.

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

<book xmlns=”http://docbook.org/ns/docbook”
xmlns:xi=”http://www.w3.org/2001/XInclude” version=”5.0″>
<info>
<title>Sample Book</title>
<edition>1st edition</edition>
<pubdate><?dbtimestamp?></pubdate>
<copyright>
<year>2010-2012</year>
<holder>
<ulink url=”http://www.swfitcore.com”>YQ</ulink>
</holder>
</copyright>
<authorgroup>
<author>
<personname>
<firstname>Q.</firstname>
<surname>Yuan</surname>
<honorific>Mr</honorific>
</personname>
</author>
</authorgroup>
</info>

<part>
<title>Prefix</title>
<xi:include href=”prefix.overview.xml”/>
</part>

</book>

Then create a chapter for your book. Create the file chapter1.xml in your project folder with this content:

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

<chapter version=”5.0″ xmlns=”http://docbook.org/ns/docbook”>
<title>Organization Overview</title>
<para>Most of these servers are running with VMware Virtualization technology.</para>
</chapter>

Generating HTML from the document

The easiest way to use Docbook is to export to HTML. Execute this command to create an HTML version of your book:

xsltproc –xinclude –output samplebook.html c:/docbook/xsl/html/docbook.xsl samplebook.xml

Creating a makefile to build the PDF

The PDF creation process is similar to the HTML process but it does require two steps. You need to first convert the document to the FO file format. Then you use FOP to convert it to the PDF. We can automate this by using Ruby.

Create a Ruby file in your project folder called “make”. You’ll use this file to build the PDF of your book.

xsltproc –xinclude –output samplebook.fo c:/docbook-xsl/fo/docbook.xsl samplebook.xml
java org.apache.fop.cli.Main -fo samplebook.fo -pdf samplebook.pdf

Summary

Docbook is a really great way to create books, tutorials, and documentation in a format that can be transformed into various other formats. It’s extremly easy to work with in Windows too!

One comment on “Working with Docbook on Windows natively
  1. Mordechai says:

    Great article! simple and to the point. Can’t wait to try

Leave a Reply

Your email address will not be published. Required fields are marked *

*