当前页面: 开发资料首页 → Eclipse 专题 → 将 Eclipse 导航文件转化成 DITA 导航文件

将 Eclipse 导航文件转化成 DITA 导航文件

摘要: 上一期文章介绍了把 Eclipse 导航文件转化成 Darwin Information Typing Architecture (DITA) 格式的基础。2005 年 8 月，OASIS DITA Toolkit 1.1 实现了集成 DITA 导航文件的新方式。这种新功能称为 mapref，可用于代替 navref 元素（上一期文章中介绍了）集成导航文件。本文比较集成导航文件的 mapref 和 navref 方法。可以在本文的下载包中找到更新后的 XSLT 样式表，它利用了 mapref 的能力，并对上一期文章中的样式表作了其他改进。

使用主文件集成导航文件

Eclipse 帮助技术提供了一个内容查看器，可显示一个导航控件区域和一个主题内容区域。要选择在内容区显示的主题，用户可以单击导航区中的项。Eclipse 帮助服务器使用 Eclipse Table of Contents (TOC) 文件在导航区创建主题层次。

Eclipse TOC 文件支持两种类型的集成：自顶向下和自底向上。这两种集成都在运行时完成。运行时 即 Eclipse 帮助服务器启动之后。自顶向下的集成 即从一个 TOC 文件链接到更细的 TOC 文件。自底向上的集成 提供了集成其他 TOC 文件的锚点，可供将来使用。

与 Eclipse 帮助技术一样，OASIS DITA 规范支持集成映射文件。在 OASIS DITA 1.0 规范之前，集成映射文件的方法就是在 DITA 映射中编写 元素嵌入其他的 DITA 映射。 元素支持将 DITA 映射转换成 Eclipse TOC 文件，但不能转换成其他导航文件。OASIS DITA 1.0 增加了新的选择，在一个 DITA 映射中可使用专门编写的 元素嵌入其他 DITA 映射。这种编码惯例称为 mapref，不同于 元素的 mapref 属性。OASIS DITA Toolkit 1.1 实现了 OASIS DITA 1.0 规范。

本文中的 XSLT 样式表有一个输入参数用于指定使用哪一种集成方法。

新的 XSLT 样式表在以下方面作了改进：

• 支持 navref 参数，它用于指定如何转换 Eclipse <link>> 元素。
• 支持 transformext 参数，它指定 Eclipse 元素中的 HTML 文件在输出的 DITA 映射中使用文件扩展名 .dita 还是 .xml。
• 在转换输出中指定 OASIS DITA DTD 而不是 IBM DITA DTD。
• 在 Eclipse 元素中处理 JPEG 文件的引用。

使用 mapref 功能转换主 TOC 文件

将 Eclipse TOC 文件转换成 DITA 映射文件更容易，因为两者都是 XML 文件、以层次化的方式描述主题。为了利用 mapref 功能，XSLT 样式表支持输入参数 navref，它确定如何处理 <link>> 元素。Eclipse TOC 文件中的 <link>> 元素嵌入其他 TOC 文件。如果 navref 参数设置为 “no”，那么源 TOC 文件中的 <link>> 就被转换成 DITA 输出文件中的 mapref。若将 navref 参数设为 “yes”，则 <link>> 将转换成 元素。

表 1 是对上一期文章 “将 Eclipse 导航文件转换为 DITA 导航文件”（请参阅 参考资料）中表格内容的修改，增加了一行说明将 <link>> 元素转换成 DITA mapref 的选项。该表还列出了第二个输入参数 transformext，它控制 Eclipse TOC 文件中引用的 HTML 文件扩展名。该表中，每个 Eclipse TOC 元素的属性都列在元素后面。

表 1. 对比 Eclipse TOC 和 DITA 映射的元素 <table border="0" cellpadding="0" cellspacing="0" class="data-table-2" summary="Element-by-element comparison of Eclipse TOC to DITA map" width="100%"><tr><th>TOC 元素和属性</th><th>映射元素和属性</th><th>说明</th></tr><tr><td class="tb-row"></td><td>

对比 mapref 和 navref 方法的转换输出

