Kylene Bruski
Comtech Services, Inc.

If you would like to learn more basic information on DITA, please visit the OASIS Cover Pages web site at xml.coverpages.org/dita.html.

In the Darwin Information Typing Architecture (DITA), authors can link within topics to other topics through the <related-links> element. However, there are disadvantages to hard-coding links in a topic. Hard-coded links create dependencies between topics and decrease the reusability of each topic. Since the links are hard coded within the topic, they may not apply to other contexts in which the topic is reused. If a topic is renamed or if its path changes, the link will have to be recreated in all topics which reference this link. Hard-coded links result in excessive maintenance.

DITA provides a powerful alternative means of linking using relationship tables. The benefit of using a relationship table is the ability to create and maintain links in one place with the map rather than in the topics. Links can be created both between topics of the same information type and between topics of different information types that are not directly related through parent/child relationships. Therefore, the best practice for linking in DITA is to use a relationship table within a map.

Relationship tables are expressed in the CALS Table Model format using rows and columns to set up the links. Each column in a table groups similar information types together, such as concept, task, and reference. Each row in the table represents a relationship, which is generally rendered as a link, and each cell represents participants in the relationship. Therefore, when the relationship table is created, each topic reference in a cell will link to the topic references in the other cells in the same row.

For example, if we wanted to link the three topics: simpleconcept.dita, simpletask.dita, and simplereference.dita, the relationship table would look like this:

In practice, relationship tables are more complex than this simple example. When creating a more complex relationship table, it is important to remember the following:
Each row represents a separate set of relationships and links
No relationship exists between the rows in a table
Topic references are not needed in every cell within a row
Each cell can contain multiple topic references
Topic references can be repeated in multiple rows

In the complex relationship table below, each arrow represents a link which is created between the topics. Each link created in the table below will be placed at the end of each topic during production.

In a relationship table, topic references within a cell are not linked together. However, there are instances when they should be linked. Applying the collection-type attribute in the <topicgroup> element allows you to link topic references inside a cell.

The collection-type attribute is added to give additional functionality to link-related topics. The collection-type attribute only affects the relationships within a cell—it does not affect relationships across cells. The most common collection-type value used within a relationship table is family. If you have a set of closely related concepts or tasks that need links or relationships created, other than a parent/child relationship, use the family collection-typevalue. For example, in the table below, the simplereference1.dita and simplereference2.dita are related using the collection-type=“family”.

You can use the linking attribute to create one-way links within a relationship table. Thelinking attribute values are sourceonly and targetonly. The sourceonly value creates only a link in the source topic to the target topic. The target topic will not contain a link back to the source topic. For example, the simpletask1.dita linking attribute value is set to sourceonly. Therefore, the link to simplereference1.dita and simplereference2.dita will only appear in the simpletask1.dita. The simplereference1.dita and simplereference2.dita will not contain a link back to the simpletask1.dita. These links do not affect the linking between simplereference1.dita and simplereference2.dita.

The targetonly value creates a link in the target topic to the source topic, which means that the source topic will not contain a link to the target topic.

Relationship Table Elements

The following section describes the DITA elements needed to create a relationship table within a map.

<reltable> element

The <reltable> element is the framework for the relationship table. All elements contained in the relationship table are added between the beginning and ending tag of the <reltable> element.

<relheader> element

The <relheader> element is the first element added to the relationship table and is the container for defining the columns in a relationship table.

<relcolspec> element

Multiple <relcolspec> elements can be contained within the <relheader> element. Each <relcolspec> element defines the common attributes used to categorize the topics using the type attribute. Typically organizations use three <relcolspec> elements to categorize their topics: concept, task, and reference.

<relrow> element

Each <relrow> element defines a new set of links and relationships between the topic references. You can add more than one <relrow> element to each relationship table.

<relcell> element

The <relcell> element is the container for each topic reference to be linked within the <relrow>. The number of <relcell> elements has to match the number and order of <relcolspec> elements. You will typically use three elements in order—concept, task, and reference. If a cell within a row does not contain any topic references, you still have to add the <relcell> element, but you can leave the cell empty.

