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: RE: [dita] Proposal 12048 - expanded header for reltable

Your comments and clarifications make a lot of sense.  Some replies and a few more comments edited into the text below.




From: Erik Hennum [mailto:ehennum@us.ibm.com]
Sent: Monday, July 09, 2007 7:57 PM
To: Ogden, Jeff
Cc: dita@lists.oasis-open.org
Subject: RE: [dita] Proposal 12048 - expanded header for reltable


Hi, Jeff:

Thanks for the close read. Some responses ...

"Ogden, Jeff" <jogden@ptc.com> wrote on 07/08/2007 10:55:30 PM:
. . .

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

I still like “hint”.  The Arbortext Editor does produce edit time warnings if someone tries to place a topicref into a reltable column when the type doesn’t match the type of the relcolspec. It isn’t a constraint or validation exactly since the user can choose to ignore the warning. We’ve had requests to automatically place topicrefs in the correct column in a reltable based on type. We haven’t had requests to do anything similar with attributes other than type.

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

But the inheritance hierarchy is all we have in DITA 1.1 to explain how relcolspec and topicmeta within relcolspec work. Having to introduce new special case rules for relcolspec as part of this proposal is one of the things that makes we worry about the overall DITA specification getting too large and too complicated.  While I am uneasy, if everyone else is comfortable with adding more special cases, I can get over my uneasiness.

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

This is inheritance to the relcells in a column isn’t it?

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.  

I see it as adding something beyond what is there due to inheritance now.

As with the current DITA, the contents of <relcolspec> apply to every cell in the column (vertical distribution).  

With the current DITA there are some attributes that do not inherit and so would not apply to every relcell.  This proposal adds something new that goes beyond that. That may be OK, but we should be aware that it is a new case that applies just to reltables.

As with <relrow>, the distribution of a <topicref> establishes a linking relationship.

I agree.

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.

I agree.

> 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

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.

Would this be true just within a reltable or would it apply more generally throughout a DITA document? You can probably guess from what I’ve written already that I’d be happier if it applied more generally and were not a special case for reltables.

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

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

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

Right, so isn’t that sufficient? Do we need to allow <data> to be used directly within relcolspec as well? Or why do we have the topicmeta element at all when we could just allow all of the topicmeta contents to be used directly?

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.

I agree that this ship has already sailed. I can live with it.

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

I’d rather not add a navtitle attribute. Attributes on table markup are hard to display visually within the constraints imposed by small cells. I guess I’d rather just add a title element and be done with it.  I’m not sure that topic titles or navtitles will make good group labels in any case.

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

I agree.

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

Hoping that clarifies,

It did, thanks.

Erik Hennum

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