入門

本文將演示如何結(jié)合使用 DocBook XML 和 Eclipse 集成開發(fā)環(huán)境 (IDE)，創(chuàng)建以多種格式輕松分發(fā)的可重用技術(shù)文檔，

在Eclipse中構(gòu)建DocBook XML

。DocBook XML 是標準 XML 標記庫，使用它可以編寫用于生成幾乎所有輸出的樣式表。但是，由于 DocBook 已經(jīng)存在近 10 年，因此已經(jīng)編寫了許多樣式表來生成許多類型的文檔，包括 HTML、文本、PDF 和手冊。

讀完本文后，您應(yīng)當能夠使用 DocBook XML 創(chuàng)建可生成為 HTML 格式的文檔，并可用于 Eclipse 幫助插件及來自單個 XML 源文件的 PDF。您應(yīng)當具備一定的 XML 使用知識，還應(yīng)當能夠使用 Eclipse 和 Apache Ant，包括從 Eclipse IDE 運行 Ant 構(gòu)建文件。您需要使用 Eclipse V3.2 或更高版本、DocBook XML V4.x 文檔類型定義（Document Type Definition，DTD）、DocBook XSL 樣式表、Apache Xalan-Java™ 和（可選）Apache FOP（要獲得下載，請參閱 參考資料）。

DocBook XML 概覽

DocBook XML 是適于編寫文檔的 XML 標記庫。DocBook 中的眾多可用標記使它成為構(gòu)建技術(shù) 文檔的最佳選擇。由于 DocBook 是 XML，因此可以使用樣式表將其轉(zhuǎn)換為多種不同的輸出格式，而樣式表使 DocBook XML 成為一次性編寫技術(shù)文檔并以各種格式生成技術(shù)文檔的最佳選擇。

注：本文中的這些代碼都是使用 DocBook XML V4.5 開發(fā)的；在撰寫本文時，V5.0 正處于預(yù)發(fā)布狀態(tài)。

高級元素

表 1 顯示的元素常用作 DocBook XML 文件的高級元素。

表 1. 頂級 DocBook XML 元素

元素 說明 book 包含許多其他元素；惟一的高級元素是 chapter 書的一部分 article 一篇文章，也可包含在書中

內(nèi)容元素

在較高級元素內(nèi)，可能需要添加實際內(nèi)容 —— 段落、表、列表、代碼樣例等。表 2 列出了向書、章節(jié)或文章中添加內(nèi)容時所使用的一些常見元素。

表 2. 元素

元素 說明 caution 包含敬告讀者操作可能導(dǎo)致數(shù)據(jù)丟失、硬件損壞或軟件問題的文本 code 包含內(nèi)聯(lián)代碼，例如 this example 包含帶有標題的代碼示例 important 包含可能對讀者十分重要的文本 itemizedlist 具有可選的要點句（bullet point）的條目列表 note 包含提請讀者特別注意的文本 orderedlist 編號條目列表；您不必在構(gòu)建時為列表編號 —— 樣式表將為您執(zhí)行該操作 para 文本段落或文本塊 table 文本表或數(shù)據(jù)表 tip 包含用于為讀者提供建議的文本 title 與元素相關(guān)的標題

下面顯示的示例文檔中，其中的書至少包含了表 2 中列出的每個元素的其中一個。

清單 1. 基本 DocBook XML 示例


"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

　　
　　Example
　　
　　　　
　　　　　　
　　　　　　　　Nathan
　　　　　　　　Good
　　　　　　
　　　　
　　
　　
　　　　
　　　　You will like my book (I think).
　　
　　
　　　　
　　　　You must include at least one chapter in your book.
　　　　Here is another paragraph.
　　　　
　　　　　　This is some really important text.
　　　　
　　　　
　　　　　　Look both ways before crossing the street!
　　　　
　　　　
　　　　　　
　　　　　　　　Liberal use of new in loops can cause performance issues!
　　　　　　
　　　　
　　　　
　　　　　　
　　　　　　
String something = "Something";
　　　　　　
　　　　
　　


當文件生成為 HTML 并呈現(xiàn)到瀏覽器中后，它將類似圖 1：

