Book-Build INI file

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 main DITA-FMx directory. If you always use the same settings, you can just keep one copy in the DITA-FMx directory, 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 and fm-subditamap 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) 
AttrAsCondPrefix=<your_prefix> 
AttrAsCondDefaultState=(Show|<Hide>) 
 
[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) 
RebuildVars=(0|1) 
XrefToHyperlink=(0|1) 
ApplyDitaval=(0|1) 
DitavalName=<registered ditaval name or file name> 
MovePrologIndex=(0|1) 
MoveFigTitles=(0|1) 
MoveFigId=(0|1) 
BreakToInline=(0|1) 
MoveTableTitles=(0|1) 
MoveTableId=(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) 
NormalizeConditions=(0|1) 
UpdateBook=(0|1|2) 

Each section and item are described below.

General Section

BookTemplatesDir
Specifies the directory that contains the layout templates (tpl~*.fm) and generated file templates (gentpl~*.fm) files. A relative path is relative to the INI file.
ImportAttrsAsVars
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 “fmx-<attributename>” and the value of the variable is set to the attribute value. 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. (Added in DITA-FMx 1.1.09.)
ImportAttrsAsConds
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 “fmx-<attributename>-<attributevalue>”. 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. (Added in DITA-FMx 1.1.09.)
UseOutputclassForType
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”. (Added in DITA-FMx 1.1.09.)
PreBuildScript
If provided, this parameter specifies the name of a batch file or executable script that will run before any book-build processing is begun (this is not used to run an FDK client or FrameScript). You can use this to copy or rename files that may vary under different conditions or perform other pre-build setup tasks. Two “variables” are available to provide information to the script. The string “%MAPNAME%” is replaced with the DITA map name (no path or file extension) and “%MAPFILE%” is replaced with the full path and file name of the DITA map. (Added in DITA-FMx 1.1.10.)
PostBuildScript
If provided, this parameter specifies the name of a batch file or executable script that will run after all book-build processing has completed (this is not used to run an FDK client or FrameScript). You can use this to copy or rename files that may vary under different conditions or perform other post-build tasks. Two “variables” are available to provide information to the script. The string “%MAPNAME%” is replaced with the DITA map name (no path or file extension) and “%MAPFILE%” is replaced with the full path and file name of the DITA map. (Added in DITA-FMx 1.1.10.)
AttrAsCondPrefix
If provided, this parameter specifies the prefix of conditions defined in the ConditionMap section. If not provided, the default value of “fmx-” is used as the prefix. (Added in DITA-FMx 1.1.11.)

ConditionMap Section

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-”.

Numbering(First|Default)-<mapelemtype> Sections

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.

VolumeProperty
Correlates to the options on the Volume tab of the Numbering Properties dialog. Valid values are: Restart, Continue, UseSame, and FromFile.
VolumeNumberValue
If Restart is specified for VolumeProperty, defines the number to use as the starting value (use numeric values only regardless of the number format).
VolumeNumberFormat
If Restart is specified for VolumeProperty, defines the format for that number and all subsequent numbers of this type that follow. Valid values are: Numeric, LCRoman, UCRoman, LCAlpha, UCAlpha, and Text.
ChapterProperty
Correlates to the options on the Chapter tab of the Numbering Properties dialog. Valid values are: Restart, Continue, UseSame, and FromFile.
ChapterNumberValue
If Restart is specified for ChapterProperty, defines the number to use as the starting value (use numeric values only regardless of the number format).
ChapterNumberFormat
If Restart is specified for ChapterProperty, defines the format for that number and all subsequent numbers of this type that follow. Valid values are: Numeric, LCRoman, UCRoman, LCAlpha, UCAlpha, and Text.
PageProperty
Correlates to the options on the Page tab of the Numbering Properties dialog. Valid values are: Restart, Continue, and FromFile.
PageNumberValue
If Restart is specified for PageProperty, defines the number to use as the starting value (use numeric values only regardless of the number format).
PageNumberFormat
If Restart is specified for PageProperty, defines the format for that number and all subsequent numbers of this type that follow. Valid values are: Numeric, LCRoman, UCRoman, LCAlpha, UCAlpha, and Text.
ParagraphProperty
Correlates to the options on the Paragraph tab of the Numbering Properties dialog. Valid values are: Restart, Continue, and FromFile.
FootnoteProperty
Correlates to the options on the Footnote tab of the Numbering Properties dialog. Valid values are: Restart, Continue, UseSame, and FromFile.
FootnoteNumberValue
If Restart is specified for FootnoteProperty, defines the number to use as the starting value (use numeric values only regardless of the number format).
FootnoteNumberFormat
If Restart is specified for FootnoteProperty, defines the format for that number and all subsequent numbers of this type that follow. Valid values are: Numeric, LCRoman, UCRoman, LCAlpha, UCAlpha, and Custom.
FootnoteNumberCustom
If Custom is specified in FootnoteNumberFormat, defines the custom value to use.
TableFootnoteProperty
Correlates to the options on the Table Footnote tab of the Numbering Properties dialog. Valid values are: Format and FromFile.
TableFootnoteNumberFormat
If Format is specified for TableFootnoteProperty, defines the format for that number and all subsequent numbers of this type that follow. Valid values are: Numeric, LCRoman, UCRoman, LCAlpha, UCAlpha, and Custom.
TableFootnoteNumberCustom
If Custom is specified in TableFootnoteNumberFormat, defines the custom value to use.
PageStartSide
Correlates to the 1st Page Side options in the Pagination dialog. Valid values are: FromFile, Next, Left, and Right.
PageDoubleSided
Correlates to the Pagination options in the Pagination dialog. Valid values are: 1 (double-sided) and 0 (single-sided).
PageRounding
Correlates to the Before Saving & Printing options in the Pagination dialog. Valid values are: DeleteEmpty, MakeEven, MakeOdd, and NoChange.

