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 concept
and the 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
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
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:
A DITA-sensitive editor would render this <reltable> as a table to visualize the vertical and horizontal associations:
This relationship table establishes the following links:
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.
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.
This proposal expands the content model of the <relcolspec> element. The proposal doesn't introduce new elements or attributes.
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:
The change in XML Schema syntax:
Base processing changes to distribute relationships contained by the <relcolspec> element to the <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.
Consistent with horizontal related linking across the <topicref> elements in distinct cells within a row and hierarchical linking between a container parent <topicref> elements and contained child <topicref> elements, each <topicref> element contained by the <relcolspec> has related links with each <topicref> in the cells of the same column.
The title for the link to the header topics is established in the typical way for a <topicref> context:
yes, the processor gets the title from the navtitle attribute.
no, the processor gets the <navtitle> element (or, failing that, the <title> element) from the topic.
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
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.
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.
Improves support for link management on a basis other than the information type. The enhancement makes it easy to title the group of related links and makes it easy to encourage a consistent grouping principle by means of links to a common directory topic. Otherwise, adopters have to customize processing to get an equivalent capability.
Supports specializations that take advantage of this capability.