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