11.4 Making Index Entries

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: 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. The advanced indexing features described in Advanced Indexing can help with this, as well.

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 “Indices” are 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 skilled art, the subtleties of which may not be appreciated until you need to do it yourself.