Should short strings use text keys or conkeyrefs?
If you want to use keys to reference a short string, such as your company name, a text key is the easiest way to do it.
However, the <keyword> element used to define text keys can only contain text, the <text> element, or the <tm> (trademark) element. If the string requires internal markup, it’s better to use a warehouse file to define a <ph> (phrase) element containing the string and its markup.
For example, for the company name “Pure-H2O”, you could not store this in a <keyword> element; you would need to use a <ph> element:
<ph id="company_name">Pure-H<sub>2</sub>O</ph>
To create a reusable topic that referenced a company name, use a <ph> element with a conkeyref to pull in the name.
To use conkeyref or conref push?
A good rule of thumb for deciding between using conkeyref and conref push:
- If the element will always be present, but will change depending on the intended target, use conkeyref.
- If the element will only be present for one or two intended targets (out of many), use conref push.
Gather keys in submaps
As recommended in the lesson on using keys, it is a good idea to use submaps to gather the key defininitions for conkeyrefs.