Setting up a DocBook toolchain

Exporting DocBook content requires a DocBook toolchain . The toolchain is a collection of tools that converts your XML DocBook files into documents like PDF, ePub, HTML help, Open Office and even Microsoft Word. Sometimes the XML editing software that you use includes such a toolchain and the casual DocBook author may need never to build their own toolchain. Other, prepackaged DocBook toolchains can be found at the http://wiki.DocBook.org/DocBookTools website.

When you want to do more advanced customizations with your DocBook content, such as automating document creation, testing out new stylesheets, or creating templates for use with other document creation tools, you may need to set up your own toolchain. For example the AsciiDoc project exports into the DocBook format but does not contain a DocBook toolchain.

If you already have a DocBook toolchain with your XML editing software, it may support console commands. In that case, you may have a quick way to achieve your customization needs. For example, the XML editor from xmlmind.org includes a convertdoc tool for executing commands from the command-line.

You can definitely create your own DocBook toolchain using open source software. A basic DocBook toolchain includes:

  • DocBook stylesheets that explain the rules to follow when creating the final documents, for example, these rules can say to include the document title, date, and author on the first page.

  • An XML parser software , this software applies the DocBook stylesheets to your content. This software applies the rules from the stylesheets, for example, if you are convert the same DocBook content but change the product name in each, the XML parser will be responsible for that task. If your final document is a PDF, the XML parser will create a formatting objects (FO) file. If your fional document is HTML, the XML parser will create an HTML file.

  • Print formatter software to convert Formatting object (FO) files into things like PDF, AFP, PNG and other formats.

In summary, you use the DocBook Stylesheets and an XSLT processor to convert your XML book into another text format, such as HTML. If you want to convert your XML book into a non-text format, such as a PDF, you will first convert the book to a special format calleed formatting objects (FO). Then you will use a formatting objects processor to make the transformation into a PDF file.

These instructions will summarize the steps to create your own toolchain.

Download software

You will need the following software:

Supporting software

If any of the software you are using in your toolchain require Java, be sure to have a Java Runtime installed on your computer. Java can be downloaded from http://java.com/en/download/index.jsp.

The toolchain software that you are downloading is probably compressed archives like zip. After downloading the software in the toolchain, you need a software such as 7-zip http://www.7-zip.org/ to open these archives.

Downloading the DocBook XSL Stylesheets

This is the easiest part of the toolchain to download. All of the stylesheet files that you need are in a single file to download. At the time of this writing, that file was DocBook-xsl-1.77.1.zip (6.1 MB).

After opening the archive, copy all of the files to a new folder such as c:\DocBook. You should now have a folder with the following files in it.

c:\DocBook
        DocBook-xsl-1.77.1

Downloading xsltproc

Xsltproc requires you to pick the operating system of your computer and then download a few files. For Windows binaries (binaries are ready to run software, source is software that needs a software programmer to run), download the iconv, libxml2, libxslt and zlib files. These files will have names like iconv-1.9.2.win32.zip to show which version they are.

After opening the archives, copy the xsltproc.exe from the bin directory of the libxslt folder, to the c:\DocBook folder you created. Copy the following files to the same c:\DocBook folder:

  • iconv.dll from the bin directory of the iconv folder.

  • libxml2.dll from the bin directory of the libxml2 folder

  • libexslt.dll from the bin directory of the libxslt folder

  • libxslt.dll from the bin directory of the libxslt folder

  • zlib1.dll from the bin directory of the zlib folder

You should now have a folder with the following files in it.

c:\DocBook
        DocBook-xsl-1.77.0
        iconv.dll
        libexslt.dll
        libxml2.dll
        libxslt.dll
        xsltproc.exe
        zlib1.dll

If you use your command prompt from this directory you can already test if the xsltproc software can run.

C:\DocBook>xsltproc.exe
Usage: xsltproc.exe [options] stylesheet file [file ...]
   Options:
        --version or -V: show the version of libxml and libxslt used
        --verbose or -v: show logs of what's happening
        ...

There are other processors such as Saxon, MSXML from Microsoft, and more that you can find with a Google search. The xsltproc software does not require Java and can be be downloaded for free.

Downloading Apache FOP

The Apache FOP requires you to pick the operating system of your computer and then download a single file. For Windows binaries (binaries are ready to run software, source is software that needs a software programmer to run), download the fop-1.0-bin.zip file. This is the current version at the time of this writing.

After opening the archive, copy the fop-1.0 directory, to the c:\DocBook folder you created. Your DocBook folder should contain the following files and folders.

c:\DocBook
        fop-1.0
        DocBook-xsl-1.77.1
        iconv.dll
        libexslt.dll
        libxml2.dll
        libxslt.dll
        xsltproc.exe
        zlib1.dll

Apache FOP requires a Java Runtime to be installed on your computer. You can check if you have this installed by running "java -version" from your command prompt. If you see something similar to the following output, your Java Runtime should be installed.

