Proposal 12048 - expanded header for reltable

Add header rows to reltables

Longer description

Currently, <reltable> provides a <relheader> element that provides a <relspec> element for each column. The <relspec> element sets default values for column attributes. These default values also resemble constraints because only topics to which the property can apply should appear 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. (For more detail about the currently specified capabilities, see http://docs.oasis-open.org/dita/v1.1/CD02/langspec/langref/relcolspec.html.)

This proposal recognizes the existing default-setting capability of the column header as a special case of a more general capability for specifying properties and relationships common to all topics referenced in a column. In particular, such properties should be expressable not only with attributes but with <data> elements. In addition, relationships common to all topics referenced in a column should be possible to express with <topicref> elements. As with simple values, these complex properties and relationships can resemble constraints. For instance, if the column header supplies a topic reference to a hub topic about troubleshooting, the column should contain only topics related to troubleshooting.

In the same way that a textual column header applies to values in all column cells of a content table, a column header with full distributive capability is consistent with the expected structure of a table. This distributive capability would also add to the value of the relationship table.

To make it possible to express complex properties and relationships, the content model of the <recolspec> element could allow any number of <data> or <topicref> elements after the optional <topicmeta> element. (This change is simpler than the suggestion in original email at http://lists.oasis-open.org/archives/dita/200703/msg00065.html.)

Statement of Requirement

Make it easy to distribute properties and relationships common to a set of topics within a relationship table structure.
Make it possible to declare the commonality of a column of a relationship table where the commonality requires relationships or is more complex than can be expressed with a combination of simple attribute tokens.
Make it easy to label the groupings of related links at the bottom of the topic in typical output.

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. Processing can use the title of the first topic in the <relcolspec> to provide a label for the grouped related topics from the column in the output for each topic.

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.

Complex data

A marketing trend reporter needs to associate descriptive topics about product trends in different geographic locations.

The writer uses a <data> element in each column header to specify the longitude, latitude, and label for the geographic location associated with the column. In each row of the <reltable>, the writer puts the topics about one product type, putting the topics for different locations in different columns.

As usual, the processing creates a related link between topics about the same product type in different locations. The processing also associates the geographic data for the column with each topic in the column, supporting retrieval based on geographic location.

The geographic lookup encourages other writers who later maintain the <reltable> to be careful to provide a topic about each location when adding a row for a new product type.

Classification header relationships

In the taxonomy specialization, a specialized <reltable> provides a specialized <relcolspec> that requires a reference to a subject category (that is, a facet in taxonomy terminology) in every column except the first. In the rows, the first column has a reference to the content topics and subsequent columns each have a subject from a different category. As a result, the markup guides the writer to create a facet classification.

Scope

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

Technical Requirements

The change in DTD syntax (prior to consolidation of <data> and <data-about> in an entity):

<!ELEMENT relcolspec ((%topicmeta;)?, (%topicref;|%data;|%data-about;)*)>

The change in XML Schema syntax (prior to consolidation of <data> and <data-about> in a group):

<xs:complexType name="relcolspec.class">
    <xs:sequence>
        <xs:group ref="topicmeta" minOccurs="0"/>
        <xs:choice minOccurs="0" maxOccurs="unbounded">
            <xs:group ref="topicref"/>
            <xs:group ref="data-about"/>
            <xs:group ref="data"/>
        </xs:choice>
    </xs:sequence>
    ...
</xs:complexType>

Base processing would change to distribute properties and related links from the column header to the topics referenced in the column cells. Base processing could also use the title of the first topic from the <relcolspec> as the label for the grouped related links from the column in the output for each topic referenced in other columns. At the discretion of the process, the group label can be a hotspot for the link to the first topic or the link can be separate from the label.

New or Changed Specification Language

The Language Reference topic for <relcolspec> would change.
The Architectural topic for map structure would have some additions.

Note: The specification might also consider whether a <data> element in a relcell would distribute to other columns in the same row (providing a horizontal equivalent to this vertical distributive capability).

Costs

The only significant expense is the enhancement of default processing.

Benefits

As users become familiar with the basic horizontal capability of relationship tables, this added function will become useful for more sophisticated definition of the qualifications for column membership. In addition, specializers can take advantage of this capability.

dita message

DITA Proposed Feature #12048