--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/xemacs/trouble.texi	Mon Aug 13 11:28:15 2007 +0200
@@ -0,0 +1,406 @@
+
+@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 @file{.emacs} file, set any variables that may affect the functioning
+of Emacs.  Also, see whether the problem happens in a freshly started Emacs
+without loading your @file{.emacs} 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 @file{.emacs} file so that the termscript file will
+be open when Emacs displays the screen for the first time.  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.