reltable

Darwin Information Typing Architecture (DITA) Version 1.2

The <reltable> element is a relationship table that specifies relationships between 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.

Contains

Note: These models represent only the default document types distributed by OASIS. Actual content models will differ with each new document type.
Doctype Content model
map, bookmap, classifyMap, subjectScheme, learningBookmap, learningMap ( (title) (optional) then (topicmeta) (optional) then (relheader) (optional) then (relrow) (one or more) )

Contained by

Doctype Content model
map (base), map (technical content), classifyMap, learningMap map
bookmap, learningBookmap map, bookmap
subjectScheme map, subjectScheme

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

Name Description Data Type Default Value Required?
title An identifying title for this element. CDATA #IMPLIED No
topicref-atts-no-toc attribute group (collection-type, processing-role, type, scope, locktitle, format, linking, toc, print, search, chunk) A related set of attributes. See topicref-atts, topicref-atts-no-toc, and topicref-atts-without-format attribute groups.      
univ-atts attribute group (includes select-atts, id-atts, and localization-atts groups) A set of related attributes, described in univ-atts attribute group      
global-atts attribute group (xtrf, xtrc) A set of related attributes, described in global-atts attribute group      
class, outputclass Common attributes described in Other common DITA attributes