diff options
Diffstat (limited to 'doc/emacs/trouble.texi')
| -rw-r--r-- | doc/emacs/trouble.texi | 296 |
1 files changed, 138 insertions, 158 deletions
diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi index ae7550d0fa..8cb5ab44a2 100644 --- a/doc/emacs/trouble.texi +++ b/doc/emacs/trouble.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @iftex @@ -40,8 +40,8 @@ Cancel a previously made change in the buffer contents (@code{undo}). @dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]} or @kbd{M-x top-level}. Quitting cancels a partially typed command, or one which is still running. Aborting exits a recursive editing level -and cancels the command that invoked the recursive edit. -(@xref{Recursive Edit}.) +and cancels the command that invoked the recursive edit +(@pxref{Recursive Edit}). @cindex quitting @kindex C-g @@ -54,7 +54,7 @@ a kill command that is taking a long time, either your text will kill ring, or maybe both. If the region is active, @kbd{C-g} deactivates the mark, unless Transient Mark mode is off (@pxref{Disabled Transient Mark}). If you are in the middle of an -incremental search, @kbd{C-g} does special things; it may take two +incremental search, @kbd{C-g} behaves specially; it may take two successive @kbd{C-g} characters to get out of a search. @xref{Incremental Search}, for details. @@ -136,12 +136,12 @@ facility. @node Lossage, Bugs, Quitting, Top @section Dealing with Emacs Trouble - This section describes various conditions in which Emacs fails to work -normally, and how to recognize them and correct them. For a list of -additional problems you might encounter, see @ref{Bugs and problems, , -Bugs and problems, efaq, GNU Emacs FAQ}, and the file @file{etc/PROBLEMS} -in the Emacs distribution. Type @kbd{C-h C-f} to read the FAQ; type -@kbd{C-h C-p} to read the @file{PROBLEMS} file. + This section describes how to recognize and deal with situations in +which Emacs does not work as you expect, such as keyboard code mixups, +garbled displays, running out of memory, and crashes and hangs. + + @xref{Bugs}, for what to do when you think you have found a bug in +Emacs. @menu * DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. @@ -150,40 +150,35 @@ in the Emacs distribution. Type @kbd{C-h C-f} to read the FAQ; type * Text Garbled:: Garbage in the text. * Memory Full:: How to cope when you run out of memory. * After a Crash:: Recovering editing in an Emacs session that crashed. -* Emergency Escape:: Emergency escape--- - What to do if Emacs stops responding. -* Total Frustration:: When you are at your wits' end. +* Emergency Escape:: What to do if Emacs stops responding. @end menu @node DEL Does Not Delete @subsection If @key{DEL} Fails to Delete @cindex @key{DEL} vs @key{BACKSPACE} @cindex @key{BACKSPACE} vs @key{DEL} -@cindex usual erasure key Every keyboard has a large key, usually labeled @key{Backspace}, which is ordinarily used to erase the last character that you typed. -We call this key @dfn{the usual erasure key}. In Emacs, it is -supposed to be equivalent to @key{DEL}. +In Emacs, this key is supposed to be equivalent to @key{DEL}. When Emacs starts up on a graphical display, it determines automatically which key should be @key{DEL}. In some unusual cases, -Emacs gets the wrong information from the system. If the usual -erasure key deletes forwards instead of backwards, that is probably -what happened---Emacs ought to be treating the @key{Backspace} key as -@key{DEL}, but it isn't. +Emacs gets the wrong information from the system, and @key{Backspace} +ends up deleting forwards instead of backwards. Some keyboards also have a @key{Delete} key, which is ordinarily used to delete forwards. If this key deletes backward in Emacs, that too suggests Emacs got the wrong information---but in the opposite sense. - On a text-only terminal, if you find the usual erasure key prompts + On a text-only terminal, if you find that @key{Backspace} prompts for a Help command, like @kbd{Control-h}, instead of deleting a character, it means that key is actually sending the @key{BS} character. Emacs ought to be treating @key{BS} as @key{DEL}, but it isn't. +@findex normal-erase-is-backspace-mode In all of those cases, the immediate remedy is the same: use the command @kbd{M-x normal-erase-is-backspace-mode}. This toggles between the two modes that Emacs supports for handling @key{DEL}, so @@ -192,13 +187,10 @@ mode. On a text-only terminal, if you want to ask for help when @key{BS} is treated as @key{DEL}, use @key{F1}; @kbd{C-?} may also work, if it sends character code 127. -@findex normal-erase-is-backspace-mode - To fix the problem automatically for every Emacs session, you can -put one of the following lines into your @file{.emacs} file -(@pxref{Init File}). For the first case above, where @key{Backspace} -deletes forwards instead of backwards, use this line to make -@key{Backspace} act as @key{DEL} (resulting in behavior compatible -with Emacs 20 and previous versions): + To fix the problem in every Emacs session, put one of the following +lines into your initialization file (@pxref{Init File}). For the +first case above, where @key{Backspace} deletes forwards instead of +backwards, use this line to make @key{Backspace} act as @key{DEL}: @lisp (normal-erase-is-backspace-mode 0) @@ -224,12 +216,12 @@ Customization}. Recursive editing levels are important and useful features of Emacs, but they can seem like malfunctions if you do 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}. + 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}. @xref{Recursive Edit}. @node Screen Garbled @subsection Garbage on the Screen @@ -244,12 +236,9 @@ the following section.) 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. 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, it is likely to be a bad terminfo entry, -though it could also be due to a bug in Emacs that appears for -terminals that have or that lack specific features. +one of its sections. If you seem to be using the right terminfo +entry, it is possible that there is a bug in the terminfo entry, or a +bug in Emacs that appears for certain terminal types. @node Text Garbled @subsection Garbage in the Text @@ -385,25 +374,6 @@ program. emergency escape---but there are cases where it won't work, when system call hangs or when Emacs is stuck in a tight loop in C code. -@node Total Frustration -@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 Emacs psychotherapist will help you feel better. Each time you -say something to the psychotherapist, you must end it by typing -@key{RET} @key{RET}. This indicates you are finished typing. - @node Bugs, Contributing, Lossage, Top @section Reporting Bugs @@ -432,41 +402,51 @@ of the main places you can read about known issues: @itemize @item -The @file{etc/PROBLEMS} file in the Emacs distribution; type @kbd{C-h -C-p} to read it. This file contains a list of particularly well-known -issues that have been encountered in compiling, installing and running -Emacs. Often, there are suggestions for workarounds and solutions. +The @file{etc/PROBLEMS} file; type @kbd{C-h C-p} to read it. This +file contains a list of particularly well-known issues that have been +encountered in compiling, installing and running Emacs. Often, there +are suggestions for workarounds and solutions. @item Some additional user-level problems can be found in @ref{Bugs and problems, , Bugs and problems, efaq, GNU Emacs FAQ}. +@cindex bug tracker +@item +The GNU Bug Tracker at @url{http://debbugs.gnu.org}. Emacs bugs are +filed in the tracker under the @samp{emacs} package. The tracker +records information about the status of each bug, the initial bug +report, and the follow-up messages by the bug reporter and Emacs +developers. You can search for bugs by subject, severity, and other +criteria. + +@cindex debbugs package +Instead of browsing the bug tracker as a webpage, you can browse it +from Emacs using the @code{debbugs} package, which can be downloaded +via the Package Menu (@pxref{Packages}). This package provides the +command @kbd{M-x debbugs-gnu} to list bugs, and @kbd{M-x +debbugs-gnu-search} to search for a specific bug. + @item The @samp{bug-gnu-emacs} mailing list (also available as the newsgroup @samp{gnu.emacs.bug}). You can read the list archives at -@url{http://lists.gnu.org/mailman/listinfo/bug-gnu-emacs}. If you -like, you can also subscribe to the list. Be aware that the sole -purpose of this list is to provide the Emacs maintainers with -information about bugs and feature requests. Reports may contain -fairly large amounts of data; spectators should not complain about -this. +@url{http://lists.gnu.org/mailman/listinfo/bug-gnu-emacs}. This list +works as a ``mirror'' of the Emacs bug reports and follow-up messages +which are sent to the bug tracker. It also contains old bug reports +from before the bug tracker was introduced (in early 2008). -@item -The bug tracker at @url{http://debbugs.gnu.org}. From early 2008, -reports from the @samp{bug-gnu-emacs} list have also been sent here. -The tracker contains the same information as the mailing list, just in -a different format. You may prefer to browse and read reports using -the tracker. +If you like, you can subscribe to the list. Be aware that its purpose +is to provide the Emacs maintainers with information about bugs and +feature requests, so reports may contain fairly large amounts of data; +spectators should not complain about this. @item The @samp{emacs-pretest-bug} mailing list. This list is no longer used, and is mainly of historical interest. At one time, it was used for bug reports in development (i.e., not yet released) versions of Emacs. You can read the archives for 2003 to mid 2007 at -@url{http://lists.gnu.org/archive/html/emacs-pretest-bug/}. From -late 2007 to mid 2008, the address was an alias for the -@samp{emacs-devel} mailing list. From mid 2008 onwards, it has been -an alias for @samp{bug-gnu-emacs}. +@url{http://lists.gnu.org/archive/html/emacs-pretest-bug/}. Nowadays, +it is an alias for @samp{bug-gnu-emacs}. @item The @samp{emacs-devel} mailing list. Sometimes people report bugs to @@ -485,33 +465,32 @@ fault''), or exits 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. + If the Emacs display does not correspond properly to the contents of +the buffer, then it is a bug. But you should check that features like +buffer narrowing (@pxref{Narrowing}), which can hide parts of the +buffer or change how it is displayed, are not responsible. 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} (@kbd{C-@key{BREAK}} on MS-DOS) 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 @emph{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. +sure that it is really Emacs's fault. Some commands simply take a +long time. Type @kbd{C-g} (@kbd{C-@key{BREAK}} on MS-DOS) 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 @emph{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. + 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, it might actually be working right. If in doubt, +read the command's documentation (@pxref{Name Help}). - Finally, a command's intended definition may not be the best -possible definition for editing with. This is a very important sort -of problem, but it is also a matter of judgment. Also, it is easy to + A command's intended definition may not be the best possible +definition 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 @@ -527,59 +506,61 @@ you should report. The manual's job is to make everything clear to people who are not Emacs experts---including you. It is just as important to report documentation bugs as program bugs. - If the on-line documentation string of a function or variable disagrees + If the built-in documentation for a function or variable disagrees with the manual, one of them must be wrong; that is a bug. @node Understanding Bug Reporting @subsection Understanding Bug Reporting @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. + 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. The most important principle in reporting a bug is to report -@emph{facts}. Hypotheses and verbal descriptions are no substitute for -the detailed raw data. Reporting the facts is straightforward, but many -people strain to posit explanations and report them instead of the -facts. If the explanations are based on guesses about how Emacs is -implemented, they will be useless; meanwhile, lacking the facts, we will -have no real information about the bug. +@emph{facts}. Hypotheses and verbal descriptions are no substitute +for the detailed raw data. Reporting the facts is straightforward, +but many people strain to posit explanations and report them instead +of the facts. If the explanations are based on guesses about how +Emacs is implemented, they will be useless; meanwhile, lacking the +facts, we will have no real information about the bug. If you want to +actually @emph{debug} the problem, and report explanations that are +more than guesses, that is useful---but please include the raw facts +as well. 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 displays @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. - - A bad way would be to assume that the problem is due to the size of -the file and say, ``I visited a large file, and Emacs displayed @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 see any problem. There -is no way in the world that we could guess that we should try visiting a +large, and Emacs displays @samp{I feel pretty today}. The bug report +would need to provide all that information. You should not assume +that the problem is due to the size of the file and say, ``I visited a +large file, and Emacs displayed @samp{I feel pretty today}.'' This is +what we mean by ``guessing explanations.'' The problem might 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 see any +problem. There is no way 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 C-a} -command previously? This is why we ask you to give the exact sequence of -characters you typed since starting the Emacs session. - - You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless -you @emph{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. - - So please don't guess any explanations when you report a bug. If you -want to actually @emph{debug} the problem, and report explanations that -are more than guesses, that is useful---but please include the facts as -well. + You should not even say ``visit a file'' instead of @kbd{C-x C-f}. +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. + + If possible, try quickly to reproduce the bug by invoking Emacs with +@command{emacs -Q} (so that Emacs starts with no initial +customizations; @pxref{Initial Options}), and repeating the steps that +you took to trigger the bug. If you can reproduce the bug this way, +that rules out bugs in your personal customizations. Then your bug +report should begin by stating that you started Emacs with +@command{emacs -Q}, followed by the exact sequence of steps for +reproducing the bug. If possible, inform us of the exact contents of +any file that is needed to reproduce the bug. + + Some bugs are not reproducible from @command{emacs -Q}; some are not +easily reproducible at all. In that case, you should report what you +have---but, as before, please stick to the raw facts about what you +did to trigger the bug the first time. @node Checklist @subsection Checklist for Bug Reports @@ -616,15 +597,14 @@ address. Or you can simply send an email to that address describing the problem. Your report will be sent to the @samp{bug-gnu-emacs} mailing list, and -stored in the tracker at @url{http://debbugs.gnu.org}. Please try to +stored in the GNU Bug Tracker at @url{http://debbugs.gnu.org}. Please include a valid reply email address, in case we need to ask you for more information about your report. Submissions are moderated, so there may be a delay before your report appears. -You do not need to know how the @url{http://debbugs.gnu.org} bug -tracker works in order to report a bug, but if you want to, you can -read the tracker's online documentation to see the various features -you can use. +You do not need to know how the Gnu Bug Tracker works in order to +report a bug, but if you want to, you can read the tracker's online +documentation to see the various features you can use. All mail sent to the @samp{bug-gnu-emacs} mailing list is also gatewayed to the @samp{gnu.emacs.bug} newsgroup. The reverse is also @@ -689,10 +669,10 @@ newline after the last line in the buffer (nothing ought to care whether the last line is terminated, but try telling the bugs that). @item -The precise commands we need to type to reproduce the bug. -If at all possible, give a full recipe for an Emacs started with the -@samp{-Q} option (@pxref{Initial Options}). This bypasses your -@file{.emacs} customizations. +The precise commands we need to type to reproduce the bug. If at all +possible, give a full recipe for an Emacs started with the @samp{-Q} +option (@pxref{Initial Options}). This bypasses your personal +customizations. @findex open-dribble-file @cindex dribble file @@ -722,8 +702,8 @@ using @kbd{M-:} or from the @samp{*scratch*} buffer just after starting Emacs. From then on, Emacs copies all terminal output to 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. +your Emacs initialization 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 @@ -806,13 +786,13 @@ produce it, copy it into the bug report. @item 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 files). If -the problem does @emph{not} occur then, you must report the precise -contents of any programs that you must load into the Lisp world in order -to cause the problem to occur. +including your initialization 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 initialization file (start +Emacs with the @code{-Q} switch to prevent loading the init files). +If the problem does @emph{not} occur then, you must report the precise +contents of any programs that you must load into the Lisp world in +order to cause the problem to occur. @item If the problem does depend on an init file or other Lisp programs that @@ -983,8 +963,8 @@ your best to help. Send an explanation with your changes of what problem they fix or what improvement they bring about. For a fix for an existing bug, it is best to reply to the relevant discussion on the @samp{bug-gnu-emacs} -list, or item in the @url{http://debbugs.gnu.org} tracker. Explain -why your change fixes the bug. +list, or the bug entry in the GNU Bug Tracker at +@url{http://debbugs.gnu.org}. Explain why your change fixes the bug. @item Always include a proper bug report for the problem you think you have |