6.2 Creating indexes | Microsoft Office Automation with Visual FoxPro

Creating indexes

Long documents are far more useful when they re indexed. Unfortunately, the best way to produce a high-quality index is still the old-fashioned way by having a person do it. That s because no automated technique can read the contents of a manuscript and decide whether a particular use of a word or phrase deserves to be mentioned in the index. In fact, this problem is the reason that so many search engines produce irrelevant results so much of the time.

Nonetheless, Word offers a couple of ways to create indexes. Only one of the techniques is really suited to Automation, however, as the other involves a great deal of human intervention. The easily automated technique uses a concordance table listing all the words to be indexed and the index entries for them.

Deciding what to index

The concordance table is a separate document containing a standard Word table with two columns. You can create it interactively or through Automation. Table 2 is part of a concordance table for Chapter 3 of this book, "Visual FoxPro as an Automation Client" (though not the one actually used to index the book).

Table 2. Creating an index. One way to index a document is by using a table that lists the terms to be indexed together with the index entries.

1426	error:1426
1429	error:1429
Activate	Activate
Application	Application
client	client
collection	collection
collections	collection
Command Window	Command Window
CreateObject()	CreateObject()
CreateObjectEx()	CreateObjectEx()
DCOM	DCOM
debugger	debugger
debugging	debugging

The table shows several items worth noting. First, if a word appears in several forms in the document, you need to list all those forms in the table. (Notice "collection" and "collections" in the first column, both being indexed to "collection.")

Second, you can handle multiple levels in the index within the table by separating them with a colon in the second column. Note the entries for 1426 and 1429. In the index, these will both be part of a general entry for "error," but sub-divided into "1426" and "1429."

Third, most rows in the table have the same thing in the two columns. If you re creating the table interactively, this is a great place to take advantage of a Word feature that s usually an annoyance. In Word, the Edit|Repeat Typing menu option (the shortcut is Ctrl-Y) is almost always available. When you re creating a concordance table, you can use it to cut your typing almost in half. Type the string into the first column, then hit Ctrl-Y to repeat it in the second column.

Finally, Word is unfortunately not smart enough to notice when one index phrase is contained in another. For example, Table 2 contains the word "client." If we added "client application" to the table, when the index is created, a phrase like "Using VFP as our client application" would be indexed twice once for "client" and once for "client application." Beware of this issue as you decide what to put in the table.

Marking items for the index

Once you have the concordance table, the next step is to get the relevant items in the document marked. This is the part where the concordance table gets put to work and actually saves time. Interactively, choose Insert|Index and Tables from the menu. This displays the dialog shown in Figure 5. Choose AutoMark and select your concordance file.

Figure 5. Creating an index. To mark items in a document based on the concordance table, choose AutoMark from this dialog.

Word goes through the document and adds special fields to the document everywhere it finds an item from the left column of the concordance table.

To automate this process, you use the AutoMarkEntries method of the document s Indexes collection, like this:

oDocument.Indexes.AutoMarkEntries( "d:\autovfp\chapter3\wordlist.DOC" )

Generating the index

After the items are marked, creating the index itself is simple. Interactively, you position the cursor where the index is to be placed, then bring up the Index and Tables dialog (shown in Figure 5) again, choose a format from the Formats dropdown, check Right align page numbers, if you want, and choose OK. Figure 6 shows part of the index generated for Chapter 3, "Visual FoxPro as an Automation Client," based on the concordance in Table 2.

Figure 6. Generated index. Applying the concordance table in Table 2 to Chapter 3 results in this index.

To produce the index with Automation, you use the Add method of Indexes, passing it the range where the index is to be placed and several other parameters. This example creates the same index as in Figure 6, positioning it at the end of the document.

#DEFINE wdCollapseEnd 0

#DEFINE wdHeadingSeparatorNone 0

#DEFINE wdIndexIndent 0

#DEFINE wdTabLeaderDots 1

oRange = oDocument.Range()

oRange.Collapse( wdCollapseEnd )

oIndex = oDocument.Indexes.Add( oRange, wdHeadingSeparatorNone, .T., ;

wdIndexIndent, 2, .F.)

* Change leader to dots

oIndex.TabLeader = wdTabLeaderDots

oIndex.Update()

The Add method has a number of parameters. In the example, following the range, we specify that no punctuation is needed to separate entries for each letter of the alphabet in the index. Other choices include wdHeadingSeparatorBlankLine (1) and wdHeadingSeparatorLetter (2). The Index object s HeadingSeparator property matches up to this parameter.

The third parameter corresponds to the RightAlignPageNumbers property of the Index object and determines whether the page numbers immediately follow the entry or are right-justified.

The fourth parameter determines how the index handles sub-entries. The default value, wdIndexIndent (0), lists each sub-entry indented on a separate line beneath the main heading. The alternative option, wdIndexRunIn (1), separates the sub-entries with semi-colons on the same line with the main heading. Don t use it when you re right-aligning the page numbers it looks terrible in that case.

The fifth parameter specifies the number of columns in the index, two in the example. It corresponds to the NumberOfColumns property of the Index object.

The final parameter shown in the example indicates that accented letters should be combined with the basic letters. Pass .T. to separate accented letters into separate index listings. This parameter corresponds to Index s AccentedLetters property.

Add has several additional parameters, but they re fairly obscure. See Help for details.

Formatting indexes

As with tables of contents, once you ve added an index, you can use its properties to change its appearance. The Index object has a number of properties that affect its look a number of them correspond to parameters of the Indexes collection s Add method, as noted previously. In addition, as with TableOfContents, the TabLeader property lets you vary the character that appears between the entry and the page number(s). The constants are the same as for TableOfContents see Table 1.

The Update method (used in the example in the previous section), as its name suggests, updates the index. It s useful both when the marked index entries change and when you ve changed formatting.