圖 1. 轉(zhuǎn)換成 HTML 并在瀏覽器中呈現(xiàn)后的清單 1 代碼

完全介紹每個可用的 DocBook XML 標記最好留給參考手冊來完成；指向這些參考手冊的 HTML 版本的鏈接可在 參考資料 中獲得。同樣可以找到有關(guān) DocBook XML 的書籍。表 2 中列出的標記將給您提供一個良好的開端，但是更多標記可用于屏幕快照、命令提示符、用戶輸入、商標和引號等。

設(shè)置環(huán)境

您必須使用工具來執(zhí)行可擴展樣式表轉(zhuǎn)換語言（Extensible Stylesheet Transformation Language，XSLT）轉(zhuǎn)換，以及使用 XSL 樣式表把 DocBook XML 轉(zhuǎn)換為 HTML 或 PDF 等您認為更有用的格式。如果您構(gòu)建了自己私有的 XML，則還必須編寫您自己的樣式表。但是，使用 DocBook XML 等已建立的格式將允許您使用其他人已經(jīng)編寫的樣式表。要使用預(yù)編寫的樣式表，請下載這些樣式表（請參閱 參考資料）。在撰寫本文時，適用于 DocBook XML V4.5 的一組樣式表是 DocBook XSL V1.72.0。

獲得樣式表

包含 DocBook XSL（例如，docbook-xsl-1.72.0.zip）的已下載的歸檔文件包括按照生成的輸出類型組織到不同目錄中的樣式表。html 目錄包括輸出 HTML 的樣式表；fo 目錄包括生成格式化對象（Formatting Object，F(xiàn)O）格式文件的樣式表，等等。

下載歸檔文件并將其保存到便于記憶的位置。不需要把文件從歸檔文件中解壓縮出來 —— 您可以直接把它們導(dǎo)入 Eclipse。

使用 Xalan

在本文中，我使用 Xalan 作為 XSLT 處理器。在將 Xalan 與 Eclipse 附帶的 Ant 版本結(jié)合使用時會有一個問題：版本太低并且在嘗試處理 XSL 時會遇到問題。

Xalan 是可用作兩個子項目 Xalan C++ 和 Xalan-Java 的 Apache 項目。下載 Xalan-Java（如果計算機上還沒有）。下載完文件后，請將其保存到便于記憶的位置。像包含樣式表的歸檔文件一樣，仍然不要解壓縮文件的內(nèi)容。

創(chuàng)建 Eclipse 項目

到目前為止，您已經(jīng)看到了一些樣例文件，并且應(yīng)當已經(jīng)下載了最新版本的 DocBook XSL 樣式表，以及最新版本的 Xalan（如果以前沒有的話）。您還應(yīng)當已經(jīng)下載了 DocBook XML 模式文件。歸檔文件（例如，docbook-xsl-1.72.0.zip、xalan-j_2_7_0_bin-2jars.zip 和 docbook-xml-4.5.zip）應(yīng)當被保存到便于查找的位置。

下載并保存了所有歸檔文件后，您已經(jīng)準備好啟動 Eclipse 以創(chuàng)建新項目，并編輯把 DocBook XML 轉(zhuǎn)換為不同格式的 DocBook XML 和 Ant 腳本。

在 Eclipse 啟動后，通過選擇 File > New > Project 創(chuàng)建新項目。在 General 下，單擊常見的 Project，然后單擊 Next。在鍵入項目的名稱之后，單擊 Finish，在工作區(qū)中創(chuàng)建新項目。

從歸檔中導(dǎo)入文件

既然已經(jīng)在 Eclipse 中創(chuàng)建了新項目，那么接下來導(dǎo)入構(gòu)建 DocBook XML 要使用的文件。

導(dǎo)入 DTD 文件

首先，導(dǎo)入 DocBook XML DTD 文件。選擇 File > Import，如下所示，然后，在 General 類別中，選擇 Archive File。當 Import Wizard 顯示時，單擊 Browse 以打開可用于定位 DocBook XML DTD 歸檔文件（例如 docbook-xml-4.5.zip）的文件瀏覽器。

圖 2. 從歸檔文件導(dǎo)入

