reltable

The <reltable> element is a relationship table that specifies relationships among topics, based on the familiar table model of rows (<relrow>), columns (<relheader>), and cells (<relcell>).

A frequently-used type of relationship table establishes relationships between task, concept, and reference topics. Each column in a relationship table typically represents a specific role in a set of relationships; for example, the first column often contains references to tasks, while the second and third columns often reference concept and reference topics. The relationship table rows define relationships between the resources referenced in different cells of the same row; in this example, each row establishes relationships between tasks and the concept and reference topics that support the tasks. When used in this manner, relationship tables make it easy to determine where related information is missing or undefined.

By default, the contents of a <reltable> element are not output for navigation or TOC purposes; 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).

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

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

Content models

See appendix for information about this element in OASIS document type shells.

Inheritance

- map/reltable

Example

In this example, a relationship table is defined with three columns; one for "concept", one for "task", and one for "reference". Three cells are defined within one row. The first cell contains one concept topic: batsonar.dita. The second cell contains two task topics: batcaring.dita and batfeeding.dita. The third cell contains two reference topics: batguano.dita and bathistory.dita.

<map>
  <reltable>
    <relheader>
      <relcolspec type="concept"/>
      <relcolspec type="task"/>
      <relcolspec type="reference"/>
    </relheader>
    <relrow>
      <relcell>
        <topicref href="batsonar.dita"/>
      </relcell>
      <relcell>
        <topicref href="batcaring.dita"/>
        <topicref href="batfeeding.dita"/>
      </relcell>
      <relcell>
        <topicref href="batguano.dita"/>
        <topicref href="bathistory.dita"/>
      </relcell>
    </relrow>
  </reltable>
</map>

A DITA-aware tool might represent the <reltable> element graphically:

type="concept"	type="task"	type="reference"
batsonar.dita	batcaring.dita batfeeding.dita	batguano.dita bathistory.dita

On output, links should be 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, batcaring.dita and batfeeding.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 cell's @collection-type attribute 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:

batsonar.dita: batcaring.dita, batfeeding.dita, batguano.dita, bathistory.dita
batcaring.dita: batsonar.dita, batguano.dita, bathistory.dita
batfeeding.dita: batsonar.dita, batguano.dita, bathistory.dita
batguano.dita: batsonar.dita, batcaring.dita, batfeeding.dita
bathistory.dita: batsonar.dita, batcaring.dita, batfeeding.dita

Although such tables can initially take some time to learn and manipulate, they 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 batfeeding.dita and batcaring.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.

Attributes

The following attributes are available on this element: Universal attribute group, Attributes common to many map elements (without the @keyscope attribute, and with a narrowed definition of @toc, given below), outputclass, and the attributes defined below. This element also uses @type, @scope, and @format from Link relationship attribute group.

@toc: Specifies whether a topic appears in the table of contents (TOC). If the value is not specified locally, but is specified on an ancestor, the value will cascade from the closest ancestor. On this element the default value for @toc is "no". See Attributes common to many map elements for a complete definition of @toc.
@title: An identifying title for this element.