Key Reference (keyref)

The key reference mechanism has been developed to decouple information.

Sample project: keyref.zip

Consider that the only linking mechanism in a DITA environment would be a relative link:

<!-- Move a directory level up (../) and go to topic.dita --> 
<topicref href="../topic.dita"/>

<!-- Step into the "subdir" directory and go to topic.dita -->
<topicref href="subdir/topic.dita"/>

If topics would link heavily among each other, renaming or moving files or directories would cause a lot of trouble.

As a solution, keys can be added to topics and elements on DITA Maps. Afterwards these topics and elements can be pulled by their keys. The file paths are fetched from the DITA Map.

keyref.ditamap

The keyref.ditamap contains a <keydef> element that has a @keys attribute with the value product. The wrapped <keyword> element can then be pulled into the topics with a key reference (@keyref).

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
    <title>keyref</title>
    
    <!-- The <keydef> element defines the key "product" for a <keyword> element. -->
    <keydef keys="product">
        <topicmeta>
            <keywords>
                <keyword>My Product</keyword>
            </keywords>
        </topicmeta>
    </keydef>
    
    <topicref href="keyref.dita"/>
</map>

keyref.dita

The <keyword> element is replaced with the <keyword> element from the keyref.ditamap.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="keyref">
    <title>keyref</title>
    <body>
        <p>Thank you for buying <keyword keyref="product"/>.</p>
    </body>
</topic>

The rendered output is:

Thank you for buying My Product.