Re: [dita] General Implications of Multiple Uses of Same Topic WithDifferent Keys

[Eliot Kimber <ekimber@reallysi.com>]

Just to be clear: I'm saying that multiple renderings for conref push to
different keys bound to the same topic is required *because there's no other
way it could possibly work*, not because the spec as written explicitly
requires it. That is, the requirement is an emergent requirement stemming
from the interaction of conref push and keyref.

But that's my question: is my analysis correct and if not, why not and what
are the possible alternative behaviors?

Cheers,

E.

On 2/15/11 7:27 AM, "Nitchie, Chris" <cnitchie@ptc.com> wrote:

> I agree that it's desirable, I'm reasonably sure it's allowed, but I'm
> also reasonably sure it's not mandated. If we want to say that this
> behavior is allowed/required, then I think we need to tweak the language
> in the spec, either in 1.3 or in an addendum to 1.2. And if
> use-context-dependent behavior is something that people seem to need -
> and I think it is - then I don't think this is an ideal way to support
> it, and we need to come up with easier to implement (heck, easier to
> describe) mechanisms in future versions of the spec. That's all I'm
> saying.
>
> Chris
>
> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com]
> Sent: Monday, February 14, 2011 10:47 PM
> To: Nitchie, Chris; dita
> Subject: Re: [dita] General Implications of Multiple Uses of Same Topic
> With Different Keys
>
> It was my understanding in discussions I had with Robert and Michael on
> the
> various issues around references to topicrefs and the implications of
> key
> references to normal-role topicrefs that it very definitely had a
> specific
> and clear meaning, or at least implication.
>
> That was certainly the case for ID-based references to topicrefs. I'll
> have
> to do some more research on the spec to find the specific language.
>
> But note that the issue is not really about the resource a key resolves
> to,
> but the processing implications of *rendering* that resource in the
> context
> of a specific use from a map as referenced by a particular link.
>
> If the link is a conref push link there is one set of (potential)
> processing
> implications. If the link is a cross reference there is another set of
> processing implications. None of these implications says anything about
> the
> resource the key is bound to, but everything about the context within
> which
> that binding occurs.
>
> It also doesn't really matter what we think--the mechanism in the spec
> is
> there and users will interpret it how they will and implementers ignore
> reasonable interpretations at their peril.
>
> That's one reason I asked the question in the first place: if I write in
> a
> book that a particular way of using conref push with keys is both
> *allowed*
> and *desireable* it is highly likely that people will use it and
> probably
> expect processors to do it. At that point it doesn't matter what the
> intent
> of the design was.
>
> In the specific case of conref push I think the ability to push to
> different
> use contexts is extremely powerful, making a very important feature
> really
> really important. I think we would be ill advised to legislate that
> feature
> away.
>
> I'm curious to know if Michael or Robert had that particular use in mind
> when they designed conref push or if it is simply the combination of two
> separate features. It would not surprise me that they had that specific
> use
> in mind all the time.
>
> Cheers,
>
> E.
>
>
> On 2/14/11 9:04 PM, "Chris Nitchie" <cnitchie@ptc.com> wrote:
>
>> <snip>
>> I'm starting to think that this is an area where the 1.2 spec is at
> best
>> underspecified and at worst thinking a bit fuzzily.
>> ...
>> So I think context-specific linking and the general implications of
> use
>> context is something we'll have to think more carefully about in the
> 1.3
>> timeframe.
>> </snip>
>>
>> Yes. I think I agree that Eliot's description is the most desirable
>> behavior, but I don't think the spec mandates that behavior as
> currently
>> written. For example, I don't think it's inconsistent with the spec to
>> interpret the conref example below:
>>
>> <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>
>>
>> Like this:
>>
>> <topic id="pushing-topic">
>>   <title>Push to Topic-01</title>
>>   <body>
>>    <p conref="topic-01.dita#topic/id"
>>       conaction="pushreplace">This is specific to use one</p>
>>    <p conref="topic-01.dita#topic/id"
>>       conaction="pushreplace">This is specific to use two</p>
>>   </body>
>> </topic>
>>
>> I'll grant that this probably isn't the "right" handling, in that it
> doesn't
>> reflect the author's intent, but I don't think it's inconsistent with
> the
>> current language in the spec. I think the spec is at best ambiguous on
>> whether a key is bound to the specific TOC location of the
> key-defining
>> topicref as well as the topic that it references. The exact language
> is:
>>
>> <snip>
>> A key can be bound simultaneously to several resources:
>>
>> * It is directly bound to the resource addressed by the @href
> attribute of
>> the key-defining element, if a @keyref either is not specified or
> cannot be
>> resolved following key space construction.
>> * If the key-defining element specifies a @keyref attribute and the
> key
>> reference can be resolved following key space construction, the key is
> bound
>> to any directly addressed resource bound to the referenced key
> (directly or
>> indirectly). (It is an error for a topicref to refer directly or
> indirectly
>> to any key that it defines.)
>> * It is bound to the subelements of the <topicmeta> element within the
>> key-defining element, if any are present.
>> </snip>
>>
>> If keys are a way to distinguish between instances of topics in the
> toc
>> structure, then the spec needs to say that explicitly, and it doesn't
> do
>> that now. The broader point, I think, is that there really needs to be
> a way
>> to allow different instances of topics in the same map structure
> behave
>> differently with regard to conditional processing and keyref
> resolution.
>>
>> Chris
>>
>> On 2/14/11 6:31 PM, "Eliot Kimber" <ekimber@reallysi.com> wrote:
>>
>>> Hmmm.
>>>
>>> In the specific case of conref push I think my analysis is correct
> that the
>>> only correct way to for processors to behave in the case two
> different
>>> pushes to the same topic via different keys is to create two
> renditions of
>>> the topic, otherwise the author's intent cannot be correctly or
> completely
>>> reflected. [Note that by "two renditions" I don't necessarily mean
> "two HTML
>>> files", although that's the easiest way to do it for non-monolithic
>>> outputs.]
>>>
>>> In the general case of keys bound to normal-role topicrefs, I can see
> Chris'
>>> point that it's not necessarily required to create new copies simply
> to
>>> allow the potential for references to the topic by that key from peer
> or
>>> external-scope resources.
>>>
>>> For local-scope references a processor can know if a given key is
> ever
>>> referenced and not create copies for those keys that are never
> referenced.
>>> So I think that Chris is correct that my "must" is too strong.
>>>
>>> I was actually thinking about a future case, when it becomes possible
> to
>>> refer to keys in other key spaces (that is, peer and external scope
> key
>>> references). In that future every key becomes a candidate for use.
> But I
>>> think in that case it will be necessary to allow key definition
> authors to
>>> indicate whether a given key is intended to be a "public" key that
> must
>>> accommodate non-local use and therefore in that case, requires
> creating
>>> use-context-specific copies. That is, some attribute analogous to
> @copy-to
>>> that says "make sure this key as bound to this context is available
> for
>>> non-local addressing". But that discussion is for the future.
>>>
>>> I think that the semantic distinction between normal- and
> resource-only key
>>> definitions is probably underappreciated by the community. In
> particular,
>>> the fact that they do have different implications for links in terms
> of use
>>> context (resource-only key definitions by definition are not in any
> use
>>> context).
>>>
>>> It is probably important to better educate the community about the
>>> implications for normal- and resource-only key definitions, in
> particular,
>>> that if you want to unambiguously link to things without regard to
> use
>>> context, use resource-only key bindings.
>>>
>>> I think that does still leave the question of what, if anything,
> processors
>>> are required to do or should at least give the option of doing when a
>>> normal-role key binding *is* referenced. For me personally as an
> author, if
>>> I link to a normal-role key then I do so specifically because I want
> to link
>>> to the topic in that context, which means reflecting a specific set
> of
>>> related links, previous/next links, and so on.
>>>
>>> I suppose that doesn't necessarily require multiple literal copies
> e.g., in
>>> the HTML case, since you could do something clever with JavaScript or
>>> whatever to have have a specific incoming link make a single HTML
> rendering
>>> reflect a specific use context, but how is that not a set of
> "distinct
>>> renderings" of the topic?
>>>
>>> I'm starting to think that this is an area where the 1.2 spec is at
> best
>>> underspecified and at worst thinking a bit fuzzily.
>>>
>>> Or maybe another way to put it is: when you link to something in a
> specific
>>> use context, what can that mean other than to either link to the
> navigation
>>> structure artifact for that context [e.g., go to the rendered ToC (or
>>> whatever) for that use context] or go to a context-specific rendering
> of the
>>> topic that reflects its context appropriately (e.g., prev/next links,
> etc.).
>>>
>>> A lot of the original DITA design was based on a view of information
>>> delivery that said that topics can or must be meaningful out of any
> specific
>>> use context, but that's clearly not a universal even for tech doc and
> it
>>> certainly can't be a universal for many important applications of
> DITA,
>>> where use context is very important, if not essential.
>>>
>>> So I think context-specific linking and the general implications of
> use
>>> context is something we'll have to think more carefully about in the
> 1.3
>>> timeframe.
>>>
>>> Cheers,
>>>
>>> E.
>>>
>>>
>>> On 2/14/11 4:05 PM, "Nitchie, Chris" <cnitchie@ptc.com> wrote:
>>>
>>>> "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
>>>>
>>>>
>>>>
> ---------------------------------------------------------------------
>>>> 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
>>>>
>>>
>>> --
>>> Eliot Kimber
>>> Senior Solutions Architect
>>> "Bringing Strategy, Content, and Technology Together"
>>> Main: 512.554.9368
>>> www.reallysi.com
>>> www.rsuitecms.com
>>>
>>
>
> --
> Eliot Kimber
> Senior Solutions Architect
> "Bringing Strategy, Content, and Technology Together"
> Main: 512.554.9368
> www.reallysi.com
> www.rsuitecms.com
>

--
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com