Insert Key Element Reference

Inserts an element whose content is defined by content within a key definition.

Note: The term “key element reference” is not an industry standard term. We use this term in lieu of any other useful term for this DITA construct.

The Insert Key Element Reference dialog lets you select the keyspace and the key, then it displays the available elements and their current values.

Figure 1. Insert Key Element Reference dialog

A keydef that contains a topicmeta element with a linktext child will add the content of linktext into any element that you insert which references the associated key.

If a keydef does not define any a topicmeta content, the title text from the referenced topic is used as the content for the key element reference. You can override the title text by providing an Alternate Text value.

To define the content of specific key-based elements, include those elements in the topicmeta element. In the following example key definition of a “ditafmx-ini” key, inserting the apiname element will provide the content “DITAFMX-INI” for references that use the apiname element while all other elements will use the content of the linktext element as “ditafmx.ini.”

Important: While the use of the linktext element as described above is clearly indicated as valid in the DITA specification, processing by the DITA Open Toolkit does not seem to honor this structure. You may want to use the alternate method described below, which does work in OT processing.

If your keydef includes a keyword element (within keywords), that value will also be used when inserting a key element reference of non-matching element types. For example, if you insert a key-referencing ph element, the content within the ph will be that of the keyword element.

References to glossary entries

DITA-FMx supports the use of key-based references to glossary entries. When setting up a map that contains topicrefs to glossentry topics, assign a key to that topicref (or glossref) so the glossary term can be referenced by a key. (If using a topicref, remember to set the type attribute to “glossentry”.)

Assuming that your glossary entries are identified by a key, insert a term element with the keyref set to the value of the key. While authoring, the content of the term will match that of the glossary entry’s title (the glossterm element).

If you enable the Glossary Term Swapping option (in the Book Build Settings dialog), the term will render the glossSurfaceForm content in the first instance of the term in a book component, and the value of glossAlt (glossAcronym or glossAbbreviation) for remaining instances.