The default values for these parameters should be sufficient
for most people, but there are reasons that you may want to change
the default behavior. The following settings must be changed manually
in the ditafmx.ini file.
- General section
MaxRefLevels -
Specifies the number of nested files that are opened due to the auto-loading
of references (xref or conref). If your files never have references
within references (such as an xref within a conref), then you should
set this to a value of “1”. If your files do make use of nested
references, set this value equal to the maximum number of reference
levels that exist. The greater the number the longer it may take to
open files since all references in all opened files will resolve
(unless limited by this option). Valid values are 0 through 9 or
“*” (asterisk means unlimited levels). Setting this value to 0 disables
the auto-updating of xrefs and conrefs. (Defaults to “2” if this parameter
is missing or set to a null string.)
This reference
resolving process is used when generating a book from a map, but
is not used while authoring unless the INIOnly/UseRefList parameter
is set to “0”.
- INIOnly section
UseRefList - Controls the way references
are resolved while authoring. If set to “1” (the default), references
(xrefs and conrefs) are resolved “on disk,” allowing for much faster
processing and less time required to open files. If set to “0” all
referenced files are opened in FrameMaker in order to resolve the
references. The number of files opened is determined by the reference
nesting level, which is controlled by the General/MaxRefLevels parameter.
(Defaults to “1” if this parameter is missing or set to a null string.)
ForceTablesWide -
If set to 1, tables are forced to fill the text column (or page
if the pgwide attribute is set to 1). This overcomes a limitation
where under certain circumstances tables are not rendered full width
in Book builds. If your EDD already handles “pgwide” tables, you
may need to disable this functionality by setting ForceTablesWide
to 0. (Defaults to “1” if this parameter is missing or set to a
null string.)
StructappsFile -
Specifies an alternate file to use as the structure application
definitions file. In order for this to function properly you must
also have set the Directories/StructureDir parameter in the maker.ini file.
(No default value, may be null.)
XrefElements -
A vertical-bar delimited list of element names that defines the elements
that are valid as xref or link targets. For example, setting XrefElements
to the following string limits the xref targets to the elements
specified:
- XrefElements=topic|concept|task|reference|section|dt
If
this parameter is not set, all elements are valid as xref or link
targets. (No default value, may be null.)
DitaFMxGuide -
Specifies the name of the DITA-FMx Help file (relative to the FrameMaker\DITA-FMx folder,
unless an absolute path is specified). This Help file may be a CHM
file or an EXE, or it may specify a URL (via the “http:” or “file:”
protocols). If an EXE is specified, this is likely an AIR Help file,
but may be any executable Help application set up to accept a command
line parameter that indicates the target HTML filename to display.
(Defaults to “ditafmx.chm” if this parameter is missing or set to a
null string.)
DitaHelpKeys -
Specifies the shortcut keystrokes to launch context-help for DITA authoring
(this runs the “DitaReference” Help file). The keys defined here
use the syntax for shortcuts as specified in the FDK Reference.
(Defaults to “~/F1”, Alt+F1, if this parameter is missing or set
to a null string.)
DitaReference -
Specifies the name of the DITA Reference Help file (relative to
the FrameMaker\DITA-FMx folder), which is used
for element-based context sensitive Help. This Help file may be
a CHM file or an EXE, or it may specify a URL (via the “http:” or
“file:” protocols). If an EXE is specified, this is likely an AIR
Help file, but may be any executable Help application set up to
accept a command line parameter that indicates the target HTML filename
to display. (Defaults to “ditafmx-ref.chm” if this parameter is
missing or set to a null string.)
Displaying the DITA Reference
Help uses a combination of this and two other parameters, DitaRefTargetType
and DitaRefTargetPath. If a DITA document is open and the insertion
point is within a DITA element, when the user presses Alt+F1 (as
defined by the DitaHelpKeys parameter), the following action is
issued:
<DitaReference> [<DitaRefTargetPath>]<element-tag><DitaRefTargetType>
If
the DitaReference parameter specifies a CHM or EXE file, the DitaRefTargetPath, selected
element tag name, and the DitaRefTargetType (file extension) values
are concatenated and passed to the Help system.
If the DitaReference
parameter specifies a URL, the DitaReference, DitaRefTargetPath,
selected element tag name, and the DitaRefTargetType (file extension)
values are concatenated and the resulting URL is passed to the default
web browser application.
DitaRefTargetType -
Specifies the file extension of target topics in the “DitaReference”
Help file for context sensitive Help. For additional information,
refer to the DitaReference parameter above. (Defaults to “.html”
if this parameter is missing or set to a null string.)
DitaRefTargetPath -
Specifies an optional “path” to target topics in the “DitaReference”
Help file for context sensitive Help. For additional information,
refer to the DitaReference parameter above. (No default value, may
be null.)
MapFromOutlineTemplate -
Specifies the “Map from Outline” template file used as the template
for the New ‘Map from Outline’ Template command.
(Defaults to “$STRUCTDIR\xml\DITA-FMx_1.1\map-from-outline_template.fm”
if this parameter is missing or set to a null string.)
BaselineOffset -
Specifies the distance (in points) an inline image is shifted below the
baseline of the surrounding text. (Defaults to “2” if this parameter
is missing or set to a null string.)
BookTitleVariableName - Specifies the
name of the variable that is updated with the book title (from map/title,
map/@title, bookmap/title, or bookmap/booktitle/mainbooktitle).
This variable is only updated in generated list files if it is included in
the generated list template (structured files can access the book
title via the attribute on the fm-ditabook element). (Defaults to
“FMxBookTitle” if this parameter is missing or set to a null string.)
StripClassAttribute -
Set this to “0” to prevent the @class attribute value from being deleted
when changing an element’s type (using the “Change” button in the
Element Catalog). (Added in DITA-FMx 1.1.09. Defaults to “1”, enabled,
if this parameter is missing or set to a null string.)
TplDelimChar -
Set this to specify the character to use as the file name delimiter
for new file templates (new~<topictype>~<template
name>.fm), book-build component templates (tpl~<mapelemtype>.fm), and generated
list templates (gentpl~<mapelemtype>.fm).
If necessary you can set this to a character, such as the hash symbol,
#. (Added in DITA-FMx 1.1.09. Defaults to “~” if this parameter
is missing or set to a null string.)
MaxOpenFiles -
Specifies the number of XML files opened before a warning is displayed.
This is convenience when working with FM7.2 and FM8 to allow time
to restart FrameMaker before it crashes. These versions of FrameMaker
have a bug that results in a crash after opening 300+ XML files
in the same session. (Defaults to “300” if this parameter is missing
or set to a null string.)
UseBooklistPlaceholder -
Set this to “0” to allow DITA-FMx to use the “proper” syntax for
frontmatter and backmatter “list” elements. According to the DITA
specification, to automatically generate a list a booklists “list”
element should not specify a topic via the @href attribute. Prior
to version 1.1.11 DITA-FMx required a placeholder file to generate
a list. (Added in DITA-FMx 1.1.11. Currently defaults to “1” if
this parameter is missing or set to a null string to maintain backwards
compatibility.)
RunaroundOff - Set this to “0” to disable
the DITA-FMx feature which turns Off the image Runaround property.
As of version 1.1.15 by default DITA-FMx will set the image Runaround
property to “None” which makes it possible to place callouts over images.
(Added in DITA-FMx 1.1.15. Defaults to “1” if this parameter is
missing or set to a null string.)
- INIOnly section (for use with
the Set Attributes command)
SetAttrIgnore -
Specifies the attributes to ignore (and not display) in the Set
Attributes dialog. This is a vertical bar delimited string. By default
this is set to the following values, you can change these values
or set this to a null string as needed.
xtrc|xtrf|xmlns|class|xmlns:ditaarch|ditaarch:DITAArchVersion|domains
SetAttrStrings -
Specifies an INI file that defines additional “default” values for
the indicated “Strings” attributes. These default values are organized
into named groups which can be associated with a specific file system
path. All topic files that fall within the specified root path are
mapped to that group. Each group lists one or more attributes and
a vertical bar delimited list of default values for that attribute.
This lets you provide alternate filtering options for different
projects that use the same structure application without modifying
the EDD. (Defaults to “FilterGroups.ini” if this parameter is missing
or set to a null string.)
Unless the value of the SetAttrStrings
parameter specifies an absolute path and file name, it is relative
to the “program files” or “app data” FrameMaker\DITA-FMx folder (depending
on the Windows version). If you use a SetAttrStrings file, no default values
need be set in the EDD at all. This adds flexibility to the EDD
not otherwise obtainable. For more information and details, see Set Attributes.
SetAttrStringsDefault - Specifies the
“default” value that is ignored when displaying the list of defaults.
Note: This
INI parameter is for very specialized and atypical use. Unless you
are doing special FDK processing using attributes of type “Strings”
you can safely ignore the following information.
When you
specify default values to a Strings attribute in the EDD, the first
default may be used as the actual default for certain types of processing.
If you want to specify a special value as the first default so that
your processing can match on it and ignore the value, enter that
string as the value for the SetAttrStringsDefault parameter. A likely
value is the dot (“.”) character, but you can specify any value
that makes sense for your processing. If you specify this value,
it will be ignored and excluded from the options displayed in the
Set Attribute dialog. (Defaults to “.” if this parameter is missing,
but this value may be set to a null string.)
If you do not
have processing that cares about the initial default value of a
Strings attribute, you can ignore this parameter.
- INIOnly section (for use with content management
systems)
CMSClientName -
Specifies the FDK client name used to connect with the CMS bridge or
connector. Typically set automatically by the CMS client. (No default
value, may be null.)
CMSImageDefaultDpi -
Specifies the default DPI for new images. Currently only used for
XDocs CMS. (Defaults to “72” if this parameter is missing or set
to a null string.)
- GeneralImport section
IndextermProcessing -
If set to 1, enables conversion of indexterm elements to proper
format required by FrameMaker. This parameter is set through the
user interface as the Indexterm to Fm-indexterm Conversion option
in the DITA-FMx Options dialog and should not be set manually without
care. (Defaults to “1” if this parameter is missing or set to a
null string.)
StripPadding -
If set to 1, strips leading space from the XML. This parameter is
set through the Normalize Whitespace on Import option
in the DITA-FMx Options dialog. (Defaults to “1” if this parameter
is missing or set to a null string.)
StripTrailing -
If set to 1, strips space characters from the XML that follow the opening
or closing block-level element tags. This only strips the spaces
when there are no other non-space characters in the node that follow
the open or close element. (Defaults to “1” if this parameter is
missing or set to a null string.)
TableProcessing -
If set to 1, enables the counting of table columns for proper import
of simpletable and other table types into FrameMaker. (Defaults
to “1” if this parameter is missing or set to a null string.)
UseLanguageTemplate -
If set to 1, enables the use of language-specific template files.
When opening a DITA XML file, if the “topic”/@xml:lang attribute
specifies a value, the plugin checks for a language template in
the same folder as the default template. The language template must
be named “<templatename>.<langval>.fm” (the “.fm” extension
is optional, but if the default template includes the extension,
the language template must also. For example, if your default template
is topic.template.fm, a Japanese language template
would be named topic.template.ja-jp.fm (assuming
that “ja-jp” was the value in the xml:lang attribute). (Defaults
to “0”, off, if this parameter is missing or set to a null string.)
As of version 1.1.11, if this parameter is enabled,
DITA-FMx will also look for a language-specific book-build INI file
when creating a book from a map (ditafmx-bookbuild.<langval>.ini).
This file will be located in the same places as the standard book-build
INI file. If a language-specific INI is not found, the default book-build
INI will be used (if available). For example, if the @xml:lang attribute
value is set to “ja-jp”, DITA-FMx will look for the file ditafmx-bookbuild.ja-jp.ini.
MissingImageDir -
Specifies the folder that the “missing image” files are stored.
This location is relative to the DITA-FMx folder in the Program
Files area, and defaults to “missing-images” if not specified. To
specify an alternate location, specify an absolute path to the folder
that contains these files. To disable this feature, set this parameter to
“0” (zero) or “Off”.
This feature is intended to eliminate
the XML parser log messages during a book-build that may incorrectly
report images as missing. This would often happen when generating
a book file into a folder structure that varies significantly from
that of the source folder structure. On import, the images would
in fact not be found, but the DITA-FMx “Reload References” book-build
option would resolve these references.
If enabled, during
the book-build process the images in the MissingImageDir folder will
temporarily replace the actual images to prevent the errant XML
parser log messages. This folder must contain a “break” and “inline”
image for each file type in use in your documents. These files are
named “missing-image-break.<EXT>” and “missing-image-inline.<EXT>”.
- GeneralExport section
IndextermProcessing -
If set to 1, enables conversion of indexterm elements from the format
required by FrameMaker back to one required by DITA. This parameter
is set through the user interface as the Indexterm to Fm-indexterm
Conversion option in the DITA-FMx Options dialog and should
not be set manually without care. (Defaults to “1” if this parameter
is missing or set to a null string.)
XrefProcessing -
If set to 1, enables processing and conversion of xrefs and links. (Defaults
to “1” if this parameter is missing or set to a null string.)
CrossRefToXref -
If set to 1, enables the conversion of FM-based cross-references to
DITA-based xrefs and links. (Defaults to “1” if this parameter is
missing or set to a null string.)
DitaXrefElem -
Defines the element name to use when mapping FM-based cross-refs to
DITA xrefs on file export (only used if GeneralExport/CrossRefToXref
is enabled). (Defaults to “xref” if this parameter is missing or
set to a null string.)
DitaLinkElem -
Defines the element name to use when mapping FM-based cross-refs to
DITA links on file export (only used if GeneralExport/CrossRefToXref
is enabled). (Defaults to “link” if this parameter is missing or
set to a null string.)
IgnoreElemPrefix -
If you use elements in FrameMaker that do not exist in the DITA DTDs,
you should make sure they all have the same prefix (“fm-” for example).
This INI setting specifies that prefix. This is required for proper
generation of conrefs on export, and should be used in conjunction
with any read/write rules that may be needed. (Defaults to “fm-”
if this parameter is missing or set to a null string.)
WriteLinkTextToFmXrefs -
If set to 1, specifies that the link text of fm-xrefs is written
to the xref element on file save. Normally, this link text is regenerated
based on the target element text, but if you want the FM-generated
text to be available for other processing engines, this should be
enabled. (Defaults to “0” if this parameter is missing or set to
a null string.)
WriteLineBreakPIs -
If set to 1, specifies that line breaks (Shift+Enter) are written to
the XML file as a processing instruction (PI). If DITA-FMx encounters
a PI of dtall break="line", it inserts a line break,
thus allowing proper round-tripping of line breaks between authoring
and publishing. Note that the line breaks will only be persevered
when publishing through FrameMaker (and DITA-FMx), and other tools
that honor this processing instruction. (Defaults to “1” if this
parameter is missing or set to a null string.)
FmXrefUseOutputclass -
If set to 1, specifies that fm-xref elements use the @outputclass
attribute rather than the @type attribute to store the cross-ref
format name. (Added in 1.1.15 and should be considered experimental.
Currently defaults to “0” if this parameter is missing or set to
a null string, but will default to “1” in DITA-FMx 2.0.)
- TableImport section
SetColumnsProp -
If set to 1, enables the automatic assignment of the “columns” property.
(Defaults to “1” if this parameter is missing or set to a null string.)
SetColumnWidthsProp -
If set to 1, enables the automatic assignment of the “column width”
property. (Defaults to “1” if this parameter is missing or set to
a null string.)
CustomTableCount and N -
Specifies the number of instances of simpletable elements that have
been specialized that need to be automatically analyzed for their column
number. The Count value should match the number of N values.
Each N value should have the following format: “<table-element>|<row-element>|<cell-element>”.
- BuildFile section
AntCommand -
Specifies the command or path/command used to run Ant. The default
is “ant”, but if you need to specify another executable or if you
need to include the path, change this value. This value is used
for both Generate Output options, Current File and Selected Target.
(Defaults to “ant” if this parameter is missing or set to a null
string.)
EnvironmentSetup -
Specifies a batch file to run before the Ant script in order to
set up any needed environment variables. This parameter can be set
through the DITA-FMx Options dialog in the External Application
Settings dialog. (No default value, must be set to use the Generate
Output command.)
DitaDir -
Specifies the folder that contains the DITA-OT files. This parameter
can be set through the DITA-FMx Options dialog in the External Application
Settings dialog. (No default value, must be set to use the Generate
Output command.)
EnvironmentSetup-<buildname> -
Specifies an alternate batch file to override the default specified
by EnvironmentSetup. Allows you to define builds that rely on different
DITA environments.
DitaDir-<buildname> -
Specifies an alternate location for the DITA-OT folder to override
the default specified by DitaDir. Allows you to define builds that
rely on different DITA environments.
AntScript -
Specifies the filename of the Ant script that is run for the Generate Output:
Current File option. The default is “ditafmx-ant.xml”, but if you
need to specify another filename, change this value. This filename
is assumed to be relative to the path specified by the DitaDir parameter.
(Defaults to “ditafmx-ant.xml” if this parameter is missing or set
to a null string.)
Count and N -
Specifies the number of build options available in the AntScript file (and
thus displayed in the Generate Output: Current File output option).
If you modify the targets in that script, be sure to update the Count value
and add/remove the related N value.
- AntBuild section
Count and N -
Specifies the number of “ANT:” sections which define the available build
options displayed in the Generate Output: Selected Target output
option. For each “ANT:” section added, you must update the Count value
and add/remove the related N value. The value of each N parameter
must exactly match the text following the “ANT:” section name.
- ANT:<buildname> section
BuildFile -
Specifies path and filename of the associated Ant script (use double
backslashes as the directory delimiter). (No default value, must
be set to use the Selected Target option of the Generate Output
command.)
EnvironmentSetup -
Specifies a batch file to run before the Ant script in order to
set up any needed environment variables.
Target -
Specifies target within the BuildFile. (No default value,
must be set to use the Selected Target option of the Generate Output
command.)
OutputDir -
Specifies the path to the output directory (use double backslashes
as the directory delimiter). (No default value, must be set to use
the Selected Target option of the Generate Output command.)
Logfile -
Specifies the path and filename to the log file (use double backslashes
as the directory delimiter). (No default value, must be set to use
the Selected Target option of the Generate Output command.)