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