The Book Build Settings Dialog and the Book-Build INI File

Describes the methods available for generating a FM book from a DITA map.

The Book Build Settings dialog (DITA-FMx > Options) provides a number of options that control the processes that are run on the generated book file and components after the initial aggregation has taken place. If all of the options are deselected, you’ll end up with an unprocessed book file and FM files. This is typically not what’s needed (since any references will not be resolved, among other things), but if you have special processing needs, this may be a viable option.

The book-build INI file (ditafmx-bookbuild.ini) (ditafmx-bookbuild.ini) is a user-managed text file that defines the properties (pagination, numbering, and formatting) of each book component including the properties of generated list components (toc, index, etc.). This file also defines additional settings that control how book-level variables are used, as well as any pre and/or post build scripts. Settings defined in the Book Build Settings dialog may be overridden in the book-build INI file. This file is intended to allow the user to predefine all of the properties for each book-build, to ensure that subsequent builds result in the exact same output.

You would typically have one book-build INI file for each book that is created. The Generate Book from Map command looks for the book-build INI file in the folder selected for the book file to be created. If one does not exist in that location, it reads the settings defined in the user’s DITA-FMx folder (DITA-FMx > Open DITA-FMx Folder).

The first option in the Book Build Settings dialog is “Normalize Reference Paths.” This option processes all elements that contains an href or conref attribute and converts them into absolute paths based on the new relationship of content due to the file aggregation. If this option is selected, the “Add Related Links” and “Reload References” are also available. If “Add Related Links” is selected, any related links defined in reltable elements will be built and added to the bottom of each topic as appropriate. The “Reload References” option reloads and updates the references based on the updated reference locations.

Other options are described in detail in the Book Build Settings topic. Three of these options rely on properties that can be specified in a ditafmx-bookbuild.ini file. This INI file must be created manually and placed in either, the folder that contains the generated book file, or the user’s DITA-FMx folder (DITA-FMx > Open DITA-FMx Folder). This file is initially checked for in the book folder, if it does not exist there one will be used from the user’s DITA-FMx folder. This lets you maintain properties and templates that are specific to each book. The details of this INI file are provided in the Book-Build INI file topic.

The “Assign Numbering and Pagination” option enables the “NumberingFirst” and “NumberingDefault” sections of the ditafmx-bookbuild.ini file. This INI file can contain either or both of these “Numbering” sections for each mapelemtype attribute (each unique topic referencing element in the map file). Within each section are options that mirror the standard FrameMaker book numbering and pagination options. A simple bookmap that contains a “toc”, a few chapters, and an index (indexlist) would need the following four “Numbering” sections:

If only one element of any given map element type exists in the bookmap, you only need the NumberingFirst section for that element type, otherwise you should include both the NumberingFirst and NumberingDefault sections. These numbering options can be used for both DITA maps and bookmaps.

If enabled, the “Replace List Files with Generated Files” option will replace the placeholder files in the frontmatter and backmatter elements with FrameMaker generated lists. This uses the “GeneratedFile” sections in the ditafmx-bookbuild.ini file. You should create a GeneratedFile section for each of the unique list files. These sections specify the component type and the tags that are used for the generated list. Additionally the General section specifies the BookTemplatesDir option which specifies the folder that contains the template to use for each of the generated lists. The BookTemplatesDir location can be an absolute or relative path, if relative, it is relative to the book folder. For example, a book with a toc and index would specify two GeneratedFile sections:

The INI code would look something like the following:


The valid ComponentType values are specified in the Book-Build INI file topic. The generated list templates in the BookTemplatesDir folder must be named with the file naming convention of gentpl~<mapelemtype>.fm (that’s the string “gentpl” followed by a tilde, then the associated map element type name, with a “.fm” file extension). The “Replace List Files...” option is only valid with DITA bookmaps. (Sample templates are available in the DITA-FMx_1.2\Book\component-templates folder.)

The default XSLT import script makes the book title (from map/title, map/@title, bookmap/title, or bookmap/booktitle/mainbooktitle) available as a header/footer variable in files generated from DITA topic files. If you want to include the book title in generated list files, create a variable named “FMxBookTitle” and insert it into the appropriate location in your generated list template file. The variable will be updated when the generated lists are added to the book. If you’d like to use a different variable name, you can specify that name in the BookTitleVariableName parameter in the INIOnly section of the ditafmx.ini file.

The “Apply templates” option applies component templates to the other (non-list) files. It also uses the folder specified by the BookTemplatesDir option. The file naming convention for component templates is tpl~<mapelemtype>.fm. This option is also only applicable for DITA bookmaps. (Sample templates are available in the DITA-FMx_1.2\Book\component-templates folder.)

If you’d like to perform additional automated processing to the generated book and component files, you can use the “Run Custom Script” option to specify one or more FrameScript or FDK clients to run near the end of the book-build processing. These scripts run before pagination has been completed (conditional text has not been hidden and other processes that affect pagination are yet to be run). If you want to run a script after final pagination has been applied, use the RunPostPaginationScript settings in the ditafmx-bookbuild.ini file.

Variable values and condition states can be defined by values in the DITA map. These are controlled by attributes on the fm-ditabook element. For more information, see Adding Map to Book Metadata Mappings.

There are a number of other book-build settings that are controlled by the ditafmx-bookbuild.ini; please review the Book-Build INI file topic for more details.

A sample ditafmx-bookbuild.ini is provided in the DITA-FMx installation folder. This file is also provided in the file along with the working templates.

Using the outputclass attribute as a “mapelemtype” value

You can set the outputclass attribute on topicrefs or topicref-based elements in a map and that value will be assigned to the outputclass attribute on the associated fm-ditafile element. This mapping is used when the UseOutputclassForType parameter is set to 1 in the book-build INI file. When this feature is enabled, this value will be used instead of the fm-ditafile/@mapelemtype attribute that is set based on the type of the associated map element. For additional information see “UseOutputclassForType” in the Book-Build INI file topic.