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

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

Hi, Jeff:

Thanks for the close read. Some responses ...

"Ogden, Jeff" <jogden@ptc.com> wrote on 07/08/2007 10:55:30 PM:
>
> The business about constraints isn’t anything new and in fact
> there aren’t really any constraints imposed by the relcolspec or at
> least not any constraints that are enforced.  Rather than
> constraints the relcolspec might be viewed as providing a hint to an
> author about how the column in the reltable is to be used.

Apologies for the confusion caused by a poor choice of terms
on my part.

XML processors aren't expected to enforce any rules associated with
the relationship of the contents of the <relcolspec> and <relcell>
elements for a relationship table column.  (Also, the <relcolspec>
header has nothing to do with a separate proposal for constraints
on content models, which is progressing in a workgroup.)

I do need to convey somehow that, from the author's perspective,
linking is something more than a hint -- that authors will avoid
providing topic references on a column when the topics shouldn't
receive the link to the header topic, which thus provides a kind
of weak validation (but that's another loaded term).

> The proposal calls for the addition of topicref to the content model
> of relcolspec. This would provide a feature somewhat similar to the
> inheritance that already exists for topicmeta.  It is different in
> that topicrefs themselves aren’t inherited elsewhere in DITA
> documents, although some of their attributes might be.  

I'd suggest the analogy to the cascade of values down the
inheritance hierarchy is a little misleading.

The relationship table today provides a method of distribution
across cells.

The <relcolspec> provides a container for properties that apply
to the entire column (vertical distribution).

The <relrow> establishes linking relationships across topicrefs
in different columns (horizontal distribution).

The proposal to add topicrefs to <relcolspec> is consistent
with those existing distribution mechanisms.  As with the
current DITA, the contents of <relcolspec> apply to every cell
in the column (vertical distribution).  As with <relrow>, the
distribution of a <topicref> establishes a linking relationship.

I'd also note a consistency (though not as directly relevant)
with linking relationships established between parent and child
topicrefs in the map hierarchy.

> Is there a need to merge attribute values from a
> topicref in a relcolspec with attribute values on a matching
> topicref that appears explicitly in a relcell?

I wouldn't think so because the attributes of a <topicref> are
properties of the referenced topic and not (via <relcolspec>)
of the column as a whole.

> Is this just a matter of copying the data and data-about elements
> from the relcolspec into the relcell during processing in a manner
> that is like what is done for topicmeta?

Yes, the proposal is to distribute properties expressed with
the <data> element consistent with the distribution of properties
expressed with attributes.

A belated realization:  given that <data-about> isn't about its
container, there would be no reason to distribute it.

> Is there a need to merge matching data or data-about
> elements in some fashion?

Good point.  The proposal should certainly address this issue.

Existing distribution of attribute values from <relcolspec> is
overridden by setting the same attribute within a topicref in the
column.

Applying the same principle consistently, the distribution
of <data> should be overridden when a topicref contains <data>
with the same value for the name attribute or with the same
specialized <data> element.

> Are data and data-about inherited elsewhere within DITA documents?

The <data> element specifies a property of its container element.
In the case of the <relcolspec>, the property applies to the entire
column similar to the attributes of the <relcolspec> or the <topicmeta>
properties.

> Could these elements or specializations more simply be included
> within topicmeta rather than directly within relcolspec?

The <data> element is already included within <topicmeta>.

The <data> element is provided directly within other map contexts,
however, so specializations can express properties more directly
and obviously.  Providing the <data> element directly for <relcolspec>
would be consistent with the map elsewhere.

> There is a comment that says: “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.” I guess I’m not sure why just the
> title form the first topicref would be used. And is this the actual
> title from the topic that is referenced or the value of the navtitle
> attribute on the topicref?  Providing a way to specify the label to
> use for a related link group seems like a good idea, but is using a
> title from a topicref the right way to do this?  Would a topichead
> element work for this as well or better? Or would allowing a title
> element to appear within a relcolspec be a more straight forward approach?

This issue came up in discussion at the Technical Committee.  Because
a group can only have one label, it makes sense to get that label from
the first location where a label can be found.  I would think the
standard <topicref> rules could apply in determining the order of
finding a label.  

That is, if the <topicref> has a navtitle attribute and either doesn't
refer to a DITA topic or does have a locktitle attribute of yes, a
processor should get the title from the <topicref>.  If the <topicref>
has an href attribute that refers to a DITA topic, the processor should
get the <navtitle> element or, failing that, the <title> element from
the topic.  Otherwise, recurse on the first child <topicref>.

Those rules allow matching on an initial <topichead> element and
recursion on an initial <topicgroup> element (given that both are
specializations of <topicref>).

I would support your proposal to add a navtitle attribute
to <recolspec> as the first possible match in a recursive descent
to find a label for grouping.

(In passing, I believe there is a separate proposal arising out
of the translation subcommittee to introduce a <title> subelement
for all elements with a navtitle attribute.)

> There is a note that says: “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).”  ... Is this really
> looking for a relrowspec element to play the same role for rows as
> relcolspec does for columns?

I didn't have a developed thought on the horizontal distribution
of properties but wanted to raise the issue, so thanks for
following up.

You make a good point that, to introduce distribution of attribute
values and <data> horizontally across the row, the best approach
would be to add a <relrowspec> element.  I don't think we should
introduce such an element now, however.

If all that makes sense, I'll revise the proposal accordingly (in particular, remove the
"constraints" terminology).


Hoping that clarifies,


Erik Hennum
ehennum@us.ibm.com