在 Eclipse 中构建 DocBook XML

使用 DocBook XML 创建 PDF、HTML 和帮助文件

DocBook XML 是一个标准 XML 标记库,可用于编写生成几乎所有输出的样式表。但是,由于 DocBook 已经存在有一段时间了,因此许多样式表已经可用于生成各种类型的文档。通过本文了解如何结合使用 DocBook XML 和 Eclipse IDE,创建可以轻松地以大多数格式分发的可重用技术文档。

Nathan A. Good, 作家兼软件工程师, Alliance of Computer Professionals

Nathan A. Good 居住在明尼苏达州的双子城。在不编写软件时,他喜欢组装 PC 和服务器、阅读和撰写技术文章,鼓励他的所有朋友转用开源软件。如果他不呆在电脑旁(他自己承认,这种情况并不多见),他会与家人共渡、前往教堂或去看电影。



2007 年 8 月 06 日

入门

本文将演示如何结合使用 DocBook XML 和 Eclipse 集成开发环境 (IDE),创建以多种格式轻松分发的可重用技术文档。DocBook XML 是标准 XML 标记库,使用它可以编写用于生成几乎所有输出的样式表。但是,由于 DocBook 已经存在近 10 年,因此已经编写了许多样式表来生成许多类型的文档,包括 HTML、文本、PDF 和手册。

读完本文后,您应当能够使用 DocBook XML 创建可生成为 HTML 格式的文档,并可用于 Eclipse 帮助插件及来自单个 XML 源文件的 PDF。您应当具备一定的 XML 使用知识,还应当能够使用 Eclipse 和 Apache Ant,包括从 Eclipse IDE 运行 Ant 构建文件。您需要使用 Eclipse V3.2 或更高版本、DocBook XML V4.x 文档类型定义(Document Type Definition,DTD)、DocBook XSL 样式表、Apache Xalan-Java™ 和(可选)Apache FOP(要获得下载,请参阅 参考资料)。

DocBook XML 概览

DocBook XML 是适于编写文档的 XML 标记库。DocBook 中的众多可用标记使它成为构建技术 文档的最佳选择。由于 DocBook 是 XML,因此可以使用样式表将其转换为多种不同的输出格式,而样式表使 DocBook XML 成为一次性编写技术文档并以各种格式生成技术文档的最佳选择。

:本文中的这些代码都是使用 DocBook XML V4.5 开发的;在撰写本文时,V5.0 正处于预发布状态。


高级元素

表 1 显示的元素常用作 DocBook XML 文件的高级元素。

表 1. 顶级 DocBook XML 元素
元素说明
book包含许多其他元素;惟一的高级元素是 <set>
chapter书的一部分
article一篇文章,也可包含在书中

内容元素

在较高级元素内,可能需要添加实际内容 —— 段落、表、列表、代码样例等。表 2 列出了向书、章节或文章中添加内容时所使用的一些常见元素。

表 2. 元素
元素说明
caution包含敬告读者操作可能导致数据丢失、硬件损坏或软件问题的文本
code包含内联代码,例如 this
example包含带有标题的代码示例
important包含可能对读者十分重要的文本
itemizedlist具有可选的要点句(bullet point)的条目列表
note包含提请读者特别注意的文本
orderedlist编号条目列表;您不必在构建时为列表编号 —— 样式表将为您执行该操作
para文本段落或文本块
table文本表或数据表
tip包含用于为读者提供建议的文本
title与元素相关的标题

下面显示的示例文档中,其中的书至少包含了表 2 中列出的每个元素的其中一个。

清单 1. 基本 DocBook XML 示例
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book>
    <title>My Example Book</title>
    <titleabbrev>Example</titleabbrev>
    <bookinfo>
        <author>
            <personname>
                <firstname>Nathan</firstname>
                <surname>Good</surname>
            </personname>
        </author>
    </bookinfo>
    <preface id="preface1">
        <title>Required Preface</title>
        <para>You will like my book (I think).</para>
    </preface>
    <chapter id="chapter1">
        <title>Your First Chapter</title>
        <para>You must include at least one chapter in your book.</para>
        <para>Here is another paragraph.</para>
        <important>
            <para>This is some really important text.</para>
        </important>
        <tip>
            <para>Look both ways before crossing the street!</para>
        </tip>
        <caution>
            <para>
                Liberal use of <code>new</code> in loops can cause performance issues!
            </para>
        </caution>
        <example>
            <title>Example 1</title>
            <programlisting>