在 Into folder 框中的項目名稱后鍵入 /docbook-xml。確保選中 / 文件夾，如下所示。單擊 Select All（如果尚未選中或者如果已灰顯），則在完成時單擊 Finish。歸檔內(nèi)的文件將 入到項目中。

圖 3. 選擇要導(dǎo)入的文件

導(dǎo)入 XSL 樣式表

導(dǎo)入完 DocBook XML DTD 文件后，請遵循相同的過程導(dǎo)入 docbook-xsl-1.72.0.zip 文件的內(nèi)容。但是，這一次您無需在 Into folder 框中的項目名稱后指定文件夾名稱，因為歸檔的內(nèi)容將已經(jīng)被放入項目內(nèi)名為 docbook-xsl-1.72.0 的文件夾中。

既然已經(jīng)導(dǎo)入了 XSL 樣式表，接下來從在 Xalan Web 站點中下載的歸檔中導(dǎo)入所需的 Java Archive (JAR) 文件。導(dǎo)入其他歸檔文件時遵循同樣的過程，但是這一次，請確保清空 docs、licenses 和 samples 目錄，以便這些目錄不被導(dǎo)入到項目中。在您清空了那些目錄后，在 Into folder 框中添加 /lib，修改項目名稱。

在導(dǎo)入需要的所有文件后，請在項目內(nèi)創(chuàng)建另一個文件夾并將其命名為 src。這將是所有 DocBook XML 文件的基本文件夾。

到目前為止，應(yīng)當在 Eclipse 中有一個包括以下文件夾的項目：

docbook-xml，包含 DocBook XML DTD

docbook-xsl-1.72.0，包含 DocBook XSL 樣式表

lib，包含 Xalan JAR 文件

src，現(xiàn)在為空

如果項目中有了所有這些文件夾，那么您已經(jīng)準備好添加 Ant build.xml 文件以運行轉(zhuǎn)換過程。

編寫 Ant 腳本

Ant 是基于 Java 的構(gòu)建工具，它將讀取 XML 腳本并且可以執(zhí)行腳本中定義的很多任務(wù)。如果您不熟悉 Ant，請參閱 參考資料。在本文中，您將使用 Eclipse 來啟動 Ant，因此無需熟悉如何從命令行運行 Ant。此外，您也無需擔(dān)心自己如何下載和安裝 Ant，因為 Eclipse IDE V3.2.x 附帶了 Ant。它是比當前可獲得的版本低的版本 —— V1.65，相對于 V1.7 —— 但是出于本文的目的，該版本不會造成問題。

不過，Ant V1.6.5 附帶的 Xalan 版本在嘗試使用最新的 DocBook XSL 時看上去運行得不太好。但是如果下載和使用最新版本的 Xalan（及附帶的 Xerces 版本），它應(yīng)當可以正常運行。

結(jié)合使用 Xalan 與 Ant

有很多種方法可以告訴 Ant 使用特定版本的 Xalan —— 或任何其他 XSLT 處理器 —— 而不使用 Ant 附帶的默認版本。其中一種方法是修改 Ant 的類路徑。當您在 Eclipse IDE 內(nèi)使用 Ant 時，這是十分簡單的。選擇 Window > Preferences 以更改 Ant/CLASSPATH 下的設(shè)置。您可以在 CLASSPATH 選項卡中刪除對 Xalan 或 Xerces 的任何引用，并將其替換為已經(jīng)下載的版本。

如果您是惟一要執(zhí)行轉(zhuǎn)換的人，則這個方法很好，因為只有您必須更改 Ant 設(shè)置才能正確進行轉(zhuǎn)換。但是，如果要與團隊協(xié)作，更好的方法是在目錄（例如，lib）中包含 Xalan 和 Xerces JAR 文件以及項目，并修改 build.xml 文件以使用 xslt 任務(wù)的庫。使用這種方法，您可以簡單地將文件從源文件控件中簽出或者分發(fā)并運行項目，而不更改 Eclipse IDE 設(shè)置。

下面的 Ant 構(gòu)建腳本中提供了為 xslt 任務(wù)提供 JAR 文件的示例。

