DocBook是一種文檔標準，用以創建結構化的純文本文檔。用DocBook創建的文檔能夠方便的在不同的操作系統之間以及不同的文本處理 工具之間進行移植，并可以通過XSLT 轉為其他的輸出格式。XSLT是EXtensible Stylesheet Language Transformation的縮寫。 由于DocBook是使用純文本編輯的，因此你可以使用任何一個文本 編輯器來編寫DocBook，并納入版本控制系統的管理。

目前，有多種不同的樣式表，能夠把DocBook文件轉換為不同的輸出格式，例如轉換為HTML，pdf，java help以及Unix man pages.

DocBook有兩種主要的文檔，一種是book，另一種是article。其中

下面就是一個DocBook文檔的例子。

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

想要創建DocBook文件并轉換成其他格式，你需要以下工具：

我們使用Eclipse 作為XML編輯器，Xalan作為XSLT解析器，并使用 Apache Ant 來進行XSLT的轉換。

你需要安裝Eclipse，可以參看這篇文章 Eclipse IDE 來學習Eclipse的安裝和使用。我們需要用到的Ant已經被集成到Eclipse里面了，因此關于Ant我們不需要安裝任何額外的東西。

你還需要下載Docbook的DTD，以及用來轉換的Docbook文檔的樣式表。Docbook的DTD可以在 http://www.oasis-open.org/docbook/xml/4.5下載， 而XSLT樣式表可以在 http://docbook.sourceforge.net/ 下載。在寫這篇文檔時，最新的版本是“1.75.2”（譯者注：在翻譯這篇文檔時，最新的版本是1.76.1）。你需要下載的docbook-xsl的發布文件， 例如“docbook-xsl-1.75.2.zip”。

要命的是JVM自帶的XSL處理器在處理XSLT樣式表的時候有問題……所以我們需要從 http://xml.apache.org/xalan-j/ 下載Xalan，用來作為我們的XSL處理器。

可以在Eclipse中，創建一個"de.vogella.docbook.first"的新工程，方法是File -> New -> Project，并從彈出的 窗口中選擇General -> Projects.

在工程中創建如下的目錄結構：

把DocBook的DTD和XSLT的樣式表放入相應的文件夾中。

在lib文件夾下創建xalan文件夾，并把xalan相關的jar包拷入這個文件夾中。 結果應該看起來是這樣的：

在“documents”文件夾里面，創建一個“book.xml”文件，并輸入下面的xml文件

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

在xml文件中，“../docbook-xml-4.5/docbook.dtd”對應于我們剛剛創建的文件夾以及放入的DTD文件。

接下來我們配置ANT。在工程目錄中，創建build.xml文件如下：

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

運行build.xml文件（右鍵 -> Run As -> Ant Build）。運行之后，在你的output文件夾里面， 應該已經有一個“book.html”了。

恭喜你完成了第一個Docbook文檔，并順利的轉成了HTML格式！

下面是一個創建表格的例子

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

生成的表格看起來是這樣的

沒有序號的列表可以這樣創建：

<itemizedlist>
<listitem>
<para>Item1</para>
</listitem>
<listitem>
<para>Item2</para>
</listitem>
<listitem>
<para>Item3</para>
</listitem>
<listitem>
<para>Item4</para>
</listitem>
</itemizedlist>

輸出結果如下：

而帶編號的列表可以這樣寫：

<orderedlist>
<listitem>
<para>This is a list entry</para>
</listitem>
<listitem>
<para>This is another list entry</para>
</listitem>
</orderedlist>

輸出結果如下：

鏈接可以用下面的方法來創建：^[a]

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

插入圖片可以使用下面的方式。

<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/antview10.gif" format="gif">
</imagedata>
</imageobject>
</mediaobject>
</para>

Docbook轉成pdf的過程是：先由docbook轉成XSL-FO格式，再利用Apache FOP把FO轉成 pdf。因此，我們首先需要Apache FOP相關的庫。

XML FO，是XML Formating Object的意思，FO格式是一種處理打印、印刷介質的XML標準。

可以從http://xmlgraphics.apache.org/fop/下載FOP的最新版本。

從下載的FOP發行版中，把所有的jar文件都拷貝到你的lib文件夾中，并把這些庫都加入到ant 的build path中。可以參考 Apach Ant Tutorial來修改ant的build path。

要在ant中使用fop，我們首先應當定義一個fop相關的ant task，然后在后面的腳本中使用這個任務。 下面的這個例子演示了怎樣定義一個ant task并怎樣調用。第二個例子是一個完整的build.xml文件的例子。

<!--
- Defines the ant task for fop
-->
<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允許在轉換成html的時候，導入并包含一個外部的html文件。你可以使用這種技術，在生成 html的時候向其中插入javascript代碼。

下面是一個包含html文件的例子。

 <?dbhtml-include href="../../myadditonalcontent.html"?>

Inserting external HTML code 有更多的描述。

XInclude技術能幫你重新組織你的docbook文件。你可以在書寫每一個章節的時候，都使用 一個單獨的xml文件，然后用一個總的xml文件把這些章節都組合起來。簡單的說，XInclude 能把不同的xml文件組合成為一個大的xml文件。

例如，假設你要引入一個“foo.xml”文件，則可以寫成：

 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="foo.xml" />

下面這個例子是要把導入的文件當做文本： ^[1]

Eclipse XSL project提供一個XInclude的ant task。在此，我很自豪的告訴各位：這個ant task是我提供給XSL project 的:)

Eclipse XSL工具提供了對XSLT的支持，包括XSL的編輯以及debug的支持。雖然我們這里僅僅使用其中的ant task， 但還是得完整的安裝整個包。

安裝XSL工具可以通過Eclipse的update manager完成。 ^[2] 你可以通過 Using the Eclipse update manager 來獲得更多信息。

在你的Eclipse安裝路徑中找到“org.eclipse.wst.xsl.core.jar”并把這個jar包加入到ANT的classpath中。 這樣，你應該就可以創建和運行xinclude tast了。下面是一個build.xml文件的例子：

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