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


This is a good summary of where we are.

 

Some comments below.

 

   -Jeff

 

> -----Original Message-----

> From: Robert D Anderson [mailto:robander@us.ibm.com]

> Sent: Tuesday, April 14, 2009 9:43 AM

> To: Ogden, Jeff

> Cc: dita

> 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).

 

Don’t we already have a list for the later case (merge)?  If an attribute value cascades and the attribute allows multiple values then. it merges.  If an attribute value cascades and the attribute does not allow multiple values. it overrides.

 

My goal here is just to make the rules for map to map cascading as much like the rules for other cascading as possible because that is more consistent and therefore easier to remember.  And while the DITA 1.1 spec. didn’t talk about map to map cascading explicitly, when it did talk about cascading more generally it talked about merging multi-valued attributes and overriding single values attributes. So it just seem unnec3essairly complicated to introduce a new case.  Note too that this question is about general cascading and that there are separate rules for conref behavior.

 

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

 

Again I’m just trying to avoid more special cases.  I think of the three attributes href, format, and scope as working together to define the meaning of a reference.  @href and @format do not cascade from document to document. I don’t think @scope should either. I’d like to avoid the situation where @scope cascades if @format=”ditamap”, but does not otherwise.

 

If the map author wants to override references in other maps or in topics, they can use key references to do that since that allows them to override all three of the properties (href, format, and scope) together and with more granularity than doing it for all references in a sub-map.

 

 

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