Index entries in the manuals

Index entries in the manuals

[Eli Zaretskii]

Would people who work on the manuals please think about indexing while
at that?

The indexing in the Emacs manuals is generally very good, but it
sometimes warrants improvement, especially when large portions are
being rewritten or amended.

For example, this text:

    @vindex x-gtk-show-hidden-files
    @vindex x-gtk-file-dialog-help-text
      When Emacs is compiled with GTK+ support, it uses the GTK+ ``file
    chooser'' dialog.  Emacs adds an additional toggle button to this
    dialog, which you can use to enable or disable the display of hidden
    files (files starting with a dot) in that dialog.  If you want this
    toggle to be activated by default, change the variable
    @code{x-gtk-show-hidden-files} to @code{t}.  In addition, Emacs adds
    help text to the GTK+ file chooser dialog; to disable this help text,
    change the variable @code{x-gtk-file-dialog-help-text} to @code{nil}.

has index entries for the variables it describes, which is good, but
what if a user looks for this information without knowing the names of
these variables?  For those, I added these two concept index entries:

    @cindex hidden files, in GTK+ file chooser
    @cindex help text, in GTK+ file chooser

Thus, if a user types "i hidden files TAB" in Info, she will see the
first entry, and if so if she types "i file chooser RET".  See why it
is better?

The way to come up with useful index entries is to put yourself in the
shoes of someone who looks for the information, and think about words
and phrases you'd use to find it.

One other rule for good indexing is not to have several index entries
that begin with the same substring and point to the same page or
screenful (i.e. to places that are close to one another).  Here's a
fictitious example of such redundant entries:

  @cindex foobar, how to use
  @cindex foobar rules

  Either leave only one of these, e.g. just "@cindex foobar", or
combine them into a single entry, e.g.:

  @cindex foobar, rules and usage

Index entries are one of the most powerful features of the Info
documentation system.  Please help improving indexing in the Emacs
manuals.