RE: [dita] General Implications of Multiple Uses of Same Topic With Different Keys

["Nitchie, Chris" <cnitchie@ptc.com>]

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

Chris

-----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
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


---------------------------------------------------------------------
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:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php