Initial git import

[sxemacs] / info / sxemacs / trouble.texi

@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 SXEmacs.  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