<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.
<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".
<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.
<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.
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.
<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".
<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.
<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).
<topicref keys="a"> <topicmeta> <linktext>This is just text.</linktext> </topicmeta> </topicref>
The reusing author must create a parallel set of elements and IDs in the replacement topic; the element IDs within the topic are not remapped, only the pointer to the topic container.
<topicref keys="prodname"> <topicmeta> <linktext>My Product</linktext> </topicmeta> </topicref>
<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.
A processor should generate a warning message when a key reference on an empty element cannot be resolved, resulting in the element effectively being removed.
<topicref keys="blat-overview blat-intro blat-example blat-reference" href="blat-overview.dita"/>
<topicref keys="blat-overview blat-intro blat-example blat-reference foobar" href="foobar.dita"/>
<topicref keys="overview" href="blat-overview.dita"/>
<link keyref="overview" href="blat-overview.dita"/>
<topicref keys="overview"/>
The link element which uses keyref="overview" is now removed, because there is no target and no link text.