使用 Eclipse 幫助系統爲項目編制文檔

構建易於使用且可搜索的幫助文檔

級別:入門

Arthur Barr
軟件工程師,IBM
2004 年 3 月

具有非常強大的 IDE 的 Eclipse 平臺中有其自己的幫助系統,這個系統基於一個引用 HTML 文件的 XML 目錄表。鮮爲人知的是,您不必去編寫 Eclipse 插件就可以使用它。任何項目都可以使用一個簡化版的平臺來提供專業的、易用的和可搜索的文檔。這個文檔系統已經成功地應用於許多 IBM 項目,包括像 WebSphere Application Server 那樣大的項目。

當您訪問 Eclipse 幫助系統時(通過 Help > Help Contents),您實際上啓動了一個嵌入式的 Apache Tomcat 服務器。然後打開了一個基於 Web 瀏覽器的窗口,定位到服務器上適當的頁(見圖 1)。文檔同時在左側提供了一個可摺疊的索引,右側是 HTML 文檔,隨時可以進行搜索(幸好有 Apach Lucene 搜索引擎)。由於使用了 Tomcate,您不只可以用 HTML;例如,您可以用 JSP 來使您的文檔能動態改變 (可是我們稍後將會討論避免這樣做的可能原因之一)。

圖 1. Eclipse 幫助示例
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>

根據您的項目,將插件的nameidversionprovider-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
運行的 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
生成的 index.html

結束語
使用 Eclipse 幫助系統可以輕鬆開發出令您的朋友和同事大爲驚奇的、具有專業外觀的並且可搜索的文檔。如果您不需要獨立的文檔集,那麼您甚至不需要理會 XSLT;您只需要編寫兩個簡單的 XML 文件就可以愉快地享用文檔了。開始吧。

參考資料

 

關於作者
Arthur Barr 是英國 IBM Hursley 開發實驗室的一名軟件工程師。他已經將本文的心得應用到 Business Integration for Games 項目中,這應該是他當前正在致力的項目。可以通過 arthur.barr at uk.ibm.com 與 Arthur 聯繫。
發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章