5. Index Support

LaTeX has builtin support for creating an Index. The LaTeX core supports two different indices, the standard index and a glossary. With the help of special LaTeX packages (`multind.sty' or `index.sty'), any number of indices can be supported.

Index entries are created with the \index{entry} macro. All entries defined in a document are written out to the `.aux' file. A separate tool must be used to convert this information into a nicely formatted index. Tools used with LaTeX include MakeIndex and xindy.

Indexing is a very difficult task. It must follow strict conventions to make the index consistent and complete. There are basically two approaches one can follow, and both have their merits.

1. Part of the indexing should already be done with the markup. The document structure should be reflected in the index, so when starting new sections, the basic topics of the section should be indexed. If the document contains definitions, theorems or the like, these should all correspond to appropriate index entries. This part of the index can very well be developed along with the document. Often it is worthwhile to define special purpose macros which define an item and at the same time make an index entry, possibly with special formatting to make the reference page in the index bold or underlined. To make RefTeX support for indexing possible, these special macros must be added to RefTeX's configuration (see section 5.5 Defining Index Macros).

2. The rest of the index is often just a collection of where in the document certain words or phrases are being used. This part is difficult to develop along with the document, because consistent entries for each occurrence are needed and are best selected when the document is ready. RefTeX supports this with an index phrases file which collects phrases and helps indexing the phrases globally.

Before you start, you need to make sure that RefTeX knows about the index style being used in the current document. RefTeX has builtin support for the default \index and \glossary macros. Other LaTeX packages, like the `multind' or `index' package, redefine the \index macro to have an additional argument, and RefTeX needs to be configured for those. A sufficiently new version of AUCTeX (9.10c or later) will do this automatically. If you really don't use AUCTeX (you should!), this configuration needs to be done by hand with the menu (Ref->Index Style), or globally for all your documents with

(setq reftex-index-macros '(multind))     or
(setq reftex-index-macros '(index))

5.1 Creating Index Entries

In order to index the current selection or the word at the cursor press C-c / (reftex-index-selection-or-word). This causes the selection or word `word' to be replaced with `\index{word}word'. The macro which is used (\index by default) can be configured with the variable reftex-index-default-macro. When the command is called with a prefix argument (C-u C-c /), you get a chance to edit the generated index entry. Use this to change the case of the word or to make the entry a subentry, for example by entering `main!sub!word'. When called with two raw C-u prefixes (C-u C-u C-c /), you will be asked for the index macro as well. When there is nothing selected and no word at point, this command will just call reftex-index, described below.

In order to create a general index entry, press C-c < (reftex-index). RefTeX will prompt for one of the available index macros and for its arguments. Completion will be available for the index entry and, if applicable, the index tag. The index tag is a string identifying one of multiple indices. With the `multind' and `index' packages, this tag is the first argument to the redefined \index macro.

5.2 The Index Phrases File

RefTeX maintains a file in which phrases can be collected for later indexing. The file is located in the same directory as the master file of the document and has the extension `.rip' (Reftex Index Phrases). You can create or visit the file with C-c | (reftex-index-visit-phrases-buffer). If the file is empty it is initialized by inserting a file header which contains the definition of the available index macros. This list is initialized from reftex-index-macros (see section 5.5 Defining Index Macros). You can edit the header as needed, but if you define new LaTeX indexing macros, don't forget to add them to reftex-index-macros as well. Here is a phrase file header example:

% -*- mode: reftex-index-phrases -*-
%                           Key   Macro Format       Repeat
%----------------------------------------------------------
>>>INDEX_MACRO_DEFINITION:   i    \index{%s}          t
>>>INDEX_MACRO_DEFINITION:   I    \index*{%s}         nil
>>>INDEX_MACRO_DEFINITION:   g    \glossary{%s}       t
>>>INDEX_MACRO_DEFINITION:   n    \index*[name]{%s}   nil
%----------------------------------------------------------

The macro definition lines consist of a unique letter identifying a macro, a format string and the repeat flag, all separated by TAB. The format string shows how the macro is to be applied, the `%s' will be replaced with the index entry. The repeat flag indicates if word is indexed by the macro as `\index{word}' (repeat = nil) or as `\index{word}word' (repeat = t). In the above example it is assumed that the macro \index*{word} already typesets its argument in the text, so that it is unnecessary to repeat word outside the macro.

5.2.1 Collecting Phrases

Phrases for indexing can be collected while writing the document. The command C-c \ (reftex-index-phrase-selection-or-word) copies the current selection (if active) or the word near point into the phrases buffer. It then selects this buffer, so that the phrase line can be edited. To return to the LaTeX document, press C-c C-c (reftex-index-phrases-save-and-return).

You can also prepare the list of index phrases in a different way and copy it into the phrases file. For example you might want to start from a word list of the document and remove all words which should not be indexed.

The phrase lines in the phrase buffer must have a specific format. RefTeX will use font-lock to indicate if a line has the proper format. A phrase line looks like this:

[key] <TABs> phrase [<TABs> arg[&&arg]... [ || arg]...] 

<TABs> stands for white space containing at least one TAB. key must be at the start of the line and is the character identifying one of the macros defined in the file header. It is optional - when omitted, the first macro definition line in the file will be used for this phrase. The phrase is the phrase to be searched for when indexing. It may contain several words separated by spaces. By default the search phrase is also the text entered as argument of the index macro. If you want the index entry to be different from the search phrase, enter another TAB and the index argument arg. If you want to have each match produce several index entries, separate the different index arguments with ` && '(4). If you want to be able to choose at each match between several different index arguments, separate them with ` || '(5). Here is an example:

%--------------------------------------------------------------------
I     Sun
i     Planet         Planets
i     Vega           Stars!Vega
      Jupiter        Planets!Jupiter
i     Mars           Planets!Mars || Gods!Mars || Chocolate Bars!Mars
i     Pluto          Planets!Pluto && Kuiper Belt Objects!Pluto

So `Sun' will be indexed directly as `\index*{Sun}', while `Planet' will be indexed as `\index{Planets}Planet'. `Vega' will be indexed as a subitem of `Stars'. The `Jupiter' line will also use the `i' macro as it was the first macro definition in the file header (see above example). At each occurrence of `Mars' you will be able choose between indexing it as a subitem of `Planets', `Gods' or `Chocolate Bars'. Finally, every occurrence of `Pluto' will be indexed as `\index{Planets!Pluto}\index{Kuiper Belt Objects!Pluto}Pluto' and will therefore create two different index entries.

5.2.2 Consistency Checks

Before indexing the phrases in the phrases buffer, they should be checked carefully for consistency. A first step is to sort the phrases alphabetically - this is done with the command C-c C-s (reftex-index-sort-phrases). It will sort all phrases in the buffer alphabetically by search phrase. If you want to group certain phrases and only sort within the groups, insert empty lines between the groups. Sorting will only change the sequence of phrases within each group (see the variable reftex-index-phrases-sort-in-blocks).

A useful command is C-c C-i (reftex-index-phrases-info) which lists information about the phrase at point, including an example of how the index entry will look like and the number of expected matches in the document.

Another important check is to find out if there are double or overlapping entries in the buffer. For example if you are first searching and indexing `Mars' and then `Planet Mars', the second phrase will not match because of the index macro inserted before `Mars' earlier. The command C-c C-t (reftex-index-find-next-conflict-phrase) finds the next phrase in the buffer which is either duplicate or a subphrase of another phrase. In order to check the whole buffer like this, start at the beginning and execute this command repeatedly.

5.2.3 Global Indexing

Once the index phrases have been collected and organized, you are set for global indexing. I recommend to do this only on an otherwise finished document. Global indexing starts from the phrases buffer. There are several commands which start indexing: C-c C-x acts on the current phrase line, C-c C-r on all lines in the current region and C-c C-a on all phrase lines in the buffer. It is probably good to do indexing in small chunks since your concentration may not last long enough to do everything in one go.

RefTeX will start at the first phrase line and search the phrase globally in the whole document. At each match it will stop, compute the replacement string and offer you the following choices(6):

y

Replace this match with the proposed string.

n

Skip this match.

!

Replace this and all further matches in this file.

q

Skip this match, start with next file.

Q

Skip this match, start with next phrase.

o

Select a different indexing macro for this match.

1-9

Select one of multiple index keys (those separated with `||').

e

Edit the replacement text.

C-r

Recursive edit. Use C-M-c to return to the indexing process.

s

Save this buffer and ask again about the current match.

S

Save all document buffers and ask again about the current match.

C-g

Abort the indexing process.

The `Find and Index in Document' menu in the phrases buffer also lists a few options for the indexing process. The options have associated customization variables to set the defaults (see section 8.6 Index Support). Here is a short explanation of what the options do:

Match Whole Words

When searching for index phrases, make sure whole words are matched. This should probably always be on.

Case Sensitive Search

Search case sensitively for phrases. I recommend to have this setting off, in order to match the capitalized words at the beginning of a sentence, and even typos. You can always say no at a match you do not like.

Wrap Long Lines

Inserting index macros increases the line length. Turn this option on to allow RefTeX to wrap long lines.

Skip Indexed Matches

When this is on, RefTeX will at each match try to figure out if this match is already indexed. A match is considered indexed if it is either the argument of an index macro, or if an index macro is directly (without whitespace separation) before or after the match. Index macros are those configured in reftex-index-macros. Intended for re-indexing a documents after changes have been made.

Even though indexing should be the last thing you do to a document, you are bound to make changes afterwards. Indexing then has to be applied to the changed regions. The command reftex-index-phrases-apply-to-region is designed for this purpose. When called from a LaTeX document with active region, it will apply reftex-index-all-phrases to the current region.

5.3 Displaying and Editing the Index

In order to compile and display the index, press C-c >. If the document uses multiple indices, RefTeX will ask you to select one. Then, all index entries will be sorted alphabetically and displayed in a special buffer, the `*Index*' buffer. From that buffer you can check and edit each entry.

The index can be restricted to the current section or the region. Then only entries in that part of the document will go into the compiled index. To restrict to the current section, use a numeric prefix `2', thus press C-u 2 C-c >. To restrict to the current region, make the region active and use a numeric prefix `3' (press C-u 3 C-c >). From within the `*Index*' buffer the restriction can be moved from one section to the next by pressing the < and > keys.

One caveat: RefTeX finds the definition point of an index entry by searching near the buffer position where it had found to macro during scanning. If you have several identical index entries in the same buffer and significant changes have shifted the entries around, you must rescan the buffer to ensure the correspondence between the `*Index*' buffer and the definition locations. It is therefore advisable to rescan the document (with r or C-u r) frequently while editing the index from the `*Index*' buffer.

Here is a list of special commands available in the `*Index*' buffer. A summary of this information is always available by pressing ?.

General

General

? Display a summary of commands.

0-9, - Prefix argument.

Moving around

Moving around

! A..Z Pressing any capital letter will jump to the corresponding section in the `*Index*' buffer. The exclamation mark is special and jumps to the first entries alphabetically sorted below `A'. These are usually non-alphanumeric characters.

n Go to next entry.

p Go to previous entry.

Access to document locations

Access to document locations

SPC Show the place in the document where this index entry is defined.

TAB Go to the definition of the current index entry in another window.

RET Go to the definition of the current index entry and hide the `*Index*' buffer window.

f Toggle follow mode. When follow mode is active, the other window will always show the location corresponding to the line in the `*Index*' buffer at point. This is similar to pressing SPC after each cursor motion. The default for this flag can be set with the variable reftex-index-follow-mode. Note that only context in files already visited is shown. RefTeX will not visit a file just for follow mode. See, however, the variable reftex-revisit-to-follow.

Entry editing

Entry editing

e Edit the current index entry. In the minibuffer, you can edit the index macro which defines this entry.

C-k Kill the index entry. Currently not implemented because I don't know how to implement an undo function for this.

* Edit the key part of the entry. This is the initial part of the entry which determines the location of the entry in the index.

| Edit the attribute part of the entry. This is the part after the vertical bar. With MakeIndex, this part is an encapsulating macro. With xindy, it is called attribute and is a property of the index entry that can lead to special formatting. When called with C-u prefix, kill the entire attribute part.

@ Edit the visual part of the entry. This is the part after the `@' which is used by MakeIndex to change the visual appearance of the entry in the index. When called with C-u prefix, kill the entire visual part.

( Toggle the beginning of page range property `|(' of the entry.

) Toggle the end of page range property `|)' of the entry.

_ Make the current entry a subentry. This command will prompt for the superordinate entry and insert it.

^ Remove the highest superordinate entry. If the current entry is a subitem (`aaa!bbb!ccc'), this function moves it up the hierarchy (`bbb!ccc').

Exiting

Exiting

q Hide the `*Index*' buffer.

k Kill the `*Index*' buffer.

C-c = Switch to the Table of Contents buffer of this document.

Controlling what gets displayed

Controlling what gets displayed

c Toggle the display of short context in the `*Index*' buffer. The default for this flag can be set with the variable reftex-index-include-context.

} Restrict the index to a single document section. The corresponding section number will be displayed in the R<> indicator in the mode line and in the header of the `*Index*' buffer.

{ Widen the index to contain all entries of the document.

< When the index is currently restricted, move the restriction to the previous section.

> When the index is currently restricted, move the restriction to the next section.

Updating the buffer

Updating the buffer

g Rebuild the `*Index*' buffer. This does not rescan the document. However, it sorts the entries again, so that edited entries will move to the correct position.

r Reparse the LaTeX document and rebuild the `*Index*' buffer. When reftex-enable-partial-scans is non-nil, rescan only the file this location is defined in, not the entire document.

C-u r Reparse the entire LaTeX document and rebuild the `*Index*' buffer.

s Switch to a different index (for documents with multiple indices).

5.4 Builtin Index Macros

RefTeX by default recognizes the \index and \glossary macros which are defined in the LaTeX core. It has also builtin support for the re-implementations of \index in the `multind' and `index' packages. However, since the different definitions of the \index macro are incompatible, you will have to explicitly specify the index style used. See section 5.1 Creating Index Entries, for information on how to do that.

5.5 Defining Index Macros

When writing a document with an index you will probably define additional macros which make entries into the index. Let's look at an example.

\newcommand{\ix}[1]{#1\index{#1}}
\newcommand{\nindex}[1]{\textit{#1}\index[name]{#1}}
\newcommand{\astobj}[1]{\index{Astronomical Objects!#1}}

The first macro \ix typesets its argument in the text and places it into the index. The second macro \nindex typesets its argument in the text and places it into a separate index with the tag `name'(7). The last macro also places its argument into the index, but as subitems under the main index entry `Astronomical Objects'. Here is how to make RefTeX recognize and correctly interpret these macros, first with Emacs Lisp.

(setq reftex-index-macros
      '(("\\ix{*}" "idx" ?x "" nil nil)
        ("\\nindex{*}" "name" ?n "" nil nil)
        ("\\astobj{*}" "idx" ?o "Astronomical Objects!" nil t)))

Note that the index tag is `idx' for the main index, and `name' for the name index. `idx' and `glo' are reserved for the default index and for the glossary.

The character arguments ?x, ?n, and ?o are for quick identification of these macros when RefTeX inserts new index entries with reftex-index. These codes need to be unique. ?i, ?I, and ?g are reserved for the \index, \index*, and \glossary macros, respectively.

The following string is empty unless your macro adds a superordinate entry to the index key - this is the case for the \astobj macro.

The next entry can be a hook function to exclude certain matches, it almost always can be nil.

The final element in the list indicates if the text being indexed needs to be repeated outside the macro. For the normal index macros, this should be t. Only if the macro typesets the entry in the text (like \ix and \nindex in the example do), this should be nil.

To do the same thing with customize, you need to fill in the templates like this:

Repeat:
[INS] [DEL] List:
            Macro with args: \ix{*}
            Index Tag      : [Value Menu] String: idx
            Access Key     : x
            Key Prefix     : 
            Exclusion hook : nil
            Repeat Outside : [Toggle]  off (nil)
[INS] [DEL] List:
            Macro with args: \nindex{*}
            Index Tag      : [Value Menu] String: name
            Access Key     : n
            Key Prefix     : 
            Exclusion hook : nil
            Repeat Outside : [Toggle]  off (nil)
[INS] [DEL] List:
            Macro with args: \astobj{*}
            Index Tag      : [Value Menu] String: idx
            Access Key     : o
            Key Prefix     : Astronomical Objects!
            Exclusion hook : nil
            Repeat Outside : [Toggle]  on (non-nil)
[INS]

With the macro \ix defined, you may want to change the default macro used for indexing a text phrase (see section 5.1 Creating Index Entries). This would be done like this

(setq reftex-index-default-macro '(?x "idx"))

which specifies that the macro identified with the character ?x (the \ix macro) should be used for indexing phrases and words already in the buffer with C-c / (reftex-index-selection-or-word). The index tag is "idx".

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.