C:\>java -version
java version "1.6.0_27"
Java(TM) SE Runtime Environment (build 1.6.0_27-b07)
Java HotSpot(TM) 64-Bit Server VM (build 20.2-b06, mixed mode

If you do not see a java version number or see something similar to the following, you will need to install Java:

C:\>java -version
'java' is not recognized as an internal or external command, operable program or batch command.

If Java is installed, you use your command prompt from the fop-1.0 directory to test if the fop software can run.

C:\DocBook\fop-1.0>fop.bat
FOP Version 1.0
USAGE
fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-rtf|-tiff|-png|-pcl|-ps|-txt|-at [mime]|-print] <outfile>
 [OPTIONS]
  -version          print FOP version and exit
  -d                debug mode
  ...

Downloading Java

Java can be downloaded from http://java.com/en/download/index.jsp. Go to the Java website to download Java for your computer. Follow the instructions to install Java and retry the "java -version" command. If you see something similar to the following output, your Java Runtime should be installed.

C:\>java -version
java version "1.6.0_27"
Java(TM) SE Runtime Environment (build 1.6.0_27-b07)
Java HotSpot(TM) 64-Bit Server VM (build 20.2-b06, mixed mode

If you do not see a java version number check the Java help center for possible solutions. The Java help center is available at http://java.com/en/download/help/index.xml.

Testing the toolchain

Now that you have prepared your toolchain, it is time to test creating documents. Create a simple DocBook file in XML. The following text is an example of a simple DocBook file:

<?xml version="1.0" encoding="utf-8"?>
<book>
<info>
  <title>My First Book</title>
  <author>
    <personname><firstname>Jane</firstname><surname>Doe</surname></personname>
  </author>
  <copyright><year>2010</year><holder>Jane Doe</holder></copyright>
</info>
<preface>
        <title>Foreword</title>
</preface>
<chapter>
        <title>My Chapter</title>
        <section><title>First Section</title>
        <para>Important book content</para>
        <indexterm><primary>books</primary></indexterm>
</section>
</chapter>
<glossary>
<glossentry>
        <glossterm>Extensible Markup Language</glossterm>
      <acronym>XML</acronym>
      <glossdef>
       <para>Some reasonable definition here.</para>
      </glossdef>
    </glossentry>
</glossary>
<index></index>
</book>

Save this file to the DocBook directory that you created earlier. Give this file the name book.xml.

Now run xsltproc and tell it which stylesheet to use, which XML file that contains your book, and where to save the finished document. You must run xsltproc from the directory where it is located. For example:

C:\DocBook>xsltproc.exe DocBook-xsl-1.77.1\html\DocBook.xsl book.xml > book.html

Now, you should have a new HTML file in your DocBook directory called book.html. Open it up in your preferred web browser and you should see all of your content. Change some of the content in book.xml and try it again, for example, change the book title. See if you can generate other types of documents from your book.xml file, for example epub.

If you have installed and tested FOP, you can also create a PDF.

C:\DocBook>xsltproc.exe DocBook-xsl-1.77.1\fo\DocBook.xsl book.xml > book.fo
Making portrait pages on USletter paper (8.5inx11in)
C:\cd fop-1.1
C:\DocBook\fop-1.1>fop \DocBook\book.fo -pdf \DocBook\book.pdf

Now, you should have a new PDF file in your DocBook directory called book.pdf. The command for running FOP looks a little different since you run FOP inside its own directory are using ".\" to tell the software to go up one directory to where the XML file is located. There may be some warning messages generated by FOP but none of them should stop the creation of a nice, new PDF file.

Open the book.pdf in your Acrobat Reader and you should see all of your content. See if you can generate other types of documents from your book.fo file, for example rtf.

Congratulations, you now have a new DocBook toolchain. This is a good time to archive the DocBook folder that you are using.

Customizing DocBook

Now that you have seen some sample output for a document you might want to change the output. This is done by setting parameters in the DocBook stylesheets. Some examples of customizations:

  • changing the CSS stylesheet

  • change default image widths

  • use profiles when creating your document

  • add bookmarks to the PDF

  • changing the fonts used in the PDF

References

Some references that I’ve found very useful are listed here:

The tools I use

I use the following software applications to make books using AsciiDoc:

  • Text editor - any will do but Sublime Text 2 is my preferred editor. (http://www.sublimetext.com)

  • AsciiDoc - downloadable files for direct file conversion to PDF, HTML and XML DocBook. I use MacPorts to install this on Mac OS X. (http://www.methods.co.nz/asciidoc/)

  • DocBook toolchain - Apache FOP, DocBook stylesheets, xsltproc (there is a toolchain packaged with the AsciiDoc installation).

  • Custom stylesheet - for DocBook output.

  • TechSmith’s SnagiIt - for screen captures. (http://www.techsmith.com)

Some additional tools may also prove useful if your documentation needs go beyond the basic tools:

Index