Version 1.7
Copyright © 2007 - 2010 Lars Vogel
15.08.2010
| Revision History | ||
|---|---|---|
| Revision 0.1 - 0.5 | 28.06.2007 | Lars Vogel |
| Created | ||
| Revision 0.6 - 1.7 | 16.10.2008 - 15.08.2010 | Lars Vogel |
| bugfixes and updates | ||
Table of Contents
DocBook is a standard for creating well-formated plain text documents. It allows the creation of documentation that is portable between different operating systems and text processing tools. DocBook documents can easily be transformed into other output formats via XSLT . XSLT stands for Extensible Stylesheet Language Transformation. DocBook is plain text and can therefore be writen in a text editor which supports plain text as output format and put under version control.
Stylesheets for converting DocBook to common output are available, e.g. to convert into HTML, pdf, java help or Unix man pages.
DocBook has two main document class, book and article.
Article: Used for writing technical articles. The main tag is article. Article is used in the following example.
Book: Used for longer description. The main tags is book. In addition to sections which are used in an article another structuring element exists, the chapter.
The following is an example of a DocBook document:
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "../docbook-xml-4.5/docbookx.dtd"> <article> <articleinfo> <title>DocBook Intro</title> <author> <firstname>Lars</firstname> <surname>Vogel</surname> </author> </articleinfo> <sect1 label="1.0"> <title>An introduction to DocBook</title> <para> This is text. </para> </sect1> </article>
To create DocBook files and to convert them into other formats you have to use :
The DocBook DTD which defines how a DocBook must be written.
XSLT stylesheets to convert your DocBook into another format.
A XSLT parser
We will use Eclipse as an XML editor, Xalan as the XSLT parser and Apache Ant for the XSLT transformation.
You need to have the Eclipse installed. See Eclipse IDE for installing and using Eclipse. We will use Apache Ant but Ant is integrated into Eclipse therefore no additional installation is required.
Download the Docbook DTD and XSLT stylesheets. You can download the Docbook DTD from http://www.oasis-open.org/docbook/xml/4.5 and the XSLT stylesheets from http://docbook.sourceforge.net At of the time of writing this article the version "1.75.2" is the most recent version. Download the docbook-xsl distribution, e.g. "docbook-xsl-1.75.2.zip".
Unfortunately the XSL processor included into the JVM has problem with the XSLT stylesheets. Therefore download the Xalan XSL processor from http://xml.apache.org/xalan-j/ .
In Eclipse create a new project "de.vogella.docbook.first", select File -> New -> Project and select from the proposed list General -> Projects.
Create the following folder structure:
output: Contains the result of the conversion
docbook-xml-4.5: Contains the DTD definition for DocBook
docbook-xsl: Contains the XSL stylesheets to convert to the other output formats.
lib: Will contains your libraries (for pdf creation)
documents: Contains your DocBook files
Place the DocBook DTD and the XSLT stylesheets into the corresponding directories.
Create the folder "/lib/xalan" and copy the xalan jars into this folder. The result should look like the following.

