Working with Variable Text in DITA

You may often find that you want a certain piece of text in a topic to have a different value in various circumstances. For example, if you are reusing a topic about a feature that is shared between several products, you might want to make the name of the product variable so that the correct product name is used in the manual for each product.

For example, you might have a sentence like this:

The quick-heat feature allows [product-name] to come up to temperature quickly.

You need a way to substitute the correct product name for each product.

One way to do this would be to use conditional profiling, as in this figure:

Figure: Variable content using profiling

<p>The quick-heat feature allows 
    <ph product="basic">Basic Widget</ph>
    <ph product="pro">Pro Widget</ph>
    <ph product="enterprise">Enterprise Widget</ph>
to come up to temperature quickly.</p>

Creating Variable Text Using Keys

In DITA, you can create variable text using keys.

One way to do this would be to provide conditional values using the product profiling attribute.

However, this approach means that you are repeating the product names over and over again everywhere the product name is mentioned. This is time consuming for authors and will create a maintenance problem if the product names change.

Creating Variable Content Using a Key Reference

The alternative is to use a key reference, as in the following example:

Figure: Variable content using a key reference

<p>The quick-heat feature allows <ph keyref="product"/> to come up to temperature quickly.</p>

The key reference stands in for the name of the product. When the content is published, the current value of the key product will be inserted.

To insert a key reference into a document in Oxygen XML Editor Author mode, follow these steps:

Press Enter and select any DITA element that supports the keyref attribute.
Select Edit Attributes from the contextual menu (or simply press Alt+Enter) to bring up the attribute editor.
In the Name field, select keyref.
In the Value field, select or enter the name of the key.
Note: Additionally, if you have a need for reusing the key reference pattern while editing your documentation, you could add that pattern to a code template so that it appears in your list of content completion proposals.