清單 2. 樣例 Ant 腳本





　　
　　　　　　This Ant build.xml file is used to transform. DocBook XML to various
　　
　　
　　
　　
　　
　　
　　
　　
　　　　
　　　　　　
　　　　　　
　　　　
　　
　　
　　
　　　　
　　
　　
　　
　　　　
　　
　　
　　
　　　　
　　
　　
　　 　　　　description="Generates HTML files from DocBook XML">
　　　　 　　　　　　basedir="src" destdir="${doc.dir}">
　　　　　　
　　　　
　　



粗體顯示的 標記使您可以指定 Xalan JAR 文件的位置。 元素用于定義在整個 Ant 腳本中可以重用的路徑。您還可以使用 classpath 屬性或在 classpath 元素內(nèi)指定路徑而不是使用 refid 屬性來引用路徑，把 Xalan XSLT 處理器的路徑指定給 xslt 目標。

xslt 目標是與 basedir、extension 和 destdir 屬性結(jié)合設(shè)計，用于遞歸瀏覽文件夾并為在目錄中找到的每個 XML 文件生成 HTML 文件。輸出將被存儲到一個文件夾中，稍后將用作后面演示的 Eclipse 插件附帶的幫助文件的 HTML 源文件。

創(chuàng)建 build.xml 文件

通過選擇 File > New >File 創(chuàng)建 build.xml 文件。鍵入 build.xml 作為文件名，然后選擇項目作為文件的位置。單擊 Finish 創(chuàng)建 Ant 文件。

您可以把 清單 2 中所示的內(nèi)容放入到新的構(gòu)建文件中。如果選用的任何目錄名稱與在這里使用的目錄名稱不同，則可能需要調(diào)整 property 元素中的一些值以確保正常運行。

您可以直接從 Eclipse 執(zhí)行 build.xml 文件，因為 Eclipse 配有內(nèi)置掛鉤 (hook)，可以運行 Ant 構(gòu)建腳本。使用 Ant 有很多其他優(yōu)點：首先，它是跨平臺的，這意味著您可以在運行 Java 代碼的任何操作系統(tǒng)上執(zhí)行相同的構(gòu)建腳本。另一個優(yōu)點是可以不依賴于 IDE 運行這個構(gòu)建腳本。因而，您可以輕松地將其整合到自動執(zhí)行的構(gòu)建過程中，也可以從命令行執(zhí)行它。最初，我打算研究如何設(shè)定 Eclipse 屬性以將 XSLT 處理器作為外部工具運行（參見 Run > External Tools），但是我為了獲得這些優(yōu)點而放棄了那個想法。

運行 build-html 目標

在編寫了 build.xml 文件之后，您可以運行 build-html 目標。您沒有任何 DocBook XML 文件，因此目標將不會做任何有用的操作。但是，運行腳本時不應(yīng)當會得到任何錯誤。

運行 Ant 目標的最簡單方法之一是在編輯器中打開構(gòu)建文件的情況下從 Outline 視圖運行 Ant 目標。在 Outline 視圖內(nèi)，右擊 build-html 目標的名稱，然后選擇 Run As > Ant Build。來自 Ant 構(gòu)建腳本的消息（如果有）將顯示在 Console 視圖中。

編寫 DocBook XML 文件

在 Eclipse 項目中，應(yīng)當有 DocBook XML DTD 文件、DocBook XSL 文件、Xalan 庫，而且現(xiàn)在還有 build.xml 文件。此時，您擁有了開始構(gòu)建 DocBook XML 文件所需的一切內(nèi)容。

創(chuàng)建第一個 DocBook XML 文件

要在 Eclipse 中創(chuàng)建第一個 DocBook XML 文件，請執(zhí)行以下步驟：

選擇 File > New > Other，

電腦資料