GeneratedFile-<mapelemtype> Section

A GeneratedFile-<mapelemtype> section should be included for each generated file to be included in the book.

ComponentType
Specifies the type of generated file to create for this map element. Valid values are:
  • Toc - Table of contents
  • ListFigure - List of figures
  • ListTable - List of tables
  • ListPara - Elements and paragraphs
  • ListParaAlpha - Elements and paragraphs (alphabetical)
  • ListMarker - List of markers
  • ListMarkerAlpha - List of markers (alphabetical)
  • ListReferences - List of references
  • ListFormat - List of formats
  • IndexStandard - Standard index
  • IndexAuthor - Index of authors
  • IndexSubject - Index of subjects
  • IndexMarker - Index of markers
  • IndexReferences - Index of references
  • IndexFormats - Index of formats
NumTags
Specifies the number of “tags” (paragraph style names or marker types) to be included in this generated file. For each tag provide a numbered entry starting with 1 and extending to the value specified in NumTags.

IncludeFiles Section

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.

IncludeFileTypes Section

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.

BookBuildOverrides Section

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.

DitavalName
As of DITA-FMx 1.1.14, the value of the DitavalName parameter can be either a registered ditaval name or the path and file name of a ditaval file. If you use the file name option, be sure that this value includes at least one slash. If the ditaval file is in the book output folder, use “./” as the prefix for the file name. Any value that has no slash will be assumed to be a registered ditaval name.
UpdateBook
Updated in DITA-FMx 1.1.15 to support the value “2” (previously just “0” and “1”). If set to “2”, when the book update is performed, the “Apply Master Pages” option is enabled.
MoveFigId
If set to “1”, specifies that the @id attribute values are moved to the respective “title” elements when the “Move fig/title” option is enabled. For figures, the @id attribute value is moved to the fm-figuretitle element (if one exists in the EDD). This is required to support fm-xref references to figure titles. If you do not want these @id values to be moved, set this parameter to “0” (it is set to “1” by default). Added in DITA-FMx 1.1.11.
MoveTableId
If set to “1”, specifies that the @id attribute values are moved to the respective “title” elements when the “Move table/title” option is enabled. For tables, the @id attribute value is moved to the fm-tabletitle element. This is required to support fm-xref references to table titles. If you do not want these @id values to be moved, set this parameter to “0” (it is set to “1” by default). Added in DITA-FMx 1.1.11.
BreakToInline
If set to “1”, supports the indenting of images in indented content blocks. This parameter must be set manually in a book-build INI file, and defaults to “0” (off). For more information, see Support for Indented Images. Added in DITA-FMx 1.1.11.
NormalizeConditions
If set to “1”, runs a “normalization” process on the condition formats in all book components (including generated lists and any included binary files). This process ensures that the condition settings in all files are the same. The properties of all like-named conditions will be set to the properties of the first instance of that condition in the book. This parameter must be set manually in a book-build INI file, and defaults to “0” (off). Added in DITA-FMx 1.1.11.
AssignMasterPagesFromMarkers
If set to “1”, enables the “Assign master pages from markers” feature. The text of the first fmx-masterpage marker found on a page defines the master page that is applied to that page. This provides an alternative to the StructMasterPageMaps feature in FrameMaker. For additonal information, see Custom Master Pages. Added in DITA-FMx 1.1.15.