vogella.de

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.

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 :

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:

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.

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:

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:

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>
		

You can include graphics via the following tag

			
<para>
	<mediaobject>
		<imageobject>
			<imagedata fileref="images/antview10.gif" format="gif">
			</imagedata>
		</imageobject>
	</mediaobject>
</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>
			

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" />
			

				
<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>