String something = "Something";
            </programlisting>        
        </example>
    </chapter>
</book>

当文件生成为 HTML 并呈现到浏览器中后,它将类似图 1:

图 1. 转换成 HTML 并在浏览器中呈现后的清单 1 代码
经过转换和呈现的清单 1

完全介绍每个可用的 DocBook XML 标记最好留给参考手册来完成;指向这些参考手册的 HTML 版本的链接可在 参考资料 中获得。同样可以找到有关 DocBook XML 的书籍。表 2 中列出的标记将给您提供一个良好的开端,但是更多标记可用于屏幕快照、命令提示符、用户输入、商标和引号等。


设置环境

您必须使用工具来执行可扩展样式表转换语言(Extensible Stylesheet Transformation Language,XSLT)转换,以及使用 XSL 样式表把 DocBook XML 转换为 HTML 或 PDF 等您认为更有用的格式。如果您构建了自己私有的 XML,则还必须编写您自己的样式表。但是,使用 DocBook XML 等已建立的格式将允许您使用其他人已经编写的样式表。要使用预编写的样式表,请下载这些样式表(请参阅 参考资料)。在撰写本文时,适用于 DocBook XML V4.5 的一组样式表是 DocBook XSL V1.72.0。

获得样式表

包含 DocBook XSL(例如,docbook-xsl-1.72.0.zip)的已下载的归档文件包括按照生成的输出类型组织到不同目录中的样式表。html 目录包括输出 HTML 的样式表;fo 目录包括生成格式化对象(Formatting Object,FO)格式文件的样式表,等等。

下载归档文件并将其保存到便于记忆的位置。不需要把文件从归档文件中解压缩出来 —— 您可以直接把它们导入 Eclipse。

使用 Xalan

在本文中,我使用 Xalan 作为 XSLT 处理器。在将 Xalan 与 Eclipse 附带的 Ant 版本结合使用时会有一个问题:版本太低并且在尝试处理 XSL 时会遇到问题。

Xalan 是可用作两个子项目 Xalan C++ 和 Xalan-Java 的 Apache 项目。下载 Xalan-Java(如果计算机上还没有)。下载完文件后,请将其保存到便于记忆的位置。像包含样式表的归档文件一样,仍然不要解压缩文件的内容。


创建 Eclipse 项目

到目前为止,您已经看到了一些样例文件,并且应当已经下载了最新版本的 DocBook XSL 样式表,以及最新版本的 Xalan(如果以前没有的话)。您还应当已经下载了 DocBook XML 模式文件。归档文件(例如,docbook-xsl-1.72.0.zip、xalan-j_2_7_0_bin-2jars.zip 和 docbook-xml-4.5.zip)应当被保存到便于查找的位置。

下载并保存了所有归档文件后,您已经准备好启动 Eclipse 以创建新项目,并编辑把 DocBook XML 转换为不同格式的 DocBook XML 和 Ant 脚本。

在 Eclipse 启动后,通过选择 File > New > Project 创建新项目。在 General 下,单击常见的 Project,然后单击 Next。在键入项目的名称之后,单击 Finish,在工作区中创建新项目。


从归档中导入文件

既然已经在 Eclipse 中创建了新项目,那么接下来导入构建 DocBook XML 要使用的文件。

导入 DTD 文件

首先,导入 DocBook XML DTD 文件。选择 File > Import,如下所示,然后,在 General 类别中,选择 Archive File。当 Import Wizard 显示时,单击 Browse 以打开可用于定位 DocBook XML DTD 归档文件(例如 docbook-xml-4.5.zip)的文件浏览器。

图 2. 从归档文件导入
从归档文件导入

Into folder 框中的项目名称后键入 /docbook-xml。确保选中 / 文件夹,如下所示。单击 Select All(如果尚未选中或者如果已灰显),则在完成时单击 Finish。归档内的文件将被插入到项目中。

