X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/51fb064bc72968e739e8dea580e58796c1a87f4c..d3658de7373f55d5f153748aafe82e5806672085:/doc/emacs/trouble.texi diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi index 4ea53ee9b0..ef8b5ab677 100644 --- a/doc/emacs/trouble.texi +++ b/doc/emacs/trouble.texi @@ -1,6 +1,7 @@ @c This is part of the Emacs manual. @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. +@c 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 +@c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @iftex @chapter Dealing with Common Problems @@ -30,7 +31,9 @@ invoked it (@code{abort-recursive-edit}). Either quit or abort, whichever makes sense (@code{keyboard-escape-quit}). @item M-x top-level Abort all recursive editing levels that are currently executing. -@item C-x u +@item C-/ +@itemx C-x u +@itemx C-_ Cancel a previously made change in the buffer contents (@code{undo}). @end table @@ -44,15 +47,17 @@ and cancels the command that invoked the recursive edit. @cindex quitting @kindex C-g Quitting with @kbd{C-g} is the way to get 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 give a command which takes a long time. In -particular, it is safe to quit out of a kill command; either your text -will @emph{all} still be in the buffer, or it will @emph{all} be in -the kill ring, or maybe both. Quitting an incremental search does -special things, documented under searching; it may take two successive -@kbd{C-g} characters to get out of a search (@pxref{Incremental -Search}). +command, or a numeric argument that you don't want. Furthermore, if +you are in the middle of a command that is running, @kbd{C-g} stops +the command in a relatively safe way. For example, if you quit out of +a kill command that is taking a long time, either your text will +@emph{all} still be in the buffer, or it will @emph{all} be in the +kill ring, or maybe both. If the region is active, @kbd{C-g} +deactivates the mark, unless Transient Mark mode is off +(@pxref{Persistent Mark}). If you are in the middle of an incremental +search, @kbd{C-g} does special things; it may take two successive +@kbd{C-g} characters to get out of a search. @xref{Incremental +Search}, for details. On MS-DOS, the character @kbd{C-@key{BREAK}} serves as a quit character like @kbd{C-g}. The reason is that it is not feasible, on MS-DOS, to @@ -66,7 +71,6 @@ with the user. By contrast, it @emph{is} feasible to recognize @xref{MS-DOS Keyboard}. @end ifnottex - @findex keyboard-quit @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 @@ -115,19 +119,20 @@ it executes as an ordinary command, and Emacs doesn't notice it until it is ready for the next command. @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-]} 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 take effect 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 + 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; it also exits the minibuffer if it is active. +@kbd{C-]} 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 take +effect 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 canceling + @kbd{C-/} (@code{undo}) is not strictly speaking a way of canceling a command, but you can think of it as canceling a command that already -finished executing. @xref{Undo}, for more information -about the undo facility. +finished executing. @xref{Undo}, for more information about the undo +facility. @node Lossage, Bugs, Quitting, Top @section Dealing with Emacs Trouble @@ -137,7 +142,7 @@ 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-e} to read the @file{PROBLEMS} file. +@kbd{C-h C-p} to read the @file{PROBLEMS} file. @menu * DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. @@ -157,26 +162,22 @@ in the Emacs distribution. Type @kbd{C-h C-f} to read the FAQ; type @cindex @key{BACKSPACE} vs @key{DEL} @cindex usual erasure key - Every keyboard has a large key, a little ways above the @key{RET} or -@key{ENTER} key, which you normally use outside Emacs 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}, -and when Emacs is properly configured for your terminal, it translates -that key into the character @key{DEL}. + Every keyboard has a large key, usually labelled @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}. When Emacs starts up on a graphical display, it determines -automatically which key should be @key{DEL}. In some unusual cases +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{DELETE} key as +what happened---Emacs ought to be treating the @key{Backspace} key as @key{DEL}, but it isn't. - On a graphical display, if the usual erasure key is labeled -@key{BACKSPACE} and there is a @key{DELETE} key elsewhere, but the -@key{DELETE} key deletes backward instead of forward, that too -suggests Emacs got the wrong information---but in the opposite sense. -It ought to be treating the @key{BACKSPACE} key as @key{DEL}, and -treating @key{DELETE} differently, but it isn't. + 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 for a Help command, like @kbd{Control-h}, instead of deleting a @@ -195,9 +196,9 @@ 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{DELETE} +(@pxref{Init File}). For the first case above, where @key{Backspace} deletes forwards instead of backwards, use this line to make -@key{DELETE} act as @key{DEL} (resulting in behavior compatible +@key{Backspace} act as @key{DEL} (resulting in behavior compatible with Emacs 20 and previous versions): @lisp @@ -205,8 +206,7 @@ with Emacs 20 and previous versions): @end lisp @noindent -For the other two cases, where @key{BACKSPACE} ought to act as -@key{DEL}, use this line: +For the other two cases, use this line: @lisp (normal-erase-is-backspace-mode 1) @@ -219,15 +219,6 @@ customize the variable @code{normal-erase-is-backspace}: the value @key{DEL}, and @code{nil} specifies the other mode. @xref{Easy Customization}. - On a graphical display, it can also happen that the usual erasure key -is labeled @key{BACKSPACE}, there is a @key{DELETE} key elsewhere, and -both keys delete forward. This probably means that someone has -redefined your @key{BACKSPACE} key as a @key{DELETE} key. With X, -this is typically done with a command to the @code{xmodmap} program -when you start the server or log in. The most likely motive for this -customization was to support old versions of Emacs, so we recommend -you simply remove it now. - @node Stuck Recursive @subsection Recursive Editing Levels @@ -418,29 +409,76 @@ say something to the psychotherapist, you must end it by typing @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 problems you encounter. Often we agree -they are bugs and 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. - - Before reporting a bug, it is a good idea to see if it is already -known. You can find the list of known problems in the file -@file{etc/PROBLEMS} in the Emacs distribution; type @kbd{C-h C-e} to read -it. Some additional user-level problems can be found in @ref{Bugs and -problems, , Bugs and problems, efaq, GNU Emacs FAQ}. Looking up your -problem in these two documents might provide you with a solution or a -work-around, or give you additional information about related issues. + If you think you have found a bug in Emacs, please report it. We +cannot promise to fix it, or always to agree that it is a bug, but we +certainly want to hear about it. The same applies for new features +you would like to see added. The following sections will help you to +construct an effective bug report. @menu -* Criteria: Bug Criteria. Have you really found a bug? -* Understanding Bug Reporting:: How to report a bug effectively. -* Checklist:: Steps to follow for a good bug report. -* Sending Patches:: How to send a patch for GNU Emacs. +* Known Problems:: How to read about known problems and bugs. +* Criteria: Bug Criteria. Have you really found a bug? +* Understanding Bug Reporting:: How to report a bug effectively. +* Checklist:: Steps to follow for a good bug report. +* Sending Patches:: How to send a patch for GNU Emacs. @end menu +@node Known Problems +@subsection Reading Existing Bug Reports and Known Problems + + Before reporting a bug, if at all possible please check to see if it +is already known about. Indeed, it may already have been fixed in a +later release of Emacs, or in the development version. Here is a list +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. + +@item +Some additional user-level problems can be found in @ref{Bugs and +problems, , Bugs and problems, efaq, GNU Emacs FAQ}. + +@item +The @samp{bug-gnu-emacs} mailing list (also available as the newsgroup +@samp{gnu.emacs.bug}). This is where you will find most Emacs bug +reports. 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. + +@item +The bug tracker at @url{http://debbugs.gnu.org}. From early 2008, +reports from the @samp{bug-gnu-emacs} list have 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. + +@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}. + +@item +The @samp{emacs-devel} mailing list. Sometimes people report bugs to +this mailing list. This is not the main purpose of the list, however, +and it is much better to send bug reports to the bug list. You should +not feel obliged to read this list before reporting a bug. + +@end itemize + + @node Bug Criteria @subsection When Is There a Bug @@ -549,58 +587,82 @@ well. @subsection Checklist for Bug Reports @cindex reporting bugs - The best way to send a bug report is to mail it electronically to the -Emacs maintainers at @email{bug-gnu-emacs@@gnu.org}, or to -@email{emacs-pretest-bug@@gnu.org} if you are pretesting an Emacs beta -release. (If you want to suggest a change as an improvement, use the -same address.) - - If you'd like to read the bug reports, you can find them on the -newsgroup @samp{gnu.emacs.bug}; keep in mind, however, that as a -spectator you should not criticize anything about what you see there. -The purpose of bug reports is to give information to the Emacs -maintainers. Spectators are welcome only as long as they do not -interfere with this. In particular, some bug reports contain fairly -large amounts of data; spectators should not complain about this. - - Please do not post bug reports using netnews; mail is more reliable -than netnews about reporting your correct address, which we may need -in order to ask you for more information. If your data is more than -500,000 bytes, please don't include it directly in the bug report; -instead, offer to send it on request, or make it available by ftp and -say where. + + Before reporting a bug, first try to see if the problem has already +been reported (@pxref{Known Problems}). + +If you are able to, try the latest release of Emacs to see if the +problem has already been fixed. Even better is to try the latest +development version. We recognize that this is not easy for some +people, so do not feel that you absolutely must do this before making +a report. @findex report-emacs-bug - A convenient way to send a bug report for Emacs is to use the command -@kbd{M-x report-emacs-bug}. This sets up a mail buffer (@pxref{Sending -Mail}) and automatically inserts @emph{some} of the essential -information. However, it cannot supply all the necessary information; -you should still read and follow the guidelines below, so you can enter -the other crucial information by hand before you send the message. + The best way to write a bug report for Emacs is to use the command +@kbd{M-x report-emacs-bug}. This sets up a mail buffer +(@pxref{Sending Mail}) and automatically inserts @emph{some} of the +essential information. However, it cannot supply all the necessary +information; you should still read and follow the guidelines below, so +you can enter the other crucial information by hand before you send +the message. You may feel that some of the information inserted by +@kbd{M-x report-emacs-bug} is not relevant, but unless you are +absolutely sure it is best to leave it, so that the developers can +decide for themselves. + +When you have finished writing your report, type @kbd{C-c C-c} and it +will be sent to the Emacs maintainers at @email{bug-gnu-emacs@@gnu.org}. +(If you want to suggest an improvement or new feature, use the same +address.) If you cannot send mail from inside Emacs, you can copy the +text of your report to your normal mail client and send it to that +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 +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. + +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 +true, but we ask you not to post bug reports (or replies) via the +newsgroup. It can make it much harder to contact you if we need to ask +for more information, and it does not integrate well with the bug +tracker. + +If your data is more than 500,000 bytes, please don't include it +directly in the bug report; instead, offer to send it on request, or +make it available by ftp and say where. To enable maintainers to investigate a bug, your report should include all these things: @itemize @bullet @item -The version number of Emacs. Without this, we won't know whether there -is any point in looking for the bug in the current version of GNU -Emacs. +The version number of Emacs. Without this, we won't know whether there is any +point in looking for the bug in the current version of GNU Emacs. -You can get the version number by typing @kbd{M-x emacs-version -@key{RET}}. If that command does not work, you probably have something -other than GNU Emacs, so you will have to report the bug somewhere -else. +@kbd{M-x report-emacs-bug} includes this information automatically, +but if you are not using that command for your report you can get the +version number by typing @kbd{M-x emacs-version @key{RET}}. If that +command does not work, you probably have something other than GNU +Emacs, so you will have to report the bug somewhere else. @item The type of machine you are using, and the operating system name and -version number. @kbd{M-x emacs-version @key{RET}} provides this -information too. Copy its output from the @samp{*Messages*} buffer, so -that you get it all and get it accurately. +version number (again, automatically included by @kbd{M-x +report-emacs-bug}). @kbd{M-x emacs-version @key{RET}} provides this +information too. Copy its output from the @samp{*Messages*} buffer, +so that you get it all and get it accurately. @item The operands given to the @code{configure} command when Emacs was -installed. +installed (automatically included by @kbd{M-x report-emacs-bug}). @item A complete list of any modifications you have made to the Emacs source. @@ -630,12 +692,15 @@ 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. @findex open-dribble-file @cindex dribble file @cindex logging keystrokes -The easy way to record the input to Emacs precisely is to write a -dribble file. To start the file, execute the Lisp expression +One way to record the input to Emacs precisely is to write a dribble +file. To start the file, execute the Lisp expression @example (open-dribble-file "~/dribble") @@ -746,7 +811,7 @@ 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 +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. @@ -918,12 +983,10 @@ your best to help. @itemize @bullet @item Send an explanation with your changes of what problem they fix or what -improvement they bring about. For a bug fix, just include a copy of the -bug report, and explain why the change fixes the bug. - -(Referring to a bug report is not as good as including it, because then -we will have to look it up, and we have probably already deleted it if -we've already fixed the bug.) +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. @item Always include a proper bug report for the problem you think you have @@ -1019,6 +1082,7 @@ form that is clearly safe to install. @node Contributing, Service, Bugs, Top @section Contributing to Emacs Development +@cindex contributing to Emacs If you would like to help pretest Emacs releases to assure they work well, or if you would like to work on improving Emacs, please contact @@ -1033,11 +1097,14 @@ you have not yet started work, it is useful to contact possible to suggest ways to make your extension fit in better with the rest of Emacs. -The development version of Emacs can be downloaded from the CVS +The development version of Emacs can be downloaded from the repository where it is actively maintained by a group of developers. See the Emacs project page @url{http://savannah.gnu.org/projects/emacs/} for details. +For more information on how to contribute, see the @file{etc/CONTRIBUTE} +file in the Emacs distribution. + @node Service, Copying, Contributing, Top @section How To Get Help with GNU Emacs @@ -1061,6 +1128,3 @@ Emacs distribution. @lowersections @end ifnottex -@ignore - arch-tag: c9cba76d-b2cb-4e0c-ae3f-19d5ef35817c -@end ignore