Mercurial > emacs
view admin/notes/documentation @ 99503:9d16e131644e
2008-11-12 Carsten Dominik <dominik@science.uva.nl>
* org.texi (Clocking work time): Document the :formula property of
clock tables.
(Structure editing, Refiling notes): Document refiling regions.
(Agenda commands): Document the double-prefix version
of the `l' command in the agenda.
(Handling links): Explain the effect of a double prefix
arg to `C-c C-o'.
(TODO basics): Add documentation for tag triggers.
author | Carsten Dominik <dominik@science.uva.nl> |
---|---|
date | Wed, 12 Nov 2008 08:06:54 +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.