docbook_在Eclipse中构建DocBook XML

最新推荐文章于 2022-09-22 09:07:50 发布

cuyi7076

最新推荐文章于 2022-09-22 09:07:50 发布

阅读量341

点赞数

文章标签： python java 大数据 linux eclipse

原文链接：https://www.ibm.com/developerworks/xml/library/os-eclipse-docbook/index.html

版权

docbook

入门

本文演示了如何结合使用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文档类型定义（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`	可选地带有项目符号点的项目列表
`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.清单1代码经过HTML转换和浏览器渲染后

最好将每个可用的DocBook XML标记详尽地提到参考手册中。为这些类型之一HTML版本的链接中提供相关信息。也提供有关DocBook XML的书籍。表2中列出的标签将为您提供一个良好的开端，但还有更多标签可用于截屏，命令提示符，用户输入，商标和引号等。

设置环境

您必须使用一种工具来执行可扩展样式表转换语言（XSLT）转换，并使用XSL样式表将DocBook XML转换为您认为更有用的格式，例如HTML或PDF。如果要构建自己的专有XML，则还必须编写自己的样式表。但是，使用诸如DocBook XML的既定格式，可以使用其他人已经编写的样式表。要使用预先编写的样式表，请下载它们（请参阅参考资料）。在撰写本文时，DocBook XSL V1.72.0是DocBook XML V4.5的一组样式表。

获取样式表

您下载的包含DocBook XSL的存档文件（例如docbook-xsl-1.72.0.zip）包括不同目录中的样式表，这些样式表根据它们产生的输出类型进行组织。 html目录中包含用于输出HTML的样式表； fo目录包含用于生成格式设置对象（FO）格式的文件的样式表等。

下载存档文件并将其保存到以后容易记住的位置。无需从归档文件中提取文件-您可以将它们直接导入Eclipse。

使用Xalan

在本文中，我将Xalan用作XSLT处理器。将Xalan与Eclipse附带的Ant版本一起使用时存在一个问题：该版本较旧，并且在尝试处理XSL时出现问题。

Xalan是一个Apache项目，可以作为两个子项目使用：Xalan C ++和Xalan-Java。如果您的计算机上没有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和Ant脚本，这些脚本会将DocBook XML转换为不同的格式。

Eclipse启动后，通过选择File> New> Project来创建一个新项目。在“ 常规”下 ，单击常规项目，然后单击“ 下一步” 。输入项目名称后，单击“ 完成”以在工作区中创建新项目。

从档案导入文件

现在，您已经在Eclipse中创建了一个新项目，请导入将用于构建DocBook XML的文件。

导入DTD文件

首先，导入DocBook XML DTD文件。如下所示，选择“ 文件”>“导入” ，然后从“ 常规”类别中选择“ 存档文件” 。当出现导入向导时，单击浏览以打开文件浏览器，您可以使用该文件浏览器找到DocBook XML DTD存档文件，例如docbook-xml-4.5.zip。

图2.从档案文件导入

在“ 进入文件夹”框中，在项目名称后键入/docbook-xml 。确保选择/文件夹，如下所示。单击Select All如果它没有选择，或者如果它是灰色的，然后单击完成时，即可大功告成。存档中的文件将插入到您的项目中。

图3.选择要导入的文件

导入XSL样式表

完成DocBook XML DTD文件的导入后，请按照相同的过程导入docbook-xsl-1.72.0.zip文件的内容。但是，这一次，您不需要在“ 进入文件夹”框中的项目名称之后指定文件夹名称，因为存档的内容已经放置在项目内部名为docbook-xsl-1.72.0的文件夹中。

现在，您已经导入了XSL样式表，请从Xalan网站下载的归档文件中导入所需的Java归档文件（JAR）文件。遵循与导入其他存档文件相同的过程，但是这次，请确保清除docs，license和sample目录，以免将它们导入到项目中。清除这些目录后，通过添加/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，因为Eclipse IDE V3.2.x随Ant一起提供。它是一个比当前可用版本更旧的版本-V1.65，而不是V1.7-但是就本文而言，这无关紧要。

但是，当我使用最新的DocBook XSL尝试使用Ant的V1.6.5附带的Xalan版本时，它似乎无法正常工作。但是，如果您正在下载并使用最新版本的Xalan（包括Xerces的版本），它应该可以正常工作。