《在Eclipse中構(gòu)建DocBook XML》(http://www.lotusphilosophies.com)。

從 XML 類別中，選擇 XML，然后單擊 Next。

在 Create XML File 窗口中，選擇 Create XML file from a DTD file，然后單擊 Next。

在 File name 框中鍵入 chapter1.xml，然后確保項目內(nèi)的 src 文件夾已被選中，然后單擊 Next。

在 Select DTD File 中，瀏覽到項目的 docbook-xml 文件夾中的 docbookx.dtd 文件，然后單擊 Next。

當 Select Root Element 窗口顯示時，請從 Root element 中選擇 chapter，然后取消選中 Create first choice of required choice 復(fù)選框。

鍵入 -//OASIS//DTD DocBook XML V4.5//EN，然后單擊 Finish。

在 XML 編輯器中使用 chapter1.xml

Eclipse 將在 XML 編輯器中打開 chapter1.xml。Eclipse 中的 XML 編輯器有兩個文件視圖：Design 和 Source。XML 文件的 Design 視圖將以網(wǎng)格的形式顯示文件的元素，其中，元素名稱顯示在左側(cè)列中，元素的內(nèi)容顯示在右側(cè)列中。您可以通過右鍵單擊文件并選擇 Add Child、Add After 或 Add Before 把新元素添加到文件中。

如果使用的是 DTD，則上下文菜單中的菜單項將限定您只能添加有效的元素。此功能使您可以確保在稍后執(zhí)行轉(zhuǎn)換時 XML 文件中不會有大量驗證錯誤。

構(gòu)建模塊化文檔

創(chuàng)建許多文檔時，文檔之間一定會有類似之處，尤其是在它們?nèi)�都面向相同讀者的情況下，例如大型企業(yè)或一群人。例如，如果您讀過很多技術(shù)書籍，您就可能已經(jīng)注意到幾乎每本技術(shù)書籍都有 “本書中使用的約定” 部分或用于演示書中如何設(shè)定線索、提示、內(nèi)嵌代碼和代碼清單格式的章節(jié)。

分割 DocBook XML 文件

使用 DocBook XML 使您能夠?qū)⑽臋n分割為多個文件，這些文件可以編譯成一個單元并能夠重用。例如，您可以將書中的每一個章節(jié)放入單獨的 XML 文檔中。然后可以在其他書中使用這些章節(jié)，或者簡單地將章節(jié)分割為獨立的文件以實現(xiàn)更輕松地維護。您還可以將這些章節(jié)包括到書并使用樣式表處理它們。

清單 3 提供了構(gòu)建動態(tài)包含其他 DocBook XML 文件的 DocBook XML 文檔的示例。在轉(zhuǎn)換過程中處理此文件時，該文件看上去 —— 這里是指 chapter1.xml —— 就是 &chap1; 所在的位置。

清單 3. 包含 chapter1.xml 的樣例 book.xml 文件


　　"../docbook-xml/docbookx.dtd" [
　　
　　]>

　　&chap1;


采取這種方法時有幾點注意事項。首先，必須修改 chapter1.xml 文件以刪除 XML 預(yù)處理指令和 DOCTYPE 元素。由于 chapter1.xml 的內(nèi)容將被放到 &chap1 實體所在的位置，因此 book.xml 文件的中間將包含 XML 處理指令和 DOCTYPE 元素，會使該文件無效。

其次，如果不再需要將單獨的章節(jié)文件處理成單獨的 HTML 文件，則應(yīng)當更新 Ant 構(gòu)建腳本以避免對章節(jié)文件進行處理。幸運的是，使用 Ant 中的 xslt 任務(wù)，這項更改非常簡單。xslt 任務(wù)可以包含與 Ant 中的 fileset 元素相同的元素，這意味著您可以構(gòu)建一系列可以非常輕松地包含和清除文件。清單 4 顯示了如何使用 元素包括必要的添加內(nèi)容以在處理時跳過某些文件。

清單 4. 使用 XSLT 任務(wù)包含和清除文件

　　description="Generates HTML files from DocBook XML">
　　 　　　　basedir="${source.dir}" destdir="${doc.dir}">
　　　　
　　　　
　　　　
　　


如果仍需要構(gòu)建全部文檔，可以刪除上面所示的 exclude 元素。

不僅限于分割章節(jié)和書。只要是對您有意義，就可以以任何方法物理分割 DocBook XML 文件，例如將各部分單獨保存在文件中。您甚至可以把書包含在 set 元素中，該元素是最高級別的 DocBook 元素。

構(gòu)建幫助插件

