RE: [dita] Inheritance of attributes through mapref

["Su-Laine Yeo" <su-laine.yeo@justsystems.com>]

Thanks Jeff for the nice summary.

 

I can’t say I’ve gotten my head around all aspects of these issues. However, some housekeeping regarding #5 “Cascading as part of conref processing” is that the role of the dita-use-conref-target value should be mentioned.

 

Regarding the issues I raised earlier about the cascading of conditional attribute values, I haven’t heard any discussion since Thursday. So I plan to write a proposal for DITA 1.3 to better accommodate the case of including partially-conditional child documents in a parent document set.

 

Cheers,

Su-Laine

 

Su-Laine Yeo
Interaction Design Specialist

JustSystems Canada, Inc.
Office: 778-327-6356
syeo@justsystems.com

www.justsystems.com

 

 

 

From: Ogden, Jeff [mailto:jogden@ptc.com]
Sent: Friday, April 17, 2009 9:36 PM
To: dita
Subject: RE: [dita] Inheritance of attributes through mapref

 

Let me try to outline where I think things stand. I’m doing this as much to get this straight in my own mind as to make an argument for a specific solution. 

 

There seem to be three questions left to resolve.  I’ve marked them in orange.

  

1. Do multi-valued attributes override or merge when they cascade from map to map?  I think they should work the same as they do for map to topic cascading, that is they should merge.  See item #2 below.

 

2. While @base and attributes specialized upon @base do not cascade within maps or topics, it is unclear if @base or a specialization based upon @base cascades from a map to a topic or not. I’m guessing that they should.  See item #3 below.

 

3. We need to confirm the behavior for @scope when cascading from map to map.  See item #3 below.

 

I think we have five situations where attribute values can cascade.  The first four are related and are applied in order from #1 to #4. The fifth is @conref processing and is separate.

 

#1 Cascading within a map.

 

This is already well defined as part of DITA 1.1 and I don’t think we are making any changes for DITA 1.2.

From the DITA 1.1 Spec:

Inheritance is additive except where this would cause a conflict. When there is a conflict, the value

defined closest (most specifically) to the topicref takes effect.

Here “additive” means what I’ve been calling “merge” and there is no overriding.

There is a specific list of attributes that cascade within a map and the implication is that other attributes do not.

@base and attributes specialized form @base do not cascade within a map (or a topic).

Attribute values that cascade cascade within the within the entire map, they never merge or override, but they always supply default values for attributes that don’t have explicit values and which do not have default values assigned in the DTD or Schema.

 

#2 Cascading from a map to a map

 

This is not well defined as part of DITA 1.1 and we are trying to do a better job for DITA 1.2. 

 

