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


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]