You can use a key as a variable for replaceable text in your DITA topics. Typical uses of keys for text variables include:
- Product names
- Product numbers
- Company names
- Telephone numbers
- Titles of other books in a document set
Although there is no limit on the length of the string defined by a key, strings in keys are usually fairly short.
Note: The previous course (Introduction to reuse in DITA) pointed out that it was not a good idea to use replaceable text in anything smaller than a sentence. Overall, this is good advice. However, if you are using keys for a company or product name, particularly when documenting a product that might be rebranded or OEMed, the convenience and consistency provided by keys may outweigh some considerations of localization.
To define a key that will contain a text string, use the keys attribute to name the key, then nest a <topicmeta> element containing a keyword definition inside the <keydef> element. For example:
<keydef keys="product_name">
<topicmeta>
<keywords>
<keyword>Duck Database</keyword>
</keywords>
</topicmeta>
</keydef>
This syntax is quite verbose. The good thing is: you define it once, then forget about it.
Note that the string is limited to the content that is allowed in the <keyword> element, that is: plain text, the <text> element, and the <tm> (trademark) element. You cannot use other elements in the string to provide inline formatting or cross-references. If you need additional elements within the string, consider using a conref instead.
Using the key
To use a key for a text string, use the keyref attribute with these elements (or any element specialized from these elements):
- <ph>
- <term>
- <keyword>
This example shows how a key can be used with a <ph> (phrase) element:
Congratulations on purchasing <ph keyref="product_name"/>!
When the DITA map includes the <keydef> element shown above, the output would contain:
Congratulations on purchasing Duck Database!