与 DITA 的关系答案

【问题标题】：Relationships with DITA与 DITA 的关系
【发布时间】：2013-01-14 00:21:58
【问题描述】：

我正在尝试在一系列概念文档之间建立关系。因此，给定三个文档“A”、“B”和“C”，我希望它们分别显示如下内容：

一个...

相关概念

B

C

由于某种原因，以下操作无法正常工作：

<reltable>
    <relrow>
        <relcell>
            <topicgroup collection-type="family">
                <topicref href="topics/a.dita" type="concept"/>
                <topicref href="topics/b.dita" type="concept"/>
                <topicref href="topics/c.dita" type="concept"/>
            </topicgroup>
        </relcell>
    </relrow>
</reltable>

以下是可行的，但这肯定是不正确的：

<reltable>
    <relrow>
        <relcell>
            <topicgroup collection-type="family">
                <topicref href="topics/a.dita" type="concept"/>
                <topicref href="topics/b.dita" type="concept"/>
                <topicref href="topics/c.dita" type="concept"/>
            </topicgroup>
        </relcell>
        <relcell>
            <topicgroup collection-type="family">
                <topicref href="topics/a.dita" type="concept"/>
                <topicref href="topics/b.dita" type="concept"/>
                <topicref href="topics/c.dita" type="concept"/>
            </topicgroup>
        </relcell>
    </relrow>
</reltable>

我正在使用 XMLMind 的开源 DITA Converter。

【问题讨论】：

标签： xml documentation dita

【解决方案1】：

您可以阅读关于 reltables 的 DITA 1.2 规范：

http://docs.oasis-open.org/dita/v1.2/os/spec/langref/reltable.html#reltable

规范还包含一个示例。规格说明如下：

在输出时，应将链接添加到同一行但不在同一单元格中的主题。

因此，您的主题需要位于不同的单元格和同一行中。

【讨论】：

该规范页面显示“虽然不一定在同一个单元格中”。

【解决方案2】：

请注意，DITA Open Toolkit 没有规定的限制，您的第一个代码可以正常工作。

但是，您可以在关系表的上下文之外使用@collection-type 属性。在该工具支持 DITA 规范的范围内，这甚至可以使用 DITA 转换器工具。

您没有说明您的可交付成果是在线帮助主题还是 PDF。如果您正在生成帮助主题，您可以在导航地图中包含此代码：

<topicgroup collection-type="family" toc="no">
    <topicref href="topics/a.dita" type="concept"/>
    <topicref href="topics/b.dita" type="concept"/>
    <topicref href="topics/c.dita" type="concept"/>
</topicgroup>

结果是创建了主题之间的链接，但导航中不会列出主题的新实例。

当然，如果这三个主题已经是导航中父节点的唯一子节点，您可以简单地将@collection-type 属性添加到父节点。

【讨论】：

【解决方案3】：

由于 DITAC 转换器具有该限制，我建议将其作为错误报告给 DITAC。也就是说，您还可以创建一个看起来像这样的 reltable，以便它可以在 DITAC 中工作

<reltable>
    <relrow>
       <relcell>
           <topicref href="topics/a.dita" type="concept"/>
        </relcell>
        <relcell>
            <topicref href="topics/b.dita" type="concept"/>
        </relcell> 
        <relcell>
            <topicref href="topics/c.dita" type="concept"/>
     </relrow>
</reltable>

在 DITA-OT 中，所有这 3 个主题都将相互指向，并被分类为概念主题。它应该在 DITAC 中同样工作。根本不需要@collection-type 属性。

从语义上讲，我更喜欢在通过元素中的@collection-type 属性表示的 reltable 中查看我的关系，所以我很清楚发生了什么。

HTH。

【讨论】：

【解决方案4】：

看来这实际上是 XML Mind 对 DITA Converter 工具的一个不幸限制：

生成链接

属性集合类型，无论其值如何，在 reltable 元素内都会被忽略。

参考：http://www.xmlmind.com/ditac/_distrib/doc/manual/limitations.html

【讨论】：