RE: [dita] Groups - Understanding Keys and Key Spaces (understanding-dita-keys-and-key-spaces.pdf) uploaded

["Bruce Nevin (bnevin)" <bnevin@cisco.com>]

Yes of course, it is fundamentally different. My bad. For nontech
readers the analogy will be irrepressible, so best to take it by the
horns and say how it differs. My main point is the need for a
description from the point of view of someone creating and managing
content deliverables. We already have one from the point of view of
someone making tools do the right thing. That's an adoption issue, so
I'm probably barking at the wrong alias. 

Sorry, have to run. Regrets for 2/1 and 2/8.

	/B

> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com] 
> Sent: Friday, January 28, 2011 1:23 PM
> To: Bruce Nevin (bnevin); dita
> Subject: Re: [dita] Groups - Understanding Keys and Key 
> Spaces (understanding-dita-keys-and-key-spaces.pdf) uploaded
> 
> To clarify a bit more:
> 
> Keyrefs can define text to be used as the link text for 
> elements that use keyref to point to their associated 
> resources. In the case where there is no actual resource then 
> the link text *is* the resource (or you could say the result 
> is a link to a null resource).
> 
> This aspect of keyref makes it look a bit like conref but 
> it's not really conref.
> 
> My point being that a keyref should always be thought of as 
> some form of link, even if there's no actual resource bound 
> to the key-defining topicref, because there always could be 
> in a different or future map.
> 
> Also, it's becoming clear to me that the use of keyref to get 
> just text, while convenient, is not and cannot be a 
> replacement for a more general "variable" mechanism that 
> allows for dynamic replacement of references with text where 
> the text is defined within a map, topicref, or topic scope.
> 
> Thus I think we need for 1.3 or later something like the 
> experimental "variable" domain I added to DITA for Publishers 
> recently.
> 
> Having such a mechanism would go a long way to both 
> satisfying a general requirement for context-dependent 
> variable text and removing the natural attempt to use keyref 
> for something it's not intended nor capable of doing.
> 
> Cheers,
> 
> E.
> 
> On 1/28/11 11:57 AM, "Eliot Kimber" <ekimber@reallysi.com> wrote:
> 
> > Keyref is not a content inclusion mechanism. It's an addressing 
> > mechanism that in DITA is used for both navigational linking and 
> > conref, so to make an analogy of keyref to conref would be 
> inaccurate and confusing.
> > 
> > Cheers,
> > 
> > E.
> > 
> > 
> > On 1/28/11 11:49 AM, "Bruce Nevin (bnevin)" 
> <bnevin@cisco.com> wrote:
> > 
> >> I'm going to be away until the 9th. I want to get this 
> comment in the 
> >> discussion hopper before I go.
> >> 
> >> "... create references to things without having to know 
> exactly where 
> >> those things are or will be in the future."
> >> 
> >> Without having to know where or what.
> >> 
> >> Eliot's excellent draft seems to be addressed to a fairly 
> technical 
> >> audience of implementers or technically savvy writers.
> >> 
> >> Adoption language addressed to writers, editors, and 
> managers might 
> >> start with an analogy to conref, something like:
> >> 
> >> Keyref is a content inclusion mechanism just like conref, 
> except that 
> >> it is specified with a variable, called a key. Keys are 
> defined in a map.
> >> If a topic that uses keyref is in a map where keys are defined for 
> >> product A, then content appropriate for product A is 
> included in that 
> >> topic; but if the topic is in a map where the same keys 
> are defined 
> >> for product B, then content for product B is included in the topic.
> >> 
> >> It's possible to define a key more than once in a map, for 
> example in 
> >> an included submap. However, only the first definition is 
> used, and 
> >> subsequent definitions are ignored. The effect is that the 
> choice of 
> >> specific content to include is always determined by the map author 
> >> when the topic author uses keyref to indicate variable 
> content. For 
> >> many purposes, keyref is much more robust and easy to manage than 
> >> profiling, which can get burdensomely complex with 
> intersecting patterns of reuse.
> >> 
> >> Knowing which key definition is first may not be obvious 
> if there are 
> >> submaps. In a given map, definitions are considered in document 
> >> order, from beginning to end of the map. Only then are submaps 
> >> considered in breadth-first order, that is, in the order in which 
> >> their references occur in the current map, and delaying 
> drill-down to 
> >> the next level of sub-sub-maps until all submaps at the 
> current depth 
> >> have been considered. An example will clarify this:
> >> ...
> >> 
> >> As you can see, keys are defined in <topicref> here. They 
> can also be 
> >> defined in <keyref>, a convenient specialization of <topicref>. 
> >> [Further discussion of the example.] ...
> >> 
> >> 
> ---------------------------------------------------------------------
> >> 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.ph
> >> p
> >> 
> > 
> > --
> > 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
> 
>