龙空技术网

如何让跨手册的链接发布后不被破坏

镭内容技术 152

前言:

今天大家对“attributeshtml”大概比较看重,朋友们都想要知道一些“attributeshtml”的相关内容。那么小编在网上汇集了一些对于“attributeshtml””的相关文章,希望咱们能喜欢,姐妹们一起来学习一下吧!

昨天在提供了 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.htmlout/bookA/keys-bookA.ditamap    <---...book A content files...out/bookB/index.htmlout/bookB/keys-bookB.ditamap    <---...book B content files...out/bookC/index.htmlout/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 updatesudo apt install cpanminussudo 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/book1dita -Dpreserve.keys=yes ... -o out/book2...
后处理使用

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

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

$ fix_html_xbook_links.plUsage:      <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 文件,然后将这些子目录与该书的内容等同起来。

例子

实施说明

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

限制

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

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

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

标签: #attributeshtml