Mercurial > emacs
annotate admin/notes/documentation @ 99536:cca376562315
(About This Manual): Comment out a mention of marginal notes.
author | Jay Belanger <jay.p.belanger@gmail.com> |
---|---|
date | Fri, 14 Nov 2008 05:32:03 +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. |