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

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

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