图 3. 选择要导入的文件
选择要导入的文件

导入 XSL 样式表

导入完 DocBook XML DTD 文件后,请遵循相同的过程导入 docbook-xsl-1.72.0.zip 文件的内容。但是,这一次您无需在 Into folder 框中的项目名称后指定文件夹名称,因为归档的内容将已经被放入项目内名为 docbook-xsl-1.72.0 的文件夹中。

既然已经导入了 XSL 样式表,接下来从在 Xalan Web 站点中下载的归档中导入所需的 Java Archive (JAR) 文件。导入其他归档文件时遵循同样的过程,但是这一次,请确保清空 docs、licenses 和 samples 目录,以便这些目录不被导入到项目中。在您清空了那些目录后,在 Into folder 框中添加 /lib,修改项目名称。

在导入需要的所有文件后,请在项目内创建另一个文件夹并将其命名为 src。这将是所有 DocBook XML 文件的基本文件夹。

到目前为止,应当在 Eclipse 中有一个包括以下文件夹的项目:

  • docbook-xml,包含 DocBook XML DTD
  • docbook-xsl-1.72.0,包含 DocBook XSL 样式表
  • lib,包含 Xalan JAR 文件
  • src,现在为空

如果项目中有了所有这些文件夹,那么您已经准备好添加 Ant build.xml 文件以运行转换过程。

编写 Ant 脚本

Ant 是基于 Java 的构建工具,它将读取 XML 脚本并且可以执行脚本中定义的很多任务。如果您不熟悉 Ant,请参阅 参考资料。在本文中,您将使用 Eclipse 来启动 Ant,因此无需熟悉如何从命令行运行 Ant。此外,您也无需担心自己如何下载和安装 Ant,因为 Eclipse IDE V3.2.x 附带了 Ant。它是比当前可获得的版本低的版本 —— V1.65,相对于 V1.7 —— 但是出于本文的目的,该版本不会造成问题。

不过,Ant V1.6.5 附带的 Xalan 版本在尝试使用最新的 DocBook XSL 时看上去运行得不太好。但是如果下载和使用最新版本的 Xalan(及附带的 Xerces 版本),它应当可以正常运行。


结合使用 Xalan 与 Ant

有很多种方法可以告诉 Ant 使用特定版本的 Xalan —— 或任何其他 XSLT 处理器 —— 而不使用 Ant 附带的默认版本。其中一种方法是修改 Ant 的类路径。当您在 Eclipse IDE 内使用 Ant 时,这是十分简单的。选择 Window > Preferences 以更改 Ant/CLASSPATH 下的设置。您可以在 CLASSPATH 选项卡中删除对 Xalan 或 Xerces 的任何引用,并将其替换为已经下载的版本。

如果您是惟一要执行转换的人,则这个方法很好,因为只有您必须更改 Ant 设置才能正确进行转换。但是,如果要与团队协作,更好的方法是在目录(例如,lib)中包含 Xalan 和 Xerces JAR 文件以及项目,并修改 build.xml 文件以使用 xslt 任务的库。使用这种方法,您可以简单地将文件从源文件控件中签出或者分发并运行项目,而不更改 Eclipse IDE 设置。

下面的 Ant 构建脚本中提供了为 xslt 任务提供 JAR 文件的示例。

清单 2. 样例 Ant 脚本
<?xml version="1.0"?>
<!--
  - Author:  Nathan A. Good <mail@nathanagood.com>
  -->
<project name="docbook-src" default="usage">
    
    <description>
            This Ant build.xml file is used to transform DocBook XML to various
    </description>

    <!--
      - Configure basic properties that will be used in the file.
      -->
    <property name="docbook.xsl.dir" value="docbook-xsl-1.72.0" />
    <property name="doc.dir" value="doc" />
    <property name="html.stylesheet" value="${docbook.xsl.dir}/html/docbook.xsl" />
    <property name="xalan.lib.dir" value="lib/xalan-j_2_7_0" />

    <!--
      - Sets up the classpath for the Xalan and Xerces implementations
      - that are to be used in this script, since the versions that ship
      - with Ant may be out of date.
      -->
    <path id="xalan.classpath">
        <fileset dir="${xalan.lib.dir}" id="xalan.fileset">
            <include name="xalan.jar" />
            <include name="xercesImpl.jar" />
        </fileset>
    </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="src" destdir="${doc.dir}">
            <classpath refid="xalan.classpath" />
        </xslt>
    </target>
    
