Docbook introduction

Docbook is a specification for writing documentation in XML*. Once an XML document containing the data content of the documentation has been created, it can be processed by XSL transforms to produce an output format (pdf, html, chm and more…). This proved particularly useful for a project at work, where I generated a set of output formats from a single XML data source.

Tools, examples and resources after the jump.

Tools:

I used xsltproc to run the transforms. A windows version can be downloaded from:
http://www.zlatkovic.com/libxml.en.html

Docbook XSLT’s can be found here:
http://sourceforge.net/projects/docbook/

Apache FOP is needed to output to PDF:
http://xmlgraphics.apache.org/fop/

Example usage:
Assuming you already have an input xml file (test.xml), you can use the following commands to generate outputs:

HTML:
xsltproc --output test.html ../docbook-xsl/html/docbook.xsl test.xml

PDF:
xsltproc --output test.fo ../docbook-xsl/fo/docbook.xsl test.xml
fop.bat -fo test.fo -pdf test.pdf

CHM:
xsltproc ..\docbook-xsl\htmlhelp\htmlhelp.xsl test.xml
"C:\Program Files\HTML Help Workshop\hhc" htmlhelp.hhp

Here is a very basic example input xml file (test.xml):

<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
<book><title>Test Documentation</title>
   <bookinfo>
      <author>
      <firstname>Bill</firstname>
      <surname>Gates</surname>
      </author>
   </bookinfo>
   <chapter><title>First chapter</title>
      <para>
         First chapter content. Paragraph One.
      </para>
      <para>
         Paragraph two.
      </para>
   </chapter>
   <chapter><title>Chapter two</title>
      <para>
         Chapter two content. Paragraph One.
         <graphic fileref="test.png"></graphic>
      </para>
   </chapter>
</book>

Documentation:
Here is some documentation that I found particularly useful:

https://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/docbooksys/docbooksys.html

http://www.codeproject.com/KB/winhelp/docbook_howto.aspx

http://sagehill.net/docbookxsl/index.html

“DocBook: The Definitive Guide” – O’Reilly, v.good reference section.
http://www.docbook.org/tdg/en/html/docbook.html

* I think there is an older SGML variation of Docbook as well.