Review #2 comment: Rules for key definition precedence

[Kristen James Eberlein <kris@eberleinconsulting.com>]

DITAweb URL:
https://ditaweb.com/oasis-dita/#/00074601-DA$00074397-DB$Core%20concepts%20for%20working%20with%20keys

Text in question:
"When a key has a definition in a parent scope's key space, that definition is effective. Otherwise, a key definition is effective if it is first in a breadth-first traversal of the locally-scoped submaps beneath the scope-defining element. Put another way, a key definition is effective if it is the first definition in the shallowest map for that key. This allows higher-level map authors to override keys defined in referenced submaps."

Comments

[Eliot Kimber]

This paragraph leaves out the general first-element in scope rule. I think it needs to be more like:

The rules for determining effective keys are:

• Within the same XML document, for each scope, the first key definition in normal depth-first document order is the effective definition for that key name within the scope and any descendant scopes.
• Within the tree of maps referenced from within a scope, the first definition, in normal depth-first document order, in the first map within a breadth-first traversal of the map tree.

[Eliot Kimber]

It took me a minute to figure out what the first sentence was really saying. It took me a few false starts to realize that the existence of key scopes changes the simple key definition predecence rule.

In addition, this paragraph does not reflect everything in the 1.2 spec's section on this, which I think is all essential:

"For a given key there is at most one effective definition within a key space. A key definition is the effective definition for a given key if it is the first, in document order, within the map document that contains it, and is the first in the map tree in breadth-first order. It is not an error for the same key name to be defined more than once within a map or map tree, and duplicate key definitions  should  be ignored without warning."

There are important things in this paragraph that have not been preserved, in particular that it is not an error to define the same key name more than once.

[Kris Eberlein]

I think the use of the term "parent scope's key space" is impeding comprehension here. Could it be rephrased as the "key space associated with the parent scope"?

--
Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)