[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: FW: notes from call about controlled value defaults and other related things
|
Included below are notes from the conference call several of us had back on 24 September to talk about processor supplied defaults and cascading values. The call was initiated by Michael to address a question that was originally asked by Robert. Robert’s original note to the DITA TC list on 9 September is included below.
I should have sent these notes to the DITA TC earlier.
Please send any comments, corrections, or questions to me, to the six of us who were on the call, or to the DITA TC e-mail list. If necessary we can talk about this on a future DITA TC call, but at least right now I am assuming that that isn’t necessary and this will all be reviewed again when it is written up and included in the DITA 1.2 Architectural Specification.
-Jeff
From: Ogden, Jeff
No responses to this note. Can I assume that what I wrote is perfect? If that isn’t the case, please let me know.
-Jeff
From: Ogden, Jeff
This isn’t the description that I agreed to write at the end of yesterday’s call. I still plan to produce the description, but I wanted to get some notes written down soon before I forgot what we talked about and agreed to on yesterday’s call. Let me know if any of my understandings are off base.
The main thing we agreed to yesterday is that within a document the order in which effective attribute values are determined is:
1. Explicit values 2. DTD or XML schema defaults 3. Cascades within the document (override or combined) 4. Cascades from a higher level doc to this doc a. maps to maps or maps to topics, b. override or combined, c. includes cascading of values within this doc when appropriate 5. Controlled value defaults applied within the document 6. Other processor supplied defaults.
Before attributes values cascade from a higher level doc to a lower level doc (step #4), the attribute values within the higher level doc are determined using the same 6 steps. The source of the attribute value in the higher level document never matters when values cascade into lower level documents.
More notes edited into the text below.
-Jeff
________________________________________
> -----Original Message----- > From: Robert D Anderson [mailto:robander@us.ibm.com] > Sent: Tuesday, September 09, 2008 10:40 AM > To: dita@lists.oasis-open.org > Subject: [dita] Cascading / inheritance of default values > > A question came up when writing up the Controlled Values proposal, and Erik > Hennum suggested I take it to the TC list. I realize it's too late for > today's call, but hopefully this will get discussion started. > > The controlled values proposal allows you to select values that are valid > in a given attribute - for example, you can provide an enumeration for the > audience attribute. At the same time, you can specify a default value from > the enumeration. > > This raises a question about cascading attributes. In a map, many > attributes (like audience) cascade to nested topicrefs. If a default value > for @audience is set in the DTD, this means it applies everywhere - parsers > see it the same as a specified value, it is the clear default for every > instance of the element. So, setting a value on the topicref will not > override nested topicrefs, because they pick up the default. > > What happens if a default is specified through a controlled values file? > In that case, there is a default, but it is a processor controlled default. > It will not show up in a file unless / until a processor reads the file, > determines the default, and then applies it. > > So - assume that I have a controlled values file which defines a default > of audience="us" among the valid values (us | them | everybody). What > audience applies to the following topics? > > <map> > <!-- First pull in the controlled values --> > <topicref href=""values.ditamap"" format="ditamap"/> > <topicref href=""a.dita"> > <topicref href=""b.dita"" audience="them"> > <topicref href=""c.dita"/> > </topicref> > </topicref> > </map> > > Topic A will have audience="us", topic B has audience="them", what does > topic C have?
Assuming that the controlled value default of “us” is specific to topicref elements:
The effective values are:
topicref to A: “us” (from the controlled value default) topicref to B: “them” (from the explicit value) topicref to C: “them” (cascades from the explicit value on B)
> Thanks - > > Robert D Anderson > IBM Authoring Tools Development > Chief Architect, DITA Open Toolkit > (507) 253-8787, T/L 553-8787 (Good Monday & Thursday)
________________________________________
> From: Ogden, Jeff > Sent: Thursday, September 11, 2008 6:03 PM > To: 'Robert D Anderson' > Cc: Helfinstine, David; 'Michael Priestley' > Subject: clarification on cascading behavior > > Robert, > > Sorry for the long note. > > Dave and I (mostly Dave) have been working on updating the Arbortext DITA Composition Pipeline to reflect some of the newer cascading/inheritance behavior between maps and topics and between maps and maps and topics as described in DITA 1.2 Feature #12055. At the same time I’ve been working to update the portions of the DITA Architecture Spec. that talk about this. > > This work has gotten us to reread the DITA 1.1 spec. more carefully (perhaps too carefully) and we’ve realized that some of our previous understandings of cascading/inheritance may not have been quite right. Before we go much further we want to double check things with you to make sure that our new understanding is in fact correct and that I get the right information into the DITA 1.2 spec. > > I think we understand the issues related to cascading between documents (maps to topics, or maps to maps to topics). In what follows I am [mostly] just talking about cascading within a single file (single map or single topic file or ditabase). The big change for us is that we had been assuming the attribute values that cascade within maps also cascade within topics. But a careful reading of the DITA 1.1 Architecture Spec. says that attribute values cascade within a map, but not within topics. There are also statements in the DITA 1.1 Language Reference that talks about cascading specific attribute values in the context of the related-links section. So our main question is, is this right, that attribute values that cascade only cascade within the related-links section of a topic and not more generally within a topic?
This was all correct with the addition that attribute values cascade from a topicref to a topic tag as well as to any nested topic tags, but these values do not cascade to non-topic sub-elements within the topic.
And there is an open question on cascading of conditional processing attribute values within the related-links section of topics. See the comment after next below.
> So @audience would not cascade in this example: > > <section audience="Novice"> > <p audience="Expert">here the effective audience value is “Expert” and not “Novice Expert”</p> > <p>There is no specific audience value for this paragraph</p> > </section> > > Is this right? > Yes. > > And for this example: > > <related-links audience="Novice" scope="external"> > <link audience="Expert" scope="peer">here the effective value of scope is peer and audience is “Novice Expert”</link> > <link>here the effective value of scope is “external” and audience is “Novice”</link> > </related-links> > > Is this right?
Yes, this is correct if you follow the DITA 1.1 spec, which says that conditional processing attributes do cascade within related-links within topics. But during yesterday’s call didn’t we have a different understanding—that only a few attributes cascaded within the related-links section and that the conditional processing attributes did not?
> Are there other attributes beyond @scope and the conditional processing attributes that cascade within the related-links section in topics? In particular do @format or @type cascade? They aren’t described as cascading within a topic in the DIA 1.1 Language Reference, but I wonder what use @format and @type are on the related-links, linklist, and linkpool elements are, if they don’t cascade?
Yes, format and type both cascade within a related-links section in topics, need to make sure that the DITA 1.2 spec. says this.
> Is there anything else that cascades within a topic?
Nope.
> @xml:lang, @dir, or @translate are listed as cascading within a map. I think the DITA 1.1 Architecture Spec. says or at least implies that @xml:lang, @dir, and @translate cascade from maps to maps and from maps to topics, but some time ago I think we decided that this is wrong and they only cascade within maps and not between maps and other maps or topics. Am I remembering this correctly?
Yes.
> Do @xml:lang, @dir, or @translate cascade within a topic? Within the related-links section of a topic?
No and no. While they do not cascade within a topic, they are effective in much the same ways as if they did cascade. That is, if someone sets xml:lang=”fr” on a topic tag, then all of the content in the topic including content in nested topics is assumed to be French. We need to take care that we don’t change the semantics for xml:lang that are defined elsewhere (in the XML spec.). So far I think we are OK, but it wouldn’t hurt for someone who knows more about xml:lang than I do to double check.
> There is a column in several of the long tables that list translation elements in the DITA 1.1 Architecture Spec. titled “Inherits everything from ancestor” and it says “yes” for most elements. Does this imply something about cascading of @xml:lang, @dir, or @translate within a topic or is this a different use of “inherits” that has to do with specializations and not ancestor elements in the document instance? And the same tables list “no” for a few elements that can occur in maps (completed, day, month, revisionid, started, year), so does this override the general instruction elsewhere in the Architecture Spec. that says that these three attributes cascade within a map?
We can ignore this since this was a different use off the term “inherits”. I’ll reword this in the DITA 1.2 spec. to make this clearer.
> The rest of this is a summary of our current understanding, just to double check: > > Within a map both scope and audience would cascade. And within a map scope might conflict and conflicts would be resolved in favor of the value closest to the reference element. Also within a map audience will not conflict and multiple values will be combined.
Yes.
> Between maps (map to map) values from the maps cascade to lower level maps and within the map they cascade to lower level elements, with conflicts being resolved in favor of the higher level map values when cascading from map to map and in favor of the values closest to the reference element when cascading within the map. Cascading occurs first [[within the higher level map, then]] from map to map and then within the [[target or lower level]] map, so values from a higher level map can cascade to lower level elements within lower level maps.
Yes, with the clarification added above.
> Between maps and topics values cascade from the map to the topic element (or in the case of peer topics within a ditabase to all of the topic level topic elements), but they do not cascade further to lower level elements within a topic (not even to the topic element of nested topics). And in this case, as in the map to map case, conflicts are resolved in favor of the values from the higher level map and attributes that allow multiple values are combined.
This is right except for the bit about “not even to the topic element of nested topics”. Values do cascade from topicrefs to nested topic elements.
> Specialized attributes based on props do cascade within maps and within the related-links section of topics, but specialized attributes based on base do not.
I think this is mostly right, but @props and attributes specialized on @props may or may not cascade within the related-link section of topics depending on how we answer this question for all of the conditional processing attributes.
We didn’t talk about this on yesterday’s call, but while @base and attributes specialized on @base do not cascade within maps or topics, I think they do cascade to topic elements, both parent topics and nested topics, but not to non-topic sub-topic elements.
> And it is only after all of this cascading between and within documents is complete, that implicit [processor supplied] default values such as @scope=”local” are applied for values that are not set on an element. I’m not sure if this case ever comes up, but we’d never combine explicit values with implied default values for attributes that allow multiple values.
The above isn’t quite right. Within a document the order in which effective attribute values are determined is:
1. Explicit values 2. DTD or XML schema defaults 3. Cascades within the document 4. Cascades from a higher level doc to this doc (maps to maps or maps to topics) 5. Controlled value defaults applied within the document 6. Other processor supplied defaults
Before attributes values cascade from a higher level doc to a lower level doc, the attribute values within the higher level doc are determined using the same 6 steps.
> Are these understandings right? > > -Jeff
> From: Helfinstine, David > Sent: Friday, September 19, 2008 4:59 PM > To: Ogden, Jeff > Subject: Questions for Tuesday Meeting > > Jeff, > Here are a couple further questions I see from my notes. > > Further questions for attribute processing in maps and cascading maps: > > 1) So the question is, do the generated links get cascaded values from just the map or from the map and the topic if there is an authored related-links element in the topic.
I don’t think this was explicitly answered during our call, but I suggest that we should apply the same rules that were outlined above.
> I guess there are three cases: > (i) the related-links element itself and its content is generated, > (ii) the related-links element and all of its content is authored, and > (iii) the related-links element is authored and some of its content is authored and some is generated. > > So, if I author a related-links element and it includes some cascadable attributes and some generated links are added and those didn't inherit values for the cascadable attributes on the authored related-links element from the reltable or elsewhere in the map, what happens? > > 2) What is the correlation with the attributes set on a topicref and the possible setting of attributes in a topicmeta. How do these affect the child / children topics that these refer to?
Not sure this was answered during the call either.
An example would be when a shortdesc is added to a topic from a map, with it's own attributes on it.
Here is a possible approach:
shortdesc can’t appear within related-links can it? If this example wehat about an element that could appear within related-links (linktext, desc), then we’d need to add:
6.5 Cascades from ancestors within related-links to the new element for those attributes that cascade within related-links.
This is probably the approach to take for dealing with the questions about attributes for generated related-links too. The unanswered questions are:
I think we should assume none for the first case and no for the second. Any attribute values from the map should be explicit on the generated link elements injected into the topic from the map.
And something I didn’t think of before, but the DTD defaults could be different between one map and another or between a map and a topic. I don’t think we need to do anything about this. It should more or less fall out automatically.
> 3) The issue of cascading as far as a topic vs. cascading all of the way into the elements of a topic.
This was answered as described above. Cascade from maps to topic tags and nested topic tags, but not to sub-topic elements within the topics.
> 4) The issues around the language attributes and their inheritance or cascading
They cascade within a map, but not from map to map or from map to topic, and not anywhere within a topic. While they do not cascade, they do have an effect on child elements unless overridden by additional attribute values on the children.
> Thanks. > > - Dave H. > |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]