DITA-FMx User Guide

Generate Book from Map

Generates a FrameMaker book and chapter files from the current DITA map.

This command builds a FrameMaker book by creating FM binary files from each top-level topic reference in a DITA map. Any topic references within a frontmatter or backmatter wrapper element are considered “top-level” topic references and become FM files. Additionally, if your bookmap uses a part element to organize chapters, the file referenced by the part will become a separate FM file, and each chapter will be considered a top-level topic reference and will be added to the book after the generated part file. After generating the book file, you are free to add any additional unstructured files that are needed (such as a title page).

If the current DITA map file has not been saved, you will be required to save it before processing can begin. This command first prompts for the name and location of the book file to create. It then assembles all FM binary files and resolves all references. The resulting FM files are named based on the root topic file’s relative path and filename with a “.fm” file extension.

Before running this command you should select the desired options in the Book Build Settings dialog (in the DITA Options dialog). These options allow you to select from numerous processing choices for setting up the files in the generated book. Some of the options in the Book Build Settings dialog require you to set up an INI file with numbering, pagination, and generated file information. You can set up this INI file for each book you are creating or use a common INI file used by all books.

Conrefs and xrefs that reference content within the book, are updated to point to the new FM files. Any references to DITA files that are not part of the final book, remain pointing at the source DITA file (with the href modified to suit the new path if it has changed). The paths to referenced graphics are updated to account for any changes due to relative differences between the source files and the new FM files. If your files do reference files that are not part of the book (typically graphics and possibly conrefs), it is important to choose an appropriate location to generate the book so that the FM files and referenced files can be easily moved as needed.

Note: It is not uncommon to get “XML Parser Messages” in the “XML Read Report Log” regarding IDs that have been “already used.” This happens if you’ve used a conref multiple times and that conref contains an ID that is of type “UniqueID.” Frame doesn’t like multiple instances of the same UniqueID in the same document. DITA doesn’t care since they are in different topics. If you get this message, just choose the “OK” button and proceed.

Maintaining a generated book

One possible way to build and maintain a custom book is described below. The use of a ditafmx-bookbuild.ini file and component templates should obviate the need to maintain a book in the way, but this method is offered as an alternative.

  1. Generate the book and FM files with the Generate Book from Map command. Think of this as a “throw-away” book, and name it something temporary like temp.book.

  2. Create a new book by doing a SaveAs from the throw-away book. This is your “real” book, give it an appropriate name.

  3. Add your TOC, Index, and other non-DITA-based files to the “real” book.

  4. Setup the properties for each file in the “real” book. Select each file and right-click, then choose Numbering, Pagination, or Set Up, as appropriate.

  5. Now choose Edit > Update Book to generate your TOC and Index.

  6. Save the “real” book.

Now, when you update your DITA files, re-run the Generate Book from Map command and overwrite the “throw-away” book and the FM content files will be replaced with fresh versions. Just close the “throw-away” book file that’s been generated, then open your “real” book and do an Edit > Update to refresh the TOC and Index and your book is ready to print.