昨天在提供了 DITA 技巧基础上，读者提出，仍然遇到发布后的链接破坏现象。为此，在昨天解决了正确解析链接关系基础上，本文提供了 DITA 发布后解决链接显示的方案。

介绍

DITA 1.3 中引入的作用域键 SCOPED KEY 允许在 DITA 内容中表示跨书籍引用（也称为交叉可交付引用）。但是，DITA-OT 尚未为此类引用提供开箱即用 plugin 的发布支持。

本文披露了一个 DITA-OT 插件和一个 perl 后处理脚本，当它们一起使用时，可以解析 DITA-OT 的 HTML 输出中的跨书链接。

有关范围键的更多信息，请参阅 DITA 1.3 专题文章： DITA 1.3 中的范围键 SCOPED

KEY。

这个怎么运作

为了使后处理解决方案起作用，我们需要在发布的 HTML 输出中保留关键引用和关键定义。

提供的 DITA-OT 插件执行以下操作：

• 为了保留关键引用，插件将和元素（及其特化）的未解析范围@keyref属性转换为特殊格式的 HTML引用：<xref><link>@href<p class="p">See <a href="keyref://B.topic_B">this topic in book B</a>.</p>
• 为了保留键定义，插件将最终 DITA 映射的“仅键”版本复制到每个输出目录：

out/bookA/index.html
out/bookA/keys-bookA.ditamap    <---
...book A content files...

out/bookB/index.html
out/bookB/keys-bookB.ditamap    <---
...book B content files...

out/bookC/index.html
out/bookC/keys-bookC.ditamap    <---
...book C content files...

• 在应用了所有过滤和分块之后，这个“仅键”映射文件包含@keys/@href定义对：

% cat out/bookA/keys-bookA.ditamap
<map>
   <title>Book A Online Help</title>
   <topicref keys="topic1" href="bookA_content/topic1.dita"/>
   <topicref keys="topic2" href="bookA_content/topic2.dita">
      <topicref keys="topic2a" href="bookA_content/topic2a.dita"/>
      <topicref keys="topic2b" href="bookA_content/topic2b.dita"/>
   </topicref>
</map>

.dita最终地图中的文件直接对应于 HTML 输出中的.html或.htm文件。

发布所有可交付成果后，提供的 perl 脚本href="keyref://..."会对元素进行后处理以引用实际的 HTML 目标文件。无论发布输出的目录结构如何，脚本还会针对引用和引用 HTML 文件之间的相对文件系统路径差异进行调整。

书籍范围首先与输出目录名称匹配（以支持从单个地图发布的多本书），然后是地图名称（以处理简单情况）。

入门

您可以在本机 linux 计算机或安装了 Windows Subsystem for Linux (WSL) 的 Windows 10 计算机上运行此脚本。

先决条件

PERL 脚本

在使用此脚本之前，您必须安装以下 perl 模块：

sudo apt update
sudo apt install cpanminus
sudo cpanm install XML::Twig utf8::all

DITA-OT

你必须在你的 DITA-OT 中从这个 repo 安装以下插件：

plugins/com.synopsys.preserve.keyrefs/

安装

下载或克隆存储库，然后将其bin/目录放在您的搜索路径中，以便fix_html_xbook_links.pl在您的搜索路径中找到该实用程序。

例如，在默认的 bash shell 中，将此行添加到您的\~/.profile文件中：

PATH=~/git/DITA-fix-html-xbook-links/bin:$PATH

将插件复制到您的 DITA-OTplugins/目录，然后运行

dita --install

转换用途

要保留关键信息，请在preserve.keys参数设置为 的情况下运行转换yes：

dita -Dpreserve.keys=yes ... -o out/book1
dita -Dpreserve.keys=yes ... -o out/book2
...

后处理使用

该实用程序处理一个或多个包含来自 DITA-OT 的 HTML 输出的目录，然后就地修改文件以解析可交叉传递的链接。

不带参数或 with 运行该实用程序-help以查看用法：

$ fix_html_xbook_links.pl
Usage:
      <html_dir> [<html_dir> ...]
            Set of directories containing HTML output from the DITA-OT
      --keep-keyrefs
            Keep @data-keyref attributes in HTML (to allow for future incremental updates)

要对内容进行后处理，请指定一个或多个包含所有已发布输出的目录名称：

fix_html_xbook_links.pl ./out

您不需要单独指定每个可交付的输出目录。该实用程序递归搜索keys- bookname .ditamap 文件，然后将这些子目录与该书的内容等同起来。

例子

https://github.com/dcwise/DITA-fix-xbook-html-links

实施说明

的keyref://参考文献都通过一个perl常规表达式，其值的子程序，以确定目标转换。我尝试了各种 HTML 解析解决方案，但它们都不起作用，或者它们显着降低了文件结构，或者它们非常慢。

限制

请注意此脚本和此流程的以下限制：

• bookname.scopename.keyname不支持地图 ( )内的范围。
• 跨书籍范围名称必须与书籍地图名称或输出目录名称匹配。
• 尽管仅键映射文件包含原始<mapref>引用，但不使用或交叉检查信息的一致性。
• DITA-OT 会为跨书籍的纯资源地图引用生成错误消息，但它们似乎是无害的。

如果对文档结构化技术感兴趣，请联系我们

https://raycontentech.com/#/companyintroduction