[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Inheritance of attributes through mapref
I'm afraid my action on this front has not been completed. I think we are essentially at the same spot we were at previously. The general conclusion is that an attribute on a map reference is equivalent to setting that attribute (or overriding that attribute) on the target map. From that point, the attributes inherit as they normally would within a map. This is true for elements such as toc and linking, which only take a single value. The two open questions are: 1) What about attributes like @audience, which take multiple values? If my map reference has audience="a b", and the map has audience="c", does "a b" override "c", or does this result in "a b c"? If the latter, we will need to come up with an authoritative list of which attributes act this way (as opposed to the override behavior of @toc and @linking). 2) What about the scope attribute? This is intended to describe the scope of the target of the topicref. In the case of a normal topic reference, scope="peer" means the target is not part of the current set of information, and may not be available, but is part of my overall information set (I think of this as a reference from one Eclipse plug-in to another). However, if I set @scope="peer" on a reference to a map - does that scope attribute describe the map (may not be available, part of another information set), or does the scope attribute cascade to the map, essentially resulting in a local map with full of peer topics? In the off-list discussion, Jeff Ogden has been pushing for the first behavior (@scope=peer means the map is outside of the current information set). I now have an action to go back to my users in IBM who are depending upon the second behavior, so we can see what impact this will have and/or see if they have other good reasons to keep this behavior. Thanks - Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit "Ogden, Jeff" <jogden@ptc.com> wrote on 03/24/2009 10:31:25 AM: > RE: [dita] Inheritance of attributes through mapref > > More comments below. I think we are close. > > -Jeff > > > -----Original Message----- > > From: Robert D Anderson [mailto:robander@us.ibm.com] > > Sent: Tuesday, March 24, 2009 8:37 AM > > To: Ogden, Jeff > > Cc: dita > > Subject: RE: [dita] Inheritance of attributes through mapref > > > > Hi Jeff, > > > > > So some properties such as @format cascade within a map, but not > > > from map to map. Other properties such as @linking cascade within a > > > map and from map to map. And still other attributes such as @href > > > don’t cascade within a map or from map to map. Am I following this > > > correctly? If this is correct, it seems OK to me, we just need to > > > explain clearly which category each attribute or property is in. > > > > Yes, this is correct. > > > > > Is there yet another case where a property can cascade from a map to > > > a topic or from a map to a map to a topic and in both cases on to > > > elements within the topic? Are the rules for map to map cascades and > > > the rules for map to topic cascades the same? > > > > I believe they are not the same, mostly because some many attributes > > clearly apply to the map and not to the topic, so they would not cascade > > to > > the topic. We have an Arch Spec topic that covers which attributes cascade > > within a map, and one that covers which topicmeta elements cascade within > > maps and from maps to topics. It would probably make sense to have another > > topic about which attributes cascade. If so - I'd rather start a new > > thread for that. > > A new thread would be fine. > > I’ve thought that having this discussed in different places in the > Arch Spec. makes it harder to understand and so think trying to pull > it together into one discussion would be a good idea. > > What I am hoping for is enough consistency between all of the > cascading rules that someone can remember what the rules are without > having to read and re-read the architecture spec. over and over. > Perhaps that is too much to hope for. > > > > Is @scope in the same category as @format? I’ve always thought of > > > @format and @scope as qualifying the @href value on the current > > > element. > > > > I have some users who strongly believe otherwise. I was on the fence > > originally; the user came back with this argument: > > -------------------- > > Consider this: > > > > <topicref href="a.dita" scope="peer"> > > <topicref href="b.dita"> > > <topicref href="c.dita"> </topicref> > > </topicref> > > </topicref> > > > > and this > > <topicref href="a.dita" scope="peer"> > > <topicref format="dita" href="othermap.ditamap"/> > > </topicref> > > > > where othermap.ditamap contains: > > > > <map> > > <topicref href="b.dita"> > > <topicref href="c.dita"> </topicref> > > </topicref> > > </map> > > > > I think a user would expect these to be exactly equivalent. The > > first > > map would include the second, and scope="peer" would apply to the > > topicrefs down the tree. > > -------------------- > > I’ll need to think about this some more. It makes @scope a special > case when @format=”ditamap” and that makes me uneasy. But there are > other special cases related to topicrefs that reference a map rather > than a topic or other topic-like things, so perhaps one more special > case won’t make things any worse. Still it seems odd that @scope > does not apply to the @href value on the same element. Is > @format=”ditamap” the only case where @scope values cascade? > > > > So when a single valued attribute like @linking cascades within a > > > map, it provides a default value for elements that support @linking > > > and which do not have an explicit value for @linking set, but does > > > not override explicitly set values. And when a single valued > > > attribute like @linking cascades from a map to a map, it does > > > override any explicitly specified @linking value specified on the > > > <map> element, and then we go back to regular non-overriding > > > cascading within the referenced map. Is that correct? That might > > > work, but it isn’t possible to override explicitly set @linking > > > values on topicrefs in the referenced map with this approach. That > > > is OK by me, but I just wanted to make sure that I understand the > > proposal. > > > > Yes, that's correct. The group seemed to feel this was the Path of Most > > Understanding (and the path that doesn't lead to new attributes for 1.2). > > > > > Multi-valued attributes such as @audience are a bit different since > > > they never override and instead their values are merged with values > > > from lower level elements when they cascade both within a map and > > > from map to map. Still right so far? > > > > I'm not sure - this has been discussed before so I would rather point to > > that discussion, if I could find it. > > I’m not sure that we talked about this in the context of map to map > and map to topic cascading, but perhaps we did. The discussion I > remember had to do with merging or not merging values during conref > processing. In any case we just need to be clear what the rules are > in the map to map case, the map to topic case, and the within topic > case. It would be nice if the rules were the same for all three cases. > > > > And thinking about @scope again: It is a single valued attribute, > > > but I’m not sure how much sense it makes to have one map change the > > > effective scope value on a topicref in another map without also > > > being able to change the @href and @format values (something you can > > > do using key references, but not with map to map cascading). Take > > > this example: > > > > > > <map title=”map1”> > > > <topicref href=”sometopic.dita” format=”dita” /> > > > </map> > > > > > > So @scope on the topicref defaults to “local”. > > > > > > But what happens if I reference this map from another map: > > > > > > <map title=”map2”> > > > <topicref href=”map1.ditamap” format=”ditamap” scope=”external” /> > > > </map> > > > > > > Does this make the effective value of @scope “external” on the > > > topicref for “sometopic.dita”? And if it does, what does that do? > > > > The user I quoted above would say that this provides a scope of external > > for topics in map1.ditamap. This would mean that if they generate links, > > those links are to external sources (often presented as new-window links). > > > > > And does this work the same way for both @toc=”yes” and @toc=”no”? > > > And in both cases the @toc value would apply to all topicrefs that > > > don’t have an explicitly specified @toc value, but it would not > > > override a @toc value that was explicitly set other than possibly a > > > @toc value on the <map> element, nor would @toc cascade to topicrefs > > > within reltables because @toc on <reltable> has a default of “no” > > > specified in the DTD or XML Schema? If I’m understanding this > > > correctly, I think it is OK, although I’m not sure how useful this will > > be. > > > > That was the consensus of the group, as I understood it. > > > > > I have my usual reservations about @scope, but lets pick a different > > > attribute as an example. > > > > > > Say that @linking is not specified at all in the higher level map > > > and so defaults to “normal” as the processor supplied default within > > > that map, but the @linking value would not cascade from the higher > > > level map to a lower level map. > > > > I think this may be differing from my own definition of processing default. > > I'm thinking of a processing default as something that the processor > > assumes when no value is specified on the element, in the dtd/schema, or > > on > > an ancestor that could cascade. On a map with no attributes specified or > > defaulted anywhere, I'd treat the default as toc="yes", and consider that > > a > > processing default. When @toc cascades from a parent or ancestor, it's > > still a user-specified value. > > I think this is OK. We just need the description to be clear and > explicit about this. I think it would be best to give each sort of > cascading an explict name so that we can talk about them and be > clear what we are and aren’t talking about. The names might be: > > explicit values > default values from the DTD or Schema > cascading values > controlled values > processor supplied defaults > > I think that list is more or less in order of precedence except that > I’m not sure about controlled values vs. processor supplied defaults. > > > > What happens if I have nested topicrefs in a higher level map as > > follows: > > > > > > <topicref linking=”none”> > > > <topicref href=”someothermap.ditamap” format=”ditamap” /> > > > </topicref> > > > > > > So here linking=”none” cascades from the first topicref to the > > > nested topicref, but is it a processor supplied default and so it > > > does not cascade on to the referenced map. Or is a cascading value > > > different from a processor supplied default and so @linking=”none” > > > would cascade on to the referenced map? > > > > This is exactly the same as specifying linking="none" on the map reference, > > and the linking attribute would apply to someothermap accordingly. > > > > > Some of this was discussed by an ad hoc group back last September > > > and summarized in a note to the TC: > > > > > > http://lists.oasis-open.org/archives/dita/200810/msg00009.html > > > > > > Most of this current proposal is in line with the earlier > > > discussion, but the earlier discussion did not make a distinction > > > between explicit values and processor supplied defaults in terms of > > > map to map cascading, they all cascade from map to map no matter > > > where/how they originated. The current proposal only has explicit > > > values cascading and processor supplied defaults do not cascade. Is > > > the change deliberate? It seems simpler and more consistent to me > > > to be able to determine what an attributes value is using explicit > > > values, DTD defaults, cascading within the document, and processor > > > supplied defaults into account, and then after you know what the > > > attribute value is to have that value cascade on to the referenced > > > document if appropriate. > > > > Does my clarified description of "processor default" get rid of the > > problems? The example in my mind is of a map with no attributes specified, > > and this in the middle: > > <topicref href="someothermap.ditamap" format="ditamap"/> > > If someothermap has @toc="no" on the root element, then I don't think it > > makes sense for us to override that unless the original map says to do so. > > The processor would default to toc="yes" in the original location, but I > > don't think we override the other map unless a user tells us to do so by > > explicitly setting toc="yes". > > Yes, I think there are good reasons to do it this way (the way you > outlined in the most recent proposal). > > > > > Do we need to bring controlled value defaults into this discussion? > > > The September 2008 discussion had controlled values being applied > > > within a document before other processor supplied defaults and then > > > the final result would cascade from one document to another. > > > > Makes sense to mention it - I would consider that as a user supplied value > > as well (not a processor default), which cascades using the rules > > specified > > in that proposal. If after cascading within an original map, a Controlled > > Value item results in @toc="no" on a map reference, then it cascades to > > the > > other map the same as any other user setting. > > That sounds fine, but are controlled values the same as other > processor supplied defaults or are they a special category of > processor supplied defaults that get applied first before other > processor supplied defaults? I think they are a special category, > but someone needs to verify that. > > > > > Robert D Anderson > > IBM Authoring Tools Development > > Chief Architect, DITA Open Toolkit > > > > "Ogden, Jeff" <jogden@ptc.com> wrote on 03/24/2009 12:12:30 AM: > > > > > RE: [dita] Inheritance of attributes through mapref > > > > > > I've edited some questions and comments into the text below. > > > > > > -Jeff > > > > > > > -----Original Message----- > > > > From: Robert D Anderson [mailto:robander@us.ibm.com] > > > > Sent: Monday, March 23, 2009 9:08 AM > > > > To: dita > > > > Subject: [dita] Inheritance of attributes through mapref > > > > > > > > This is a summary of the item discussed last week and the week before, > > > > initially raised here: > > > > http://wiki.oasis-open.org/dita/MaprefResolution > > > > > > > > The consensus at the TC as I understand it is that attributes > > specified > > on > > > > a map reference are equivalent to the same attributes specified on the > > > > target element. Exceptions are format (which must be 'ditamap') and > > href > > > > (which references the target). > > > > > > So some properties such as @format cascade within a map, but not > > > from map to map. Other properties such as @linking cascade within a > > > map and from map to map. And still other attributes such as @href > > > don’t cascade within a map or from map to map. Am I following this > > > correctly? If this is correct, it seems OK to me, we just need to > > > explain clearly which category each attribute or property is in. > > > > > > Is there yet another case where a property can cascade from a map to > > > a topic or from a map to a map to a topic and in both cases on to > > > elements within the topic? Are the rules for map to map cascades and > > > the rules for map to topic cascades the same? > > > > > > Is @scope in the same category as @format? I’ve always thought of > > > @format and @scope as qualifying the @href value on the current > > > element. Is @format=”ditamap” a special case where @scope is > > > ignored on the current element and just passed on? If so, is that a > > > good idea? And if it isn’t a special case, don’t you need to > > > specify @scope=”local” @format=”ditamap” for things to make sense? > > > I’m not sure what @scope=”external” @format=”ditamap” or > > > @scope=”peer” @format=”ditamap” would do, but it would seem that the > > > DITA map wouldn’t be available for local processing unless @scope is > > > “local” either explicitly or by default. > > > > > > > For example, if I have this map reference: > > > > <topicref href="someMap.ditamap" > > > > format="ditamap" > > > > toc="no" > > > > scope="peer" > > > > print="no" > > > > linking="normal"/> > > > > > > > > In the map someMap.ditamap, the toc / scope / print / linking > > attributes > > > > from that topicref will override whatever is set or defaulted on the > > <map> > > > > element. From there, those attributes will cascade as they normally > > would > > > > within someMap.ditamap. > > > > > > So when a single valued attribute like @linking cascades within a > > > map, it provides a default value for elements that support @linking > > > and which do not have an explicit value for @linking set, but does > > > not override explicitly set values. And when a single valued > > > attribute like @linking cascades from a map to a map, it does > > > override any explicitly specified @linking value specified on the > > > <map> element, and then we go back to regular non-overriding > > > cascading within the referenced map. Is that correct? That might > > > work, but it isn’t possible to override explicitly set @linking > > > values on topicrefs in the referenced map with this approach. That > > > is OK by me, but I just wanted to make sure that I understand the > > proposal. > > > > > > Multi-valued attributes such as @audience are a bit different since > > > they never override and instead their values are merged with values > > > from lower level elements when they cascade both within a map and > > > from map to map. Still right so far? > > > > > > And thinking about @scope again: It is a single valued attribute, > > > but I’m not sure how much sense it makes to have one map change the > > > effective scope value on a topicref in another map without also > > > being able to change the @href and @format values (something you can > > > do using key references, but not with map to map cascading). Take > > > this example: > > > > > > <map title=”map1”> > > > <topicref href=”sometopic.dita” format=”dita” /> > > > </map> > > > > > > So @scope on the topicref defaults to “local”. > > > > > > But what happens if I reference this map from another map: > > > > > > <map title=”map2”> > > > <topicref href=”map1.ditamap” format=”ditamap” scope=”external” /> > > > </map> > > > > > > Does this make the effective value of @scope “external” on the > > > topicref for “sometopic.dita”? And if it does, what does that do? > > > > > > > Similarly, if I have this construct in the original map: > > > > <topicref toc="no"> > > > > <topicref href="someMap.ditamap" format="ditamap"/> > > > > </topicref> > > > > > > > > The toc="no" attribute will cascade to the map reference, which is > > then > > > > treated the same as in the previous example, and will override the toc > > > > attribute on the map element within someMap.ditamap. > > > > > > And does this work the same way for both @toc=”yes” and @toc=”no”? > > > And in both cases the @toc value would apply to all topicrefs that > > > don’t have an explicitly specified @toc value, but it would not > > > override a @toc value that was explicitly set other than possibly a > > > @toc value on the <map> element, nor would @toc cascade to topicrefs > > > within reltables because @toc on <reltable> has a default of “no” > > > specified in the DTD or XML Schema? If I’m understanding this > > > correctly, I think it is OK, although I’m not sure how useful this will > > be. > > > > > > > An attribute that is defaulted in the DTD or Schema is treated in the > > same > > > > way as an attribute specified in the document. > > > > > > > > A value generally treated as a processing default does *not* cascade > > in > > the > > > > same manner. For example, within a map where no element specifies the > > scope > > > > attribute and no element has a default scope attribute, there will be > > a > > > > processing default of scope="local". That processing default will not > > > > override whatever is specified at the root of someMap.ditamap. > > > > > > I have my usual reservations about @scope, but lets pick a different > > > attribute as an example. > > > > > > Say that @linking is not specified at all in the higher level map > > > and so defaults to “normal” as the processor supplied default within > > > that map, but the @linking value would not cascade from the higher > > > level map to a lower level map. > > > > > > What happens if I have nested topicrefs in a higher level map as > > follows: > > > > > > <topicref linking=”none”> > > > <topicref href=”someothermap.ditamap” format=”ditamap” /> > > > </topicref> > > > > > > So here linking=”none” cascades from the first topicref to the > > > nested topicref, but is it a processor supplied default and so it > > > does not cascade on to the referenced map. Or is a cascading value > > > different from a processor supplied default and so @linking=”none” > > > would cascade on to the referenced map? > > > > > > Some of this was discussed by an ad hoc group back last September > > > and summarized in a note to the TC: > > > > > > http://lists.oasis-open.org/archives/dita/200810/msg00009.html > > > > > > Most of this current proposal is in line with the earlier > > > discussion, but the earlier discussion did not make a distinction > > > between explicit values and processor supplied defaults in terms of > > > map to map cascading, they all cascade from map to map no matter > > > where/how they originated. The current proposal only has explicit > > > values cascading and processor supplied defaults do not cascade. Is > > > the change deliberate? It seems simpler and more consistent to me > > > to be able to determine what an attributes value is using explicit > > > values, DTD defaults, cascading within the document, and processor > > > supplied defaults into account, and then after you know what the > > > attribute value is to have that value cascade on to the referenced > > > document if appropriate. > > > > > > Do we need to bring controlled value defaults into this discussion? > > > The September 2008 discussion had controlled values being applied > > > within a document before other processor supplied defaults and then > > > the final result would cascade from one document to another. > > > > > > > Any questions/comments, please respond to the list... > > > > > > > > Thanks - > > > > > > > > Robert D Anderson > > > > IBM Authoring Tools Development > > > > Chief Architect, DITA Open Toolkit > > > > > > > > > > > > --------------------------------------------------------------------- > > > > To unsubscribe from this mail list, you must leave the OASIS TC that > > > > generates this mail. Follow this link to all your TCs in OASIS at: > > > > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php > > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]