I'm trying to understand
this:
“A given attribute
value on the resolved element comes in its entirety from either the source or
target: the attribute values of the target and source for a given attribute are
never additive, even if the property (such as the audience type) takes a list of
values.”
The spec seems to leave that up to the
adopter. Should it at least advise to pick one and stick to
it?
I suppose there's a case where you want the attribute
in the target to be determinative. Here's one where I think the
source clearly should be determinative.
Source in thistopic.dita:
<p
conref="thattopic.dita#topicid/elementidX"
audience="beginner"/>
Target in thattopic.dita:
<concept
id="topicid">
...
<p id="elementidX"
audience="expert">Expert stuff.</p>
...
</concept>
(This also illustrates why they shouldn't
be additive.)
Should the advice be that it is more
manageable never to put profiling attributes in the target and always have them
instead on the conref-bearing source elements? For example:
Source in thistopic.dita:
<p conref="thattopic.dita#topicid/elementidX"
audience="beginner"/>
<p
conref="thattopic.dita#topicid/elementidY"
audience="expert"/>
Target in thattopic.dita:
<concept
id="topicid">
...
<p id="elementidX"
audience="expert">Beginner stuff.</p>
<p id="elementidY"
audience="expert">Expert
stuff.</p>
...
</concept>
User would have to be able to inspect the
attribute values in the target so as to pick the right one for each conref. But
you have to pick the right target for the conref in every case
anyway.
/Bruce
From: Su-Laine Yeo
[mailto:]
Sent: Thursday, April 16,
2009 2:42 PM
To: dita
Subject: RE: [dita] Inheritance of
attributes through mapref
That makes sense
to me Jeff. I agree that changing the spec in this regard would be a big
change and that we’ll probably have to not change course for
1.2.
I’ve thought a bit
more about conditional processing with respect to other mechanisms for
including child document sets in parent document sets. I can see more bad
news, unfortunately. The use cases I’ve described are examples of a general
case in which a child document set contains a mixture of conditional and
unconditional content, that within a parent document set should be treated as
entirely conditional. The Architectural Spec rules for conref attributes don’t
handle this case well either:
“A given attribute
value on the resolved element comes in its entirety from either the source or
target: the attribute values of the target and source for a given attribute
are never additive, even if the property (such as the audience type) takes a
list of values.”
This rule will
give undesired results if the conref target contains a mixture of conditional
and unconditional content and the unconditional content should be treated as
conditional in the context of the source document. So this rule is one more
thing to think about changing.
Su-Laine
From: Ogden, Jeff
[mailto:]
Sent: Wednesday, April 15, 2009 7:11
PM
To: Su-Laine Yeo; dita
Subject: RE: [dita] Inheritance
of attributes through mapref
I went
back to the DITA 1.0 specification to see what that said about map to topic
cascading. What I found is almost identical to the version in the DITA
1.1 spec.:
Topic properties in
topics and maps
The properties of a topic
can be specified in the topic itself or on references to the topic within
maps.
. .
.
If a property is set in
both the map and topic, the map properties are additive if the property (such
as the
audience type) takes a
list of values. If, instead, the property (such as the importance) takes a
single
value, the map property
overrides the topic property.
Here
is the section from the DITA 1.1 spec. for comparison:
Topic properties in
topics and maps
The properties of a topic
(including metadata attributes and metadata elements) can be specified in
the
topic itself or in
references to the topic within maps.
. .
.
If a property is set in
both the map and topic, the map properties are additive if the property (such
as the
audience type) takes a
list of values. If, instead, the property (such as the importance) takes a
single
value, the map property
overrides the topic property.
Given
this I think it is hard to argue that the DITA specifications are “wrong”.
I think a case could be made that the specification should be changed.
But such a change should really require a full-blown proposal, review, and a
vote. And I think that that would need to wait for DITA 1.3. And it might need
to wait for DITA 2.0 since it is an incompatible change that would change the
behavior for existing documents that conform to the DITA 1.0 and 1.1
specifications as originally written and approved.
My own
not too well thought out feeling is that we should try to avoid an
incompatible change here altogether by coming up with a syntax that allows
authors to explicitly say which behavior they want (override, merge, provide
new default values for those cases where no value has been explicitly given,
…). But that will take some care to design and so it too would need to
wait for DITA 1.3 or 2.0.
-Jeff
From: Su-Laine Yeo
[mailto:]
Sent: Wednesday, April 15,
2009 8:35 PM
To: dita
Subject: RE: [dita] Inheritance of
attributes through mapref
Hi
Jeff,
Thanks for
providing the relevant section of the 1.1 spec. I think the TC should
re-examine whether the spec might be wrong. I agree that this thread didn’t
start out with the intention of revisiting the 1.1 map-to-topic cascading
rules, but if they’re wrong we should fix them before copying the problem over
to the map-to-map cascading rules.
Having said that,
I thought more about the example I gave, and I think the conclusion I first
reached is not quite right either. If there is a difference between the
conditional values on a topicref and the values on an element in the
referenced topic, the processor should have different rules depending on
whether the element has values for that attribute or not. In the example, if
topic 3 contains an element with no “audience” attribute, that element should
be processed as if it inherits audience values from the topicref. However, if
topic 3 contains an element with an “audience” attribute, that element should
be processed as if its audience values are the intersection between the local
values and any audience values on the topicref.
When I think about
this issue abstractly, it also seems logicially wrong to ask processors to add
conditional attribute values that are set at different levels. The way that
conditional attributes work is that when you specify what audiences an element
is for, you are implicitly saying that it is not for any other audience. E.g.
when you say that audience = “c”, you are saying that the audience is not B or
A.
Here is a second
use case, which is an extension of the first but illuminates a few more
issues: You are creating a document for three audiences, A, B, and C. The map
includes:
1) a topic that is
common to all audiences
2) a topic in
which the entire topic is for audience A only
3) a topic that
does not apply to A at all, and contains some elements that apply only to B
and some elements that apply only to C
4) a topicref
pointing to a submap that includes the following topics:
- 4.1) a topic
that applies to B and C only
- 4.2) a topic for
B only
- 4.3) a topic
that contains some elements that apply only to B and some elements that apply
only to C
If generating
output for audience A, you will want to include topic 1 and 2. Topic 3 and
submap 4 should not appear.
If generating
output for audience B, you will want the TOC to include topic 1, unconditional
and B-only elements from topic 3, topic 4.1, topic 4.2, and unconditional and
B-only elements from topic 4.3.
There are four
ways to indicate that topic 4.1 applies to B and C only:
- mark topicref
4.1 as having audience =”b c”
- mark topic 4.1
as having audience =”b c”
- mark submap 4 as
having audience =”b c”
- mark topicref 4
as having audience =”b c”. This is useful because it is possible that the
author of submap 4 knew that audiences B and C existed, but was unaware of the
existence of audience A, and so did not indicate anywhere within the submap or
its topics that 4.1 was a conditional topic. In this case, the author of the
parent map should set “audience=”b c” on the topicref that points to submap 4.
Using any of these
four methods, the processor will give desired results if it follows the
following rules for both map-to-topic and map-to-map
cascading:
- An element
inherits conditional attribute values if it has no local values for that
attribute.
- An element is
processed as if it has the intersection of local and inherited attribute
values, if any local values exist for that attribute.
That’s all my
brain can handle today :)
Best,
Su-Laine
Su-Laine
Yeo
Interaction
Design Specialist
JustSystems
Canada, Inc.
Office:
778-327-6356
www.justsystems.com
From: Ogden, Jeff
[mailto:]
Sent: Wednesday, April 15, 2009 1:55
PM
To: dita
Subject: RE: [dita] Inheritance of attributes
through mapref
Su-Laine,
thanks for providing a concrete use case.
Is the
use case just a single map and cascading of attribute properties from that map
to the topics? It isn’t talking about map to map cascading is
it?
I
thought that the map to topic case was already settled in the DITA 1.1
specification and we were just talking about cascading in the map to map
case. Am I mistaken about that?
Here
is what the section “Topic properties in topics and maps” in the DITA 1.1
Architecture Spec. says:
The properties of a topic
(including metadata attributes and metadata elements) can be specified in
the
topic itself or in
references to the topic within maps.
. .
.
If a property is set in
both the map and topic, the map properties are additive if the property (such
as the
audience type) takes a
list of values. If, instead, the property (such as the importance) takes a
single
value, the map property
overrides the topic property.
And
I’m arguing that for simplicity’s sake we should follow the same rules for the
map to map case as already exist for the map to topic
case.
-Jeff
From: Su-Laine Yeo
[mailto:]
Sent: Tuesday, April 14, 2009
2:45 PM
To: dita
Subject: RE: [dita] Inheritance of
attributes through mapref
Regarding merging
vs. overriding for conditional attributes, let’s consider the following
example: You are creating a document for three audiences, A, B, and C. The map
includes:
1) a topic that is
common to all audiences
2) a topic in
which the entire topic is for audience A only
3) a topic which
does not apply to A at all, and contains some elements that apply only to B
and some elements that apply only to C
If generating
output for audience A, you will want to include topic 1 and 2. Topic 3 should
not appear at all, not even in the TOC.
If generating
output for audience B, you will want the TOC to include topic 1 and topic 3.
Topic 3 should include any unconditional elements, include the elements that
apply to B, and exclude the elements that apply only to
C.
Currently the OT
gives the desired behaviour if you set audience=”a” on the topicref to topic 2
and audience=”b c” on the topicref to topic 3. If we were to say that audience
attribute values on a topicref are added to the conditional attributes within
the target topic, you would not get the desired behaviour in this case,
because when generating output for audience B, you would get all the content
for audience C in topic 3. I have thought of trying to get the desired
behaviour by explicitly conditionalizing all of the elements in topic 3
instead of putting conditions on the topicref, however this is not feasible
because you cannot conditionalize element types such as
<title>.
So I think this
particular example supports a rule that conditional attribute values should be
processed as the intersection as of the values on the topicref and the values
on the further down the hierarchy. I think this is the rule which is actually
implemented in the current OT.
Regards,
Su-Laine
Su-Laine
Yeo
Interaction
Design Specialist
JustSystems
Canada, Inc.
Office:
778-327-6356
www.justsystems.com
> 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.
