Key references (keyrefs) are a form of indirect inline links that use key names defined in a map to link to resources. This type of indirect linking allows for topics to be reused in multiple publications.
You can think of key references as links to ‘things’ (key names) in a map rather than specific topics. And because you’re linking to ‘things’ and not specific topics, this makes linking more abstract and optimizes your reuse capabilities.
Let’s look at this another way. In your phone’s contact list, you probably don’t save your contacts based on their phone number and use their name instead. And any time that you want to call someone, you probably don’t search for the exact phone number. Instead you search for the contact’s name. Key references operate along these lines.
With key references, instead of linking to topics using the exact filename, you link to the key name assigned to it. This way, if the topic changes, you can easily associate the key name to another topic. Continuing with the phone example, if your contact’s number changes, you can just associate the contact name to a new number. And if the topic being referenced changes, just assign the key name to the new topic. This also allows you to reuse topics in multiple publication maps.
To create a key reference, you need to do the following:
You need to publish a manual for both the Toaster 1000 and Toaster 1500. Both publication maps reuse the Setting up the Toaster topic. However, they contain different Button Functions topics.
Although the content in the Button Functions topics is different, conceptually they’re the same. So, within each publication map, you’ll use the same key name for the Button Functions topics, which is buttonFunctions.
In the Setting up the Toaster topic, which is reused in both publications, there is a keyref indirectly linking to the key name buttonFunctions:
Depending on the publication map used, the link in the Setting up the Toaster topic will resolve to the corresponding Button Functions topic included in the map. Let’s look at the Toaster 1000 publication map:
When the Setting up the Toaster topic is in the Toaster 1000 map, the keyref to buttonFunctions will link to the Toaster 1000 Button Functions topic and display like this:
But when the Setting up the Toaster topic is in the Toaster 1500 map, the keyref to buttonFunctions will link to the Toaster 1500 Button Functions topic instead:
This enables you to reuse the Setting Up the Toaster topic in both publication maps. Then depending on the map context, the keyref resolves to display the corresponding topic the key name is assigned to in each map.
Key references are a complex and somewhat abstract method of linking, so maintaining keyrefs requires a thorough understanding of how they work. When you insert a keyref, you’re linking to the key assigned to a topic in a map, not the topic itself.
Key references are resolved using the map as context. When you reuse content with key references, you must always check to ensure that the keys will resolve correctly. You should also keep reuse opportunities in mind when authoring content with key references and consider where else that topic might be used in the future.
For example, if you insert a key reference in in a topic that references the key safety, you must ensure that there is always a topic with the key definition safety in any other maps you reuse that topic in. If you don’t have a key with that definition in a map, the map won’t publish.
Similarly, your key names must be unique. If you have two keys with the same name, when you publish, the key will resolve to the first instance of that key name in the map. For this reason, you should develop a key naming strategy that is easy to understand and replicate as you reuse maps and topics.
There are two reports available in easyDITA to help you manage your key references. The varsReports/reportInvalidKeyrefs checks for broken key references. This report lists keyrefs linking to key names not defined in the map. The varsReports/reportFolderKeys identifies all the keys used in a specific folder and where they’re used.
Your map won’t publish if the key references in the map are not resolved.