From: Eli Zaretskii <eliz@gnu.org>
To: emacs-devel@gnu.org
Subject: Index entries in the manuals
Date: Mon, 20 Oct 2008 13:53:02 +0200 [thread overview]
Message-ID: <utzb7iiu9.fsf@gnu.org> (raw)
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.
reply other threads:[~2008-10-20 11:53 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=utzb7iiu9.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.