Topic and Map Template Building Blocks

Building blocks control the file name format and structure for topics and maps.

The fm2dita.ini file includes two settings that require the use of file name building blocks. Most of the building blocks are the same as those provided in DITA-FMx (all except the “$FMX_” types), in addition to a four more “$FM_” types. A building block is a string of text enclosed in angle brackets and are used in the TopicNameTpl and MapNameTpl INI parameters.

The $TITLE* building blocks provide various options for using the text of the topic title. In all cases the text returned is processed by stripping the “stop words” as defined in the StopWords parameter.

Building Block Modifiers

You can include various types of modifiers after the building block name in square brackets to modify the resulting value.

Entering a number (from 0 to 99), limits the length of the resulting string to that value (the first N characters). If you want to extract a substring from a building block, include the start and end positions in square brackets. For example, the following building block will extract the first two characters from the topic type:

<$TOPIC_TYPE[2]>

Or, to extract the second through fifth characters, use the following syntax:

<$TOPIC_TYPE[2-5]>

Other modifiers can be used to change the case of the text that results from the building block. These single-character modifers must follow any numeric modifiers if present. The following modifiers are available:

The following syntax will generate the first two characters from the topic type in uppercase:

<$TOPIC_TYPE[2U]>

An additional “split” building block modifier is available for extracting a “field” from a delimited string. If the string being processed ($MARKERTEXT for example) contains values separated by colons, you can use this modifier to return the nth field from that string. Use the following syntax:

[<index><splitchar>S]

where <index> specifies the 1-based field and <splitchar> is the delimiter character (a single character). The following example will return the second “field” in a colon-delimited marker text string:

<$MARKERTEXT[2:S]>

Building Blocks

Valid building blocks are listed below. Some of these building blocks will make more sense for use in specific situations than others. Using an invalid building block may have unexpected results; be sure to thoroughly test on a small set of files if you’re unsure.

Note: Using time-based building blocks can result in errors if the conversion time spans the time unit boundary used in the building block. Use these building blocks with care.