Indexing FrameMaker Documents

By Anitha S. Rao

Designing an effective technical communication product, be it online Help or a printed manual, is an eternal challenge for technical writers.

Marking an Index Entry

To mark an index entry, you can either select the text in your document or manually type in an index entry. To mark an index entry use the Special > Marker menu option. Enter the text for the index entry, and choose the type of marker in the Marker dialog box. FrameMaker accepts index entries of up to 255 characters.

Following is a sample index entry:

   vi editor (primary entry)

      See also ex editor (cross-reference)

      command summary, 4-8 (secondary entries and page numbers)

This index entry contains a primary entry (vi editor), a cross-reference (See also ex editor), and a secondary index entry (command summary).

You can also use any of the following building blocks in the marker text to control the form of the index entry and its location in the index.

Planning an Index

The scope of an index depends on the type of manual you are indexing, and not on its page count. For example, a reference manual has a shorter index than a conceptual guide. A reference manual includes terms such as commands, qualifiers, and keywords. A conceptual guide, on the other hand, contains not just terms, but also concepts and procedures.

Guidelines for Choosing What to Index

• Terms defined in the text

• Acronyms and mnemonics

• Command descriptions

• Preface and appendixes – if they contain important, pertinent material
  that are not included in the main body of the text

• Figures

• Parameter names

• Routine and function names

• Standards, such as IEEE or ASCII

• Tables

• Utilities

• Notes, cautions, warnings, and restrictions

• Tasks described in the manual

• Overall concepts described in the manual

• Subject of the manual

• Individual error messages documented in the manual

Character Formatting for an Index Marker

You can use the following character formatting tags to format an index entry:

• <Default Para Font>

• <Emphasis>

• <bold>

For example, the output of the index entry, <bold>routers<Default Para Font>:internal;routers:external, is as follows:

   routers

      external  5

      internal   6

Specifying the Sorting Order for an Index Entry

In FrameMaker, you can change the sorting order of an index entry.

For example, consider the entry “1024 KB”. By default, this entry is sorted under the Numbers category, but you might wish to sort this entry under the “K” alphabet category. Another instance where you might wish to change the order is while cross-referencing. When you use the ‘See also’ cross-reference in an index marker, you might want to list this entry as the last subentry for a primary index entry.

To change the sorting order for an index entry, add text between square brackets ([…]) at the end of the marker text to indicate the sorting order.

Example: 

Troubleshooting Indexes

After generating the index, you may notice many discrepancies in the output. The discrepancies may be due to the following reasons:

Incorrect character formatting

If you use a character formatting tag such as <Emphasis>, ensure that you reset the format to the default format using the <Default Para Font>. Otherwise, the entire index entry appears in italics. Consider the following example:

Incorrect use of <$nopage> tag

When you specify multiple index entries, and if you incorrectly place the <$nopage> tag in a cross-reference entry, the subsequent index entry will not contain a page number. Consider the following example:

Incorrect marker text

Most problems that occur during indexing arise from spelling mistakes and incorrect usage of “:” (colon). Consider the following example:

(Anitha S Rao is an Information Engineer at Hewlett-Packard, Bangalore.)

STC India | Home | Contact Us

Copyright © 2003 India Chapter STC. All rights reserved.