Examples of keys

A generic topicref element used to define a key bound to a topic:

<map>
  ...
  <topicref keys="apple-definition"
    href="topics/glossary/apple-gloss-en-US.dita"
  />
  ...
</map>

In this example, the topicref is acting as both a key definition and contributing to the navigation structure of the map, meaning the topic apple-gloss-en-US.dita will be processed as it would be if the @keys attribute were not present.

The same key definition using the <keydef> specialization of <topicref>:

<map domains="(map mapgroup-d)">
  ...
  <keydef keys="apple-definition"
    href="topics/glossary/apple-gloss-en-US.dita"
  />
  ...
</map>

Because the <keydef> element sets the default value of the @processing-role attribute to "resource-only", the key definition does not contribute to the map's navigation structure, but only serves to establish the key-to-resource binding for the key "apple-definition".

Duplicate definition of the same key:

<map domains="(map mapgroup-d)">
  ...
  <keydef keys="load-toner"
    href="topics/tasks/model-1235-load-toner-proc.dita"
  />
  <keydef keys="load-toner"
    href="topics/tasks/model-4545-load-toner-proc.dita"
  />
  ...
</map>

In this example, only the first definition in document order of the "load-toner" key is effective, so all references to the key within the scope of the root map will resolve to the topic model-1235-load-toner-proc.dita, not topic model-4545-load-toner-proc.dita.

Duplicate definitions with different conditions:

<map domains="(map mapgroup-d)">
  ...
  <keydef keys="file-chooser-dialog"
    href="topics/ref/file-chooser-osx.dita"
    platform="osx"
  />
  <keydef keys="file-chooser-dialog"
    href="topics/tasks/file-chooser-win7.dita"
    platform="windows7"
  />
  ...
</map>

In this example, both key definitions use the @platform metadata attribute to indicate that they apply to different operating system platforms. In this case, the effective key definition is determined not just by the order in which the definitions occur but whether the active value of @platform is "osx" or "windows7" when the key space is determined or the key is resolved. In this case both key definitions are potentially effective because they have distinct values for conditional attributes. Note that if no active value is specified for the @platform condition when determining the effective keys, then both of the definitions are effective and thus the first one in document order is the effective definition.

If the DITA value configuration were defined such that the default behavior is "exclude" rather than the normal default of "include", then neither definition would be effective and the key would be undefined. That case can be avoided by specifying an unconditional key definition after any conditional key definitions, e.g.:

<map domains="(map mapgroup-d)">
  ...
  <keydef keys="file-chooser-dialog"
    href="topics/ref/file-chooser-osx.dita"
    platform="osx"
  />
  <keydef keys="file-chooser-dialog"
    href="topics/tasks/file-chooser-win7.dita"
    platform="windows7"
  />
  <keydef keys="file-chooser-dialog"
    href="topics/tasks/file-chooser-generic.dita"
  />
  ...
</map>

In this case, with an explicitly-configured default behavior of "exclude", if no active value for the platform condition is specified, the third definition will be the effective definition, binding the key "file-chooser-dialog" to the topic file-chooser-generic.dita.

Duplicate key definitions using subordinate maps

Root map:

<map domains="(map mapgroup-d)">
  <keydef keys="toner-specs"
   href="topics/reference/toner-type-a-specs.dita"
  />
  <mapref href="submap-01.ditamap"/>
  <mapref href="submap-02.ditamap"/>
</map>

submap-01.ditamap:

<map domains="(map mapgroup-d)">
  <keydef keys="toner-specs"
   href="topics/reference/toner-type-b-specs.dita"
  />
  <keydef keys="toner-handling"
   href="topics/concepts/toner-type-b-handling.dita"
  />
</map>

submap-02.ditamap:

<map domains="(map mapgroup-d)">
  <keydef keys="toner-specs"
   href="topics/reference/toner-type-c-specs.dita"
  />
  <keydef keys="toner-handling"
   href="topics/concepts/toner-type-c-handling.dita"
  />
  <keydef keys="toner-disposal"
   href="topics/tasks/toner-type-c-disposal.dita"
  />
</map>

In this example the effective key space is:

The binding for the key "toner-specs" in the root map is effective because it is the first encountered in a breadth-first traversal of the map tree. The binding for the key "toner-handling" to the definition in submap-01.ditamap is effective because submap-01 is included before submap-02 and therefore comes first in the map tree. The binding for the key "toner-disposal" is effective because it is the only definition of the key in the map tree.

A key definition that uses elements within the key definition rather than a separately-addressed resource

<map domains="(map mapgroup-d)">
  <keydef keys="product-name">
    <topicmeta>
     <keywords>
       <keyword>Thing-O-Matic</keyword>
     </keywords>
    </topicmeta>
  </keydef>
</map>

This form of key definition would normally be used from a <keyword> element in order to use the value defined in the key definition:

<topic id="topicid">
  <title>About the <keyword keyref="product-name"/> product</title>
</topic>

Normal processing results in the effective title text "About the Thing-O-Matic product".

A key definition that uses both elements within the key definition and points to a resource

