Editing the fm2dita.ini File

The fm2dita.ini file defines the configuration settings for all of the FM2DITA commands.

The fm2dita.ini file controls many of the default settings for the FM2DITA processing. A default version of this file should be created in one of the following locations:

To locate this folder, use the Pubs-Tools > Open Pubs-Tools Folder command.

If this file exists in the same folder as the FM file or book being processed, that INI file will be used instead of the default file. This allows you to maintain separate INI files for each project.

[General]

MainFlow

Overrides the default flow-detection and processes the specified flow. In most cases this should not be specified, but if you want to process a flow that’s not recognized as the main flow, try setting it here.

Default: (nothing)

Used by: most commands

AssignIdElems

Space-delimited list of elements (element names) to assign IDs. If empty, IDs are assigned based on element definitions in the EDD where the @id attribute is identified as required.

Default: (nothing)

Used by: Assign IDs to Topics, Fix Cross-refs

TopicElems

Space-delimited list of “topic” elements. Leave empty to check the EDD for element definitions where the @class attribute contains “topic/topic”.

Default: (nothing)

Used by: Assign IDs to Topics, Fix Cross-refs

AttributeDisplay

Specifies the attribute display setting applied by the Import Template and EDD command.

Valid values: None, ReqSpec, All

Default: ReqSpec

Used by: Import Template and EDD

IdPrefix

String prefix for auto-generated IDs.

Default: id

Used by: Assign IDs to Topics

IdType

Specifies the type of auto-generated IDs. Available types are GUID (globally unique ID) or QUID (quasi-unique ID, shorter FM-based values).

Valid values: GUID, QUID

Default: GUID

Used by: Assign IDs to Topics

TopicNameTpl

Template string for generated topic file names. Should include building blocks as well as the required file name extension (typically “.xml” or “.dita”). Do not specify a path. For building block details, see Topic and Map Template Building Blocks.

Default: <$FM_CHAPNUM[L]>-<$TITLE_NOSPACECAMELLOW>.xml

Used by: Fix Cross-refs, Check for Topic Collisions, Write Chapter Map, Write XML Topics, Write Root Map, Write Root and Chapter Maps, Write Single Map

MapNameTpl

Template string for generated chapter map file names. Should include building blocks as well as the required file name extension (typically “.ditamap”). Do not specify a path. For building block details, see Topic and Map Template Building Blocks.

Default: <$FM_CHAPNUM[L]>-<$TITLE_NOSPACECAMELLOW>.ditamap

Used by: Write Chapter Map, Write Root and Chapter Maps

RootMapNameTpl

Template string for generated root ditamap file name. Should include building blocks as well as the required file name extension (typically “.ditamap”). Do not specify a path. For building block details, see Topic and Map Template Building Blocks.

Default: _!<$FM_FILENAME[L]>.ditamap

Used by: Write Root and Chapter Maps

RootMapIsBookmap

Controls the type of root map created. If set to “1”, a bookmap will be written for the root map, otherwise a “regular” map is written.

Default: 0

Used by: Write Root Map, Write Root and Chapter Maps

DeleteRelLinks

Specifies if related-links are deleted while writing XML topics. Valid values are 0 (don’t delete) or 1 (delete)

Default: 1

Used by: Write XML Topics

FmXrefAttr

The xref element’s attribute to which the FM cross-ref format is assigned (for fm-xref usage). Typical values are “type” or “outputclass”. If set to nothing, the format name is not assigned to the xref element.

Default: (nothing)

Used by: Fix Cross-refs

FlattenXrefs

if set to “1”, tells the Fix Cross-refs command to perform the “flatten cross-ref” command as well. This is used to revert the functionality back to the original single command.

Default: 0

Used by: Fix Cross-refs

TopicAppName

Topic application name as registered in the structure application definition file.

Default: FM2DITA-Topic-1.1

Used by: Variables to Conrefs, Write XML Topics

DefaultCondToAttr