In your folder "documents" create a following file "book.xml". The "../docbook-xml-4.5/docbookx.dtd" corresponds to the directory you have created earlier in your project setup.
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "../docbook-xml-4.5/docbookx.dtd"> <article> <articleinfo> <title>DocBook Intro</title> <author> <firstname>Lars</firstname> <surname>Vogel</surname> </author> </articleinfo> <sect1 label="1.0"> <title>An introduction to DocBook</title> <para> This is text. </para> </sect1> </article>
We will now create an Apache Ant . Create the following file "build.xml" in your project directory.
<?xml version="1.0"?>
<!--
- Author: Lars Vogel
-->
<project name="docbook-src" default="build-html">
<description>
This Ant buildhtml.xml file is used to transform DocBook XML to html output
</description>
<!--
- Configure basic properties that will be used in the file.
-->
<property name="docbook.xsl.dir" value="docbook-xsl" />
<property name="doc.dir" value="output" />
<property name="documents" value="documents" />
<property name="html.stylesheet" value="${docbook.xsl.dir}/html/docbook.xsl" />
<!-- Making xalan available -->
<path id="xalan.class.path">
<pathelement location="lib/xalan/serializer.jar" />
<pathelement location="lib/xalan/xalan.jar" />
<pathelement location="lib/xalan/xercesImpl.jar" />
<pathelement location="lib/xalan/xml-apis.jar" />
</path>
<!--
- target: usage
-->
<target name="usage" description="Prints the Ant build.xml usage">
<echo message="Use -projecthelp to get a list of the available targets." />
</target>
<!--
- target: clean
-->
<target name="clean" description="Cleans up generated files.">
<delete dir="${doc.dir}" />
</target>
<!--
- target: depends
-->
<target name="depends">
<mkdir dir="${doc.dir}" />
</target>
<!--
- target: build-html
- description: Iterates through a directory and transforms
- .xml files into .html files using the DocBook XSL.
-->
<target name="build-html" depends="depends" description="Generates HTML files from DocBook XML">
<xslt style="${html.stylesheet}" extension=".html" basedir="${documents}" destdir="${doc.dir}">
<include name="**/*book.xml" />
<include name="**/*article.xml" />
<param name="html.stylesheet" expression="style.css" />
<classpath refid="xalan.class.path" />
</xslt>
<!-- Copy the stylesheet to the same directory as the HTML files -->
<copy todir="${doc.dir}">
<fileset dir="lib">
<include name="style.css" />
</fileset>
</copy>
</target>
</project>
Run the build.xml file (right mouse click, run as -> Ant Build). Then check the output directory. You should find a directory "Example", with the file "book.html".
Congratulations you created your first Docbook and converted it into an HTLM document.
The following is an overview of useful Docbook tags.
Table 1. Important Docbook tags
| Tag | Explanation |
|---|---|
| <![CDATA[ SPECIAL_SIGN_HERE,e.g. & ]]> | Allows to enter special signs into the text which would be otherwise intepreted by DocBook |
| <programlisting> </programlisting> | Highlights the text as coding. |
| <emphasis> </emphasis> | Highlights the text |
| <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="example1.txt" /> | Includes example1.xml as text, so the file can contain tag, etc. |
| <ulink url="http://www.heise.de/newsticker">German IT News</ulink>. | Paste a hypertext link into the the document. |
| & | & Creates the & sign. Can for example be used in links. |
You can create an table like this:
<table frame='all'> <title>Sample Table</title> <tgroup cols='2' align='left' colsep='1' rowsep='1'> <colspec colname='c1' /> <colspec colname='c2' /> <thead> <row> <entry>a4</entry> <entry>a5</entry> </row> </thead> <tfoot> <row> <entry>f4</entry> <entry>f5</entry> </row> </tfoot> <tbody> <row> <entry>b1</entry> <entry>b2</entry> </row> <row> <entry>d1</entry> <entry>d5</entry> </row> </tbody> </tgroup> </table>
The output look then like this:
You can create non-numbered lists like this:
<itemizedlist> <listitem> <para>Item1</para> </listitem> <listitem> <para>Item2</para> </listitem> <listitem> <para>Item3</para> </listitem> <listitem> <para>Item4</para> </listitem> </itemizedlist>
The output look then like this:
This is a list entry
This is another list entry
You can create non-numbered lists like this:
<orderedlist> <listitem> <para>This is a list entry</para> </listitem> <listitem> <para>This is another list entry</para> </listitem> </orderedlist>
The output look then like this:
Item1
Item2
Item3
Item4
You can create links like this
<para> We use the Ant integrated into Eclipse. See <ulink url="http://www.vogella.de/articles/ApacheAnt/article.html"> Apache Ant Tutorial</ulink> for an introduction into Apache Ant. </para>
The source file will be translated to XSL-FO. Then Apache FOP will be used to translate this into pdf. Therefore you need the Apache FOP liberies to convert to pdf.
XML FO stands for XML Formating Objects and is a XML Standard which is optimized for print medias.
Download the binary FOP distribution http://xmlgraphics.apache.org/fop/.
Copy all the jars from the FOP distribution in your library directory and add the libs to the ant build path. See Apache Ant Tutorial on how to modify the ant build path.
You have to add the task to your ant build file and then call the task. The following show how to define the task and how to call it. The second listing is then a full example ant build.xml file.
<!--
- Defines the ant task for xinclude
-->
<taskdef name="fop" classname="org.apache.fop.tools.anttasks.Fop" />
<!-- Transformation into pdf
- Two steps
- 1.) First create the FO files
- 2.) Then transform the FO files into pdf files
-->
<!--
- target: build-pdf
- description: Iterates through a directory and transforms
- .xml files into .fo files using the DocBook XSL.
-->
<target name="build-pdf" depends="depends, xinclude"
description="Generates HTML files from DocBook XML">
<!-- Convert DocBook Files into FO -->
<xslt style="${fo.stylesheet}" extension=".fo" basedir="${src.tmp}"
destdir="${src.tmp}">
<include name="**/*book.xml" />
<include name="**/*article.xml" />
<param name="section.autolabel" expression="1" />
</xslt>
<!-- Convert FO Files into pdf -->
<fop format="application/pdf" outdir="${doc.dir}">
<fileset dir="${src.tmp}">
<include name="**/*.fo" />
</fileset>
</fop>
</target>
<?xml version="1.0"?>
<!--
- Author: Lars Vogel
-->
<project name="docbook-src" default="all">
<description>
This Ant build.xml file is used to transform DocBook XML to
various output formats
</description>
<!--
- Defines the ant task for xinclude
-->
<taskdef name="xinclude" classname="de.vogella.xinclude.XIncludeTask" />
<!--
- Defines the ant task for xinclude
-->
<taskdef name="fop" classname="org.apache.fop.tools.anttasks.Fop" />
<!--
- Configure basic properties that will be used in the file.
-->
<property name="javahelp.dir" value="${basedir}/../Documentation/output/vogella/javahelp" />
<property name="src" value="${basedir}/documentation" />
<property name="output.dir" value="${basedir}/../Documentation/output/vogella/articles" />
<property name="output.tmp" value="${basedir}/output.tmp" />
<property name="lib" value="${basedir}/lib/" />
<property name="docbook.xsl.dir" value="${basedir}/docbook-xsl-1.72.0" />
<property name="xinclude.lib.dir" value="${basedir}/lib/" />
<!--
- Usage of the differect style sheets which will be used for the transformation
-->
<property name="eclipse.stylesheet" value="${docbook.xsl.dir}/eclipse/eclipse.xsl" />
<property name="html.stylesheet" value="${docbook.xsl.dir}/html/docbook.xsl" />
<property name="fo.stylesheet" value="${docbook.xsl.dir}/fo/docbook.xsl" />
<property name="javahelp.stylesheet" value="${docbook.xsl.dir}/javahelp/javahelp.xsl" />
<property name="chunk-html.stylesheet" value="${docbook.xsl.dir}/html/chunk.xsl" />
<!--
- target: usage
-->
<target name="usage" description="Prints the Ant build.xml usage">
<echo message="Use -projecthelp to get a list of the available targets." />
</target>
<!--
- target: clean
-->
<target name="clean" description="Cleans up generated files.">
<delete dir="${output.dir}" />
</target>
<!--
- target: depends
-->
<target name="depends">
<mkdir dir="${output.dir}" />
</target>
<!--
- target: copy
- Copies the images from the subdirectories to the target folder
-->
<target name="copy">
<echo message="Copy the images" />
<copy todir="${output.dir}">
<fileset dir="${src}">
<include name="**/images/*.*" />
</fileset>
</copy>
</target>
<!--
- target: xinclude
- description: Creates one combined temporary files for the different inputs files.
- The combined file will then be processed via different ant tasks
-->
<target name="xinclude">
<xinclude in="${src}/DocBook/article.xml" out="${output.tmp}/DocBook/article.xml" />
<xinclude in="${src}/JavaConventions/article.xml" out="${output.tmp}/JavaConventions/article.xml" />
<xinclude in="${src}/JUnit/article.xml" out="${output.tmp}/JUnit/article.xml" />
<xinclude in="${src}/EclipseReview/article.xml" out="${output.tmp}/EclipseReview/article.xml" />
<xinclude in="${src}/HTML/article.xml" out="${output.tmp}/HTML/article.xml" />
<xinclude in="${src}/Eclipse/article.xml" out="${output.tmp}/Eclipse/article.xml" />
<xinclude in="${src}/Logging/article.xml" out="${output.tmp}/Logging/article.xml" />
<!--
<xinclude in="${src}/ant/article.xml" out="${src.tmp}/ant/article.xml" />
-->
</target>
<!--
- target: build-html
- description: Iterates through a directory and transforms
- .xml files into .html files using the DocBook XSL.
-->
<target name="build-html" depends="depends, xinclude" description="Generates HTML files from DocBook XML">
<xslt style="${html.stylesheet}" extension=".html" basedir="${output.tmp}" destdir="${output.dir}">
<include name="**/*book.xml" />
<include name="**/*article.xml" />
<param name="html.stylesheet" expression="styles.css" />
<param name="section.autolabel" expression="1" />
<param name="html.cleanup" expression="1" />
<outputproperty name="indent" value="yes" />
</xslt>
<!-- Copy the stylesheet to the same directory as the HTML files -->
<copy todir="${output.dir}">
<fileset dir="lib">
<include name="styles.css" />
</fileset>
</copy>
</target>
<!--
- target: build-javahelp
- description: Iterates through a directory and transforms
- .xml files into .html files using the DocBook XSL.
-->
<target name="build-javahelp" depends="depends, xinclude" description="Generates HTML files from DocBook XML">
<xslt style="${javahelp.stylesheet}" extension=".html" basedir="${output.tmp}" destdir="${javahelp.dir}">
<include name="**/*book.xml" />
<include name="**/*article.xml" />
<outputproperty name="indent" value="yes" />
</xslt>
</target>
<!--
- target: chunks-html
- description: Iterates through a directory and transforms
- .xml files into seperate .html files using the DocBook XSL.
-->
<target name="build-chunks" depends="depends, xinclude" description="Generates chunk HTML files from DocBook XML">
<xslt style="${html.stylesheet}" extension=".html" basedir="${output.tmp}" destdir="${output.dir}">
<include name="**/*book.xml" />
<include name="**/*article.xml" />
<param name="html.stylesheet" expression="styles.css" />
<param name="section.autolabel" expression="1" />
<param name="html.cleanup" expression="1" />
<param name="chunk.first.selection" expression="1" />
</xslt>
<!-- Copy the stylesheet to the same directory as the HTML files -->
<copy todir="${output.dir}">
<fileset dir="lib">
<include name="styles.css" />
</fileset>
</copy>
</target>
<!-- Transformation into pdf
- Two steps
- 1.) First create the FO files
- 2.) Then transform the FO files into pdf files
-->
<!--
- target: build-pdf
- description: Iterates through a directory and transforms
- .xml files into .fo files using the DocBook XSL.
- Relativebase is set to true to enable FOP to find the graphics which are included
- in the images directory
-->
<target name="build-pdf" depends="depends, xinclude" description="Generates HTML files from DocBook XML">
<!-- Convert DocBook Files into FO -->
<xslt style="${fo.stylesheet}" extension=".fo" basedir="${output.tmp}" destdir="${output.tmp}">
<include name="**/*book.xml" />
<include name="**/*article.xml" />
<param name="section.autolabel" expression="1" />
</xslt>
<!-- Convert FO Files into pdf -->
<fop format="application/pdf" outdir="${output.dir}" relativebase="true">
<fileset dir="${output.tmp}">
<include name="**/*.fo" />
</fileset>
</fop>
</target>
<!--
- target: chunks-html
- description: Iterates through a directory and transforms
- .xml files into seperate .html files using the DocBook XSL.
-->
<target name="build-eclipse" depends="depends, xinclude" description="Generates Eclipse help files from DocBook XML">
<xslt style="${eclipse.stylesheet}" basedir="${output.tmp}" destdir="${output.dir}">
<include name="**/*book.xml" />
<include name="**/*article.xml" />
</xslt>
</target>
<target name="all" depends="copy, build-html, build-pdf, build-chunks, build-eclipse">
</target>
</project>
The XSLT stylesheets have several parameters which can influence the result of the conversion.
Table 3. HTML Parameters
| Parameter | Description |
|---|---|
| name="section.autolabel" expression="1" | Turns on the autolabeling for sections (1. Title, 1.1. Subtitle, etc. |
| name="chapter.autolabel" expression="1" | Turns on the autolabeling for chapters |
| name="html.stylesheet" expression="styles.css" | Define the stylesheet which should be used. |
| name="html.cleanup" expression="1" | Will try to clean-up the html code for better readability |
| name="chunk.first.sections" expression="0" | Will try to clean-up the html code for better readability [TODO: Does not work yet] |
Table 4. pdf Parameters
| Parameter | Description |
|---|---|
| name="section.autolabel" expression="1" | Turns on the autolabeling for sections (1. Title, 1.1. Subtitle, etc. |
| name="chapter.autolabel" expression="1" | Turns on the autolabeling for chapters |
| name="html.stylesheet" expression="styles.css" | Define the stylesheet which should be used. |
| name="html.cleanup" expression="1" | Will try to clean-up the html code for better readability |
Docbook allows to include external html files into the HTML output. For example you could use this to add Javascript into your HTML output.
For example use the following statement to include some html code.
<?dbhtml-include href="../../myadditonalcontent.html"?>
See Inserting external HTML code for details.
XInclude can be used to structure the DocBook source files so that you have one file per chapter / section and one master file which includes these files. Via XInclude these separate files can be combined into on file.
You can for example include a file "foo.xml" into another one via the following statement
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="foo.xml" />In case this file should be treated as text:
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="bar.xml" />
A XInclude ant task is provided by the Eclipse XSL project. I can proudly say that this ant task was contributed by me to the Eclipse XLS project. :-)
Eclipse XSL Tools provide support for XSLT transformations. It supports XSL editing and debugging support. We will only use the XInclude task but you have to install the whole package.
Install the XSL tools via the update manager from the standard Eclipse Galileo update site. See Using the Eclipse update manager for details.

From your Eclipse installation take the "org.eclipse.wst.xsl.core.jar" and add this jar to your ant classpath. Put the new jar into your Ant classpath. See Apache Ant Tutorial - Classpath for details.
You should now be able to create and run the xinclude task. Belong an example ant build.xml file.
<?xml version="1.0"?>
<!--
- Author: Lars Vogel
-->
<project name="docbook-src" default="usage">
<description>
This Ant build.xml file is used to transform DocBook XML to various
output formats
</description>
<!--
- Configure basic properties that will be used in the file.
-->
<property name="doc.dir" value="${basedir}/output" />
<property name="src" value="${basedir}/src" />
<property name="src.tmp" value="${basedir}/src.tmp" />
<property name="lib" value="${basedir}/lib/" />
<property name="docbook.xsl.dir" value="${basedir}/docbook-xsl-1.72.0" />
<property name="html.stylesheet" value="${docbook.xsl.dir}/html/docbook.xsl" />
<property name="xinclude.lib.dir" value="${basedir}/lib/" />
<!--
- target: usage
-->
<target name="usage" description="Prints the Ant build.xml usage">
<echo message="Use -projecthelp to get a list of the available targets." />
</target>
<!--
- target: clean
-->
<target name="clean" description="Cleans up generated files.">
<delete dir="${doc.dir}" />
</target>
<!--
- target: depends
-->
<target name="depends">
<mkdir dir="${doc.dir}" />
</target>
<!--
- target: xinclude
- description: Creates one combined temporary files for the different inputs files.
- The combined file will then be processed via different ant tasks
-->
<target name="xinclude">
<xsl.xinclude in="${src}/DocBook/article.xml" out="${src.tmp}/DocBook/article.xml" />
</target>
<!--
- target: build-html
- description: Iterates through a directory and transforms
- .xml files into .html files using the DocBook XSL.
-->
<target name="build-html" depends="depends, xinclude" description="Generates HTML files from DocBook XML">
<xslt style="${html.stylesheet}" extension=".html" basedir="${src.tmp}" destdir="${doc.dir}">
<include name="**/*book.xml" />
<include name="**/*article.xml" />
<param name="html.stylesheet" expression="styles.css" />
</xslt>
<!-- Copy the stylesheet to the same directory as the HTML files -->
<copy todir="${doc.dir}">
<fileset dir="lib">
<include name="styles.css" />
</fileset>
</copy>
</target>
</project>
Thank you for practicing with this tutorial.
I maintain this tutorial in my private time. If you like the information please help me by using flattr or donating or by
|
Before posting questions, please see the vogella FAQ . If you have questions or find an error in this article please use the www.vogella.de Google Group . I have created a short list how to create good questions which might also help you. .
http://www.sagehill.net/docbookxsl/index.html DocBook XSL Online Book from Bob Stayton
http://sourceforge.net/projects/docbook/ The XSLT stylesheets
http://docbook.sourceforge.net/release/xsl/current/doc/ - Reference of the XSLT stylesheet parameters
http://www.docbook.org/tdg/en/html/docbook.html Reference of the DocBook parameters
http://www.eclipse.org/articles/article.php?file=Article-Authoring-With-Eclipse/index.html Article about how to use Eclipse and DocBook
http://www.ibm.com/developerworks/linux/library/l-docbk.html Introduction into DocBook
http://xmlgraphics.apache.org/fop/ The Apache FOP Distribution