將 Eclipse TOC 導航檔轉換為 DITA Map 格式

背景與動機

將 Eclipse Help 外掛遷移至 DITA 格式時，HTML 內容轉換工具已相對成熟，但導航結構（TOC 檔）的轉換缺乏自動化工具。Eclipse TOC 檔定義了說明系統的主題層級、搜尋索引、關鍵主題可見性等核心結構，手動轉換不僅耗時且易出錯。本文提供 XSLT 樣式表，自動將 Eclipse TOC 轉換為 DITA Map，填補工具鏈缺口。

Eclipse TOC 與 DITA Map 元素對照

兩者皆為 XML 導航檔，結構相似。下表列出主要元素對應關係：

轉換範例：主 TOC 檔

主 TOC（mastertoc.xml）通常包含根標題、連結子 TOC、定義錨點供擴充、包含提醒主題。轉換後的 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 檔

自上而下整合：toca.xml

主 TOC 以 <link toc="toca.xml"> 明確引用，轉換為 <navref mapref="toca.ditamap"/> 嵌入父 topicref 中。

自下而上整合：tocb.xml

子 TOC 以 <toc link_to="../com.mycompany.plugin.doc/mastertoc.xml#anchor_id"> 指向主 TOC 錨點。轉換後，map 根元素加上 anchorref="../com.mycompany.plugin.doc/mastertoc.ditamap#anchor_id"。

<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>

如何使用 XSLT 進行轉換

1. 下載並解壓 x-ecldita-toc2dita.zip，取出 toc2dita_adv.xsl
2. 建立工作資料夾，放入 XSLT 檔與待轉換的 TOC XML
3. 安裝 XSLT 處理器（如 Apache Xalan-Java），需 JDK 環境
4. 執行轉換指令，輸出副檔名為 .ditamap：

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

結語

XSLT 提供可靠、自動化的 TOC 轉 DITA Map 方案，降低遷移風險與成本。轉換後的 DITA Map 可直接用於 DITA 處理流程，支援 ditamap 格式選項與 OASIS DITA 1.0 規範新特性。