Filtering attribute name to use for conditions not mapped in the CondToAttrMap section of the INI file.

Default: product

Used by: Condition to Attribute

CheckParentCond

Specifies whether to apply a filtering attribute if set on element’s parent. Valid values are 0 (don’t check parent) or 1 (check parent).

Default: 0

Used by: Condition to Attribute

StopWords

Space-delimited list of words to exclude from topic titles when generating file names as well as strings for the $TITLE* building blocks. This can also specify a file name (plain text) which contains the list of stop words (one word per line). The file name can be an absolute path, or relative (if it starts with “./” or “../”). If relative, it is relative to the INI file. If this parameter is commented out or set to no value, no stop words will be stripped.

Default: (nothing)

Used by: Fix Cross-refs, Check for Topic Collisions, Write Chapter Map, Write XML Topics, Write Root Map, Write Root and Chapter Maps, Write Single Map

PunctuationChar

Specifies the character used to replace punctuation when strings are returned by the $TITLE* building blocks. If not present or set to an empty string (nothing), this punctuation is stripped from the return string.

Default: (nothing)

Used by: Fix Cross-refs, Check for Topic Collisions, Write Chapter Map, Write XML Topics, Write Root Map, Write Root and Chapter Maps, Write Single Map

ConrefLibrary

File name for conref library. Do not specify a path or use building blocks.

Default: shared.xml

Used by: Variables to Conrefs

TabToSpaces

Number of spaces to replace for each tab character.

Default: 4

Used by: Tab to Spaces

DeleteAttrs

Space-delimited list of attributes to delete. If empty (default), you’ll be prompted for values.

Default: (nothing)

Used by: Delete Invalid Attributes

DeleteMarkers

Space-delimited list of unstructured markers to delete. If empty (default), you’ll be prompted for values.

Default: (nothing)

Used by: Delete Unstructured Markers

UnwrapElems

Space-delimited list of elements to unwrap. If empty (default), you’ll be prompted for values. This value can be the element name or an element/attribute specification (like b/@outputclass=’unwrapme’).

Default: (nothing)

Used by: Unwrap Elements

DeleteElems

Space-delimited list of elements to delete. If empty (default), you’ll be prompted for values. This value can be the element name or an element/attribute specification (like b/@outputclass=’deleteme’).

Default: (nothing)

Used by: Delete Elements

MergeElems

Space-delimited list of elements to merge. If empty (default), you’ll be prompted for values.

Default: (nothing)

Used by: Merge Code Lines

DeleteEmpty

Space-delimited list of elements to delete. If empty (default), you’ll be prompted for values.

Default: (nothing)

Used by: Delete Empty Elements

MoveTblOutputclass

If set to “1”, specifies that the outputclass value is moved from the tgroup element to the parent table element.

Default: 0 (outputclass is not moved)

Used by: Fix Tables

SaveTableWidth

If set to “1”, saves the relative table width (as a percentage) to the parent table element’s pgwide attribute. The percentage is rounded to the nearest higher 5.

Default: 0 (don’t save table width)

Used by: Fix Tables

SaveTableShading

If set to “1”, adds a value to the cell element’s outputclass attribute based on the shading applied to the cell. This value includes the color name and the fill pattern number (a value from 0-15). For example, if the color is blue and the fill is a dotted pattern, the value may be “fill-blue-4”.

Default: 0 (don’t save table shading)

Used by: Fix Tables

TableFmtPrefixChopChar

Specifies the character to use to determine the prefix to remove from table formats applied to each table. For example, if your table format is “con-FormatA”, but you want it to be just “FormatA”, specify the “-” character in this parameter.

Default: (nothing)

Used by: Fix Tables

UnwrapTables

A space-delimited list of table formats to unwrap (convert to text). If empty (default), you’ll be prompted for values.

Default: (nothing)

Used by: Tables to Text

UnwrapTablesPrefix

A space-delimited list of prefixes to apply to the paragraphs that result from the unwrapping of tables.

Alternatively, a complex mapping option is available that allows column-based and/or tag based assignment of the new tag names. See Complex mapping option for details.

Default: (nothing)

Used by: Tables to Text

IncludeMetadataInMaps

If set to “1”, includes topicmeta/critdates/created/@date=’YYYY-MM-DD’ in generated maps, otherwise no metadata is included.

Default: 1 (include metadata)

Used by: Related Links to Reltable, Write Root Map, Write Root and Chapter Maps, Write Single Map, Write Chapter Map

FmDpiVal

If set to a value greater than “0” sets @outputclass='fmdpi:VAL' when processing images, otherwise sets the @height and @width values based on the actual image size.

Default: 0

Used by: Fix Images

[TopicHeadings]

Delim

Delimiter character used in H<n> lists.

Default: (space)

Used by:Topic Report

H0, H1, H2, H3, H4

“Delim”-delimited lists of paragraph tags used as topic headings in the unstructured FM files. The H0 parameter is the “chapter title”, and H1, H2, H3, H4 parameters are the headings within that chapter. Assign the heading styles to these parameters for each that is to become a topic. Note that this setup is not used to actually perform the writing of XML topics, only for the Topic Report heading count and analysis.

Default: (none)

Used by:Topic Report

[AltTableTypes]

Count

Specifies the number of alternate table type entries defined in this section.

Valid values: Integer value

Default: 3 (uses internal definitions for simpletable, choicetable, and properties tables if this parameter is not defined)

Used by: Fix Tables

<N>

Each sequential numeric entry (starting with “1”) defines the structure of a table that will replace the default structure (thead, tbody, row, entry). This entry defines the table type, followed by the “>” character followed by a space-delimited table structure definition. The format for this entry is as follows:

tableType > theadReplacement theadRow theadCell(s) tbodyReplacement tbodyRow tbodyCell(s)

Where

  • tableType is the name of the alternate table (like “simpletable”). This is followed by the “>” character which separates it from the table structure definition.
  • theadReplacement is the name of the table head container (like “fm-simpletablehead”)
  • theadRow is the name of the row element(s) in the table head (like “sthead”)
  • theadCell(s) is the name of the cell element(s) in the table head (like “stentry”). This can specify a group of sequential cell elements, by using the following syntax: (cell1Elem,cell2Elem,...). No spaces are allowed in this group syntax.
  • tbodyReplacement is the name of the table body container (like “fm-simpletablebody”)
  • tbodyRow is the name of the row element(s) in the table body (like “strow”)
  • tbodyCell(s) is the name of the cell element(s) in the table body (like “stentry”). This can specify a group of sequential cell elements, by using the following syntax: (cell1Elem,cell2Elem,...). No spaces are allowed in this group syntax.

Default: (none, unless Count is not specified)

Used by: Fix Tables

[MoveMarkers]

NumMarkerTypes

Number of marker types being moved. If more than 1, each marker-move specification is defined in a new INI section named MoveMarkers-N. This parameter is not recognized in MoveMarker-N sections.

Default: 1

Used by: Move Markers

MarkerType

Name of marker type to move.

Default: Index

Used by: Move Markers

PrologElemPath

XPath-like specification of the placement of the marker (or content) if moved to the prolog. Specifies the path within the prolog element. If the last node specifies an element name and that element is the same as the element being moved, it will be moved to that location. If the element name differs from that being moved, then the text of the marker is copied to the specified element name.

If the last node is an attribute (as in “resource/@id”), the text of the marker is copied into that attribute value. To add a static attribute value, append a vertical bar followed by @attr=value (as in “|@name=TopicAlias”).

Default: metadata/keywords/fm-indexterm

Used by: Move Markers

ParaTags

Space-delimited list of paragraph elements that are allowed to contains these markers.

Default: p li entry

Used by: Move Markers

MoveTopicTitleMarkersTo