</project>

粗体显示的 <property> 标记使您可以指定 Xalan JAR 文件的位置。<path> 元素用于定义在整个 Ant 脚本中可以重用的路径。您还可以使用 classpath 属性或在 classpath 元素内指定路径而不是使用 refid 属性来引用路径,把 Xalan XSLT 处理器的路径指定给 xslt 目标。

xslt 目标是与 basedirextensiondestdir 属性结合设计,用于递归浏览文件夹并为在目录中找到的每个 XML 文件生成 HTML 文件。输出将被存储到一个文件夹中,稍后将用作后面演示的 Eclipse 插件附带的帮助文件的 HTML 源文件。


创建 build.xml 文件

通过选择 File > New >File 创建 build.xml 文件。键入 build.xml 作为文件名,然后选择项目作为文件的位置。单击 Finish 创建 Ant 文件。

您可以把 清单 2 中所示的内容放入到新的构建文件中。如果选用的任何目录名称与在这里使用的目录名称不同,则可能需要调整 property 元素中的一些值以确保正常运行。

您可以直接从 Eclipse 执行 build.xml 文件,因为 Eclipse 配有内置挂钩 (hook),可以运行 Ant 构建脚本。使用 Ant 有很多其他优点:首先,它是跨平台的,这意味着您可以在运行 Java 代码的任何操作系统上执行相同的构建脚本。另一个优点是可以不依赖于 IDE 运行这个构建脚本。因而,您可以轻松地将其整合到自动执行的构建过程中,也可以从命令行执行它。最初,我打算研究如何设定 Eclipse 属性以将 XSLT 处理器作为外部工具运行(参见 Run > External Tools),但是我为了获得这些优点而放弃了那个想法。


运行 build-html 目标

在编写了 build.xml 文件之后,您可以运行 build-html 目标。您没有任何 DocBook XML 文件,因此目标将不会做任何有用的操作。但是,运行脚本时不应当会得到任何错误。

运行 Ant 目标的最简单方法之一是在编辑器中打开构建文件的情况下从 Outline 视图运行 Ant 目标。在 Outline 视图内,右击 build-html 目标的名称,然后选择 Run As > Ant Build。来自 Ant 构建脚本的消息(如果有)将显示在 Console 视图中。


编写 DocBook XML 文件

在 Eclipse 项目中,应当有 DocBook XML DTD 文件、DocBook XSL 文件、Xalan 库,而且现在还有 build.xml 文件。此时,您拥有了开始构建 DocBook XML 文件所需的一切内容。

创建第一个 DocBook XML 文件

要在 Eclipse 中创建第一个 DocBook XML 文件,请执行以下步骤:

  1. 选择 File > New > Other
  2. XML 类别中,选择 XML,然后单击 Next
  3. Create XML File 窗口中,选择 Create XML file from a DTD file,然后单击 Next
  4. File name 框中键入 chapter1.xml,然后确保项目内的 src 文件夹已被选中,然后单击 Next
  5. Select DTD File 中,浏览到项目的 docbook-xml 文件夹中的 docbookx.dtd 文件,然后单击 Next
  6. 当 Select Root Element 窗口显示时,请从 Root element 中选择 chapter,然后取消选中 Create first choice of required choice 复选框。
  7. 键入 -//OASIS//DTD DocBook XML V4.5//EN,然后单击 Finish

在 XML 编辑器中使用 chapter1.xml

Eclipse 将在 XML 编辑器中打开 chapter1.xml。Eclipse 中的 XML 编辑器有两个文件视图:Design 和 Source。XML 文件的 Design 视图将以网格的形式显示文件的元素,其中,元素名称显示在左侧列中,元素的内容显示在右侧列中。您可以通过右键单击文件并选择 Add ChildAdd AfterAdd Before 把新元素添加到文件中。

