This document is written in DocBook. The Docbook XML format offers a single-source platform for generating HTML, PDF and other outputs. The generated HTML is very minimal, much less verbose than for example the HTML generated by word processors.
There are many online resources for the DocBook syntax, for example http://www.docbook.org/tdg5/en/html/docbook.html. While these nicely describe the syntax, I had a hard time finding a concise description of a tool set for translating DocBook into HTML or PDF. The following seems to work on Linux and OS X.
This is an example document:
<?xml version="1.0" encoding="UTF-8"?> <book xmlns="http://docbook.org/ns/docbook" version="5.0"> <title>Very simple book</title> <chapter> <title>Hello</title> <para>Hello world!</para> </chapter> </book>
Most real-world documents would actually be split across files,
for example a example.xml:
<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="http://docbook.org/ns/docbook" version="5.0"
xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Very simple book</title>
<xi:include href="chapter.xml" />
</book>
.. which includes a chapter.xml using XInclude:
<?xml version="1.0" encoding="UTF-8"?> <chapter xmlns="http://docbook.org/ns/docbook" version="5.0"> <title>Hello</title> <para>Hello world!</para> </chapter>
XSL translations are used to convert the DocBook XML into other formats.
The necessary set of style sheets, for example the version docbook-xsl-1.76.1,
can be downloaded from http://sourceforge.net/projects/docbook/files.
In addition to the style sheets, a processing tool that can apply XSL translations
to XML documents is required. Linux and Mac OS X already include such a tool,
namely xsltproc. For Windows, you need to find such a tool.
HTML is generated by simply applying the appropriate translation:
xsltproc /path/to/docbook-xsl-1.76.1/html/docbook.xsl \
example.xml >example.html
Fundamentally, PDF is created by first translating the DocBook XML into an intermediate format like LaTeX, then using LaTeX to generate PDF. A very convenient intermediate format is XSL-FO because the free, open source Apache Java FOP tool can perform the transformation to FO and render the result as PDF.
After downloading and installing Apache FOP, use a command like this:
fop -xsl /path/to/docbook-xsl-1.76.1/html/docbook.xsl \
-xml example.xml -pdf example.pdf
Both xsltproc and fop support processing options
that influence the generated output:
Set to the name of a Cascading Style Sheet. Only applies to HTML output.
Set to 0 to disable table of contents.
Set to 0 to disable index.
Set to 0 to disable numbering of chapters.
For xsltproc, they are passed as
xsltproc --stringparam parm value ...
For fop, use fop -param parm value ...