The Book Build Settings Dialog and the ditafmx-bookbuild.ini File

The Book Build Settings dialog (in 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 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 main FrameMaker\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 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:

• NumberingFirst-toc
• NumberingFirst-chapter
• NumberingDefault-chapter
• NumberingFirst-indexlist

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:

• GeneratedFile-toc
• GeneratedFile-indexlist

The INI code would look something like the following:

[GeneratedFile-toc] 
ComponentType=Toc 
NumTags=3 
1=title.0 
2=title.1 
3=title-index 
 
[GeneratedFile-indexlist] 
ComponentType=IndexStandard 
NumTags=1 
1=Index

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.1\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.1\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 at the end of the processing.

Variable values and condition states can be defined by values in the DITA map. These are controlled by fm-ditabook attribute values. For more information, see Adding New fm-ditabook Attributes.

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 DITA-FMx_Help_Source.zip file along with the working templates.