Mercurial > emacs
view admin/notes/documentation @ 99878:684861183d28
* emacs-lisp/elp.el (elp-instrument-list): Fix 2nd arg of `signal'.
author | Juanma Barranquero <lekktu@gmail.com> |
---|---|
date | Mon, 24 Nov 2008 18:23:53 +0000 |
parents | c1ca00a5b81d |
children | 374fce6afcea |
line wrap: on
line source
-*- 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.