Specifies the destination for markers found in topic titles. If “Prolog,” markers are moved into the current topic’s prolog (created if it doesn’t exist). If “FirstPara,” markers are moved to the first paragraph (matching a “ParaTags” entry) that follows the title. Note that this setting only applies to topic titles; other titles use the setting from the MoveParaMarkersTo parameter with the exception of BeginPara or EndPara using the next “ParaTags” element.

Valid values: Prolog, FirstPara

Default: Prolog

Used by: Move Markers

MoveParaMarkersTo

Specifies the destination for markers found in paragraphs (basically, anywhere other than a title). If “Prolog,” markers are moved into the current topic’s prolog (created if it doesn’t exist). If “BeginPara,” markers are moved to the beginning of the current paragraph, or if “EndPara,” markers are moved to the end of the current paragraph.

Valid values: Prolog, BeginPara, EndPara

Default: BeginPara

Used by: Move Markers

[MoveMarkers-N]

Sections that contain parameters matching those in the MoveMarkers section (described above). if the MoveMarkers/NumMarkerTypes parameter is greater than 1, there should be one MoveMarker-N section for each marker type being moved (starting with MoveMarkers-1 up to the value specified in the NumMarkerTypes parameter).

[CondToCharTag]

<condname>

Specifies the character tag to which the condition (<condname>) is assigned. Entering pairs of <condname>=<chartag> entries in this section defines the mapping that is performed by the Condition to Char Tag command.

Used by:Condition to Char Tag

[RenameCondMap]

<oldname>

Specifies the new condition name. Entering pairs of <oldname>=<newname> entries in this section defines the mapping that is performed by the Rename Conditions command. If no mapping is defined in this section, the Rename Conditions command does nothing.

Used by:Rename Conditions

[CondToAttrMap]

<condname>

Specifies the filtering attribute to which the condition (<condname>) is assigned. Entering pairs of <condname>=<attrname> entries in this section defines the mapping that is performed by the Condition to Attribute command. If no mapping is defined in this section, the conditions are assigned to the attribute specified in the General/DefaultCondToAttr parameter.

Used by:Condition to Attribute

[ImagePathMap]

<origpath>

Specifies the new path to which the original path (<origpath>) is mapped. Entering pairs of <origpath>=<newpath> entries in this section defines the mapping that is performed by the Fix Images command. If no mapping is defined, the images remain referenced at the original location. The paths specified in this section must be the full path to the image file name; partial paths are not mapped. Each of the values for <origpath> and <newpath> must not be greater than 120 characters.

Used by:Fix Images

[TagCleanup]

UseTagsFromFile

Specifies where to get the list of character tags. If set to “1” the tags are read from the current file, if set to “0” the list of tags is read from the TagCleanup section (see Count and <N> below).

Valid values: Integer value (0 or 1)

Default: 1

Used by:Tag Cleanup

NewCharColor

Specifies the color applied to newly created character tags.

Valid values: String value of a valid color name

Default: Red

Used by:Tag Cleanup

Count

Specifies the number of character tag entries in this section.

Valid values: Integer value

Default: 0

Used by:Tag Cleanup

<N>

Character tag entries. One entry per tag, using sequential numeric key values starting with “1”.

Default: (none)

Used by:Tag Cleanup

[RetagParas-N]

NumPasses

Specifies the number of iterations or passes performed by the Retag Paras command. For values greater than 1, a new RetagParas-N section must be added.“NumPasses” is only valid in the initial RetagParas section.

Valid values: Integer value of 1 or more

Default: 1

Used by:Retag Paras

Delim

Specifies the character that separates the tag and prefix. The only reason to change this from the default is if your paragraph tags contain the “>” character This value should be a character that does not occur in your paragraph tag names. “Delim” is only valid in the initial RetagParas section.

Valid values: Any single character

Default: >

Used by:Retag Paras

Count

Specifies the number of tag/prefix entries in this section. If you are using multiple passes (NumPasses > 1), you must provide the Count parameter in each section.

Valid values: Integer value

Default: 0

Used by:Retag Paras

<N>

