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

[Eliot Kimber <ekimber@reallysi.com>]

Based on Chris' assertion that one can read the spec in a way that allows
conforming processors to not treat this case as I've asserted they must,
I've added a note to my book to the effect that because the 1.2 spec doesn't
explicitly disallow this behavior it is allowed but because it doesn't also
explicit mandate it, conforming processors may choose to behave a different
way, so don't assume any given processor will behave this way.

Having said that, I fully intend to ensure that the Open Toolkit, in
particular, does behave this way, even if it means I have to rewrite the
conref push processing myself. Currently that processing has a bug that
causes it to fail in all cases so I can't test this particular case.

That is, I intend to lobby hard that this behavior should be mandated
because I think it's an exceptionally powerful feature, intended or not.

Cheers,

E.
On 2/15/11 7:56 AM, "Eliot Kimber" <ekimber@reallysi.com> wrote:

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