RE: [dita] Quick reality check on FAQ item #2

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

The introduction seems incomplete. It gets as far as establishing the map tree. It doesn't say how this helps us to determine which of two key definitions is effective.

 

The interplay of the concepts "depth first" and "breadth first" is a bit tricky to express in words because "depth first" or document order applies first to key definitions within the current map and then to @href submap references within that map. "Breadth first" is at a different level of abstraction as a consequence of exhausting the latter within the referencing map before moving on.

1. Depth-first (document order) determines which key definition within the current map (beginning with the root map).
2. Depth-first (document order) determines which submap reference within the current map (beginning with the root map).
3. Breadth-first requires that key definitions be considered (in document order) in all children of a given map  before submap references found in that map (in document order) are followed.

 

Is there really more than one way to do this, or could we go so far as to specify an algorithm? Or barring that, do so as an example of one way to do it? As a quick sketch, something like:

1. Consider all the key definitions in the current map
2. For each @href reference in the current map, consider all the key definitions in the referenced submap.
3. For each @href reference in the current map, apply steps (1) and (2) to the referenced submap. 

 

Meta-rule: when you find a definition for a given key name, ignore any further definitions of that key name.

 

Note that these are all document order or depth-first processes, and "breadth-first" falls out as a consequence of (3). It might be better not to get tangled up with those terms because of the abovementioned trickiness of expression.

 

    /B

---

From: Kristen Eberlein [mailto:keberlein@sdl.com]
Sent: Tuesday, March 15, 2011 10:05 PM
To: dita
Subject: [dita] Quick reality check on FAQ item #2

There is one part of FAQ item #2 that I would like TC members to do a quick reality check on. (FAQ item #2 is the one about “Question about the order in which keys are resolved".)

 

Eliot wrote the FAQ item; I edited it heavily and added example #3.

 

I’m confident that the “Overview of key-binding precedence” and the examples make it clear how keys should be resolved. However, I’d like to make sure that a statement in the introduction to the FAQ maps well to the content explicated in the “Overview” and examples.

 

Here is a copy-and-paste of the introduction, with the key (no pun intended) text highlighted in bold:

----------------------------------------------------------------------------

A root map and its referenced sub maps can contain multiple different definitions for a key. So, given the possibility of multiple definitions for a key name, how does a processor determine which key name is effective?

The DITA 1.2 specification outlines the following rules:

1. Determine the root map
2. Construct the map tree

First, the processor must determine the root map that establishes the key space. (A processor cannot perform key resolution until the appropriate resolution context has been defined.) For processors such as the DITA Open Toolkit, the root map is obvious–it is the DITA map to which a transformation is applied–but for authoring tools and component content management systems, the root map is not necessarily obvious; such processors might require that a user explicitly select the root map.

Second, the processor must construct the map tree. The map tree consists all maps referenced from the root map by @href attributes, all maps referenced from submaps by @href attributes, and so on down the map hierarchy.

The order in which processors must construct the map tree is determined by the document order of the references to the maps in a normal depth-first traversal of the element tree in each map.

Note:

1.    The term document order is formally defined in the XPath Recommendation: http://www.w3.org/TR/xpath/#dt-document-order

2.    The term map tree refers to the tree of maps constructed as described here, not the XML element tree for the elements within a single map document.

 

----------------------------------------------------------------------------

 

Does the text highlighted in bold clearly and unambiguously match what is outlined the subsequent sections of the FAQ?

 

You can view the draft FAQ at http://wiki.oasis-open.org/dita/FAQ-items; the Wiki page for review comments is at http://wiki.oasis-open.org/dita/Review-FAQ-

Best regards,

Kris

Kristen James Eberlein l DITA Architect and Technical Specialist l SDL Structured Content Technologies Division l (t) + 1 (919) 682-2290 l keberlein@sdl.com

Please consider the environment before printing this e-mail