将Xalan与Ant一起使用

有几种方法可以告诉Ant使用特定版本的Xalan或任何其他XSLT处理器，而不使用Ant随附的默认版本。其中之一是修改Ant的类路径。当您在Eclipse IDE中使用Ant时，这很容易做到。选择“ 窗口”>“首选项”以更改“ Ant / CLASSPATH”下的设置。您可以在CLASSPATH选项卡上删除对Xalan或Xerces的任何引用，并将其替换为您下载的版本。

不可逆转的变化

不必担心进行不可逆的更改。如果您决定要将Ant设置恢复为首次下载Eclipse时的状态，那么Restore Default按钮可能是真正的救星。

如果您是唯一要进行转换的人，则此方法很好，因为只有您将需要更改Ant设置才能使转换正常工作。但是，如果您与一群人一起工作，更好的方法是将Xalan和Xerces JAR文件包含在项目的目录中（例如lib），并修改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脚本中重用的路径。还可以指定该路径的Xalan XSLT处理器将所述xslt通过使用目标classpath属性或通过指定内部的路径classpath元件，而不是使用refid属性指的路径。

xslt目标设计为具有basedir ， extension和destdir属性，以递归通过文件夹并为目录中找到的每个XML文件生成HTML文件。输出将存储在一个文件夹中，您将在稍后使用该文件夹作为Eclipse插件附带的帮助文件HTML源。

创建一个build.xml文件

通过选择File> New> File创建一个build.xml文件。键入build.xml作为文件名，然后选择项目作为文件的位置。单击完成以创建Ant文件。

您可以将清单2中所示的内容放入新的构建文件中。如果您选择的任何目录名称与此处使用的目录名称都不相同，则可能需要调整property元素中的某些值才能使所有内容正常工作。

您可以直接从Eclipse执行build.xml文件，因为Eclipse具有用于运行Ant构建脚本的内置挂钩。使用Ant有两个其他优点：首先，它是跨平台的，这意味着您可以在运行Java代码的任何操作系统上执行相同的构建脚本。另一个优点是您可以独立于IDE运行此构建脚本。因此，您可以轻松地将其合并到自动构建过程中，也可以从命令行执行它。最初，我正在研究设置Eclipse属性以将XSLT处理器作为外部工具运行（请参阅Run> External Tools ），但是为了获得这些优势，我放弃了这个想法。

运行build-html目标

编写build.xml文件后，即可运行build-html目标。您没有任何DocBook XML文件，因此目标不会做任何有用的事情。但是，您不应从运行脚本中得到任何错误。

运行Ant目标的最简单方法之一是在编辑器中打开构建文件的同时从Outline视图中执行。在Outline视图中，右键单击build-html目标的名称，然后选择Run As> Ant Build 。来自Ant构建脚本的消息（如果有）将出现在“控制台”视图中。

编写DocBook XML文件

在Eclipse项目中，您应该拥有DocBook XML DTD文件，DocBook XSL文件，Xalan库以及现在的build.xml文件。至此，您已经具备了开始构建DocBook XML文件所需的一切。

创建第一个DocBook XML文件

要在Eclipse中创建第一个DocBook XML文件：

选择“ 文件”>“新建”>“其他” 。
从XML类别中，选择XML ，然后单击Next 。
在“ 创建XML文件”窗口中，选择从DTD文件创建XML文件 ，然后单击下一步 。
在“ 文件名”框中键入chapter1.xml ，然后确保已选择项目中的src文件夹，然后单击“ 下一步” 。
在“ 选择DTD文件”中 ，导航到项目的docbook-xml文件夹中的docbookx.dtd文件，然后单击“ 下一步” 。
当出现“选择根元素”窗口时，从“ 根元素”中选择章节，然后清除“ 创建所需选项的第一选择”复选框。
键入-//OASIS//DTD DocBook XML V4.5//EN ，然后单击“ 完成” 。

验证XML

可以在Eclipse内部验证DocBook XML文件。只需在Project Explorer中右键单击该文件，然后单击Validate即可 。如果发生验证错误，它们将显示在IDE中“ 错误”下的“问题”视图中。如果在此视图中双击错误消息，则Eclipse IDE将显示文件中发生错误的位置。