Tag/prefix entries.

Valid values: Tag and optional prefix name separated by the Delim character. One item per tag/prefix entry, using sequential numeric key values starting with “1”.

Default: (none)

Used by:Retag Paras

[RetagTablesInParas]

AddPostion

Specifies that the TblFmtStr values are added as a prefix or suffix to the current table format name.

Valid values: “Prefix” or “Suffix”

Default: Prefix

Used by:Retag Tables in Paras

Delim

Specifies the delimiter character used in the TagList-<N> entries.

Valid values: Any single character

Default: (space)

Used by:Retag Tables in Paras

Count

Specifies the number of TagList-<N> and TagFmtStr-<N> pairs.

Valid values: Integer value

Default: 0

Used by:Retag Tables in Paras

TagList-<N>

List of paragraph tags separated with the “Delim” character. One entry per table prefix/suffix.

Valid values: Paragraph tag names.

Default: (none)

Used by:Retag Tables in Paras

TagFmtStr-<N>

Prefix/suffix string added to the current table format name.

Valid values: String value.

Default: (none)

Used by:Retag Tables in Paras

[BuildMenucascades]

SourceType

Specifies the construction of elements to process. If you are matching on a single element that contains multiple “menu items” separated with a delimiter, the SourceType is “0”. If you are matching on multiple elements separated with a delimiter, the SourceType is “1”.

Valid values: Integer value (0 or 1)

Default: 0

Used by:Build Menucascades

MatchSpec

Specifies the element to match for performing this operation. You can specify and element name or an element and attribute (b/@outputclass=’uicontrol’).

Valid values: String value

Default: uicontrol

Used by:Build Menucascades

Delim

Specifies the menu delimiter to split on (typically a “>”).

Valid values: String value

Default: >

Used by:Build Menucascades

WrapperElem

Specifies the element name to be the wrapper for the menucascade.

Valid values: String value

Default: menucascade

Used by:Build Menucascades

InnerElem

Specifies the element name within the menucascade.

Valid values: String value

Default: uicontrol

Used by:Build Menucascades

[Hypertext]

GotolinkHref

Defines the syntax of the resulting @href attribute. Can be used with building blocks.

Valid values: String value

Default: http://gotolinkurl?marker=<$URI-MARKERTEXT>&link=<$URI-LINKTEXT>

Used by:Map Hypertext Markers

NewlinkToData

If set to “1”, specifies that a “NEWLINK” marker should convert into fm-data-marker elements.

Valid values: Integer value

Default: 0

Used by:Map Hypertext Markers

[RellinksToReltable]

ElemName

Processes all cross-ref objects in the specified element.

Valid values: String value

Default: related-links

Used by:Related Links to Reltable

DeleteElem

If set to “1”, deletes the element specified by the ElemName parameter after processing.

Valid values: Integer value

Default: 0

Used by:Related Links to Reltable

[AFrameToRaster]

ImageType

Specifies the type of image to be created from the anchored frame.

Valid values: JPG, PNG, GIF, TIF, or a valid export filter hint string

Default: JPG

Used by:AFrame to Raster

ImageFilenameTemplate

Defines the “template” for the generated graphic file names. New building blocks are available for this template: <$IMG-DOCNAME> (the document name), <$IMG-IMGNAME> (the first image file name in anchored frame [may be null]), and <$IMG-COUNT> (the nth aframe processed).

Valid values: String

Default: image_<$IMG-COUNT>.jpg

Used by:AFrame to Raster

ImagePath

Specifies the relative path where the generated graphics are written.

Valid values: String

Default: graphics

Used by:AFrame to Raster

ImageDpi

Specifies the DPI for the generated graphics.

Valid values: Integer

Default: 150

Used by:AFrame to Raster

ConvertTypes

A space-delimited list of graphic file types (file extensions). Matching file types found while processing are converted to the new type, even if there is just one object in the anchored frame.

Valid values: String

Default: (none)

Used by:AFrame to Raster