Use the <keydef> element, rather than <topicref>
The <keydef> element is a specialization of the <topicref> element. Although you can use the <topicref> element to define keys, it’s better to use <keydef> because:
- It indicates specifically what you’re doing (semantics).
- It automatically specifies processing-role=”resource-only”. Without this attribute, the output generator uses the referenced topic exactly where it occurs in the map, which is probably not what you want.
- It requires you to use the keys attribute (which helps if you tend to forget things like that).
Gather keys in submaps
It’s a good idea to gather all related keys together in a submap. There are two main reasons for doing this:
- Once you have gathered all related key definitions together in a single submap, you (and others on your team) can reuse that submap in maps or bookmaps for other output targets
- To change the key definitions used by the map or bookmap, it’s just a matter of switching out one key submap for another (rather than having to update all the keydef elements). Additionally, you can add multiple <mapref> elements to the map or bookmap and use DITA conditional filtering (as described in the first lesson of this course) to hide all but one of the <mapref> elements.
Adding key definitions to bookmaps
The structure of the <bookmap> element does not allow <topicref>, <keydef>, or <mapref> elements as children of the <bookmap> element, so there is no obvious place in a <bookmap> element to place your key definitions.
A number of DITA users place <keydef> or <mapref> elements as children of the <frontmatter> element. This ensures that they are immediately visible to people editing the bookmap.