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


Hi Bruce,

That sentence is just meant to highlight the fact that you cannot combine -
they must come from one or the other. Which one they come from is
determined by rules laid out in the previous few paragraphs -- with rare
exceptions, an attribute on the source always wins. The only time the
target's audience attribute would be used is if the source does not specify
@audience.

The (rather important) additional context is here:
http://docs.oasis-open.org/dita/v1.1/OS/archspec/conref.html

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit



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:su-laine.yeo@justsystems.com]
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:jogden@ptc.com]
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:su-laine.yeo@justsystems.com]
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
syeo@justsystems.com
www.justsystems.com


From: Ogden, Jeff [mailto:jogden@ptc.com]
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:su-laine.yeo@justsystems.com]
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
syeo@justsystems.com
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.


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]