Tutorial

DocBook is a standard for creating well-formated plain text documents. DocBook documents can be transformed into other output formats.

DocBook is plain text and can therefore be written in a text editor which supports plain text as output format and put under version control.

To transform Docbook into other formats you can use XLST. XSLT stands for Extensible Stylesheet Language Transformation. 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 article:

				
<?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>
	<section label="1.0">
		<title>An introduction to DocBook</title>
		<section label="1.1">
			<title>Subsection</title>
			<para> 
				This is text.
			</para>
		</section>
	</section>
</article>

			

The following is an example of a DocBook book:

				
<?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">
<book>
	<title>Docbook Book Example</title>
	<chapter>
		<title>This is the first chapter</title>
		<section>
			<title> First section in the chapter</title>
			<para>Random text.
			</para>
		</section>
		<section>
			<title> Second section in the chapter</title>
			<para>Other random text
			</para>
		</section>
	</chapter>	

	<chapter>
		<title>This is the second chapter</title>
		<section>
			<title> My Title</title>
			<para>More...
			</para>
		</section>
		<section>
			<title> Other title</title>
			<para>Blabla
			</para>
		</section>
	</chapter>
</book>
			

To create DocBook files and to convert them into other formats you need:

We will use Eclipse as an XML editor, Saxon as the XSLT parser and Apache Ant for the XSLT transformation.

Install Eclipse. See Eclipse IDE for installing and using Eclipse. We will use the Apache Ant which 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 The XSLT stylesheets can be downloaded from:

http://docbook.sourceforge.net

At of the time of writing this article the version "docbook-xsl-1.76.1" is the most recent version.

Download Saxon from http://saxon.sourceforge.net/ . Download the version 6.5.5 as newer Saxon version to not work well with DocBook 4.5. Saxon 9 is an XSLT 2.0 processor and the current official version of the XSL stylesheets are XSLT 1.0 based.

Sometimes running the XSLT conversion result in the strange error message:

				
javax.xml.transform.TransformerConfigurationException: java.net.MalformedURLException: no protocol: ../common/entities.ent
			

In this case I added the XML parser xerces-j to your build path and see if that resolves the error.

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.

Copy the Saxon jar into the lib 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>
	<section label="1.0">
		<title>An introduction to DocBook</title>
		<section label="1.1">
			<title>Subsection</title>
			<para> 
				This is text.
			</para>
		</section>
	</section>
</article>

			

Create an Apache Ant build 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="input.dir" value="input" />
	<property name="output.dir" value="output" />
	<property name="docbook.xsl.dir" value="docbook-xsl" />
	<property name="html.stylesheet" value="${docbook.xsl.dir}/html/docbook.xsl" />

	<!-- Making saxon available -->
	<path id="saxon.class.path">
		<pathelement location="lib/saxon9he.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="${output.dir}" />
	</target>

	<!--
      - target:  depends
      -->
	<target name="depends">
		<mkdir dir="${output.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="${input.dir}" destdir="${output.dir}">
			<include name="**/*book.xml" />
			<include name="**/*article.xml" />
			<param name="html.stylesheet" expression="style.css" />
			<classpath refid="saxon.class.path" />
		</xslt>
		<!-- Copy the stylesheet to the same directory as the HTML files -->
		<copy todir="${output.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>
		

DocBook has no restrictions what kind of graphic format you use, e.g. JPEG, PNG or SVG. You can include graphics via the following tag. The optional "phrase" is used in HTML output to define the mandatory "alt" attribute of image.

			
<para>
	<mediaobject>
		<imageobject>
			<imagedata fileref="images/antview10.gif"/>
		</imageobject>
		<textobject>
			<phrase>A text for the graphic</phrase>
		</textobject>
	</mediaobject>
</para>
		

You can also specify different graphics for different output formats.

			
<para>
	<mediaobject>
		<imageobject role="html">
			<imagedata fileref="images/antview10.gif" />
			
		</imageobject>
		<imageobject role="fo">
			<imagedata fileref="images/antview10.gif" />
			
		</imageobject>
		<textobject>
			<phrase>A text for the graphic</phrase>
		</textobject>
	</mediaobject>
</para>
		

