DITA Proposed Feature #12048

Add topic references to reltable headers to improve link management.

Longer description

Currently: The <reltable> provides a <relheader> element that provides a <relcolspec> element for each column. The <relcolspec> element sets default values for attributes of top-level <topicref> elements in the column (which, in turn, can cascade attributes to contained <topicref> elements).

One benefit of these default values is simply convenience. More importantly, however, these values provide guidance to writers by indicating the kind of topic that should be referenced in the column. For instance, setting the default value for the type attribute to "concept" and the platform attribute to "linux" indicates that only concept topics about Linux should appear in the column.

Base DITA limits the organizing principle for the relationship table column, however, to these predefined attributes. To manifest a different organizing principle for the relationship table column in the DITA source, the content provider has to specialize. For instance, the content provider cannot specify a title for the related links from the column. (For more detail about the currently specified capabilities, see http://docs.oasis-open.org/dita/v1.1/CD02/langspec/langref/relcolspec.html.)

Proposed: Broaden the <relcolspec> element to distribute not only the pre-defined attributes but the relationships specified with the <topicref> element. That is, the <topicref> elements within the <relcolspec> element have relationships with every <topicref> in the column. In addition, add the <title> element as a convenience for labelling the grouping of related links from the column when generating related links.

For instance, if the <relcolspec> contains a topic reference to a troubleshooting directory topic, every <topicref> in the column links to the troubleshooting directory topic. Such linking motivates writers to populate the column only with topics related to troubleshooting. This linking model is consistent with the distribution of relationships horizontally across a <relrow> and with the distribution of relationships between parent and child <topicref> elements in a map navigation.

This approach is consistent with general vertical distribution expectations for table header. That is, in the same way that a textual column header applies to content in all cells of the table column, a target specified in a column header can be linked to targets in all cells of the table column.

This change is simpler than the suggestion in original email at http://lists.oasis-open.org/archives/dita/200703/msg00065.html.

Statement of Requirement

Use Cases

Content header relationships
A software developer needs to create a set of many-to-many relationships between topics that describe error messages and troubleshooting topics that explain how to recover from problems. In addition, the content provider wants to provide a directory of message topics and another directory of troubleshooting topics.

The writer puts the topic for the message directory in one column header and the topic for the troubleshooting directory in another column header. The writer puts the message topics in one column and the troubleshooting topics in the other column, grouping interrelated message and troubleshooting topics in the same row.

The processing creates a related link between the message directory topic and each message topic, a related link between the troubleshooting directory topic and each troubleshooting topic, and related links among message topics and troubleshooting topics in the same row.

This column-based linking encourages other writers who later maintain the <reltable> to be careful to put only message topics in the message column and only troubleshooting topics in the troubleshooting column.

Here is an example for this use case:

<reltable>
<relheader>
  <relcolspec>
    <topicref navtitle="Troubleshooting" href="troubleHub.dita" locktitle="yes"/>
  </relcolspec>
  <relcolspec>
    <topicref navtitle="Messages" href="messageHub.dita" locktitle="yes"/>
  </relcolspec>
</relheader>
<relrow>
  <relcell>
    <topicref navtitle="Debugging login"          href="debugLogin.dita"/>
  </relcell>
  <relcell>
    <topicref navtitle="Login not found"          href="loginErr1.dita"/>
  </relcell>
</relrow>
<relrow>
  <relcell>
    <topicref navtitle="Checking access controls" href="checkAccess.dita"/>
  </relcell>
  <relcell>
    <topicref navtitle="Login not allowed"        href="loginErr2.dita"/>
  </relcell>
</relrow>
</reltable>

A DITA-sensitive editor would render this <reltable> as a table to visualize the vertical and horizontal associations:

<topicref navtitle="Troubleshooting"
    href="troubleHub.dita" locktitle="yes"/>
<topicref navtitle="Messages"
    href="messageHub.dita" locktitle="yes"/>
<topicref navtitle="Debugging login"
    href="debugLogin.dita"/>
<topicref navtitle="Login not found"
    href="loginErr1.dita"/>
<topicref navtitle="Checking access controls"
    href="checkAccess.dita"/>
<topicref navtitle="Login not allowed"
    href="loginErr2.dita"/>

This relationship table establishes the following links:

  • From debugLogin.dita to troubleHub.dita (new) and loginErr1.dita.
  • From checkAccess.dita to troubleHub.dita (new) and loginErr2.dita
  • From loginErr1.dita to messageHub (new) and debugLogin.dita.
  • From loginErr2.dita to messageHub (new) and checkAccess.dita
  • From troubleHub.dita (new) to debugLogin.dita and checkAccess.dita
  • From messageHub (new) to loginErr1.dita and loginErr2.dita

In addition, processing can use "Troubleshooting" to title the related links to debugLogin.dita and checkAccess.dita. Similarly, processing can use "Messages" to title the related links to loginErr1.dita and loginErr2.dita.

Classification header relationships
An organization has created a taxonomy using topics to define the subjects and maps to organize subjects in hierarchical facet categories. The organization wants to make it easy for writers to classify the subject matter of content. In particular, the organization wants to encourage writers to create a facet classification where a single topic is classified with subjects from multiple categories (such as hardware platform, operating system, and so on).

The specializer creates a specialized <reltable> and <relcolspec> that provides a reference to a topic that defines a facet category in each classification column. The specializer also provides extended editing behaviors that validate the reference to the facet category, provide look up to select subjects from the facet category for inserting in the rows of the column, and validate edited subjects in the column row against the facet category.

The markup guides writers to create and maintain the facet classification. For instance, the writer can put a reference to a description of a software offering in the first column, a reference to the subjects for the supported hardware platforms in the second column, a reference to the subjects for the supported operating systems in the third column, and so on.

Scope

This proposal expands the content model of the <relcolspec> element. The proposal doesn't introduce new elements or attributes.

Technical Requirements

The content model of the <recolspec> element changes to allow a <title> element to make it easy to specify the label for grouping related links before the optional <topicmeta> element. The <recolspec> element also adds any number of <topicref> elements after the optional <topicmeta> element.

The change in DTD syntax:

<!ELEMENT relcolspec ((%title;)?, (%topicmeta;)?, (%topicref)*)>

The change in XML Schema syntax:

<xs:complexType name="relcolspec.class">
    <xs:sequence>
        <xs:group ref="title"     minOccurs="0"/>
        <xs:group ref="topicmeta" minOccurs="0"/>
        <xs:group ref="topicref"  minOccurs="0"/>
    </xs:sequence>
    ...
</xs:complexType>

Base processing changes to distribute relationships contained by the <relcolspec> element to the <topicref> elements in the cells of the column. In particular:

The title for the link to the header topics is established in the typical way for a <topicref> context:

The linking attributes on the header and row <topicref> elements control the directionality of linking in the typical way. A <topicref> with a linking attribute of "sourceonly" contains links but isn't a target of links for relationships in the context. A <topicref> with a linking attribute of "targetonly" is a target of links but doesn't contain links for relationships in the context.

Processing can use the <relcolspec> to establish the label for the grouped related links from the column in the output for the topics in other columns. If the <relcolspec> contains a <title> element, that title should be used. If no <title> element is provided and only a single <topicref> element (or specialized <topichead> element) is provided, a processor can use the <topicref> to title the group of the links from the column. As shown in the example under Use Cases, this approach allows for intuitive and efficient titling of related link groups.

Note: In the same way that attribute values of <topicref> elements within <relcell> don't distribute horizontally across the reltable row, attribute values of <topicref> elements within <relcolspec> do not distribute vertically in the column.

In particular, in the same way that the collection-type attribute of a <topicref> element within <relcell> applies only on linking to its contained <topicref> subelements and not horizontally across the reltable row to other <topicref> elements, the collection-type attribute of a <topicref> element within <relcolspec> applies only on linking to its contained <topicref> subelements and not vertically down the column to other <topicref> elements.

Note: In the same way that <topicref> elements at any depth within a <relcell> element participate in horizontal linking across the reltable row, <topicref> elements at any depth within the <relcolspec> header participate in vertical linking down the column.

New or Changed Specification Language

Note: In the future, the DITA community might consider setting defaults for distribution horizontally across a row with a <relrowspec> element.

Costs

The only significant expense is the enhancement of the existing processing that distributes attributes vertically within the reltable column to distribute links vertically and to use the title when grouping related links.

Benefits