Controls all aspects of generating FM files from a DITA map.
The ditafmx-bookbuild.ini file defines many of the parameters used to assemble the generated book to match your needs. The book build process first looks for this file in the directory that you have specified for the new book file, then it checks in the user’s DITA-FMx folder ().
If you always use the same settings, you can just keep one copy in the user’s DITA-FMx folder, but if you have book-specific settings, you may want to add this file to each output directory. This file follows the standard INI file format with section names in square brackets and key/value pairs following each section using a key=value syntax.
The book build process operates on individual book components based on the names of the map elements that are referencing the topic files (such as “part,” “chapter,” “toc,” “indexlist,” and so on). These element names are stored in the mapelemtype attributes on the fm-ditafile elements in the generated book. The ditafmx-bookbuild.ini file provides two general section types, one that defines the numbering and pagination properties for each element type and one that defines the creation of generated FM files that replace the “list” files in the frontmatter and backmatter elements. The basic syntax for this file is as follows:
[General] BookTemplatesDir=<path to templates folder> PreBuildScript=<c:\projects\prebuild.bat %MAPNAME%> PostBuildScript=<c:\projects\postbuild.bat %MAPNAME%> UseOutputclassForType=(0|1) ImportAttrsAsVars=(0|1) ImportAttrsAsConds=(0|1) AttrAsVarPrefix=<your_prefix> AttrAsCondPrefix=<your_prefix> AttrAsCondDefaultState=(Show|<Hide>) ShowBuildTimes=(0|1) [AltBookTemplatesDirs] Count=<N> 1=<some path> 2=<another path> <N>=<as needed> [ConditionMap] ;fmx-<attribute>-<value>=(Show|Hide) [NumberingFirst-<mapelemtype>] ... (same as below) [NumberingDefault-<mapelemtype>] VolumeProperty=(Restart|Continue|UseSame|FromFile) VolumeNumberValue=<value> VolumeNumberFormat=(Numeric|LCRoman|UCRoman|LCAlpha|UCAlpha|Text) ChapterProperty=(Restart|Continue|UseSame|FromFile) ChapterNumberValue=<value> ChapterNumberFormat=(Numeric|LCRoman|UCRoman|LCAlpha|UCAlpha|Text) PageProperty=(Restart|Continue|FromFile) PageNumberValue=<value> PageNumberFormat=(Numeric|LCRoman|UCRoman|LCAlpha|UCAlpha|Text) ParagraphProperty=(Restart|Continue|FromFile) FootnoteProperty=(Restart|StartOver|Continue|FromFile) FootnoteNumberValue=<value> FootnoteNumberFormat=(Numeric|LCRoman|UCRoman|LCAlpha|UCAlpha|Custom) FootnoteNumberCustom=<value> TableFootnoteProperty=(Format|FromFile) TableFootnoteNumberFormat=(Numeric|LCRoman|UCRoman|LCAlpha|UCAlpha|Custom) TableFootnoteNumberCustom=<value> PageStartSide=(FromFile|Next|Left|Right) PageDoubleSided=(1|0) PageRounding=(DeleteEmpty|MakeEven|MakeOdd|NoChange) [GeneratedFile-<mapelemtype>] ComponentType=(IndexAuthor|IndexFormats|IndexMarker|IndexReferences|IndexStandard|IndexSubject|ListFigure|ListFormat|ListMarker|ListMarkerAlpha|ListPara|ListParaAlpha|ListReferences|ListTable|Toc) NumTags=<N> 1=<paratag or markername> 2=<paratag or markername> <N>=<paratag or markername> [IncludeFiles] <position>=<filename> [IncludeFileTypes] <position>=<mapelemtype> [BookBuildOverrides] NormalizeRefs=(0|1) AddRelLinks=(0|1) RelLinkType=(0|1) ReloadRefs=(0|1) XrefToHyperlink=(0|1) ApplyDitaval=(0|1) DitavalName=<registered ditaval name or file name> MovePrologIndex=(0|1) MoveFigTitles=(0|1) MoveTableTitles=(0|1) AppendTableContVar=(0|1) FlattenConrefs=(0|1) AssignNumbers=(0|1) ReplaceListFiles=(0|1) ApplyTemplates=(0|1) RunScript=(0|1) ScriptName=<script names> ScriptArgs=<script arguments> HideConditionalizedContent=(0|1) UpdateBook=(0|1|2) ; The following parameters are not exposed in the UI, must be set in INI RunPostPaginationScript=(0|1) PostPaginationScriptName=<script names> PostPaginationScriptArgs=<script arguments> MoveFigId=(0|1) MoveTableId=(0|1) BreakToInline=(0|1) NormalizeConditions=(0|1) AssignMasterPagesFromMarkers=(0|1) RetagElements=<element list> FilterByAttribute=BUILD-EXPRESSION>CONDITION-NAME BuildImagemapHotspots=(0|1)
Each section and item are described below.
If set to 1, results in FrameMaker variables being created or updated in all book components (both structured and unstructured) where the variable name is “<prefix><attributename>” and the value of the variable is set to the attribute value. The default <prefix> value is “fmx-”, but can be changed or set to an emptying string with the AttrAsVarPrefix parameter, described below.
These variables can be used as header/footer variables or elsewhere in a document’s layout. If the variable exists in the template or predefined FM file, its value will be updated, otherwise the variable will be created. For more information see, Adding Map to Book Metadata Mappings.
If set to 1, results in the hide/show state of FrameMaker conditions being set in all book components (both structured and unstructured) where the condition name is “<prefix><attributename>-<attributevalue>”. The default <prefix> value is “fmx-”, but can be changed or set to an emptying string with the AttrAsCondPrefix parameter, described below.
Only conditions that exactly match the composite names are set. The hide/show state of the conditions is determined by the names in the ConditionMap section (described below). This feature works best for attributes that use enumerated values as the attribute value. For example, you may enable an fm-ditabook attribute named “permission”, and one of the possible values is “controlled”. You would create a condition named “fmx-permission-controlled” and tag the text “CONTROLLED” in the footer with this condition. The default state of this condition may be hidden, and if the attribute is set to “controlled”, the condition is toggled to show. For more information see, Adding Map to Book Metadata Mappings.
If set to 1, uses the value of the top-level topicref-based element’s outputclass attribute to specify the component template’s “mapelemtype” value. If no outputclass value is set, the element type will be used. This allows you to specify different component templates for files of the same map element type. If this option is enabled, you’ll need to include the corresponding NumberingFirst/NumberingDefault sections for that value. For example, if you set the outputclass of the first appendix element to “appxspecial”, you’ll need to include a section labeled “NumberingFirst-appxspecial”.
The AltBookTemplatesDirs section is used to define alternate component template folders available as overrides in the Generate Book from Map dialog. To use this feature, set the Count parameter to the number of alternate paths to display, then add sequential numeric entries for each path.
[AltBookTemplatesDirs] Count=2 1=C:/some/path 2=C:/another/path
You can add as many paths to this section as you’d like. They display as a list in the Generate Book from Map dialog. The “default” setting is defined by the path specified in the BookTemplatesDir parameter.
The ConditionMap section is used to assign a hide/show state to conditions that are set based on the value of fm-ditabook attributes. If the General/ImportAttrsAsConds parameter is set to 1, the values in the ConditionMap section are read.
Each entry in the ConditionMap section specifies the full composite condition name and the hide/show state to set that condition. To use the example described above (in the ImportAttrsAsConds description), the following ConditionMap section would be used to show the “CONTROLLED” label in a footer if the permissions attribute is set to “controlled”.
[ConditionMap] fmx-permission-controlled=Show
You can add as many conditions to this section as you’d like, each is used only if the attribute name and value match a defined entry. These conditions are updated in the FM book components only if the condition exists in that file.
Use the General/AttrAsCondPrefix parameter to specify a prefix other than “fmx-”.
A NumberingFirst-<mapelemtype> section applies to the first occurrence of this element in the map, and NumberingDefault-<mapelemtype> applies to any additional like-named elements in the map.
A GeneratedFile-<mapelemtype> section should be included for each generated file to be included in the book.
An IncludeFiles section is used to include FM binary (.fm) files in a generated book.
Entries in the IncludeFiles section specify the position and file name of the included file, where the file name is relative to the book file. The key specifies the position and the value specifies the file name. This section can contain multiple entries to add multiple files, just make sure that the “position” values are always unique, and the files are ordered from the lowest position to the highest.
An IncludeFileTypes section is optionally included (if the IncludeFiles section is used) to define the “mapelemtype” values that are associated with the files listed in the IncludeFiles section.
Entries in the IncludeFileTypes section assign the specified mapelemtype values to the files defined by the “position” as used in the IncludeFiles section. The key specifies the position, and the value is the mapelemtype string. You can use values that match those that are map element types in DITA (such as “chapter” or “appendix”) and you can create your own values (such as “titlepage”). Be sure to define the NumberingFirst and NumberingDefault sections as needed to assign numbering and pagination values to these mapelemtype values.
A BookBuildOverrides section is available to override default book-build settings defined in the Book Build Options dialog.
Most entries in the BookBuildOverrides section of the ditafmx-bookbuild.ini file mirror those found in the BookBuild section of the ditafmx.ini file. If you have questions about the values to be used, refer to the parameters and values in the BookBuild section of the ditafmx.ini file.
The following parameters are either not available through the Book Build Options dialog or have features that must be manually entered in the INI file. It’s likely that these options will be included in the UI in a future release.
This feature attempts to overcome an elusive FrameMaker formatting bug, this setting lets you specify a space-delimited list of element names that are “retagged” at the end of the book-build process. This seems to correct the formatting of paragraphs that contain multiple inline elements.
To enable this option, add a RetagElements entry to the BookBuildOverrides section. The value for this entry is a space-delimited list of elements to retag. This problem seems to occur most in li and note elements, but may happen elsewhere.
In some cases, the filtering provided by the Filter By Attribute command (FM10 and later) may be preferable to that currently provided by the DITA-FMx mapping of ditavals to conditions. To make use of this filtering option use the FilterByAttribute setting in the BookBuildOverrides section of the book-build INI file.
Set the value of the FilterByAttribute entry to ATTR-EXPRESSION>CONDITION-NAME. Where ATTR-EXPRESSION is the attribute build expression (must exist in the template), and CONDITION-NAME is the name of the condition to apply (also must exist in the template).
When the FilterByAttribute entry is enabled, ditaval filtering is not performed, even if specified.
For additional information, see “Filter by Attribute” in Filtering Content.
If you use imagemap elements to define linked regions in an image, enable the BuildImagemapHotspots parameter to have those linked regions automatically generated by the book-build process. Set this parameter to “1” to enable and “0” to disable (“0” is the default).
The imagemap element allows for multiple area elements, each of which defines a “hot” region. The area element contains a shape, coords, and xref elements. The shape element defines the shape of the region, currently only the “rect” (rectangle) shape is supported. The coords element defines the coordinates for the shape. Because only “rect” is supported, the coordinates value is “x1,y1,x2,y2” (upper left corner and lower right corner). The xref element defines the destination for the hot spot.
The coords values are assumed to be in pixels (at 72 DPI). In order to ensure alignment of the coordinates with those of the image itself, you must make use of the “fmdpi” feature (unless your image DPI is 72).