Arbortext Editor provides support for key based references as defined in the Key based (indirect) addressing section of the OASIS DITA Architectural Specification. The Arbortext Editor user interface provides many features to assist you with both defining key definitions in your DITA maps and inserting key references in your maps and topics. In addition, Arbortext Editor provides a specialized DITA map intended for just containing key definitions called the DITA Key Definition Map. This map enables you to provide additional information for your key definitions.

The best practice for storing your key definitions is to have a DITA map that is dedicated to just holding key definitions. You can then use a mapref element to include the map containing your key definitions in any other DITA map as needed. It is suggested you use the DITA Key Definition Map to store your key definitions.

The following parts of the Arbortext Editor user interface support key references:

By default, the key reference user interface is available in Arbortext Editor. If you are not using key references in your DITA documentation, you can remove the key reference features from the user interface.

Whether the key reference user interface is available is controlled by the ditakeyrefui advanced preference. Set the value of this preference to off to remove the key reference user interface.

For Arbortext Editor to find the key definitions associated with key references, it must know the key context for the current document. The key context is a DITA map that contains the relevant key definitions. If the map containing the definitions is a DITA Key Definition Map, you can add additional information to the key definitions that appears in the key reference user interface. The key context for a document is determined by the settings of the ditakeycontext set option.

The ditakeycontext option is set to a single map and defines the primary key context for the current document during the current session. When a document has a key context established, it affects how Arbortext Editor handles references. For example, if an image tag has both an href and a keyref attribute defined, Arbortext Editor displays the image from the keyref attribute’s key definition. Arbortext Editor gives a key reference or content key reference precedence when there is an established key context that contains a matching key definition.

You can set the ditakeycontext explicitly, or Arbortext Editor sets it automatically in some cases. For example, if you open a document through double-clicking on a cross reference, topic reference, and so forth, the key context for the original document is applied to the newly opened document. Similarly, when you open a document from an Arbortext Editor DITA-related dialog box, the key context for the current document is applied to the opened document. If the original document is a DITA map that does not have a key context, that map becomes the key context for the opened document.

Another option that determines the key definitions available for inserting into a document is the ditakeybaselist set option. You use the ditakeybaselist option primarily to establish the list of maps used for the key definitions displayed in the Insert Key Reference dialog box and in the Resource Manager’s Keyref option. Unlike ditakeycontext, ditakeybaselist is an advanced preference, can contain multiple maps, and persists across Arbortext Editor sessions. If you have assigned a value to the ditakeybaselist and the map that is the current ditakeycontext is not in that list, the key context map is added to the beginning of the list of ditakeybaselist maps for the current session.

Arbortext Editor provides a specialized DITA map called the DITA Key Definition Map. This map contains additional elements that enable you to provide more information in your key definitions and is intended to be used just for storing key definitions. The extra key definition information is displayed in the key reference user interface in various places. The DITA Key Definition Map is in the New dialog box’s DITA Technical Content category.

The key definition map adds extra elements to the topicmeta element that provide more information about the key definitions. To use these elements, you would insert a keydef element into the map, insert a topicmeta element in the keydef element and a keyinfo element in topicmeta. You can then insert whichever of the new metadata elements you would like to use inside of keyinfo. You can also use the Resource Manager’s Key Definition tab in a key definition map to add this extra information to your key definitions.

The following additional elements are available in topicmeta for regular key references:

To replace content through a key reference in Arbortext Editor, you can use the conkeyref attribute on an element to set up a content key reference. As with regular key references when a content key reference has an associated definition in the key context for a document and an element has both the conref and conkeyref attributes defined, Arbortext Editor displays the content associated with the conkeyref and generally gives the key content reference precedence.

You can use a regular key definition to set up the keys for content key references. However, the DITA Key Definition Map provides some additional elements to assist you with defining key definitions for content references. Also, to include content key references in the Insert Key Reference dialog box, you must define the associated key definitions in a DITA Key Definition Map. The following additional elements are available for content key references:

Using a DITA Key Definition Map, you can set up your content key definitions so that either a single element is available for a content key reference or all elements with IDs are available. To make a single element available for a conkeyref reference in the Insert Key Reference dialog box, you must define it in a DITA Key Definition Map using the following markup:

For example, the following key definition adds the ph element with the ID custom in the topic strings.dita to the Insert Key Reference dialog box as a conkeyref target:

To make all elements with IDs available in a map or topic for a conkeyref reference in the Insert Key Reference dialog box, you must also define that in a DITA Key Definition Map. You can define that markup in one of the following ways:

You can also use regular key references to insert text into your documents. Many DITA elements have the keyref attribute. You can include text in your key definitions to insert into these elements, when the element is empty and has a key reference set. The element must be empty to be used for text insertion. For example, you could have the following element in your document:

The key references the following key definition:

When you publish the document, the following text is inserted in the ph element:

You can also include markup with the text you want to insert. For example, when the key references the following key definition:

The following text is inserted in the document:

In addition to inserting text, you can also turn non-linking elements into linking elements and vice versa by including an href attribute in your key definition. For example, consider the following key definitions:

These key definitions are referenced by the following elements in your document:

When the document is published, the following text is inserted into your document:

Note that when the key definition has an href assigned, the element into which the text is inserted becomes a linking element. When it does not have an href assigned, even a linking element such as xref does not contain a link. This linking behavior applies even if the element referencing the key definition contains content and cannot be used for text insertion. For example, consider when the following element references the key definition above:

In this case, the key reference just makes the element a linking element and does not insert the text in the key definition when the document is published:

The text to be inserted from a key definition is determined in the following order of precedence:

For example, the following key definition contains text in more than one of the possible areas for text insertion:

In this case, the text inserted for a key reference is the contents of the keyword element since it has a higher precedence than the contents of the navtitle attribute.

The following elements are special cases for text insertion:

The Arbortext Editor user interface provides the following features to support inserting text with key references:

When a topic reference contains a key reference, some of the information in the topicmeta element might conflict with similar information in the key definition. The topicref element contains a topicmeta element as does a key definition. The following rules are followed when merging the topicmeta content of a topicref with a key reference and the referenced key definition: