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.
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]>
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.
<$FM_VOLNUM> - volumne number (or letter) defined in the FM file
<$FM_CHAPNUM> - chapter number (or letter) defined in the FM file
<$FM_FILENAME> - file name (without path or extension) of the FM file
<$FM_USER> - from maker.ini RegInfo/User
<$FM_COMPANY> - from maker.ini RegInfo/Company
<$OS_USERNAME> - %username% environment variable
<$OS_COMPUTERNAME> - %computername% environment variable
<$T_YYYY> - 4 digit year
<$T_YY> - 2 digit year
<$T_MM> - 2 digit month (zero padded)
<$T_MON> - 3 character month
<$T_MONTH> - full month name
<$T_DD> - 2 digit date (zero padded)
<$T_HOUR> - 2 digit hour (zero padded)
<$TITLE> - the actual text of the title (with “stop words” removed)
<$TITLE_NOSPACE> - the text of the title with spaces removed
<$TITLE_NOSPACECAMEL> - the text of the title, with spaces removed, using “camel” casing
<$TITLE_NOSPACECAMELLOW> - the text of the title, with spaces removed, using “camel” casing, and the first character lowercased
<$TITLE_SPACETOUNDER> - the text of the title with spaces replaced with underscores
<$UNIQUEID> - the unique ID as applied to the root topic element
<$TOPIC_TYPE> - the topic type’s element name
<$VAR(VARNAME)> - the value of the VARNAME variable
<$MARKERTEXT> - the value of the current marker’s marker text (for use with the Map Hypertext Markers command)
<$LINKTEXT> - the value of the current marker’s “link text” (for use with the Map Hypertext Markers command)
<$URI-VAR(VARNAME)> - the value of the VARNAME variable, URI-encoded
<$URI-MARKERTEXT> - the value of the current marker’s marker text, URI-encoded (for use with the Map Hypertext Markers command)
<$URI-LINKTEXT> - the value of the current marker’s “link text,” URI-encoded (for use with the Map Hypertext Markers command)
<$IMG-COUNT> - the nth anchored frame processed. (For use with the AFrame to Raster command.)
<$IMG-DOCNAME> - the current document name containing the anchored frame being processed. (For use with the AFrame to Raster command.)
<$IMG-IMGNAME> - the first image file name in anchored frame. Note that this may be null, if there are no referenced images in the frame. (For use with the AFrame to Raster command.)