DITA Proposed Feature #12048
Add header rows to reltables
Currently: The <reltable>
provides a <relheader> element that provides a <relspec> element for
each column. The <relspec> 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. (For more
detail about the currently specified capabilities, see http://docs.oasis-open.org/dita/v1.1/CD02/langspec/langref/relcolspec.html.)
Broaden the kinds of properties that can be specified for the top-level <topicref>
elements in column by means of the <relcolspec> element to include properties
specified with the <data> element and also to contain <topicref> elements.
The top-level <topicref> elements within the <relcolspec> element have
relationships with every <topicref> in the column.
if the <relcolspec> contains a topic reference to a troubleshooting directory
topic, every <topicref> in the column will have a link to the troubleshooting
directory topic. This 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 relationships between parent and child <topicref> elements in a map
More generally, in the same way that a textual column header
applies to values in all column cells of a content table, a column header
with vertical distributive capability is consistent with the expected vertical
and horizontal structure of a table.
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 specify properties and relationships common to all of
the topics referenced in a column of a relationship table.
- Make it easy to motivate writers to refer to a desired kind of topic by
indicating complex properties or links expected of the topic.
- Make it easy to label the groupings of related links at the bottom of
the topic in typical output.
- 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
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.
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 retail business has analysts who write discussions of sales trends for
a product type at a store location.
The analyst uses a specialized <data>
element in each column header to specify the name and address for the store
location associated with the column. In each row of the <reltable>, the
analyst puts the topics about a product type, assigning each topic to the
column for the appropriate store location.
The processing associates
the store location data from the column with each topic in the column, supporting
retrieval based on store location. The location data in the heading also encourages
other analysts who contribute to the <reltable> to be careful to put analysis
topics in the correct column. (Note that this use case might also benefit
from a directory page for each store location in the column header.)
- 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).
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.
This proposal expands the content model of
the <relcolspec> element. The proposal doesn't introduce new elements or
The content model
of the <recolspec> element changes to allow any number of <data> or <topicref>
elements after the optional <topicmeta> element. The <recolspec> element
also adds a <title> element to make it easy to specify the label for grouping
The change in DTD syntax:
<!ELEMENT relcolspec ((%title;)?, (%topicmeta;)?, (%topicref;|%data;)*)>
The change in XML Schema syntax (prior to consolidation of <data> and <data-about>
in a group):
<xs:group ref="title" minOccurs="0"/>
<xs:group ref="topicmeta" minOccurs="0"/>
<xs:choice minOccurs="0" maxOccurs="unbounded">
Base processing changes to distribute properties
and relationships contained by the <relcolspec> element to the top-level
<topicref> elements in the cells of the column. In particular:
- Attribute and <topicmeta> properties are copied to each top-level <topicref>
in a cell as currently. Attributes that cascade through the DITA inheritance
mechanism in the navigation hierarchy can, by virtue of the copy, cascade
from a top-level <topicref> to any contained <topicref> elements.
- Similarly, <data> properties are copied to each top-level <topicref>
in a cell. In the same way that a <topicref> can prevent the copy of an
attribute value by setting the same attribute, a <topicref> element can
avoid receiving a copy of a <data> element by containing a <data> element
with the same name or of the same specialization. As with the navigation hierarchy,
<data> elements do not cascade from top-level <topicref> elements to
any contained <topicref> elements.
- Consistent with horizontal related linking across the <topicref> elements
in distinct cells within a row, each top-level <topicref> element contained
by the <relcolspec> has related links with each top-level <topicref>
in the cells of the same column.
In addition, base processing uses the <relcolspec> to establish
the label for the grouped related links from the column in the output for
the topics in other columns. The order of precedence for establishing the
label consistent with other DITA linking:
- If the <relcolspec> contains a <title> element, that is used.
- If not, the top-level <topicref> elements are examined in sequence.
- If a <topicref> has a navtitle attribute and doesn't have an href attribute
(as with the <topichead> specialization), doesn't refer to a DITA topic
(as with a reference to an HTML or PDF resource), or does have a locktitle
attribute of "yes", the processor gets the title from the navtitle attribute.
- If the <topicref> has an href attribute that refers to a DITA topic,
the processor gets the <navtitle> element or, failing that, the <title>
element from the topic.
- Otherwise, the processor tries the next <topicref> element.
Note: Attribute values and other properties of <topicref> elements
within <relcolspec> do not distribute to the <topicref> elements in
the column. These properties apply to the referenced topic. Similarly, subelements
of top-level <topicref> elements in the <relcolspec> or cells do not
participate in vertical related linking. That is, only the contents of <relcolspec>
distribute vertically within the column.
New or Changed Specification Language
- The Language Reference topic for <relcolspec> would change.
- The Architectural topic for map structure would have some additions.
Note: In the future, the DITA community might consider setting defaults
for distribution horizontally across a row with a <relrowspec> element.
The only significant expense is the
enhancement of default processing.
Providing more mechanisms for identifying
the commonality of a <reltable> column and for encouraging consistency
within the column makes it easier for the adopters to manager relationships
between content. In addition, specializers can take advantage of this capability.