@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 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
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
@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
@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
impossible unless special pains are taken for the particular system
call within Emacs where the waiting occurs. We have done this for the
system calls that users are likely to want to quit from, but it's
-possible you will a case not handled. In one very common
+possible you will encounter a case not handled. In one very common
case---waiting for file input or output using NFS---Emacs itself knows
how to quit, but many NFS implementations simply do not allow user
programs to stop waiting for NFS when the NFS server is hung.
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
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.
@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
@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
@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)
@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
@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
@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.
@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")
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.
@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
@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
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
@lowersections
@end ifnottex
-@ignore
- arch-tag: c9cba76d-b2cb-4e0c-ae3f-19d5ef35817c
-@end ignore
HCoop / bpt / emacs.git / blobdiff