Part of Plans for DITA Open Toolkit 1.5

Plans for implementing keyref linking in the DITA Open Toolkit

What user need will be met by this feature?

Users can use @keys in <topicref> to define keys and utilize those specified keys by @keyref and @conkeyref.

What is the technical design for the change

1. Parse key definition
Key defnitions are defined in ditamap
We will parse ditamap, find all the key definitions during first step of preprocessing. Definitions include three parts, key name, target and content, so key defs should be stored in the form of triplet. Based upon the spec, key defs are defined by using breadth-first parse method. And there should be no duplicated key defs in a single ditamap. When we find a key definition which has been defined before with the same key name, the previous one should be used and the current one should be ignored. This job will be done by GenList module. For the purpose of avoiding to re-parse ditamap in the next step, the content of key definition will also be
stored. We need a data structure to store this kind of data, we can use HashTable<String, String>, target and content can be combined into one sigle string using a stick to seperate them, and this table will be passed down to the other modules in preprocess.
In order to facilitate next related modules, the name of dita file which contains @keyref should also be stored, the list name is keyreflist. @conkeyref can be processed in DebugAndFilter, just replace it with conref. This resolution of conkeyref may demand that conreflist should include the name of the file which contains @conkeyref.

Note:Because the content of key definition mignt contain @conref, we can not simply store the content during the first parse of ditamap files in GenList step. The content should be read when we resolve the keyref. In Genlist module, we only store the key name, target of the key and the location where the key is defined. The key definition location is necessary because the same key name can be defined in different ditamap and we use the breadth-first method to determine which one should be the effective key. We need the key definition location to keep the memorize the effective key and prevent reading the wrong content for the key in later step.

2. Resolve keyref
We prefer to use a new Module to resolve @keyref, name it KeyrefModule for the time being. You can see bullet 4 for details about this module. And where should we put this step in preprocess? Because keyref may pull attributes and content to its element, three modules may be influenced. After considering the MoveMeta, MapPull and TopicPull, we decide to insert it between MoveMeta and Mapref. The reasons are listed as following:
MapPull: This module will pull some link metadata information of topic into <topicref> which refers to it. If KeyrefModule is behind MapPull, metadata information of topic will not be pulled in by MapPull, because MapPull cannot recognize keyref attribute. So it is reasonable to put KeyrefModule before MapPull, and make the MapPull take effect with regard to keyref.
TopicPull: This module will pull some link meta information from the source into target. Note that it parses all the dita topic files. If KeyrefModule is behind it, cross referece between topic using keyref couldn't be processed, because TopicPull cann't recognize keyref attribute as MapPull.
MoveMetaData: This module will move all metadata recorded in map into topics. According keyref spec, content in key definition and elements referencing the key may be combined. If the keyref is used in map and the contents are combined, then metadata may be moved twice or more into a single topic. So KeyrefModule should be after MoveMetaData.

3. Resolve conkeyref
We put the resolution of @conkeyref into DebugAndFilter, reslove all the conkeyrefs and replace them with conref. Leave it to Conref for conref resolution. As proposed in before, conref list includes conkeyref, so conref list doesn't need to be updated in DebugAndFilter.

4. KeyrefModule
For tihs iteration we only consider redirecting link, the problems of combining contents and attributes are left in future iteration. The input of KeyrefModule are one HashTable containing all the information of key definitions and conref list containing all the file using @conkeyref attributes. We may need another class to help this module to fulfill its function, name it KeyrefParser temporary. KeyrefParser, will parse the file containing keyref, and resolve the keyref with related key definition in HashTable depend on key reference's formation. In the future iteration, we will utilize the content in HashTable, but now redirecting link only use the target value recorded in hastable.

Note:The contents of key definition has not been ready for design yet, they should be read from the map where it is defined. We will use a reader to do his job, name it KeyrefReader and design the detail of it when spec for keyref content is ready.

What sections of the toolkit will be impacted by the change?

See also

none