如果使用的是 DTD,则上下文菜单中的菜单项将限定您只能添加有效的元素。此功能使您可以确保在稍后执行转换时 XML 文件中不会有大量验证错误。


构建模块化文档

创建许多文档时,文档之间一定会有类似之处,尤其是在它们全都面向相同读者的情况下,例如大型企业或一群人。例如,如果您读过很多技术书籍,您就可能已经注意到几乎每本技术书籍都有 “本书中使用的约定” 部分或用于演示书中如何设定线索、提示、内嵌代码和代码清单格式的章节。

分割 DocBook XML 文件

使用 DocBook XML 使您能够将文档分割为多个文件,这些文件可以编译成一个单元并能够重用。例如,您可以将书中的每一个章节放入单独的 XML 文档中。然后可以在其他书中使用这些章节,或者简单地将章节分割为独立的文件以实现更轻松地维护。您还可以将这些章节包括到书并使用样式表处理它们。

清单 3 提供了构建动态包含其他 DocBook XML 文件的 DocBook XML 文档的示例。在转换过程中处理此文件时,该文件看上去 —— 这里是指 chapter1.xml —— 就是 &chap1; 所在的位置。

清单 3. 包含 chapter1.xml 的样例 book.xml 文件
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
    "../docbook-xml/docbookx.dtd" [
    <!ENTITY chap1 SYSTEM "chapter1.xml">
    ]>
<book>
    &chap1;
</book>

采取这种方法时有几点注意事项。首先,必须修改 chapter1.xml 文件以删除 XML 预处理指令和 DOCTYPE 元素。由于 chapter1.xml 的内容将被放到 &chap1 实体所在的位置,因此 book.xml 文件的中间将包含 XML 处理指令和 DOCTYPE 元素,会使该文件无效。

其次,如果不再需要将单独的章节文件处理成单独的 HTML 文件,则应当更新 Ant 构建脚本以避免对章节文件进行处理。幸运的是,使用 Ant 中的 xslt 任务,这项更改非常简单。xslt 任务可以包含与 Ant 中的 fileset 元素相同的元素,这意味着您可以构建一系列可以非常轻松地包含和清除文件。清单 4 显示了如何使用 <exclude> 元素包括必要的添加内容以在处理时跳过某些文件。

清单 4. 使用 XSLT 任务包含和清除文件
<target name="build-html" depends="depends" 
    description="Generates HTML files from DocBook XML">
    <xslt style="${html.stylesheet}" extension=".html" 
        basedir="${source.dir}" destdir="${doc.dir}">
        <classpath refid="xalan.classpath" />
        <include name="**/*.xml" />
        <exclude name="chapter1.xml" />

    </xslt>
</target>

如果仍需要构建全部文档,可以删除上面所示的 exclude 元素。

不仅限于分割章节和书。只要是对您有意义,就可以以任何方法物理分割 DocBook XML 文件,例如将各部分单独保存在文件中。您甚至可以把书包含在 set 元素中,该元素是最高级别的 DocBook 元素。

构建帮助插件

Eclipse 框架功能强大的特性之一是可扩展性。当我看到企业使用特殊的 “企业允许的” 方法连接至数据库、事务处理或错误处理时,我总是想知道企业为什么让开发人员到工作环境外部去查找并获取文档。为什么不构建可在公司内部网中获得的相同 HTML 文档并以能够通过 IDE、索引和搜索轻松地访问到的帮助形式将其分发给开发人员?

您可以使用 Eclipse IDE 附带的模板快速创建包含 HTML 文件格式的帮助的插件项目。下几个部分将演示如何构建这个插件项目。构建插件项目后,您可以包括在 DocBook XML 项目中构建的 HTML 文件。


创建帮助插件

要创建帮助插件,请执行以下步骤:

  1. 选择 File > New > Project 以启动 New Project Wizard。
  2. 从可用向导列表的 Plug-in Development 类别中,选择 Plug-in Project,然后单击 Next
  3. Project name 框中,键入 MyHelpPlugin,然后单击 Next
  4. 在如图 4 所示的窗口中单击 Next
    图 4. New Plug-in Project
    New Plug-in Project
  5. Available Templates 列表中,选择 Plug-in with sample help content,然后单击 Next
  6. 在下一个窗口中,单击 Finish。系统可能提示您切换到 Plug-in Development 透视图。如果提示,建议单击 Yes,因为透视图将自动包括在构建帮助时对您有用的视图。