在XML编辑器中使用Chapter1.xml

Eclipse在XML编辑器中打开chapter1.xml。 Eclipse中的XML编辑器有两个文件视图：Design和Source。 XML文件的“设计”视图在网格中显示文件的元素，在左列中具有元素名称，在右列中具有元素的内容。您可以通过右键单击文件并选择Add Child ， Add After或Add Before来向文件添加新元素。

如果使用的是DTD，则上下文菜单中的菜单选项会将您限制为仅添加有效的元素。此功能使您可以确保在以后执行转换时，在XML文件中没有一堆验证错误。

构建模块化文档

当您创建许多文档时，文档之间必然会有相似之处，特别是如果这些文档都是针对同一受众的，例如大型公司或员工。例如，如果您阅读了许多技术书籍，您可能已经注意到几乎每个人都有一个“本书中使用的惯例”部分或该章节演示了如何在提示中使用提示，技巧，内联代码和代码清单格式。书。

对DocBook XML文件进行分区

使用DocBook XML，您可以将文档划分为多个文件，这些文件可以编译为一个单元并有可能重新使用。例如，您可以将书的每一章放入一个单独的XML文档中。然后，您可以在其他书籍中使用它们，也可以将它们分区到单独的文件中，以使其更易于维护。然后，您可以将这些章节包括在书中，并使用样式表进行处理。

清单3提供了一个构建DocBook XML文档的示例，该文档动态地包含其他DocBook XML文件。在转换过程中处理此文件时，就好像文件-在这里，chapter1.xml-在&chap1; 位于。

清单3.示例book.xml文件，其中包括chapter1.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元素。由于&chap1的内容将放置在&chap1实体所在的位置，因此book.xml将在文件中间包含XML处理指令和DOCTYPE元素，从而使其无效。

其次，如果您不再希望将单个章节文件处理为单个HTML文件，则应更新Ant构建脚本以跳过对章节文件的处理。幸运的是，对于Ant中的xslt任务，此更改相当微不足道。 xslt任务可以包含与Ant中的fileset元素相同的元素，这意味着您可以构建文件列表以相当容易地包含和排除。清单4显示了如何使用<exclude>元素<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元素中包含书籍， set元素是最高级别的DocBook元素。

构建一个帮助插件

Eclipse框架的强大功能之一是其可扩展性。我常常想知道-当我看到具有连接到数据库，处理事务或处理错误的特定“企业批准”方式的企业时，为什么企业让他们的开发人员将目光投向他们正在研究的环境之外。为什么不构建企业内部网上可用的相同HTML文档，并以帮助形式将其分发给开发人员，这些帮助可以从IDE轻松访问，进行索引和搜索？

Eclipse IDE附带了模板，您可以使用这些模板快速创建包含HTML文件形式的帮助的插件项目。接下来的几节将演示如何构建此插件项目。构建插件项目后，可以将构建HTML文件包括在DocBook XML项目中。

创建帮助插件

要创建帮助插件：

选择“ 文件”>“新建”>“项目”以启动“新建项目向导”。
从可用向导列表中，从“ 插件开发”类别中选择“ 插件项目 ”，然后单击“ 下一步” 。
在“ 项目名称”框中，键入MyHelpPlugin ，然后单击“ 下一步” 。
在图4所示的窗口上单击Next 。
图4.新的插件项目
从“ 可用模板”列表中，选择“ 带有示例帮助内容的插件” ，然后单击“ 下一步” 。
在下一个窗口中，单击完成。可能会提示您切换到“插件开发”透视图。如果是这样，建议您单击“ 是”，因为透视图会自动包含有助于构建帮助的视图。

新项目包含一个名为html的文件夹，该文件夹中包含一些示例HTML文件。您将用DocBook项目中生成HTML文件替换这些文件。

检查你的进度

尚未进行任何更改，请选择“运行”>“运行方式”>“ Eclipse应用程序”以Eclipse实例运行该插件，以查看到目前为止的帮助。使用您的插件，将启动一个新的Eclipse实例。 Eclipse启动后，选择“ 帮助”>“帮助目录”以查看您的插件。如果您未进行任何更改，则会在目录中看到Test TOC ，如图5所示。