Eclipse 框架功能強大的特性之一是可擴展性。當我看到企業(yè)使用特殊的 “企業(yè)允許的” 方法連接至數(shù)據(jù)庫、事務(wù)處理或錯誤處理時，我總是想知道企業(yè)為什么讓開發(fā)人員到工作環(huán)境外部去查找并獲取文檔。為什么不構(gòu)建可在公司內(nèi)部網(wǎng)中獲得的相同 HTML 文檔并以能夠通過 IDE、索引和搜索輕松地訪問到的幫助形式將其分發(fā)給開發(fā)人員？

您可以使用 Eclipse IDE 附帶的模板快速創(chuàng)建包含 HTML 文件格式的幫助的插件項目。下幾個部分將演示如何構(gòu)建這個插件項目。構(gòu)建插件項目后，您可以包括在 DocBook XML 項目中構(gòu)建的 HTML 文件。

創(chuàng)建幫助插件

要創(chuàng)建幫助插件，請執(zhí)行以下步驟：

選擇 File > New > Project 以啟動 New Project Wizard。

從可用向?qū)Я斜淼?Plug-in Development 類別中，選擇 Plug-in Project，然后單擊 Next。

在 Project name 框中，鍵入 MyHelpPlugin，然后單擊 Next。

在如圖 4 所示的窗口中單擊 Next。

圖 4. New Plug-in Project

從 Available Templates 列表中，選擇 Plug-in with sample help content，然后單擊 Next。

在下一個窗口中，單擊 Finish。系統(tǒng)可能提示您切換到 Plug-in Development 透視圖。如果提示，建議單擊 Yes，因為透視圖將自動包括在構(gòu)建幫助時對您有用的視圖。

新項目包含名為 html 的文件夾，并且在該文件夾中包含一些樣例 HTML 文件。將用 DocBook 項目中生成的 HTML 文件替換這些文件。

查看進度

在尚未進行任何更改的情況下，選擇 Run > Run As > Eclipse Application，將插件與 Eclipse 的實例結(jié)合運行以查看到目前為止幫助的內(nèi)容。使用您的插件，Eclipse 的新實例將啟動。在 Eclipse 啟動后，選擇 Help > Help Contents 以查看運行中的插件。如果沒有做任何更改，則將看到 Test TOC 列于內(nèi)容之中，如圖 5 所示：

圖 5. 內(nèi)容樣例表

整合 DocBook XML 項目中的 HTML

現(xiàn)在您已經(jīng)看到了新幫助插件的默認內(nèi)容，接下來該整合先前構(gòu)建的 DocBook XML 項目中的 HTML 了。因此需要復(fù)制新幫助插件項目的 HTML 輸出，但是您不希望每次都手動執(zhí)行該操作。如果進行手動操作，則在構(gòu)建插件的過程中很可能犯下錯誤或忘記執(zhí)行該操作。

添加 Ant 文件

自動復(fù)制 HTML 文件的第一步是構(gòu)建一個簡單的 Ant 文件。這個 Ant 文件只將來自 DocBook XML 項目的 HTML 文件復(fù)制到插件項目的 html 文件夾中。然后，只要 Eclipse 構(gòu)建項目，就會執(zhí)行該 Ant 文件。

Ant 文件的內(nèi)容如下所示。文件只有一個目標 —— prepare —— 它也是構(gòu)建文件的默認目標。由于此構(gòu)建文件實際上只適于被 Eclipse 調(diào)用，因此我把默認目標保留為 prepare。

清單 5. 插件項目中的 Ant 構(gòu)建文件



　　
　　　　Prepares the Help plug-in project by copying the HTML help files
　　　　from the DocBook XML project into this one.
　　

　　
　　
　　

　　
　　　　
　　　　
　　

　　
　　　　
　　　　　　
　　　　
　　


定義構(gòu)建器

在 Eclipse 中，您可以定義在 Eclipse 構(gòu)建項目時運行的程序。這些程序被稱為構(gòu)建器。您可以通過單擊項目名稱，然后選擇 Project > Properties 來修改構(gòu)建器。在 Builders 下方，您將看到已經(jīng)為項目設(shè)置的構(gòu)建器：Java Builder、Plug-in Manifest Builder 和 Extension Point Schema Builder。要讓 Eclipse 運行 Ant 腳本把 HTML 文件復(fù)制到插件項目中，請執(zhí)行以下步驟：