Creating a Relationship Table

Below describes the steps needed to create a relationship table, however the following is not a complete table. We have provided a complete relationship table example, including graphics and code, below the steps.

1. Create a new map file and call it simplemap.ditamap.
2. Add the <reltable> element to the map between the <map> element start and end tags.
<reltable>
</reltable>
3. Add the <relheader> element to the <reltable> element.
<reltable>
<relheader>
</relheader>
</reltable>
4. Add the <relcolspec> element to the <relheader> element.
<relheader>
<relcolspec/>
<relcolspec/>
<relcolspec/>
</relheader>
5. Add the type attribute to each <relcolspec> element setting the attribute value to concept, task, and reference respectively.
<relcolspec type=“concept”/>
<relcolspec type=“task”/>
<relcolspec type=“reference”/>
6. Add the <relrow> element under the ending tag for the <relheader> element.
</relheader>
<relrow>
</relrow>
<relrow>
</relrow>
7. Add the <relcell> element to the <relrow> element.
<relrow>
<relcell>
</relcell>
<relcell>
</relcell>
<relcell>
</relcell>
</relrow>
8. Add the <topicref> element to the <relcell> element.
<relcell>
<topicref/>
<topicref/>
</relcell>
9. Add the href attribute to the target’s URL for each of the <topicref> elements in each of the <relcell> elements.
<topicref href=“simpletask1.dita”/>
10. Add the <topicgroup> element to the <relcell> element.
<relcell>
<topicgroup>
<topicref href=“simpletask1.dita”/>
</topicgroup>
</relcell>
11. Add the collection-type attribute and set the value to family in the <topicgroup> element.
<topicgroup collection-type=“family”>
12. Add the linking attribute to the <topicref> element setting the value to sourceonly or targetonly.
<topicref href=“simpletask1.dita” linking=“sourceonly”>

A more complex relationship table example is shown below. In this example, the first row provides links between the three topics, concept, task, and reference. The second row provides links between the two concept topics and the reference topic. However, there is not a link created between the two concept topics. The third row creates links between all three concept topics. There are one way links created from the three concepts and one task topic to the simplereference2 topic because the reference is labeled as a ‘targetonly’ link. Therefore, links are created within the concept and task topics to the simplereference2 topic. However, there are not links in the simplereference2 topic to the other topics. There is also a one way link created between the simplereference1.dita and the task and three concept topics. The simplereference1 topic is labeled as ‘sourceonly’ so links will only be created within the simplereference1 to the other topics. The other topics will not contain a link back to the simplerefence1 topic. There are two way links created between the three concept topics and the task topic.

Below is the code for the relationship table created above.

<?xml version=“1.0” encoding=“utf-8″?>
<!DOCTYPE map PUBLIC “-///IBM//DTD DITA Map//EN” “../../dtd/map.dtd”>
<map title=“Title of map is place here.” id=“InfoTypeMap” toc=“yes”>
<reltable>
<relheader>
<relcolspec type=“concept”/>
<relcolspec type=“task”/>
<relcolspec type=“reference”/>
</relheader>
<relrow>
<relcell>
<topicref href=“simpleconcept1.dita”/>
</relcell>
<relcell>
<topicref href=“simpletask1.dita”/>
</relcell>
<relcell>
<topicref href=“simplereference1.dita”/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref href=“simpleconcept1.dita”/>
<topicref href=“simpleconcept2.dita”/>
</relcell>
<relcell></relcell>
<relcell>
<topicref href=“simplereference1.dita”/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicgroup collection-type=“family”>
<topicref href=“simpleconcept2.dita”/>
<topicref href=“simpleconcept3.dita”/>
<topicref href=“simpleconcept4.dita”/>
<topicgroup>
</relcell>
<relcell>
<topicref href=“simpletask2.dita”/>
</relcell>
<relcell>
<topicref href=“simplereference1.dita” linking=“sourceonly”/>
<topicref href=“simplereference2.dita” linking=“targetonly”/>
</relcell>
</relrow>
</reltable>
</map>