diff options
author | Dave Love <[email protected]> | 1999-09-29 15:17:24 +0000 |
---|---|---|
committer | Dave Love <[email protected]> | 1999-09-29 15:17:24 +0000 |
commit | 6bf7aab68402fd010eae5d280350bd399014406a (patch) | |
tree | 625ed090fc4abe8605e63f152740733c70314c4a /man/trouble.texi | |
parent | f58395f66db524e38e011f95f292d7abcc1fe2d1 (diff) |
#
Diffstat (limited to 'man/trouble.texi')
-rw-r--r-- | man/trouble.texi | 972 |
1 files changed, 972 insertions, 0 deletions
diff --git a/man/trouble.texi b/man/trouble.texi new file mode 100644 index 0000000000..e201b6311a --- /dev/null +++ b/man/trouble.texi @@ -0,0 +1,972 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@iftex +@chapter Dealing with Common Problems + + If you type an Emacs command you did not intend, the results are often +mysterious. This chapter tells what you can do to cancel your mistake or +recover from a mysterious situation. Emacs bugs and system crashes are +also considered. +@end iftex + +@node Quitting, Lossage, Customization, Top +@section Quitting and Aborting +@cindex quitting + +@table @kbd +@item C-g +@itemx C-@key{BREAK} (MS-DOS) +Quit. Cancel running or partially typed command. +@item C-] +Abort innermost recursive editing level and cancel the command which +invoked it (@code{abort-recursive-edit}). +@item @key{ESC} @key{ESC} @key{ESC} +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 +Cancel a previously made change in the buffer contents (@code{undo}). +@end table + + There are two ways of canceling commands which are not finished +executing: @dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with +@kbd{C-]} or @kbd{M-x top-level}. Quitting cancels a partially typed +command or one which is already running. Aborting exits a recursive +editing level and cancels the command that invoked the recursive edit. +(@xref{Recursive Edit}.) + +@cindex quitting +@kindex C-g + Quitting with @kbd{C-g} is used for getting rid of a partially typed +command, or a numeric argument that you don't want. It also stops a +running command in the middle in a relatively safe way, so you can use +it if you accidentally give a command which takes a long time. In +particular, it is safe to quit out of killing; 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; in general, it may take two +successive @kbd{C-g} characters to get out of a search +(@pxref{Incremental Search}). + + 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 +recognize @kbd{C-g} while a command is running, between interactions +with the user. By contrast, it @emph{is} feasible to recognize +@kbd{C-@key{BREAK}} at all times. @xref{MS-DOS Input}. + + @kbd{C-g} works by setting the variable @code{quit-flag} to @code{t} +the instant @kbd{C-g} is typed; Emacs Lisp checks this variable +frequently and quits if it is non-@code{nil}. @kbd{C-g} is only +actually executed as a command if you type it while Emacs is waiting for +input. + + If you quit with @kbd{C-g} a second time before the first @kbd{C-g} is +recognized, you activate the ``emergency escape'' feature and return to +the shell. @xref{Emergency Escape}. + +@cindex NFS and quitting + There may be times when you cannot quit. When Emacs is waiting for +the operating system to do something, quitting is 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 find +another. In one very common case---waiting for file input or output +using NFS---Emacs itself knows how to quit, but most NFS implementations +simply do not allow user programs to stop waiting for NFS when the NFS +server is hung. + +@cindex aborting recursive edit +@findex abort-recursive-edit +@kindex C-] + Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get +out of a recursive editing level and cancel the command which invoked +it. Quitting with @kbd{C-g} does not do this, and could not do this, +because it is used to cancel a partially typed command @emph{within} the +recursive editing level. Both operations are useful. For example, if +you are in a recursive edit and type @kbd{C-u 8} to enter a numeric +argument, you can cancel that argument with @kbd{C-g} and remain in the +recursive edit. + +@findex keyboard-escape-quit +@kindex ESC ESC ESC + The command @kbd{@key{ESC} @key{ESC} @key{ESC}} +(@code{keyboard-escape-quit}) can either quit or abort. This key was +defined because @key{ESC} is used to ``get out'' in many PC programs. +It can cancel a prefix argument, clear a selected region, or get out of +a Query Replace, like @kbd{C-g}. It can get out of the minibuffer or a +recursive edit, like @kbd{C-]}. It can also get out of splitting the +frame into multiple windows, like @kbd{C-x 1}. One thing it cannot do, +however, is stop a command that is running. That's because it executes +as an ordinary command, and Emacs doesn't notice it until it is ready +for a 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 +keymap. @xref{Recursive Edit}. + + @kbd{C-x u} (@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}. + +@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. + +@menu +* DEL Gets Help:: What to do if @key{DEL} doesn't delete. +* Stuck Recursive:: `[...]' in mode line around the parentheses. +* Screen Garbled:: Garbage on the screen. +* Text Garbled:: Garbage in the text. +* Unasked-for Search:: Spontaneous entry to incremental search. +* 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. +@end menu + +@node DEL Gets Help +@subsection If @key{DEL} Fails to Delete + + If you find that @key{DEL} enters Help like @kbd{Control-h} instead of +deleting a character, your terminal is sending the wrong code for +@key{DEL}. You can work around this problem by changing the keyboard +translation table (@pxref{Keyboard Translations}). + +@node Stuck Recursive +@subsection Recursive Editing Levels + + Recursive editing levels are important and useful features of Emacs, but +they can seem like malfunctions to the user who does not understand them. + + If the mode line has square brackets @samp{[@dots{}]} around the parentheses +that contain the names of the major and minor modes, you have entered a +recursive editing level. If you did not do this on purpose, or if you +don't understand what that means, you should just get out of the recursive +editing level. To do so, type @kbd{M-x top-level}. This is called getting +back to top level. @xref{Recursive Edit}. + +@node Screen Garbled +@subsection Garbage on the Screen + + If the data on the screen looks wrong, the first thing to do is see +whether the text is really wrong. Type @kbd{C-l}, to redisplay the +entire screen. If the screen appears correct after this, the problem +was entirely in the previous screen update. (Otherwise, see @ref{Text +Garbled}.) + + Display updating problems often result from an incorrect termcap entry +for the terminal you are using. The file @file{etc/TERMS} in the Emacs +distribution gives the fixes for known problems of this sort. +@file{INSTALL} contains general advice for these problems in one of its +sections. Very likely there is simply insufficient padding for certain +display operations. To investigate the possibility that you have this sort +of problem, try Emacs on another terminal made by a different manufacturer. +If problems happen frequently on one kind of terminal but not another kind, +it is likely to be a bad termcap entry, though it could also be due to a +bug in Emacs that appears for terminals that have or that lack specific +features. + +@node Text Garbled +@subsection Garbage in the Text + + If @kbd{C-l} shows that the text is wrong, try undoing the changes to it +using @kbd{C-x u} until it gets back to a state you consider correct. Also +try @kbd{C-h l} to find out what command you typed to produce the observed +results. + + If a large portion of text appears to be missing at the beginning or +end of the buffer, check for the word @samp{Narrow} in the mode line. +If it appears, the text you don't see is probably still present, but +temporarily off-limits. To make it accessible again, type @kbd{C-x n +w}. @xref{Narrowing}. + +@node Unasked-for Search +@subsection Spontaneous Entry to Incremental Search + + If Emacs spontaneously displays @samp{I-search:} at the bottom of the +screen, it means that the terminal is sending @kbd{C-s} and @kbd{C-q} +according to the poorly designed xon/xoff ``flow control'' protocol. + + If this happens to you, your best recourse is to put the terminal in a +mode where it will not use flow control, or give it so much padding that +it will never send a @kbd{C-s}. (One way to increase the amount of +padding is to set the variable @code{baud-rate} to a larger value. Its +value is the terminal output speed, measured in the conventional units +of baud.) + +@cindex flow control +@cindex xon-xoff +@findex enable-flow-control + If you don't succeed in turning off flow control, the next best thing +is to tell Emacs to cope with it. To do this, call the function +@code{enable-flow-control}. + +@findex enable-flow-control-on + Typically there are particular terminal types with which you must use +flow control. You can conveniently ask for flow control on those +terminal types only, using @code{enable-flow-control-on}. For example, +if you find you must use flow control on VT-100 and H19 terminals, put +the following in your @file{.emacs} file: + +@example +(enable-flow-control-on "vt100" "h19") +@end example + + When flow control is enabled, you must type @kbd{C-\} to get the +effect of a @kbd{C-s}, and type @kbd{C-^} to get the effect of a +@kbd{C-q}. (These aliases work by means of keyboard translations; see +@ref{Keyboard Translations}.) + +@node Memory Full +@subsection Running out of Memory +@cindex memory full +@cindex out of memory + + If you get the error message @samp{Virtual memory exceeded}, save your +modified buffers with @kbd{C-x s}. This method of saving them has the +smallest need for additional memory. Emacs keeps a reserve of memory +which it makes available when this error happens; that should be enough +to enable @kbd{C-x s} to complete its work. + + Once you have saved your modified buffers, you can exit this Emacs job +and start another, or you can use @kbd{M-x kill-some-buffers} to free +space in the current Emacs job. If you kill buffers containing a +substantial amount of text, you can safely go on editing. Emacs refills +its memory reserve automatically when it sees sufficient free space +available, in case you run out of memory another time. + + 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 memory +itself, and the reserve supply may not be enough. + +@node After a Crash +@subsection Recovery After a Crash + + If Emacs or the computer crashes, you can recover the files you were +editing at the time of the crash from their auto-save files. To do +this, start Emacs again and type the command @kbd{M-x recover-session}. + + This command initially displays a buffer which lists interrupted +session files, each with its date. You must choose which session to +recover from. Typically the one you want is the most recent one. Move +point to the one you choose, and type @kbd{C-c C-c}. + + Then @code{recover-session} asks about each of the files that you were +editing during that session; it asks whether to recover that file. If +you answer @kbd{y} for a file, it shows the dates of that file and its +auto-save file, then asks once again whether to recover that file. For +the second question, you must confirm with @kbd{yes}. If you do, Emacs +visits the file but gets the text from the auto-save file. + + When @code{recover-session} is done, the files you've chosen to +recover are present in Emacs buffers. You should then save them. Only +this---saving them---updates the files themselves. + +@node Emergency Escape +@subsection Emergency Escape + + Because at times there have been bugs causing Emacs to loop without +checking @code{quit-flag}, a special feature causes Emacs to be suspended +immediately if you type a second @kbd{C-g} while the flag is already set, +so you can always get out of GNU Emacs. Normally Emacs recognizes and +clears @code{quit-flag} (and quits!) quickly enough to prevent this from +happening. (On MS-DOS and compatible systems, type @kbd{C-@key{BREAK}} +twice.) + + When you resume Emacs after a suspension caused by multiple @kbd{C-g}, it +asks two questions before going back to what it had been doing: + +@example +Auto-save? (y or n) +Abort (and dump core)? (y or n) +@end example + +@noindent +Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}. + + Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of all +modified buffers in which auto-saving is enabled. + + Saying @kbd{y} to @samp{Abort (and dump core)?} causes an illegal instruction to be +executed, dumping core. This is to enable a wizard to figure out why Emacs +was failing to quit in the first place. Execution does not continue +after a core dump. If you answer @kbd{n}, execution does continue. With +luck, GNU Emacs will ultimately check @code{quit-flag} and quit normally. +If not, and you type another @kbd{C-g}, it is suspended again. + + If Emacs is not really hung, just slow, you may invoke the double +@kbd{C-g} feature without really meaning to. Then just resume and answer +@kbd{n} to both questions, and you will arrive at your former state. +Presumably the quit you requested will happen soon. + + The double-@kbd{C-g} feature is turned off when Emacs is running under +the X Window System, since you can use the window manager to kill Emacs +or to create another window and run another program. + + On MS-DOS and compatible systems, the emergency escape feature is +sometimes unavailable, even if you press @kbd{C-@key{BREAK}} twice, when +some system call (MS-DOS or BIOS) hangs, or when Emacs is stuck in a +very tight endless loop (in C code, @strong{not} in Lisp 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 doctor will help you feel better. Each time you say something to +the doctor, you must end it by typing @key{RET} @key{RET}. This lets +the doctor know you are finished. + +@node Bugs, Contributing, Lossage, Top +@section Reporting Bugs + +@cindex bugs + Sometimes you will encounter a bug in Emacs. Although we cannot +promise we can or will fix the bug, and we might not even agree that it +is a bug, we want to hear about 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. + +@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. +@end menu + +@node Bug Criteria +@subsection When Is There a Bug + + If Emacs executes an illegal instruction, or dies with an operating +system error message that indicates a problem in the program (as opposed to +something like ``disk full''), then it is certainly a bug. + + If Emacs updates the display in a way that does not correspond to what is +in the buffer, then it is certainly a bug. If a command seems to do the +wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a +case of incorrect display updating. + + Taking forever to complete a command can be a bug, but you must make +certain that it was really Emacs's fault. Some commands simply take a +long time. Type @kbd{C-g} (@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. + + Finally, a command's intended definition may not be best for editing +with. This is a very important sort of problem, but it is also a matter of +judgment. Also, it is easy to come to such a conclusion out of ignorance +of some of the existing features. It is probably best not to complain +about such a problem until you have checked the documentation in the usual +ways, feel confident that you understand it, and know for certain that what +you want is not available. If you are not sure what the command is +supposed to do after a careful reading of the manual, check the index and +glossary for any terms that may be unclear. + + If after careful rereading of the manual you still do not understand +what the command should do, that indicates a bug in the manual, which +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 +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. + + 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. + + 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 displayed @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 +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.@refill + + 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. + +@node Checklist +@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 @samp{bug-gnu-emacs@@gnu.org}. (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 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 you can't send electronic mail, then mail the bug report on paper +or machine-readable media to this address: + +@format +GNU Emacs Bugs +Free Software Foundation +59 Temple Place, Suite 330 +Boston, MA 02111-1307 USA +@end format + + We do not promise to fix the bug; but if the bug is serious, +or ugly, or easy to fix, chances are we will want to. + +@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. + + 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. + +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. + +@item +The operands given to the @code{configure} command when Emacs was +installed. + +@item +A complete list of any modifications you have made to the Emacs source. +(We may not have time to investigate the bug unless it happens in an +unmodified Emacs. But if you've made modifications and you don't tell +us, you are sending us on a wild goose chase.) + +Be precise about these changes. A description in English is not +enough---send a context diff for them. + +Adding files of your own, or porting to another machine, is a +modification of the source. + +@item +Details of any other deviations from the standard procedure for installing +GNU Emacs. + +@item +The complete text of any files needed to reproduce the bug. + + If you can tell us a way to cause the problem without visiting any files, +please do so. This makes it much easier to debug. If you do need files, +make sure you arrange for us to see their exact contents. For example, it +can often matter whether there are spaces at the ends of lines, or a +newline after the last line in the buffer (nothing ought to care whether +the last line is terminated, but try telling the bugs that). + +@item +The precise commands we need to type to reproduce the bug. + +@findex open-dribble-file +@cindex dribble file + The easy 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 +specified dribble file until the Emacs process is killed. + +@item +@findex open-termscript +@cindex termscript file +@cindex @code{TERM} environment variable +For possible display bugs, the terminal type (the value of environment +variable @code{TERM}), the complete termcap entry for the terminal from +@file{/etc/termcap} (since that file is not identical on all machines), +and the output that Emacs actually sent to the terminal. + +The way to collect the terminal output is to execute the Lisp expression + +@example +(open-termscript "~/termscript") +@end example + +@noindent +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. + +Be warned: it is often difficult, and sometimes impossible, to fix a +terminal-dependent bug without access to a terminal of the type that +stimulates the bug.@refill + +@item +A description of what behavior you observe that you believe is +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 +miss it. But if the bug is incorrect text, the maintainer might fail to +notice what is wrong. Why leave it to chance? + +Even if the problem you experience is a fatal signal, you should still +say so explicitly. Suppose something strange is going on, such as, your +copy of the source is out of sync, or you have encountered a bug in the +C library on your system. (This has happened!) Your copy might crash +and the copy here might not. If you @emph{said} to expect a crash, then +when Emacs here fails to crash, we would know that the bug was not +happening. If you don't say to expect a crash, then we would not know +whether the bug was happening---we would not be able to draw any +conclusion from our observations. + +@item +If the manifestation of the bug is an Emacs error message, it is +important to report the precise text of the error message, and a +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 +part. + +To make a backtrace for the error, evaluate the Lisp expression +@code{(setq @w{debug-on-error t})} before the error happens (that is to +say, you must execute that expression and then make the bug happen). +This causes the error to run the Lisp debugger, which shows you a +backtrace. Copy the text of the debugger's backtrace into the bug +report. + +This use of the debugger is possible only if you know how to make the +bug happen again. If you can't make it happen again, at least copy +the whole error message. + +@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 file). 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 not part of the standard Emacs system, then you should make sure it +is not a bug in those programs by complaining to their maintainers +first. After they verify that they are using Emacs in a way that is +supposed to work, they should report the bug. + +@item +If you wish to mention something in the GNU Emacs source, show the line +of code with a few lines of context. Don't just give a line number. + +The line numbers in the development sources don't match those in your +sources. It would take extra work for the maintainers to determine what +code is in your version at a given line number, and we could not be +certain. + +@item +Additional information from a C debugger such as GDB might enable +someone to find a problem on a machine which he does not have available. +If you don't know how to use GDB, please read the GDB manual---it is not +very long, and using GDB is easy. You can find the GDB distribution, +including the GDB manual in online form, in most of the same places you +can find the Emacs distribution. To run Emacs under GDB, you should +switch to the @file{src} subdirectory in which Emacs was compiled, then +do @samp{gdb emacs}. It is important for the directory @file{src} to be +current so that GDB will read the @file{.gdbinit} file in this +directory. + +However, you need to think when you collect the additional information +if you want it to show what causes the bug. + +@cindex backtrace for bug reports +For example, many people send just a backtrace, but that is not very +useful by itself. A simple backtrace with arguments often conveys +little about what is happening inside GNU Emacs, because most of the +arguments listed in the backtrace are pointers to Lisp objects. The +numeric values of these pointers have no significance whatever; all that +matters is the contents of the objects they point to (and most of the +contents are themselves pointers). + +@findex debug_print +To provide useful information, you need to show the values of Lisp +objects in Lisp notation. Do this for each variable which is a Lisp +object, in several stack frames near the bottom of the stack. Look at +the source to see which variables are Lisp objects, because the debugger +thinks of them as integers. + +To show a variable's value in Lisp syntax, first print its value, then +use the user-defined GDB command @code{pr} to print the Lisp object in +Lisp syntax. (If you must use another debugger, call the function +@code{debug_print} with the object as an argument.) The @code{pr} +command is defined by the file @file{.gdbinit}, and it works only if you +are debugging a running process (not with a core dump). + +To make Lisp errors stop Emacs and return to GDB, put a breakpoint at +@code{Fsignal}. + +To find out which Lisp functions are running, using GDB, move up the +stack, and each time you get to a frame for the function +@code{Ffuncall}, type these GDB commands: + +@example +p *args +pr +@end example + +@noindent +To print the first argument that the function received, use these +commands: + +@example +p args[1] +pr +@end example + +@noindent +You can print the other arguments likewise. The argument @code{nargs} +of @code{Ffuncall} says how many arguments @code{Ffuncall} received; +these include the Lisp function itself and the arguments for that +function. + +The file @file{.gdbinit} defines several other commands that are useful +for examining the data types and contents of Lisp objects. Their names +begin with @samp{x}. These commands work at a lower level than +@code{pr}, and are less convenient, but they may work even when +@code{pr} does not, such as when debugging a core dump or when Emacs has +had a fatal signal. + +@item +If the symptom of the bug is that Emacs fails to respond, don't assume +Emacs is ``hung''---it may instead be in an infinite loop. To find out +which, make the problem happen under GDB and stop Emacs once it is not +responding. (If Emacs is using X Windows directly, you can stop Emacs +by typing @kbd{C-z} at the GDB job.) Then try stepping with +@samp{step}. If Emacs is hung, the @samp{step} command won't return. +If it is looping, @samp{step} will return. + +If this shows Emacs is hung in a system call, stop it again and examine +the arguments of the call. In your bug report, state exactly where in +the source the system call is, and what the arguments are. + +If Emacs is in an infinite loop, please determine where the loop starts +and ends. The easiest way to do this is to use the GDB command +@samp{finish}. Each time you use it, Emacs resumes execution until it +exits one stack frame. Keep typing @samp{finish} until it doesn't +return---that means the infinite loop is in the stack frame which you +just tried to finish. + +Stop Emacs again, and use @samp{finish} repeatedly again until you get +@emph{back to} that frame. Then use @samp{next} to step through that +frame. By stepping, you will see where the loop starts and ends. Also +please examine the data being used in the loop and try to determine why +the loop does not exit when it should. Include all of this information +in your bug report. +@end itemize + +Here are some things that are not necessary in a bug report: + +@itemize @bullet +@item +A description of the envelope of the bug---this is not necessary for a +reproducible bug. + +Often people who encounter a bug spend a lot of time investigating +which changes to the input file will make the bug go away and which +changes will not affect it. + +This is often time-consuming and not very useful, because the way we +will find the bug is by running a single example under the debugger with +breakpoints, not by pure deduction from a series of examples. You might +as well save time by not searching for additional examples. + +Of course, if you can find a simpler example to report @emph{instead} of +the original one, that is a convenience. Errors in the output will be +easier to spot, running under the debugger will take less time, etc. + +However, simplification is not vital; if you can't do this or don't have +time to try, please report the bug with your original test case. + +@item +A system-call trace of Emacs execution. + +System-call traces are very useful for certain special kinds of +debugging, but in most cases they give little useful information. It is +therefore strange that many people seem to think that @emph{the} way to +report information about a crash is to send a system-call trace. Perhaps +this is a habit formed from experience debugging programs that don't +have source code or debugging symbols. + +In most programs, a backtrace is normally far, far more informative than +a system-call trace. Even in Emacs, a simple backtrace is generally +more informative, though to give full information you should supplement +the backtrace by displaying variable values and printing them as Lisp +objects with @code{pr} (see above). + +@item +A patch for the bug. + +A patch for the bug is useful if it is a good one. But don't omit the +other information that a bug report needs, such as the test case, on the +assumption that a patch is sufficient. We might see problems with your +patch and decide to fix the problem another way, or we might not +understand it at all. And if we can't understand what bug you are +trying to fix, or why your patch should be an improvement, we mustn't +install it. + +@ifinfo +@xref{Sending Patches}, for guidelines on how to make it easy for us to +understand and install your patches. +@end ifinfo + +@item +A guess about what the bug is or what it depends on. + +Such guesses are usually wrong. Even experts can't guess right about +such things without first using the debugger to find the facts. +@end itemize + +@node Sending Patches +@subsection Sending Patches for GNU Emacs + +@cindex sending patches for GNU Emacs +@cindex patches, sending + If you would like to write bug fixes or improvements for GNU Emacs, +that is very helpful. When you send your changes, please follow these +guidelines to make it easy for the maintainers to use them. If you +don't follow these guidelines, your information might still be useful, +but using it will take extra work. Maintaining GNU Emacs is a lot of +work in the best of circumstances, and we can't keep up unless you do +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.) + +@item +Always include a proper bug report for the problem you think you have +fixed. We need to convince ourselves that the change is right before +installing it. Even if it is correct, we might have trouble +understanding it if we don't have a way to reproduce the problem. + +@item +Include all the comments that are appropriate to help people reading the +source in the future understand why this change was needed. + +@item +Don't mix together changes made for different reasons. +Send them @emph{individually}. + +If you make two changes for separate reasons, then we might not want to +install them both. We might want to install just one. If you send them +all jumbled together in a single set of diffs, we have to do extra work +to disentangle them---to figure out which parts of the change serve +which purpose. If we don't have time for this, we might have to ignore +your changes entirely. + +If you send each change as soon as you have written it, with its own +explanation, then two changes never get tangled up, and we can consider +each one properly without any extra work to disentangle them. + +@item +Send each change as soon as that change is finished. Sometimes people +think they are helping us by accumulating many changes to send them all +together. As explained above, this is absolutely the worst thing you +could do. + +Since you should send each change separately, you might as well send it +right away. That gives us the option of installing it immediately if it +is important. + +@item +Use @samp{diff -c} to make your diffs. Diffs without context are hard +to install reliably. More than that, they are hard to study; we must +always study a patch to decide whether we want to install it. Unidiff +format is better than contextless diffs, but not as easy to read as +@samp{-c} format. + +If you have GNU diff, use @samp{diff -c -F'^[_a-zA-Z0-9$]+ *('} when +making diffs of C code. This shows the name of the function that each +change occurs in. + +@item +Avoid any ambiguity as to which is the old version and which is the new. +Please make the old version the first argument to diff, and the new +version the second argument. And please give one version or the other a +name that indicates whether it is the old version or your new changed +one. + +@item +Write the change log entries for your changes. This is both to save us +the extra work of writing them, and to help explain your changes so we +can understand them. + +The purpose of the change log is to show people where to find what was +changed. So you need to be specific about what functions you changed; +in large functions, it's often helpful to indicate where within the +function the change was. + +On the other hand, once you have shown people where to find the change, +you need not explain its purpose in the change log. Thus, if you add a +new function, all you need to say about it is that it is new. If you +feel that the purpose needs explaining, it probably does---but put the +explanation in comments in the code. It will be more useful there. + +Please read the @file{ChangeLog} files in the @file{src} and @file{lisp} +directories to see what sorts of information to put in, and to learn the +style that we use. If you would like your name to appear in the header +line, showing who made the change, send us the header line. +@xref{Change Log}. + +@item +When you write the fix, keep in mind that we can't install a change that +would break other systems. Please think about what effect your change +will have if compiled on another type of system. + +Sometimes people send fixes that @emph{might} be an improvement in +general---but it is hard to be sure of this. It's hard to install +such changes because we have to study them very carefully. Of course, +a good explanation of the reasoning by which you concluded the change +was correct can help convince us. + +The safest changes are changes to the configuration files for a +particular machine. These are safe because they can't create new bugs +on other machines. + +Please help us keep up with the workload by designing the patch in a +form that is clearly safe to install. +@end itemize + +@node Contributing, Service, Bugs, Top +@section Contributing to Emacs Development + +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 +the maintainers at @code{bug-gnu-emacs@@gnu.org}. A pretester +should be prepared to investigate bugs as well as report them. If you'd +like to work on improving Emacs, please ask for suggested projects or +suggest your own ideas. + +If you have already written an improvement, please tell us about it. If +you have not yet started work, it is useful to contact +@code{bug-gnu-emacs@@gnu.org} before you start; it might be +possible to suggest ways to make your extension fit in better with the +rest of Emacs. + +@node Service, Command Arguments, Contributing, Top +@section How To Get Help with GNU Emacs + +If you need help installing, using or changing GNU Emacs, there are two +ways to find it: + +@itemize @bullet +@item +Send a message to the mailing list +@code{help-gnu-emacs@@gnu.org}, or post your request on +newsgroup @code{gnu.emacs.help}. (This mailing list and newsgroup +interconnect, so it does not matter which one you use.) + +@item +Look in the service directory for someone who might help you for a fee. +The service directory is found in the file named @file{etc/SERVICE} in the +Emacs distribution. +@end itemize |