Working with Indexterms

Special issues regarding the creation of index entries (indexterm and fm-indexterm elements).

DITA-FMx supports the use of the DITA indexing elements in FrameMaker by mapping them to the appropriate Index marker syntax, if the Indexterm to fm-indexterm option is enabled (in the Options dialog). When the Indexterm to fm-indexterm option is enabled, you must use the fm-indexterm element rather than indexterm.

In general, the process of creating an index entry works as it does in unstructured FrameMaker. Inserting an fm-indexterm element displays the Insert Marker dialog where you type the index entry using the standard FrameMaker index syntax. On file save, this marker syntax is converted into the proper DITA indexterm structure. When opened again in FrameMaker, this is converted to the FrameMaker marker syntax as an fm-indexterm element. When creating an index entry, feel free to enter multiple entries in a single Index marker (separated by semicolons and using the standard FrameMaker marker syntax). When you reopen the file in FrameMaker, you’ll see multiple fm-indexterm elements, because the single Index marker is converted into separate indexterm elements.

Note: For FrameMaker language versions that use a translated name for the “Index” marker (such as Japanese), you must edit the ditafmx.ini file and set the IndexOptions/IndexMarkerType parameter to the name of the Index marker on your system. In doing so, you may need to save the INI file as UTF-8 to prevent the characters from being corrupted.

In order to properly round-trip the “see” and “see-also” index entries, you need to include specific character styles within the marker syntax. For example to make a “see” entry, you would use the following syntax that uses the “ix-see” character style:

<$nopage>ONE:TWO. <ix-see>See</> SOMEWHERE, ELSE

To make a “see-also” entry, you would use the following syntax that uses the “ix-seealso” character style:

ONE:TWO;<$nopage>ONE:TWO:<ix-seealso>See also</> SOMEWHERE, ELSE

Important: You should not include the “forced sort” information in a “see” or “see-also” entry; that will be added based on the Forced Sort Value you enter in the DITA-FMx Index Options dialog. For example, if your Forced Sort Value is “zzz” the Index marker syntax of the sample entry above would be ONE:TWO;<$nopage>ONE:TWO:<ix-seealso>See also</> SOMEWHERE, ELSE[ONE:TWO:zzz]. The forced sort information is added when you save the file; if you manually enter forced soft information it will likely conflict with the automatically added value.

These character style names are defined in the Index Options dialog, so you can change them as needed. However, if you do change them, be sure to create the appropriate styles in the Topic and Book templates (“ix-see” and “ix-seealso” are the defaults).

The only way for DITA-FMx to know when you want an index entry to be a “see” or “see-also” is by entering the marker text in a specific way and to use these predefined character styles. If you enter the marker text differently, it may not properly convert into the DITA indexterm structure. Also note that after being saved to DITA and re-opened in FrameMaker, the marker text may vary slightly from what you entered (just punctuation and structure, not content). The Index Options dialog provides a number of options that allow you to define the way the indexterm content converts into the FrameMaker marker syntax.

DITA-FMx supports index page ranges through the indexterm start and end attributes. To create an index page range, insert an fm-indexterm element at the start of the range and set the start attribute to a unique value. Then insert another fm-indexterm at the end of the range and set the end attribute value to the same value as the start attribute. There is no need to enter the “<$startrange>” and “<$endrange>” FrameMaker index marker syntax; this will be added automatically when the file is reopened. The actual text of the “end” marker does not need to match that of the “start” marker, as it will be synced with the “start” marker (the end marker does need to have content, it cannot be left empty). If the “end” marker is located in a different file from that of the “start” marker, the end marker’s content will be “EMPTY”, but this value will be properly synced when the files are aggregated into chapter files at book-build time. Note that not all publishing processes will support index page ranges.

The DITA indexterm structure allows for elements that have no direct parallel in FrameMaker. If you need to work with very complex indexterm structures, you should disable the Indexterm to fm-indexterm conversion option in the Options dialog. This will give you access to the full array of elements provided by DITA and you'll be able to insert an indexterm element (as a container object, not a marker) and enter the specific DITA elements that you need. This is required if you want to use any non-index elements as children of an indexterm.