本文描述了如何完成移植過程中轉換工具所不能自動完成的任務：將 Eclipse TOC 文件轉換為 DITA 映射文件。這裡並沒有討論將 HTML 文件轉換為 DITA 格式的原因，OASIS DITA Web 站點上的其他 developerWorks 文章和參考資料將會解釋其優勢。本文比較了兩個基於 XML 的導航文件中的元素，然後使用示例主 TOC 文件和次 TOC 文件演示到 DITA 的轉換。還為使用 XSLT 樣式表對 Eclipse TOC 文件進行轉換提供了指導。
填補當前工具的空白
如果需要將 Eclipse 幫助插件轉換為 DITA，您可以找到將 HTML 文件轉換為 XHTML 和將 XHTML 轉換為 DITA 的工具。雖然 Eclipse 幫助插件中的大多數文件通常是 HTML，但 Eclipse TOC 文件仍花費了大量的設計與開發時間。基於 TOC 文件存在幾個要素：信息結構、搜索數據庫目錄和關鍵主題的可見性。如果您已經對 TOC 文件投入了大量精力並且文件工作得如您所願，您決不會冒險用手動方法將文件轉換為 DITA 映射文件 —— 除非幸運地找到處理該任務的轉換工具。在我沒有找到這樣的工具之後，我決定自己編寫 XSLT 樣式表來轉換文件。
對比 Eclipse TOC 與 DITA 映射
Eclipse TOC 文件和 DITA 映射文件都是用來為一組主題描述導航的 XML 文件。您會發現兩種類型文件間的相似點與不同點。對於 Eclipse TOC 文件中的每一個合法元素或屬性，表 1 列出了 DITA 映射文件中的相應元素。每一個 TOC 元素的屬性列在該元素後面。
表 1. Eclipse TOC 元素與 DITA 映射元素的逐個比較
TOC 元素或屬性 映射元素或屬性 注釋 <toc> <map> 它們是文檔的根元素 link_to anchorref 這些屬性指向另一個主題層次結構中的插入點（TOC 或 DITA 映射文件）。該主題層次結構與另一個主題層次結構在插入點整合。這也稱為自下而上的整合。 label title label 屬性是 <toc> 元素所必需的。 topic <topicref> DITA 映射中的第一個 <topicref> 元素用來保存 Eclipse TOC 文件中 <toc> 元素的 topic 屬性。topic 屬性的值用來設置 <topicref> 的 href 屬性值。<topicref> 元素的 print 和 toc 屬性被設置為 "no"。 <topic> <topicref> 如果<topic>元素沒有 href 屬性，那麼您可以將 <topic> 元素轉換為 <topichead> 元素。 label navtitle label 屬性是 <topic> 元素所必需的。 href href <topic> 元素的 href 屬性值用來設置 <topicref> 元素的 href 屬性值。 <anchor> <anchor> 這些元素定義了其他主題層次結構可以連接（<toc> 元素的 link_to 屬性）或參考（<map> 元素的 anchorref 屬性）的插入點。 id id id 屬性是 <anchor> 元素所必需的。 <link> <navref> 這些元素指向另一個主題層次結構。另一個主題層次結構在該插入點與此主題層次結構整合。這也稱為自上而下的整合。 toc mapref toc 屬性是 <topic> 元素所必需的。
從這張表中，您可以看到一些元素是一樣的（例如 <anchor>）或者是非常相似的。這些相似點使得我很容易創建 XSLT 樣式表將 TOC 文件轉換為 DITA 映射文件。
本文的其余部分描述了一組示例 TOC 文件到 DITA 映射文件的轉換。如果閱讀時您想更仔細地檢查這些示例文件，請下載並解壓檔案文件 x-ecldita-toc2dita.zip 的根目錄中的文件。
下載的檔案文件中包括 TOC文件、相應的 DITA 映射文件和 XSLT 樣式表（用來轉換 TOC 文件）。您可以使用 Web 浏覽器、XML 編輯器或文本編輯器查看 TOC 文件。為查看 DITA 映射文件（擴展名為 .ditamap），需要使用 IBM ID Workbench 。
x-ecldita-toc2dita.zip 文件中的 plugins.zip 文件包含來自根目錄的 Eclipse TOC 文件，這些 Eclipse TOC 文件被打包到可以安裝在 Eclipse 幫助服務器上的兩個 Eclipse 插件中。
轉換主 TOC 文件
大多數情況下，基於 Eclipse 幫助系統的導航由多個通過中心主 TOC 文件整合的 TOC 文件組成。主文件可以包含以下類型元素的任意組合：
主題（通過 <topic> 元素指定）。
到其他已存在的 TOC 文件的連接（自上而下的整合）。
將來用於擴展主 TOC 的錨（自下而上的整合）。
盡管 Eclipse 幫助系統不需要主 TOC 文件，但是當多個內容提供商必須一起開發同一個幫助系統時使用 TOC 文件是非常方便的。當幫助系統的各個部分（比如通過安裝特性而升級的基本產品）是分次安裝的時，TOC 文件也是必要的。如果有必要將基本幫助系統與特性幫助內容整合，那麼主 TOC 文件是必要的。
下載的檔案文件中，主 TOC 文件是 mastertoc.xml。圖 1 展示了 mastertoc.xml 文件，它旁邊是一個屏幕快照，顯示了整合的 TOC 文件是如何呈現在 Eclipse 幫助浏覽器中的。主 TOC 文件：
將根集合標記為“Administration Central”並指定一個在用戶點擊根集合時顯示的目錄文件。
連接到子集合（toca.xml）。
提供一個錨用於將來擴展主 TOC 文件。
包含一個提醒用戶的主題。
圖1. mastertoc.xml 的 TOC 部分
當使用 XSLT 樣式表（x-ecldita-toc2dita.zip 文件中的 toc2dita_adv.xsl）將主 TOC 文件轉換為 DITA 映射文件時，輸出文件類似於 清單 1。
清單 1. 轉換後的 mastertoc.xml 文件（mastertoc.ditamap）
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//IBM//DTD DITA Map//EN" "..\dtd\map.dtd">
<map title="Administration Central">
<topicref navtitle="Administration Central"
href="admin_central.dita" print="no" toc="no"/>
<topicref navtitle="Console Basics" href="console_basics.dita">
<navref mapref="toca.ditamap"/>
</topicref>
<anchor id="anchor_id"/>
<topicref navtitle="Notices" href="reference/notices.dita"/>
</map>
雖然示例主 TOC 是簡單的，但更復雜的主 TOC 文件也只是示例文件中基本元素的多次重復。XSLT 樣式表可以處理復雜 TOC 文件和那些引用除 HTML 之外的其他文件類型的 TOC 文件。最新的 Eclipse 技術支持顯示是 JavaServer Page 的源文件。所以 XSLT 樣式表可以處理.jsp、.pdf、 .gif、.htm 和 .html 擴展名的文件。
轉換子 TOC 文件
本節主要關注兩個示例子 TOC 文件：主 TOC 文件連接到的子 TOC 文件和主 TOC 文件中錨指向的子 TOC 文件。在檔案文件中，子 TOC 文件是 toca.xml 和 tocb.xml。
toca.xml 文件通過明確引用 toca.xml 的 <link> 元素而與主 TOC 文件整合在一起，並為集合（Console Basics）分配一個標簽，然後指定一個在用戶點擊集合標簽時顯示的主題文件。不需要將集合與主題文件關聯。在這種情況下，沒有指定 href 屬性。因為連接涉及關於子 TOC 的特定信息，所以只有在 TOC 文件已經存在，或者開發人員相信在安裝主 TOC 文件的 Eclipse 插件時會存在 TOC 文件的情況下，才可能完成這一類型的連接。圖 2 右邊顯示了 toca.xml 文件的內容，左邊顯示了內容在 Eclipse 幫助浏覽器中是如何顯示的視圖。
圖 2. toca.xml 中的 TOC 部分
與 toca.xml 比較，tocb.xml 文件通過 <anchor> 而與主 TOC 整合在一起。如果主 TOC 設計者預計未來需要與另一個 TOC 文件整合，開發人員可以在主 TOC 中希望的位置插入錨。未來的 TOC 文件將指向那個錨。雖然允許多個錨，但安裝中只有一個 TOC 可以指向具體的錨。tocb.xml 文件中，<toc> 元素的 link_to 屬性指向 主 TOC 文件中的錨。圖 3 右邊展示了 tocb.xml 文件的內容，左邊顯示了內容在 Eclipse 幫助浏覽器中是如何顯示的視圖。
圖 3. tocb.xml 中的 TOC 部分
注意，link_to 屬性的值是主 TOC 文件的相對 URL 加上數字符號（＃）和 <anchor> 元素的 id 屬性的值。因為 tocb.xml 文件和 mastertoc.xml 文件在兩個單獨的 Eclipse 插件中，所以相對 URL 包含主 TOC 的插件名稱。圖 4 和 圖 5 展示了兩個插件的目錄：com.mycompany.plugin.doc （其中包含 mastertoc.xml 和 toca.xml）和 com.mycompany.plugin.adv.doc（其中包含 tocb.xml）。
圖 4. com.mycompany.plugin.doc 目錄
圖 5. com.mycompany.plugin.adv.doc 目錄
當使用 x-ecldita-toc2dita.zip 文件中的 XSLT 樣式表將 tocb.xml 轉換為 DITA 映射文件時，輸出文件類似於 清單 2。注意，TOC 文件中的 link_to 屬性轉換為映射文件中的 anchorref 屬性。
清單 2. 轉換後的 tocb.xml 文件（tocb.ditamap）
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//IBM//DTD DITA Map//EN" "..\dtd\map.dtd">
<map title="Advanced"
anchorref="../com.mycompany.plugin.doc/mastertoc.ditamap#anchor_id">
<topicref navtitle="Advanced topics" href="advanced.dita">
<topicref navtitle="Adding resources" href="tasks/adding_res.dita"/>
<topicref navtitle="Removing resources" href="tasks/removing_res.dita"/>
</topicref>
</map>
轉換 TOC 文件
您已經看到示例文件的轉換。現在可以轉換您自己的 Eclipse TOC 文件了。下面是設置系統和運行轉換的步驟：
如果您還沒有下載檔案文件 x-ecldita-toc2dita.zip，請立即下載。
使用 PKZip、WinZip 或類似工具來解壓文件。
創建一個文件夾作為您轉換的工作區。
將 toc2dita_adv.xsl 文件從 x-ecldita-toc2dita.zip 文件拷貝到您的工作文件夾。
拷貝您的 Eclipse TOC 文件到相同的文件夾。
如果您還沒有 XSLT 樣式表處理器的拷貝，請獲取一份拷貝。例如，要獲取 Apache Xalan 處理器，請訪問 Apache.org。Xalan 包可作為 C++ 代碼和 Java 代碼得到。Java 包更適合於初學者使用。
如果已經下載了 Xalan-Java 包，則還需要 Java 開發包（JDK），因為您必須使用 java 命令來運行處理器類。如果您有 Rational Application Developer、WebSphere Application Server 或類似的基於 Java 的應用程序，您也可以使用包含在這些應用程序中的 JDK。否則您可以從 Sun Developer's Site 下載 JDK。
按照 XSLT 處理器的說明，轉換您的每一個 Eclipse TOC 文件。在命令中，指定 toc2dita_adv.xsl 文件為 XSLT 樣式表並且輸出文件的擴展名為 .ditamap。下面是使用 Xalan-Java 轉換 TOC 文件的示例命令。
java -classpath
c:\jdk142\lib\j2ee.jar;c:\xalan_dir\xalan.jar org.apache.xalan.xslt.Process
-IN toc.xml -XSL toc2dita_adv.xsl -OUT toc.ditamap
結束語
當把 Eclipse 幫助插件移植成 DITA 格式時，您不必手動將 Eclipse TOC 文件轉換為 DITA 映射文件。XSLT 提供了一種簡單、自動的方法來完成這種轉換，這減少了發生錯誤的風險並加速了移植過程。本文的“下載”部分提供了一個 XSLT 樣式表用於這種轉換。
本文講述了將 TOC 文件轉換為 DITA 映射文件。有時候，DITA 映射清單是合適的。有時候，OASIS DITA 1.0 規范（“ditamap”格式選項）的較新特性是合適的。
