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