(enum mac_menu_kind, min_menu_id): New enumerator and
menu ID for Apple menu.
(menubar_selection_callback): Remove function.
(find_and_call_menu_selection): New function from xmenu.c.
(x_activate_menubar): Use it.
(set_frame_menubar): Don't use f->output_data.mac->menubar_active.
@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 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 oftenmysterious. This chapter tells what you can do to cancel your mistake orrecover from a mysterious situation. Emacs bugs and system crashes arealso considered.@end iftex@ifnottex@raisesections@end ifnottex@node Quitting, Lossage, Customization, Top@section Quitting and Aborting@cindex quitting@table @kbd@item C-g@itemx C-@key{BREAK} @r{(MS-DOS only)}Quit: cancel running or partially typed command.@item C-]Abort innermost recursive editing level and cancel the command whichinvoked 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-levelAbort all recursive editing levels that are currently executing.@item C-x uCancel a previously made change in the buffer contents (@code{undo}).@end table There are two ways of canceling a command before it has finished:@dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]} or@kbd{M-x top-level}. Quitting cancels a partially typed command, orone which is still running. Aborting exits a recursive editing leveland cancels the command that invoked the recursive edit.(@xref{Recursive Edit}.)@cindex quitting@kindex C-g Quitting with @kbd{C-g} is the way to get rid of a partially typedcommand, or a numeric argument that you don't want. It also stops arunning command in the middle in a relatively safe way, so you can useit if you accidentally give a command which takes a long time. Inparticular, it is safe to quit out of a kill command; either your textwill @emph{all} still be in the buffer, or it will @emph{all} be inthe kill ring, or maybe both. Quitting an incremental search doesspecial things, documented under searching; it may take two successive@kbd{C-g} characters to get out of a search (@pxref{IncrementalSearch}). On MS-DOS, the character @kbd{C-@key{BREAK}} serves as a quit characterlike @kbd{C-g}. The reason is that it is not feasible, on MS-DOS, torecognize @kbd{C-g} while a command is running, between interactionswith the user. By contrast, it @emph{is} feasible to recognize@kbd{C-@key{BREAK}} at all times.@iftex@xref{MS-DOS Keyboard,,,emacs-xtra, Specialized Emacs Features}.@end iftex@ifnottex@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 variablefrequently, and quits if it is non-@code{nil}. @kbd{C-g} is onlyactually executed as a command if you type it while Emacs is waiting forinput. In that case, the command it runs is @code{keyboard-quit}. On a text terminal, if you quit with @kbd{C-g} a second time beforethe first @kbd{C-g} is recognized, you activate the ``emergencyescape'' feature and return to the shell. @xref{Emergency Escape}.@cindex NFS and quitting There are some situations where you cannot quit. When Emacs iswaiting for the operating system to do something, quitting isimpossible unless special pains are taken for the particular systemcall within Emacs where the waiting occurs. We have done this for thesystem calls that users are likely to want to quit from, but it'spossible you will a case not handled. In one very commoncase---waiting for file input or output using NFS---Emacs itself knowshow to quit, but many NFS implementations simply do not allow userprograms 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 getout of a recursive editing level and cancel the command which invokedit. 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} therecursive editing level. Both operations are useful. For example, ifyou are in a recursive edit and type @kbd{C-u 8} to enter a numericargument, you can cancel that argument with @kbd{C-g} and remain in therecursive edit.@findex keyboard-escape-quit@kindex ESC ESC ESC The sequence @kbd{@key{ESC} @key{ESC} @key{ESC}}(@code{keyboard-escape-quit}) can either quit or abort. (We definedit this way because @key{ESC} means ``get out'' in many PC programs.)It can cancel a prefix argument, clear a selected region, or get outof a Query Replace, like @kbd{C-g}. It can get out of the minibufferor a recursive edit, like @kbd{C-]}. It can also get out of splittingthe frame into multiple windows, as with @kbd{C-x 1}. One thing itcannot do, however, is stop a command that is running. That's becauseit executes as an ordinary command, and Emacs doesn't notice it untilit 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 youare in. @kbd{C-]} gets you out one level at a time, but @kbd{M-xtop-level} goes out all levels at once. Both @kbd{C-]} and @kbd{M-xtop-level} are like all other commands, and unlike @kbd{C-g}, in thatthey take effect only when Emacs is ready for a command. @kbd{C-]} isan ordinary key and has its meaning only because of its binding in thekeymap. @xref{Recursive Edit}. @kbd{C-x u} (@code{undo}) is not strictly speaking a way of cancelinga command, but you can think of it as canceling a command that alreadyfinished executing. @xref{Undo}, for more informationabout the undo facility.@node Lossage, Bugs, Quitting, Top@section Dealing with Emacs Trouble This section describes various conditions in which Emacs fails to worknormally, and how to recognize them and correct them. For a list ofadditional 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.@menu* DEL Does Not Delete:: 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.* 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 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, a little ways above the @key{RET} or@key{ENTER} key, which you normally use outside Emacs to erase thelast character that you typed. We call this key @dfn{the usualerasure key}. In Emacs, it is supposed to be equivalent to @key{DEL},and when Emacs is properly configured for your terminal, it translatesthat key into the character @key{DEL}. When Emacs starts up on a graphical display, it determinesautomatically which key should be @key{DEL}. In some unusual casesEmacs gets the wrong information from the system. If the usualerasure key deletes forwards instead of backwards, that is probablywhat happened---Emacs ought to be treating the @key{DELETE} 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 toosuggests Emacs got the wrong information---but in the opposite sense.It ought to be treating the @key{BACKSPACE} key as @key{DEL}, andtreating @key{DELETE} differently, but it isn't. On a text-only terminal, if you find the usual erasure key promptsfor a Help command, like @kbd{Control-h}, instead of deleting acharacter, it means that key is actually sending the @key{BS}character. Emacs ought to be treating @key{BS} as @key{DEL}, but itisn't. In all of those cases, the immediate remedy is the same: use thecommand @kbd{M-x normal-erase-is-backspace-mode}. This togglesbetween the two modes that Emacs supports for handling @key{DEL}, soif Emacs starts in the wrong mode, this should switch to the rightmode. 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 alsowork, if it sends character code 127.@findex normal-erase-is-backspace-mode To fix the problem automatically for every Emacs session, you canput one of the following lines into your @file{.emacs} file(@pxref{Init File}). For the first case above, where @key{DELETE}deletes forwards instead of backwards, use this line to make@key{DELETE} act as @key{DEL} (resulting in behavior compatiblewith Emacs 20 and previous versions):@lisp(normal-erase-is-backspace-mode 0)@end lisp@noindentFor the other two cases, where @key{BACKSPACE} ought to act as@key{DEL}, use this line:@lisp(normal-erase-is-backspace-mode 1)@end lisp@vindex normal-erase-is-backspace Another way to fix the problem for every Emacs session is tocustomize the variable @code{normal-erase-is-backspace}: the value@code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is@key{DEL}, and @code{nil} specifies the other mode. @xref{EasyCustomization}. On a graphical display, it can also happen that the usual erasure keyis labeled @key{BACKSPACE}, there is a @key{DELETE} key elsewhere, andboth keys delete forward. This probably means that someone hasredefined your @key{BACKSPACE} key as a @key{DELETE} key. With X,this is typically done with a command to the @code{xmodmap} programwhen you start the server or log in. The most likely motive for thiscustomization was to support old versions of Emacs, so we recommendyou simply remove it now.@node Stuck Recursive@subsection Recursive Editing Levels Recursive editing levels are important and useful features of Emacs, butthey can seem like malfunctions if you do not understand them. If the mode line has square brackets @samp{[@dots{}]} around the parenthesesthat contain the names of the major and minor modes, you have entered arecursive editing level. If you did not do this on purpose, or if youdon't understand what that means, you should just get out of the recursiveediting level. To do so, type @kbd{M-x top-level}. This is called gettingback to top level. @xref{Recursive Edit}.@node Screen Garbled@subsection Garbage on the Screen If the text on a text terminal looks wrong, the first thing to do issee whether it is wrong in the buffer. Type @kbd{C-l} to redisplaythe entire screen. If the screen appears correct after this, theproblem was entirely in the previous screen update. (Otherwise, seethe following section.) Display updating problems often result from an incorrect terminfoentry for the terminal you are using. The file @file{etc/TERMS} inthe Emacs distribution gives the fixes for known problems of thissort. @file{INSTALL} contains general advice for these problems inone of its sections. To investigate the possibility that you havethis sort of problem, try Emacs on another terminal made by adifferent manufacturer. If problems happen frequently on one kind ofterminal 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 forterminals 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, first type @kbd{C-h l} tosee what commands you typed to produce the observed results. Then tryundoing the changes step by step using @kbd{C-x u}, until it gets backto a state you consider correct. If a large portion of text appears to be missing at the beginning orend 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, buttemporarily off-limits. To make it accessible again, type @kbd{C-x nw}. @xref{Narrowing}.@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}, saveyour modified buffers with @kbd{C-x s}. This method of saving themhas the smallest need for additional memory. Emacs keeps a reserve ofmemory which it makes available when this error happens; that shouldbe enough to enable @kbd{C-x s} to complete its work. When thereserve has been used, @samp{!MEM FULL!} appears at the beginning ofthe mode line, indicating there is no more reserve. Once you have saved your modified buffers, you can exit this Emacssession and start another, or you can use @kbd{M-x kill-some-buffers}to free space in the current Emacs job. If this frees up sufficientspace, Emacs will refill its memory reserve, and @samp{!MEM FULL!}will disappear from the mode line. That means you can safely go onediting in the same Emacs session. Do not use @kbd{M-x buffer-menu} to save or kill buffers when you runout of memory, because the buffer menu needs a fair amount of memoryitself, 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 wereediting at the time of the crash from their auto-save files. To dothis, start Emacs again and type the command @kbd{M-x recover-session}. This command initially displays a buffer which lists interruptedsession files, each with its date. You must choose which session torecover from. Typically the one you want is the most recent one. Movepoint to the one you choose, and type @kbd{C-c C-c}. Then @code{recover-session} considers each of the files that youwere editing during that session; for each such file, it asks whetherto recover that file. If you answer @kbd{y} for a file, it shows thedates of that file and its auto-save file, then asks once againwhether to recover that file. For the second question, you mustconfirm with @kbd{yes}. If you do, Emacs visits the file but gets thetext from the auto-save file. When @code{recover-session} is done, the files you've chosen torecover are present in Emacs buffers. You should then save them. Onlythis---saving them---updates the files themselves. As a last resort, if you had buffers with content which were notassociated with any files, or if the autosave was not recent enough tohave recorded important changes, you can use the@file{etc/emacs-buffer.gdb} script with GDB (the GNU Debugger) toretrieve them from a core dump--provided that a core dump was saved,and that the Emacs executable was not stripped of its debuggingsymbols. As soon as you get the core dump, rename it to another name such as@file{core.emacs}, so that another crash won't overwrite it. To use this script, run @code{gdb} with the file name of your Emacsexecutable and the file name of the core dump, e.g. @samp{gdb/usr/bin/emacs core.emacs}. At the @code{(gdb)} prompt, load therecovery script: @samp{source /usr/src/emacs/etc/emacs-buffer.gdb}.Then type the command @code{ybuffer-list} to see which buffers areavailable. For each buffer, it lists a buffer number. To save abuffer, use @code{ysave-buffer}; you specify the buffer number, andthe file name to write that buffer into. You should use a file namewhich does not already exist; if the file does exist, the script doesnot make a backup of its old contents.@node Emergency Escape@subsection Emergency Escape On text-only terminals, the @dfn{emergency escape} feature suspendsEmacs immediately if you type @kbd{C-g} a second time before Emacs canactually respond to the first one by quitting. This is so you canalways get out of GNU Emacs no matter how badly it might be hung.When things are working properly, Emacs recognizes and handles thefirst @kbd{C-g} so fast that the second one won't trigger emergencyescape. However, if some problem prevents Emacs from handling thefirst @kbd{C-g} properly, then the second one will get you back to theshell. When you resume Emacs after a suspension caused by emergency escape,it asks two questions before going back to what it had been doing:@exampleAuto-save? (y or n)Abort (and dump core)? (y or n)@end example@noindentAnswer each one with @kbd{y} or @kbd{n} followed by @key{RET}. Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving ofall modified buffers in which auto-saving is enabled. Saying @kbd{n}skips this. Saying @kbd{y} to @samp{Abort (and dump core)?} causes Emacs tocrash, dumping core. This is to enable a wizard to figure out whyEmacs was failing to quit in the first place. Execution does notcontinue after a core dump. If you answer this question @kbd{n}, Emacs execution resumes. Withluck, Emacs will ultimately do the requested quit. If not, eachsubsequent @kbd{C-g} invokes emergency escape 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 andanswer @kbd{n} to both questions, and you will get back to the formerstate. The quit you requested will happen by and by. Emergency escape is active only for text terminals. On graphicaldisplays, you can use the mouse to kill Emacs or switch to anotherprogram. On MS-DOS, you must type @kbd{C-@key{BREAK}} (twice) to causeemergency escape---but there are cases where it won't work, whensystem 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 noneof the techniques described above solve the problem, Emacs can still helpyou. 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 yousay something to the psychotherapist, you must end it by typing@key{RET} @key{RET}. This indicates you are finished typing.@node Bugs, Contributing, Lossage, Top@section Reporting Bugs@cindex bugs Sometimes you will encounter a bug in Emacs. Although we cannotpromise we can or will fix the bug, and we might not even agree that itis a bug, we want to hear about problems you encounter. Often we agreethey are bugs and want to fix them. To make it possible for us to fix a bug, you must report it. In orderto 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 alreadyknown. 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 readit. Some additional user-level problems can be found in @ref{Bugs andproblems, , Bugs and problems, efaq, GNU Emacs FAQ}. Looking up yourproblem in these two documents might provide you with a solution or awork-around, or give you additional information about related issues.@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 accesses an invalid memory location (``segmentationfault''), or exits with an operating system error message thatindicates 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 isin the buffer, then it is certainly a bug. If a command seems to do thewrong thing but the problem corrects itself if you type @kbd{C-l}, it is acase of incorrect display updating. Taking forever to complete a command can be a bug, but you must makecertain that it was really Emacs's fault. Some commands simply take along 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 processedquickly, report a bug. If you don't know whether the command shouldtake a long time, find out by looking in the manual or by asking forassistance. If a command you are familiar with causes an Emacs error message in acase where its usual definition ought to be reasonable, it is probably abug. If a command does the wrong thing, that is a bug. But be sure you knowfor certain what it ought to have done. If you aren't familiar with thecommand, or don't know for certain how the command is supposed to work,then it might actually be working right. Rather than jumping toconclusions, show the problem to someone who knows for certain. Finally, a command's intended definition may not be the bestpossible definition for editing with. This is a very important sortof problem, but it is also a matter of judgment. Also, it is easy tocome to such a conclusion out of ignorance of some of the existingfeatures. It is probably best not to complain about such a problemuntil you have checked the documentation in the usual ways, feelconfident that you understand it, and know for certain that what youwant is not available. Ask other Emacs users, too. If you are notsure what the command is supposed to do after a careful reading of themanual, check the index and glossary for any terms that may beunclear. If after careful rereading of the manual you still do not understandwhat the command should do, that indicates a bug in the manual, whichyou should report. The manual's job is to make everything clear topeople who are not Emacs experts---including you. It is just asimportant to report documentation bugs as program bugs. If the on-line documentation string of a function or variable disagreeswith 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 toreport it in a way which is useful. What is most useful is an exactdescription of what commands you type, starting with the shell command torun 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 forthe detailed raw data. Reporting the facts is straightforward, but manypeople strain to posit explanations and report them instead of thefacts. If the explanations are based on guesses about how Emacs isimplemented, they will be useless; meanwhile, lacking the facts, we willhave 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 ratherlarge, and Emacs displays @samp{I feel pretty today}. The best way toreport the bug is with a sentence like the preceding one, because itgives all the facts. A bad way would be to assume that the problem is due to the size ofthe file and say, ``I visited a large file, and Emacs displayed @samp{Ifeel pretty today}.'' This is what we mean by ``guessingexplanations.'' The problem is just as likely to be due to the factthat there is a @samp{z} in the file name. If this is so, then when wegot 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. Thereis no way in the world that we could guess that we should try visiting afile with a @samp{z} in its name. Alternatively, the problem might be due to the fact that the file startswith exactly 25 spaces. For this reason, you should make sure that youinform us of the exact contents of any file that is needed to reproduce thebug. 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 ofcharacters you typed since starting the Emacs session. You should not even say ``visit a file'' instead of @kbd{C-x C-f} unlessyou @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 isthe way you entered the text. So please don't guess any explanations when you report a bug. If youwant to actually @emph{debug} the problem, and report explanations thatare more than guesses, that is useful---but please include the facts aswell.@node Checklist@subsection Checklist for Bug Reports@cindex reporting bugs The best way to send a bug report is to mail it electronically to theEmacs maintainers at @email{bug-gnu-emacs@@gnu.org}, or to@email{emacs-pretest-bug@@gnu.org} if you are pretesting an Emacs betarelease. (If you want to suggest a change as an improvement, use thesame address.) If you'd like to read the bug reports, you can find them on thenewsgroup @samp{gnu.emacs.bug}; keep in mind, however, that as aspectator you should not criticize anything about what you see there.The purpose of bug reports is to give information to the Emacsmaintainers. Spectators are welcome only as long as they do notinterfere with this. In particular, some bug reports contain fairlylarge amounts of data; spectators should not complain about this. Please do not post bug reports using netnews; mail is more reliablethan netnews about reporting your correct address, which we may needin order to ask you for more information. If your data is more than500,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 andsay where.@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{SendingMail}) and automatically inserts @emph{some} of the essentialinformation. However, it cannot supply all the necessary information;you should still read and follow the guidelines below, so you can enterthe other crucial information by hand before you send the message. To enable maintainers to investigate a bug, your reportshould include all these things:@itemize @bullet@itemThe version number of Emacs. Without this, we won't know whether thereis any point in looking for the bug in the current version of GNUEmacs.You can get the version number by typing @kbd{M-x emacs-version@key{RET}}. If that command does not work, you probably have somethingother than GNU Emacs, so you will have to report the bug somewhereelse.@itemThe type of machine you are using, and the operating system name andversion number. @kbd{M-x emacs-version @key{RET}} provides thisinformation too. Copy its output from the @samp{*Messages*} buffer, sothat you get it all and get it accurately.@itemThe operands given to the @code{configure} command when Emacs wasinstalled.@itemA 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 anunmodified Emacs. But if you've made modifications and you don't tellus, you are sending us on a wild goose chase.)Be precise about these changes. A description in English is notenough---send a context diff for them.Adding files of your own, or porting to another machine, is amodification of the source.@itemDetails of any other deviations from the standard procedure for installingGNU Emacs.@itemThe 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, itcan matter whether there are spaces at the ends of lines, or anewline after the last line in the buffer (nothing ought to care whetherthe last line is terminated, but try telling the bugs that).@itemThe precise commands we need to type to reproduce the bug.@findex open-dribble-file@cindex dribble file@cindex logging keystrokesThe easy way to record the input to Emacs precisely is to write adribble file. To start the file, execute the Lisp expression@example(open-dribble-file "~/dribble")@end example@noindentusing @kbd{M-:} or from the @samp{*scratch*} buffer just afterstarting Emacs. From then on, Emacs copies all your input to thespecified dribble file until the Emacs process is killed.@item@findex open-termscript@cindex termscript file@cindex @env{TERM} environment variableFor possible display bugs, the terminal type (the value of environmentvariable @env{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@noindentusing @kbd{M-:} or from the @samp{*scratch*} buffer just afterstarting Emacs. From then on, Emacs copies all terminal output to thespecified termscript file as well, until the Emacs process is killed.If the problem happens when Emacs starts up, put this expression intoyour @file{.emacs} file so that the termscript file will be open whenEmacs displays the screen for the first time.Be warned: it is often difficult, and sometimes impossible, to fix aterminal-dependent bug without access to a terminal of the type thatstimulates the bug.@itemIf non-@acronym{ASCII} text or internationalization is relevant, the locale thatwas current when you started Emacs. On GNU/Linux and Unix systems, orif you use a Posix-style shell such as Bash, you can use this shellcommand to view the relevant values:@smallexampleecho LC_ALL=$LC_ALL LC_COLLATE=$LC_COLLATE LC_CTYPE=$LC_CTYPE \ LC_MESSAGES=$LC_MESSAGES LC_TIME=$LC_TIME LANG=$LANG@end smallexampleAlternatively, use the @command{locale} command, if your system has it,to display your locale settings.You can use the @kbd{M-!} command to execute these commands fromEmacs, and then copy the output from the @samp{*Messages*} buffer intothe 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, andyou can copy its output from the @samp{*Messages*} buffer.@itemA description of what behavior you observe that you believe isincorrect. 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'tmiss it. But if the bug is incorrect text, the maintainer might fail tonotice what is wrong. Why leave it to chance?Even if the problem you experience is a fatal signal, you should stillsay so explicitly. Suppose something strange is going on, such as, yourcopy of the source is out of sync, or you have encountered a bug in theC library on your system. (This has happened!) Your copy might crashand the copy here might not. If you @emph{said} to expect a crash, thenwhen Emacs here fails to crash, we would know that the bug was nothappening. If you don't say to expect a crash, then we would not knowwhether the bug was happening---we would not be able to draw anyconclusion from our observations.@itemIf the bug is that the Emacs Manual or the Emacs Lisp Reference Manualfails to describe the actual behavior of Emacs, or that the text isconfusing, copy in the text from the online manual which you think isat fault. If the section is small, just the section name is enough.@itemIf the manifestation of the bug is an Emacs error message, it isimportant to report the precise text of the error message, and abacktrace 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 justpart.@findex toggle-debug-on-error@pindex EdebugTo make a backtrace for the error, use @kbd{M-x toggle-debug-on-error}before the error happens (that is to say, you must give that commandand then make the bug happen). This causes the error to start the Lispdebugger, which shows you a backtrace. Copy the text of thedebugger's backtrace into the bug report. @xref{Debugger,, The LispDebugger, elisp, the Emacs Lisp Reference Manual}, for information ondebugging Emacs Lisp programs with the Edebug package.This use of the debugger is possible only if you know how to make thebug happen again. If you can't make it happen again, at least copythe whole error message.@itemCheck whether any programs you have loaded into the Lisp world,including your @file{.emacs} file, set any variables that may affect thefunctioning of Emacs. Also, see whether the problem happens in afreshly started Emacs without loading your @file{.emacs} file (startEmacs with the @code{-q} switch to prevent loading the init file). Ifthe problem does @emph{not} occur then, you must report the precisecontents of any programs that you must load into the Lisp world in orderto cause the problem to occur.@itemIf the problem does depend on an init file or other Lisp programs thatare not part of the standard Emacs system, then you should make sure itis not a bug in those programs by complaining to their maintainersfirst. After they verify that they are using Emacs in a way that issupposed to work, they should report the bug.@itemIf you wish to mention something in the GNU Emacs source, show the lineof 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 yoursources. It would take extra work for the maintainers to determine whatcode is in your version at a given line number, and we could not becertain.@itemAdditional information from a C debugger such as GDB might enablesomeone 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 notvery 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 youcan find the Emacs distribution. To run Emacs under GDB, you shouldswitch to the @file{src} subdirectory in which Emacs was compiled, thendo @samp{gdb emacs}. It is important for the directory @file{src} to becurrent so that GDB will read the @file{.gdbinit} file in thisdirectory.However, you need to think when you collect the additional informationif you want it to show what causes the bug.@cindex backtrace for bug reportsFor example, many people send just a backtrace, but that is not veryuseful by itself. A simple backtrace with arguments often conveyslittle about what is happening inside GNU Emacs, because most of thearguments listed in the backtrace are pointers to Lisp objects. Thenumeric values of these pointers have no significance whatever; all thatmatters is the contents of the objects they point to (and most of thecontents are themselves pointers).@findex debug_printTo provide useful information, you need to show the values of Lispobjects in Lisp notation. Do this for each variable which is a Lispobject, in several stack frames near the bottom of the stack. Look atthe source to see which variables are Lisp objects, because the debuggerthinks of them as integers.To show a variable's value in Lisp syntax, first print its value, thenuse the user-defined GDB command @code{pr} to print the Lisp object inLisp 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 youare 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}.For a short listing of Lisp functions running, type the GDBcommand @code{xbacktrace}.The file @file{.gdbinit} defines several other commands that are usefulfor examining the data types and contents of Lisp objects. Their namesbegin 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 hashad a fatal signal.@cindex debugging Emacs, tricks and techniquesMore detailed advice and other useful techniques for debugging Emacsare available in the file @file{etc/DEBUG} in the Emacs distribution.That file also includes instructions for investigating problemswhereby Emacs stops responding (many people assume that Emacs is``hung,'' whereas in fact it might be in an infinite loop).To find the file @file{etc/DEBUG} in your Emacs installation, use thedirectory name stored in the variable @code{data-directory}.@end itemizeHere are some things that are not necessary in a bug report:@itemize @bullet@itemA description of the envelope of the bug---this is not necessary for areproducible bug.Often people who encounter a bug spend a lot of time investigatingwhich changes to the input file will make the bug go away and whichchanges will not affect it.This is often time-consuming and not very useful, because the way wewill find the bug is by running a single example under the debuggerwith breakpoints, not by pure deduction from a series of examples.You might as well save time by not searching for additional examples.It is better to send the bug report right away, go back to editing,and find another bug to report.Of course, if you can find a simpler example to report @emph{instead} ofthe original one, that is a convenience. Errors in the output will beeasier 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 havetime to try, please report the bug with your original test case.@itemA core dump file.Debugging the core dump might be useful, but it can only be done onyour machine, with your Emacs executable. Therefore, sending the coredump file to the Emacs maintainers won't be useful. Above all, don'tinclude the core file in an email bug report! Such a large messagecan be extremely inconvenient.@itemA system-call trace of Emacs execution.System-call traces are very useful for certain special kinds ofdebugging, but in most cases they give little useful information. It istherefore strange that many people seem to think that @emph{the} way toreport information about a crash is to send a system-call trace. Perhapsthis is a habit formed from experience debugging programs that don'thave source code or debugging symbols.In most programs, a backtrace is normally far, far more informative thana system-call trace. Even in Emacs, a simple backtrace is generallymore informative, though to give full information you should supplementthe backtrace by displaying variable values and printing them as Lispobjects with @code{pr} (see above).@itemA patch for the bug.A patch for the bug is useful if it is a good one. But don't omit theother information that a bug report needs, such as the test case, on theassumption that a patch is sufficient. We might see problems with yourpatch and decide to fix the problem another way, or we might notunderstand it at all. And if we can't understand what bug you aretrying to fix, or why your patch should be an improvement, we mustn'tinstall it.@ifnottex@xref{Sending Patches}, for guidelines on how to make it easy for us tounderstand and install your patches.@end ifnottex@itemA guess about what the bug is or what it depends on.Such guesses are usually wrong. Even experts can't guess right aboutsuch 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 theseguidelines to make it easy for the maintainers to use them. If youdon't follow these guidelines, your information might still be useful,but using it will take extra work. Maintaining GNU Emacs is a lot ofwork in the best of circumstances, and we can't keep up unless you doyour best to help.@itemize @bullet@itemSend an explanation with your changes of what problem they fix or whatimprovement they bring about. For a bug fix, just include a copy of thebug report, and explain why the change fixes the bug.(Referring to a bug report is not as good as including it, because thenwe will have to look it up, and we have probably already deleted it ifwe've already fixed the bug.)@itemAlways include a proper bug report for the problem you think you havefixed. We need to convince ourselves that the change is right beforeinstalling it. Even if it is correct, we might have troubleunderstanding it if we don't have a way to reproduce the problem.@itemInclude all the comments that are appropriate to help people reading thesource in the future understand why this change was needed.@itemDon'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 toinstall them both. We might want to install just one. If you send themall jumbled together in a single set of diffs, we have to do extra workto disentangle them---to figure out which parts of the change servewhich purpose. If we don't have time for this, we might have to ignoreyour changes entirely.If you send each change as soon as you have written it, with its ownexplanation, then two changes never get tangled up, and we can considereach one properly without any extra work to disentangle them.@itemSend each change as soon as that change is finished. Sometimes peoplethink they are helping us by accumulating many changes to send them alltogether. As explained above, this is absolutely the worst thing youcould do.Since you should send each change separately, you might as well send itright away. That gives us the option of installing it immediately if itis important.@itemUse @samp{diff -c} to make your diffs. Diffs without context are hardto install reliably. More than that, they are hard to study; we mustalways study a patch to decide whether we want to install it. Unidiffformat 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$]+ *('} whenmaking diffs of C code. This shows the name of the function that eachchange occurs in.@itemAvoid 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 newversion the second argument. And please give one version or the other aname that indicates whether it is the old version or your new changedone.@itemWrite the change log entries for your changes. This is both to save usthe extra work of writing them, and to help explain your changes so wecan understand them.The purpose of the change log is to show people where to find what waschanged. So you need to be specific about what functions you changed;in large functions, it's often helpful to indicate where within thefunction 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 anew function, all you need to say about it is that it is new. If youfeel that the purpose needs explaining, it probably does---but put theexplanation 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. @xref{Change Log}.@itemWhen you write the fix, keep in mind that we can't install a change thatwould break other systems. Please think about what effect your changewill have if compiled on another type of system.Sometimes people send fixes that @emph{might} be an improvement ingeneral---but it is hard to be sure of this. It's hard to installsuch changes because we have to study them very carefully. Of course,a good explanation of the reasoning by which you concluded the changewas correct can help convince us.The safest changes are changes to the configuration files for aparticular machine. These are safe because they can't create new bugson other machines.Please help us keep up with the workload by designing the patch in aform that is clearly safe to install.@end itemize@node Contributing, Service, Bugs, Top@section Contributing to Emacs DevelopmentIf you would like to help pretest Emacs releases to assure they workwell, or if you would like to work on improving Emacs, please contactthe maintainers at @email{emacs-devel@@gnu.org}. A pretestershould be prepared to investigate bugs as well as report them. If you'dlike to work on improving Emacs, please ask for suggested projects orsuggest your own ideas.If you have already written an improvement, please tell us about it. Ifyou have not yet started work, it is useful to contact@email{emacs-devel@@gnu.org} before you start; it might bepossible to suggest ways to make your extension fit in better with therest of Emacs.The development version of Emacs can be downloaded from the CVSrepository where it is actively maintained by a group of developers.See the Emacs project page@url{http://savannah.gnu.org/projects/emacs/} for details.@node Service, Copying, Contributing, Top@section How To Get Help with GNU EmacsIf you need help installing, using or changing GNU Emacs, there are twoways to find it:@itemize @bullet@itemSend a message to the mailing list@email{help-gnu-emacs@@gnu.org}, or post your request onnewsgroup @code{gnu.emacs.help}. (This mailing list and newsgroupinterconnect, so it does not matter which one you use.)@itemLook 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 theEmacs distribution.@end itemize@ifnottex@lowersections@end ifnottex@ignore arch-tag: c9cba76d-b2cb-4e0c-ae3f-19d5ef35817c@end ignore