--- /dev/null
+
+@iftex
+@chapter Correcting Mistakes (Yours or Emacs's)
+
+ If you type an Emacs command you did not intend, the results are often
+mysterious. This chapter discusses how you can undo your mistake or
+recover from a mysterious situation. Emacs bugs and system crashes are
+also considered.
+@end iftex
+
+@node Quitting, Lossage, Customization, Top
+@section Quitting and Aborting
+@cindex quitting
+
+@table @kbd
+@item C-g
+Quit. Cancel running or partially typed command.
+@item C-]
+Abort innermost recursive editing level and cancel the command which
+invoked it (@code{abort-recursive-edit}).
+@item M-x top-level
+Abort all recursive editing levels that are currently executing.
+@item C-x u
+Cancel an already-executed command, usually (@code{undo}).
+@end table
+
+ There are two ways of cancelling commands which are not finished
+executing: @dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]}
+or @kbd{M-x top-level}. Quitting is cancelling a partially typed command
+or one which is already running. Aborting is getting out of a recursive
+editing level and cancelling the command that invoked the recursive edit.
+
+@cindex quitting
+@kindex C-g
+ Quitting with @kbd{C-g} is used for getting rid of a partially typed
+command or a numeric argument that you don't want. It also stops a
+running command in the middle in a relatively safe way, so you can use
+it if you accidentally start executing a command that takes a long
+time. In particular, it is safe to quit out of killing; either your
+text will @var{all} still be there, or it will @var{all} be in the kill
+ring (or maybe both). Quitting an incremental search does special
+things documented under searching; in general, it may take two
+successive @kbd{C-g} characters to get out of a search. @kbd{C-g} works
+by setting the variable @code{quit-flag} to @code{t} the instant
+@kbd{C-g} is typed; Emacs Lisp checks this variable frequently and quits
+if it is non-@code{nil}. @kbd{C-g} is only actually executed as a
+command if it is typed while Emacs is waiting for input.
+
+If you quit twice in a row before the first @kbd{C-g} is recognized, you
+activate the ``emergency escape'' feature and return to the shell.
+@xref{Emergency Escape}.
+
+@cindex recursive editing level
+@cindex editing level, recursive
+@cindex aborting
+@findex abort-recursive-edit
+@kindex C-]
+ You can use @kbd{C-]} (@code{abort-recursive-edit}) to get out
+of a recursive editing level and cancel the command which invoked it.
+Quitting with @kbd{C-g} does not do this, and could not do this because it
+is used to cancel a partially typed command @i{within} the recursive
+editing level. Both operations are useful. For example, if you are in the
+Emacs debugger (@pxref{Lisp Debug}) and have typed @kbd{C-u 8} to enter a
+numeric argument, you can cancel that argument with @kbd{C-g} and remain in
+the debugger.
+
+@findex top-level
+ The command @kbd{M-x top-level} is equivalent to ``enough'' @kbd{C-]}
+commands to get you out of all the levels of recursive edits that you are
+in. @kbd{C-]} only gets you out one level at a time, but @kbd{M-x top-level}
+goes out all levels at once. Both @kbd{C-]} and @kbd{M-x top-level} are
+like all other commands and unlike @kbd{C-g} in that they are effective
+only when Emacs is ready for a command. @kbd{C-]} is an ordinary key and
+has its meaning only because of its binding in the keymap.
+@xref{Recursive Edit}.
+
+ @kbd{C-x u} (@code{undo}) is not strictly speaking a way of cancelling a
+command, but you can think of it as cancelling a command already finished
+executing. @xref{Undo}.
+
+@node Lossage, Bugs, Quitting, Top
+@section Dealing With Emacs Trouble
+
+ This section describes various conditions in which Emacs fails to work,
+and how to recognize them and correct them.
+
+@menu
+* Stuck Recursive:: `[...]' in mode line around the parentheses.
+* Screen Garbled:: Garbage on the screen.
+* Text Garbled:: Garbage in the text.
+* Unasked-for Search:: Spontaneous entry to incremental search.
+* Emergency Escape:: Emergency escape---
+ What to do if Emacs stops responding.
+* Total Frustration:: When you are at your wits' end.
+@end menu
+
+@node Stuck Recursive, Screen Garbled, Lossage, Lossage
+@subsection Recursive Editing Levels
+
+ Recursive editing levels are important and useful features of Emacs, but
+they can seem like malfunctions to the user who does not understand them.
+
+ If the mode line has square brackets @samp{[@dots{}]} around the parentheses
+that contain the names of the major and minor modes, you have entered a
+recursive editing level. If you did not do this on purpose, or if you
+don't understand what that means, you should just get out of the recursive
+editing level. To do so, type @kbd{M-x top-level}. This is called getting
+back to top level. @xref{Recursive Edit}.
+
+@node Screen Garbled, Text Garbled, Stuck Recursive, Lossage
+@subsection Garbage on the Screen
+
+ If the data on the screen looks wrong, the first thing to do is see
+whether the text is actually wrong. Type @kbd{C-l}, to redisplay the
+entire screen. If the text appears correct after this, the problem was
+entirely in the previous screen update.
+
+ Display updating problems often result from an incorrect termcap entry
+for the terminal you are using. The file @file{etc/TERMS} in the Emacs
+distribution gives the fixes for known problems of this sort.
+@file{INSTALL} contains general advice for these problems in one of its
+sections. Very likely there is simply insufficient padding for certain
+display operations. To investigate the possibility that you have this
+sort of problem, try Emacs on another terminal made by a different
+manufacturer. If problems happen frequently on one kind of terminal but
+not another kind, the real problem is likely to be a bad termcap entry,
+though it could also be due to a bug in Emacs that appears for terminals
+that have or lack specific features.
+
+@node Text Garbled, Unasked-for Search, Screen Garbled, Lossage
+@subsection Garbage in the Text
+
+ If @kbd{C-l} shows that the text is wrong, try undoing the changes to it
+using @kbd{C-x u} until it gets back to a state you consider correct. Also
+try @kbd{C-h l} to find out what command you typed to produce the observed
+results.
+
+ If a large portion of text appears to be missing at the beginning or
+end of the buffer, check for the word @samp{Narrow} in the mode line.
+If it appears, the text is still present, but marked off-limits.
+To make it visible again, type @kbd{C-x n w}. @xref{Narrowing}.
+
+@node Unasked-for Search, Emergency Escape, Text Garbled, Lossage
+@subsection Spontaneous Entry to Incremental Search
+
+ If Emacs spontaneously displays @samp{I-search:} at the bottom of the
+screen, it means that the terminal is sending @kbd{C-s} and @kbd{C-q}
+according to the poorly designed xon/xoff ``flow control'' protocol. You
+should try to prevent this by putting the terminal in a mode where it will
+not use flow control, or by giving it enough padding that it will never send a
+@kbd{C-s}. If that cannot be done, you must tell Emacs to expect flow
+control to be used, until you can get a properly designed terminal.
+
+ Information on how to do these things can be found in the file
+@file{INSTALL} in the Emacs distribution.
+
+@node Emergency Escape, Total Frustration, Unasked-for Search, Lossage
+@subsection Emergency Escape
+
+ Because at times there have been bugs causing Emacs to loop without
+checking @code{quit-flag}, a special feature causes Emacs to be suspended
+immediately if you type a second @kbd{C-g} while the flag is already set,
+so you can always get out of XEmacs. Normally Emacs recognizes and
+clears @code{quit-flag} (and quits!) quickly enough to prevent this from
+happening.
+
+ When you resume Emacs after a suspension caused by multiple @kbd{C-g}, it
+asks two questions before going back to what it had been doing:
+
+@example
+Auto-save? (y or n)
+Abort (and dump core)? (y or n)
+@end example
+
+@noindent
+Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}.
+
+ Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of all
+modified buffers in which auto-saving is enabled.
+
+ Saying @kbd{y} to @samp{Abort (and dump core)?} causes an illegal
+instruction to be executed, dumping core. This is to enable a wizard to
+figure out why Emacs was failing to quit in the first place. Execution
+does not continue after a core dump. If you answer @kbd{n}, execution
+does continue. With luck, Emacs will ultimately check
+@code{quit-flag} and quit normally. If not, and you type another
+@kbd{C-g}, it is suspended again.
+
+ If Emacs is not really hung, but is just being slow, you may invoke
+the double @kbd{C-g} feature without really meaning to. In that case,
+simply resume and answer @kbd{n} to both questions, and you will arrive
+at your former state. Presumably the quit you requested will happen
+soon.
+
+ The double-@kbd{C-g} feature may be turned off when Emacs is running under
+a window system, since the window system always enables you to kill Emacs
+or to create another window and run another program.
+
+@node Total Frustration,, Emergency Escape, Lossage
+@subsection Help for Total Frustration
+@cindex Eliza
+@cindex doctor
+
+ If using Emacs (or something else) becomes terribly frustrating and none
+of the techniques described above solve the problem, Emacs can still help
+you.
+
+ First, if the Emacs you are using is not responding to commands, type
+@kbd{C-g C-g} to get out of it and then start a new one.
+
+@findex doctor
+ Second, type @kbd{M-x doctor @key{RET}}.
+
+ The doctor will make you feel better. Each time you say something to
+the doctor, you must end it by typing @key{RET} @key{RET}. This lets the
+doctor know you are finished.
+
+@node Bugs,, Lossage, Top
+@section Reporting Bugs
+
+@cindex bugs
+ Sometimes you will encounter a bug in Emacs. Although we cannot promise
+we can or will fix the bug, and we might not even agree that it is a bug,
+we want to hear about bugs you encounter in case we do want to fix them.
+
+ To make it possible for us to fix a bug, you must report it. In order
+to do so effectively, you must know when and how to do it.
+
+@subsection When Is There a Bug
+
+ If Emacs executes an illegal instruction, or dies with an operating
+system error message that indicates a problem in the program (as opposed to
+something like ``disk full''), then it is certainly a bug.
+
+ If Emacs updates the display in a way that does not correspond to what is
+in the buffer, then it is certainly a bug. If a command seems to do the
+wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a
+case of incorrect display updating.
+
+ Taking forever to complete a command can be a bug, but you must make
+certain that it was really Emacs's fault. Some commands simply take a long
+time. Type @kbd{C-g} and then @kbd{C-h l} to see whether the input Emacs
+received was what you intended to type; if the input was such that you
+@var{know} it should have been processed quickly, report a bug. If you
+don't know whether the command should take a long time, find out by looking
+in the manual or by asking for assistance.
+
+ If a command you are familiar with causes an Emacs error message in a
+case where its usual definition ought to be reasonable, it is probably a
+bug.
+
+ If a command does the wrong thing, that is a bug. But be sure you know
+for certain what it ought to have done. If you aren't familiar with the
+command, or don't know for certain how the command is supposed to work,
+then it might actually be working right. Rather than jumping to
+conclusions, show the problem to someone who knows for certain.
+
+ Finally, a command's intended definition may not be best for editing
+with. This is a very important sort of problem, but it is also a matter of
+judgment. Also, it is easy to come to such a conclusion out of ignorance
+of some of the existing features. It is probably best not to complain
+about such a problem until you have checked the documentation in the usual
+ways, feel confident that you understand it, and know for certain that what
+you want is not available. If you are not sure what the command is
+supposed to do after a careful reading of the manual, check the index and
+glossary for any terms that may be unclear. If you still do not
+understand, this indicates a bug in the manual. The manual's job is to
+make everything clear. It is just as important to report documentation
+bugs as program bugs.
+
+ If the online documentation string of a function or variable disagrees
+with the manual, one of them must be wrong, so report the bug.
+
+@subsection How to Report a Bug
+
+@findex emacs-version
+ When you decide that there is a bug, it is important to report it and to
+report it in a way which is useful. What is most useful is an exact
+description of what commands you type, starting with the shell command to
+run Emacs, until the problem happens. Always include the version number
+of Emacs that you are using; type @kbd{M-x emacs-version} to print this.
+
+ The most important principle in reporting a bug is to report @var{facts},
+not hypotheses or categorizations. It is always easier to report the facts,
+but people seem to prefer to strain to posit explanations and report
+them instead. If the explanations are based on guesses about how Emacs is
+implemented, they will be useless; we will have to try to figure out what
+the facts must have been to lead to such speculations. Sometimes this is
+impossible. But in any case, it is unnecessary work for us.
+
+ For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh
+@key{RET}}, visiting a file which (you know) happens to be rather large,
+and Emacs prints out @samp{I feel pretty today}. The best way to report
+the bug is with a sentence like the preceding one, because it gives all the
+facts and nothing but the facts.
+
+ Do not assume that the problem is due to the size of the file and say,
+``When I visit a large file, Emacs prints out @samp{I feel pretty today}.''
+This is what we mean by ``guessing explanations''. The problem is just as
+likely to be due to the fact that there is a @samp{z} in the file name. If
+this is so, then when we got your report, we would try out the problem with
+some ``large file'', probably with no @samp{z} in its name, and not find
+anything wrong. There is no way in the world that we could guess that we
+should try visiting a file with a @samp{z} in its name.
+
+ Alternatively, the problem might be due to the fact that the file starts
+with exactly 25 spaces. For this reason, you should make sure that you
+inform us of the exact contents of any file that is needed to reproduce the
+bug. What if the problem only occurs when you have typed the @kbd{C-x a l}
+command previously? This is why we ask you to give the exact sequence of
+characters you typed since starting to use Emacs.
+
+ You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless
+you @i{know} that it makes no difference which visiting command is used.
+Similarly, rather than saying ``if I have three characters on the line,''
+say ``after I type @kbd{@key{RET} A B C @key{RET} C-p},'' if that is
+the way you entered the text.@refill
+
+ If you are not in Fundamental mode when the problem occurs, you should
+say what mode you are in.
+
+ If the manifestation of the bug is an Emacs error message, it is
+important to report not just the text of the error message but a backtrace
+showing how the Lisp program in Emacs arrived at the error. To make the
+backtrace, you must execute the Lisp expression
+@code{(setq @w{debug-on-error t})} before the error happens (that is to
+say, you must execute that expression and then make the bug happen). This
+causes the Lisp debugger to run (@pxref{Lisp Debug}). The debugger's
+backtrace can be copied as text into the bug report. This use of the
+debugger is possible only if you know how to make the bug happen again. Do
+note the error message the first time the bug happens, so if you can't make
+it happen again, you can report at least that.
+
+ Check whether any programs you have loaded into the Lisp world, including
+your init file, set any variables that may affect the functioning of
+Emacs. @xref{Init File}. Also, see whether the problem happens in a
+freshly started Emacs without loading your init file (start Emacs with
+the @code{-q} switch to prevent loading the init file). If the problem
+does @var{not} occur then, it is essential that we know the contents of
+any programs that you must load into the Lisp world in order to cause
+the problem to occur.
+
+ If the problem does depend on an init file or other Lisp programs that
+are not part of the standard Emacs system, then you should make sure it is
+not a bug in those programs by complaining to their maintainers first.
+After they verify that they are using Emacs in a way that is supposed to
+work, they should report the bug.
+
+ If you can tell us a way to cause the problem without visiting any files,
+please do so. This makes it much easier to debug. If you do need files,
+make sure you arrange for us to see their exact contents. For example, it
+can often matter whether there are spaces at the ends of lines, or a
+newline after the last line in the buffer (nothing ought to care whether
+the last line is terminated, but tell that to the bugs).
+
+@findex open-dribble-file
+@cindex dribble file
+ The easy way to record the input to Emacs precisely is to write a
+dribble file; execute the Lisp expression:
+
+@example
+(open-dribble-file "~/dribble")
+@end example
+
+@noindent
+using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer just after starting
+Emacs. From then on, all Emacs input will be written in the specified
+dribble file until the Emacs process is killed.
+
+@findex open-termscript
+@cindex termscript file
+ For possible display bugs, it is important to report the terminal type
+(the value of environment variable @code{TERM}), the complete termcap entry
+for the terminal from @file{/etc/termcap} (since that file is not identical
+on all machines), and the output that Emacs actually sent to the terminal.
+The way to collect this output is to execute the Lisp expression:
+
+@example
+(open-termscript "~/termscript")
+@end example
+
+@noindent using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer
+just after starting Emacs. From then on, all output from Emacs to the
+terminal will be written in the specified termscript file as well, until
+the Emacs process is killed. If the problem happens when Emacs starts
+up, put this expression into your init file so that the termscript file
+will be open when Emacs displays the screen for the first time.
+@xref{Init File}. Be warned: it is often difficult, and sometimes
+impossible, to fix a terminal-dependent bug without access to a terminal
+of the type that stimulates the bug.@refill
+
+The newsgroup @samp{comp.emacs.xemacs} may be used for bug reports,
+other discussions and requests for assistance.
+
+If you don't have access to this newgroup, you can subscribe to the
+mailing list version: the newsgroup is bidirectionally gatewayed into
+the mailing list @samp{xemacs@@xemacs.org}.
+
+To be added or removed from this mailing list, send mail to
+@samp{xemacs-request@@xemacs.org}. Do not send requests for addition
+to the mailing list itself.
+
+The mailing lists and newsgroups are archived on our anonymous FTP server,
+@samp{ftp.xemacs.org}, and at various other archive sites around the net. You
+should also check the @samp{FAQ} in @samp{/pub/xemacs} on our anonymous
+FTP server. It provides some introductory information and help for initial
+configuration problems.
projects / chise / xemacs-chise.git- / blobdiff