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 

Sent: Wednesday, October 01, 2008
3:06 PM

To: Helfinstine, David; 'Robert D Anderson';
'Michael Priestley'; 'Bruce Nevin (bnevin)'; 'Erik Hennum'

Subject: RE: notes from
yesterday's call about controlled value defaults and other related things

 

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 

Sent: Wednesday, September 24,
2008 3:53 PM

To: Helfinstine, David; 'Robert D
Anderson'; 'Michael Priestley'; 'Bruce Nevin (bnevin)'; 'Erik Hennum'

Subject: notes from yesterday's call
about controlled value defaults and other rrelated things

 

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

> Sent: Tuesday, September 09, 2008 10:40 AM

> To: 

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

 

 
Explicit values on shortdesc in
     the map 

 
DTD defaults for shortdesc
     attributes in the map 

 
Cascades to shortdesc in the
     map from ancestors in the map 

 
Controlled value defaults
     applied within map 

 
shortdesc from the map injected
     into the topic 

 
Cascades from map to topic
     (maps to maps or maps to topics, the order of  5 and 6 could be
     reversed)

 
Cascades from ancestors within
     the topic. 

 
Controlled value defaults for
     the topic applied to shortdesc

 
Other processor supplied
     default applied to shortdesc

 

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: 

 

 
What attribute values does a
     generated related-links element have when it is injected into a topic that
     does not have an authored related-links section.

 

 
Are any attribute values from
     the map added to or merged with attributes on an existing authored
     related-links element in a topic?

 

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.

>