Mercurial > emacs
annotate admin/notes/documentation @ 106856:5fc7644b0c5f
Merge from trunk
author | Jan D. <jan.h.d@swipnet.se> |
---|---|
date | Fri, 15 Jan 2010 18:01:51 +0100 |
parents | 374fce6afcea |
children |
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. |
100030 | 77 |
78 | |
79 ** Antinews nodes | |
80 | |
81 *** Why Antinews is useful | |
82 | |
83 http://lists.gnu.org/archive/html/emacs-devel/2008-11/msg00893.html | |
84 | |
85 The usefulness of Antinews is to help people who buy the printed | |
86 manual and are still using the previous Emacs version. That's why we | |
87 focus on the (eliminated) behavior of the old version rather than on | |
88 the new features. | |
89 | |
90 Of course, we try to make it amusing as well. | |
91 | |
92 *** Don't mention in Antinews too many features absent in old versions | |
93 | |
94 http://lists.gnu.org/archive/html/emacs-devel/2008-11/msg01054.html | |
95 | |
96 Since the purpose of Antinews is to help people use the previous Emacs | |
97 version, there is usually no need to mention features that are simply | |
98 absent in that version. That situation will be clear enough to users | |
99 without help from the manual. | |
100 | |
101 For instance, this | |
102 | |
103 @item | |
104 Emacs can no longer be started as a daemon. We decided that having an | |
105 Emacs sitting silently in the background with no visual manifestation | |
106 anywhere in sight is too confusing. | |
107 | |
108 may not need mentioning, because --daemon will give an error message | |
109 saying it's not implemented, and other cases aren't affected. | |
110 | |
111 The kind of change for which the user really needs help from Antinews | |
112 is where a feature works _differently_ in the previous version. | |
113 In those cases, the user might have trouble figuring out how to use | |
114 the old version without some sort of help. |