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.

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
mapref and mappull. 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.

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

Genlist, DebugandFilter, conref resolution, move meta, map pull, topic pull.

 

See also

none