Mercurial > emacs
annotate admin/notes/documentation @ 99492:ee792794d888
(isearch-search-fun): Compare the length of the
current search string with the length of the string from the
previous search state to detect the situation when the user
adds or removes characters in the search string.
Use word-search-forward-lax and word-search-backward-lax in this
case, and otherwise word-search-forward and word-search-backward.
author | Juri Linkov <juri@jurta.org> |
---|---|
date | Tue, 11 Nov 2008 19:43:09 +0000 |
parents | c1ca00a5b81d |
children | 374fce6afcea |
rev | line source |
---|---|
98955
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
1 -*- outline -*- |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
2 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
3 Some documentation tips culled from emacs-devel postings. |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
4 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
5 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
6 ** Manual indices |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
7 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
8 http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00400.html |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
9 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
10 For example, this text: |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
11 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
12 @vindex x-gtk-show-hidden-files |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
13 @vindex x-gtk-file-dialog-help-text |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
14 When Emacs is compiled with GTK+ support, it uses the GTK+ ``file |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
15 chooser'' dialog. Emacs adds an additional toggle button to this |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
16 dialog, which you can use to enable or disable the display of hidden |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
17 files (files starting with a dot) in that dialog. If you want this |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
18 toggle to be activated by default, change the variable |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
19 @code{x-gtk-show-hidden-files} to @code{t}. In addition, Emacs adds |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
20 help text to the GTK+ file chooser dialog; to disable this help text, |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
21 change the variable @code{x-gtk-file-dialog-help-text} to @code{nil}. |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
22 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
23 has index entries for the variables it describes, which is good, but |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
24 what if a user looks for this information without knowing the names of |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
25 these variables? For those, I added these two concept index entries: |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
26 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
27 @cindex hidden files, in GTK+ file chooser |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
28 @cindex help text, in GTK+ file chooser |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
29 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
30 Thus, if a user types "i hidden files TAB" in Info, she will see the |
98959
c1ca00a5b81d
Fix wording of the first entry.
Eli Zaretskii <eliz@gnu.org>
parents:
98955
diff
changeset
|
31 first entry, and so if she types "i file chooser RET". See why it is |
c1ca00a5b81d
Fix wording of the first entry.
Eli Zaretskii <eliz@gnu.org>
parents:
98955
diff
changeset
|
32 better? |
98955
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
33 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
34 The way to come up with useful index entries is to put yourself in the |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
35 shoes of someone who looks for the information, and think about words |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
36 and phrases you'd use to find it. |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
37 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
38 One other rule for good indexing is not to have several index entries |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
39 that begin with the same substring and point to the same page or |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
40 screenful (i.e. to places that are close to one another). Here's a |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
41 fictitious example of such redundant entries: |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
42 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
43 @cindex foobar, how to use |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
44 @cindex foobar rules |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
45 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
46 Either leave only one of these, e.g. just "@cindex foobar", or |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
47 combine them into a single entry, e.g.: |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
48 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
49 @cindex foobar, rules and usage |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
50 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
51 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
52 ** Point is a proper name |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
53 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
54 http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00414.html |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
55 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
56 In Emacs tradition, we treat "point" as a proper name when it refers |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
57 to the current editing location. It should not have an article. |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
58 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
59 Thus, it is incorrect to write, "The point does not move". It should |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
60 be, "Point does not move". |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
61 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
62 If you see "the point" anywhere in Emacs documentation or comments, |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
63 referring to point, please fix it. |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
64 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
65 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
66 ** Don't use passive verbs |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
67 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
68 http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00414.html |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
69 |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
70 Documentation is clearer if it avoids the passive voice whenever |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
71 possible. For example, rather than saying "Point does not move", say |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
72 "This does not move point". If you come across passive verbs in Emacs |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
73 documentation or comments, please see if it is possible to make the |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
74 text shorter and clearer using the active voice. Usually that does |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
75 make an improvement. The explicit subject required by the active voice |
696800e083e7
New file, with some wisdom from emacs-devel.
Glenn Morris <rgm@gnu.org>
parents:
diff
changeset
|
76 often provides important information which makes the text clearer, too. |