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>
ImportAttrsAsVars=(0|1)
ImportAttrsAsConds=(0|1)
UseOutputclassForType=(0|1)
PreBuildScript=<c:\projects\prebuild.bat %MAPNAME%>
PostBuildScript=<c:\projects\postbuild.bat %MAPNAME%>
AttrAsCondPrefix=<your_prefix>
[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=<ditaval 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)
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 New fm-ditabook Attributes. (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 New fm-ditabook Attributes. (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.
Four
parameters are not available through the Book Build Options dialog
and thus not found in the BookBuild section of the ditafmx.ini file. Those parameters
were added in DITA-FMx 1.1.11, and are described below.
- 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).
- 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).
- 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.
- 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. This parameter must be set manually in
a book-build INI file, and defaults to “0” (off).