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