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.

INIOnly section

FlattenedConrefAttr - Specifies an attribute name to set on conref elements that have been flattened during the book-build process. By default this is disabled (set to an empty string), but if you set this to an attribute name such as “outputclass”, that attribute will be set with the value of “flattened-conref”. This can be useful if you want to apply formatting to content that was previously a conref (but has been flattened).

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

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

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.2\map-from-outline_template.fm” 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). (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, #. (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 “1” to revert to the pre 1.1.11 DITA-FMx method of requiring a placeholder file to generate a list. The default value “0” indicates that DITA-FMx will honor the “proper” syntax for frontmatter and backmatter list elements which does not require a placeholder file.

NewMapShortcuts and NewTopicShortcuts - Allows customization of the shortcut keys assigned to the New File menu items. The value for both of these is a space-delimited string of doctype/key pairs. Use the following syntax:

<doctype>:<key-sequence>

Where:

<doctype> is the root topic or map element.

<key-sequence> is the key sequence for the shortcut. To specify an ESC sequence the string starts with “\!” (backslash, exclamation). This is followed by 2 or 3 characters or numbers (case sensitive). (In theory you can also use ALT “~” or CTRL “^” or SHIFT “+”, but this may or may not work well. You can also “try” to use function keys, which are defined as slash followed by “F” and the number, as in “/F3”.)

For example, to create shortcuts for map, bookmap, topic, and task, you could use the following:

NewMapShortcuts=map:\!NMM bookmap:\!NMB 
NewTopicShortcuts=topic:\!NTO task:\!NTA

FilteringAttributes - Specifies the attributes that are considered when performing ditaval filtering. The default value is a space-delimited string of attribute names: audience product platform otherprops rev props.

UseDatatype - As of v.2.0.06, graphic overlay object type information is now stored in the data element’s name attribute. If you want to continue using the datatype attribute, set this parameter to “1”.

NavtitleLen - As of v.2.0.06, controls the length of the content in navtitle element when updated based on the referenced topic title text. This defaults to 250 characters (bytes), which should be more than sufficient, but for multibyte content, you may want to increase this value.

AutoXrefTextElems - As of v.2.0.07, specifies a space delimited list of elements to automatically add alt text to xrefs based on the target element type selected in the Reference Manager. If not set, no automatic alt text is added.

ReportRO - As of v.2.0.07, if set to “0”, disables the notification when opening a read-only file. If not set, this notification is enabled.

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 the “filtering groups” INI file which defines values for the specified “Strings” attributes. These 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 user’s DITA-FMx folder. 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.)

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

WriteDictionaryPIs - If set to 1, specifies that words flagged by the spelling checker as “Allow in Document” are written to the XML file as a processing instruction (PI) before the root topic node (<?dtall dict="allowed-word"?>). On file open these words are loaded in to the document dictionary for the current file. Note that these processing instructions are not likely to be honored by other tools. (Defaults to “1” if this parameter is missing or set to a null string.)

Note: Over time if you clone a topic file for other uses, these processing instructions may build up in the file. You can delete the items in the document dictionary for a given file by opening that file and choosing the Dictionaries button in the Spelling Checker dialog. In that dialog select the Document Dictionary option, choose Clear from the list, then choose OK.

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. (In DITA-FMx 1.1 the default was “0”, but now it is “1”.)

FmDpiUseOutputclass - If set to 1, specifies that the “fmdpi” value is assigned to the outputclass attribute rather than the otherprops attribute.

DITA-FMx 1.1 used the otherprops attribute, which was not the intended use for that attribute. Using the outputclass attribute is more in line with the DITA specification. This setting controls how this attribute is added to new elements, but does not affect existing elements. The sizing of images will work properly regardless of the attribute the “fmdpi:NN” value is assigned.

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

IndexOptions section

IndexMarkerType - Specifies the name of the index marker type. Useful for Japanese systems, which use a localized name for the index marker. (Defaults to “Index” if this parameter is missing or set to a null string.)

ExternalApplications section

EPUBReaderAppExe - Registers the path and filename of the AZARDI EPUB reader application to use if an EPUB file is specified in the DitaFMxGuide or DitaReference parameters. (This feature is considered experimental.)

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.) This parameter is ignored for OT 2.x or later.

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

For OT 2.x or later, specifies the bin\dita.bat file in the selected DITA-OT installation.

For OT 1.x, specifies the batch file to run before the Ant script in order to set up any needed environment variables.

DitaDir - Specifies the folder that contains the DITA-OT installation. 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.) This parameter is ignored for OT 2.x or later.

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