Note: This is a design discussion about how to implement Controlled Values Files - a major item in the upcoming DITA 1.2 standard - within the DITA Open Toolkit. For information about this new OASIS feature, please see the approved proposal here:
http://www.oasis-open.org/committees/download.php/26359/IssueControlledV...
along with the post-approval clarifications:
http://wiki.oasis-open.org/dita/scheme_map_clarifications
--------------------------------------------

CVF provides DITA adopters with a method for defining controlled values as part
of their content. This approach has the following benefits.
1. Adopters can easily define controlled values for the DITA attributes and
other purposes without special technical knowledge.
2. Parnters can share the definition of controlled values so that, when
building their combined content, a common set of filtering and flagging
values can be applied.
3. Tools have the option to validate controlled values for attributes
against the definitions.
4. Controlled values can be used to classify content for filtering and
flagging at build time but can also scale for retrieval and traversal at
runtime if sophisticated information viewers are available.
After inspecting the specification of CVF proposal, we come to the conclusion
that CVF entries are actually a tree-like structure which can be extended at
any level. Values are organzied hiearchically which indicates a
paren-children-like relationship between related values. And upward scheme
extension indicates a sibling-like relationship between original and extended
schema. Thus it is intuitive and straight forward to organize controlled values
in a simlar manner, which can be achieved by parsing and merging the controlled
values into a tree structure. That is to merge all schema into a final scheme.
This tree structure is designed to be generated in GenList module. As the
module parses and collects different entries and catagorize them into
differenct lists, the analyse for CVF values is performed simutaneously.
We intend to use DOM tree as our data structure because it stores structural
information about the subject scheme documents which is critical for extending
a scheme. SAX is good for parsing documents as text streams but not good at
dealing with structural operations.
Our approach takes schema maps as input sources, parses them into document tree
models and then merge them together to form a complete scheme. The resulting
model will be outputed in XML format for usage in debug-and-filter module which
uses controlled values to validate and filter-flag dita elements. Assuming that
the final output tree is T and the element being processed currently is E,
initiall T = E = null, let the map currently being parse be M and the element
SAX currently encountered be N, we will modify SAX logics in GenListReader to
build our document tree as:
In startElement:
if M is a subject scheme map (its root element is subjectScheme)
if E == null, T = E = new document root.
if P is of subjectdef type
for each node X in E's children
if X has the same key value as P
E = X, we found an extension point
if no valid extension point found
X = new P
add X to E's children
E = X, need to add X's children to E
if P is of schemeref type
add P's href value to waitList as merging A scheme to B scheme is
equal to merging B to A, thus just leave it to be parsed later
if P is of enumerationdef type
X = new P
add X to E's children
E = X
if P is of attributedef or elementdef or defaultSubject type:
X = new P
add X to E's children
E = X
In endElement:
if E is not the document root
E = E's parent node
When gen-list finishes, a merged scheme which contains all valid subject
definitions will be constructed in T. We need to output it as a persisten file
for usage in later modules.
Next, in debug-filter module, the resulting document tree will be use to
validate and filter/flag topic contents. As CVF defines a hierarchical
structure of controlled values which employs contains/contained-by
relationships, filter operation applied to "container" subject should also be
applied to "contained" subjects, e.g. operations applied to elements with
@platform="linux" should also affect elements with @platform="redhat" since
redhat is a linux. Thus when we are parsing ditaval files, hierarchical
information defined in schema maps need to be considered accordingly. Here the
merged scheme is utilized as it contains all information we need. In
DitaValReader, before putting key-action pair into filterMap, we search for the
attribute binding for the current @att, if a subject scheme is associated with
this attribute, then add all related descendant subjects to filter map, e.g.
suppose @platform is bound to "os" subject, as in ditaval an "exclude" action
is defined for any element with @platform="linux", then we need to search for
linux definitions in os subject and add all its values into filter map because
redhat, suse and ubuntu are linux too:
(Assumptions are the same as above, P is the current element in SAX)
// We use a cache map CM to accelerate the attribute binding search
CM = new HashMap>
for each element X in T's children
// enumerationdef only appears as direct child of root
if X is of enumerationdef type
localname = null
elementname = "*"
for each element Y in X's children
if Y is of elementdef type
elementname = Y's @name
continue
if Y is of attributedef type
S = CM.get(Y's @name)
if S == null
put (Y's @name --> HashMap) into CM
localname = Y's @name
continue
Z = find binding in CM with key=P's @att
if Z == null
Z = do a BFS in T to find @keys == Y's @keyref
if Z != null and localname == P's @att
for each node V in {Z, Z's children}
if V is of subjectdef type and V's @keys == P's @val
for each node Q in {V, V's children}
put (P's @att = Q's value --> action) into filterMap
if Z != null
S = CM.get(localname)
if S != null
A = S.get(elementname)
if A is not empty, then add Z into A
else
A = new HashSet(Z)
put (elementname --> A) into S
else
S = new HashMap
put (elementname --> new HashSet(Z)) into S
put (localname --> S) into CM
When DitaValReader finishes, filterMap contains all possible filter actions.
The cache map CM we used is also useful in validating properties, so we will
process it and pass it to debug writer. In DitaWriter:
S = CM.get(P's attribute name)
if S != null and S is not empty
if S.keySet() contains "*"
A = S.get("*")
else if S.keySet() contains P's element name
A = S.get(P's element name)
if A != null and A is not empty
for each subject tree K in A
do BFS in K for P's attribute value
if not found
throw a warning that the property value is invalid
Modifications will be mainly in GenListModule.java, GenListAndMapReader.java,
DitaValReader.java, DitaWriter.java