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<String, HashMap<String, HashSet>>
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