在考察示例 TOC 文件的转换输出之前，要考虑到两种集成导航文件方法的下列区别：

• DITA mapref 功能在构建时集成导航文件。构建时 就是 DITA 映射文件处理生成特定输出（如 Eclipse 帮助、Java 帮助或 HTML 帮助）。在转换过程中，被集成的 DITA 映射中的任何主题链接都被处理。无论链接被关系表还是 元素的链接属性控制，主题链接都会被集成进来。mapref 功能允许集成导航，并支持在集合中集成跨主题的链接。
• DITA 元素仅用于 Eclipse 输出。如果 DITA 映射转换成 Eclipse 输出， 元素就被转换成 Eclipse 元素，该素指向另一个 Eclipse TOC 文件。只有当 Eclipse 帮助服务器启动后在运行时环境中才把 Eclipse TOC 文件集成进来。DITA 元素适用于要求 Eclipse TOC 输出而不需要跨主题集合集成主题链接的场合。

本文的其他部分讨论使用这两种导航文件集成方法将一个主 Eclipse TOC 文件（mastertoc.xml）转换成 DITA 映射。图 1 显示了主导航文件。主文件中嵌入了名为 Console Basics 的集合（toca.xml 文件），提供了嵌入另一个假定在构建时不存在的集合的锚，连接到名为 Notices 的主题。该TOC 文件和 “将 Eclipse 导航文件转化成 DITA 导航文件”（请参阅 参考资料）中的相同。那些相关的主题文件以及 XSLT 样式表放在本文下载包中。请参阅 下载。

图 2 显示了通过 Eclipse 从上到下集成和主 TOC 文件集成到一起的 Eclipse TOC 文件：

图 3 显示了以 Eclipse 从下到上方式集成的 Eclipse TOC 文件。那个 TOC 文件引用了主 TOC 文件中的锚。

转换到 mapref 编码

为了调用 mapref 转换，将输入参数 navref 设置为 “no” 运行 XSLT 转换。XSLT 样式表（toc2dita_adv_mapref.xsl）的下面一行将 navref 参数设为 “no”，并在没有指定 navref 输入参数的情况下使用它：

由于输入参数的默认值设为 “no”，需要 mapref 编码的时候可以跳过该输入参数。

当转换处理程序遇到 TOC 文件中的 <link>> 元素时，XSLT 样式表生成一个新的 元素，并设置属性 format="ditamap"，href 属性等于该 <link>> 元素的 href 属性。

在 Eclipse TOC 格式中，每个 <link>> 元素都必须包含在 元素中。与 DITA 元素不同，Eclipse 元素不需要 href 属性。建议为每个 元素提供 href 属性，避免让用户感到迷惑。如果用户单击导航项而没有看到内容区域的变化，可能认为帮助系统不能正常工作。为所有 Eclipse 元素设置 href 属性还可以在 TOC 转换成 DITA 映射格式时避免验证错误。无论如何，修改后的 XSLT 支持 元素没有 href 属性的情况。遇到这样的 元素时，将为 元素添加空白的 href 属性。这种方法使输出的 DITA 映射能够成功地转换回原来的 Eclipse TOC 文件（支持往复）。映射到 TOC 的转换忽略输出中的空白 href 属性但保留导航项的标签。

图 4 显示了使用 mapref 转换 mastertoc.xml 时输出的 DITA 映射，以及运行时看到的 Eclipse 导航。在 DITA 映射中，关键在于 mapref 代码行的开始位置。

转换成 元素

要把 Eclipse <link>> 元素转换成 DITA 元素，将输入参数 navref 设为 “yes” 然后运行 XSLT 转换。

当转换处理程序遇到 TOC 文件中的 <link>> 元素时，XSLT 样式表生成一个 元素，将其 mapref 属性设为 <link>> 元素 toc 属性的值。与 mapref 编码的情况一样，如果父 元素包含 href 属性，该 href 保留在 DITA 映射父 元素的 href 属性中。如果没有 href 属性，则在 元素中使用空白 href 属性以便再转换回去。

