DITA-FMx User Guide

Basic Map Structure

Basic information on working with DITA map files.

The DITA map file uses the map element as the root node. This type of map was the only map type available in DITA 1.0. In DITA 1.0, the map title was defined by the map/@title attribute, but with DITA 1.1, the map element can now include a child title element instead of the title attribute. DITA-FMx will honor either type of map title.

Following the title is an optional topicmeta element which can contain 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. 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 map 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 group of 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), and topicref elements within 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 reltable, 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 reltable without setting the relcolspec/@linking attributes, the resulting links will be bidirectional.