入門
本文將演示如何結(jié)合使用 DocBook XML 和 Eclipse 集成開(kāi)發(fā)環(huán)境 (IDE)，創(chuàng)建以多種格式輕松分發(fā)的可重用技術(shù)文檔，
在Eclipse中構(gòu)建DocBook XML
。DocBook XML 是標(biāo)準(zhǔn) XML 標(biāo)記庫(kù)，使用它可以編寫用于生成幾乎所有輸出的樣式表。但是，由于 DocBook 已經(jīng)存在近 10 年，因此已經(jīng)編寫了許多樣式表來(lái)生成許多類型的文檔，包括 HTML、文本、PDF 和手冊(cè)。讀完本文后，您應(yīng)當(dāng)能夠使用 DocBook XML 創(chuàng)建可生成為 HTML 格式的文檔，并可用于 Eclipse 幫助插件及來(lái)自單個(gè) XML 源文件的 PDF。您應(yīng)當(dāng)具備一定的 XML 使用知識(shí)，還應(yīng)當(dāng)能夠使用 Eclipse 和 Apache Ant，包括從 Eclipse IDE 運(yùn)行 Ant 構(gòu)建文件。您需要使用 Eclipse V3.2 或更高版本、DocBook XML V4.x 文檔類型定義（Document Type Definition，DTD）、DocBook XSL 樣式表、Apache Xalan-Java™ 和（可選）Apache FOP（要獲得下載，請(qǐng)參閱 參考資料）。
DocBook XML 概覽
DocBook XML 是適于編寫文檔的 XML 標(biāo)記庫(kù)。DocBook 中的眾多可用標(biāo)記使它成為構(gòu)建技術(shù) 文檔的最佳選擇。由于 DocBook 是 XML，因此可以使用樣式表將其轉(zhuǎn)換為多種不同的輸出格式，而樣式表使 DocBook XML 成為一次性編寫技術(shù)文檔并以各種格式生成技術(shù)文檔的最佳選擇。
注：本文中的這些代碼都是使用 DocBook XML V4.5 開(kāi)發(fā)的；在撰寫本文時(shí)，V5.0 正處于預(yù)發(fā)布狀態(tài)。
高級(jí)元素
表 1 顯示的元素常用作 DocBook XML 文件的高級(jí)元素。
表 1. 頂級(jí) DocBook XML 元素
元素
說(shuō)明
book
包含許多其他元素；惟一的高級(jí)元素是
內(nèi)容元素
在較高級(jí)元素內(nèi)，可能需要添加實(shí)際內(nèi)容 —— 段落、表、列表、代碼樣例等。表 2 列出了向書(shū)、章節(jié)或文章中添加內(nèi)容時(shí)所使用的一些常見(jiàn)元素。
表 2. 元素
元素 說(shuō)明 caution 包含敬告讀者操作可能導(dǎo)致數(shù)據(jù)丟失、硬件損壞或軟件問(wèn)題的文本 code 包含內(nèi)聯(lián)代碼，例如 this example 包含帶有標(biāo)題的代碼示例 important 包含可能對(duì)讀者十分重要的文本 itemizedlist 具有可選的要點(diǎn)句（bullet point）的條目列表 note 包含提請(qǐng)讀者特別注意的文本 orderedlist 編號(hào)條目列表；您不必在構(gòu)建時(shí)為列表編號(hào) —— 樣式表將為您執(zhí)行該操作 para 文本段落或文本塊 table 文本表或數(shù)據(jù)表 tip 包含用于為讀者提供建議的文本 title 與元素相關(guān)的標(biāo)題
下面顯示的示例文檔中，其中的書(shū)至少包含了表 2 中列出的每個(gè)元素的其中一個(gè)。
清單 1. 基本 DocBook XML 示例
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
Liberal use of new in loops can cause performance issues!
String something = "Something";
當(dāng)文件生成為 HTML 并呈現(xiàn)到瀏覽器中后，它將類似圖 1：
圖 1. 轉(zhuǎn)換成 HTML 并在瀏覽器中呈現(xiàn)后的清單 1 代碼
完全介紹每個(gè)可用的 DocBook XML 標(biāo)記最好留給參考手冊(cè)來(lái)完成；指向這些參考手冊(cè)的 HTML 版本的鏈接可在 參考資料 中獲得。同樣可以找到有關(guān) DocBook XML 的書(shū)籍。表 2 中列出的標(biāo)記將給您提供一個(gè)良好的開(kāi)端，但是更多標(biāo)記可用于屏幕快照、命令提示符、用戶輸入、商標(biāo)和引號(hào)等。
設(shè)置環(huán)境
您必須使用工具來(lái)執(zhí)行可擴(kuò)展樣式表轉(zhuǎn)換語(yǔ)言（Extensible Stylesheet Transformation Language，XSLT）轉(zhuǎn)換，以及使用 XSL 樣式表把 DocBook XML 轉(zhuǎn)換為 HTML 或 PDF 等您認(rèn)為更有用的格式。如果您構(gòu)建了自己私有的 XML，則還必須編寫您自己的樣式表。但是，使用 DocBook XML 等已建立的格式將允許您使用其他人已經(jīng)編寫的樣式表。要使用預(yù)編寫的樣式表，請(qǐng)下載這些樣式表（請(qǐng)參閱 參考資料）。在撰寫本文時(shí)，適用于 DocBook XML V4.5 的一組樣式表是 DocBook XSL V1.72.0。
獲得樣式表
包含 DocBook XSL（例如，docbook-xsl-1.72.0.zip）的已下載的歸檔文件包括按照生成的輸出類型組織到不同目錄中的樣式表。html 目錄包括輸出 HTML 的樣式表；fo 目錄包括生成格式化對(duì)象（Formatting Object，F(xiàn)O）格式文件的樣式表，等等。
下載歸檔文件并將其保存到便于記憶的位置。不需要把文件從歸檔文件中解壓縮出來(lái) —— 您可以直接把它們導(dǎo)入 Eclipse。
使用 Xalan
在本文中，我使用 Xalan 作為 XSLT 處理器。在將 Xalan 與 Eclipse 附帶的 Ant 版本結(jié)合使用時(shí)會(huì)有一個(gè)問(wèn)題：版本太低并且在嘗試處理 XSL 時(shí)會(huì)遇到問(wèn)題。
Xalan 是可用作兩個(gè)子項(xiàng)目 Xalan C++ 和 Xalan-Java 的 Apache 項(xiàng)目。下載 Xalan-Java（如果計(jì)算機(jī)上還沒(méi)有）。下載完文件后，請(qǐng)將其保存到便于記憶的位置。像包含樣式表的歸檔文件一樣，仍然不要解壓縮文件的內(nèi)容。
創(chuàng)建 Eclipse 項(xiàng)目
到目前為止，您已經(jīng)看到了一些樣例文件，并且應(yīng)當(dāng)已經(jīng)下載了最新版本的 DocBook XSL 樣式表，以及最新版本的 Xalan（如果以前沒(méi)有的話）。您還應(yīng)當(dā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)當(dāng)被保存到便于查找的位置。
下載并保存了所有歸檔文件后，您已經(jīng)準(zhǔn)備好啟動(dòng) Eclipse 以創(chuàng)建新項(xiàng)目，并編輯把 DocBook XML 轉(zhuǎn)換為不同格式的 DocBook XML 和 Ant 腳本。
在 Eclipse 啟動(dòng)后，通過(guò)選擇 File > New > Project 創(chuàng)建新項(xiàng)目。在 General 下，單擊常見(jiàn)的 Project，然后單擊 Next。在鍵入項(xiàng)目的名稱之后，單擊 Finish，在工作區(qū)中創(chuàng)建新項(xiàng)目。
從歸檔中導(dǎo)入文件
既然已經(jīng)在 Eclipse 中創(chuàng)建了新項(xiàng)目，那么接下來(lái)導(dǎo)入構(gòu)建 DocBook XML 要使用的文件。
導(dǎo)入 DTD 文件
首先，導(dǎo)入 DocBook XML DTD 文件。選擇 File > Import，如下所示，然后，在 General 類別中，選擇 Archive File。當(dāng) Import Wizard 顯示時(shí)，單擊 Browse 以打開(kāi)可用于定位 DocBook XML DTD 歸檔文件（例如 docbook-xml-4.5.zip）的文件瀏覽器。
圖 2. 從歸檔文件導(dǎo)入
在 Into folder 框中的項(xiàng)目名稱后鍵入 /docbook-xml。確保選中 / 文件夾，如下所示。單擊 Select All（如果尚未選中或者如果已灰顯），則在完成時(shí)單擊 Finish。歸檔內(nèi)的文件將 入到項(xiàng)目中。
圖 3. 選擇要導(dǎo)入的文件
導(dǎo)入 XSL 樣式表
導(dǎo)入完 DocBook XML DTD 文件后，請(qǐng)遵循相同的過(guò)程導(dǎo)入 docbook-xsl-1.72.0.zip 文件的內(nèi)容。但是，這一次您無(wú)需在 Into folder 框中的項(xiàng)目名稱后指定文件夾名稱，因?yàn)闅w檔的內(nèi)容將已經(jīng)被放入項(xiàng)目?jī)?nèi)名為 docbook-xsl-1.72.0 的文件夾中。
既然已經(jīng)導(dǎo)入了 XSL 樣式表，接下來(lái)從在 Xalan Web 站點(diǎn)中下載的歸檔中導(dǎo)入所需的 Java Archive (JAR) 文件。導(dǎo)入其他歸檔文件時(shí)遵循同樣的過(guò)程，但是這一次，請(qǐng)確保清空 docs、licenses 和 samples 目錄，以便這些目錄不被導(dǎo)入到項(xiàng)目中。在您清空了那些目錄后，在 Into folder 框中添加 /lib，修改項(xiàng)目名稱。
在導(dǎo)入需要的所有文件后，請(qǐng)?jiān)陧?xiàng)目?jī)?nèi)創(chuàng)建另一個(gè)文件夾并將其命名為 src。這將是所有 DocBook XML 文件的基本文件夾。
到目前為止，應(yīng)當(dāng)在 Eclipse 中有一個(gè)包括以下文件夾的項(xiàng)目：
docbook-xml，包含 DocBook XML DTD
docbook-xsl-1.72.0，包含 DocBook XSL 樣式表
lib，包含 Xalan JAR 文件
src，現(xiàn)在為空
如果項(xiàng)目中有了所有這些文件夾，那么您已經(jīng)準(zhǔn)備好添加 Ant build.xml 文件以運(yùn)行轉(zhuǎn)換過(guò)程。
編寫 Ant 腳本
Ant 是基于 Java 的構(gòu)建工具，它將讀取 XML 腳本并且可以執(zhí)行腳本中定義的很多任務(wù)。如果您不熟悉 Ant，請(qǐng)參閱 參考資料。在本文中，您將使用 Eclipse 來(lái)啟動(dòng) Ant，因此無(wú)需熟悉如何從命令行運(yùn)行 Ant。此外，您也無(wú)需擔(dān)心自己如何下載和安裝 Ant，因?yàn)?Eclipse IDE V3.2.x 附帶了 Ant。它是比當(dāng)前可獲得的版本低的版本 —— V1.65，相對(duì)于 V1.7 —— 但是出于本文的目的，該版本不會(huì)造成問(wèn)題。
不過(guò)，Ant V1.6.5 附帶的 Xalan 版本在嘗試使用最新的 DocBook XSL 時(shí)看上去運(yùn)行得不太好。但是如果下載和使用最新版本的 Xalan（及附帶的 Xerces 版本），它應(yīng)當(dāng)可以正常運(yùn)行。
結(jié)合使用 Xalan 與 Ant
有很多種方法可以告訴 Ant 使用特定版本的 Xalan —— 或任何其他 XSLT 處理器 —— 而不使用 Ant 附帶的默認(rèn)版本。其中一種方法是修改 Ant 的類路徑。當(dāng)您在 Eclipse IDE 內(nèi)使用 Ant 時(shí)，這是十分簡(jiǎn)單的。選擇 Window > Preferences 以更改 Ant/CLASSPATH 下的設(shè)置。您可以在 CLASSPATH 選項(xiàng)卡中刪除對(duì) Xalan 或 Xerces 的任何引用，并將其替換為已經(jīng)下載的版本。
如果您是惟一要執(zhí)行轉(zhuǎn)換的人，則這個(gè)方法很好，因?yàn)橹挥心仨毟?Ant 設(shè)置才能正確進(jìn)行轉(zhuǎn)換。但是，如果要與團(tuán)隊(duì)協(xié)作，更好的方法是在目錄（例如，lib）中包含 Xalan 和 Xerces JAR 文件以及項(xiàng)目，并修改 build.xml 文件以使用 xslt 任務(wù)的庫(kù)。使用這種方法，您可以簡(jiǎn)單地將文件從源文件控件中簽出或者分發(fā)并運(yùn)行項(xiàng)目，而不更改 Eclipse IDE 設(shè)置。
下面的 Ant 構(gòu)建腳本中提供了為 xslt 任務(wù)提供 JAR 文件的示例。
清單 2. 樣例 Ant 腳本
This Ant build.xml file is used to transform. DocBook XML to various
粗體顯示的
xslt 目標(biāo)是與 basedir、extension 和 destdir 屬性結(jié)合設(shè)計(jì)，用于遞歸瀏覽文件夾并為在目錄中找到的每個(gè) XML 文件生成 HTML 文件。輸出將被存儲(chǔ)到一個(gè)文件夾中，稍后將用作后面演示的 Eclipse 插件附帶的幫助文件的 HTML 源文件。
創(chuàng)建 build.xml 文件
通過(guò)選擇 File > New >File 創(chuàng)建 build.xml 文件。鍵入 build.xml 作為文件名，然后選擇項(xiàng)目作為文件的位置。單擊 Finish 創(chuàng)建 Ant 文件。
您可以把 清單 2 中所示的內(nèi)容放入到新的構(gòu)建文件中。如果選用的任何目錄名稱與在這里使用的目錄名稱不同，則可能需要調(diào)整 property 元素中的一些值以確保正常運(yùn)行。
您可以直接從 Eclipse 執(zhí)行 build.xml 文件，因?yàn)?Eclipse 配有內(nèi)置掛鉤 (hook)，可以運(yùn)行 Ant 構(gòu)建腳本。使用 Ant 有很多其他優(yōu)點(diǎn)：首先，它是跨平臺(tái)的，這意味著您可以在運(yùn)行 Java 代碼的任何操作系統(tǒng)上執(zhí)行相同的構(gòu)建腳本。另一個(gè)優(yōu)點(diǎn)是可以不依賴于 IDE 運(yùn)行這個(gè)構(gòu)建腳本。因而，您可以輕松地將其整合到自動(dòng)執(zhí)行的構(gòu)建過(guò)程中，也可以從命令行執(zhí)行它。最初，我打算研究如何設(shè)定 Eclipse 屬性以將 XSLT 處理器作為外部工具運(yùn)行（參見(jiàn) Run > External Tools），但是我為了獲得這些優(yōu)點(diǎn)而放棄了那個(gè)想法。
運(yùn)行 build-html 目標(biāo)
在編寫了 build.xml 文件之后，您可以運(yùn)行 build-html 目標(biāo)。您沒(méi)有任何 DocBook XML 文件，因此目標(biāo)將不會(huì)做任何有用的操作。但是，運(yùn)行腳本時(shí)不應(yīng)當(dāng)會(huì)得到任何錯(cuò)誤。
運(yùn)行 Ant 目標(biāo)的最簡(jiǎn)單方法之一是在編輯器中打開(kāi)構(gòu)建文件的情況下從 Outline 視圖運(yùn)行 Ant 目標(biāo)。在 Outline 視圖內(nèi)，右擊 build-html 目標(biāo)的名稱，然后選擇 Run As > Ant Build。來(lái)自 Ant 構(gòu)建腳本的消息（如果有）將顯示在 Console 視圖中。
編寫 DocBook XML 文件
在 Eclipse 項(xiàng)目中，應(yīng)當(dāng)有 DocBook XML DTD 文件、DocBook XSL 文件、Xalan 庫(kù)，而且現(xiàn)在還有 build.xml 文件。此時(shí)，您擁有了開(kāi)始構(gòu)建 DocBook XML 文件所需的一切內(nèi)容。
創(chuàng)建第一個(gè) DocBook XML 文件
要在 Eclipse 中創(chuàng)建第一個(gè) DocBook XML 文件，請(qǐng)執(zhí)行以下步驟：
選擇 File > New > Other，
電腦資料
《在Eclipse中構(gòu)建DocBook XML》(http://www.oriental01.com)。從 XML 類別中，選擇 XML，然后單擊 Next。
在 Create XML File 窗口中，選擇 Create XML file from a DTD file，然后單擊 Next。
在 File name 框中鍵入 chapter1.xml，然后確保項(xiàng)目?jī)?nèi)的 src 文件夾已被選中，然后單擊 Next。
在 Select DTD File 中，瀏覽到項(xiàng)目的 docbook-xml 文件夾中的 docbookx.dtd 文件，然后單擊 Next。
當(dāng) Select Root Element 窗口顯示時(shí)，請(qǐng)從 Root element 中選擇 chapter，然后取消選中 Create first choice of required choice 復(fù)選框。
鍵入 -//OASIS//DTD DocBook XML V4.5//EN，然后單擊 Finish。
在 XML 編輯器中使用 chapter1.xml
Eclipse 將在 XML 編輯器中打開(kāi) chapter1.xml。Eclipse 中的 XML 編輯器有兩個(gè)文件視圖：Design 和 Source。XML 文件的 Design 視圖將以網(wǎng)格的形式顯示文件的元素，其中，元素名稱顯示在左側(cè)列中，元素的內(nèi)容顯示在右側(cè)列中。您可以通過(guò)右鍵單擊文件并選擇 Add Child、Add After 或 Add Before 把新元素添加到文件中。
如果使用的是 DTD，則上下文菜單中的菜單項(xiàng)將限定您只能添加有效的元素。此功能使您可以確保在稍后執(zhí)行轉(zhuǎn)換時(shí) XML 文件中不會(huì)有大量驗(yàn)證錯(cuò)誤。
構(gòu)建模塊化文檔
創(chuàng)建許多文檔時(shí)，文檔之間一定會(huì)有類似之處，尤其是在它們?nèi)济嫦蛳嗤x者的情況下，例如大型企業(yè)或一群人。例如，如果您讀過(guò)很多技術(shù)書(shū)籍，您就可能已經(jīng)注意到幾乎每本技術(shù)書(shū)籍都有 “本書(shū)中使用的約定” 部分或用于演示書(shū)中如何設(shè)定線索、提示、內(nèi)嵌代碼和代碼清單格式的章節(jié)。
分割 DocBook XML 文件
使用 DocBook XML 使您能夠?qū)⑽臋n分割為多個(gè)文件，這些文件可以編譯成一個(gè)單元并能夠重用。例如，您可以將書(shū)中的每一個(gè)章節(jié)放入單獨(dú)的 XML 文檔中。然后可以在其他書(shū)中使用這些章節(jié)，或者簡(jiǎn)單地將章節(jié)分割為獨(dú)立的文件以實(shí)現(xiàn)更輕松地維護(hù)。您還可以將這些章節(jié)包括到書(shū)并使用樣式表處理它們。
清單 3 提供了構(gòu)建動(dòng)態(tài)包含其他 DocBook XML 文件的 DocBook XML 文檔的示例。在轉(zhuǎn)換過(guò)程中處理此文件時(shí)，該文件看上去 —— 這里是指 chapter1.xml —— 就是 &chap1; 所在的位置。
清單 3. 包含 chapter1.xml 的樣例 book.xml 文件
"../docbook-xml/docbookx.dtd" [
]>
&chap1;
采取這種方法時(shí)有幾點(diǎn)注意事項(xiàng)。首先，必須修改 chapter1.xml 文件以刪除 XML 預(yù)處理指令和 DOCTYPE 元素。由于 chapter1.xml 的內(nèi)容將被放到 &chap1 實(shí)體所在的位置，因此 book.xml 文件的中間將包含 XML 處理指令和 DOCTYPE 元素，會(huì)使該文件無(wú)效。
其次，如果不再需要將單獨(dú)的章節(jié)文件處理成單獨(dú)的 HTML 文件，則應(yīng)當(dāng)更新 Ant 構(gòu)建腳本以避免對(duì)章節(jié)文件進(jìn)行處理。幸運(yùn)的是，使用 Ant 中的 xslt 任務(wù)，這項(xiàng)更改非常簡(jiǎn)單。xslt 任務(wù)可以包含與 Ant 中的 fileset 元素相同的元素，這意味著您可以構(gòu)建一系列可以非常輕松地包含和清除文件。清單 4 顯示了如何使用
清單 4. 使用 XSLT 任務(wù)包含和清除文件
如果仍需要構(gòu)建全部文檔，可以刪除上面所示的 exclude 元素。
不僅限于分割章節(jié)和書(shū)。只要是對(duì)您有意義，就可以以任何方法物理分割 DocBook XML 文件，例如將各部分單獨(dú)保存在文件中。您甚至可以把書(shū)包含在 set 元素中，該元素是最高級(jí)別的 DocBook 元素。
構(gòu)建幫助插件
Eclipse 框架功能強(qiáng)大的特性之一是可擴(kuò)展性。當(dāng)我看到企業(yè)使用特殊的 “企業(yè)允許的” 方法連接至數(shù)據(jù)庫(kù)、事務(wù)處理或錯(cuò)誤處理時(shí)，我總是想知道企業(yè)為什么讓開(kāi)發(fā)人員到工作環(huán)境外部去查找并獲取文檔。為什么不構(gòu)建可在公司內(nèi)部網(wǎng)中獲得的相同 HTML 文檔并以能夠通過(guò) IDE、索引和搜索輕松地訪問(wèn)到的幫助形式將其分發(fā)給開(kāi)發(fā)人員？
您可以使用 Eclipse IDE 附帶的模板快速創(chuàng)建包含 HTML 文件格式的幫助的插件項(xiàng)目。下幾個(gè)部分將演示如何構(gòu)建這個(gè)插件項(xiàng)目。構(gòu)建插件項(xiàng)目后，您可以包括在 DocBook XML 項(xiàng)目中構(gòu)建的 HTML 文件。
創(chuàng)建幫助插件
要?jiǎng)?chuàng)建幫助插件，請(qǐng)執(zhí)行以下步驟：
選擇 File > New > Project 以啟動(dòng) 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。
在下一個(gè)窗口中，單擊 Finish。系統(tǒng)可能提示您切換到 Plug-in Development 透視圖。如果提示，建議單擊 Yes，因?yàn)橥敢晥D將自動(dòng)包括在構(gòu)建幫助時(shí)對(duì)您有用的視圖。
新項(xiàng)目包含名為 html 的文件夾，并且在該文件夾中包含一些樣例 HTML 文件。將用 DocBook 項(xiàng)目中生成的 HTML 文件替換這些文件。
查看進(jìn)度
在尚未進(jìn)行任何更改的情況下，選擇 Run > Run As > Eclipse Application，將插件與 Eclipse 的實(shí)例結(jié)合運(yùn)行以查看到目前為止幫助的內(nèi)容。使用您的插件，Eclipse 的新實(shí)例將啟動(dòng)。在 Eclipse 啟動(dòng)后，選擇 Help > Help Contents 以查看運(yùn)行中的插件。如果沒(méi)有做任何更改，則將看到 Test TOC 列于內(nèi)容之中，如圖 5 所示：
圖 5. 內(nèi)容樣例表
整合 DocBook XML 項(xiàng)目中的 HTML
現(xiàn)在您已經(jīng)看到了新幫助插件的默認(rèn)內(nèi)容，接下來(lái)該整合先前構(gòu)建的 DocBook XML 項(xiàng)目中的 HTML 了。因此需要復(fù)制新幫助插件項(xiàng)目的 HTML 輸出，但是您不希望每次都手動(dòng)執(zhí)行該操作。如果進(jìn)行手動(dòng)操作，則在構(gòu)建插件的過(guò)程中很可能犯下錯(cuò)誤或忘記執(zhí)行該操作。
添加 Ant 文件
自動(dòng)復(fù)制 HTML 文件的第一步是構(gòu)建一個(gè)簡(jiǎn)單的 Ant 文件。這個(gè) Ant 文件只將來(lái)自 DocBook XML 項(xiàng)目的 HTML 文件復(fù)制到插件項(xiàng)目的 html 文件夾中。然后，只要 Eclipse 構(gòu)建項(xiàng)目，就會(huì)執(zhí)行該 Ant 文件。
Ant 文件的內(nèi)容如下所示。文件只有一個(gè)目標(biāo) —— prepare —— 它也是構(gòu)建文件的默認(rèn)目標(biāo)。由于此構(gòu)建文件實(shí)際上只適于被 Eclipse 調(diào)用，因此我把默認(rèn)目標(biāo)保留為 prepare。
清單 5. 插件項(xiàng)目中的 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)建項(xiàng)目時(shí)運(yùn)行的程序。這些程序被稱為構(gòu)建器。您可以通過(guò)單擊項(xiàng)目名稱，然后選擇 Project > Properties 來(lái)修改構(gòu)建器。在 Builders 下方，您將看到已經(jīng)為項(xiàng)目設(shè)置的構(gòu)建器：Java Builder、Plug-in Manifest Builder 和 Extension Point Schema Builder。要讓 Eclipse 運(yùn)行 Ant 腳本把 HTML 文件復(fù)制到插件項(xiàng)目中，請(qǐng)執(zhí)行以下步驟：
在 Builders 屬性頁(yè)面中單擊 New。
從列表中選擇 Ant Build，然后單擊 OK。
鍵入新構(gòu)建器的名稱，例如 Ant Builder。
在 Buildfile 下，單擊 Browser Workspace 定位工作區(qū)內(nèi)的 Ant 文件。
單擊 Targets 選項(xiàng)卡，并確保 After a "Clean" 和 Manual Build 目標(biāo)顯示
單擊 OK 保存構(gòu)建器。
在 Builders 頁(yè)面中，選擇剛創(chuàng)建的新 Ant 構(gòu)建器，然后單擊 Up，直至您的構(gòu)建器在列表中位于第一位。您必須這樣做，因?yàn)樾枰盐募䦶?fù)制到插件項(xiàng)目中，然后才能執(zhí)行其他操作。
設(shè)置了新構(gòu)建器后，您可以選擇 Project > Clean 或 Project > Build 清除或構(gòu)建項(xiàng)目。Ant 構(gòu)建器將運(yùn)行并自動(dòng)從 DocBook XML 項(xiàng)目中拖出 HTML 文件。
添加構(gòu)建器也適于 DocBook XML 項(xiàng)目。您可以將 Ant 構(gòu)建器添加到 DocBook XML 項(xiàng)目中，把任意一個(gè)目標(biāo)設(shè)為清除或構(gòu)建項(xiàng)目時(shí)執(zhí)行的目標(biāo)（記住，對(duì)于這些目標(biāo)，usage 目標(biāo)是默認(rèn)值）。
幫助 TOC 文件
HTML 幫助文件的目錄 (TOC) 表位于插件項(xiàng)目包括的兩個(gè) XML 文件中。文件如下所示：
清單 6. TestTOC.xml
清單 6 中所示的 testTOC.xml 文件包含顯示在幫助窗口的 Contents 窗格中的標(biāo)題名稱。它只是用于鏈接到 toc.xml 文件。
清單 7. Toc.xml
toc.xml 文件包含顯示在主標(biāo)題下方的主要標(biāo)題。這些主要標(biāo)題都是用 href 屬性鏈接到 HTML 頁(yè)面，在清單 7 中用粗體顯示：
您可以將幫助作為一個(gè)整體文件來(lái)構(gòu)建，像書(shū)一樣，并且只有一個(gè)指向該文件的主要標(biāo)題。但是，請(qǐng)考慮把文檔分割為可以在 toc.xml 文件中通過(guò)索引找到的獨(dú)立章節(jié)，而且根據(jù)需要構(gòu)建為單獨(dú)的書(shū)。有關(guān)如何把文檔分割為可以組織的各種物理文件的提示，請(qǐng)參閱 “Building modular documentation”。
自定義 DocBook 輸出
到目前為止，DocBook XML 已經(jīng)轉(zhuǎn)換為在 Eclipse 插件內(nèi)用作幫助的常規(guī) HTML。但是如果需要整理轉(zhuǎn)換后輸出的 HTML 的外觀該怎么辦？
幸運(yùn)的是，您不必只為了向 HTML 添加一點(diǎn)個(gè)性化或自定義格式而編寫自己的 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 類的簡(jiǎn)單 CSS。該 CSS 修改了這些類中文本的顏色。您將看到在顯示頁(yè)面時(shí)，這些類分別對(duì)應(yīng)
清單 8. 簡(jiǎn)單的 CSS 文件
body { font-family : arial,sans-serif; font-size : small; }
.important { color : blue; }
.caution { color : red; }
修改 Ant 構(gòu)建文件
將清單 8 中所示的 CSS 保存到 DocBook XML 項(xiàng)目的 lib 目錄中名為 style.css 的文件中。保存完文件后，必須修改 Ant 構(gòu)建文件把 CSS 文件的名稱傳遞到 xslt 目標(biāo)中，然后將 CSS 文件從 lib 文件夾復(fù)制到與其余 HTML 輸出相同的文件夾中。清單 9 用粗體顯示了這些更改。
清單 9. 經(jīng)過(guò)修改后的 Ant 腳本
在做出更改后，您可以重新運(yùn)行 DocBook XML 項(xiàng)目中的 Ant 構(gòu)建腳本。這一次，當(dāng)您查看輸出的 HTML 文件時(shí)，您將看到更改后的字體和 “Important” 和 “Caution” 部分的新字體顏色。
創(chuàng)建 PDF
至此，您已經(jīng)使用了各種工具從 DocBook XML 生成可以分布到內(nèi)部網(wǎng)站和包含在 Eclipse 幫助插件中的 HTML。但是，我在前面提到過(guò)，使用相同的 DocBook XML 源文件，還可以生成 PDF。從 DocBook XML 生成 PDF 要求使用一個(gè)額外的工具：來(lái)自 Apache XML Graphics Project 的 FOP 庫(kù)（請(qǐng)參閱 參考資料）。
FOP 庫(kù)中有一個(gè)可以直接放入 DocBook XML 項(xiàng)目現(xiàn)有 Ant 構(gòu)建文件中的 Ant 任務(wù)。該 Ant 任務(wù) fop 將轉(zhuǎn)換 FO 文件，這些 FO 文件都是使用 DocBook XSL 附帶的 FO 樣式表構(gòu)建的。
使用 FOP 庫(kù)生成 PDF
要使用 FOP 庫(kù)，請(qǐng)從 Web 站點(diǎn)中下載包含二進(jìn)制版本的 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é)合使用。像已下載的其他歸檔文件一樣，您仍無(wú)需解壓縮此文件。
在 Eclipse 中，選擇 File > Import，然后執(zhí)行在 “從歸檔導(dǎo)入文件” 中使用的相同過(guò)程。但是，這一次，只選擇 build 和 lib 文件夾執(zhí)行導(dǎo)入。
導(dǎo)入完文件后，修改 Ant 構(gòu)建腳本以設(shè)置 fop 目標(biāo)并在新的 build-pdf 目標(biāo)中調(diào)用它，如下所示：
清單 10. build-pdf 目標(biāo)
>
>
>
設(shè)置了此目標(biāo)之后，從 Eclipse IDE 運(yùn)行 build-pdf 目標(biāo)。這一次，在 dist 目錄中，將出現(xiàn)名為 book.pdf 的文件。
結(jié)束語(yǔ)
DocBook XML 是一種功能強(qiáng)大的格式，可用于構(gòu)建可以生成各種不同輸出格式（例如 HTML 和 PDF）的技術(shù)文檔。該格式使您可以專注于文檔的內(nèi)容，將樣式問(wèn)題分離。由于它十分成熟，因此很多工具可用于編輯和構(gòu)建 DocBook XML 格式的文檔。
Eclipse IDE 附帶了用于編寫和驗(yàn)證 XML 文檔的編輯器。Eclipse 還集成了 Ant，使您可以創(chuàng)建能夠作為 Eclipse 中的常規(guī)構(gòu)建器來(lái)執(zhí)行的強(qiáng)大構(gòu)建文件。此外，Eclipse 附帶的模板使您可以快速構(gòu)建插件項(xiàng)目，其中一些插件項(xiàng)目包含可在 Eclipse 中用作幫助的 HTML 文件。
所有這些工具結(jié)合使用可以讓您在一個(gè)地點(diǎn)編寫技術(shù)文檔，然后將該技術(shù)文檔以不同格式分發(fā)給各種讀者。