新项目包含名为 html 的文件夹,并且在该文件夹中包含一些样例 HTML 文件。将用 DocBook 项目中生成的 HTML 文件替换这些文件。

查看进度

在尚未进行任何更改的情况下,选择 Run > Run As > Eclipse Application,将插件与 Eclipse 的实例结合运行以查看到目前为止帮助的内容。使用您的插件,Eclipse 的新实例将启动。在 Eclipse 启动后,选择 Help > Help Contents 以查看运行中的插件。如果没有做任何更改,则将看到 Test TOC 列于内容之中,如图 5 所示:

图 5. 内容样例表
内容样例表

整合 DocBook XML 项目中的 HTML

现在您已经看到了新帮助插件的默认内容,接下来该整合先前构建的 DocBook XML 项目中的 HTML 了。因此需要复制新帮助插件项目的 HTML 输出,但是您不希望每次都手动执行该操作。如果进行手动操作,则在构建插件的过程中很可能犯下错误或忘记执行该操作。

添加 Ant 文件

自动复制 HTML 文件的第一步是构建一个简单的 Ant 文件。这个 Ant 文件只将来自 DocBook XML 项目的 HTML 文件复制到插件项目的 html 文件夹中。然后,只要 Eclipse 构建项目,就会执行该 Ant 文件。

Ant 文件的内容如下所示。文件只有一个目标 —— prepare —— 它也是构建文件的默认目标。由于此构建文件实际上只适于被 Eclipse 调用,因此我把默认目标保留为 prepare

清单 5. 插件项目中的 Ant 构建文件
<?xml version="1.0"?>
<project name="MyHelpPlugin" default="prepare">
    <description>
        Prepares the Help plug-in project by copying the HTML help files
        from the DocBook XML project into this one.
    </description>
    
    <property name="docbook.project.dir" value="../myProject" />
    <property name="html.dir" value="html" />
    <property name="html.src.dir" value="${docbook.project.dir}/doc" />
    
    <fileset id="html-files" dir="${html.src.dir}">
        <include name="**/*.html" />
        <include name="**/*.css" />
    </fileset>
    
    <target name="prepare">
        <copy todir="${html.dir}">
            <fileset refid="html-files" />
        </copy>
    </target>
</project>

定义构建器

在 Eclipse 中,您可以定义在 Eclipse 构建项目时运行的程序。这些程序被称为构建器。您可以通过单击项目名称,然后选择 Project > Properties 来修改构建器。在 Builders 下方,您将看到已经为项目设置的构建器:Java Builder、Plug-in Manifest Builder 和 Extension Point Schema Builder。要让 Eclipse 运行 Ant 脚本把 HTML 文件复制到插件项目中,请执行以下步骤:

  1. Builders 属性页面中单击 New
  2. 从列表中选择 Ant Build,然后单击 OK
  3. 键入新构建器的名称,例如 Ant Builder
  4. Buildfile 下,单击 Browser Workspace 定位工作区内的 Ant 文件。
  5. 单击 Targets 选项卡,并确保 After a "Clean"Manual Build 目标显示 <default target selected>
  6. 单击 OK 保存构建器。
  7. 在 Builders 页面中,选择刚创建的新 Ant 构建器,然后单击 Up,直至您的构建器在列表中位于第一位。您必须这样做,因为需要把文件复制到插件项目中,然后才能执行其他操作。

设置了新构建器后,您可以选择 Project > CleanProject > Build 清除或构建项目。Ant 构建器将运行并自动从 DocBook XML 项目中拖出 HTML 文件。

添加构建器也适于 DocBook XML 项目。您可以将 Ant 构建器添加到 DocBook XML 项目中,把任意一个目标设为清除或构建项目时执行的目标(记住,对于这些目标,usage 目标是默认值)。


帮助 TOC 文件

HTML 帮助文件的目录 (TOC) 表位于插件项目包括的两个 XML 文件中。文件如下所示:

