INI-Only Settings

Describes the settings that must be applied manually in the ditafmx.ini file.

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