13.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, defining
@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, as listed in the previous section.

Concept index entries consist of text. The best way to write an index is to devise entries which are terse yet clear. If you can do this, the index usually looks better if the entries are written just as they would appear in the middle of a sentence, that is, capitalizing only proper names and acronyms that always call for uppercase 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. Whichever case convention you use, use it consistently.

In any event, do not ever capitalize a case-sensitive name such as a C or Lisp function name or a shell command; that would be a spelling error. Entries in indices other than the concept index are symbol names in programming languages, or program names; these names are usually case-sensitive, so likewise use upper- and lowercase as required.

It is a good idea to make index entries unique wherever feasible. That way, people using the printed output or online completion of index entries don’t see undifferentiated lists. Consider this an opportunity to make otherwise-identical index entries be more specific, so readers can more easily find the exact place they are looking for.

Index entries should precede the visible material that is being indexed. For instance:

@cindex hello
Hello, there!

Among other reasons, that way following indexing links (in whatever context) ends up before the material, where readers want to be, instead of after.

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 (see section Marking Text, Words and Phrases), and @r for the normal roman font (see section Fonts for Printing).

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 The Parts of a Menu, for more information about the structure of a menu entry.

This document was generated on October 2, 2013 using texi2html 5.0.