Indirect content referencing

The keyref feature was introduced in DITA 1.2 to allow indirect referencing in links, images, and content references. Rather than referencing an element directly in the conref attribute, you can reference a key, the destination of which you specify in the ditamap.

You may sometimes need to conref different text depending upon the context of the output publication. For example, when publishing a user guide for the Australian market you may want to include the telephone number of the Australian office, but when publishing for the New Zealand market you may want to include the New Zealand office number. You could use conditional publishing in this scenario, but the keyref feature is much simpler.

The process is to use a conkeyref attribute to reference a key to the topic containing the re-use elements, and the id attribute of the element to re-use, using the syntax key/id.

For example, instead of <ph conref="conref_contacts.dita#contacts/aus_phone" />, you would use the code <ph conkeyref="reuse/office_phone" />. In the Australian user guide ditamap, you would define the URI of the topic with a key of reuse in the Australian context, such as <topicref keys="reuse" href="reuse_aus.dita"/>. In the New Zealand user guide ditamap, you could define the reuse key as <topicref keys="reuse" href="reuse_nz.dita"/>. Both topics would have a phrase (ph) element with an id of office_phone, containing the respective telephone numbers.