Preservation of attributes when resolving mapref

Jeff: Comments added late on 19 January or early on 20 January. Not sure I'm going to be a lot of help. I'm pretty confused about how this should all work. On the one hand I'd like some simple rules that cover cascading behavior for all attributes. On the other hand sticking to a consistent set of rules may disallow some otherwise useful cases or even lead to outright silly behavior.
My own hope is that there is very little that is special about a map referencing topicref or topicref specialization and that all topicrefs (map or topic referencing) follow pretty much the same rules. There are already two exceptions to this that I am aware of: 1. A map referencing topicref does not add to the hierarchy of the document as a regular topicref does. In this sense it is more like a topicgroup, but a topicgroup with an href value. 2. The behavior of a map referencing topicref that contains nested topicrefs is not well defined and its use is discouraged.

Questions have come up about how to preserve attributes when resolving mapref. This is an initial attempt to lay out some of the use cases for further discussion at the OASIS TC.

For each of the following, an additional consideration may be whether it matters if the attribute is set explicitly, inherits a value, or uses an application default. For example, when the application defaults to "local" for the scope value, will there be any difference in how these map references are evaluated? 

Case 1:
<map><topicref href="target.ditamap" format="ditamap"/></map>
Case 2:
<map><topicref href="target.ditamap" format="ditamap" scope="local"/></map>
Case 3:
<topicref href="something.xml" scope="local">
  <topicref href="target.ditamap" format="ditamap"/>
</topicref>

Jeff: My take on all three cases is that @scope has the value "local" either as a processor supplied default (case 1), an explicit value (case 2), and as a processor supplied inherited default (case 3).

Jeff: It is less clear to me what @scope="peer" or @scope="external" means for a map referencing topicref. Is this always legal? Never legal? Sometimes legal and sometimes illegal? Or is this implementation dependent?
Robert: I know of people using scope="peer" when pulling in a map to indicate that topics in the target map are "peer". It's one of the use cases prompting me to try to clarify all of this.

The TOC attribute

For the following: 

<topicref href="target.ditamap" format="ditamap" toc="___"/>

What happens when:

Jeff: I agree, unless the referenced map contains a reltable in which case @toc="no" applies within the reltable.

Jeff: My first reaction is yes, @toc in a higher level map overrides except in reltables. It is what other attributes do when they cascade from a map to a map. And the alternative is to make the cascading behavior dependent on the values and I'd really like to avoid that. I'd also like to avoid making a distinction between explicit values and default values. And the default when @toc isn't specified is "yes", so in theory any higher level map that references a lower level map will supply some @toc value that will override whatever values are in the lower level map. And sadly, that isn't very useful.

Jeff: I'm not sure what to do about this. The solutions I come up with are all complicated and confusing. For example we could have some new values for @toc such as "always", "never", "default" in addition to "yes" and "no" and make @toc allow multiple spece delimited values so that cascading values would be combined rather than replacing the values in the lower level map. Then there would be a precedence for how a mix of the values would be evaluated ("always" and "never" take precedence over "yes" and "no". "no" takes precedence over "yes".

Jeff: Yes except within reltables. Not sure how useful this is, however.

Jeff: Again I'd hope so, but I'm pretty unsure of myself on all of this and wonder how useful this is.

Jeff: I hope we can stick to the idea that the higher level author can override most everything that the lower level map or topic author has written.

Keeping in mind the following known use cases, which may or may not be possible:

Jeff: The more I think about this the more I think we can't make this work with just "yes" and "no" values for @toc and I am starting to wonder if we don't need to add both new attributes and new values to do everything we want to do without overloading @toc top the point where it isn't possible for anyone to understand or remember how this should work.

Su-Laine: Jeff, is the new @processing-role attribute that we're adding to DITA 1.2 not what you're looking for? I think, by the way, that the %topicref-atts-no-toc; attribute set should probably have @processing-role set to "resource-only" instead of having @toc set to "no". Doing this might eliminate the need to have special rules for reltables.

The linking attribute

For the following: 

<topicref href="target.ditamap" format="ditamap" linking="___"/>

What happens when:

Jeff: That works for me.

Jeff: This is getting us back into having to build specific knowledge of attribute values into the cascading behavior, something that I'd like to avoid, but for practical reasons it may not be possible to avoid.

The scope attribute

<topicref href="target.ditamap" format="ditamap" scope="___"/>

What happens when:

Note: I know of users today that expect scope="peer" to apply "peer" to every target in the map, but I do not think that their cases include any truly external topics.

Jeff: I wonder if @scope, @type, and @format should cascade within a document, but not from one document to the next?
Robert: I know of people using @scope today with the expectation that it cascade (which is one of the items prompting this issue here)

Jeff: Does keyref help us out here more than any cascading rules we might come up with?
Robert: If every key is defined together with scope/type/format, and topics are only referenced using keys, then it would ... but (I think) this would also mean that to override the scope values on a nested map, you would need to re-define every key simply to reset the scope.

Jeff: For other reasons I've been wondering if having @scope, @type, and @format cascade at all even within a document is the right thing to do. Mostly this has to do with the inherited defaults changing unintentionally as one moves a topicref around within a map using copy/cut/paste or drag/drop.

Other attributes

The same questions could arise for other attributes that only take a single value (unlike property attributes like "audience", which can be additive):

Jeff: The solution for some of these may be to have them cascade within a document, but not between documents. @translate is an example of that and seems like it should work like @xml:lang and @dir. Perhaps other attributes should become multi-valued so their values would be combined rather than being overridden. @locktitle doesn't cascade does it? It just determines if the current navtitle in the map should override a navtitle or title in the referenced map or topic.
Robert: I could see translate being used to cascade through a map - it defines metadata about the topic (I do not consider this translatable) rather than an inherent property (language). For example, if I have a set of information I cannot afford to translate, or which does not belong to me and will be translated by somebody else later, I could reuse that map with translate="no". Don't know if anybody could support this easily, but I can see the use case. About locktitle - I think it does not cascade within a map; this was clarified in DITA 1.1, if I remember correctly.

MaprefResolution (last edited 2009-08-12 18:02:57 by localhost)