428
+ − 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
442
+ − 335 your init file, set any variables that may affect the functioning of
+ − 336 Emacs. @xref{Init File}. Also, see whether the problem happens in a
+ − 337 freshly started Emacs without loading your init file (start Emacs with
+ − 338 the @code{-q} switch to prevent loading the init file). If the problem
+ − 339 does @var{not} occur then, it is essential that we know the contents of
+ − 340 any programs that you must load into the Lisp world in order to cause
+ − 341 the problem to occur.
428
+ − 342
+ − 343 If the problem does depend on an init file or other Lisp programs that
+ − 344 are not part of the standard Emacs system, then you should make sure it is
+ − 345 not a bug in those programs by complaining to their maintainers first.
+ − 346 After they verify that they are using Emacs in a way that is supposed to
+ − 347 work, they should report the bug.
+ − 348
+ − 349 If you can tell us a way to cause the problem without visiting any files,
+ − 350 please do so. This makes it much easier to debug. If you do need files,
+ − 351 make sure you arrange for us to see their exact contents. For example, it
+ − 352 can often matter whether there are spaces at the ends of lines, or a
+ − 353 newline after the last line in the buffer (nothing ought to care whether
+ − 354 the last line is terminated, but tell that to the bugs).
+ − 355
+ − 356 @findex open-dribble-file
+ − 357 @cindex dribble file
+ − 358 The easy way to record the input to Emacs precisely is to write a
+ − 359 dribble file; execute the Lisp expression:
+ − 360
+ − 361 @example
+ − 362 (open-dribble-file "~/dribble")
+ − 363 @end example
+ − 364
+ − 365 @noindent
+ − 366 using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer just after starting
+ − 367 Emacs. From then on, all Emacs input will be written in the specified
+ − 368 dribble file until the Emacs process is killed.
+ − 369
+ − 370 @findex open-termscript
+ − 371 @cindex termscript file
+ − 372 For possible display bugs, it is important to report the terminal type
+ − 373 (the value of environment variable @code{TERM}), the complete termcap entry
+ − 374 for the terminal from @file{/etc/termcap} (since that file is not identical
+ − 375 on all machines), and the output that Emacs actually sent to the terminal.
+ − 376 The way to collect this output is to execute the Lisp expression:
+ − 377
+ − 378 @example
+ − 379 (open-termscript "~/termscript")
+ − 380 @end example
+ − 381
442
+ − 382 @noindent using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer
+ − 383 just after starting Emacs. From then on, all output from Emacs to the
+ − 384 terminal will be written in the specified termscript file as well, until
+ − 385 the Emacs process is killed. If the problem happens when Emacs starts
+ − 386 up, put this expression into your init file so that the termscript file
+ − 387 will be open when Emacs displays the screen for the first time.
+ − 388 @xref{Init File}. Be warned: it is often difficult, and sometimes
+ − 389 impossible, to fix a terminal-dependent bug without access to a terminal
+ − 390 of the type that stimulates the bug.@refill
428
+ − 391
+ − 392 The newsgroup @samp{comp.emacs.xemacs} may be used for bug reports,
+ − 393 other discussions and requests for assistance.
+ − 394
4488
+ − 395 If you don't have access to this newsgroup, you can subscribe to the
428
+ − 396 mailing list version: the newsgroup is bidirectionally gatewayed into
+ − 397 the mailing list @samp{xemacs@@xemacs.org}.
+ − 398
+ − 399 To be added or removed from this mailing list, send mail to
+ − 400 @samp{xemacs-request@@xemacs.org}. Do not send requests for addition
+ − 401 to the mailing list itself.
+ − 402
+ − 403 The mailing lists and newsgroups are archived on our anonymous FTP server,
+ − 404 @samp{ftp.xemacs.org}, and at various other archive sites around the net. You
+ − 405 should also check the @samp{FAQ} in @samp{/pub/xemacs} on our anonymous
+ − 406 FTP server. It provides some introductory information and help for initial
+ − 407 configuration problems.