[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Index entries in the manuals
From: |
Eli Zaretskii |
Subject: |
Index entries in the manuals |
Date: |
Mon, 20 Oct 2008 13:53:02 +0200 |
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.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- Index entries in the manuals,
Eli Zaretskii <=