将 Eclipse 导航文件转换为 DITA 导航文件

核心提示：本文描述了如何完成移植过程中转换工具所不能自动完成的任务：将 Eclipse TOC 文件转换为 DITA 映射文件，这里并没有讨论将 HTML 文件转换为 DITA 格式的原因，将 Eclipse 导航文件转换为 DITA 导航文件，OASIS DITA Web 站点上的其他 developerWorks 文章和参考

本文描述了如何完成移植过程中转换工具所不能自动完成的任务：将 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”格式选项）的较新特性是合适的。