`<reltable>`

A relationship table is a mechanism that creates relationships among topics, based on the familiar table model of rows, columns, and cells.

Usage information

Relationship tables can be used in conjunction with hierarchies and groups to manage all the related links in an information set.

Each column in a relationship table typically represents a specific role in a set of relationships, and each row defines relationships between the resources that are referenced in the different cells of that row.

A frequently-used type of relationship table uses the following structure:

The first column contains references to task topics.
The second column contains references to concept topics.
The third column contains references to reference topics.

Such a relationship table establishes relationships between task topics and the concept and reference topics that support the tasks. It help authors and architects determine where related information is missing or undefined.

When a title is associated with a relationship table, the title typically is used as an authoring convenience and is not displayed in generated publications.

Processing expectations

By default, the contents of a <reltable> element are not rendered in a table of contents; they are used only to define relationships that can be expressed as topic-to-topic links. The <relcell> elements can contain <topicref> elements, which are then related to other <topicref> elements in the same row (although not necessarily in the same cell).

Within a root map, the effective relationship table is the union of all relationship tables in the map hierarchy.

Attributes

The following attributes are available on this element: common map attributes (without @keyscope or @collection-type), universal attributes, @format, @scope, and @type.

For this element, the @toc attribute has a default value of no.

Example

In the following code sample, a relationship table is defined with three columns: one for "concept", one for "task", and one for "reference". Three cells are defined within each row. The first cell contains one concept topic: about-MyDevice.dita. The second cell contains two task topics: setting-up-MyDevice.dita and operating-MyDevice.dita. The third cell contains two reference topics: MyDevice-settings.dita and MyDevice-version-info.dita.

<map>
  <reltable>
    <relheader>
      <relcolspec type="concept"/>
      <relcolspec type="task"/>
      <relcolspec type="reference"/>
    </relheader>
    <relrow>
      <relcell>
        <topicref href="about-MyDevice.dita"/>
      </relcell>
      <relcell>
        <topicref href="setting-up-MyDevice.dita"/>
        <topicref href="operating-MyDevice.dita"/>
      </relcell>
      <relcell>
        <topicref href="MyDevice-settings.dita"/>
        <topicref href="MyDevice-version-info.dita"/>
      </relcell>
    </relrow>
  </reltable>
</map>

A graphical version of the relationship table in an editor might look like this:

type="concept"	type="task"	type="reference"
about-MyDevice.dita	setting-up-MyDevice.dita operating-MyDevice.dita	MyDevice-settings.dita MyDevice-version-info.dita

When rendered, links are added to topics that are in the same row, but not in the same cell. This allows simple maintenance of parallel relationships: for example, in this case, setting-up-MyDevice.dita and operating-MyDevice.dita are two tasks that require the same supporting information (concept and reference topics) but might otherwise be unrelated. When topics in the same cell are in fact related, the @collection-type attribute for the cell can be set to family. If some cells or columns are intended solely as supporting information and should not link back to topics in other cells, you can set the @linking attribute on the <relcell> or <relcolspec> to targetonly.

In this example, the related links would be as follows:

about-MyDevice.dita: setting-up-MyDevice.dita, operating-MyDevice.dita, MyDevice-settings.dita, MyDevice-version-info.dita
setting-up-MyDevice.dita: about-MyDevice.dita, MyDevice-settings.dita, MyDevice-version-info.dita
operating-MyDevice.dita: about-MyDevice.dita, MyDevice-settings.dita, MyDevice-version-info.dita
MyDevice-settings.dita: about-MyDevice.dita, setting-up-MyDevice.dita, operating-MyDevice.dita
MyDevice-version-info.dita: about-MyDevice.dita, setting-up-MyDevice.dita, operating-MyDevice.dita

Relationship tables are inherently an efficient way to manage these links. In particular, they increase the prospect for reuse among topics, because those topics do not contain context-specific links. A relationship table also makes it easy to see and manage patterns; for example, the fact that operating-MyDevice.dita and setting-up-MyDevice.dita have the same relationships to supporting information is clear from the table, but would require some comparison and counting to determine from the list summary just before this paragraph.