图 5 显示了将 参数设为 “yes” 转换 mastertoc.xml 时输出的 DITA 映射。在 DITA 映射中，关键在 元素之前。图中还显示了运行时看到的 Eclipse 导航。要注意，mapref 和 navref 转换的运行时导航是一样的，因为两种方法的区别对 Eclipse 导航区的内容没有影响。

比较建立的输出文件

将原来的 Eclipse TOC 转换为 DITA 映射之后，可以使用 DITA 映射建立 Eclipse 帮助集或者其他输出类型。帮助集包括转换后的导航文件和主题文件。本文中的示例文件在 DITA 映射中没有包含链接，但在实际情况中可能需要在 DITA 映射文件中增加其他编码。

比较 mapref 编码和 navref 编码的输出可以明确两种集成方法之间的区别。图 6 显示了 mastertoc.dita 映射包含 mapref 编码、转换方式指定为 Eclipse 时输出目录中的子目录和文件。要注意输出文件夹中的三个子目录。这些目录包含 mastertoc.ditamap 文件中引用的 Notices 和内嵌 toca.ditamap 文件中引用的主题文件。没有一个 tocb.ditamap 的主题文件在输出文件夹之中，因为映射是通过 元素集成的。这些主题文件将结合到 Eclipse 运行时环境中。

图 7 显示了当 mastertoc.ditamap 包含 navref 编码且转换方式指定为 Eclipse 时输出目录中的子目录和文件。要注意，输出文件夹中只有一个子目录。引用子目录包含 mastertoc.ditamap 中引用的 Notices 文件，但是输出目录没有包含集成导航文件（toca.ditamap 和 tocb.ditamap）的主题文件。为什么这些文件没有出现在输出目录中？toca.ditamap 的内容文件没有出现是因为 元素启用了运行时集成而不是构建时集成。tocb.ditamap 文件的内容文件没有出现是因为同样的理由。

转换 TOC 文件

将 Eclipse TOC 文件转换为 DITA 映射的步骤如下：

1. 如果还没有的话请下载本文的压缩包。请参阅 下载。
2. 使用 PKZip、WinZip 或者类似的工具解压该文件。
3. 创建一个文件夹作为转换工作区。
4. 将 toc2dita_adv_mapref.xsl 文件从解压文件的根目录复制到工作文件夹。
5. 将您的 Eclipse TOC 文件复制到同一个文件夹。
6. 如果还没有 XSLT 样式表处理程序，下载一个并安装。比如，可以从 Apache 网站下载 Apache Xalan 处理程序（请参阅 参考资料）。网站提供了 C++ 代码和 Java 代码的 Xalan 包。对于新手来说，Java 包更容易使用。
7. 如果下载了 Xalan Java 包，还需要 Java 开发工具箱以便使用 Java 命令运行处理程序类。如果有 Rational Application Developer、WebSphere Application Server 或者类似的基于 Java 的应用程序，可以使用包含在这些应用程序中的 Java 开发工具箱。否则，可以从 Sun Developer 站点（请参阅 参考资料）下载一个 Java 开发工具箱。
8. 按照 XSLT 处理程序提供的说明转换每个 Eclipse TOC 文件。如果使用的 XSLT 处理程序不接受输入参数，不要指定输入参数，这样 XSLT 样式表将在 <link>> 元素中使用 mapref 编码，并把内嵌主题文件的扩展名设置为 .dita。

   清单 2 中的例子在以下情况下使用 Xalan Java 命令转换一个 TOC 文件，即 jar 文件在系统类路径中，请求 mapref 输出，并且对 HTML 主题文件的引用将在输出 DITA 映射中使用文件扩展名 .xml。如果指定输出 DITA 映射文件的名称，可使用扩展名 “.ditamap” 或 “.xml”。

   
   
   清单 2. 使用 Xalan Java 的命令行
   <table bgcolor="#eeeeee" width="100%" cellpadding="5" cellspacing="0" border="1"><tr><td>

   
   java org.apache.xalan.xslt.Process -param navref no -param transformext .xml no
       -in e:\mastertoc.xml -xsl e:\toc2dita_adv_mapref.xsl -out e:\out\mastertoc.ditamap
   

   </td></tr></table>
   

下载