清单 6. TestTOC.xml
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Test TOC">
    <link toc="toc.xml" />
</toc>

清单 6 中所示的 testTOC.xml 文件包含显示在帮助窗口的 Contents 窗格中的标题名称。它只是用于链接到 toc.xml 文件。

清单 7. Toc.xml
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Sample Table of Contents">
    <topic label="Main Topic" href="html/book.html"> 
    </topic>
</toc>

toc.xml 文件包含显示在主标题下方的主要标题。这些主要标题都是用 href 属性链接到 HTML 页面,在清单 7 中用粗体显示:

您可以将帮助作为一个整体文件来构建,像书一样,并且只有一个指向该文件的主要标题。但是,请考虑把文档分割为可以在 toc.xml 文件中通过索引找到的独立章节,而且根据需要构建为单独的书。有关如何把文档分割为可以组织的各种物理文件的提示,请参阅 “Building modular documentation”。


自定义 DocBook 输出

到目前为止,DocBook XML 已经转换为在 Eclipse 插件内用作帮助的常规 HTML。但是如果需要整理转换后输出的 HTML 的外观该怎么办?

幸运的是,您不必只为了向 HTML 添加一点个性化或自定义格式而编写自己的 XSL 样式表。相反,您可以将变量传递给 XSLT 转换步骤以指定使您可以优化 HTML 格式的层叠样式表(Cascading Style Sheet,CSS)。


指定 CSS 样式表

把 DocBook XML 转换为 HTML 的 XSL 样式表将检查名为 html.stylesheet 的变量。如果变量包含值,则将在 HTML 的 link 元素中使用该值链接到您指定的样式表。

清单 8 显示了具有 importantcaution 类的简单 CSS。该 CSS 修改了这些类中文本的颜色。您将看到在显示页面时,这些类分别对应 <important><caution> 标记中的内容。

清单 8. 简单的 CSS 文件
body { font-family : arial,sans-serif; font-size : small; }
.important { color : blue; }
.caution { color : red; }

修改 Ant 构建文件

将清单 8 中所示的 CSS 保存到 DocBook XML 项目的 lib 目录中名为 style.css 的文件中。保存完文件后,必须修改 Ant 构建文件把 CSS 文件的名称传递到 xslt 目标中,然后将 CSS 文件从 lib 文件夹复制到与其余 HTML 输出相同的文件夹中。清单 9 用粗体显示了这些更改。

清单 9. 经过修改后的 Ant 脚本
<target name="build-html" depends="depends" 
    description="Generates HTML files from DocBook XML">
    <xslt style="${html.stylesheet}" extension=".html" 
        basedir="${source.dir}" destdir="${doc.dir}">
        <classpath refid="xalan.classpath" />
        <include name="**/*.xml" />
        <exclude name="chapter1.xml" />
        <param name="html.stylesheet" expression="style.css" />
    </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>

在做出更改后,您可以重新运行 DocBook XML 项目中的 Ant 构建脚本。这一次,当您查看输出的 HTML 文件时,您将看到更改后的字体和 “Important” 和 “Caution” 部分的新字体颜色。


创建 PDF

至此,您已经使用了各种工具从 DocBook XML 生成可以分布到内部网站和包含在 Eclipse 帮助插件中的 HTML。但是,我在前面提到过,使用相同的 DocBook XML 源文件,还可以生成 PDF。从 DocBook XML 生成 PDF 要求使用一个额外的工具:来自 Apache XML Graphics Project 的 FOP 库(请参阅 参考资料)。

FOP 库中有一个可以直接放入 DocBook XML 项目现有 Ant 构建文件中的 Ant 任务。该 Ant 任务 fop 将转换 FO 文件,这些 FO 文件都是使用 DocBook XSL 附带的 FO 样式表构建的。


使用 FOP 库生成 PDF

要使用 FOP 库,请从 Web 站点中下载包含二进制版本的 ZIP 文件(例如,fop-0.93-bin-jdk1.4.zip)。虽然该 ZIP 文件的名称好像指示它是专门为 Java 2 Platform, Standard Edition (J2SE), Development Kit (JDK) V1.4 构建的,但是它可以与 Java V5 很好地结合使用。像已下载的其他归档文件一样,您仍无需解压缩此文件。

