What user need will be met by this feature?
Users can define various glossary entries which serve as specific terms or acronyms. Such glossary entries will be expanded to appropriate form according to the context automatically.

What is the technical design for the change?
Key definitions and references are already prepared during key definition parsing process, so we mainly focus on how to resolve keyref accordingly in appropriate contexts. Here we have 2 problems yet to solve while resolving the keys:

1. How to determine in what context a key is referenced? The description on how to distinguish introductory context from other contexts in “DITA Proposed Feature #12026 and #12038” is not clear enough to define all possible contexts that would be encountered. Thus we classify the contexts into three specific situations for the time being. More accurate definition and classification of different contexts should be considered thoroughly and added later.

a)    The very first appearance of a keyref pointing to a certain glossentry in a deliverable book context should be expanded to its surface form; otherwise an acronym form (or other forms appropriate) should be used. Intuitively, the very first topic entity that we encounter during preprocess (either directly in a topic dita file or indirectly referenced in a ditamap file) would be an introductory context for the whole book. Thus, all keyrefs appearing in this first topic should be expanded to surface form. Keyrefs in other contexts are replaces with other appropriate forms of the corresponding glossentry.

b)    The terms appearing in online documents should have a hover tooltip of its surface form.

c)    Terms appearing in copyright declaration should be expanded to its surface form.

2. How the contents of glossentries are saved and used. We prefer to use a lazy-loading mechanism as follows:

a)    When the keyref is encountered for the first time, the target file associated with the key should be parsed and corresponding surface form together with other forms should be loaded into memory and saved with the key as a triplet. We use a Hashtbale to store such triplet, concatenating all the forms together separating by a stick.

b)    If it is not the first time the keyref is resolved ( there is an existing entry in the Hashtable mentioned above), appropriate form is retrieved and used.

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