[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: General Implications of Multiple Uses of Same Topic With DifferentKeys
A general implication of the use of keys with normal-role topics is that if
the same topic is used twice in a map and bound to different keys, those two
uses become unambiguously different and therefore processors can do "the
right thing".
That is, the use of keys in this way removes the need to use @copy-to simply
to distinguish two uses of the same topic that should be treated
independently for processing purposes.
For example, consider this map:
<map>
<topicref href="pushing-topic-01.dita"
processing-role="resource-only"
/>
<topicref href="topic-01.dita"
keys="topic-01-use-01"
/>
<topicref href="topic-01.dita"
keys="topic-01-use-02"
/>
</map>
The same topic is used twice and each use is bound to a unique key.
One implication of this is that processors should treat these two uses of
the topic as distinct, whatever that means for the processing context.
In the case of monolithic renditions such as PDF, it simply means that a
cross-ref to a specific use via keyref will result in a link to that
location in the PDF.
But for multi-file outputs, such as HTML, where a single rendered instance
of the topic could be used by reference from multiple places in the
rendition, I think it means that the processor must treat these uses *as
though* @copy-to had been specified, because the use of the distinct keys
means that links may be created to specific uses of the topic and those
links may come from peer or external resources, meaning that the processor
cannot know at rendition time whether or not there are or will be links to
those uses, therefore the processor must anticipate that possibility by
generating distinct copies of the topic, one for each use.
Where this gets particularly interesting is with conref push.
With conref push, if I use conkeyref I can push content to distinct *uses*
of a topic, allowing me to have use-context-specific versions of topics
created through conref push. This is very powerful because it allows
something that neither pull conref nor key-based link text construction
today allow, namely use-context-specific results within a single root map
using normal processing (that is, not using any of the pre-processing tricks
Michael has described at various times on the DITA Users list) [I call these
"tricks" because they rely on coordination of filenames and other
identifiers in a way that is not reliable in the general case. In
particular, they require that addresses be authored to reflect the data as
it *will be* following pre processing, not as it is as authored. In my world
that is very very wrong and any system that requires it is architecturally
broken. Not to put to fine a point on it or anything. Fortunately, DITA
appears to avoid the need for these sorts of tricks, if my analysis is
correct.]
Given the map above, topic "pushing-topic-01.dita" can unambiguously push
different content into topic-01.dita in its different use contexts, e.g.,
given a paragraph with the ID "para-01" in topic-01.dita, I could do this:
<topic id="pushing-topic">
<title>Push to Topic-01</title>
<body>
<p conkeyref="topic-01-use-01"
conaction="pushreplace">This is specific to use one</p>
<p conkeyref="topic-01-use-02"
conaction="pushreplace">This is specific to use two</p>
</body>
</topic>
The processing result must be that there are two copies of topic
topic-01.dita reflected in the output. I say "must" because there's no other
way that the author's clear intent could be realized except by rendering two
copies of the topic, one for each distinct push.
This requirement is not stated explicitly in the 1.2 spec as far as I can
tell but it is, I think, clearly implicit in the fact that I can do what
this example shows.
I'm pretty sure the Open Toolkit does not currently behave this way, but I
can't tell for sure because there's a bug in its implementation of conref
push that causes key-based conref push to fail. But I'm asserting that it
(and all other conref-push-supporting processors) should behave this way.
Does anybody disagree with my analysis?
I'm seeking confirmation that the following two statements are true:
1. When the same topic is used twice with different key bindings, processors
are obligated to create distinct renditions of that topic when they would
have otherwise created a single rendition absent the keys (e.g., for HTML
output).
2. It is possible to use conref push as in my example, pushing different
content to the same topic used multiple times with different keys.
In both cases the use of @copy-to is not required (because the keys are
sufficient to establish the identity of the uses and provide enough
information for processors to construct correct addresses in the rendered
result).
One implication of this use of keys is that @copy-to becomes a tool for
establishing persistent identifiers in *renditions* and is not necessary
simply to cause processors to distinguish different uses of a given topic
when those uses have distinct keys.
In particular, on the principle that all addresses in content should be to
the content *as authored*, not as rendered, if you need to address a
specific use of a topic or map you should *always* use keys and not depend
on @copy-to in any way (because @copy-to is about controlling the addresses
of things as rendered).
Or more simply: the keyref facility removes the need to rely on @copy-to
tricks or the behavior of specific processors in order to unambiguously link
to specific uses of topics.
I want to make sure that there is TC consensus on this point because it's a
very important but somewhat non-obvious implication of the key reference
facility. I intend to reflect this analysis in my DITA for Practitioners
book unless the TC determines that this analysis is incorrect for some
reason.
Cheers,
Eliot
--
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]