@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, 2009, 2010, 2011, 2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 Free Software
+@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@iftex
@chapter Dealing with Common Problems
@raisesections
@end ifnottex
-@node Quitting, Lossage, Customization, Top
+@node Quitting
@section Quitting and Aborting
@cindex quitting
@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
@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.
+(@pxref{Disabled Transient Mark}). If you are in the middle of an
+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.
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
finished executing. @xref{Undo}, for more information about the undo
facility.
-@node Lossage, Bugs, Quitting, Top
+@node Lossage
@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.
* Screen Garbled:: Garbage on the screen.
* Text Garbled:: Garbage in the text.
* Memory Full:: How to cope when you run out of memory.
+* Crashing:: What Emacs does when it crashes.
* 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 labelled @key{Backspace},
+ 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
-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.
+ On a text 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
if Emacs starts in the wrong mode, this should switch to the right
-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.
+mode. On a text 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)
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
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
editing in the same Emacs session.
Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run
-out of memory, because the buffer menu needs a fair amount of memory
+out of memory, because the Buffer Menu needs a fair amount of memory
itself, and the reserve supply may not be enough.
+@node Crashing
+@subsection When Emacs Crashes
+
+@cindex crash report
+@cindex backtrace
+@cindex @file{emacs_backtrace.txt} file, MS-Windows
+ Emacs is not supposed to crash, but if it does, it produces a
+@dfn{crash report} prior to exiting. The crash report is printed to
+the standard error stream. If Emacs was started from a graphical
+desktop on a GNU or Unix system, the standard error stream is commonly
+redirected to a file such as @file{~/.xsession-errors}, so you can
+look for the crash report there. On MS-Windows, the crash report is
+written to a file named @file{emacs_backtrace.txt} in the current
+directory of the Emacs process, in addition to the standard error
+stream.
+
+ The format of the crash report depends on the platform. On some
+platforms, such as those using the GNU C Library, the crash report
+includes a @dfn{backtrace} describing the execution state prior to
+crashing, which can be used to help debug the crash. Here is an
+example for a GNU system:
+
+@example
+Fatal error 11: Segmentation fault
+Backtrace:
+emacs[0x5094e4]
+emacs[0x4ed3e6]
+emacs[0x4ed504]
+/lib64/libpthread.so.0[0x375220efe0]
+/lib64/libpthread.so.0(read+0xe)[0x375220e08e]
+emacs[0x509af6]
+emacs[0x5acc26]
+@dots{}
+@end example
+
+@noindent
+The number @samp{11} is the system signal number corresponding to the
+crash---in this case a segmentation fault. The hexadecimal numbers
+are program addresses, which can be associated with source code lines
+using a debugging tool. For example, the GDB command
+@samp{list *0x509af6} prints the source-code lines corresponding to
+the @samp{emacs[0x509af6]} entry. If your system has the
+@command{addr2line} utility, the following shell command outputs a
+backtrace with source-code line numbers:
+
+@example
+sed -n 's/.*\[\(.*\)]$/\1/p' @var{backtrace} |
+ addr2line -Cfip -e @var{bindir}/@var{emacs-binary}
+@end example
+
+@noindent
+Here, @var{backtrace} is the name of a text file containing a copy of
+the backtrace, @var{bindir} is the name of the directory that
+contains the Emacs executable, and @var{emacs-binary} is the name of
+the Emacs executable file, normally @file{emacs} on GNU and Unix
+systems and @file{emacs.exe} on MS-Windows and MS-DOS.
+
+@cindex core dump
+ Optionally, Emacs can generate a @dfn{core dump} when it crashes, on
+systems that support core files. A core dump is a file containing
+voluminous data about the state of the program prior to the crash,
+usually examined by loading it into a debugger such as GDB@. On many
+platforms, core dumps are disabled by default, and you must explicitly
+enable them by running the shell command @samp{ulimit -c unlimited}
+(e.g., in your shell startup script).
+
@node After a Crash
@subsection Recovery After a Crash
@file{core.emacs}, so that another crash won't overwrite it.
To use this script, run @code{gdb} with the file name of your Emacs
-executable and the file name of the core dump, e.g. @samp{gdb
+executable and the file name of the core dump, e.g., @samp{gdb
/usr/bin/emacs core.emacs}. At the @code{(gdb)} prompt, load the
recovery script: @samp{source /usr/src/emacs/etc/emacs-buffer.gdb}.
Then type the command @code{ybuffer-list} to see which buffers are
@node Emergency Escape
@subsection Emergency Escape
- On text-only terminals, the @dfn{emergency escape} feature suspends
-Emacs immediately if you type @kbd{C-g} a second time before Emacs can
+ On text terminals, the @dfn{emergency escape} feature suspends Emacs
+immediately if you type @kbd{C-g} a second time before Emacs can
actually respond to the first one by quitting. This is so you can
always get out of GNU Emacs no matter how badly it might be hung.
When things are working properly, Emacs recognizes and handles the
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
+@node Bugs
@section Reporting Bugs
@cindex bugs
@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. User tags, applied
+by the Emacs maintainers, are shown by @kbd{M-x debbugs-gnu-usertags}.
+
@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
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
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
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.
+text of your report to your normal mail client (if your system
+supports it, you can type @kbd{C-c m} to have Emacs do this for you)
+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
+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
The type of machine you are using, and the operating system name and
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,
+information too. Copy its output from the @file{*Messages*} buffer,
so that you get it all and get it accurately.
@item
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
@cindex logging keystrokes
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")
-@end example
-
-@noindent
-using @kbd{M-:} or from the @samp{*scratch*} buffer just after
-starting Emacs. From then on, Emacs copies all your input to the
+file. To start the file, use the @kbd{M-x open-dribble-file
+@key{RET}} command. From then on, Emacs copies all your input to the
specified dribble file until the Emacs process is killed.
@item
@end example
@noindent
-using @kbd{M-:} or from the @samp{*scratch*} buffer just after
+using @kbd{M-:} or from the @file{*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
to display your locale settings.
You can use the @kbd{M-!} command to execute these commands from
-Emacs, and then copy the output from the @samp{*Messages*} buffer into
+Emacs, and then copy the output from the @file{*Messages*} buffer into
the bug report. Alternatively, @kbd{M-x getenv @key{RET} LC_ALL
@key{RET}} will display the value of @code{LC_ALL} in the echo area, and
-you can copy its output from the @samp{*Messages*} buffer.
+you can copy its output from the @file{*Messages*} buffer.
@item
A description of what behavior you observe that you believe is
-incorrect. For example, ``The Emacs process gets a fatal signal,'' or,
+incorrect. For example, ``The Emacs process gets a fatal signal'', or,
``The resulting text is as follows, which I think is wrong.''
Of course, if the bug is that Emacs gets a fatal signal, then one can't
backtrace showing how the Lisp program in Emacs arrived at the error.
To get the error message text accurately, copy it from the
-@samp{*Messages*} buffer into the bug report. Copy all of it, not just
+@file{*Messages*} buffer into the bug report. Copy all of it, not just
part.
@findex toggle-debug-on-error
This backtrace is useful for debugging such long loops, so if you can
produce it, copy it into the bug report.
+@vindex debug-on-event
+If you cannot get Emacs to respond to @kbd{C-g} (e.g., because
+@code{inhibit-quit} is set), then you can try sending the signal
+specified by @code{debug-on-event} (default SIGUSR2) from outside
+Emacs to cause it to enter the debugger.
+
@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
are available in the file @file{etc/DEBUG} in the Emacs distribution.
That file also includes instructions for investigating problems
whereby Emacs stops responding (many people assume that Emacs is
-``hung,'' whereas in fact it might be in an infinite loop).
+``hung'', whereas in fact it might be in an infinite loop).
To find the file @file{etc/DEBUG} in your Emacs installation, use the
directory name stored in the variable @code{data-directory}.
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
form that is clearly safe to install.
@end itemize
-@node Contributing, Service, Bugs, Top
+@node Contributing
@section Contributing to Emacs Development
@cindex contributing to Emacs
For more information on how to contribute, see the @file{etc/CONTRIBUTE}
file in the Emacs distribution.
-@node Service, Copying, Contributing, Top
+@node Service
@section How To Get Help with GNU Emacs
If you need help installing, using or changing GNU Emacs, there are two
@ifnottex
@lowersections
@end ifnottex
-