Relationships with DITA

Question

I am trying to create a relationship between a selection of concept documents. So given three documents "A", "B" and "C" I would like them to each display something like the following:

A ...

Related Concepts

• B
• C

For some reason the following fails to work:

<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>

The following works, but this surely cannot be correct:

<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>

I am using the open-source DITA Converter by XMLMind.

Answer 1

It seems that this is in fact an unfortunate limitation of the DITA Converter tool by XML Mind:

Generating links

Attribute collection-type, whatever its value, is ignored inside the reltable element.

Ref: http://www.xmlmind.com/ditac/_distrib/doc/manual/limitations.html

Answer 2

You can read the DITA 1.2 specs about reltables:

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

the specs also contains an example. The specs says something like:

On output, links should be added to topics that are in the same row, but not in the same cell.

So your topics need to be in different cells and on the same row.

Answer 3

Note that the DITA Open Toolkit does not have the stated limitation and your first code would work fine.

However, you can use the @collection-type attribute outside of the context of a relationship table. This should work even with the DITA Converter tool to the extent that the tool supports the DITA spec.

You do not state whether your deliverable is online help topics or a PDF. If you are generating help topics, you could include this code in your navigation map:

<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>

The result is that the links among the topics would be created, but a new instance of the topics would not be listed in the navigation.

Of course, if these three topics already are the only children of a parent node in the navigation, you could simply add the @collection-type attribute to the parent node.

Answer 4

With the DITAC converter having that limitation, I would suggest reporting it as a bug to DITAC. That said, you can also take the position of creating a reltable that looks something like this so it would work in 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>

In the DITA-OT, all 3 of these topics will point to each other and be sorted as concept topics. It should work the same in DITAC. There's no need for the @collection-type attribute at all.

Semantically, I prefer to see my relationships in a reltable that expressed through @collection-type attributes in elements so it's obvious to me what's going on.

HTH.