<map domains="(map mapgroup-d)">
  <keydef keys="yaw-restrictor"
    href="parts/subassem/subassm-9414-C.dita"
  >
    <topicmeta>
     <keywords>
       <keyword>yaw restrictor assembly</keyword>
     </keywords>
    </topicmeta>
  </keydef>
</map>

When referenced from a <keyword> element with no directly-specified content, normal processing sets the effective content of the keyword to "yaw restrictor assembly" and makes the keyword a navigation link to the topic subassm-9414-C.dita.

Redirect a link or xref

1. Author 1 creates a map that associates keys with each topic, for example <topicref keys="a" href="a1.dita"/>
2. Author 1 creates topic c.dita that contains a related link to a0.dita - but uses the keyref attribute: <link keyref="a" href="a0.dita"/>
3. Author 2 reuses c.dita, but wants to redirect the link, so applies a different map with <topicref keys="a" href="a2.dita"/>. The link in c.dita now resolves to a2.dita when author 2 builds it (it continues to resolve to a1.dita when author 1 builds it)
4. Author 3 also reuses c.dita, but wants the link to point to an external resource, so creates an external-pointing topicref to resolve the key:

   <topicref  keys="a" href="http://www.a..." scope="external">
     <topicmeta>
       <linktext>This links to A2</linktext>
       <shortdesc>Because it does.</shortdesc>
     </topicmeta>
   </topicref>

   The link in c.dita now resolves to an external URI reference when author 3 builds it (without affecting how it resolves for the other two reusers).

5. Author 4 wants to get rid of the link, so creates an explicitly empty topicref to get rid of it: <topicref keys="a"/>. This gets rid of the link for author 4 without affecting the other reusers.
6. Author 5 wants to turn the link into just plain text (not hypertext) - for example a citation of a print-only magazine article.

   <topicref  keys="a">
     <topicmeta>
       <linktext>This is just text.</linktext>
     </topicmeta>
   </topicref>

7. Author 6 reuses c.dita, but does not include a topicref that defines the key “a” in the map. Topic a0.dita is used as the “fallback” related link.

Redirect conref

1. Author 1 creates a map that associates a key with a topic that contains reusable elements, for example <topicref keys="reuse" href="prodA/reuse.dita"/>
2. Author 1 uses the key instead of the full href whenever creating conrefs - for example <p conkeyref="reuse/para1"/>
3. Author 2 wants to reuse author 1's content, but swap in a different set of reusable content. So Author 2 associates the key "reuse" with a different topic: <topicref keys="reuse" href="prodB/mytopic.dita"/>. So now <p conkeyref="reuse/para1"/> will resolve to a paragraph with the id “para1” in prodB/mytopic.dita when author 2 builds the content, while continuing to resolve to the para with the id “para1” in prodA/reuse.dita for author 1.

Create links from keywords, terms, or other elements

1. Author 1 creates a map that contains glossary entries, and associates keys for each entry: <topicref keys="myterm" href="myterm.dita"/>
2. Author 1 then uses the keys to create links to the appropriate glossary entry from occurrences of terms in content: <term keyref="myterm">my term</term>.

Swap out variable content

1. Author 1 creates a map for key words and phrases that tend to change, such as UI labels and product names. The topicrefs do not in this case contain any actual hrefs, just the text that should be used:

   <topicref keys="prodname">
     <topicmeta>
       <linktext>My Product</linktext>
     </topicmeta>
   </topicref>

2. Author 1 then uses the keys to draw text into empty keywords: <keyword keyref="prodname"/>
3. Author 2 reuses the content but wants to use a different product name, so associates prodname with a different string:

   <topicref keys="prodname">
     <topicmeta>
       <linktext>Another Product</linktext>
     </topicmeta>
   </topicref>

   The keyword now resolves to "Another Product" for author 2, while continuing to resolve to "My Product" for author 1.

Splitting or combining targets

1. Author 1 creates a map in which most branches have the same structure: intro, example, reference. Two branches have only very little content in them, because the product support is only minimal. In anticipation of future elaboration, author 1 assigns 4 keys to the container under which more topics are expected in the future:

   <topicref keys="blat-overview blat-intro blat-example blat-reference" 
             href="blat-overview.dita"/>

2. Author 2 references blat-example, and in the future when Author 1 moves blat-example into a separate topic, author 2's link remains appropriate and valid and does not need to be reworked.
3. Author 3 is reusing a bunch of author 1's content, but in a context where blats are not available, and are instead replaced by foobars. So author 3 simply adds the blat keys to their own foobar topicref:

   <topicref keys="blat-overview blat-intro blat-example blat-reference foobar" 
             href="foobar.dita"/>

Removing a link

1. Author 1 creates a map which defines the key "overview":

   <topicref keys="overview" 
             href="blat-overview.dita"/>

2. Author 1 adds a link to the topic productInfo.dita using they keyref attribute, and using the href as a fallback:

   <link keyref="overview" href="blat-overview.dita"/>

3. Author 2 wishes to reuse productInfo.dita, but does not want a link to overview information. So, author 2 creates a new definition for the key overview that does not have a target:

   <topicref keys="overview"/>

   The link element which uses keyref="overview" is now removed, because there is no target and no link text.