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