Review #2 comment: Rules for key definition precedence

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)