RE: [dita] Proposal 12048 - expanded header for reltable (revised)

[Erik Hennum <ehennum@us.ibm.com>]

Hi, Esteemed TC:

I've updated the reltable header proposal again (appended in HTML for your reading convenience) to:

• Remove containment of <data> by <relcolspec>.
• Expand the example as part of one use case.
• Expand the explanation of the benefits of the proposal for link management.
• Simplify the expected processing for titles on the link groups for a column.
• Describe the linking attribute and collection-type attributes.

Many thanks to Deborah and Jeff for driving clarity and precision with their generous engagement.  

I do want to take up a few of Jeff's concerns more directly. In particular:

> Using the topicref within a relcolspec 
> as a way to establish default topicrefs that are to be included in 
> each relcell of the column. 

If a <topicref> were copied from the header into every relcell in a column, I would expect horizontal linking across the reltable rows to apply to the copied header <topicref>. If so, a header topic in column 2 would end up linked to all topics in columns 1 and 3 in every row but to no topics in column 2 in any row.

That seems counter-intuitive to me and is the inverse of the proposal, which is:

> ... establishing related links between
> topicrefs in the relcolspec and topicrefs in the relcells of the 
> column.

That behavior is consistent with map processing elsewhere.  In the following example, the hierarchy establishes links between the parent topic and child topics:

... <topicref href=""parent.dita">

....... <topicref href=""child1.dita"/> ....... <topicref href=""child2.dita"/> ... </topicref>

In the following example, the reltable establishes links between the topic in one column and the topic in another column of the same row:

... <retable>
... <relrow>
....... <relcell><topicref href=""troubleshoot1.dita"/></relcell> ....... <relcell><topicref href=""message1.dita"/></relcell> ... </relrow>
... </reltable>

Consistent with that behavior, this proposal establishes links between the header topic for a column and the row topics for the same column:

... <reltable>
... <relheader>
....... <relcolspec><topicref href=""troubleshootHub.dita"/></relcolspec> ....... <relcolspec>...</relcolspec>
... </relheader>
... <relrow>
....... <relcell><topicref href=""debugLogin.dita"/></relcell> ....... <relcell>...</relcell>
... </relrow>
... <relrow>
....... <relcell><topicref href=""checkAccess.dita"/></relcell> ....... <relcell>...</relcell>
... </relrow>
... </reltable>

The association of the column header topic with the column row topics becomes visually obvious with the expected table rendering:

+===========================================+=====+
|  <topicref href=""troubleshootHub.dita"/>"  | ... |
+===========================================+=====+
:  <topicref href=""debugLogin.dita"/>       : ... :
: - - - - - - - - - - - - - - - - - - - - - : - - :
:  <topicref href=""checkAccess.dita"/>      : ... :
+===========================================+=====+

That's consistent with the standard table semantics of a strong vertical association of the column header with the column cells in all rows.

Regarding:

> Increase in the size and complexity of the DITA specification.

While that's a good concern that we should bear in mind generally when evaluating what's going into a new version of DITA, it's not isolated to this proposal (as Jeff pointed out in an earlier note). To put it the other way, this general concern should be brought to bear on every proposal and so probably isn't useful to add to every proposal.

Regarding the applicability of that concern to this proposal, I'd note that this proposal doesn't add any new elements to DITA but, instead, adds two existing elements with optional occurrence in one content model. In terms of the increment on the DITA vocabulary itself, changes don't get much smaller than that.

In terms of the increment on processing expectations, the proposal extends current propagation of attributes in one context to add linking. Viewed the other way, the proposal extends existing propagation of links to one new context. The other aspect of the proposal is to introduce a title for related link groups in the output.

One good thing about DITA is that adopters have a low barrier for entry but a high ceiling. I'd submit that this proposal preserves this principle in that:

• The user can get started with maps using simple navigation hierarchies.
• When the user needs related links, the user can add relationship tables.
• When the user needs to manage the types of related links, the user can add relcolspec headers that establish the information type for a column.
• When the user needs categories for link management that are more flexible than information types, the user can add header topics that establish those column categories.

I hope we can discuss and vote on the proposal next Tuesday.


Erik Hennum
ehennum@us.ibm.com


Here's the official XML version:

http://www.oasis-open.org/apps/org/workgroup/dita/download.php/24802/IssueReltableHeader12048.dita


Here's a formatted version:

(See attached file: IssueReltableHeader12048.dita)

IssueReltableHeader12048.dita