Contents | < Browse | Browse >
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.
The usual convention is to capitalize the first word of each index
entry, unless that word is the name of a function, variable, or other
such entity that should not be capitalized. Thus, if you are
documenting Emacs Lisp, you should usually capitalize entries in the
concept index, but not those in the function index. However, if your
concept index entries are consistently short (one or two words each) it
may look better for each regular entry to start with a lower case
letter. Whichever convention you adapt, please be consistent!
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 (Marking Text).
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. An extra colon
confuses Info. Menu Parts, 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.
(Printing Indices & Menus)