From 077d7c406334a0a3da418115e9d85b08447d97be Mon Sep 17 00:00:00 2001
From: aabeatty
Video: A DITA topic is the basic unit of authoring and reuse. In topic-based authoring, you create a number of individual topics, each of which
- each addresses a single idea or answers a single question. These topics can then be
- used and reused in any order, in a number of different documents. In DITA the topics
- are organized in maps, which are much like a table of contents; the map
- allows you to specify the order and the hierarchy of the topics.
To make your topics reusable:
Similar to the glossary entry topic, the glossary group topic must contain a - single <glossgroup> root element with an id attribute that contains one - <title> element and one or more <glossterm> or <glossgroup> elements, each - with an id attribute.
+Similar to the glossary entry topic, the glossary group topic must contain a single + <glossgroup> root element with an id attribute that contains one <title> + element and one or more <glossentry> or <glossgroup> elements, each with an id + attribute.
This lesson covers basic use of the glossary group elements. For the full
specifications for each element, see the
To make your writing more generalized:
<ul conref="domestic_duck_warehouse.dita#domestic_warehouse/nesting_materials"> <li/> -</ul>
This - conref pulls a <ul> element from a warehouse topic that contains reusable - elements relevant to domestic ducks.
If the topic containing this conref must - be reusable, a hard-coded filename will be a problem. To use the reusable topic in a - map that discusses wild ducks, the conref needs to point to a different warehouse - topic file (wild_duck_warehouse.dita).
Rather than hard code the path to a - file, you can use the conkeyref attribute to create a content reference that uses a - key, rather than a filename.
The first step in using a conkeyref is to create a DITA topic - (domestic_duck_warehouse.dita) that contains a reusable element (including an id +</ul>
This conref pulls a <ul> element from a warehouse topic that + contains reusable elements relevant to domestic ducks.
If the topic + containing this conref must be reusable, a hard-coded filename will be a problem. To + use the reusable topic in a map that discusses wild ducks, the conref needs to point + to a different warehouse topic file (wild_duck_warehouse.dita).
Rather than + hard code the path to a file, you can use the conkeyref attribute to create a + content reference that uses a key, rather than a filename.
The first step in + using a conkeyref is to create a DITA topic (domestic_duck_warehouse.dita) that + contains a reusable element (including an id attribute):
<ul id="nesting_materials"> <li>Sawdust</li> <li>Wood shavings</li> <li>Sand</li> ... -</ul>
In - a map that references the topic that will use the conkeyref, define a key for the - warehouse file: +</ul>
In a map that references the topic that will use the conkeyref, + define a key for the warehouse file:
<keydef keys="duck_warehouse" href="domestic_duck_warehouse.dita"/>
The example at the beginning of this topic shows a <ul> element with a conref. Replace the conref attribute with a conkeyref attribute that contains the key, a slash ('/'), and the id of the element to be pulled:
<ul conkeyref="duck_warehouse/nesting_materials"> <li/> -</ul>
When the topic containing the conkeyref is processed, - the key duck_warehouse is replaced with the current key definition, which is - domestic_duck_warehouse.dita.
You can reuse the topic containing the
- conkeyref in another DITA map, but you might need it to pull content from a file
- that is specific to the new map. To do this, add a <keydef> element to the new
- map that defines the key so that it points to a different file. In this example, the
- new map (that addresses wild ducks) defines the duck_warehouse key to point to
- wild_duck_warehouse.dita:
+</ul>
When the topic containing the + conkeyref is processed, the key duck_warehouse is replaced with the current key + definition, which is domestic_duck_warehouse.dita.
You can reuse the topic + containing the conkeyref in another DITA map, but you might need it to pull content + from a file that is specific to the new map. To do this, add a <keydef> element + to the new map that defines the key so that it points to a different file. In this + example, the new map (that addresses wild ducks) defines the duck_warehouse key to + point to wild_duck_warehouse.dita:
<keydef keys="duck_warehouse" href="wild_duck_warehouse.dita"/>
The file wild_duck_warehouse.dita defines a different <ul> element; however, it must - use the same id - attribute:
<ul id="nesting_materials"> + use the same id attribute:<ul id="nesting_materials"> <li>Ferns</li> <li>Twigs</li> <li>Grass</li> ... -</ul>When - this new key is used in the wile duck map, the unordered list of wild duck nesting - materials is used.
Finally, note that all the same rules that apply to conrefs - also apply to conkeyrefs:
When this new key is used in the wild duck map, the unordered list + of wild duck nesting materials is used.
Finally, note that all the same rules + that apply to conrefs also apply to conkeyrefs: