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