DocBook与Eclipse - 教程

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]

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

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>