在 Builders 屬性頁面中單擊 New。

從列表中選擇 Ant Build，然后單擊 OK。

鍵入新構(gòu)建器的名稱，例如 Ant Builder。

在 Buildfile 下，單擊 Browser Workspace 定位工作區(qū)內(nèi)的 Ant 文件。

單擊 Targets 選項卡，并確保 After a "Clean" 和 Manual Build 目標顯示 。

單擊 OK 保存構(gòu)建器。

在 Builders 頁面中，選擇剛創(chuàng)建的新 Ant 構(gòu)建器，然后單擊 Up，直至您的構(gòu)建器在列表中位于第一位。您必須這樣做，因為需要把文件復(fù)制到插件項目中，然后才能執(zhí)行其他操作。

設(shè)置了新構(gòu)建器后，您可以選擇 Project > Clean 或 Project > Build 清除或構(gòu)建項目。Ant 構(gòu)建器將運行并自動從 DocBook XML 項目中拖出 HTML 文件。

添加構(gòu)建器也適于 DocBook XML 項目。您可以將 Ant 構(gòu)建器添加到 DocBook XML 項目中，把任意一個目標設(shè)為清除或構(gòu)建項目時執(zhí)行的目標（記住，對于這些目標，usage 目標是默認值）。

幫助 TOC 文件

HTML 幫助文件的目錄 (TOC) 表位于插件項目包括的兩個 XML 文件中。文件如下所示：

清單 6. TestTOC.xml




　　


清單 6 中所示的 testTOC.xml 文件包含顯示在幫助窗口的 Contents 窗格中的標題名稱。它只是用于鏈接到 toc.xml 文件。

清單 7. Toc.xml




　　
　　


toc.xml 文件包含顯示在主標題下方的主要標題。這些主要標題都是用 href 屬性鏈接到 HTML 頁面，在清單 7 中用粗體顯示：

您可以將幫助作為一個整體文件來構(gòu)建，像書一樣，并且只有一個指向該文件的主要標題。但是，請考慮把文檔分割為可以在 toc.xml 文件中通過索引找到的獨立章節(jié)，而且根據(jù)需要構(gòu)建為單獨的書。有關(guān)如何把文檔分割為可以組織的各種物理文件的提示，請參閱 “Building modular documentation”。

自定義 DocBook 輸出

到目前為止，DocBook XML 已經(jīng)轉(zhuǎn)換為在 Eclipse 插件內(nèi)用作幫助的常規(guī) HTML。但是如果需要整理轉(zhuǎn)換后輸出的 HTML 的外觀該怎么辦？

幸運的是，您不必只為了向 HTML 添加一點個性化或自定義格式而編寫自己的 XSL 樣式表。相反，您可以將變量傳遞給 XSLT 轉(zhuǎn)換步驟以指定使您可以優(yōu)化 HTML 格式的層疊樣式表（Cascading Style. Sheet，CSS）。

指定 CSS 樣式表

把 DocBook XML 轉(zhuǎn)換為 HTML 的 XSL 樣式表將檢查名為 html.stylesheet 的變量。如果變量包含值，則將在 HTML 的 link 元素中使用該值鏈接到您指定的樣式表。

清單 8 顯示了具有 important 和 caution 類的簡單 CSS。該 CSS 修改了這些類中文本的顏色。您將看到在顯示頁面時，這些類分別對應(yīng) 和 標記中的內(nèi)容。

清單 8. 簡單的 CSS 文件

body { font-family : arial,sans-serif; font-size : small; }
.important { color : blue; }
.caution { color : red; }

修改 Ant 構(gòu)建文件

將清單 8 中所示的 CSS 保存到 DocBook XML 項目的 lib 目錄中名為 style.css 的文件中。保存完文件后，必須修改 Ant 構(gòu)建文件把 CSS 文件的名稱傳遞到 xslt 目標中，然后將 CSS 文件從 lib 文件夾復(fù)制到與其余 HTML 輸出相同的文件夾中。清單 9 用粗體顯示了這些更改。

