Keys support reuse by defining a resource (topics, text strings, URIs, metadata) in different ways for different uses. One application is when a product is marketed under more than one brand or product name. Several versions of the documentation are the same except for the branding (company, product name). The unique resources for the various document versions can be defined in brand-specific definitions files. Different brand versions of the documentation can be created by referencing different definitions files from a high level DITA map.
In this short example about youth soccer referees, the league’s region name and region web site can vary among document versions. A version for West San Jose is implemented and the variable information is bolded. The example pages are coded in DITA and transformed to HTML.
In the reusable topics the region name is referenced by using a keyref attribute on the keyword element:
<keyword keyref="region_name"/>
In the reusable topics the region web site is referenced with a keyref attribute on the xref element:
<xref keyref="region_website" scope="external”> … </xref>
The keys are defined for the West San Jose region in a definitions file:
<!-- The region_name text is dynamic. -->
<keydef keys="region_name">
<topicmeta>
<keywords>
<keyword>West San Jose</keyword>
</keywords>
</topicmeta>
</keydef>
<!-- The region_website value is dynamic. -->
<keydef href="https://www.ayso64.org/Default.aspx?tabid=862611"
keys="region_website" scope="external"/>
The keys could be defined for another region in another definitions file. The definitions file that is referenced from the DITA map file determines which region’s name and web site is printed in the output.