在 Eclipse 中,选择 File > Import,然后执行在 “从归档导入文件” 中使用的相同过程。但是,这一次,只选择 build 和 lib 文件夹执行导入。

导入完文件后,修改 Ant 构建脚本以设置 fop 目标并在新的 build-pdf 目标中调用它,如下所示:

清单 10. build-pdf 目标
<!--
    - target:  build-pdf
    - description:  Iterates through a directory and transforms
    -     .xml files into .fo files which can then be turned into DocBook XML
    -     files.
    -->>
<target name="build-pdf" depends="depends" 
    description="Generates PDF files from DocBook XML">>
    <xslt style="${fo.stylesheet}" extension=".fo" 
        basedir="${source.dir}" destdir="${fo.dir}">>
        <classpath refid="xalan.classpath" />>
        <include name="book.xml" />>
    </xslt>>

    <property name="fop.home" value="lib/fop-0.93" />>

    <taskdef name="fop" classname="org.apache.fop.tools.anttasks.Fop">>
        <classpath>>
            <fileset dir="${fop.home}/lib">>
                <include name="*.jar" />>
            </fileset>>
            <fileset dir="${fop.home}/build">>
                <include name="fop.jar" />>
                <include name="fop-hyph.jar" />>
            </fileset>>
        </classpath>>
    </taskdef>>

    <fop format="application/pdf" fofile="${fo.dir}/book.fo" 
        outfile="${dist.dir}/book.pdf" />>
</target>>

设置了此目标之后,从 Eclipse IDE 运行 build-pdf 目标。这一次,在 dist 目录中,将出现名为 book.pdf 的文件。

结束语

DocBook XML 是一种功能强大的格式,可用于构建可以生成各种不同输出格式(例如 HTML 和 PDF)的技术文档。该格式使您可以专注于文档的内容,将样式问题分离。由于它十分成熟,因此很多工具可用于编辑和构建 DocBook XML 格式的文档。

Eclipse IDE 附带了用于编写和验证 XML 文档的编辑器。Eclipse 还集成了 Ant,使您可以创建能够作为 Eclipse 中的常规构建器来执行的强大构建文件。此外,Eclipse 附带的模板使您可以快速构建插件项目,其中一些插件项目包含可在 Eclipse 中用作帮助的 HTML 文件。

所有这些工具结合使用可以让您在一个地点编写技术文档,然后将该技术文档以不同格式分发给各种读者。

参考资料

学习

获得产品和技术

讨论

  • Eclipse Platform 新闻组 应当是讨论关于 Eclipse 的问题的第一站(选择此链接将启动默认的 Usenet 新闻阅读器应用程序并打开 eclipse.platform)。
  • Eclipse 新闻组 中有很多参考资料适用于对使用和扩展 Eclipse 感兴趣的人员。
  • 参与 developerWorks blog 并加入 developerWorks 社区。

条评论

developerWorks: 登录

标有星(*)号的字段是必填字段。


需要一个 IBM ID?
忘记 IBM ID?


忘记密码?
更改您的密码

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件

 


在您首次登录 developerWorks 时,会为您创建一份个人概要。您的个人概要中的信息(您的姓名、国家/地区,以及公司名称)是公开显示的,而且会随着您发布的任何内容一起显示,除非您选择隐藏您的公司名称。您可以随时更新您的 IBM 帐户。

所有提交的信息确保安全。

选择您的昵称



当您初次登录到 developerWorks 时,将会为您创建一份概要信息,您需要指定一个昵称。您的昵称将和您在 developerWorks 发布的内容显示在一起。

昵称长度在 3 至 31 个字符之间。 您的昵称在 developerWorks 社区中必须是唯一的,并且出于隐私保护的原因,不能是您的电子邮件地址。

标有星(*)号的字段是必填字段。

(昵称长度在 3 至 31 个字符之间)

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件.

 


所有提交的信息确保安全。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=10
Zone=Open source, XML
ArticleID=245287
ArticleTitle=在 Eclipse 中构建 DocBook XML
publish-date=08062007