DITA-FMx User Guide


Information specific to bookmaps in DITA-FMx.

The bookmap is a special 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 the top-level map 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.

Note: As of DITA-FMx 1.1.11, DITA-FMx supports the “proper” method for specifying the frontmatter and backmatter “lists.” The DITA specification states that to have a list generated from a booklists child element, you should insert the list element and leave the @href attribute empty. Earlier versions of DITA-FMx required a placeholder file, and thus the @href attribute was not empty. To enable this feature, set the ditafmx.ini INIOnly/UseBooklistPlaceholder parameter to “0” (in the next major release of DITA-FMx, this will default to “0” instead of “1”).

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.