Table of Contents
User Guide
Key References
Key References
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.
Assigning a Key Name to Topics
Set the key name on a topic so you can indirectly link to it from a topic.
Inserting a Keyref
Insert a keyref to a key name defined in the map and create an indirect, inline link to an element in a map.
Key References

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.

section

Definition

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:
section

Keyref Example

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.
section

Maintentance Considerations

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.
section

Publishing Considerations

Your map won’t publish if the key references in the map are not resolved.
Assigning a Key Name to Topics

Set the key name on a topic so you can indirectly link to it from a topic.
  1. Open a map in the Map Editor .

    Expected Result
    The map displays in the Map Editor Pane.
  2. In the Map Editor , hover over the topic you want to assign a key name to.

    Expected Result
    A quick list of icons display.
  3. Select the key icon.

    Expected Result
    The Keys field displays.
  4. Enter a key name for the topic.

    Example
  5. Click Update .
  6. Click Save to save the changes you made to the map.
result

A key name is defined for the selected map element. This key name can be used when inserting a keyref in a topic. For more information, see Inserting a Keyref.

Inserting a Keyref

Insert a keyref to a key name defined in the map and create an indirect, inline link to an element in a map.
prereq
You must assign a key name to the topic that you want to indirectly link to before inserting a keyref. For more information, see Assigning a Key Name to Topics.
Remember:When using keys, you must have a map open or map context set in order to see available keys and for keyrefs to resolve.
  1. Open a topic in the Topic Editor . Topic Editor
  2. Place your cursor where you want to insert a keyref.
  3. Click Link -> Keyref . Keyref drop-down menu
  4. Enter or select the key name you want to create a keyref to.

    Example

result

A key reference is inserted in the topic, which indirectly links to the topic in the map with the key name.