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:
-
The latest DocBook XSL stylesheets at http://docbook.sourceforge.net/release/xsl/current/.
-
An XSLT processor such as xsltproc. Xsltproc is available for Windows in the libxslt-1.1.26.win32.zip download from http://www.xmlsoft.org/downloads.html.
-
Alternatively, you can use Saxon http://saxon.sourceforge.net/ or Xalan http://xml.apache.org/xalan-j/. These two alternatives require a Java Runtime to use.
-
-
A Formatting Objects processor such as Apache FOP from http://xmlgraphics.apache.org/fop/download.html. This requires a Java Runtime to use.
-
There are commercial alternatives to this such as the XMLmind XSL-FO Convertor http://www.xmlmind.com/foconverter/, RederX XEP http://www.renderx.com/tools/xep.html, Antenna House http://www.antennahouse.com/product.htm.
-
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:
-
DocBook 5: The Definitive Guide http://www.DocBook.org/tdg5/en/html/
-
DocBook XSL: The Complete Guide http://www.sagehill.net/DocBookxsl/
-
DocBook FAQ http://www.dpawson.co.uk/DocBook/
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:
-
XMLMind’s XML Editor - build output from the command line, they include some nice tools, and you can validate or customize the DocBook format directly. (http://www.xmlmind.com/xmleditor/)
-
Render X’s XEP - for additional PDF output options if needed such as creating sidebars from DocBook. (http://www.renderx.com/tools/xep.html)
-
Adobe Acrobat Professional - if any special PDF features were absolutely needed.
-
AntConc - for verifying writing guidelines and maintain common word usage. (http://www.antlab.sci.waseda.ac.jp/software.html)