图5.样例目录

合并DocBook XML项目中HTML

现在，您已经看到了新帮助插件的默认内容，是时候合并您先前构建的DocBook XML项目中HTML了。这样做需要从新的帮助插件项目中复制HTML输出，但是您不想每次都手动进行。如果不进行手动操作，则在构建插件的过程中很容易犯错误或忘记这样做。

添加一个Ant文件

自动复制HTML文件的第一步是构建一个简单的Ant文件。该Ant文件仅将HTML文件从DocBook XML项目复制到插件项目中的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，插件清单构建器和Extension Point Schema Builder。要使Eclipse运行Ant脚本以将HTML文件复制到您的插件项目中：

从“ 构建器”属性页面中单击“ 新建 ”。
从列表中选择Ant Build ，然后单击OK 。
输入新构建器的名称，例如Ant Builder 。
在构建文件 ，单击浏览器工作区来定位工作区内的Ant文件。
单击“ 目标”选项卡，并确保“清理后”和“ 手动构建”目标后说<default target selected> 。
单击确定以保存构建器。
在“构建器”页面上，选择刚创建的新Ant构建器，然后单击“ 向上”直到您的构建器成为列表中的第一个。之所以必须这样做，是因为您想要在执行更多工作之前将文件复制到插件项目中。

设置新的生成器后，可以选择“ 项目”>“清理”或“ 项目”>“生成”来清理或生成项目。 Ant构建器将运行并自动从DocBook XML项目中提取HTML文件。

项目建设订单

您可能必须修改在工作空间中构建项目的顺序，以确保在您的帮助插件之前已构建了包含DocBook文档的项目。要更改项目构建顺序，请选择“ 窗口”>“首选项” 。在常规/工作区/构建订单下 ，您将找到项目列表。您可以清除“ 使用默认构建顺序”复选框，然后使用“ 向上”和“向下”按钮对项目进行重新排序。

添加构建器也适用于DocBook XML项目。您可以将Ant构建器添加到DocBook XML项目中，将任何一个目标设置为在清理或构建项目时要执行的目标。（请记住，使用这些目标是默认的usage目标。）

帮助目录

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文件包含将出现在帮助窗口的“内容”窗格中的标题名称。它只不过链接到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文件中建立索引，也可以根据需要嵌入到一本书中。有关如何将文档分解为可以组织的不同物理文件的提示，请参阅“构建模块化文档”。

自定义DocBook输出

到目前为止，您已经将DocBook XML转换为常规HTML，用作Eclipse插件中的帮助。但是，如果要修饰转换输出HTML外观，该怎么办？

幸运的是，您不必编写自己的XSL样式表就可以向HTML添加一些个性化或自定义格式。相反，您可以将变量传递到XSLT转换步骤，以分配级联样式表（CSS），从而可以“漂亮地格式化” HTML。

分配CSS样式表

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

清单8显示了一个简单CSS，其中包含几个类： important和caution 。 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构建文件以在xslt目标中传递CSS文件的名称，然后将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文件时，您将看到“重要”和“警告”部分的字体更改和新的字体颜色。

创建PDF

到现在为止，您一直在使用各种工具从DocBook XML生成HTML，这些HTML可分发到Intranet站点并包含在Eclipse帮助插件中。但是，我之前提到过，使用相同的DocBook XML源文件，您还可以生成PDF。从DocBook XML生成PDF需要另外一种工具：Apache XML Graphics Project的FOP库（请参阅参考资料）。

FOP库包含一个Ant任务，您可以将其直接放入DocBook XML项目中现有的Ant构建文件中。 Ant任务fop转换FO文件，这些文件是由DocBook XSL随附的FO样式表构建的。

使用FOP库生成PDF

要使用FOP库，请从网站下载包含二进制发行版的ZIP文件（例如fop-0.93-bin-jdk1.4.zip）。尽管ZIP文件的名称似乎表明它是专门为Java 2平台标准版（J2SE），开发套件（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文件的模板。

所有这些工具共同作用，使您可以在一处编写技术文档，并以不同的格式将其分发给广泛的受众。

翻译自: https://www.ibm.com/developerworks/xml/library/os-eclipse-docbook/index.html