Commit | Line | Data |
---|---|---|
8e5de323 GM |
1 | -*- outline -*- |
2 | ||
3 | Some documentation tips culled from emacs-devel postings. | |
4 | ||
5 | ||
6 | ** Manual indices | |
7 | ||
8 | http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00400.html | |
9 | ||
10 | For example, this text: | |
11 | ||
12 | @vindex x-gtk-show-hidden-files | |
13 | @vindex x-gtk-file-dialog-help-text | |
14 | When Emacs is compiled with GTK+ support, it uses the GTK+ ``file | |
15 | chooser'' dialog. Emacs adds an additional toggle button to this | |
16 | dialog, which you can use to enable or disable the display of hidden | |
17 | files (files starting with a dot) in that dialog. If you want this | |
18 | toggle to be activated by default, change the variable | |
19 | @code{x-gtk-show-hidden-files} to @code{t}. In addition, Emacs adds | |
20 | help text to the GTK+ file chooser dialog; to disable this help text, | |
21 | change the variable @code{x-gtk-file-dialog-help-text} to @code{nil}. | |
22 | ||
23 | has index entries for the variables it describes, which is good, but | |
24 | what if a user looks for this information without knowing the names of | |
25 | these variables? For those, I added these two concept index entries: | |
26 | ||
27 | @cindex hidden files, in GTK+ file chooser | |
28 | @cindex help text, in GTK+ file chooser | |
29 | ||
30 | Thus, if a user types "i hidden files TAB" in Info, she will see the | |
a93110ca EZ |
31 | first entry, and so if she types "i file chooser RET". See why it is |
32 | better? | |
8e5de323 GM |
33 | |
34 | The way to come up with useful index entries is to put yourself in the | |
35 | shoes of someone who looks for the information, and think about words | |
36 | and phrases you'd use to find it. | |
37 | ||
38 | One other rule for good indexing is not to have several index entries | |
39 | that begin with the same substring and point to the same page or | |
40 | screenful (i.e. to places that are close to one another). Here's a | |
41 | fictitious example of such redundant entries: | |
42 | ||
43 | @cindex foobar, how to use | |
44 | @cindex foobar rules | |
45 | ||
46 | Either leave only one of these, e.g. just "@cindex foobar", or | |
47 | combine them into a single entry, e.g.: | |
48 | ||
49 | @cindex foobar, rules and usage | |
50 | ||
51 | ||
52 | ** Point is a proper name | |
53 | ||
54 | http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00414.html | |
55 | ||
56 | In Emacs tradition, we treat "point" as a proper name when it refers | |
57 | to the current editing location. It should not have an article. | |
58 | ||
59 | Thus, it is incorrect to write, "The point does not move". It should | |
60 | be, "Point does not move". | |
61 | ||
62 | If you see "the point" anywhere in Emacs documentation or comments, | |
63 | referring to point, please fix it. | |
64 | ||
65 | ||
66 | ** Don't use passive verbs | |
67 | ||
68 | http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00414.html | |
69 | ||
70 | Documentation is clearer if it avoids the passive voice whenever | |
71 | possible. For example, rather than saying "Point does not move", say | |
72 | "This does not move point". If you come across passive verbs in Emacs | |
73 | documentation or comments, please see if it is possible to make the | |
74 | text shorter and clearer using the active voice. Usually that does | |
75 | make an improvement. The explicit subject required by the active voice | |
76 | often provides important information which makes the text clearer, too. | |
983ab7ba EZ |
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. | |
44e97401 GM |
115 | |
116 | ** To indicate possession, write Emacs's rather than Emacs'. | |
117 | http://lists.gnu.org/archive/html/emacs-devel/2012-02/msg00649.html |