Mercurial > emacs
annotate doc/emacs/trouble.texi @ 112397:a7191495c39c
Include entries from yesterdays checkins that were in an unsaved buffer.
author | Ken Manheimer <ken.manheimer@gmail.com> |
---|---|
date | Fri, 21 Jan 2011 11:36:24 -0500 |
parents | 376148b31b5e |
children |
rev | line source |
---|---|
84269 | 1 @c This is part of the Emacs manual. |
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, | |
112218
376148b31b5e
Add 2011 to FSF/AIST copyright years.
Glenn Morris <rgm@gnu.org>
parents:
112076
diff
changeset
|
3 @c 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 |
106802
b92c3979701c
Replace emacs-pretest-bug with bug-gnu-emacs mailing list.
Glenn Morris <rgm@gnu.org>
parents:
105594
diff
changeset
|
4 @c Free Software Foundation, Inc. |
84269 | 5 @c See file emacs.texi for copying conditions. |
6 @iftex | |
7 @chapter Dealing with Common Problems | |
8 | |
9 If you type an Emacs command you did not intend, the results are often | |
10 mysterious. This chapter tells what you can do to cancel your mistake or | |
11 recover from a mysterious situation. Emacs bugs and system crashes are | |
12 also considered. | |
13 @end iftex | |
14 | |
15 @ifnottex | |
16 @raisesections | |
17 @end ifnottex | |
18 | |
19 @node Quitting, Lossage, Customization, Top | |
20 @section Quitting and Aborting | |
21 @cindex quitting | |
22 | |
23 @table @kbd | |
24 @item C-g | |
25 @itemx C-@key{BREAK} @r{(MS-DOS only)} | |
26 Quit: cancel running or partially typed command. | |
27 @item C-] | |
28 Abort innermost recursive editing level and cancel the command which | |
29 invoked it (@code{abort-recursive-edit}). | |
30 @item @key{ESC} @key{ESC} @key{ESC} | |
31 Either quit or abort, whichever makes sense (@code{keyboard-escape-quit}). | |
32 @item M-x top-level | |
33 Abort all recursive editing levels that are currently executing. | |
103202
9597f2f82406
* trouble.texi (Quitting): Add other undo bindings to table.
Chong Yidong <cyd@stupidchicken.com>
parents:
103151
diff
changeset
|
34 @item C-/ |
9597f2f82406
* trouble.texi (Quitting): Add other undo bindings to table.
Chong Yidong <cyd@stupidchicken.com>
parents:
103151
diff
changeset
|
35 @itemx C-x u |
9597f2f82406
* trouble.texi (Quitting): Add other undo bindings to table.
Chong Yidong <cyd@stupidchicken.com>
parents:
103151
diff
changeset
|
36 @itemx C-_ |
84269 | 37 Cancel a previously made change in the buffer contents (@code{undo}). |
38 @end table | |
39 | |
40 There are two ways of canceling a command before it has finished: | |
41 @dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]} or | |
42 @kbd{M-x top-level}. Quitting cancels a partially typed command, or | |
43 one which is still running. Aborting exits a recursive editing level | |
44 and cancels the command that invoked the recursive edit. | |
45 (@xref{Recursive Edit}.) | |
46 | |
47 @cindex quitting | |
48 @kindex C-g | |
49 Quitting with @kbd{C-g} is the way to get rid of a partially typed | |
93360
80674d4c5239
(Quitting): Clarify effects of C-g.
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
50 command, or a numeric argument that you don't want. Furthermore, if |
80674d4c5239
(Quitting): Clarify effects of C-g.
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
51 you are in the middle of a command that is running, @kbd{C-g} stops |
80674d4c5239
(Quitting): Clarify effects of C-g.
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
52 the command in a relatively safe way. For example, if you quit out of |
80674d4c5239
(Quitting): Clarify effects of C-g.
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
53 a kill command that is taking a long time, either your text will |
80674d4c5239
(Quitting): Clarify effects of C-g.
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
54 @emph{all} still be in the buffer, or it will @emph{all} be in the |
80674d4c5239
(Quitting): Clarify effects of C-g.
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
55 kill ring, or maybe both. If the region is active, @kbd{C-g} |
80674d4c5239
(Quitting): Clarify effects of C-g.
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
56 deactivates the mark, unless Transient Mark mode is off |
80674d4c5239
(Quitting): Clarify effects of C-g.
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
57 (@pxref{Persistent Mark}). If you are in the middle of an incremental |
80674d4c5239
(Quitting): Clarify effects of C-g.
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
58 search, @kbd{C-g} does special things; it may take two successive |
80674d4c5239
(Quitting): Clarify effects of C-g.
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
59 @kbd{C-g} characters to get out of a search. @xref{Incremental |
80674d4c5239
(Quitting): Clarify effects of C-g.
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
60 Search}, for details. |
84269 | 61 |
62 On MS-DOS, the character @kbd{C-@key{BREAK}} serves as a quit character | |
63 like @kbd{C-g}. The reason is that it is not feasible, on MS-DOS, to | |
64 recognize @kbd{C-g} while a command is running, between interactions | |
65 with the user. By contrast, it @emph{is} feasible to recognize | |
66 @kbd{C-@key{BREAK}} at all times. | |
67 @iftex | |
68 @xref{MS-DOS Keyboard,,,emacs-xtra, Specialized Emacs Features}. | |
69 @end iftex | |
70 @ifnottex | |
71 @xref{MS-DOS Keyboard}. | |
72 @end ifnottex | |
73 | |
74 @findex keyboard-quit | |
75 @kbd{C-g} works by setting the variable @code{quit-flag} to @code{t} | |
76 the instant @kbd{C-g} is typed; Emacs Lisp checks this variable | |
77 frequently, and quits if it is non-@code{nil}. @kbd{C-g} is only | |
78 actually executed as a command if you type it while Emacs is waiting for | |
79 input. In that case, the command it runs is @code{keyboard-quit}. | |
80 | |
81 On a text terminal, if you quit with @kbd{C-g} a second time before | |
82 the first @kbd{C-g} is recognized, you activate the ``emergency | |
83 escape'' feature and return to the shell. @xref{Emergency Escape}. | |
84 | |
85 @cindex NFS and quitting | |
86 There are some situations where you cannot quit. When Emacs is | |
87 waiting for the operating system to do something, quitting is | |
88 impossible unless special pains are taken for the particular system | |
89 call within Emacs where the waiting occurs. We have done this for the | |
90 system calls that users are likely to want to quit from, but it's | |
85423 | 91 possible you will encounter a case not handled. In one very common |
84269 | 92 case---waiting for file input or output using NFS---Emacs itself knows |
93 how to quit, but many NFS implementations simply do not allow user | |
94 programs to stop waiting for NFS when the NFS server is hung. | |
95 | |
96 @cindex aborting recursive edit | |
97 @findex abort-recursive-edit | |
98 @kindex C-] | |
99 Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get | |
100 out of a recursive editing level and cancel the command which invoked | |
101 it. Quitting with @kbd{C-g} does not do this, and could not do this, | |
102 because it is used to cancel a partially typed command @emph{within} the | |
103 recursive editing level. Both operations are useful. For example, if | |
104 you are in a recursive edit and type @kbd{C-u 8} to enter a numeric | |
105 argument, you can cancel that argument with @kbd{C-g} and remain in the | |
106 recursive edit. | |
107 | |
108 @findex keyboard-escape-quit | |
109 @kindex ESC ESC ESC | |
110 The sequence @kbd{@key{ESC} @key{ESC} @key{ESC}} | |
111 (@code{keyboard-escape-quit}) can either quit or abort. (We defined | |
112 it this way because @key{ESC} means ``get out'' in many PC programs.) | |
113 It can cancel a prefix argument, clear a selected region, or get out | |
114 of a Query Replace, like @kbd{C-g}. It can get out of the minibuffer | |
115 or a recursive edit, like @kbd{C-]}. It can also get out of splitting | |
116 the frame into multiple windows, as with @kbd{C-x 1}. One thing it | |
117 cannot do, however, is stop a command that is running. That's because | |
118 it executes as an ordinary command, and Emacs doesn't notice it until | |
119 it is ready for the next command. | |
120 | |
121 @findex top-level | |
98045
7e5d202f9202
(Quitting): Note that top-level exits active minibuffers.
Chong Yidong <cyd@stupidchicken.com>
parents:
93360
diff
changeset
|
122 The command @kbd{M-x top-level} is equivalent to ``enough'' |
7e5d202f9202
(Quitting): Note that top-level exits active minibuffers.
Chong Yidong <cyd@stupidchicken.com>
parents:
93360
diff
changeset
|
123 @kbd{C-]} commands to get you out of all the levels of recursive edits |
7e5d202f9202
(Quitting): Note that top-level exits active minibuffers.
Chong Yidong <cyd@stupidchicken.com>
parents:
93360
diff
changeset
|
124 that you are in; it also exits the minibuffer if it is active. |
7e5d202f9202
(Quitting): Note that top-level exits active minibuffers.
Chong Yidong <cyd@stupidchicken.com>
parents:
93360
diff
changeset
|
125 @kbd{C-]} gets you out one level at a time, but @kbd{M-x top-level} |
7e5d202f9202
(Quitting): Note that top-level exits active minibuffers.
Chong Yidong <cyd@stupidchicken.com>
parents:
93360
diff
changeset
|
126 goes out all levels at once. Both @kbd{C-]} and @kbd{M-x top-level} |
7e5d202f9202
(Quitting): Note that top-level exits active minibuffers.
Chong Yidong <cyd@stupidchicken.com>
parents:
93360
diff
changeset
|
127 are like all other commands, and unlike @kbd{C-g}, in that they take |
7e5d202f9202
(Quitting): Note that top-level exits active minibuffers.
Chong Yidong <cyd@stupidchicken.com>
parents:
93360
diff
changeset
|
128 effect only when Emacs is ready for a command. @kbd{C-]} is an |
7e5d202f9202
(Quitting): Note that top-level exits active minibuffers.
Chong Yidong <cyd@stupidchicken.com>
parents:
93360
diff
changeset
|
129 ordinary key and has its meaning only because of its binding in the |
84269 | 130 keymap. @xref{Recursive Edit}. |
131 | |
103202
9597f2f82406
* trouble.texi (Quitting): Add other undo bindings to table.
Chong Yidong <cyd@stupidchicken.com>
parents:
103151
diff
changeset
|
132 @kbd{C-/} (@code{undo}) is not strictly speaking a way of canceling |
84269 | 133 a command, but you can think of it as canceling a command that already |
103202
9597f2f82406
* trouble.texi (Quitting): Add other undo bindings to table.
Chong Yidong <cyd@stupidchicken.com>
parents:
103151
diff
changeset
|
134 finished executing. @xref{Undo}, for more information about the undo |
9597f2f82406
* trouble.texi (Quitting): Add other undo bindings to table.
Chong Yidong <cyd@stupidchicken.com>
parents:
103151
diff
changeset
|
135 facility. |
84269 | 136 |
137 @node Lossage, Bugs, Quitting, Top | |
138 @section Dealing with Emacs Trouble | |
139 | |
140 This section describes various conditions in which Emacs fails to work | |
141 normally, and how to recognize them and correct them. For a list of | |
142 additional problems you might encounter, see @ref{Bugs and problems, , | |
143 Bugs and problems, efaq, GNU Emacs FAQ}, and the file @file{etc/PROBLEMS} | |
144 in the Emacs distribution. Type @kbd{C-h C-f} to read the FAQ; type | |
103151
58bdec4eecc6
* trouble.texi (Lossage): Use new binding of view-emacs-problems.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
145 @kbd{C-h C-p} to read the @file{PROBLEMS} file. |
84269 | 146 |
147 @menu | |
148 * DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. | |
149 * Stuck Recursive:: `[...]' in mode line around the parentheses. | |
150 * Screen Garbled:: Garbage on the screen. | |
151 * Text Garbled:: Garbage in the text. | |
152 * Memory Full:: How to cope when you run out of memory. | |
153 * After a Crash:: Recovering editing in an Emacs session that crashed. | |
154 * Emergency Escape:: Emergency escape--- | |
155 What to do if Emacs stops responding. | |
156 * Total Frustration:: When you are at your wits' end. | |
157 @end menu | |
158 | |
159 @node DEL Does Not Delete | |
160 @subsection If @key{DEL} Fails to Delete | |
161 @cindex @key{DEL} vs @key{BACKSPACE} | |
162 @cindex @key{BACKSPACE} vs @key{DEL} | |
163 @cindex usual erasure key | |
164 | |
103202
9597f2f82406
* trouble.texi (Quitting): Add other undo bindings to table.
Chong Yidong <cyd@stupidchicken.com>
parents:
103151
diff
changeset
|
165 Every keyboard has a large key, usually labelled @key{Backspace}, |
9597f2f82406
* trouble.texi (Quitting): Add other undo bindings to table.
Chong Yidong <cyd@stupidchicken.com>
parents:
103151
diff
changeset
|
166 which is ordinarily used to erase the last character that you typed. |
9597f2f82406
* trouble.texi (Quitting): Add other undo bindings to table.
Chong Yidong <cyd@stupidchicken.com>
parents:
103151
diff
changeset
|
167 We call this key @dfn{the usual erasure key}. In Emacs, it is |
9597f2f82406
* trouble.texi (Quitting): Add other undo bindings to table.
Chong Yidong <cyd@stupidchicken.com>
parents:
103151
diff
changeset
|
168 supposed to be equivalent to @key{DEL}. |
84269 | 169 |
170 When Emacs starts up on a graphical display, it determines | |
103202
9597f2f82406
* trouble.texi (Quitting): Add other undo bindings to table.
Chong Yidong <cyd@stupidchicken.com>
parents:
103151
diff
changeset
|
171 automatically which key should be @key{DEL}. In some unusual cases, |
84269 | 172 Emacs gets the wrong information from the system. If the usual |
173 erasure key deletes forwards instead of backwards, that is probably | |
103202
9597f2f82406
* trouble.texi (Quitting): Add other undo bindings to table.
Chong Yidong <cyd@stupidchicken.com>
parents:
103151
diff
changeset
|
174 what happened---Emacs ought to be treating the @key{Backspace} key as |
84269 | 175 @key{DEL}, but it isn't. |
176 | |
103202
9597f2f82406
* trouble.texi (Quitting): Add other undo bindings to table.
Chong Yidong <cyd@stupidchicken.com>
parents:
103151
diff
changeset
|
177 Some keyboards also have a @key{Delete} key, which is ordinarily |
105594
93081d78d55b
* trouble.texi (DEL Does Not Delete): Fix typo.
Juanma Barranquero <lekktu@gmail.com>
parents:
103202
diff
changeset
|
178 used to delete forwards. If this key deletes backward in Emacs, that |
93081d78d55b
* trouble.texi (DEL Does Not Delete): Fix typo.
Juanma Barranquero <lekktu@gmail.com>
parents:
103202
diff
changeset
|
179 too suggests Emacs got the wrong information---but in the opposite |
93081d78d55b
* trouble.texi (DEL Does Not Delete): Fix typo.
Juanma Barranquero <lekktu@gmail.com>
parents:
103202
diff
changeset
|
180 sense. |
84269 | 181 |
182 On a text-only terminal, if you find the usual erasure key prompts | |
183 for a Help command, like @kbd{Control-h}, instead of deleting a | |
184 character, it means that key is actually sending the @key{BS} | |
185 character. Emacs ought to be treating @key{BS} as @key{DEL}, but it | |
186 isn't. | |
187 | |
188 In all of those cases, the immediate remedy is the same: use the | |
189 command @kbd{M-x normal-erase-is-backspace-mode}. This toggles | |
190 between the two modes that Emacs supports for handling @key{DEL}, so | |
191 if Emacs starts in the wrong mode, this should switch to the right | |
192 mode. On a text-only terminal, if you want to ask for help when | |
193 @key{BS} is treated as @key{DEL}, use @key{F1}; @kbd{C-?} may also | |
194 work, if it sends character code 127. | |
195 | |
196 @findex normal-erase-is-backspace-mode | |
197 To fix the problem automatically for every Emacs session, you can | |
198 put one of the following lines into your @file{.emacs} file | |
103202
9597f2f82406
* trouble.texi (Quitting): Add other undo bindings to table.
Chong Yidong <cyd@stupidchicken.com>
parents:
103151
diff
changeset
|
199 (@pxref{Init File}). For the first case above, where @key{Backspace} |
84269 | 200 deletes forwards instead of backwards, use this line to make |
103202
9597f2f82406
* trouble.texi (Quitting): Add other undo bindings to table.
Chong Yidong <cyd@stupidchicken.com>
parents:
103151
diff
changeset
|
201 @key{Backspace} act as @key{DEL} (resulting in behavior compatible |
84269 | 202 with Emacs 20 and previous versions): |
203 | |
204 @lisp | |
205 (normal-erase-is-backspace-mode 0) | |
206 @end lisp | |
207 | |
208 @noindent | |
103202
9597f2f82406
* trouble.texi (Quitting): Add other undo bindings to table.
Chong Yidong <cyd@stupidchicken.com>
parents:
103151
diff
changeset
|
209 For the other two cases, use this line: |
84269 | 210 |
211 @lisp | |
212 (normal-erase-is-backspace-mode 1) | |
213 @end lisp | |
214 | |
215 @vindex normal-erase-is-backspace | |
216 Another way to fix the problem for every Emacs session is to | |
217 customize the variable @code{normal-erase-is-backspace}: the value | |
218 @code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is | |
219 @key{DEL}, and @code{nil} specifies the other mode. @xref{Easy | |
220 Customization}. | |
221 | |
222 @node Stuck Recursive | |
223 @subsection Recursive Editing Levels | |
224 | |
225 Recursive editing levels are important and useful features of Emacs, but | |
226 they can seem like malfunctions if you do not understand them. | |
227 | |
228 If the mode line has square brackets @samp{[@dots{}]} around the parentheses | |
229 that contain the names of the major and minor modes, you have entered a | |
230 recursive editing level. If you did not do this on purpose, or if you | |
231 don't understand what that means, you should just get out of the recursive | |
232 editing level. To do so, type @kbd{M-x top-level}. This is called getting | |
233 back to top level. @xref{Recursive Edit}. | |
234 | |
235 @node Screen Garbled | |
236 @subsection Garbage on the Screen | |
237 | |
238 If the text on a text terminal looks wrong, the first thing to do is | |
239 see whether it is wrong in the buffer. Type @kbd{C-l} to redisplay | |
240 the entire screen. If the screen appears correct after this, the | |
241 problem was entirely in the previous screen update. (Otherwise, see | |
242 the following section.) | |
243 | |
244 Display updating problems often result from an incorrect terminfo | |
245 entry for the terminal you are using. The file @file{etc/TERMS} in | |
246 the Emacs distribution gives the fixes for known problems of this | |
247 sort. @file{INSTALL} contains general advice for these problems in | |
248 one of its sections. To investigate the possibility that you have | |
249 this sort of problem, try Emacs on another terminal made by a | |
250 different manufacturer. If problems happen frequently on one kind of | |
251 terminal but not another kind, it is likely to be a bad terminfo entry, | |
252 though it could also be due to a bug in Emacs that appears for | |
253 terminals that have or that lack specific features. | |
254 | |
255 @node Text Garbled | |
256 @subsection Garbage in the Text | |
257 | |
258 If @kbd{C-l} shows that the text is wrong, first type @kbd{C-h l} to | |
259 see what commands you typed to produce the observed results. Then try | |
260 undoing the changes step by step using @kbd{C-x u}, until it gets back | |
261 to a state you consider correct. | |
262 | |
263 If a large portion of text appears to be missing at the beginning or | |
264 end of the buffer, check for the word @samp{Narrow} in the mode line. | |
265 If it appears, the text you don't see is probably still present, but | |
266 temporarily off-limits. To make it accessible again, type @kbd{C-x n | |
267 w}. @xref{Narrowing}. | |
268 | |
269 @node Memory Full | |
270 @subsection Running out of Memory | |
271 @cindex memory full | |
272 @cindex out of memory | |
273 | |
274 If you get the error message @samp{Virtual memory exceeded}, save | |
275 your modified buffers with @kbd{C-x s}. This method of saving them | |
276 has the smallest need for additional memory. Emacs keeps a reserve of | |
277 memory which it makes available when this error happens; that should | |
278 be enough to enable @kbd{C-x s} to complete its work. When the | |
279 reserve has been used, @samp{!MEM FULL!} appears at the beginning of | |
280 the mode line, indicating there is no more reserve. | |
281 | |
282 Once you have saved your modified buffers, you can exit this Emacs | |
283 session and start another, or you can use @kbd{M-x kill-some-buffers} | |
284 to free space in the current Emacs job. If this frees up sufficient | |
285 space, Emacs will refill its memory reserve, and @samp{!MEM FULL!} | |
286 will disappear from the mode line. That means you can safely go on | |
287 editing in the same Emacs session. | |
288 | |
289 Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run | |
290 out of memory, because the buffer menu needs a fair amount of memory | |
291 itself, and the reserve supply may not be enough. | |
292 | |
293 @node After a Crash | |
294 @subsection Recovery After a Crash | |
295 | |
296 If Emacs or the computer crashes, you can recover the files you were | |
297 editing at the time of the crash from their auto-save files. To do | |
298 this, start Emacs again and type the command @kbd{M-x recover-session}. | |
299 | |
300 This command initially displays a buffer which lists interrupted | |
301 session files, each with its date. You must choose which session to | |
302 recover from. Typically the one you want is the most recent one. Move | |
303 point to the one you choose, and type @kbd{C-c C-c}. | |
304 | |
305 Then @code{recover-session} considers each of the files that you | |
306 were editing during that session; for each such file, it asks whether | |
307 to recover that file. If you answer @kbd{y} for a file, it shows the | |
308 dates of that file and its auto-save file, then asks once again | |
309 whether to recover that file. For the second question, you must | |
310 confirm with @kbd{yes}. If you do, Emacs visits the file but gets the | |
311 text from the auto-save file. | |
312 | |
313 When @code{recover-session} is done, the files you've chosen to | |
314 recover are present in Emacs buffers. You should then save them. Only | |
315 this---saving them---updates the files themselves. | |
316 | |
317 As a last resort, if you had buffers with content which were not | |
318 associated with any files, or if the autosave was not recent enough to | |
319 have recorded important changes, you can use the | |
320 @file{etc/emacs-buffer.gdb} script with GDB (the GNU Debugger) to | |
321 retrieve them from a core dump--provided that a core dump was saved, | |
322 and that the Emacs executable was not stripped of its debugging | |
323 symbols. | |
324 | |
325 As soon as you get the core dump, rename it to another name such as | |
326 @file{core.emacs}, so that another crash won't overwrite it. | |
327 | |
328 To use this script, run @code{gdb} with the file name of your Emacs | |
329 executable and the file name of the core dump, e.g. @samp{gdb | |
330 /usr/bin/emacs core.emacs}. At the @code{(gdb)} prompt, load the | |
331 recovery script: @samp{source /usr/src/emacs/etc/emacs-buffer.gdb}. | |
332 Then type the command @code{ybuffer-list} to see which buffers are | |
333 available. For each buffer, it lists a buffer number. To save a | |
334 buffer, use @code{ysave-buffer}; you specify the buffer number, and | |
335 the file name to write that buffer into. You should use a file name | |
336 which does not already exist; if the file does exist, the script does | |
337 not make a backup of its old contents. | |
338 | |
339 @node Emergency Escape | |
340 @subsection Emergency Escape | |
341 | |
342 On text-only terminals, the @dfn{emergency escape} feature suspends | |
343 Emacs immediately if you type @kbd{C-g} a second time before Emacs can | |
344 actually respond to the first one by quitting. This is so you can | |
345 always get out of GNU Emacs no matter how badly it might be hung. | |
346 When things are working properly, Emacs recognizes and handles the | |
347 first @kbd{C-g} so fast that the second one won't trigger emergency | |
348 escape. However, if some problem prevents Emacs from handling the | |
349 first @kbd{C-g} properly, then the second one will get you back to the | |
350 shell. | |
351 | |
352 When you resume Emacs after a suspension caused by emergency escape, | |
353 it asks two questions before going back to what it had been doing: | |
354 | |
355 @example | |
356 Auto-save? (y or n) | |
357 Abort (and dump core)? (y or n) | |
358 @end example | |
359 | |
360 @noindent | |
361 Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}. | |
362 | |
363 Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of | |
364 all modified buffers in which auto-saving is enabled. Saying @kbd{n} | |
365 skips this. | |
366 | |
367 Saying @kbd{y} to @samp{Abort (and dump core)?} causes Emacs to | |
368 crash, dumping core. This is to enable a wizard to figure out why | |
369 Emacs was failing to quit in the first place. Execution does not | |
370 continue after a core dump. | |
371 | |
372 If you answer this question @kbd{n}, Emacs execution resumes. With | |
373 luck, Emacs will ultimately do the requested quit. If not, each | |
374 subsequent @kbd{C-g} invokes emergency escape again. | |
375 | |
376 If Emacs is not really hung, just slow, you may invoke the double | |
377 @kbd{C-g} feature without really meaning to. Then just resume and | |
378 answer @kbd{n} to both questions, and you will get back to the former | |
379 state. The quit you requested will happen by and by. | |
380 | |
381 Emergency escape is active only for text terminals. On graphical | |
382 displays, you can use the mouse to kill Emacs or switch to another | |
383 program. | |
384 | |
385 On MS-DOS, you must type @kbd{C-@key{BREAK}} (twice) to cause | |
386 emergency escape---but there are cases where it won't work, when | |
387 system call hangs or when Emacs is stuck in a tight loop in C code. | |
388 | |
389 @node Total Frustration | |
390 @subsection Help for Total Frustration | |
391 @cindex Eliza | |
392 @cindex doctor | |
393 | |
394 If using Emacs (or something else) becomes terribly frustrating and none | |
395 of the techniques described above solve the problem, Emacs can still help | |
396 you. | |
397 | |
398 First, if the Emacs you are using is not responding to commands, type | |
399 @kbd{C-g C-g} to get out of it and then start a new one. | |
400 | |
401 @findex doctor | |
402 Second, type @kbd{M-x doctor @key{RET}}. | |
403 | |
404 The Emacs psychotherapist will help you feel better. Each time you | |
405 say something to the psychotherapist, you must end it by typing | |
406 @key{RET} @key{RET}. This indicates you are finished typing. | |
407 | |
408 @node Bugs, Contributing, Lossage, Top | |
409 @section Reporting Bugs | |
410 | |
411 @cindex bugs | |
110348
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
412 If you think you have found a bug in Emacs, please report it. We |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
413 cannot promise to fix it, or always to agree that it is a bug, but we |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
414 certainly want to hear about it. The same applies for new features |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
415 you would like to see added. The following sections will help you to |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
416 construct an effective bug report. |
84269 | 417 |
418 @menu | |
110348
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
419 * Known Problems:: How to read about known problems and bugs. |
109262
51ddcf320fe4
Untabify doc/emacs/*.texi files.
Glenn Morris <rgm@gnu.org>
parents:
107929
diff
changeset
|
420 * Criteria: Bug Criteria. Have you really found a bug? |
51ddcf320fe4
Untabify doc/emacs/*.texi files.
Glenn Morris <rgm@gnu.org>
parents:
107929
diff
changeset
|
421 * Understanding Bug Reporting:: How to report a bug effectively. |
51ddcf320fe4
Untabify doc/emacs/*.texi files.
Glenn Morris <rgm@gnu.org>
parents:
107929
diff
changeset
|
422 * Checklist:: Steps to follow for a good bug report. |
51ddcf320fe4
Untabify doc/emacs/*.texi files.
Glenn Morris <rgm@gnu.org>
parents:
107929
diff
changeset
|
423 * Sending Patches:: How to send a patch for GNU Emacs. |
84269 | 424 @end menu |
425 | |
110348
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
426 @node Known Problems |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
427 @subsection Reading Existing Bug Reports and Known Problems |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
428 |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
429 Before reporting a bug, if at all possible please check to see if it |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
430 is already known about. Indeed, it may already have been fixed in a |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
431 later release of Emacs, or in the development version. Here is a list |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
432 of the main places you can read about known issues: |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
433 |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
434 @itemize |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
435 @item |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
436 The @file{etc/PROBLEMS} file in the Emacs distribution; type @kbd{C-h |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
437 C-p} to read it. This file contains a list of particularly well-known |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
438 issues that have been encountered in compiling, installing and running |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
439 Emacs. Often, there are suggestions for workarounds and solutions. |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
440 |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
441 @item |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
442 Some additional user-level problems can be found in @ref{Bugs and |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
443 problems, , Bugs and problems, efaq, GNU Emacs FAQ}. |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
444 |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
445 @item |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
446 The @samp{bug-gnu-emacs} mailing list (also available as the newsgroup |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
447 @samp{gnu.emacs.bug}). This is where you will find most Emacs bug |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
448 reports. You can read the list archives at |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
449 @url{http://lists.gnu.org/mailman/listinfo/bug-gnu-emacs}. If you |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
450 like, you can also subscribe to the list. Be aware that the sole |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
451 purpose of this list is to provide the Emacs maintainers with |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
452 information about bugs and feature requests. Reports may contain |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
453 fairly large amounts of data; spectators should not complain about |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
454 this. |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
455 |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
456 @item |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
457 The bug tracker at @url{http://debbugs.gnu.org}. From early 2008, |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
458 reports from the @samp{bug-gnu-emacs} list have been sent here. The |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
459 tracker contains the same information as the mailing list, just in a |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
460 different format. You may prefer to browse and read reports using the |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
461 tracker. |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
462 |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
463 @item |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
464 The @samp{emacs-pretest-bug} mailing list. This list is no longer |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
465 used, and is mainly of historical interest. At one time, it was used |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
466 for bug reports in development (i.e., not yet released) versions of |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
467 Emacs. You can read the archives for 2003 to mid 2007 at |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
468 @url{http://lists.gnu.org/archive/html/emacs-pretest-bug/}. From |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
469 late 2007 to mid 2008, the address was an alias for the |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
470 @samp{emacs-devel} mailing list. From mid 2008 onwards, it has been |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
471 an alias for @samp{bug-gnu-emacs}. |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
472 |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
473 @item |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
474 The @samp{emacs-devel} mailing list. Sometimes people report bugs to |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
475 this mailing list. This is not the main purpose of the list, however, |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
476 and it is much better to send bug reports to the bug list. You should |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
477 not feel obliged to read this list before reporting a bug. |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
478 |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
479 @end itemize |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
480 |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
481 |
84269 | 482 @node Bug Criteria |
483 @subsection When Is There a Bug | |
484 | |
485 If Emacs accesses an invalid memory location (``segmentation | |
486 fault''), or exits with an operating system error message that | |
487 indicates a problem in the program (as opposed to something like | |
488 ``disk full''), then it is certainly a bug. | |
489 | |
490 If Emacs updates the display in a way that does not correspond to what is | |
491 in the buffer, then it is certainly a bug. If a command seems to do the | |
492 wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a | |
493 case of incorrect display updating. | |
494 | |
495 Taking forever to complete a command can be a bug, but you must make | |
496 certain that it was really Emacs's fault. Some commands simply take a | |
497 long time. Type @kbd{C-g} (@kbd{C-@key{BREAK}} on MS-DOS) and then @kbd{C-h l} | |
498 to see whether the input Emacs received was what you intended to type; | |
499 if the input was such that you @emph{know} it should have been processed | |
500 quickly, report a bug. If you don't know whether the command should | |
501 take a long time, find out by looking in the manual or by asking for | |
502 assistance. | |
503 | |
504 If a command you are familiar with causes an Emacs error message in a | |
505 case where its usual definition ought to be reasonable, it is probably a | |
506 bug. | |
507 | |
508 If a command does the wrong thing, that is a bug. But be sure you know | |
509 for certain what it ought to have done. If you aren't familiar with the | |
510 command, or don't know for certain how the command is supposed to work, | |
511 then it might actually be working right. Rather than jumping to | |
512 conclusions, show the problem to someone who knows for certain. | |
513 | |
514 Finally, a command's intended definition may not be the best | |
515 possible definition for editing with. This is a very important sort | |
516 of problem, but it is also a matter of judgment. Also, it is easy to | |
517 come to such a conclusion out of ignorance of some of the existing | |
518 features. It is probably best not to complain about such a problem | |
519 until you have checked the documentation in the usual ways, feel | |
520 confident that you understand it, and know for certain that what you | |
521 want is not available. Ask other Emacs users, too. If you are not | |
522 sure what the command is supposed to do after a careful reading of the | |
523 manual, check the index and glossary for any terms that may be | |
524 unclear. | |
525 | |
526 If after careful rereading of the manual you still do not understand | |
527 what the command should do, that indicates a bug in the manual, which | |
528 you should report. The manual's job is to make everything clear to | |
529 people who are not Emacs experts---including you. It is just as | |
530 important to report documentation bugs as program bugs. | |
531 | |
532 If the on-line documentation string of a function or variable disagrees | |
533 with the manual, one of them must be wrong; that is a bug. | |
534 | |
535 @node Understanding Bug Reporting | |
536 @subsection Understanding Bug Reporting | |
537 | |
538 @findex emacs-version | |
539 When you decide that there is a bug, it is important to report it and to | |
540 report it in a way which is useful. What is most useful is an exact | |
541 description of what commands you type, starting with the shell command to | |
542 run Emacs, until the problem happens. | |
543 | |
544 The most important principle in reporting a bug is to report | |
545 @emph{facts}. Hypotheses and verbal descriptions are no substitute for | |
546 the detailed raw data. Reporting the facts is straightforward, but many | |
547 people strain to posit explanations and report them instead of the | |
548 facts. If the explanations are based on guesses about how Emacs is | |
549 implemented, they will be useless; meanwhile, lacking the facts, we will | |
550 have no real information about the bug. | |
551 | |
552 For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh | |
553 @key{RET}}, visiting a file which (you know) happens to be rather | |
554 large, and Emacs displays @samp{I feel pretty today}. The best way to | |
555 report the bug is with a sentence like the preceding one, because it | |
556 gives all the facts. | |
557 | |
558 A bad way would be to assume that the problem is due to the size of | |
559 the file and say, ``I visited a large file, and Emacs displayed @samp{I | |
560 feel pretty today}.'' This is what we mean by ``guessing | |
561 explanations.'' The problem is just as likely to be due to the fact | |
562 that there is a @samp{z} in the file name. If this is so, then when we | |
563 got your report, we would try out the problem with some ``large file,'' | |
564 probably with no @samp{z} in its name, and not see any problem. There | |
565 is no way in the world that we could guess that we should try visiting a | |
566 file with a @samp{z} in its name. | |
567 | |
568 Alternatively, the problem might be due to the fact that the file starts | |
569 with exactly 25 spaces. For this reason, you should make sure that you | |
570 inform us of the exact contents of any file that is needed to reproduce the | |
571 bug. What if the problem only occurs when you have typed the @kbd{C-x C-a} | |
572 command previously? This is why we ask you to give the exact sequence of | |
573 characters you typed since starting the Emacs session. | |
574 | |
575 You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless | |
576 you @emph{know} that it makes no difference which visiting command is used. | |
577 Similarly, rather than saying ``if I have three characters on the line,'' | |
578 say ``after I type @kbd{@key{RET} A B C @key{RET} C-p},'' if that is | |
579 the way you entered the text. | |
580 | |
581 So please don't guess any explanations when you report a bug. If you | |
582 want to actually @emph{debug} the problem, and report explanations that | |
583 are more than guesses, that is useful---but please include the facts as | |
584 well. | |
585 | |
586 @node Checklist | |
587 @subsection Checklist for Bug Reports | |
588 | |
589 @cindex reporting bugs | |
110348
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
590 |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
591 Before reporting a bug, first try to see if the problem has already |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
592 been reported (@pxref{Known Problems}). |
84269 | 593 |
110348
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
594 If you are able to, try the latest release of Emacs to see if the |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
595 problem has already been fixed. Even better is to try the latest |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
596 development version. We recognize that this is not easy for some |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
597 people, so do not feel that you absolutely must do this before making |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
598 a report. |
84269 | 599 |
600 @findex report-emacs-bug | |
110348
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
601 The best way to write a bug report for Emacs is to use the command |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
602 @kbd{M-x report-emacs-bug}. This sets up a mail buffer |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
603 (@pxref{Sending Mail}) and automatically inserts @emph{some} of the |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
604 essential information. However, it cannot supply all the necessary |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
605 information; you should still read and follow the guidelines below, so |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
606 you can enter the other crucial information by hand before you send |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
607 the message. You may feel that some of the information inserted by |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
608 @kbd{M-x report-emacs-bug} is not relevant, but unless you are |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
609 absolutely sure it is best to leave it, so that the developers can |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
610 decide for themselves. |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
611 |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
612 When you have finished writing your report, type @kbd{C-c C-c} and it |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
613 will be sent to the Emacs maintainers at @email{bug-gnu-emacs@@gnu.org}. |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
614 (If you want to suggest an improvement or new feature, use the same |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
615 address.) If you cannot send mail from inside Emacs, you can copy the |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
616 text of your report to your normal mail client and send it to that |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
617 address. Or you can simply send an email to that address describing |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
618 the problem. |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
619 |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
620 Your report will be sent to the @samp{bug-gnu-emacs} mailing list, and |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
621 stored in the tracker at @url{http://debbugs.gnu.org}. Please try to |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
622 include a valid reply email address, in case we need to ask you for |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
623 more information about your report. Submissions are moderated, so |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
624 there may be a delay before your report appears. |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
625 |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
626 You do not need to know how the @url{http://debbugs.gnu.org} bug |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
627 tracker works in order to report a bug, but if you want to, you can |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
628 read the tracker's online documentation to see the various features |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
629 you can use. |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
630 |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
631 All mail sent to the @samp{bug-gnu-emacs} mailing list is also |
111931
bcd9920c3c81
* doc/emacs/trouble.texi (Checklist): Fix typo in newsgroup name.
Glenn Morris <rgm@gnu.org>
parents:
110348
diff
changeset
|
632 gatewayed to the @samp{gnu.emacs.bug} newsgroup. The reverse is also |
112048
916ee043dbcf
* doc/emacs/trouble.texi (Checklist): Mention not replying via news either.
Glenn Morris <rgm@gnu.org>
parents:
111931
diff
changeset
|
633 true, but we ask you not to post bug reports (or replies) via the |
916ee043dbcf
* doc/emacs/trouble.texi (Checklist): Mention not replying via news either.
Glenn Morris <rgm@gnu.org>
parents:
111931
diff
changeset
|
634 newsgroup. It can make it much harder to contact you if we need to ask |
916ee043dbcf
* doc/emacs/trouble.texi (Checklist): Mention not replying via news either.
Glenn Morris <rgm@gnu.org>
parents:
111931
diff
changeset
|
635 for more information, and it does not integrate well with the bug |
916ee043dbcf
* doc/emacs/trouble.texi (Checklist): Mention not replying via news either.
Glenn Morris <rgm@gnu.org>
parents:
111931
diff
changeset
|
636 tracker. |
110348
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
637 |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
638 If your data is more than 500,000 bytes, please don't include it |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
639 directly in the bug report; instead, offer to send it on request, or |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
640 make it available by ftp and say where. |
84269 | 641 |
642 To enable maintainers to investigate a bug, your report | |
643 should include all these things: | |
644 | |
645 @itemize @bullet | |
646 @item | |
110348
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
647 The version number of Emacs. Without this, we won't know whether there is any |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
648 point in looking for the bug in the current version of GNU Emacs. |
84269 | 649 |
110348
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
650 @kbd{M-x report-emacs-bug} includes this information automatically, |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
651 but if you are not using that command for your report you can get the |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
652 version number by typing @kbd{M-x emacs-version @key{RET}}. If that |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
653 command does not work, you probably have something other than GNU |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
654 Emacs, so you will have to report the bug somewhere else. |
84269 | 655 |
656 @item | |
657 The type of machine you are using, and the operating system name and | |
110348
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
658 version number (again, automatically included by @kbd{M-x |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
659 report-emacs-bug}). @kbd{M-x emacs-version @key{RET}} provides this |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
660 information too. Copy its output from the @samp{*Messages*} buffer, |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
661 so that you get it all and get it accurately. |
84269 | 662 |
663 @item | |
664 The operands given to the @code{configure} command when Emacs was | |
110348
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
665 installed (automatically included by @kbd{M-x report-emacs-bug}). |
84269 | 666 |
667 @item | |
668 A complete list of any modifications you have made to the Emacs source. | |
669 (We may not have time to investigate the bug unless it happens in an | |
670 unmodified Emacs. But if you've made modifications and you don't tell | |
671 us, you are sending us on a wild goose chase.) | |
672 | |
673 Be precise about these changes. A description in English is not | |
674 enough---send a context diff for them. | |
675 | |
676 Adding files of your own, or porting to another machine, is a | |
677 modification of the source. | |
678 | |
679 @item | |
680 Details of any other deviations from the standard procedure for installing | |
681 GNU Emacs. | |
682 | |
683 @item | |
684 The complete text of any files needed to reproduce the bug. | |
685 | |
686 If you can tell us a way to cause the problem without visiting any files, | |
687 please do so. This makes it much easier to debug. If you do need files, | |
688 make sure you arrange for us to see their exact contents. For example, it | |
689 can matter whether there are spaces at the ends of lines, or a | |
690 newline after the last line in the buffer (nothing ought to care whether | |
691 the last line is terminated, but try telling the bugs that). | |
692 | |
693 @item | |
694 The precise commands we need to type to reproduce the bug. | |
110348
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
695 If at all possible, give a full recipe for an Emacs started with the |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
696 @samp{-Q} option (@pxref{Initial Options}). This bypasses your |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
697 @file{.emacs} customizations. |
84269 | 698 |
699 @findex open-dribble-file | |
700 @cindex dribble file | |
701 @cindex logging keystrokes | |
110348
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
702 One way to record the input to Emacs precisely is to write a dribble |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
703 file. To start the file, execute the Lisp expression |
84269 | 704 |
705 @example | |
706 (open-dribble-file "~/dribble") | |
707 @end example | |
708 | |
709 @noindent | |
710 using @kbd{M-:} or from the @samp{*scratch*} buffer just after | |
711 starting Emacs. From then on, Emacs copies all your input to the | |
712 specified dribble file until the Emacs process is killed. | |
713 | |
714 @item | |
715 @findex open-termscript | |
716 @cindex termscript file | |
717 @cindex @env{TERM} environment variable | |
718 For possible display bugs, the terminal type (the value of environment | |
719 variable @env{TERM}), the complete termcap entry for the terminal from | |
720 @file{/etc/termcap} (since that file is not identical on all machines), | |
721 and the output that Emacs actually sent to the terminal. | |
722 | |
723 The way to collect the terminal output is to execute the Lisp expression | |
724 | |
725 @example | |
726 (open-termscript "~/termscript") | |
727 @end example | |
728 | |
729 @noindent | |
730 using @kbd{M-:} or from the @samp{*scratch*} buffer just after | |
731 starting Emacs. From then on, Emacs copies all terminal output to the | |
732 specified termscript file as well, until the Emacs process is killed. | |
733 If the problem happens when Emacs starts up, put this expression into | |
734 your @file{.emacs} file so that the termscript file will be open when | |
735 Emacs displays the screen for the first time. | |
736 | |
737 Be warned: it is often difficult, and sometimes impossible, to fix a | |
738 terminal-dependent bug without access to a terminal of the type that | |
739 stimulates the bug. | |
740 | |
741 @item | |
742 If non-@acronym{ASCII} text or internationalization is relevant, the locale that | |
743 was current when you started Emacs. On GNU/Linux and Unix systems, or | |
744 if you use a Posix-style shell such as Bash, you can use this shell | |
745 command to view the relevant values: | |
746 | |
747 @smallexample | |
748 echo LC_ALL=$LC_ALL LC_COLLATE=$LC_COLLATE LC_CTYPE=$LC_CTYPE \ | |
749 LC_MESSAGES=$LC_MESSAGES LC_TIME=$LC_TIME LANG=$LANG | |
750 @end smallexample | |
751 | |
752 Alternatively, use the @command{locale} command, if your system has it, | |
753 to display your locale settings. | |
754 | |
755 You can use the @kbd{M-!} command to execute these commands from | |
756 Emacs, and then copy the output from the @samp{*Messages*} buffer into | |
757 the bug report. Alternatively, @kbd{M-x getenv @key{RET} LC_ALL | |
758 @key{RET}} will display the value of @code{LC_ALL} in the echo area, and | |
759 you can copy its output from the @samp{*Messages*} buffer. | |
760 | |
761 @item | |
762 A description of what behavior you observe that you believe is | |
763 incorrect. For example, ``The Emacs process gets a fatal signal,'' or, | |
764 ``The resulting text is as follows, which I think is wrong.'' | |
765 | |
766 Of course, if the bug is that Emacs gets a fatal signal, then one can't | |
767 miss it. But if the bug is incorrect text, the maintainer might fail to | |
768 notice what is wrong. Why leave it to chance? | |
769 | |
770 Even if the problem you experience is a fatal signal, you should still | |
771 say so explicitly. Suppose something strange is going on, such as, your | |
772 copy of the source is out of sync, or you have encountered a bug in the | |
773 C library on your system. (This has happened!) Your copy might crash | |
774 and the copy here might not. If you @emph{said} to expect a crash, then | |
775 when Emacs here fails to crash, we would know that the bug was not | |
776 happening. If you don't say to expect a crash, then we would not know | |
777 whether the bug was happening---we would not be able to draw any | |
778 conclusion from our observations. | |
779 | |
780 @item | |
781 If the bug is that the Emacs Manual or the Emacs Lisp Reference Manual | |
782 fails to describe the actual behavior of Emacs, or that the text is | |
783 confusing, copy in the text from the online manual which you think is | |
784 at fault. If the section is small, just the section name is enough. | |
785 | |
786 @item | |
787 If the manifestation of the bug is an Emacs error message, it is | |
788 important to report the precise text of the error message, and a | |
789 backtrace showing how the Lisp program in Emacs arrived at the error. | |
790 | |
791 To get the error message text accurately, copy it from the | |
792 @samp{*Messages*} buffer into the bug report. Copy all of it, not just | |
793 part. | |
794 | |
795 @findex toggle-debug-on-error | |
796 @pindex Edebug | |
797 To make a backtrace for the error, use @kbd{M-x toggle-debug-on-error} | |
798 before the error happens (that is to say, you must give that command | |
799 and then make the bug happen). This causes the error to start the Lisp | |
800 debugger, which shows you a backtrace. Copy the text of the | |
801 debugger's backtrace into the bug report. @xref{Debugger,, The Lisp | |
802 Debugger, elisp, the Emacs Lisp Reference Manual}, for information on | |
803 debugging Emacs Lisp programs with the Edebug package. | |
804 | |
805 This use of the debugger is possible only if you know how to make the | |
806 bug happen again. If you can't make it happen again, at least copy | |
807 the whole error message. | |
808 | |
112076
9b34017f06c6
Fix bug #7667: mention debug-on-quit in the manual.
Eli Zaretskii <eliz@gnu.org>
parents:
112048
diff
changeset
|
809 @vindex debug-on-quit |
9b34017f06c6
Fix bug #7667: mention debug-on-quit in the manual.
Eli Zaretskii <eliz@gnu.org>
parents:
112048
diff
changeset
|
810 If Emacs appears to be stuck in an infinite loop or in a very long |
9b34017f06c6
Fix bug #7667: mention debug-on-quit in the manual.
Eli Zaretskii <eliz@gnu.org>
parents:
112048
diff
changeset
|
811 operation, typing @kbd{C-g} with the variable @code{debug-on-quit} |
9b34017f06c6
Fix bug #7667: mention debug-on-quit in the manual.
Eli Zaretskii <eliz@gnu.org>
parents:
112048
diff
changeset
|
812 non-@code{nil} will start the Lisp debugger and show a backtrace. |
9b34017f06c6
Fix bug #7667: mention debug-on-quit in the manual.
Eli Zaretskii <eliz@gnu.org>
parents:
112048
diff
changeset
|
813 This backtrace is useful for debugging such long loops, so if you can |
9b34017f06c6
Fix bug #7667: mention debug-on-quit in the manual.
Eli Zaretskii <eliz@gnu.org>
parents:
112048
diff
changeset
|
814 produce it, copy it into the bug report. |
9b34017f06c6
Fix bug #7667: mention debug-on-quit in the manual.
Eli Zaretskii <eliz@gnu.org>
parents:
112048
diff
changeset
|
815 |
84269 | 816 @item |
817 Check whether any programs you have loaded into the Lisp world, | |
818 including your @file{.emacs} file, set any variables that may affect the | |
819 functioning of Emacs. Also, see whether the problem happens in a | |
820 freshly started Emacs without loading your @file{.emacs} file (start | |
110348
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
821 Emacs with the @code{-Q} switch to prevent loading the init files). If |
84269 | 822 the problem does @emph{not} occur then, you must report the precise |
823 contents of any programs that you must load into the Lisp world in order | |
824 to cause the problem to occur. | |
825 | |
826 @item | |
827 If the problem does depend on an init file or other Lisp programs that | |
828 are not part of the standard Emacs system, then you should make sure it | |
829 is not a bug in those programs by complaining to their maintainers | |
830 first. After they verify that they are using Emacs in a way that is | |
831 supposed to work, they should report the bug. | |
832 | |
833 @item | |
834 If you wish to mention something in the GNU Emacs source, show the line | |
835 of code with a few lines of context. Don't just give a line number. | |
836 | |
837 The line numbers in the development sources don't match those in your | |
838 sources. It would take extra work for the maintainers to determine what | |
839 code is in your version at a given line number, and we could not be | |
840 certain. | |
841 | |
842 @item | |
843 Additional information from a C debugger such as GDB might enable | |
844 someone to find a problem on a machine which he does not have available. | |
845 If you don't know how to use GDB, please read the GDB manual---it is not | |
846 very long, and using GDB is easy. You can find the GDB distribution, | |
847 including the GDB manual in online form, in most of the same places you | |
848 can find the Emacs distribution. To run Emacs under GDB, you should | |
849 switch to the @file{src} subdirectory in which Emacs was compiled, then | |
850 do @samp{gdb emacs}. It is important for the directory @file{src} to be | |
851 current so that GDB will read the @file{.gdbinit} file in this | |
852 directory. | |
853 | |
854 However, you need to think when you collect the additional information | |
855 if you want it to show what causes the bug. | |
856 | |
857 @cindex backtrace for bug reports | |
858 For example, many people send just a backtrace, but that is not very | |
859 useful by itself. A simple backtrace with arguments often conveys | |
860 little about what is happening inside GNU Emacs, because most of the | |
861 arguments listed in the backtrace are pointers to Lisp objects. The | |
862 numeric values of these pointers have no significance whatever; all that | |
863 matters is the contents of the objects they point to (and most of the | |
864 contents are themselves pointers). | |
865 | |
866 @findex debug_print | |
867 To provide useful information, you need to show the values of Lisp | |
868 objects in Lisp notation. Do this for each variable which is a Lisp | |
869 object, in several stack frames near the bottom of the stack. Look at | |
870 the source to see which variables are Lisp objects, because the debugger | |
871 thinks of them as integers. | |
872 | |
873 To show a variable's value in Lisp syntax, first print its value, then | |
874 use the user-defined GDB command @code{pr} to print the Lisp object in | |
875 Lisp syntax. (If you must use another debugger, call the function | |
876 @code{debug_print} with the object as an argument.) The @code{pr} | |
877 command is defined by the file @file{.gdbinit}, and it works only if you | |
878 are debugging a running process (not with a core dump). | |
879 | |
880 To make Lisp errors stop Emacs and return to GDB, put a breakpoint at | |
881 @code{Fsignal}. | |
882 | |
883 For a short listing of Lisp functions running, type the GDB | |
884 command @code{xbacktrace}. | |
885 | |
886 The file @file{.gdbinit} defines several other commands that are useful | |
887 for examining the data types and contents of Lisp objects. Their names | |
888 begin with @samp{x}. These commands work at a lower level than | |
889 @code{pr}, and are less convenient, but they may work even when | |
890 @code{pr} does not, such as when debugging a core dump or when Emacs has | |
891 had a fatal signal. | |
892 | |
893 @cindex debugging Emacs, tricks and techniques | |
894 More detailed advice and other useful techniques for debugging Emacs | |
895 are available in the file @file{etc/DEBUG} in the Emacs distribution. | |
896 That file also includes instructions for investigating problems | |
897 whereby Emacs stops responding (many people assume that Emacs is | |
898 ``hung,'' whereas in fact it might be in an infinite loop). | |
899 | |
900 To find the file @file{etc/DEBUG} in your Emacs installation, use the | |
901 directory name stored in the variable @code{data-directory}. | |
902 @end itemize | |
903 | |
904 Here are some things that are not necessary in a bug report: | |
905 | |
906 @itemize @bullet | |
907 @item | |
908 A description of the envelope of the bug---this is not necessary for a | |
909 reproducible bug. | |
910 | |
911 Often people who encounter a bug spend a lot of time investigating | |
912 which changes to the input file will make the bug go away and which | |
913 changes will not affect it. | |
914 | |
915 This is often time-consuming and not very useful, because the way we | |
916 will find the bug is by running a single example under the debugger | |
917 with breakpoints, not by pure deduction from a series of examples. | |
918 You might as well save time by not searching for additional examples. | |
919 It is better to send the bug report right away, go back to editing, | |
920 and find another bug to report. | |
921 | |
922 Of course, if you can find a simpler example to report @emph{instead} of | |
923 the original one, that is a convenience. Errors in the output will be | |
924 easier to spot, running under the debugger will take less time, etc. | |
925 | |
926 However, simplification is not vital; if you can't do this or don't have | |
927 time to try, please report the bug with your original test case. | |
928 | |
929 @item | |
930 A core dump file. | |
931 | |
932 Debugging the core dump might be useful, but it can only be done on | |
933 your machine, with your Emacs executable. Therefore, sending the core | |
934 dump file to the Emacs maintainers won't be useful. Above all, don't | |
935 include the core file in an email bug report! Such a large message | |
936 can be extremely inconvenient. | |
937 | |
938 @item | |
939 A system-call trace of Emacs execution. | |
940 | |
941 System-call traces are very useful for certain special kinds of | |
942 debugging, but in most cases they give little useful information. It is | |
943 therefore strange that many people seem to think that @emph{the} way to | |
944 report information about a crash is to send a system-call trace. Perhaps | |
945 this is a habit formed from experience debugging programs that don't | |
946 have source code or debugging symbols. | |
947 | |
948 In most programs, a backtrace is normally far, far more informative than | |
949 a system-call trace. Even in Emacs, a simple backtrace is generally | |
950 more informative, though to give full information you should supplement | |
951 the backtrace by displaying variable values and printing them as Lisp | |
952 objects with @code{pr} (see above). | |
953 | |
954 @item | |
955 A patch for the bug. | |
956 | |
957 A patch for the bug is useful if it is a good one. But don't omit the | |
958 other information that a bug report needs, such as the test case, on the | |
959 assumption that a patch is sufficient. We might see problems with your | |
960 patch and decide to fix the problem another way, or we might not | |
961 understand it at all. And if we can't understand what bug you are | |
962 trying to fix, or why your patch should be an improvement, we mustn't | |
963 install it. | |
964 | |
965 @ifnottex | |
966 @xref{Sending Patches}, for guidelines on how to make it easy for us to | |
967 understand and install your patches. | |
968 @end ifnottex | |
969 | |
970 @item | |
971 A guess about what the bug is or what it depends on. | |
972 | |
973 Such guesses are usually wrong. Even experts can't guess right about | |
974 such things without first using the debugger to find the facts. | |
975 @end itemize | |
976 | |
977 @node Sending Patches | |
978 @subsection Sending Patches for GNU Emacs | |
979 | |
980 @cindex sending patches for GNU Emacs | |
981 @cindex patches, sending | |
982 If you would like to write bug fixes or improvements for GNU Emacs, | |
983 that is very helpful. When you send your changes, please follow these | |
984 guidelines to make it easy for the maintainers to use them. If you | |
985 don't follow these guidelines, your information might still be useful, | |
986 but using it will take extra work. Maintaining GNU Emacs is a lot of | |
987 work in the best of circumstances, and we can't keep up unless you do | |
988 your best to help. | |
989 | |
990 @itemize @bullet | |
991 @item | |
992 Send an explanation with your changes of what problem they fix or what | |
110348
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
993 improvement they bring about. For a fix for an existing bug, it is |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
994 best to reply to the relevant discussion on the @samp{bug-gnu-emacs} |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
995 list, or item in the @url{http://debbugs.gnu.org} tracker. Explain |
facbb9773cf5
Various updates for the Bugs section of the manual.
Glenn Morris <rgm@gnu.org>
parents:
109262
diff
changeset
|
996 why your change fixes the bug. |
84269 | 997 |
998 @item | |
999 Always include a proper bug report for the problem you think you have | |
1000 fixed. We need to convince ourselves that the change is right before | |
1001 installing it. Even if it is correct, we might have trouble | |
1002 understanding it if we don't have a way to reproduce the problem. | |
1003 | |
1004 @item | |
1005 Include all the comments that are appropriate to help people reading the | |
1006 source in the future understand why this change was needed. | |
1007 | |
1008 @item | |
1009 Don't mix together changes made for different reasons. | |
1010 Send them @emph{individually}. | |
1011 | |
1012 If you make two changes for separate reasons, then we might not want to | |
1013 install them both. We might want to install just one. If you send them | |
1014 all jumbled together in a single set of diffs, we have to do extra work | |
1015 to disentangle them---to figure out which parts of the change serve | |
1016 which purpose. If we don't have time for this, we might have to ignore | |
1017 your changes entirely. | |
1018 | |
1019 If you send each change as soon as you have written it, with its own | |
1020 explanation, then two changes never get tangled up, and we can consider | |
1021 each one properly without any extra work to disentangle them. | |
1022 | |
1023 @item | |
1024 Send each change as soon as that change is finished. Sometimes people | |
1025 think they are helping us by accumulating many changes to send them all | |
1026 together. As explained above, this is absolutely the worst thing you | |
1027 could do. | |
1028 | |
1029 Since you should send each change separately, you might as well send it | |
1030 right away. That gives us the option of installing it immediately if it | |
1031 is important. | |
1032 | |
1033 @item | |
1034 Use @samp{diff -c} to make your diffs. Diffs without context are hard | |
1035 to install reliably. More than that, they are hard to study; we must | |
1036 always study a patch to decide whether we want to install it. Unidiff | |
1037 format is better than contextless diffs, but not as easy to read as | |
1038 @samp{-c} format. | |
1039 | |
1040 If you have GNU diff, use @samp{diff -c -F'^[_a-zA-Z0-9$]+ *('} when | |
1041 making diffs of C code. This shows the name of the function that each | |
1042 change occurs in. | |
1043 | |
1044 @item | |
1045 Avoid any ambiguity as to which is the old version and which is the new. | |
1046 Please make the old version the first argument to diff, and the new | |
1047 version the second argument. And please give one version or the other a | |
1048 name that indicates whether it is the old version or your new changed | |
1049 one. | |
1050 | |
1051 @item | |
1052 Write the change log entries for your changes. This is both to save us | |
1053 the extra work of writing them, and to help explain your changes so we | |
1054 can understand them. | |
1055 | |
1056 The purpose of the change log is to show people where to find what was | |
1057 changed. So you need to be specific about what functions you changed; | |
1058 in large functions, it's often helpful to indicate where within the | |
1059 function the change was. | |
1060 | |
1061 On the other hand, once you have shown people where to find the change, | |
1062 you need not explain its purpose in the change log. Thus, if you add a | |
1063 new function, all you need to say about it is that it is new. If you | |
1064 feel that the purpose needs explaining, it probably does---but put the | |
1065 explanation in comments in the code. It will be more useful there. | |
1066 | |
1067 Please read the @file{ChangeLog} files in the @file{src} and | |
1068 @file{lisp} directories to see what sorts of information to put in, | |
1069 and to learn the style that we use. @xref{Change Log}. | |
1070 | |
1071 @item | |
1072 When you write the fix, keep in mind that we can't install a change that | |
1073 would break other systems. Please think about what effect your change | |
1074 will have if compiled on another type of system. | |
1075 | |
1076 Sometimes people send fixes that @emph{might} be an improvement in | |
1077 general---but it is hard to be sure of this. It's hard to install | |
1078 such changes because we have to study them very carefully. Of course, | |
1079 a good explanation of the reasoning by which you concluded the change | |
1080 was correct can help convince us. | |
1081 | |
1082 The safest changes are changes to the configuration files for a | |
1083 particular machine. These are safe because they can't create new bugs | |
1084 on other machines. | |
1085 | |
1086 Please help us keep up with the workload by designing the patch in a | |
1087 form that is clearly safe to install. | |
1088 @end itemize | |
1089 | |
1090 @node Contributing, Service, Bugs, Top | |
1091 @section Contributing to Emacs Development | |
107929
b8bbaa0c915f
Doc fix related to Contributing.
Glenn Morris <rgm@gnu.org>
parents:
107194
diff
changeset
|
1092 @cindex contributing to Emacs |
84269 | 1093 |
1094 If you would like to help pretest Emacs releases to assure they work | |
1095 well, or if you would like to work on improving Emacs, please contact | |
1096 the maintainers at @email{emacs-devel@@gnu.org}. A pretester | |
1097 should be prepared to investigate bugs as well as report them. If you'd | |
1098 like to work on improving Emacs, please ask for suggested projects or | |
1099 suggest your own ideas. | |
1100 | |
1101 If you have already written an improvement, please tell us about it. If | |
1102 you have not yet started work, it is useful to contact | |
1103 @email{emacs-devel@@gnu.org} before you start; it might be | |
1104 possible to suggest ways to make your extension fit in better with the | |
1105 rest of Emacs. | |
1106 | |
107185
3c0f19155b60
* trouble.texi (Contributing): Repository is no longer CVS.
Glenn Morris <rgm@gnu.org>
parents:
106924
diff
changeset
|
1107 The development version of Emacs can be downloaded from the |
107194
f14b4c307fe1
* trouble.texi: Revert grammar change from previous change.
Glenn Morris <rgm@gnu.org>
parents:
107185
diff
changeset
|
1108 repository where it is actively maintained by a group of developers. |
84269 | 1109 See the Emacs project page |
1110 @url{http://savannah.gnu.org/projects/emacs/} for details. | |
1111 | |
107929
b8bbaa0c915f
Doc fix related to Contributing.
Glenn Morris <rgm@gnu.org>
parents:
107194
diff
changeset
|
1112 For more information on how to contribute, see the @file{etc/CONTRIBUTE} |
b8bbaa0c915f
Doc fix related to Contributing.
Glenn Morris <rgm@gnu.org>
parents:
107194
diff
changeset
|
1113 file in the Emacs distribution. |
b8bbaa0c915f
Doc fix related to Contributing.
Glenn Morris <rgm@gnu.org>
parents:
107194
diff
changeset
|
1114 |
84269 | 1115 @node Service, Copying, Contributing, Top |
1116 @section How To Get Help with GNU Emacs | |
1117 | |
1118 If you need help installing, using or changing GNU Emacs, there are two | |
1119 ways to find it: | |
1120 | |
1121 @itemize @bullet | |
1122 @item | |
1123 Send a message to the mailing list | |
1124 @email{help-gnu-emacs@@gnu.org}, or post your request on | |
1125 newsgroup @code{gnu.emacs.help}. (This mailing list and newsgroup | |
1126 interconnect, so it does not matter which one you use.) | |
1127 | |
1128 @item | |
1129 Look in the service directory for someone who might help you for a fee. | |
1130 The service directory is found in the file named @file{etc/SERVICE} in the | |
1131 Emacs distribution. | |
1132 @end itemize | |
1133 | |
1134 @ifnottex | |
1135 @lowersections | |
1136 @end ifnottex | |
1137 |