annotate admin/notes/documentation @ 111453:5f5f21c6fca1

ChangeLog fix.
author Glenn Morris <rgm@gnu.org>
date Tue, 09 Nov 2010 19:43:44 -0800
parents 374fce6afcea
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
77
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
78
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
79 ** Antinews nodes
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
80
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
81 *** Why Antinews is useful
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
82
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
83 http://lists.gnu.org/archive/html/emacs-devel/2008-11/msg00893.html
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
84
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
85 The usefulness of Antinews is to help people who buy the printed
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
86 manual and are still using the previous Emacs version. That's why we
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
87 focus on the (eliminated) behavior of the old version rather than on
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
88 the new features.
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
89
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
90 Of course, we try to make it amusing as well.
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
91
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
92 *** Don't mention in Antinews too many features absent in old versions
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
93
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
94 http://lists.gnu.org/archive/html/emacs-devel/2008-11/msg01054.html
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
95
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
96 Since the purpose of Antinews is to help people use the previous Emacs
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
97 version, there is usually no need to mention features that are simply
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
98 absent in that version. That situation will be clear enough to users
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
99 without help from the manual.
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
100
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
101 For instance, this
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
102
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
103 @item
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
104 Emacs can no longer be started as a daemon. We decided that having an
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
105 Emacs sitting silently in the background with no visual manifestation
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
106 anywhere in sight is too confusing.
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
107
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
108 may not need mentioning, because --daemon will give an error message
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
109 saying it's not implemented, and other cases aren't affected.
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
110
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
111 The kind of change for which the user really needs help from Antinews
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
112 is where a feature works _differently_ in the previous version.
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
113 In those cases, the user might have trouble figuring out how to use
374fce6afcea Add notes about Antinews.
Eli Zaretskii <eliz@gnu.org>
parents: 98959
diff changeset
114 the old version without some sort of help.