Basic Map Structure

Basic information on working with DITA map files.

The basic DITA map file uses the map element as the root node. The map element can be followed by a title element. After the title is an optional topicmeta element which contains various elements that define metadata for the map. This metadata may define copyright or other legal information regarding the publication, as well as keywords or online Help IDs. The type of metadata used in a map will generally be defined by the deliverable format and the method the output is generated.

The only topic referencing element in a map is topicref. A map can include the keydef element which is used to create key definitions (for use in key-based referencing).

Insert a topicref element and associate it with the target topic. To create a topic hierarchy, insert new topicref elements as children of a parent topicref. If you are creating a FrameMaker book from a map, keep in mind that the “top-level” topicrefs (those that are immediate children of the root element) will become chapter FM files. Any child topicrefs will be added to the chapter files as sub-topics.

One or more relationship tables can be added after the topicrefs. A relationship table defines relationships between topics, and is the preferred method for defining topic linking (over the use of inline cross-references). Relationship tables are defined by the reltable element (which is represented by a standard FrameMaker table), with topicref elements inside the table cells. You can create relationship tables with any number of columns, but typically they will use two or three columns.

The simplest and easiest to understand is the 2-column unidirectional reltable, where the topics (defined by topicrefs) in the left column will link to the topics in the right column. To create this type of relationship table, insert a reltable with two columns (the number of rows doesn’t matter, you can add more as needed). Then locate the first relcolspec element (this will control the first column’s specifications), and set the linking attribute to “sourceonly.” Locate the second relcolspec element and set the linking attribute to “targetonly.” The selected values will display in the table heading (along with the value of the relcolspec/@type attribute if provided). Insert topicref elements in the table cells to create related-links between the specified topics. If you create a relationship table without setting the relcolspec/@linking attributes, the resulting links will be bidirectional.