[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 WithDifferent Keys
<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
>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]