[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
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:jogden@ptc.com] 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:su-laine.yeo@justsystems.com] 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 JustSystems Canada, Inc. From: Ogden, Jeff [mailto:jogden@ptc.com]
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:su-laine.yeo@justsystems.com] 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 JustSystems Canada, Inc. > 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. |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]