Go to the first, previous, next, last section, table of contents.

12. Indices

Using Texinfo, you can generate indices without having to sort and collate entries manually. In an index, the entries are listed in alphabetical order, together with information on how to find the discussion of each entry. In a printed manual, this information consists of page numbers. In an Info file, this information is a menu entry leading to the first node referenced.

Texinfo provides several predefined kinds of index: an index for functions, an index for variables, an index for concepts, and so on. You can combine indices or use them for other than their canonical purpose. If you wish, you can define your own indices.

12.1 Making Index Entries

When you are making index entries, it is good practice to think of the different ways people may look for something. Different people do not think of the same words when they look something up. A helpful index will have items indexed under all the different words that people may use. For example, one reader may think it obvious that the two-letter names for indices should be listed under "Indices, two-letter names", since the word "Index" is the general concept. But another reader may remember the specific concept of two-letter names and search for the entry listed as "Two letter names for indices". A good index will have both entries and will help both readers.

Like typesetting, the construction of an index is a highly skilled, professional art, the subtleties of which are not appreciated until you need to do it yourself.

See section 4.1 Index Menus and Printing an Index, for information about printing an index at the end of a book or creating an index menu in an Info file.

12.2 Predefined Indices

Texinfo provides six predefined indices:

Not every manual needs all of these, and most manuals use two or three of them. This manual has two indices: a concept index and an @-command index (that is actually the function index but is called a command index in the chapter heading). Two or more indices can be combined into one using the @synindex or @syncodeindex commands. See section 12.4 Combining Indices.

12.3 Defining the Entries of an Index

The data to make an index come from many individual indexing commands scattered throughout the Texinfo source file. Each command says to add one entry to a particular index; after formatting, the index will give the current page number or node name as the reference.

An index entry consists of an indexing command at the beginning of a line followed, on the rest of the line, by the entry.

For example, this section begins with the following five entries for the concept index:

@cindex Defining indexing entries
@cindex Index entries
@cindex Entries for an index
@cindex Specifying index entries
@cindex Creating index entries

Each predefined index has its own indexing command---@cindex for the concept index, @findex for the function index, and so on.

Concept index entries consist of text. The best way to write an index is to choose entries that are terse yet clear. If you can do this, the index often looks better if the entries are not capitalized, but written just as they would appear in the middle of a sentence. (Capitalize proper names and acronyms that always call for upper case letters.) This is the case convention we use in most GNU manuals' indices.

If you don't see how to make an entry terse yet clear, make it longer and clear--not terse and confusing. If many of the entries are several words long, the index may look better if you use a different convention: to capitalize the first word of each entry. But do not capitalize a case-sensitive name such as a C or Lisp function name or a shell command; that would be a spelling error.

Whichever case convention you use, please use it consistently!

Entries in indices other than the concept index are symbol names in programming languages, or program names; these names are usually case-sensitive, so use upper and lower case as required for them.

By default, entries for a concept index are printed in a small roman font and entries for the other indices are printed in a small @code font. You may change the way part of an entry is printed with the usual Texinfo commands, such as @file for file names and @emph for emphasis (see section 9. Marking Words and Phrases).

The six indexing commands for predefined indices are:

@cindex concept
Make an entry in the concept index for concept.
@findex function
Make an entry in the function index for function.
@vindex variable
Make an entry in the variable index for variable.
@kindex keystroke
Make an entry in the key index for keystroke.
@pindex program
Make an entry in the program index for program.
@tindex data type
Make an entry in the data type index for data type.

Caution: Do not use a colon in an index entry. In Info, a colon separates the menu entry name from the node name, so a colon in the entry itself confuses Info. See section 7.3 The Parts of a Menu, for more information about the structure of a menu entry.

You are not actually required to use the predefined indices for their canonical purposes. For example, suppose you wish to index some C preprocessor macros. You could put them in the function index along with actual functions, just by writing @findex commands for them; then, when you print the "Function Index" as an unnumbered chapter, you could give it the title `Function and Macro Index' and all will be consistent for the reader. Or you could put the macros in with the data types by writing @tindex commands for them, and give that index a suitable title so the reader will understand. (See section 4.1 Index Menus and Printing an Index.)

12.4 Combining Indices

Sometimes you will want to combine two disparate indices such as functions and concepts, perhaps because you have few enough of one of them that a separate index for them would look silly.

You could put functions into the concept index by writing @cindex commands for them instead of @findex commands, and produce a consistent manual by printing the concept index with the title `Function and Concept Index' and not printing the `Function Index' at all; but this is not a robust procedure. It works only if your document is never included as part of another document that is designed to have a separate function index; if your document were to be included with such a document, the functions from your document and those from the other would not end up together. Also, to make your function names appear in the right font in the concept index, you would need to enclose every one of them between the braces of @code.

12.4.1 @syncodeindex

When you want to combine functions and concepts into one index, you should index the functions with @findex and index the concepts with @cindex, and use the @syncodeindex command to redirect the function index entries into the concept index.

The @syncodeindex command takes two arguments; they are the name of the index to redirect, and the name of the index to redirect it to. The template looks like this:

@syncodeindex from to

For this purpose, the indices are given two-letter names:

concept index
function index
variable index
key index
program index
data type index

Write an @syncodeindex command before or shortly after the end-of-header line at the beginning of a Texinfo file. For example, to merge a function index with a concept index, write the following:

@syncodeindex fn cp

This will cause all entries designated for the function index to merge in with the concept index instead.

To merge both a variables index and a function index into a concept index, write the following:

@syncodeindex vr cp
@syncodeindex fn cp

The @syncodeindex command puts all the entries from the `from' index (the redirected index) into the @code font, overriding whatever default font is used by the index to which the entries are now directed. This way, if you direct function names from a function index into a concept index, all the function names are printed in the @code font as you would expect.

12.4.2 @synindex

The @synindex command is nearly the same as the @syncodeindex command, except that it does not put the `from' index entries into the @code font; rather it puts them in the roman font. Thus, you use @synindex when you merge a concept index into a function index.

See section 4.1 Index Menus and Printing an Index, for information about printing an index at the end of a book or creating an index menu in an Info file.

12.5 Defining New Indices

In addition to the predefined indices, you may use the @defindex and @defcodeindex commands to define new indices. These commands create new indexing @-commands with which you mark index entries. The @defindex command is used like this:

@defindex name

The name of an index should be a two letter word, such as `au'. For example:

@defindex au

This defines a new index, called the `au' index. At the same time, it creates a new indexing command, @auindex, that you can use to make index entries. Use the new indexing command just as you would use a predefined indexing command.

For example, here is a section heading followed by a concept index entry and two `au' index entries.

@section Cognitive Semantics
@cindex kinesthetic image schemas
@auindex Johnson, Mark
@auindex Lakoff, George

(Evidently, `au' serves here as an abbreviation for "author".) Texinfo constructs the new indexing command by concatenating the name of the index with `index'; thus, defining an `au' index leads to the automatic creation of an @auindex command.

Use the @printindex command to print the index, as you do with the predefined indices. For example:

@node Author Index, Subject Index, , Top
@unnumbered Author Index

@printindex au

The @defcodeindex is like the @defindex command, except that, in the printed output, it prints entries in an @code font instead of a roman font. Thus, it parallels the @findex command rather than the @cindex command.

You should define new indices within or right after the end-of-header line of a Texinfo file, before any @synindex or @syncodeindex commands (see section 3.3 The Texinfo File Header).

Go to the first, previous, next, last section, table of contents.