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.