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

Content model

<title> ?, <topicmeta> ?, <relheader> ?, <relrow> +

In order

Optional <title>
Optional <topicmeta>
Optional <relheader>
One or more <relrow>

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.

The following attributes are available on this element: universal attributes and the attributes defined below.

@cascade (common map attributes)

Specifies how metadata attributes cascade within a map. The specification defines the following values:

merge: Indicates that the metadata attributes cascade, and that the values of the metadata attributes are additive. This is the processing default for the @cascade attribute.
nomerge: Indicates that the metadata attributes cascade, but that they are not additive for <topicref> elements that specify a different value for a specific metadata attribute. If the cascading value for an attribute is already merged based on multiple ancestor elements, that merged value continues to cascade until a new value is encountered. That is, setting cascade="nomerge" does not undo merging that took place on ancestor elements.

Processors can also define custom, implementation-specific tokens for this attribute.

See Cascading of metadata attributes in a DITA map for more information about how this attribute interacts with metadata attributes.

@chunk (common map attributes)

Specifies how a processor should render a map or branch of a map. For example, it can be used to specify that individual topic documents should be rendered as a single document, or that a single document with multiple topics should be rendered as multiple documents.

The following values are valid:

combine: Instructs a processor to combine the referenced source documents for rendering purposes. This is intended for cases where a publishing process normally results in a single output artifact for each source XML document.
split: Instructs a processor to split each topic from the referenced source document into its own document for rendering purposes. This is intended for cases where a publishing process normally results in a single output artifact for each source XML document, regardless of how many DITA topics exist within each source document.

Processors can also define custom, implementation-specific tokens for this attribute.

For a detailed description of the @chunk attribute and its usage, see Chunking.

@collection-type (common map attributes)

Specifies how topics or links relate to each other. The processing default is unordered, although no default is specified in the OASIS-provided grammar files. The following values are valid:

unordered: Indicates that the order of the child topics is not significant.
sequence: Indicates that the order of the child topics is significant. Output processors will typically link between them in order.
choice: Indicates that one of the children should be selected.
family: Indicates a tight grouping in which each of the referenced topics not only relates to the current topic but also relate to each other.

@format (link-relationship attributes)

Specifies the format of the resource that is referenced. See The format attribute for detailed information on supported values and processing implications.

@keyscope (common map attributes)

Specifies that the element marks the boundaries of a key scope.

See The keyscope attribute for information on using this attribute.

@linking (common map attributes)

Specifies linking characteristics of a topic specific to the location of this reference in a map. If the value is not specified locally, the value might cascade from another element in the map (for cascade rules, see Cascading of metadata attributes in a DITA map). The following values are valid:

targetonly: A topic can only be linked to and cannot link to other topics.
sourceonly: A topic cannot be linked to but can link to other topics.
normal: A topic can be linked to and can link to other topics. Use this to override the linking value of a parent topic.
none: A topic cannot be linked to or link to other topics.
-dita-use-conref-target: See Using the -dita-use-conref-target value for more information.

@processing-role (common map attributes)

Specifies whether the referenced resource is processed normally or treated as a resource that is only included in order to resolve references, such as key or content references. The following values are valid:

normal: Indicates that the resource is a readable part of the information set. It is included in navigation and search results. This is the default value for the <topicref> element.
resource-only: Indicates that the resource should be used only for processing purposes. It is not included in navigation or search results, nor is it rendered as a topic. This is the default value for the <keydef> element.

-dita-use-conref-target: See Using the -dita-use-conref-target value for more information.

If no value is specified but the attribute is specified on a containing element within a map or within the related-links section, the value cascades from the closest containing element.

@scope (link-relationship attributes)

Specifies the closeness of the relationship between the current document and the referenced resource. The following values are valid: local, peer, external, and -dita-use-conref-target.

See The scope attribute for detailed information on supported values and processing implications.

@search (common map attributes)

Specifies whether the target is available for searching. If the value is not specified locally, the value might cascade from another element in the map (for cascade rules, see Cascading of metadata attributes in a DITA map). The following values are valid: yes, no, and -dita-use-conref-target.

@subjectrefs (common map attributes)

Specifies one or more keys that are each defined by a subject definition in a subject scheme map. Multiple values are separated by white space.

@toc (common map attributes)

Specifies whether a topic appears in the table of contents (TOC) based on the current map context. If the value is not specified locally, the value might cascade from another element in the map (for cascade rules, see Cascading of metadata attributes in a DITA map). The following values are valid:

yes: The topic appears in a generated TOC.
no: The topic does not appear in a generated TOC.
-dita-use-conref-target: See Using the -dita-use-conref-target value for more information.

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

@type (link-relationship attributes)

Describes the target of a reference. See The type attribute for detailed information on supported values and processing implications.

Example

This section is non-normative.

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.