To show nice menu paths, as for example File → New Project, use the folloiwng

					
<menuchoice>
	<guimenu>File</guimenu>
	<guisubmenu>New Project</guisubmenu>
</menuchoice>
		

To define keyboard as for example C-x+C-c, use the folloiwng

					
<keycombo>
		<keycap>CTRL</keycap>
		<keycap>Space</keycap>
</keycombo>
		

Epub is a format for electronic book defined by the International Digital Publishing Forum (IDPF). EPUB is based on XHTML and supports styling via CSS. A EPUB file is a zip file with a predefined content. The zip file must contain a folder "META-INF" which contains a file "container.xml". This file contains a pointer to the OEBPS/content.opf file. The content.opf contains the meta information about the book and pointers to the content pages which are defined as HTML pages.

The Docbook XLST stylesheets support a conversion into EPUB. This conversion is based on the XHTML stylesheets and therefore support the same parameter as in HTML. The final epub document requries also an additonal file mimetype with a predefined content and the content of OEBPS and META-INF. The XSLT transformation will not automatically create the mimetype file and the zip file we will use Apache Ant to create them for us.

To validate an epub you can use the jar file from Epubcheck Validation tool. Download the latest 1.x version and put it into the classpath of your Ant file. Make sure that you also extract the lib folder included in the zip file relative to the epub*.jar. After the conversion you can validate your epub via the following command line. We will include the check also in our Ant task.

				
java -jar epubcheck-1.2.jar book.epub
			

The following example is based on the same file and directory structure as the other examples. Create the following "book.xml" file in your "input" directory.

				
<?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">
<book>
	<title>Docbook Book Example</title>
	
	<bookinfo>
		<title>DocBook Intro</title>
		<author>
			<firstname>Lars</firstname>
			<surname>Vogel</surname>
		</author>
	</bookinfo>
	
	<chapter>
		<title>This is the first chapter</title>
		<section>
			<title> First section in the chapter</title>
			<para>Random text.
			</para>
			<para>
			<mediaobject>
				<imageobject>
					<imagedata fileref="images/vogella_current_logo.png"/>
				</imageobject>
				<textobject>
				<phrase>
				</phrase>
			</textobject>
			</mediaobject>
		</para>
		</section>
		<section>
			<title> Second section in the chapter</title>
			<para>Other random text
			</para>
		</section>
		
	</chapter>

	<chapter>
		<title>This is the second chapter</title>
		<section>
			<title> My Title</title>
			<para>More...
			</para>
		</section>
		<section>
			<title> Other title</title>
			<para>Blabla
			</para>
		</section>
	</chapter>
</book>
			

This book refers to a image ""vogella_current_logo.png" in the image folder. Either create such an image or delete the part.

Create also an folder "epubinput" with a file "mimetype". This file should have the following content. "application/epub+zip" need to be the only content in the file and it needs to be in the first line of the file.

				
application/epub+zip
			

The following Ant "build.xml" file will create epub output.

				
<?xml version="1.0"?>
<!--
  - Author:  Lars Vogel
  -->