The idea is that values in one map cascade from that map to the top element in a referenced map or to the top element in a reference branch within a map. And then within the referenced map cascading follows the rules outlined for cascading within a map (#1).

 

It seems clear that for single valued attributes, that the values in the referencing map override or replace the values on the top element in the referenced map or branch.

 

What is still unsettled is what happens for multi-valued attributes.

 

There is a description and a long table that defines “Metadata inheritance between maps and topics” in the DITA 1.1 Architecture Spec. I don’t think we are making changes to this for DITA 1.2. But that discussion is about cascading of metadata elements more than it is about cascading of attribute values.  However, some of the concepts outlined for elements may be useful to us as we work to define the map to map cascading behaviors for attributes:

For each element in the topicmeta, the following table provides different behaviors.

* Does it cascade to other topics in the map? This indicates whether the specified meta value cascades

to nested topicrefs. For example, setting an audience to ″user″ implicitly means that other topicrefs

within that branch of the map also have an audience of ″user″. Elements like linktext, which can apply

only to the specified target, do not cascade.

* What is the purpose when specified at the map level? The map element allows for metadata to be

specified for the entire map. This column describes what effect, if any, each element has when specified

at this level.

In the “Does it cascade to other topics in the map” column you see “Yes”, “No”, and “No, unless …”.

In the “What is the purpose when specified at the map level” you see many items that say “specify something for the entire map”, and a few that say “no stated purpose” or “no stated purpose until …”.

 

@base and attributes specialized upon @base do not cascade from map to map.

 

The attributes that cascade from map to map are the same as the attributes that cascade from within a map, with the exception of @format and @scope. 

 

The other thing that was still unsettled was if @scope behaved like @format or if it cascaded from map to map. Robert recently checked with a client that depended on @scope cascading from map to map and determined that it would be acceptable if @scope didn’t cascade. So if the TC is comfortable with treating @format and @scope the same way in this respect this question is settled.

 

#3 Cascading from a map to a topic

 

The same description and a long table mentioned above defines “Metadata inheritance between maps and topics” in the DITA 1.1 Architecture Spec. I don’t think we are making changes to this for DITA 1.2. But that discussion is about cascading of metadata elements more than it is about cascading of attribute values.

 

Cascading of attribute values from maps to topics is not so well defined in DITA 1.1 and we are trying to do a better job for DITA 1.2.

 

One approach is to use the concepts outlined for cascading of metadata elements and apply them to the cascading of attribute values from maps to topics. Here are the high level concepts outlined for map to topic element cascading in the DITA 1.1 spec.:

For each element in the topicmeta, the following table provides different behaviors.

* How does it apply to the topic? This describes how the metadata in a topicref interacts with the

specified topic. In most cases, the properties are additive, within the current context. For example, when

an audience is set to ″user″ within a topicref, this means that the audience for the specified topic is

″user″ when viewed within this context. This is in addition to any audience values specified within the

topic, and does not apply to the topic when it is viewed in other contexts.

And most of the entries in this column of the table say “Add to the topic”, but a few say “Replace the one in the topic” and “Not added to the topic; applies to links created based on this occurrence in the map”. And I take “additive”, “in addition to”, and “add to” to mean what I have been calling merge.

 

It is probably better to think and talk about elements and attributes as defining properties where the properties cascade from maps to topics.

From the section on “Topic properties in topics and maps” in the DITA 1.1 Architecture Spec:

The properties of a topic (including metadata attributes and metadata elements) can be specified in the

topic itself or in references to the topic within maps.

. . .

If a property is set in both the map and topic, the map properties are additive if the property (such as the

audience type) takes a list of values. If, instead, the property (such as the importance) takes a single

value, the map property overrides the topic property.

 

The idea is that properties defined by elements or attributes in a map cascade from that map to the top element in a referenced topic or to all of the top topic elements in a ditabase. And then within the referenced topic(s) cascading follows the rules outlined for cascading within a topic (#4). The list of attributes that cascade from maps to topics is the same as the list that cascades from maps to maps.

 

While @base and attributes specialized upon @base do not cascade within maps or topics, it is unclear if @base or a specialization based upon @base cascades from a map to a topic or not. I’m guessing that they should.

 

#4 Cascading within a topic.

 

I had thought that this was already well defined as part of DITA 1.1 and I don’t think we are making any changes for DITA 1.2, but the DITA 1.1 Architecture Spec. really says very little about cascading within a topic.  However, there are some comments about this in the DITA 1.1 Language Spec.

@scope: If no value is specified, but the attribute is specified on an ancestor within a map or within the related-links section, the value will inherit from the closest ancestor.

@props and many other attributes: If no value is specified, but the attribute is specified on an ancestor within a map or within the related-links section, the value will inherit from the closest ancestor

@type: Processed as if the target were of type ″topic″, or inherited from an ancestor

[this and a number of other descriptions don’t say the bit about “within a map or within the related-links section”, but I assume that that is implied -Jeff].

<linkpool>: Attributes set on <linkpool> are inherited by its descendants. For example, if you’ve got a <linkpool> that contains all external links, you can set scope=″external″ on that outer<linkpool> element and leave it off the links it contains.

 

I assume, but haven’t checked, that the list of attributes that cascade within the related-links section in a topic is the same as the list of attributes that cascade within a map (#1) to the extent that the same attributes occur in both places.

 

@base, attributes specialized upon @base, @status, and @importance do not cascade within a topic or a map.

 

So attribute values that cascade only cascade within the related-links section of topics and then they never merge or override, but they always supply default values for attributes that don’t have explicit values and which do not have default values assigned in the DTD or Schema.

 

#5 Cascading as part of conref processing.

 

This is already well defined in the DITA 1.1 Architecture Spec. and I don’t think we are talking about any changes for DITA 1.2. In this case attribute values override and never merge between the conref source and target elements and once conref processing is complete, attribute values cascade or not within the conref section according to the regular cascading rules (#1 and #4).

 

There are special rules for @xml:lang, @dir, and @translate which are described in the DITA 1.1 Architecture Spec.

 

     -Jeff