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] General Implications of Multiple Uses of Same Topic With Different Keys

"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)."

I take issue with the word "obligated," and I don't think the spec, as
currently written, implies that a processor must work this way. I could
go with "may" or even "should" wording, but I object to "must." To state
the obvious, different processors will process things differently, and
for this to work the step that determines the topography of the output
has to be able to know that two references to the same topic are
identified by different keys. But imagine a processor that resolves key
references before determining the organization of the output. By the
time an xref to a topic is converted into HTML, all knowledge of which
key it used to reference is gone (indeed, all knowledge of keys may be
gone), so there's no way for the processor to do what you present in
your example.

There are also legitimate cases where the behavior you propose would be
undesirable. Imagine a map that combines two lower-level maps authored
independently. Each lower-level map binds different keys to a given
topic, but otherwise the references are interchangeable. In this case
there's no benefit to having multiple copies of the topic in output, and
there's potential downside to the needless redundant processing and
bloat. If you want that behavior, you should explicitly set copy-to and
make the output unambiguous.

Assuming that a given processor does process topics bound to different
keys in this way, then I do agree that you could use conref push as you
describe, but I don't think we can mandate that behavior, and more
importantly, I'm not sure most document architects/authoring groups are
going to be willing to implement such a roundabout solution to the
problem of position-dependent output. I know of many instances where
DITA users, particularly those early in their adoption, have avoided
simple conrefs, and ideas like indirect addressing or conref push are
hard for even sophisticated users to become comfortable with. I'm
convinced that using conkeyref push for different keys to the same topic
to achieve contextutalized differences in output is significantly more
complicated than most shops will be able to manage. We as a committee
should try to come up with a more straightforward way of doing it that
doesn't involve exploiting unintended consequences of unspecified
assumptions about how keys will be processed.


-----Original Message-----
From: Eliot Kimber [mailto:ekimber@reallysi.com] 
Sent: Saturday, February 12, 2011 7:58 AM
To: dita
Subject: [dita] General Implications of Multiple Uses of Same Topic With
Different Keys

A general implication of the use of keys with normal-role topics is that
the same topic is used twice in a map and bound to different keys, those
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
to distinguish two uses of the same topic that should be treated
independently for processing purposes.

For example, consider this map:

 <topicref href="pushing-topic-01.dita"
 <topicref href="topic-01.dita"
 <topicref href="topic-01.dita"

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
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
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
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
cannot know at rendition time whether or not there are or will be links
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
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
using normal processing (that is, not using any of the pre-processing
Michael has described at various times on the DITA Users list) [I call
"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
it *will be* following pre processing, not as it is as authored. In my
that is very very wrong and any system that requires it is
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

Given the map above, topic "pushing-topic-01.dita" can unambiguously
different content into topic-01.dita in its different use contexts,
given a paragraph with the ID "para-01" in topic-01.dita, I could do

<topic id="pushing-topic">
  <title>Push to Topic-01</title>
   <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>

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
way that the author's clear intent could be realized except by rendering
copies of the topic, one for each distinct push.

This requirement is not stated explicitly in the 1.2 spec as far as I
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
can't tell for sure because there's a bug in its implementation of
push that causes key-based conref push to fail. But I'm asserting that
(and all other conref-push-supporting processors) should behave this

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,
are obligated to create distinct renditions of that topic when they
have otherwise created a single rendition absent the keys (e.g., for

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

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
when those uses have distinct keys.

In particular, on the principle that all addresses in content should be
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
on @copy-to in any way (because @copy-to is about controlling the
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
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



Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368

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:

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