清單 9. 經(jīng)過修改后的 Ant 腳本

　　description="Generates HTML files from DocBook XML">
　　 　　　　basedir="${source.dir}" destdir="${doc.dir}">
　　　　
　　　　
　　　　
　　　　
　　
　　
　　
　　　　
　　　　　　
　　　　
　　


在做出更改后，您可以重新運行 DocBook XML 項目中的 Ant 構(gòu)建腳本。這一次，當您查看輸出的 HTML 文件時，您將看到更改后的字體和 “Important” 和 “Caution” 部分的新字體顏色。

創(chuàng)建 PDF

至此，您已經(jīng)使用了各種工具從 DocBook XML 生成可以分布到內(nèi)部網(wǎng)站和包含在 Eclipse 幫助插件中的 HTML。但是，我在前面提到過，使用相同的 DocBook XML 源文件，還可以生成 PDF。從 DocBook XML 生成 PDF 要求使用一個額外的工具：來自 Apache XML Graphics Project 的 FOP 庫（請參閱 參考資料）。

FOP 庫中有一個可以直接放入 DocBook XML 項目現(xiàn)有 Ant 構(gòu)建文件中的 Ant 任務(wù)。該 Ant 任務(wù) fop 將轉(zhuǎn)換 FO 文件，這些 FO 文件都是使用 DocBook XSL 附帶的 FO 樣式表構(gòu)建的。

使用 FOP 庫生成 PDF

要使用 FOP 庫，請從 Web 站點中下載包含二進制版本的 ZIP 文件（例如，fop-0.93-bin-jdk1.4.zip）。雖然該 ZIP 文件的名稱好像指示它是專門為 Java 2 Platform, Standard Edition (J2SE), Development Kit (JDK) V1.4 構(gòu)建的，但是它可以與 Java V5 很好地結(jié)合使用。像已下載的其他歸檔文件一樣，您仍無需解壓縮此文件。

在 Eclipse 中，選擇 File > Import，然后執(zhí)行在 “從歸檔導(dǎo)入文件” 中使用的相同過程。但是，這一次，只選擇 build 和 lib 文件夾執(zhí)行導(dǎo)入。

導(dǎo)入完文件后，修改 Ant 構(gòu)建腳本以設(shè)置 fop 目標并在新的 build-pdf 目標中調(diào)用它，如下所示：

清單 10. build-pdf 目標

>
　　description="Generates PDF files from DocBook XML">>
　　 　　　　basedir="${source.dir}" destdir="${fo.dir}">>
　　　　>
　　　　>
　　>
　　>
　　>
　　　　>
　　　　　　>
　　　　　　　　>
　　　　　　>
　　　　　　>
　　　　　　　　>
　　　　　　　　>
　　　　　　>
　　　　>
　　>
　　 　　　　utfile="${dist.dir}/book.pdf" />>
>

設(shè)置了此目標之后，從 Eclipse IDE 運行 build-pdf 目標。這一次，在 dist 目錄中，將出現(xiàn)名為 book.pdf 的文件。

結(jié)束語

DocBook XML 是一種功能強大的格式，可用于構(gòu)建可以生成各種不同輸出格式（例如 HTML 和 PDF）的技術(shù)文檔。該格式使您可以專注于文檔的內(nèi)容，將樣式問題分離。由于它十分成熟，因此很多工具可用于編輯和構(gòu)建 DocBook XML 格式的文檔。

Eclipse IDE 附帶了用于編寫和驗證 XML 文檔的編輯器。Eclipse 還集成了 Ant，使您可以創(chuàng)建能夠作為 Eclipse 中的常規(guī)構(gòu)建器來執(zhí)行的強大構(gòu)建文件。此外，Eclipse 附帶的模板使您可以快速構(gòu)建插件項目，其中一些插件項目包含可在 Eclipse 中用作幫助的 HTML 文件。

所有這些工具結(jié)合使用可以讓您在一個地點編寫技術(shù)文檔，然后將該技術(shù)文檔以不同格式分發(fā)給各種讀者。