General information on creating maps and bookmaps, and how they work in FrameMaker.
The default Map structure application (DITA-FMx-Map-1.1) allows for creation and editing of both DITA map and bookmap files. When saved to disk, the resulting DITA map file is completely DITA-compliant, although within the FrameMaker authoring environment some additional elements are added to provide a more efficient authoring experience. These elements have an “fm-” prefix.
DITA maps are the fundamental mechanism provided by DITA for organizing topics into deliverables (PDFs, online Help, HTML, etc.). A separate map can be created for each deliverable type or a single map can be used for multiple deliverables. Maps organize the topics into a logical hierarchy using topic referencing elements (topicref for a “map” and chapter, appendix, topicref, and others for a “bookmap”). A topic referencing element can also reference other maps, allowing you to create multiple levels of nested maps as appropriate for your topic organization and workflow.
All DITA map files (both map and bookmap) must use the “.ditamap” file extension. This is a requirement enforced by the DITA Open Toolkit and is also required by DITA-FMx.
On the opening of a DITA map file, all topic referencing elements are updated to include a child fm-reflabel element that displays a label within a locked text range. This label is the target topic’s title (based on the value of the navtitle attribute), filename, or both. If the referenced file is not available, the label “FILE NOT FOUND” is displayed. When you double click the label, the referenced file opens for editing. These labels are formatted with a character style named “DITA-Topicref,” you can change the color and formatting of topic references by modifying the character style definition in the template file.
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 uni-directional 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 bi-directional.
The bookmap is a new type of a DITA map that was introduced with DITA 1.1. It allows you to create a hierarchy of topic references that resembles the structure of a printed book. The general order of elements in a bookmap is similar to that of the map, although in many cases the element names will be different. The title of a bookmap can be bookmap/title or bookmap/booktitle. The bookmap’s metadata is stored in the bookmeta element (very similar to the topicmeta of the map).
The most significant difference between the map and bookmap are the topic referencing elements. A bookmap provides many specialized topic referencing elements for book-specific purposes that group topicrefs into logical sections.
The first logical grouping is the frontmatter element. The frontmatter element can contain a number of topic referencing elements (including topicref) that specify topics that are part of a book’s frontmatter. A similar backmatter element can be added at the end of the book. One of the special elements in the frontmatter and backmatter is the booklists element.
The booklists element (a child of the frontmatter and backmatter elements) can contain one or more “list” elements that are intended to provide generated lists (similar to the FrameMaker generated list files like a “toc” or “index”). Using DITA-FMx, when you insert an element that is a child of booklists, you are not prompted for a target file name. Instead you are prompted for the folder that will contain a placeholder topic file that defines the location that the generated list file will be created. DITA-FMx creates a simple topic file in the specified folder using the file name frontmatter_<elemname>.<extension> or backmatter_<elemname>.<extension>. Where <elemname> is the name of the inserted “list” element and <extension> is “dita” or “xml” depending on what you’ve specified in the Options dialog as default file type. The name of the list element is used as the @navtitle value, and the element is inserted into the map. If you’d like to see a different label in the map, modify the @navtitle attribute value.
Following the frontmatter element can be a number of topic grouping elements such as part, chapter, and appendix. The part element can be used to organize chapter and appendix elements into parts, and the chapter and appendix elements are used to organize topicrefs. After the last part, chapter, or appendix can be the backmatter element, similar to the frontmatter element described above.
A bookmap can also make use of relationship tables in the same way they are used in a map. Note that even though your bookmap may make use of part, chapter, and appendix topic referencing elements, the reltable can only contain topicref elements.
When setting up a map or bookmap that will be used to define a book-like deliverable (either as a PDF or online format that breaks topics into sections or chapters), it is common to create a root map with submaps (or chapter-maps). The root map would, at a minimum, contain topicref (or chapter, appendix, etc.) elements that point to each submap (chapter). If your root map is a bookmap, it would also contain the frontmatter and backmatter along with the appropriate child elements. It might also contain a relationship table, but depending on your structure, you might want to maintain relationship tables in the submaps.
The submaps should be standard DITA maps (not a bookmap). If you are using the default DITA-FMx XSLT import script that is provided with the Book application, your chapter maps should contain a single root topicref element which defines the chapter title and any optional content that would appear before the first H1-level heading in the generated FM file. Any topicref elements that are children of the root topicref become the H1, H2, and so on, headings within the chapter.
If you want to be able to use the titles from the submaps as the chapter titles, you’ll need to modify the XSLT import script to pull that content from the map and insert it into the proper location in the output.
This method of creating chapter maps makes it very convenient to assign a “chapter” to a specific writer. Note that it is perfectly reasonable to take this nested map concept to further levels. You may have components within a chapter that make sense to group into a map. This is especially useful if you reuse these components in other maps or deliverables.
Although, in theory, you should be able to use any directory structure for your maps and topic files, the default DITA-FMx Book application’s XSLT import script (as of version 1.1.09) is set up to work best with a specific structure as described below.