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