<project name="docbook-src" default="build-epub">
	<description>
            This Ant file is used to transform DocBook XML to epub output
    </description>

	<!--
      - Configure basic properties that will be used in the file.
      -->

	<property name="input.dir" value="input" />
	<property name="output.dir" value="output" />
	<property name="docbook.xsl.dir" value="docbook-xsl-1.76.1" />

	<property name="epub.stylesheet" value="${docbook.xsl.dir}/epub/docbook.xsl" />

	<property name="{destfilename}" value="book" />

	<!-- Making saxon available -->
	<path id="saxon.class.path">
		<pathelement location="lib/saxon.jar" />
	</path>

	<property name="epubcheck.jar" value="lib/epubcheck/epubcheck-1.2.jar" />
	<!--
      - 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}" />
		<mkdir dir="${output.dir}/tmp" />
		<copy todir="${output.dir}/tmp">
			<fileset dir="epubinput">
				<include name="mimetype" />
			</fileset>
		</copy>
		<copy todir="${output.dir}/tmp/OEBPS/images">
			<fileset dir="images">
				<include name="vogella_current_logo.png" />
			</fileset>
		</copy>
	</target>

	<!--
      - target:  build-html
      - description:  Iterates through a directory and transforms
      -     .xml files into .html files using the DocBook XSL.
      -->

	<!--
	   - target:  build-epub
	   - description:  Iterates through a directory and transforms
	   -     .xml files into .epub files using the DocBook XSL.
	 -->
	<target name="build-epub" depends="clean, depends" description="Generates EPUB files from DocBook XML">

		<xslt style="${epub.stylesheet}" extension=".html" 
			basedir="${input.dir}" destdir="${output.dir}/tmp">
			<include name="**/*book.xml" />
			<param name="epub.stylesheet" expression="style.css" />
			<!-- The following parameter do not work currently
			
			<param name="epub.metainf.dir" expression="${output.dir}/META-INF/" />
			<param name="epub.oebps.dir" expression="${output.dir}/OEBPS/" />
			-->
			<classpath refid="saxon.class.path" />
		</xslt>

		<copy todir="${output.dir}/tmp/OEBPS">
			<fileset dir="OEBPS">
			</fileset>
		</copy>

		<copy todir="${output.dir}/tmp/META-INF">
			<fileset dir="META-INF">
			</fileset>
		</copy>

		<!-- Don't know how to avoid genereation of "${destfilename}.html" by Saxon -->
		<delete file="${output.dir}/tmp/book.html" />

		<echo message="Generating book.epub" level="info" />

		<!-- We create temporary zips so that minetype is the first one in the final zip  -->

		<zip destfile="${output.dir}/temp.mimetype" basedir="${output.dir}/tmp" compress="false" includes="mimetype" />
		<zip destfile="${output.dir}/temp.zip" basedir="${output.dir}/tmp/" level="9" compress="true" excludes="mimetype" includes="OEBPS/** META-INF/**" />
		<zip destfile="${output.dir}/book.epub" update="true" keepcompression="true" encoding="UTF-8" excludes="*.html">
			<zipfileset src="${output.dir}/temp.mimetype" />
			<zipfileset src="${output.dir}/temp.zip" />
		</zip>

		<!-- Have to delete these directories would be nicer to place then in tmp output dir -->
		<delete dir="./OEBPS" />
		<delete dir="./META-INF" />

		<!-- Make sure the epubcheck lib has a subfolder lib with saxon.jar and jing.jar in it
		-->
		<epub.check epub="book" />
		
	</target>

	<!-- epub check macro definition -->
	<macrodef name="epub.check" description="Check an epub">
		<attribute name="epub" description="Name of the EPUB" />
		<sequential>
			<java jar="${epubcheck.jar}" fork="true">
				<arg value="${output.dir}/@{epub}.epub" />
			</java>
		</sequential>
	</macrodef>
</project>
			

I personally see the following issues please let me know if you have a solution for it.

You find anther example Ant file in Ant for EPUB Blog Entry from Tony Graham.

You can convert DocBook to XML-FO via the DocBook XSL Stylesheets. XML FO stands for XML Formating Objects and is a XML Standard which is optimized for print medias. XML-FO can then be tranlated into PDF via the Apache FOP library.

In addition to the existing setup you also require the Apache FOP library. Download the binary FOP distribution from 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>
			

You find all HTML relevant parameters here http://docbook.sourceforge.net/release/xsl/current/doc/html/ .

You find all FO / PDF relevant parameters here http://docbook.sourceforge.net/release/xsl/current/doc/fo/ .

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.

You can also enable syntax highlighting. This involves creating a customization stylesheet layer, the usage of an external lib and configuration file. Please see Source Code Syntax Highlighting with DocBook for a description of the setup.

To change how the highlighting is done you could adjust the following template file: your_xslt_installation_dir/html/highlight.xsl

Sometimes you want to remove certain parts of your document before processing it. The following is an example where sections marked with the role="wrapper" will be removed.

The following processing rule will remove the marked section. You would output that to a temporary folder and run your real conversion on the temp folder.

				
<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	version="1.0">

	<xsl:output method="xml" />

	<xsl:template match="section[@role='wrapper']">
		<xsl:apply-templates select="section" />
	</xsl:template>

	<xsl:template match="@*|node()">
		<xsl:copy>
			<xsl:apply-templates select="@*|node()" />
		</xsl:copy>
	</xsl:template>

</xsl:stylesheet>

		
			

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>