DITA 1.3 Proposal 13004: Scoped Keys

[Eliot Kimber <ekimber@reallysi.com>]

Based on my initial reading I'm happy with the proposal as written as far as
it goes. However, there are a number of cases it doesn't address that I
think need to be worked out.

1. Is there a requirement to enable direct reference to keys within specific
scopes?

The proposal does not provide such a mechanism. Without it authors would
have to define global keys for any topic or map that needs to be addressed
across scopes and these keys would need to be different from any scoped keys
for the same topic or map (in order to avoid overriding the scoped
definition). I don't think that's necessarily a show stopper and may in fact
be best practice, but I do want to highlight the implication.

The alternative would be to provide a way to include some form of key scope
identifier or location as part of a key reference, which would require
knowledge of the specific map within which the key scope is defined, which
largely undoes the value of keys unless the key scope reference itself can
be done via keys (which I would definitely want). That starts to seem like a
lot of extra addressing complexity.

The proposal says that key scopes need to have names, which is good, but
they don't have to be globally unique or unique within a map tree, only
within a map document (think that's the only possible rule). That means that
they cannot be used alone for map scope reference but would have to
qualified with the address of the map document that contains them.

At that point there's no difference between a reference to a map scope name
and a reference to the scope-defining topicref by ID using existing
addressing methods, that is, either a keyref/id pair or a URI reference to a
map with a fragment identifier identifying the topicref within the map.

But given that, it could make sense to provide the attributes @keyscoperef,
@conkeyscoperef, @keyscopekeyref, and @conkeyscopekeyref to allow explicit
reference to key scopes, directly or by key.

2. The examples show that a global key definition that occurs *after* scoped
key definitions within the same map takes precedence over the key
definitions in the scope. This means that scopes within a map are treated as
though they were submaps for the purposes of constructing key spaces. That's
fine but I point it out because we'll have to highlight this change in
behavior over 1.2. 

3. If a topic is used in two key scopes and is not referenced using either
@copy-to or @chunk then what happens?

I think the only right answer is that, because of the key scopes, the
processor is obligated to make two copies of the topic in the result,
otherwise it cannot reflect scope-distinct addresses.

Is this interpretation correct?

4. I observe that one effect of this proposal will be to force key
definitions to the lowest maps in map trees in order to avoid inadvertent
overriding of scoped definitions by higher maps. That is, if I am using keys
to define "variables" and I want to ensure that I get the correct
definition, meaning the one that applies only in my use scope, I have to
either have full control over the entire map tree in order to ensure that
the correct definition is applicable for each use context or I have to
define submaps for exactly the use scope and define the "variable" keydefs
there. 

I think the analysis in the proposal is correct: we can't change the
precedence rules for keys without either seriously disrupting or seriously
complicating the key mechanism.

This is why I feel that a *separate* mechanism is required for variables,
one that reverses the precedence rules and that allows topic authors to
define default values for variables within topics (where those defaults can
be overridden in higher-level topics or in using maps).

5. The proposal doesn't discuss it in detail, but as written, sub map
documents explicitly do not establish new key scopes--you either add a
topicref in the map that establishes a key scope or you have the topicref to
the map establish the key scope. I think this is correct but I think this
might surprise some users who already expect submaps to establish new key
scopes. We would need to explain this detail clearly.

6. Note that with this proposal the distinction between "key space" and "key
scope" is pretty thin. A key scope as defined in the proposal is a key space
as meant in DITA 1.2, that is, a distinct namespace of keys that is disjoint
from any other key space.

The only real difference is that in the case of nested key-scope-defining
topicrefs, nested key scopes inherit key definitions from their ancestor
scopes, but that really only affects key space construction. It doesn't
affect key resolution against the constructed key space as the proposal is
clear that a key not defined in a key scope is not addressable from within
the scope of that key space, which implies that inherited key definitions
are effectively duplicated in each key scope they apply to. Of course a
processor could implement things less literally, but for the purposes of
understanding the abstraction defined by the proposal, each key scope is a
completely distinct key space.

The only other difference then is the association of a given key reference
with its applicable key space at resolution time. Per the proposal, that's
implicit in the using map structure (just as in DITA 1.2). But since we've
now established the existence of multiple key spaces within a single map
tree, it makes it easier to think about the utility and details of explicit
key space addressing, as discussed above.

Cheers,

E.


-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com