OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Proposal 12048 - expanded header for reltable (revised)


Hi, Esteemed TC:

I've updated the reltable header proposal to reflect the clarifications from the correspondence with Jeff Ogden:


For your convenience, a formatted version of the DITA proposal is appended to this note.

While I will be on vacation next week, I believe the plan is to discuss this item on Tuesday and, if no additional discussion is needed, proceed to a vote.


Many thanks to Jeff for giving it such close attention.


Erik Hennum
ehennum@us.ibm.com


(See attached file: IssueReltableHeader12048.html)
Title: DITA Proposed Feature #12048

DITA Proposed Feature #12048

Add header rows to reltables

Longer description

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

Proposed: 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.

For instance, 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 navigation.

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.

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.

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

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 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 related links.

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:complexType name="relcolspec.class">
    <xs:sequence>
        <xs:group ref="title" minOccurs="0"/>
        <xs:group ref="topicmeta" minOccurs="0"/>
        <xs:choice minOccurs="0" maxOccurs="unbounded">
            <xs:group ref="topicref"/>
            <xs:group ref="data"/>
        </xs:choice>
    </xs:sequence>
    ...
</xs:complexType>

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:

  1. If the <relcolspec> contains a <title> element, that is used.
  2. 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.

Costs

The only significant expense is the enhancement of default processing.

Benefits

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.



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]