當您訪問 Eclipse 幫助系統時（通過 Help > Help Contents），您實際上啟動了一個嵌入式的 Apache Tomcat 服務器。然後打開了一個基於 Web 浏覽器的窗口，定位到服務器上適當的頁（見圖 1）。文檔同時在左側提供了一個可折疊的索引，右側是 HTML 文檔，隨時可以進行搜索（幸好有 Apach Lucene 搜索引擎）。由於使用了 Tomcate，您不只可以用 HTML；例如，您可以用 JSP 來使您的文檔能動態改變（可是我們稍後將會討論避免這樣做的可能原因之一）。
圖 1. Eclipse 幫助示例
文檔插件的“Hello World”
文檔被拆分為“書”，只要您願意，在幫助系統的一個實例中可以有任意多的書。每本書都編寫為一個 Eclipse 插件，不過好在這一步要做的工作很少。為編寫一個示例插件，您將需要一個 plugin.xml 文件來描述您的插件，其內容類似於清單 1。
清單 1. 插件定義
<plugin name="Sample Documentation Plug-in" id="com.ibm.sample.doc"
version="1.0.0" provider-name="IBM">
<extension point="org.eclipse.help.toc">
<toc file="toc.xml" primary="true" />
</extension>
</plugin>
根據您的項目，將插件的 name 、id 、version 和 provider-name 修改為適當的值。擴展點 org.eclipse.help.toc 將此標識為幫助系統的一個插件。toc.xml 文件被引用進來，作為這個插件的目錄；這個文件將為 Eclipse 幫助窗口左側窗格中的分級信息提供數據。清單 2 是一個包含有類似內容的示例文件。
清單 2. 目錄定義
<toc label="Sample Documentation">
<topic label="My Section" href="mySection.html">
<topic label="Foo" href="foo.html"/>
<topic label="Bar" href="bar.html"/>
</topic>
</toc>
包裝插件
在最終的文檔中，每一個主題元素都表現為導航列表中的一個條目。這些主題可以嵌套（它們可以包含更多的主題），每一個指向一個 HTML 或者 JSP 文件。當您完成了這一步，所有您需要做的就是包裝如圖 2 所示的結構中的所有內容（注意，插件目錄名與在 plugin.xml 中定義的插件屬性 id 和 version 相匹配）。
圖 2. 插件目錄結構
為了方便，也為了壓縮文件的大小，Eclipse 允許您將實際的文件（HTML 文件）存放在一個名為 doc.zip 的 ZIP 文件中，所以您可以使用圖 3 所示的目錄結構。
圖 3. 另一種插件目錄結構
查看文檔
測試您的插件的最簡單方法就是，將整個目錄（像上面的一樣）拖入到已經安裝 Eclipse 平台的插件目錄下，然後啟動 Eclipse 並選擇 Help > Help Contents。您將得到一個添加了您的插件的幫助窗口（類似於 圖 1中那個）。
使用 IDE 來進行測試當然是好的，但是為了在沒有 IDE 時也可以使用，文檔需要更加易用，所以我們真正希望的是要後台運行一個進程，讓我們可以在浏覽器中連接它。這種方式的操作被稱為 InfoCenter（見圖 4）。啟動 InfoCenter 進程（基本上是 Apache Tomcat）的指令包含在 Eclipse 幫助系統文檔中。注意，還有一些指令用來簡化 Eclipse 系統，以便剛好滿足您的需要。
圖 4. 運行的 InfoCenter
處理龐大的目錄
如果您的項目有多人參與工作，或者有大量的文檔，那麼更新單個目錄文件 (toc.xml) 會變得不切實際。為改變這一狀況您可以向主 toc.xml 文件中的主題添加一個 link 元素（見清單 3 的示例）。
清單 3. 目錄定義
<toc label="Sample Documentation">
<topic label="My Section" href="mySection.html">
<topic label="Foo" href="foo.html"/>
<topic label="Bar" href="bar.html">
<link toc="bar-toc.xml" />
</topic>
</topic>
</toc>
bar-toc.xml 文件正是另一個目錄，格式應該和任何其他的 toc.xml 文件完全相同。當文檔被浏覽時，使用這種方法和簡單地直接包含另外的 topic 元素沒什麼不同。
生成獨立的文檔集
當然，如果您不介意需要發布 20 MB 額外的代碼，使用 Eclipse 幫助系統當然好，但是這對小些的項目來說是不現實的。在中心服務器上安裝一個 InfoCenter，讓人們可以遠程訪問。人們可以充分利用 Eclipse 幫助系統的所有功能（比如搜索），但是那些不能連接的人還是束手無策。所以，除了使用在主機上的 InfoCenter 以外，有必要將普通的 HTML 包含在一個可下載的包中。只要您沒有使用任何服務器端技術，比如 JSP，那麼您可以方便地生成一個 HTML 目錄來取代 Eclipse 所用的 XML 目錄。這就是為什麼我們要用 XSLT。
XSLT (eXtensible Stylesheet Language Transformations) 是一種將 XML 格式轉化為其他格式的技術，例如 XHTML（一個更為嚴格的 XML 版本的 HTML）。XSLT 提供了豐富而強大的語言來完成轉換，其本身就是很多書和文章的主題，所以我們在這裡不再細述。清單 4 給出了一個 toc.xml 文件簡單轉換的例子，將條目呈現為嵌套的 HTML 列表。注意，這個特定的轉換為全部文檔集的內容創建了一個單獨的 HTML 文件，文件量較大時這可能不實用。所以，如果您已經將您的目錄拆分為多個文件，這個 XSLT 將失效。
清單 4. 生成 HTML 目錄的示例 XSLT
<?xml version="1.0"?>
<xsl:stylesheet
version="1.1"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="html" indent="no" encoding="ISO-8859-1" />
<xsl:template match="toc">
<html>
<head />
<body>
<h1><xsl:value-of select="@label" /></h1>
<ul>
<xsl:apply-templates />
</ul>
</body>
</html>
</xsl:template>
<xsl:template match="topic">
<li>
<xsl:choose>
<xsl:when test="@href">
<!-- Only add a hyperlink when there is something to link to ->
<xsl:element name="a">
<xsl:attribute name="href">
<xsl:value-of select="@href" />
</xsl:attribute>
<xsl:value-of select="@label" />
</xsl:element>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="@label" />
</xsl:otherwise>
</xsl:choose>
<!-- If there are any nested topics, then start a new sub-list ->
<xsl:if test="descendant::topic">
<ul>
<xsl:apply-templates/>
</ul>
</xsl:if>
</li>
</xsl:template>
</xsl:stylesheet>
通過一個 XSLT 處理器，比如 Apache Xalan，使用前面的 XSLT 來處理 toc.xml 文件，生成一個在浏覽器中查看時如圖 5 所示的 HTML 文件：
圖 5. 生成的 index.html
結束語
使用 Eclipse 幫助系統可以輕松開發出令您的朋友和同事大為驚奇的、具有專業外觀的並且可搜索的文檔。如果您不需要獨立的文檔集，那麼您甚至不需要理會 XSLT；您只需要編寫兩個簡單的 XML 文件就可以愉快地享用文檔了。開始吧。
