OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


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