mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-11-29 07:58:28 +00:00
77 lines
2.9 KiB
Plaintext
77 lines
2.9 KiB
Plaintext
-*- outline -*-
|
|
|
|
Some documentation tips culled from emacs-devel postings.
|
|
|
|
|
|
** Manual indices
|
|
|
|
http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00400.html
|
|
|
|
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 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
|
|
|
|
|
|
** Point is a proper name
|
|
|
|
http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00414.html
|
|
|
|
In Emacs tradition, we treat "point" as a proper name when it refers
|
|
to the current editing location. It should not have an article.
|
|
|
|
Thus, it is incorrect to write, "The point does not move". It should
|
|
be, "Point does not move".
|
|
|
|
If you see "the point" anywhere in Emacs documentation or comments,
|
|
referring to point, please fix it.
|
|
|
|
|
|
** Don't use passive verbs
|
|
|
|
http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00414.html
|
|
|
|
Documentation is clearer if it avoids the passive voice whenever
|
|
possible. For example, rather than saying "Point does not move", say
|
|
"This does not move point". If you come across passive verbs in Emacs
|
|
documentation or comments, please see if it is possible to make the
|
|
text shorter and clearer using the active voice. Usually that does
|
|
make an improvement. The explicit subject required by the active voice
|
|
often provides important information which makes the text clearer, too.
|