DITA map elements
Map and map group elements
A DITA map is composed of the following elements:
- map
- The <map> element is the root element of the DITA map.
- topicref
-
The <topicref> elements are the basic elements of a map. A <topicref> element can reference a DITA topic, a DITA map, or any non-DITA resource. A <topicref> element also can have a title, short description, and the same kind of prolog-level metadata that is available in topics.
The <topicref> elements can be nested to create a hierarchy, which can be used to define a table of contents (TOC) for print output, online navigation, and parent/child links. Hierarchies can be annotated using the @collection-type attribute to define a particular type of relationship, such as a set of choices, a sequence, or a family. These collection types can affect link generation, and they may be interpreted differently for different outputs.
- reltable
-
Relationship tables are defined with the <reltable> element. Relationship tables can be used to define relationships between DITA topics or between DITA topics and non-DITA resources. In a relationship table, the columns define common attributes, metadata, or information type (for example, task or troubleshooting) for the resources referenced in that column. The rows define relationships between the resources referenced in different cells of the same row.
The <relrow>, <relcell>, <relheader>, and <relcolspec> elements are used to define the components of the relationship table. Relationships defined in the relationship table also can be further refined by using the @collection-type attribute.
- topicgroup
- The <topicgroup> element defines a group or collection outside of a hierarchy or relationship table. It is a convenience element that is equivalent to a <topicref> element with no @href attribute or navigation title. Groups can be combined with hierarchies and relationship tables, for example, by including a <topicgroup> element within a set of siblings in a hierarchy or within a table cell. The <topicref> elements so grouped can then share inherited attributes and linking relationships with no effect on the navigation or table of contents.
- topicmeta
- Most map-level elements, including the map itself, can contain metadata inside the <topicmeta> element. Metadata typically is applied to the element and its descendants.
- topichead
- The <topichead> element provides a navigation title; it is an convenience element that is equivalent to a <topicref> element with a navigation title but no @href attribute.
- anchor
- The <anchor> element provides an integration point that another map can reference in order to insert its navigation into the current navigation tree. For those familiar with Eclipse help systems, this serves the same purpose as the <anchor> element in that system. It may not be supported for all output formats.
- navref
- The <navref> element represents a pointer to another map which should be preserved as a transcluding link rather than resolved. Output formats that support such linking will integrate the referenced resource when displaying the referencing map to an end user.
- keydef
- Enables authors to define keys. This element is a convenience element; it is a specialization of <topicref> that sets the default value of the @processing-role attribute to resource-only. Setting the @processing-role attribute to resource-only ensures that the resource referenced by the key definition is not directly included in the navigation that is defined by the map that includes the key definition.
- mapref
- Enables authors to reference an entire DITA map, including hierarchy and relationship tables. This element is a convenience element; it is a specialization of <topicref> that sets the default value of the @format attribute to ditamap. The <mapref> element represents a reference from a parent map to a subordinate map.
- topicset
- Enables authors to define a branch of navigation in a DITA map so that it can be referenced from another DITA map.
- topicsetref
- Enables authors to reference a navigation branch that is defined in another DITA map.
- anchorref
- Enables authors to define a map fragment that is pushed to the location defined by an anchor.
Example of a simple map with a relationship table
The following example contains the markup for a simple relationship table:
<map>
...
<reltable>
<relheader>
<relcolspec type="concept"/>
<relcolspec type="task"/>
<relcolspec type="reference"/>
</relheader>
<relrow>
<relcell>
<topicref href="A.dita"/>
</relcell>
<relcell>
<topicref href="B.dita"/>
</relcell>
<relcell>
<topicref href="C1.dita"/>
<topicref href="C2.dita"/>
</relcell>
</relrow>
</reltable>
</map>
A DITA-aware tool might represent the <reltable> graphically:
| type="concept" | type="task" | type="reference" |
|---|---|---|
| A | B |
C1 C2 |
When the output is generated, the topics contain the following linkage:
- A
- Links to B, C1, and C2
- B
- Links to A, C1, and C2
- C1, C2
- Links to A and B
Example of a simple map that defines keys
The following example illustrates how keys can be defined:
<map> <keydef keys="dita-tc" href="dita_technical_committee.dita"/> <keydef keys="dita-adoption" href="dita_adoption_technical_committee.dita"/> ... </map>
The map also could be tagged in either of the following ways:
- <topicref> element with @processing-role attribute set to "resource-only"
-
<map> <topicref keys="dita-tc" href="dita_technical_committee.dita" processing-role="resource-only"/> <topicref keys="dita-adoption" href="dita_adoption_technical_committee.dita" processing-role="resource-only"/> ... </map>
- <topicref> element with @toc, @linking, and @search attributes set to "no"
-
<map> <topicref keys="dita-tc" href="dita_technical_committee.dita" toc="no" linking="no" search="no"/> <topicref keys="dita-adoption" href="dita_adoption_technical_committee.dita" toc="no" linking="no" search="no"/> ... </map>
Example of a simple map that references another map
The following code sample illustrates how a DITA map can reference another DITA map:
<map> <title>DITA work at OASIS</title> <topicref href="oasis-dita-technical-committees.dita> <topicref href="dita_technical_committee.dita"/> <topicref href="dita_adoption_technical_committee.dita/> </topicref> <mapref href"oasis-processes.ditamap"/> ... </map>
The map also could be tagged in the following way:
<map> <title>DITA work at OASIS</title> <topicref href="oasis-dita-technical-committees.dita> <topicref href="dita_technical_committee.dita"/> <topicref href="dita_adoption_technical_committee.dita/> </topicref> <topicref href"oasis-processes.ditamap" format="ditamap/> ... </map>
With either of the above examples, during processing, the map is resolved in the following way:
<map> <title>DITA work at OASIS</title> <topicref href="oasis-dita-technical-committees.dita> <topicref href="dita_technical_committee.dita"/> <topicref href="dita_adoption_technical_committee.dita/> </topicref> <-- Contents of the oasis-processes.ditamap file --> <topicref href"oasis-processes.dita> ... </topicref> ... </map>
Example of maps that use the <anchor> element and the @anchorref attribute
In this example, an anchor is defined with an ID of "a1".
<map>
<title>MyComponent tasks</title>
<topicref navtitle="Start here" href="start.dita" toc="yes">
<navref mapref="othermap2.ditamap"/>
<navref mapref="othermap3.ditamap"/>
<anchor id="a1"/>
</topicref>
</map>
The id on <anchor> can be referenced by the anchorref attribute on another map's <map> element. For example, the map to be integrated at that spot would be defined as follows.
<map anchorref="a1"> <title>This map is pulled into the MyComponent task map</title> ... </map>
- Best practices for key definitions: Using a separate map, defining keys at beginning
of map, etc.?
- First key encountered is used?
- That <keydef> is equivalent to <topicref processing-role="resource-only"> or
setting @toc, @linking, and @search attributes to "no"?
Should the example include more information about why the keys are defined and how they would be resolved?