Discretionary Indexing

["Johns, David" <14615johns -at- KCPBLDG05 -dot- BV -dot- COM>]

Lori Lathrop asked about preventing inclusion of passing references when
using Doc-To-Help's indexing utility.  The answer is to use the
Discretionary Indexing Option.

After writing a manual for an electronic diagramming program called Logic, I
created an index list of about 200 words.  One of those words was "and"--a
term used to describe connections between electronic components.  When I
told Doc-To-Help to build the index, it inserted targets at EVERY instance
of the word "and."  There must have been over 1,000 "ands" in the document.
 My 486 PC with 4 MB RAM was unable to accommodate all the code inserted at
all the "ands", and it crashed.  So I redefined the index list, this time
using the discretionary option.  Here's how it works:

1. After completing a list of index targets (where Doc-To-Help inserts index
codes) and tags (words associated with targets and listed in the index
itself), select Indexing from the Tools menu.  The Indexing dialog box will
appear.

2. From the list of index targets created earlier, double-click any target
for which you want discretionary indexing, and the Options dialog box will
appear.

3. In the upper-left corner of the box, choose Auto (inserts targets at all
references) or Discretionary (prompts you at each instance).  Auto is
selected by default.

4. Select Search Criteria:
    --Match Upper/Lower Case
    --Match Whole Word Only

5. Select Placement Position:
    --First Instance after a Heading
    --First Instance on a Page
    --First Instance in a Chapter
    --Every Instance

6.  After setting up the target list, which is kept in an .ini file, you can
tell Doc-To-Help to insert the targets by selecting Build Index from the
Indexing Dialog box.  If you selected Discretionary Indexing for a word,
Doc-To-Help will prompt you at each instance of that word.  It will open the
document at each location and will then display another dialog box with
these options:  Insert Custom Tags, Skip This Location, Move to Next Target
in List, Finalize Discretionary Indexing, or Exit Indexing Program.

You can delete index targets or tags, but you will have to rebuild the
index.  After choosing Repair Manual from the menu, you can tell Doc-To-Help
to remove all existing index targets.  This takes about five minutes for a
100-page document with 200 targets.
After selecting Tools-Indexing-Build Index, Doc-To-Help will insert the
revised list of new targets throughout the document at selected positions.
 This takes about an hour on my 486 with 4 MB RAM and 33MHz.  At the end of
this build process, Doc-To-Help will create the actual index (comprising
tags and page numbers linked to targets) at the back of the document.  This
takes about one minute.

Dave Johns
Black & Veatch