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.
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 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.
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 Combining Indices.
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 Marking Words and Phrases).
The six indexing commands for predefined indices are:
@cindex concept
@findex function
@vindex variable
@kindex keystroke
@pindex program
@tindex 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. An extra colon confuses Info. See section The Parts of a Menu, for more information about the structure of a menu entry.
If you write several identical index entries in different places in a Texinfo file, the index in the printed manual will list all the pages to which those entries refer. However, the index in the Info file will list only the node that references the first of those index entries. Therefore, it is best to write indices in which each entry refers to only one place in the Texinfo file. Fortunately, this constraint is a feature rather than a loss since it means that the index will be easy to use. Otherwise, you could create an index that lists several pages for one entry and your reader would not know to which page to turn. If you have two identical entries for one topic, change the topics slightly, or qualify them to indicate the difference.
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 Index Menus and Printing an Index.)
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.
@code
font for the merged-from index.
@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:
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.
@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 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.
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 The Texinfo File Header).