texinfo: Indexing Commands

Indices

Combining Indices

Predefined Indices

Back to Software Index

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 (Note: Marking Text),
and '@r' for the normal roman font (Note: Fonts).

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