|
0
|
1
|
|
|
2 @iftex
|
|
|
3 @chapter Correcting Mistakes (Yours or Emacs's)
|
|
|
4
|
|
|
5 If you type an Emacs command you did not intend, the results are often
|
|
|
6 mysterious. This chapter discusses how you can undo your mistake or
|
|
|
7 recover from a mysterious situation. Emacs bugs and system crashes are
|
|
|
8 also considered.
|
|
|
9 @end iftex
|
|
|
10
|
|
|
11 @node Quitting, Lossage, Customization, Top
|
|
|
12 @section Quitting and Aborting
|
|
|
13 @cindex quitting
|
|
|
14
|
|
|
15 @table @kbd
|
|
|
16 @item C-g
|
|
|
17 Quit. Cancel running or partially typed command.
|
|
|
18 @item C-]
|
|
|
19 Abort innermost recursive editing level and cancel the command which
|
|
|
20 invoked it (@code{abort-recursive-edit}).
|
|
|
21 @item M-x top-level
|
|
|
22 Abort all recursive editing levels that are currently executing.
|
|
|
23 @item C-x u
|
|
|
24 Cancel an already-executed command, usually (@code{undo}).
|
|
|
25 @end table
|
|
|
26
|
|
|
27 There are two ways of cancelling commands which are not finished
|
|
|
28 executing: @dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]}
|
|
|
29 or @kbd{M-x top-level}. Quitting is cancelling a partially typed command
|
|
|
30 or one which is already running. Aborting is getting out of a recursive
|
|
|
31 editing level and cancelling the command that invoked the recursive edit.
|
|
|
32
|
|
|
33 @cindex quitting
|
|
|
34 @kindex C-g
|
|
|
35 Quitting with @kbd{C-g} is used for getting rid of a partially typed
|
|
|
36 command or a numeric argument that you don't want. It also stops a
|
|
|
37 running command in the middle in a relatively safe way, so you can use
|
|
|
38 it if you accidentally start executing a command that takes a long
|
|
|
39 time. In particular, it is safe to quit out of killing; either your
|
|
|
40 text will @var{all} still be there, or it will @var{all} be in the kill
|
|
|
41 ring (or maybe both). Quitting an incremental search does special
|
|
|
42 things documented under searching; in general, it may take two
|
|
|
43 successive @kbd{C-g} characters to get out of a search. @kbd{C-g} works
|
|
|
44 by setting the variable @code{quit-flag} to @code{t} the instant
|
|
|
45 @kbd{C-g} is typed; Emacs Lisp checks this variable frequently and quits
|
|
|
46 if it is non-@code{nil}. @kbd{C-g} is only actually executed as a
|
|
|
47 command if it is typed while Emacs is waiting for input.
|
|
|
48
|
|
|
49 If you quit twice in a row before the first @kbd{C-g} is recognized, you
|
|
|
50 activate the ``emergency escape'' feature and return to the shell.
|
|
|
51 @xref{Emergency Escape}.
|
|
|
52
|
|
|
53 @cindex recursive editing level
|
|
|
54 @cindex editing level, recursive
|
|
|
55 @cindex aborting
|
|
|
56 @findex abort-recursive-edit
|
|
|
57 @kindex C-]
|
|
|
58 You can use @kbd{C-]} (@code{abort-recursive-edit}) to get out
|
|
|
59 of a recursive editing level and cancel the command which invoked it.
|
|
|
60 Quitting with @kbd{C-g} does not do this, and could not do this because it
|
|
|
61 is used to cancel a partially typed command @i{within} the recursive
|
|
|
62 editing level. Both operations are useful. For example, if you are in the
|
|
|
63 Emacs debugger (@pxref{Lisp Debug}) and have typed @kbd{C-u 8} to enter a
|
|
|
64 numeric argument, you can cancel that argument with @kbd{C-g} and remain in
|
|
|
65 the debugger.
|
|
|
66
|
|
|
67 @findex top-level
|
|
|
68 The command @kbd{M-x top-level} is equivalent to ``enough'' @kbd{C-]}
|
|
|
69 commands to get you out of all the levels of recursive edits that you are
|
|
|
70 in. @kbd{C-]} only gets you out one level at a time, but @kbd{M-x top-level}
|
|
|
71 goes out all levels at once. Both @kbd{C-]} and @kbd{M-x top-level} are
|
|
|
72 like all other commands and unlike @kbd{C-g} in that they are effective
|
|
|
73 only when Emacs is ready for a command. @kbd{C-]} is an ordinary key and
|
|
|
74 has its meaning only because of its binding in the keymap.
|
|
|
75 @xref{Recursive Edit}.
|
|
|
76
|
|
|
77 @kbd{C-x u} (@code{undo}) is not strictly speaking a way of cancelling a
|
|
|
78 command, but you can think of it as cancelling a command already finished
|
|
|
79 executing. @xref{Undo}.
|
|
|
80
|
|
|
81 @node Lossage, Bugs, Quitting, Top
|
|
|
82 @section Dealing With Emacs Trouble
|
|
|
83
|
|
|
84 This section describes various conditions in which Emacs fails to work,
|
|
|
85 and how to recognize them and correct them.
|
|
|
86
|
|
|
87 @menu
|
|
|
88 * Stuck Recursive:: `[...]' in mode line around the parentheses.
|
|
|
89 * Screen Garbled:: Garbage on the screen.
|
|
|
90 * Text Garbled:: Garbage in the text.
|
|
|
91 * Unasked-for Search:: Spontaneous entry to incremental search.
|
|
|
92 * Emergency Escape:: Emergency escape---
|
|
|
93 What to do if Emacs stops responding.
|
|
|
94 * Total Frustration:: When you are at your wits' end.
|
|
|
95 @end menu
|
|
|
96
|
|
|
97 @node Stuck Recursive, Screen Garbled, Lossage, Lossage
|
|
|
98 @subsection Recursive Editing Levels
|
|
|
99
|
|
|
100 Recursive editing levels are important and useful features of Emacs, but
|
|
|
101 they can seem like malfunctions to the user who does not understand them.
|
|
|
102
|
|
|
103 If the mode line has square brackets @samp{[@dots{}]} around the parentheses
|
|
|
104 that contain the names of the major and minor modes, you have entered a
|
|
|
105 recursive editing level. If you did not do this on purpose, or if you
|
|
|
106 don't understand what that means, you should just get out of the recursive
|
|
|
107 editing level. To do so, type @kbd{M-x top-level}. This is called getting
|
|
|
108 back to top level. @xref{Recursive Edit}.
|
|
|
109
|
|
|
110 @node Screen Garbled, Text Garbled, Stuck Recursive, Lossage
|
|
|
111 @subsection Garbage on the Screen
|
|
|
112
|
|
|
113 If the data on the screen looks wrong, the first thing to do is see
|
|
|
114 whether the text is actually wrong. Type @kbd{C-l}, to redisplay the
|
|
|
115 entire screen. If the text appears correct after this, the problem was
|
|
|
116 entirely in the previous screen update.
|
|
|
117
|
|
|
118 Display updating problems often result from an incorrect termcap entry
|
|
|
119 for the terminal you are using. The file @file{etc/TERMS} in the Emacs
|
|
|
120 distribution gives the fixes for known problems of this sort.
|
|
|
121 @file{INSTALL} contains general advice for these problems in one of its
|
|
|
122 sections. Very likely there is simply insufficient padding for certain
|
|
|
123 display operations. To investigate the possibility that you have this
|
|
|
124 sort of problem, try Emacs on another terminal made by a different
|
|
|
125 manufacturer. If problems happen frequently on one kind of terminal but
|
|
|
126 not another kind, the real problem is likely to be a bad termcap entry,
|
|
|
127 though it could also be due to a bug in Emacs that appears for terminals
|
|
|
128 that have or lack specific features.
|
|
|
129
|
|
|
130 @node Text Garbled, Unasked-for Search, Screen Garbled, Lossage
|
|
|
131 @subsection Garbage in the Text
|
|
|
132
|
|
|
133 If @kbd{C-l} shows that the text is wrong, try undoing the changes to it
|
|
|
134 using @kbd{C-x u} until it gets back to a state you consider correct. Also
|
|
|
135 try @kbd{C-h l} to find out what command you typed to produce the observed
|
|
|
136 results.
|
|
|
137
|
|
|
138 If a large portion of text appears to be missing at the beginning or
|
|
|
139 end of the buffer, check for the word @samp{Narrow} in the mode line.
|
|
|
140 If it appears, the text is still present, but marked off-limits.
|
|
|
141 To make it visible again, type @kbd{C-x n w}. @xref{Narrowing}.
|
|
|
142
|
|
|
143 @node Unasked-for Search, Emergency Escape, Text Garbled, Lossage
|
|
|
144 @subsection Spontaneous Entry to Incremental Search
|
|
|
145
|
|
|
146 If Emacs spontaneously displays @samp{I-search:} at the bottom of the
|
|
|
147 screen, it means that the terminal is sending @kbd{C-s} and @kbd{C-q}
|
|
|
148 according to the poorly designed xon/xoff ``flow control'' protocol. You
|
|
|
149 should try to prevent this by putting the terminal in a mode where it will
|
|
|
150 not use flow control, or by giving it enough padding that it will never send a
|
|
|
151 @kbd{C-s}. If that cannot be done, you must tell Emacs to expect flow
|
|
|
152 control to be used, until you can get a properly designed terminal.
|
|
|
153
|
|
|
154 Information on how to do these things can be found in the file
|
|
|
155 @file{INSTALL} in the Emacs distribution.
|
|
|
156
|
|
|
157 @node Emergency Escape, Total Frustration, Unasked-for Search, Lossage
|
|
|
158 @subsection Emergency Escape
|
|
|
159
|
|
|
160 Because at times there have been bugs causing Emacs to loop without
|
|
|
161 checking @code{quit-flag}, a special feature causes Emacs to be suspended
|
|
|
162 immediately if you type a second @kbd{C-g} while the flag is already set,
|
|
|
163 so you can always get out of XEmacs. Normally Emacs recognizes and
|
|
|
164 clears @code{quit-flag} (and quits!) quickly enough to prevent this from
|
|
|
165 happening.
|
|
|
166
|
|
|
167 When you resume Emacs after a suspension caused by multiple @kbd{C-g}, it
|
|
|
168 asks two questions before going back to what it had been doing:
|
|
|
169
|
|
|
170 @example
|
|
|
171 Auto-save? (y or n)
|
|
|
172 Abort (and dump core)? (y or n)
|
|
|
173 @end example
|
|
|
174
|
|
|
175 @noindent
|
|
|
176 Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}.
|
|
|
177
|
|
|
178 Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of all
|
|
|
179 modified buffers in which auto-saving is enabled.
|
|
|
180
|
|
|
181 Saying @kbd{y} to @samp{Abort (and dump core)?} causes an illegal
|
|
|
182 instruction to be executed, dumping core. This is to enable a wizard to
|
|
|
183 figure out why Emacs was failing to quit in the first place. Execution
|
|
|
184 does not continue after a core dump. If you answer @kbd{n}, execution
|
|
|
185 does continue. With luck, Emacs will ultimately check
|
|
|
186 @code{quit-flag} and quit normally. If not, and you type another
|
|
|
187 @kbd{C-g}, it is suspended again.
|
|
|
188
|
|
|
189 If Emacs is not really hung, but is just being slow, you may invoke
|
|
|
190 the double @kbd{C-g} feature without really meaning to. In that case,
|
|
|
191 simply resume and answer @kbd{n} to both questions, and you will arrive
|
|
|
192 at your former state. Presumably the quit you requested will happen
|
|
|
193 soon.
|
|
|
194
|
|
|
195 The double-@kbd{C-g} feature may be turned off when Emacs is running under
|
|
|
196 a window system, since the window system always enables you to kill Emacs
|
|
|
197 or to create another window and run another program.
|
|
|
198
|
|
|
199 @node Total Frustration,, Emergency Escape, Lossage
|
|
|
200 @subsection Help for Total Frustration
|
|
|
201 @cindex Eliza
|
|
|
202 @cindex doctor
|
|
|
203
|
|
|
204 If using Emacs (or something else) becomes terribly frustrating and none
|
|
|
205 of the techniques described above solve the problem, Emacs can still help
|
|
|
206 you.
|
|
|
207
|
|
|
208 First, if the Emacs you are using is not responding to commands, type
|
|
|
209 @kbd{C-g C-g} to get out of it and then start a new one.
|
|
|
210
|
|
|
211 @findex doctor
|
|
|
212 Second, type @kbd{M-x doctor @key{RET}}.
|
|
|
213
|
|
|
214 The doctor will make you feel better. Each time you say something to
|
|
|
215 the doctor, you must end it by typing @key{RET} @key{RET}. This lets the
|
|
|
216 doctor know you are finished.
|
|
|
217
|
|
|
218 @node Bugs,, Lossage, Top
|
|
|
219 @section Reporting Bugs
|
|
|
220
|
|
|
221 @cindex bugs
|
|
|
222 Sometimes you will encounter a bug in Emacs. Although we cannot promise
|
|
|
223 we can or will fix the bug, and we might not even agree that it is a bug,
|
|
|
224 we want to hear about bugs you encounter in case we do want to fix them.
|
|
|
225
|
|
|
226 To make it possible for us to fix a bug, you must report it. In order
|
|
|
227 to do so effectively, you must know when and how to do it.
|
|
|
228
|
|
|
229 @subsection When Is There a Bug
|
|
|
230
|
|
|
231 If Emacs executes an illegal instruction, or dies with an operating
|
|
|
232 system error message that indicates a problem in the program (as opposed to
|
|
|
233 something like ``disk full''), then it is certainly a bug.
|
|
|
234
|
|
|
235 If Emacs updates the display in a way that does not correspond to what is
|
|
|
236 in the buffer, then it is certainly a bug. If a command seems to do the
|
|
|
237 wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a
|
|
|
238 case of incorrect display updating.
|
|
|
239
|
|
|
240 Taking forever to complete a command can be a bug, but you must make
|
|
|
241 certain that it was really Emacs's fault. Some commands simply take a long
|
|
|
242 time. Type @kbd{C-g} and then @kbd{C-h l} to see whether the input Emacs
|
|
|
243 received was what you intended to type; if the input was such that you
|
|
|
244 @var{know} it should have been processed quickly, report a bug. If you
|
|
|
245 don't know whether the command should take a long time, find out by looking
|
|
|
246 in the manual or by asking for assistance.
|
|
|
247
|
|
|
248 If a command you are familiar with causes an Emacs error message in a
|
|
|
249 case where its usual definition ought to be reasonable, it is probably a
|
|
|
250 bug.
|
|
|
251
|
|
|
252 If a command does the wrong thing, that is a bug. But be sure you know
|
|
|
253 for certain what it ought to have done. If you aren't familiar with the
|
|
|
254 command, or don't know for certain how the command is supposed to work,
|
|
|
255 then it might actually be working right. Rather than jumping to
|
|
|
256 conclusions, show the problem to someone who knows for certain.
|
|
|
257
|
|
|
258 Finally, a command's intended definition may not be best for editing
|
|
|
259 with. This is a very important sort of problem, but it is also a matter of
|
|
|
260 judgment. Also, it is easy to come to such a conclusion out of ignorance
|
|
|
261 of some of the existing features. It is probably best not to complain
|
|
|
262 about such a problem until you have checked the documentation in the usual
|
|
|
263 ways, feel confident that you understand it, and know for certain that what
|
|
|
264 you want is not available. If you are not sure what the command is
|
|
|
265 supposed to do after a careful reading of the manual, check the index and
|
|
|
266 glossary for any terms that may be unclear. If you still do not
|
|
|
267 understand, this indicates a bug in the manual. The manual's job is to
|
|
|
268 make everything clear. It is just as important to report documentation
|
|
|
269 bugs as program bugs.
|
|
|
270
|
|
|
271 If the online documentation string of a function or variable disagrees
|
|
|
272 with the manual, one of them must be wrong, so report the bug.
|
|
|
273
|
|
|
274 @subsection How to Report a Bug
|
|
|
275
|
|
|
276 @findex emacs-version
|
|
|
277 When you decide that there is a bug, it is important to report it and to
|
|
|
278 report it in a way which is useful. What is most useful is an exact
|
|
|
279 description of what commands you type, starting with the shell command to
|
|
|
280 run Emacs, until the problem happens. Always include the version number
|
|
|
281 of Emacs that you are using; type @kbd{M-x emacs-version} to print this.
|
|
|
282
|
|
|
283 The most important principle in reporting a bug is to report @var{facts},
|
|
|
284 not hypotheses or categorizations. It is always easier to report the facts,
|
|
|
285 but people seem to prefer to strain to posit explanations and report
|
|
|
286 them instead. If the explanations are based on guesses about how Emacs is
|
|
|
287 implemented, they will be useless; we will have to try to figure out what
|
|
|
288 the facts must have been to lead to such speculations. Sometimes this is
|
|
|
289 impossible. But in any case, it is unnecessary work for us.
|
|
|
290
|
|
|
291 For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh
|
|
|
292 @key{RET}}, visiting a file which (you know) happens to be rather large,
|
|
|
293 and Emacs prints out @samp{I feel pretty today}. The best way to report
|
|
|
294 the bug is with a sentence like the preceding one, because it gives all the
|
|
|
295 facts and nothing but the facts.
|
|
|
296
|
|
|
297 Do not assume that the problem is due to the size of the file and say,
|
|
|
298 ``When I visit a large file, Emacs prints out @samp{I feel pretty today}.''
|
|
|
299 This is what we mean by ``guessing explanations''. The problem is just as
|
|
|
300 likely to be due to the fact that there is a @samp{z} in the file name. If
|
|
|
301 this is so, then when we got your report, we would try out the problem with
|
|
|
302 some ``large file'', probably with no @samp{z} in its name, and not find
|
|
|
303 anything wrong. There is no way in the world that we could guess that we
|
|
|
304 should try visiting a file with a @samp{z} in its name.
|
|
|
305
|
|
|
306 Alternatively, the problem might be due to the fact that the file starts
|
|
|
307 with exactly 25 spaces. For this reason, you should make sure that you
|
|
|
308 inform us of the exact contents of any file that is needed to reproduce the
|
|
|
309 bug. What if the problem only occurs when you have typed the @kbd{C-x a l}
|
|
|
310 command previously? This is why we ask you to give the exact sequence of
|
|
|
311 characters you typed since starting to use Emacs.
|
|
|
312
|
|
|
313 You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless
|
|
|
314 you @i{know} that it makes no difference which visiting command is used.
|
|
|
315 Similarly, rather than saying ``if I have three characters on the line,''
|
|
|
316 say ``after I type @kbd{@key{RET} A B C @key{RET} C-p},'' if that is
|
|
|
317 the way you entered the text.@refill
|
|
|
318
|
|
|
319 If you are not in Fundamental mode when the problem occurs, you should
|
|
|
320 say what mode you are in.
|
|
|
321
|
|
|
322 If the manifestation of the bug is an Emacs error message, it is
|
|
|
323 important to report not just the text of the error message but a backtrace
|
|
|
324 showing how the Lisp program in Emacs arrived at the error. To make the
|
|
|
325 backtrace, you must execute the Lisp expression
|
|
|
326 @code{(setq @w{debug-on-error t})} before the error happens (that is to
|
|
|
327 say, you must execute that expression and then make the bug happen). This
|
|
|
328 causes the Lisp debugger to run (@pxref{Lisp Debug}). The debugger's
|
|
|
329 backtrace can be copied as text into the bug report. This use of the
|
|
|
330 debugger is possible only if you know how to make the bug happen again. Do
|
|
|
331 note the error message the first time the bug happens, so if you can't make
|
|
|
332 it happen again, you can report at least that.
|
|
|
333
|
|
|
334 Check whether any programs you have loaded into the Lisp world, including
|
|
412
|
335 your @file{.emacs} file, set any variables that may affect the functioning
|
|
|
336 of Emacs. Also, see whether the problem happens in a freshly started Emacs
|
|
|
337 without loading your @file{.emacs} file (start Emacs with the @code{-q} switch
|
|
|
338 to prevent loading the init file). If the problem does @var{not} occur
|
|
|
339 then, it is essential that we know the contents of any programs that you
|
|
|
340 must load into the Lisp world in order to cause the problem to occur.
|
|
0
|
341
|
|
|
342 If the problem does depend on an init file or other Lisp programs that
|
|
|
343 are not part of the standard Emacs system, then you should make sure it is
|
|
|
344 not a bug in those programs by complaining to their maintainers first.
|
|
|
345 After they verify that they are using Emacs in a way that is supposed to
|
|
|
346 work, they should report the bug.
|
|
|
347
|
|
|
348 If you can tell us a way to cause the problem without visiting any files,
|
|
|
349 please do so. This makes it much easier to debug. If you do need files,
|
|
|
350 make sure you arrange for us to see their exact contents. For example, it
|
|
|
351 can often matter whether there are spaces at the ends of lines, or a
|
|
|
352 newline after the last line in the buffer (nothing ought to care whether
|
|
|
353 the last line is terminated, but tell that to the bugs).
|
|
|
354
|
|
|
355 @findex open-dribble-file
|
|
|
356 @cindex dribble file
|
|
2
|
357 The easy way to record the input to Emacs precisely is to write a
|
|
0
|
358 dribble file; execute the Lisp expression:
|
|
|
359
|
|
|
360 @example
|
|
|
361 (open-dribble-file "~/dribble")
|
|
|
362 @end example
|
|
|
363
|
|
|
364 @noindent
|
|
|
365 using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer just after starting
|
|
|
366 Emacs. From then on, all Emacs input will be written in the specified
|
|
|
367 dribble file until the Emacs process is killed.
|
|
|
368
|
|
|
369 @findex open-termscript
|
|
|
370 @cindex termscript file
|
|
|
371 For possible display bugs, it is important to report the terminal type
|
|
|
372 (the value of environment variable @code{TERM}), the complete termcap entry
|
|
|
373 for the terminal from @file{/etc/termcap} (since that file is not identical
|
|
|
374 on all machines), and the output that Emacs actually sent to the terminal.
|
|
|
375 The way to collect this output is to execute the Lisp expression:
|
|
|
376
|
|
|
377 @example
|
|
|
378 (open-termscript "~/termscript")
|
|
|
379 @end example
|
|
|
380
|
|
412
|
381 @noindent
|
|
|
382 using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer just
|
|
|
383 after starting Emacs. From then on, all output from Emacs to the terminal
|
|
|
384 will be written in the specified termscript file as well, until the Emacs
|
|
|
385 process is killed. If the problem happens when Emacs starts up, put this
|
|
|
386 expression into your @file{.emacs} file so that the termscript file will
|
|
|
387 be open when Emacs displays the screen for the first time. Be warned:
|
|
|
388 it is often difficult, and sometimes impossible, to fix a terminal-dependent
|
|
|
389 bug without access to a terminal of the type that stimulates the bug.@refill
|
|
0
|
390
|
|
|
391 The newsgroup @samp{comp.emacs.xemacs} may be used for bug reports,
|
|
|
392 other discussions and requests for assistance.
|
|
|
393
|
|
|
394 If you don't have access to this newgroup, you can subscribe to the
|
|
|
395 mailing list version: the newsgroup is bidirectionally gatewayed into
|
|
|
396 the mailing list @samp{xemacs@@xemacs.org}.
|
|
|
397
|
|
|
398 To be added or removed from this mailing list, send mail to
|
|
|
399 @samp{xemacs-request@@xemacs.org}. Do not send requests for addition
|
|
|
400 to the mailing list itself.
|
|
|
401
|
|
|
402 The mailing lists and newsgroups are archived on our anonymous FTP server,
|
|
|
403 @samp{ftp.xemacs.org}, and at various other archive sites around the net. You
|
|
|
404 should also check the @samp{FAQ} in @samp{/pub/xemacs} on our anonymous
|
|
|
405 FTP server. It provides some introductory information and help for initial
|
|
|
406 configuration problems.
|
