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

[Eliot Kimber <ekimber@reallysi.com>]

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