Book Build Settings

Specifies the automated processes to be run on a FrameMaker book that has been generated from a DITA map.

The Generate Book from Map command aggregates all of the topic files referenced by a DITA map (and submaps) into a FrameMaker book and chapter files. After the book has been assembled, a number of processes can be run on the book and book components to prepare it for publishing. The Book Build Settings dialog allows you to specify which of these processes are performed.

The settings in this dialog can be overridden by settings in the BookBuildOverrides section of a ditafmx-bookbuild.ini file (also known as a “book-build INI file”). This dialog should be used for testing of various options, but to ensure consistent book generation, you should set up a book-build INI file for each project.

Note: The term “chapter file” is used in a generic sense and does not imply chapter versus appendix or other book component type. It just means a “FM binary file”.
Figure 1. DITA-FMx Book Build Settings dialog box

The options in this dialog specify the processes that are run on the book and are shown in the order that they are run.

Normalize Reference Paths

Iterates over all chapter files and converts all href and conref attribute values into absolute paths.

Add Related Links

Adds appropriate links to related-links elements in each topic based on the reltable(s) in the DITA map. You can select the link type of “link” or “fm-link” (standard DITA links or FM-based cross-refs). If you use fm-links, the “RelatedLink” cross-reference format is used. This option is only available if the Normalize Reference Paths option has been selected.

Reload References

Iterates over all references in all chapters and updates/reloads them based on the rebuilt reference paths. This option is only available if the Normalize Reference Paths option has been selected.

Glossary Term Swapping

If enabled, instead of using the glossterm element as the content for a keyref to a glossary entry, the glossSurfaceForm element is used for the first instance of a term in a chapter, and the glossAlt elements are used for later instances.

Flatten Conrefs

Runs the Flatten Conrefs command. This is useful if you have conrefs that contain cross-refs (xrefs, links, fm-xrefs, or fm-links) since this will allow those cross-refs to become live hyperlinks.

Convert Xrefs/Links into Hyperlinks

Runs the Xref to Hyperlink command. This is only useful if you your files contains DITA xref or link elements. This only processes internal xrefs/links; if you need to make external xrefs into live links, you’ll need to enable the Add Hypertext Marker to External Xrefs option before converting the map to a book.

Move prolog/*/fm-indexterms to topic/title

Moves all of the fm-indexterm elements in the prolog to the end of the parent topic’s title element. If this option is not selected, any indexterm elements in the prolog will not be included in a generated index if the prolog is hidden.

Apply Ditaval

Runs the Apply Ditaval command on the generated book file. Select the As Conditions or By Deletion option. Select a registered ditaval file from the list. Use the Ditaval Manager to register a ditaval file with DITA-FMx.

Important: When using the As Conditions option, this feature uses the default settings as defined in the Apply Ditaval dialog box. In order to change the way the conditions are applied, you must run the Utilities > Apply Ditaval command manually before using this option.
Move fig/title to End of fig Element

Moves each title of a fig element to the end of the fig element. If a desc element follows the title, it (and any child elements) will be moved as well. Essentially moves the figure title so it follows the image. For this option to work properly, the Book application must have the title element valid at the end of a fig element’s general rule.

Move table/title to table/tgroup/title

Moves each title of a table element to the location in the FrameMaker object structure that allows it to work as a FM table title is supposed to (appear at the top of the table on new pages). In the FM object model, the tgroup element is actually the “table”, while the table element is just a container that wraps the table.

This option moves the DITA table title so that it works properly in the generated FrameMaker files. If you select the Append ‘Table Continuation’ variable option, the Table Continuation variable will be appended to the table title after it is moved to the new location. To modify the text or format of the Table Continuation variable, edit the topic template file. For this option to work properly, the Book application must have the fm-tabletitle element defined and valid as a child of the tgroup element.

Assign Numbering and Pagination

Sets up the book component’s numbering properties based on the settings in the ditafmx-bookbuild.ini file. DITA-FMx looks for this INI file in the directory that the book is built in, then in the user’s DITA-FMx folder (DITA-FMx > Open DITA-FMx Folder).

Sections named “NumberingFirst-<maptype>” and “NumberingDefault-<maptype>” define the numbering and pagination properties for the first and remainder files created from specific map elements (<maptype> refers to the element name of the top-level map element).

Replace List Files with Generated Files

Replaces any “list” files with the appropriate corresponding FrameMaker generated list. For example, the frontmatter/booklists/toc entry will be replaced with a generated TOC, and the backmatter/booklists/indexlist entry will be replaced with a generated index.

This replacement relies on settings in the ditafmx-bookbuild.ini file. DITA-FMx looks for this INI file in the directory that the book is built in, then in the user’s DITA-FMx folder (DITA-FMx > Open DITA-FMx Folder). In the General section of the ditafmx-bookbuild.ini file the BookTemplatesDir parameter indicates the directory that contains the template files used as the basis for generated book components. These files should be named gentpl~<maptype>.fm, where <maptype> is the name of the associated map element that should be replaced with a generated file. Other sections named “GeneratedFile-<maptype>” define the component type and other properties needed for this file replacement.

Apply Templates

Applies templates (for both formatting and element definitions) to each of the book components based on the settings in the ditafmx-bookbuild.ini file. DITA-FMx looks for this INI file in the directory that the book is built in, then in the user’s DITA-FMx folder (DITA-FMx > Open DITA-FMx Folder).

In the General section of the ditafmx-bookbuild.ini file the BookTemplatesDir parameter indicates the directory that contains the template files used for this process. These files should be named tpl~<maptype>.fm, where <maptype> is the name of the associated map element that should be updated with the specified template.

Run Custom Script

Runs a custom FDK client, FrameScript, or ExtendScript (FM10 and later only). Enter the client name, and any arguments that are to be passed to the client. If you’d like to pass the FDK ID of the book to the client, enter “%BOOKID%” in the Args field.

To run a FrameScript, enter “fsl” as the client name, and to run an ExtendScript (with FM10 and later) enter “ScriptingSupport” as the client name. For a FrameScript, the script name is the argument and for an ExtendScript provide the script file name as the argument.

You can run multiple clients by separating the client name and arguments with the vertical bar character. If you are specifying multiple clients, the first character in both the client list and the arguments list must be a vertical bar. Be sure that the number of vertical bars in the client list and argument list are the same to ensure that the arguments are passed to the proper client. If no arguments are needed for certain clients but are needed for others, you can enter a hyphen where no arguments are needed. For example, the following client and argument data will run three FDK clients:

Client:| client1 | client2 | client3

Args:| client1-arg %BOOKID% | client2-arg | client3-arg %BOOKID%

Note: This option runs scripts before “pagination” has been completed. Conditional text is still shown and other formatting processes are yet to be run that will affect pagination. If you need to run a script after pagination has been completed, use the RunPostPaginationScript book-build INI setting, described in Book-Build INI file.
Hide “Conditionalized” Content

Hides the elements that have been tagged through any of the four “Conditionalize” options in the Options dialog.

Update Book

Runs the Edit > Update Book command with all of the “update” options enabled except “Apply Master Pages”. If you’d like to apply master pages, select the Apply Master Pages option. The Apply Master Pages option assumes that your template (or component templates) provide a StructMasterPageMaps table.

Important: On FM versions prior to FM10, the Apply Master Pages option will result in a message box, warning you that all current master pages will be reapplied. This interrupts any automation, and pauses the build until you choose the “Yes” button. Also, on all FM versions if this option is enabled and no StructMasterPageMaps table exists in the template(s) in use, an alert message displays.