| 1 | @c This is part of the Emacs manual. |
| 2 | @c Copyright (C) 1985,86,87,93,94,95,1997,2001 Free Software Foundation, Inc. |
| 3 | @c See file emacs.texi for copying conditions. |
| 4 | @iftex |
| 5 | @chapter Dealing with Common Problems |
| 6 | |
| 7 | If you type an Emacs command you did not intend, the results are often |
| 8 | mysterious. This chapter tells what you can do to cancel your mistake or |
| 9 | recover from a mysterious situation. Emacs bugs and system crashes are |
| 10 | also considered. |
| 11 | @end iftex |
| 12 | |
| 13 | @node Quitting, Lossage, Customization, Top |
| 14 | @section Quitting and Aborting |
| 15 | @cindex quitting |
| 16 | |
| 17 | @table @kbd |
| 18 | @item C-g |
| 19 | @itemx C-@key{BREAK} @r{(MS-DOS only)} |
| 20 | Quit: cancel running or partially typed command. |
| 21 | @item C-] |
| 22 | Abort innermost recursive editing level and cancel the command which |
| 23 | invoked it (@code{abort-recursive-edit}). |
| 24 | @item @key{ESC} @key{ESC} @key{ESC} |
| 25 | Either quit or abort, whichever makes sense (@code{keyboard-escape-quit}). |
| 26 | @item M-x top-level |
| 27 | Abort all recursive editing levels that are currently executing. |
| 28 | @item C-x u |
| 29 | Cancel a previously made change in the buffer contents (@code{undo}). |
| 30 | @end table |
| 31 | |
| 32 | There are two ways of canceling commands which are not finished |
| 33 | executing: @dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with |
| 34 | @kbd{C-]} or @kbd{M-x top-level}. Quitting cancels a partially typed |
| 35 | command or one which is already running. Aborting exits a recursive |
| 36 | editing level and cancels the command that invoked the recursive edit. |
| 37 | (@xref{Recursive Edit}.) |
| 38 | |
| 39 | @cindex quitting |
| 40 | @kindex C-g |
| 41 | Quitting with @kbd{C-g} is used for getting rid of a partially typed |
| 42 | command, or a numeric argument that you don't want. It also stops a |
| 43 | running command in the middle in a relatively safe way, so you can use |
| 44 | it if you accidentally give a command which takes a long time. In |
| 45 | particular, it is safe to quit out of killing; either your text will |
| 46 | @emph{all} still be in the buffer, or it will @emph{all} be in the kill |
| 47 | ring (or maybe both). Quitting an incremental search does special |
| 48 | things documented under searching; in general, it may take two |
| 49 | successive @kbd{C-g} characters to get out of a search |
| 50 | (@pxref{Incremental Search}). |
| 51 | |
| 52 | On MS-DOS, the character @kbd{C-@key{BREAK}} serves as a quit character |
| 53 | like @kbd{C-g}. The reason is that it is not feasible, on MS-DOS, to |
| 54 | recognize @kbd{C-g} while a command is running, between interactions |
| 55 | with the user. By contrast, it @emph{is} feasible to recognize |
| 56 | @kbd{C-@key{BREAK}} at all times. @xref{MS-DOS Input}. |
| 57 | |
| 58 | @findex keyboard-quit |
| 59 | @kbd{C-g} works by setting the variable @code{quit-flag} to @code{t} |
| 60 | the instant @kbd{C-g} is typed; Emacs Lisp checks this variable |
| 61 | frequently and quits if it is non-@code{nil}. @kbd{C-g} is only |
| 62 | actually executed as a command if you type it while Emacs is waiting for |
| 63 | input. In that case, the command it runs is @code{keyboard-quit}. |
| 64 | |
| 65 | If you quit with @kbd{C-g} a second time before the first @kbd{C-g} is |
| 66 | recognized, you activate the ``emergency escape'' feature and return to |
| 67 | the shell. @xref{Emergency Escape}. |
| 68 | |
| 69 | @cindex NFS and quitting |
| 70 | There may be times when you cannot quit. When Emacs is waiting for |
| 71 | the operating system to do something, quitting is impossible unless |
| 72 | special pains are taken for the particular system call within Emacs |
| 73 | where the waiting occurs. We have done this for the system calls that |
| 74 | users are likely to want to quit from, but it's possible you will find |
| 75 | another. In one very common case---waiting for file input or output |
| 76 | using NFS---Emacs itself knows how to quit, but many NFS implementations |
| 77 | simply do not allow user programs to stop waiting for NFS when the NFS |
| 78 | server is hung. |
| 79 | |
| 80 | @cindex aborting recursive edit |
| 81 | @findex abort-recursive-edit |
| 82 | @kindex C-] |
| 83 | Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get |
| 84 | out of a recursive editing level and cancel the command which invoked |
| 85 | it. Quitting with @kbd{C-g} does not do this, and could not do this, |
| 86 | because it is used to cancel a partially typed command @emph{within} the |
| 87 | recursive editing level. Both operations are useful. For example, if |
| 88 | you are in a recursive edit and type @kbd{C-u 8} to enter a numeric |
| 89 | argument, you can cancel that argument with @kbd{C-g} and remain in the |
| 90 | recursive edit. |
| 91 | |
| 92 | @findex keyboard-escape-quit |
| 93 | @kindex ESC ESC ESC |
| 94 | The command @kbd{@key{ESC} @key{ESC} @key{ESC}} |
| 95 | (@code{keyboard-escape-quit}) can either quit or abort. This key was |
| 96 | defined because @key{ESC} is used to ``get out'' in many PC programs. |
| 97 | It can cancel a prefix argument, clear a selected region, or get out of |
| 98 | a Query Replace, like @kbd{C-g}. It can get out of the minibuffer or a |
| 99 | recursive edit, like @kbd{C-]}. It can also get out of splitting the |
| 100 | frame into multiple windows, like @kbd{C-x 1}. One thing it cannot do, |
| 101 | however, is stop a command that is running. That's because it executes |
| 102 | as an ordinary command, and Emacs doesn't notice it until it is ready |
| 103 | for a command. |
| 104 | |
| 105 | @findex top-level |
| 106 | The command @kbd{M-x top-level} is equivalent to ``enough'' @kbd{C-]} |
| 107 | commands to get you out of all the levels of recursive edits that you |
| 108 | are in. @kbd{C-]} gets you out one level at a time, but @kbd{M-x |
| 109 | top-level} goes out all levels at once. Both @kbd{C-]} and @kbd{M-x |
| 110 | top-level} are like all other commands, and unlike @kbd{C-g}, in that |
| 111 | they take effect only when Emacs is ready for a command. @kbd{C-]} is |
| 112 | an ordinary key and has its meaning only because of its binding in the |
| 113 | keymap. @xref{Recursive Edit}. |
| 114 | |
| 115 | @kbd{C-x u} (@code{undo}) is not strictly speaking a way of canceling |
| 116 | a command, but you can think of it as canceling a command that already |
| 117 | finished executing. @xref{Undo}, for more information |
| 118 | about the undo facility. |
| 119 | |
| 120 | @node Lossage, Bugs, Quitting, Top |
| 121 | @section Dealing with Emacs Trouble |
| 122 | |
| 123 | This section describes various conditions in which Emacs fails to work |
| 124 | normally, and how to recognize them and correct them. For a list of |
| 125 | additional problems you might encounter, see @ref{Bugs and problems, , |
| 126 | Bugs and problems, efaq, GNU Emacs FAQ}, and the file @file{etc/PROBLEMS} |
| 127 | in the Emacs distribution. Type @kbd{C-h F} to read the FAQ; type |
| 128 | @kbd{C-h P} to read the @file{PROBLEMS} file. |
| 129 | |
| 130 | @menu |
| 131 | * DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. |
| 132 | * Stuck Recursive:: `[...]' in mode line around the parentheses. |
| 133 | * Screen Garbled:: Garbage on the screen. |
| 134 | * Text Garbled:: Garbage in the text. |
| 135 | * Unasked-for Search:: Spontaneous entry to incremental search. |
| 136 | * Memory Full:: How to cope when you run out of memory. |
| 137 | * After a Crash:: Recovering editing in an Emacs session that crashed. |
| 138 | * Emergency Escape:: Emergency escape--- |
| 139 | What to do if Emacs stops responding. |
| 140 | * Total Frustration:: When you are at your wits' end. |
| 141 | @end menu |
| 142 | |
| 143 | @node DEL Does Not Delete |
| 144 | @subsection If @key{DEL} Fails to Delete |
| 145 | @cindex @key{DEL} vs @key{BACKSPACE} |
| 146 | @cindex @key{BACKSPACE} vs @key{DEL} |
| 147 | @cindex usual erasure key |
| 148 | |
| 149 | Every keyboard has a large key, a little ways above the @key{RET} or |
| 150 | @key{ENTER} key, which you normally use outside Emacs to erase the |
| 151 | last character that you typed. We call this key @dfn{the usual |
| 152 | erasure key}. In Emacs, it is supposed to be equivalent to @key{DEL}, |
| 153 | and when Emacs is properly configured for your terminal, it translates |
| 154 | that key into the character @key{DEL}. |
| 155 | |
| 156 | When Emacs starts up using a window system, it determines |
| 157 | automatically which key should be @key{DEL}. In some unusual cases |
| 158 | Emacs gets the wrong information from the system. If the usual |
| 159 | erasure key deletes forwards instead of backwards, that is probably |
| 160 | what happened---Emacs ought to be treating the @key{DELETE} key as |
| 161 | @key{DEL}, but it isn't. |
| 162 | |
| 163 | With a window system, if the usual erasure key is labeled |
| 164 | @key{BACKSPACE} and there is a @key{DELETE} key elsewhere, but the |
| 165 | @key{DELETE} key deletes backward instead of forward, that too |
| 166 | suggests Emacs got the wrong information---but in the opposite sense. |
| 167 | It ought to be treating the @key{BACKSPACE} key as @key{DEL}, and |
| 168 | treating @key{DELETE} differently, but it isn't. |
| 169 | |
| 170 | On a text-only terminal, if you find the usual erasure key prompts |
| 171 | for a Help command, like @kbd{Control-h}, instead of deleting a |
| 172 | character, it means that key is actually sending the @key{BS} |
| 173 | character. Emacs ought to be treating @key{BS} as @key{DEL}, but it |
| 174 | isn't. |
| 175 | |
| 176 | In all of those cases, the immediate remedy is the same: use the |
| 177 | command @kbd{M-x normal-erase-is-backspace-mode}. This toggles |
| 178 | between the two modes that Emacs supports for handling @key{DEL}, so |
| 179 | if Emacs starts in the wrong mode, it should switch to the right mode. |
| 180 | On a text-only terminal, if you want to ask for help when @key{BS} is |
| 181 | treated as @key{DEL}, use @key{F1}; @kbd{C-?} may also work, if it |
| 182 | sends character code 127. |
| 183 | |
| 184 | @findex normal-erase-is-backspace-mode |
| 185 | To fix the problem automatically for every Emacs session, you can |
| 186 | put one of the following lines into your @file{.emacs} file |
| 187 | (@pxref{Init File}). For the first case above, where @key{DELETE} |
| 188 | deletes forwards instead of backwards, use this line to make |
| 189 | @key{DELETE} act as @key{DEL} (resulting in behavior compatible |
| 190 | with Emacs 20 and previous versions): |
| 191 | |
| 192 | @lisp |
| 193 | (normal-erase-is-backspace-mode 0) |
| 194 | @end lisp |
| 195 | |
| 196 | @noindent |
| 197 | For the other two cases, where @key{BACKSPACE} ought to act as |
| 198 | @key{DEL}, use this line: |
| 199 | |
| 200 | @lisp |
| 201 | (normal-erase-is-backspace-mode 1) |
| 202 | @end lisp |
| 203 | |
| 204 | @vindex normal-erase-is-backspace |
| 205 | Another way to fix the problem for every Emacs session is to |
| 206 | customize the variable @code{normal-erase-is-backspace}: the value |
| 207 | @code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is |
| 208 | @key{DEL}, and @code{nil} specifies the other mode. @xref{Easy |
| 209 | Customization}. |
| 210 | |
| 211 | With a window system, it can also happen that the usual erasure key |
| 212 | is labeled @key{BACKSPACE}, there is a @key{DELETE} key elsewhere, and |
| 213 | both keys delete forward. This probably means that someone has |
| 214 | redefined your @key{BACKSPACE} key as a @key{DELETE} key. With X, |
| 215 | this is typically done with a command to the @code{xmodmap} program |
| 216 | when you start the server or log in. The most likely motive for this |
| 217 | customization was to support old versions of Emacs, so we recommend |
| 218 | you simply remove it now. |
| 219 | |
| 220 | @node Stuck Recursive |
| 221 | @subsection Recursive Editing Levels |
| 222 | |
| 223 | Recursive editing levels are important and useful features of Emacs, but |
| 224 | they can seem like malfunctions to the user who does not understand them. |
| 225 | |
| 226 | If the mode line has square brackets @samp{[@dots{}]} around the parentheses |
| 227 | that contain the names of the major and minor modes, you have entered a |
| 228 | recursive editing level. If you did not do this on purpose, or if you |
| 229 | don't understand what that means, you should just get out of the recursive |
| 230 | editing level. To do so, type @kbd{M-x top-level}. This is called getting |
| 231 | back to top level. @xref{Recursive Edit}. |
| 232 | |
| 233 | @node Screen Garbled |
| 234 | @subsection Garbage on the Screen |
| 235 | |
| 236 | If the data on the screen looks wrong, the first thing to do is see |
| 237 | whether the text is really wrong. Type @kbd{C-l} to redisplay the |
| 238 | entire screen. If the screen appears correct after this, the problem |
| 239 | was entirely in the previous screen update. (Otherwise, see the following |
| 240 | section.) |
| 241 | |
| 242 | Display updating problems often result from an incorrect termcap entry |
| 243 | for the terminal you are using. The file @file{etc/TERMS} in the Emacs |
| 244 | distribution gives the fixes for known problems of this sort. |
| 245 | @file{INSTALL} contains general advice for these problems in one of its |
| 246 | sections. Very likely there is simply insufficient padding for certain |
| 247 | display operations. To investigate the possibility that you have this sort |
| 248 | of problem, try Emacs on another terminal made by a different manufacturer. |
| 249 | If problems happen frequently on one kind of terminal but not another kind, |
| 250 | it is likely to be a bad termcap entry, though it could also be due to a |
| 251 | bug in Emacs that appears for terminals that have or that lack specific |
| 252 | features. |
| 253 | |
| 254 | @node Text Garbled |
| 255 | @subsection Garbage in the Text |
| 256 | |
| 257 | If @kbd{C-l} shows that the text is wrong, try undoing the changes to it |
| 258 | using @kbd{C-x u} until it gets back to a state you consider correct. Also |
| 259 | try @kbd{C-h l} to find out what command you typed to produce the observed |
| 260 | results. |
| 261 | |
| 262 | If a large portion of text appears to be missing at the beginning or |
| 263 | end of the buffer, check for the word @samp{Narrow} in the mode line. |
| 264 | If it appears, the text you don't see is probably still present, but |
| 265 | temporarily off-limits. To make it accessible again, type @kbd{C-x n |
| 266 | w}. @xref{Narrowing}. |
| 267 | |
| 268 | @node Unasked-for Search |
| 269 | @subsection Spontaneous Entry to Incremental Search |
| 270 | |
| 271 | If Emacs spontaneously displays @samp{I-search:} at the bottom of the |
| 272 | screen, it means that the terminal is sending @kbd{C-s} and @kbd{C-q} |
| 273 | according to the poorly designed xon/xoff ``flow control'' protocol. |
| 274 | |
| 275 | If this happens to you, your best recourse is to put the terminal in a |
| 276 | mode where it will not use flow control, or give it so much padding that |
| 277 | it will never send a @kbd{C-s}. (One way to increase the amount of |
| 278 | padding is to set the variable @code{baud-rate} to a larger value. Its |
| 279 | value is the terminal output speed, measured in the conventional units |
| 280 | of baud.) |
| 281 | |
| 282 | @cindex flow control |
| 283 | @cindex xon-xoff |
| 284 | @findex enable-flow-control |
| 285 | If you don't succeed in turning off flow control, the next best thing |
| 286 | is to tell Emacs to cope with it. To do this, call the function |
| 287 | @code{enable-flow-control}. |
| 288 | |
| 289 | @findex enable-flow-control-on |
| 290 | Typically there are particular terminal types with which you must use |
| 291 | flow control. You can conveniently ask for flow control on those |
| 292 | terminal types only, using @code{enable-flow-control-on}. For example, |
| 293 | if you find you must use flow control on VT-100 and H19 terminals, put |
| 294 | the following in your @file{.emacs} file: |
| 295 | |
| 296 | @example |
| 297 | (enable-flow-control-on "vt100" "h19") |
| 298 | @end example |
| 299 | |
| 300 | When flow control is enabled, you must type @kbd{C-\} to get the |
| 301 | effect of a @kbd{C-s}, and type @kbd{C-^} to get the effect of a |
| 302 | @kbd{C-q}. (These aliases work by means of keyboard translations; see |
| 303 | @ref{Keyboard Translations}.) |
| 304 | |
| 305 | @node Memory Full |
| 306 | @subsection Running out of Memory |
| 307 | @cindex memory full |
| 308 | @cindex out of memory |
| 309 | |
| 310 | If you get the error message @samp{Virtual memory exceeded}, save your |
| 311 | modified buffers with @kbd{C-x s}. This method of saving them has the |
| 312 | smallest need for additional memory. Emacs keeps a reserve of memory |
| 313 | which it makes available when this error happens; that should be enough |
| 314 | to enable @kbd{C-x s} to complete its work. |
| 315 | |
| 316 | Once you have saved your modified buffers, you can exit this Emacs job |
| 317 | and start another, or you can use @kbd{M-x kill-some-buffers} to free |
| 318 | space in the current Emacs job. If you kill buffers containing a |
| 319 | substantial amount of text, you can safely go on editing. Emacs refills |
| 320 | its memory reserve automatically when it sees sufficient free space |
| 321 | available, in case you run out of memory another time. |
| 322 | |
| 323 | Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run |
| 324 | out of memory, because the buffer menu needs a fair amount of memory |
| 325 | itself, and the reserve supply may not be enough. |
| 326 | |
| 327 | @node After a Crash |
| 328 | @subsection Recovery After a Crash |
| 329 | |
| 330 | If Emacs or the computer crashes, you can recover the files you were |
| 331 | editing at the time of the crash from their auto-save files. To do |
| 332 | this, start Emacs again and type the command @kbd{M-x recover-session}. |
| 333 | |
| 334 | This command initially displays a buffer which lists interrupted |
| 335 | session files, each with its date. You must choose which session to |
| 336 | recover from. Typically the one you want is the most recent one. Move |
| 337 | point to the one you choose, and type @kbd{C-c C-c}. |
| 338 | |
| 339 | Then @code{recover-session} asks about each of the files that you were |
| 340 | editing during that session; it asks whether to recover that file. If |
| 341 | you answer @kbd{y} for a file, it shows the dates of that file and its |
| 342 | auto-save file, then asks once again whether to recover that file. For |
| 343 | the second question, you must confirm with @kbd{yes}. If you do, Emacs |
| 344 | visits the file but gets the text from the auto-save file. |
| 345 | |
| 346 | When @code{recover-session} is done, the files you've chosen to |
| 347 | recover are present in Emacs buffers. You should then save them. Only |
| 348 | this---saving them---updates the files themselves. |
| 349 | |
| 350 | @node Emergency Escape |
| 351 | @subsection Emergency Escape |
| 352 | |
| 353 | Because at times there have been bugs causing Emacs to loop without |
| 354 | checking @code{quit-flag}, a special feature causes Emacs to be suspended |
| 355 | immediately if you type a second @kbd{C-g} while the flag is already set, |
| 356 | so you can always get out of GNU Emacs. Normally Emacs recognizes and |
| 357 | clears @code{quit-flag} (and quits!) quickly enough to prevent this from |
| 358 | happening. (On MS-DOS and compatible systems, type @kbd{C-@key{BREAK}} |
| 359 | twice.) |
| 360 | |
| 361 | When you resume Emacs after a suspension caused by multiple @kbd{C-g}, it |
| 362 | asks two questions before going back to what it had been doing: |
| 363 | |
| 364 | @example |
| 365 | Auto-save? (y or n) |
| 366 | Abort (and dump core)? (y or n) |
| 367 | @end example |
| 368 | |
| 369 | @noindent |
| 370 | Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}. |
| 371 | |
| 372 | Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of all |
| 373 | modified buffers in which auto-saving is enabled. |
| 374 | |
| 375 | Saying @kbd{y} to @samp{Abort (and dump core)?} causes an illegal instruction to be |
| 376 | executed, dumping core. This is to enable a wizard to figure out why Emacs |
| 377 | was failing to quit in the first place. Execution does not continue |
| 378 | after a core dump. If you answer @kbd{n}, execution does continue. With |
| 379 | luck, GNU Emacs will ultimately check @code{quit-flag} and quit normally. |
| 380 | If not, and you type another @kbd{C-g}, it is suspended again. |
| 381 | |
| 382 | If Emacs is not really hung, just slow, you may invoke the double |
| 383 | @kbd{C-g} feature without really meaning to. Then just resume and answer |
| 384 | @kbd{n} to both questions, and you will arrive at your former state. |
| 385 | Presumably the quit you requested will happen soon. |
| 386 | |
| 387 | The double @kbd{C-g} feature is turned off when Emacs is running under |
| 388 | the X Window System, since you can use the window manager to kill Emacs |
| 389 | or to create another window and run another program. |
| 390 | |
| 391 | On MS-DOS and compatible systems, the emergency escape feature is |
| 392 | sometimes unavailable, even if you press @kbd{C-@key{BREAK}} twice, when |
| 393 | some system call (MS-DOS or BIOS) hangs, or when Emacs is stuck in a |
| 394 | very tight endless loop (in C code, @strong{not} in Lisp code). |
| 395 | |
| 396 | @node Total Frustration |
| 397 | @subsection Help for Total Frustration |
| 398 | @cindex Eliza |
| 399 | @cindex doctor |
| 400 | |
| 401 | If using Emacs (or something else) becomes terribly frustrating and none |
| 402 | of the techniques described above solve the problem, Emacs can still help |
| 403 | you. |
| 404 | |
| 405 | First, if the Emacs you are using is not responding to commands, type |
| 406 | @kbd{C-g C-g} to get out of it and then start a new one. |
| 407 | |
| 408 | @findex doctor |
| 409 | Second, type @kbd{M-x doctor @key{RET}}. |
| 410 | |
| 411 | The doctor will help you feel better. Each time you say something to |
| 412 | the doctor, you must end it by typing @key{RET} @key{RET}. This lets |
| 413 | the doctor know you are finished. |
| 414 | |
| 415 | @node Bugs, Contributing, Lossage, Top |
| 416 | @section Reporting Bugs |
| 417 | |
| 418 | @cindex bugs |
| 419 | Sometimes you will encounter a bug in Emacs. Although we cannot |
| 420 | promise we can or will fix the bug, and we might not even agree that it |
| 421 | is a bug, we want to hear about problems you encounter. Often we agree |
| 422 | they are bugs and want to fix them. |
| 423 | |
| 424 | To make it possible for us to fix a bug, you must report it. In order |
| 425 | to do so effectively, you must know when and how to do it. |
| 426 | |
| 427 | Before reporting a bug, it is a good idea to see if it is already |
| 428 | known. You can find the list of known problems in the file |
| 429 | @file{etc/PROBLEMS} in the Emacs distribution; type @kbd{C-h P} to read |
| 430 | it. Some additional user-level problems can be found in @ref{Bugs and |
| 431 | problems, , Bugs and problems, efaq, GNU Emacs FAQ}. Looking up your |
| 432 | problem in these two documents might provide you with a solution or a |
| 433 | work-around, or give you additional information about related issues. |
| 434 | |
| 435 | @menu |
| 436 | * Criteria: Bug Criteria. Have you really found a bug? |
| 437 | * Understanding Bug Reporting:: How to report a bug effectively. |
| 438 | * Checklist:: Steps to follow for a good bug report. |
| 439 | * Sending Patches:: How to send a patch for GNU Emacs. |
| 440 | @end menu |
| 441 | |
| 442 | @node Bug Criteria |
| 443 | @subsection When Is There a Bug |
| 444 | |
| 445 | If Emacs executes an illegal instruction, or dies with an operating |
| 446 | system error message that indicates a problem in the program (as opposed to |
| 447 | something like ``disk full''), then it is certainly a bug. |
| 448 | |
| 449 | If Emacs updates the display in a way that does not correspond to what is |
| 450 | in the buffer, then it is certainly a bug. If a command seems to do the |
| 451 | wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a |
| 452 | case of incorrect display updating. |
| 453 | |
| 454 | Taking forever to complete a command can be a bug, but you must make |
| 455 | certain that it was really Emacs's fault. Some commands simply take a |
| 456 | long time. Type @kbd{C-g} (@kbd{C-@key{BREAK}} on MS-DOS) and then @kbd{C-h l} |
| 457 | to see whether the input Emacs received was what you intended to type; |
| 458 | if the input was such that you @emph{know} it should have been processed |
| 459 | quickly, report a bug. If you don't know whether the command should |
| 460 | take a long time, find out by looking in the manual or by asking for |
| 461 | assistance. |
| 462 | |
| 463 | If a command you are familiar with causes an Emacs error message in a |
| 464 | case where its usual definition ought to be reasonable, it is probably a |
| 465 | bug. |
| 466 | |
| 467 | If a command does the wrong thing, that is a bug. But be sure you know |
| 468 | for certain what it ought to have done. If you aren't familiar with the |
| 469 | command, or don't know for certain how the command is supposed to work, |
| 470 | then it might actually be working right. Rather than jumping to |
| 471 | conclusions, show the problem to someone who knows for certain. |
| 472 | |
| 473 | Finally, a command's intended definition may not be the best |
| 474 | possible definition for editing with. This is a very important sort |
| 475 | of problem, but it is also a matter of judgment. Also, it is easy to |
| 476 | come to such a conclusion out of ignorance of some of the existing |
| 477 | features. It is probably best not to complain about such a problem |
| 478 | until you have checked the documentation in the usual ways, feel |
| 479 | confident that you understand it, and know for certain that what you |
| 480 | want is not available. If you are not sure what the command is |
| 481 | supposed to do after a careful reading of the manual, check the index |
| 482 | and glossary for any terms that may be unclear. |
| 483 | |
| 484 | If after careful rereading of the manual you still do not understand |
| 485 | what the command should do, that indicates a bug in the manual, which |
| 486 | you should report. The manual's job is to make everything clear to |
| 487 | people who are not Emacs experts---including you. It is just as |
| 488 | important to report documentation bugs as program bugs. |
| 489 | |
| 490 | If the on-line documentation string of a function or variable disagrees |
| 491 | with the manual, one of them must be wrong; that is a bug. |
| 492 | |
| 493 | @node Understanding Bug Reporting |
| 494 | @subsection Understanding Bug Reporting |
| 495 | |
| 496 | @findex emacs-version |
| 497 | When you decide that there is a bug, it is important to report it and to |
| 498 | report it in a way which is useful. What is most useful is an exact |
| 499 | description of what commands you type, starting with the shell command to |
| 500 | run Emacs, until the problem happens. |
| 501 | |
| 502 | The most important principle in reporting a bug is to report |
| 503 | @emph{facts}. Hypotheses and verbal descriptions are no substitute for |
| 504 | the detailed raw data. Reporting the facts is straightforward, but many |
| 505 | people strain to posit explanations and report them instead of the |
| 506 | facts. If the explanations are based on guesses about how Emacs is |
| 507 | implemented, they will be useless; meanwhile, lacking the facts, we will |
| 508 | have no real information about the bug. |
| 509 | |
| 510 | For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh |
| 511 | @key{RET}}, visiting a file which (you know) happens to be rather large, |
| 512 | and Emacs displayed @samp{I feel pretty today}. The best way to report |
| 513 | the bug is with a sentence like the preceding one, because it gives all |
| 514 | the facts. |
| 515 | |
| 516 | A bad way would be to assume that the problem is due to the size of |
| 517 | the file and say, ``I visited a large file, and Emacs displayed @samp{I |
| 518 | feel pretty today}.'' This is what we mean by ``guessing |
| 519 | explanations.'' The problem is just as likely to be due to the fact |
| 520 | that there is a @samp{z} in the file name. If this is so, then when we |
| 521 | got your report, we would try out the problem with some ``large file,'' |
| 522 | probably with no @samp{z} in its name, and not see any problem. There |
| 523 | is no way in the world that we could guess that we should try visiting a |
| 524 | file with a @samp{z} in its name. |
| 525 | |
| 526 | Alternatively, the problem might be due to the fact that the file starts |
| 527 | with exactly 25 spaces. For this reason, you should make sure that you |
| 528 | inform us of the exact contents of any file that is needed to reproduce the |
| 529 | bug. What if the problem only occurs when you have typed the @kbd{C-x C-a} |
| 530 | command previously? This is why we ask you to give the exact sequence of |
| 531 | characters you typed since starting the Emacs session. |
| 532 | |
| 533 | You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless |
| 534 | you @emph{know} that it makes no difference which visiting command is used. |
| 535 | Similarly, rather than saying ``if I have three characters on the line,'' |
| 536 | say ``after I type @kbd{@key{RET} A B C @key{RET} C-p},'' if that is |
| 537 | the way you entered the text.@refill |
| 538 | |
| 539 | So please don't guess any explanations when you report a bug. If you |
| 540 | want to actually @emph{debug} the problem, and report explanations that |
| 541 | are more than guesses, that is useful---but please include the facts as |
| 542 | well. |
| 543 | |
| 544 | @node Checklist |
| 545 | @subsection Checklist for Bug Reports |
| 546 | |
| 547 | @cindex reporting bugs |
| 548 | The best way to send a bug report is to mail it electronically to the |
| 549 | Emacs maintainers at @email{bug-gnu-emacs@@gnu.org}, or to |
| 550 | @email{emacs-pretest-bug@@gnu.org} if you are pretesting an Emacs beta |
| 551 | release. (If you want to suggest a change as an improvement, use the |
| 552 | same address.) |
| 553 | |
| 554 | If you'd like to read the bug reports, you can find them on the |
| 555 | newsgroup @samp{gnu.emacs.bug}; keep in mind, however, that as a |
| 556 | spectator you should not criticize anything about what you see there. |
| 557 | The purpose of bug reports is to give information to the Emacs |
| 558 | maintainers. Spectators are welcome only as long as they do not |
| 559 | interfere with this. In particular, some bug reports contain fairly |
| 560 | large amounts of data; spectators should not complain about this. |
| 561 | |
| 562 | Please do not post bug reports using netnews; mail is more reliable |
| 563 | than netnews about reporting your correct address, which we may need |
| 564 | in order to ask you for more information. If your data is more than |
| 565 | 500,000 bytes, please don't include it directly in the bug report; |
| 566 | instead, offer to send it on request, or make it available by ftp and |
| 567 | say where. |
| 568 | |
| 569 | If you can't send electronic mail, then mail the bug report on paper |
| 570 | or machine-readable media to this address: |
| 571 | |
| 572 | @format |
| 573 | GNU Emacs Bugs |
| 574 | Free Software Foundation |
| 575 | 59 Temple Place, Suite 330 |
| 576 | Boston, MA 02111-1307 USA |
| 577 | @end format |
| 578 | |
| 579 | We do not promise to fix the bug; but if the bug is serious, |
| 580 | or ugly, or easy to fix, chances are we will want to. |
| 581 | |
| 582 | @findex report-emacs-bug |
| 583 | A convenient way to send a bug report for Emacs is to use the command |
| 584 | @kbd{M-x report-emacs-bug}. This sets up a mail buffer (@pxref{Sending |
| 585 | Mail}) and automatically inserts @emph{some} of the essential |
| 586 | information. However, it cannot supply all the necessary information; |
| 587 | you should still read and follow the guidelines below, so you can enter |
| 588 | the other crucial information by hand before you send the message. |
| 589 | |
| 590 | To enable maintainers to investigate a bug, your report |
| 591 | should include all these things: |
| 592 | |
| 593 | @itemize @bullet |
| 594 | @item |
| 595 | The version number of Emacs. Without this, we won't know whether there |
| 596 | is any point in looking for the bug in the current version of GNU |
| 597 | Emacs. |
| 598 | |
| 599 | You can get the version number by typing @kbd{M-x emacs-version |
| 600 | @key{RET}}. If that command does not work, you probably have something |
| 601 | other than GNU Emacs, so you will have to report the bug somewhere |
| 602 | else. |
| 603 | |
| 604 | @item |
| 605 | The type of machine you are using, and the operating system name and |
| 606 | version number. @kbd{M-x emacs-version @key{RET}} provides this |
| 607 | information too. Copy its output from the @samp{*Messages*} buffer, so |
| 608 | that you get it all and get it accurately. |
| 609 | |
| 610 | @item |
| 611 | The operands given to the @code{configure} command when Emacs was |
| 612 | installed. |
| 613 | |
| 614 | @item |
| 615 | A complete list of any modifications you have made to the Emacs source. |
| 616 | (We may not have time to investigate the bug unless it happens in an |
| 617 | unmodified Emacs. But if you've made modifications and you don't tell |
| 618 | us, you are sending us on a wild goose chase.) |
| 619 | |
| 620 | Be precise about these changes. A description in English is not |
| 621 | enough---send a context diff for them. |
| 622 | |
| 623 | Adding files of your own, or porting to another machine, is a |
| 624 | modification of the source. |
| 625 | |
| 626 | @item |
| 627 | Details of any other deviations from the standard procedure for installing |
| 628 | GNU Emacs. |
| 629 | |
| 630 | @item |
| 631 | The complete text of any files needed to reproduce the bug. |
| 632 | |
| 633 | If you can tell us a way to cause the problem without visiting any files, |
| 634 | please do so. This makes it much easier to debug. If you do need files, |
| 635 | make sure you arrange for us to see their exact contents. For example, it |
| 636 | can often matter whether there are spaces at the ends of lines, or a |
| 637 | newline after the last line in the buffer (nothing ought to care whether |
| 638 | the last line is terminated, but try telling the bugs that). |
| 639 | |
| 640 | @item |
| 641 | The precise commands we need to type to reproduce the bug. |
| 642 | |
| 643 | @findex open-dribble-file |
| 644 | @cindex dribble file |
| 645 | @cindex logging keystrokes |
| 646 | The easy way to record the input to Emacs precisely is to write a |
| 647 | dribble file. To start the file, execute the Lisp expression |
| 648 | |
| 649 | @example |
| 650 | (open-dribble-file "~/dribble") |
| 651 | @end example |
| 652 | |
| 653 | @noindent |
| 654 | using @kbd{M-:} or from the @samp{*scratch*} buffer just after |
| 655 | starting Emacs. From then on, Emacs copies all your input to the |
| 656 | specified dribble file until the Emacs process is killed. |
| 657 | |
| 658 | @item |
| 659 | @findex open-termscript |
| 660 | @cindex termscript file |
| 661 | @cindex @env{TERM} environment variable |
| 662 | For possible display bugs, the terminal type (the value of environment |
| 663 | variable @env{TERM}), the complete termcap entry for the terminal from |
| 664 | @file{/etc/termcap} (since that file is not identical on all machines), |
| 665 | and the output that Emacs actually sent to the terminal. |
| 666 | |
| 667 | The way to collect the terminal output is to execute the Lisp expression |
| 668 | |
| 669 | @example |
| 670 | (open-termscript "~/termscript") |
| 671 | @end example |
| 672 | |
| 673 | @noindent |
| 674 | using @kbd{M-:} or from the @samp{*scratch*} buffer just after |
| 675 | starting Emacs. From then on, Emacs copies all terminal output to the |
| 676 | specified termscript file as well, until the Emacs process is killed. |
| 677 | If the problem happens when Emacs starts up, put this expression into |
| 678 | your @file{.emacs} file so that the termscript file will be open when |
| 679 | Emacs displays the screen for the first time. |
| 680 | |
| 681 | Be warned: it is often difficult, and sometimes impossible, to fix a |
| 682 | terminal-dependent bug without access to a terminal of the type that |
| 683 | stimulates the bug.@refill |
| 684 | |
| 685 | @item |
| 686 | If non-ASCII text or internationalization is relevant, the locale that |
| 687 | was current when you started Emacs. On GNU/Linux and Unix systems, or |
| 688 | if you use a Posix-style shell such as Bash, you can use this shell |
| 689 | command to view the relevant values: |
| 690 | |
| 691 | @smallexample |
| 692 | echo LC_ALL=$LC_ALL LC_COLLATE=$LC_COLLATE LC_TYPE=$LC_TYPE \ |
| 693 | LC_MESSAGES=$LC_MESSAGES LC_TIME=$LC_TIME LANG=$LANG |
| 694 | @end smallexample |
| 695 | |
| 696 | Alternatively, use the @command{locale} command, if your system has it, |
| 697 | to display your locale settings. |
| 698 | |
| 699 | You can use the @kbd{M-!} command to execute these commands from |
| 700 | Emacs, and then copy the output from the @samp{*Messages*} buffer into |
| 701 | the bug report. Alternatively, @kbd{M-x getenv @key{RET} LC_ALL |
| 702 | @key{RET}} will display the value of @code{LC_ALL} in the echo area, and |
| 703 | you can copy its output from the @samp{*Messages*} buffer. |
| 704 | |
| 705 | @item |
| 706 | A description of what behavior you observe that you believe is |
| 707 | incorrect. For example, ``The Emacs process gets a fatal signal,'' or, |
| 708 | ``The resulting text is as follows, which I think is wrong.'' |
| 709 | |
| 710 | Of course, if the bug is that Emacs gets a fatal signal, then one can't |
| 711 | miss it. But if the bug is incorrect text, the maintainer might fail to |
| 712 | notice what is wrong. Why leave it to chance? |
| 713 | |
| 714 | Even if the problem you experience is a fatal signal, you should still |
| 715 | say so explicitly. Suppose something strange is going on, such as, your |
| 716 | copy of the source is out of sync, or you have encountered a bug in the |
| 717 | C library on your system. (This has happened!) Your copy might crash |
| 718 | and the copy here might not. If you @emph{said} to expect a crash, then |
| 719 | when Emacs here fails to crash, we would know that the bug was not |
| 720 | happening. If you don't say to expect a crash, then we would not know |
| 721 | whether the bug was happening---we would not be able to draw any |
| 722 | conclusion from our observations. |
| 723 | |
| 724 | @item |
| 725 | If the bug is that the Emacs Manual or the Emacs Lisp Reference Manual |
| 726 | fails to describe the actual behavior of Emacs, or that the text is |
| 727 | confusing, copy in the text from the online manual which you think is |
| 728 | at fault. If the section is small, just the section name is enough. |
| 729 | |
| 730 | @item |
| 731 | If the manifestation of the bug is an Emacs error message, it is |
| 732 | important to report the precise text of the error message, and a |
| 733 | backtrace showing how the Lisp program in Emacs arrived at the error. |
| 734 | |
| 735 | To get the error message text accurately, copy it from the |
| 736 | @samp{*Messages*} buffer into the bug report. Copy all of it, not just |
| 737 | part. |
| 738 | |
| 739 | @findex toggle-debug-on-error |
| 740 | @pindex Edebug |
| 741 | To make a backtrace for the error, use @kbd{M-x toggle-debug-on-error} |
| 742 | before the error happens (that is to say, you must give that command |
| 743 | and then make the bug happen). This causes the error to run the Lisp |
| 744 | debugger, which shows you a backtrace. Copy the text of the |
| 745 | debugger's backtrace into the bug report. @xref{Debugger,, The Lisp |
| 746 | Debugger, elisp, the Emacs Lisp Reference Manual}, for information on |
| 747 | debugging Emacs Lisp programs with the Edebug package. |
| 748 | |
| 749 | This use of the debugger is possible only if you know how to make the |
| 750 | bug happen again. If you can't make it happen again, at least copy |
| 751 | the whole error message. |
| 752 | |
| 753 | @item |
| 754 | Check whether any programs you have loaded into the Lisp world, |
| 755 | including your @file{.emacs} file, set any variables that may affect the |
| 756 | functioning of Emacs. Also, see whether the problem happens in a |
| 757 | freshly started Emacs without loading your @file{.emacs} file (start |
| 758 | Emacs with the @code{-q} switch to prevent loading the init file). If |
| 759 | the problem does @emph{not} occur then, you must report the precise |
| 760 | contents of any programs that you must load into the Lisp world in order |
| 761 | to cause the problem to occur. |
| 762 | |
| 763 | @item |
| 764 | If the problem does depend on an init file or other Lisp programs that |
| 765 | are not part of the standard Emacs system, then you should make sure it |
| 766 | is not a bug in those programs by complaining to their maintainers |
| 767 | first. After they verify that they are using Emacs in a way that is |
| 768 | supposed to work, they should report the bug. |
| 769 | |
| 770 | @item |
| 771 | If you wish to mention something in the GNU Emacs source, show the line |
| 772 | of code with a few lines of context. Don't just give a line number. |
| 773 | |
| 774 | The line numbers in the development sources don't match those in your |
| 775 | sources. It would take extra work for the maintainers to determine what |
| 776 | code is in your version at a given line number, and we could not be |
| 777 | certain. |
| 778 | |
| 779 | @item |
| 780 | Additional information from a C debugger such as GDB might enable |
| 781 | someone to find a problem on a machine which he does not have available. |
| 782 | If you don't know how to use GDB, please read the GDB manual---it is not |
| 783 | very long, and using GDB is easy. You can find the GDB distribution, |
| 784 | including the GDB manual in online form, in most of the same places you |
| 785 | can find the Emacs distribution. To run Emacs under GDB, you should |
| 786 | switch to the @file{src} subdirectory in which Emacs was compiled, then |
| 787 | do @samp{gdb emacs}. It is important for the directory @file{src} to be |
| 788 | current so that GDB will read the @file{.gdbinit} file in this |
| 789 | directory. |
| 790 | |
| 791 | However, you need to think when you collect the additional information |
| 792 | if you want it to show what causes the bug. |
| 793 | |
| 794 | @cindex backtrace for bug reports |
| 795 | For example, many people send just a backtrace, but that is not very |
| 796 | useful by itself. A simple backtrace with arguments often conveys |
| 797 | little about what is happening inside GNU Emacs, because most of the |
| 798 | arguments listed in the backtrace are pointers to Lisp objects. The |
| 799 | numeric values of these pointers have no significance whatever; all that |
| 800 | matters is the contents of the objects they point to (and most of the |
| 801 | contents are themselves pointers). |
| 802 | |
| 803 | @findex debug_print |
| 804 | To provide useful information, you need to show the values of Lisp |
| 805 | objects in Lisp notation. Do this for each variable which is a Lisp |
| 806 | object, in several stack frames near the bottom of the stack. Look at |
| 807 | the source to see which variables are Lisp objects, because the debugger |
| 808 | thinks of them as integers. |
| 809 | |
| 810 | To show a variable's value in Lisp syntax, first print its value, then |
| 811 | use the user-defined GDB command @code{pr} to print the Lisp object in |
| 812 | Lisp syntax. (If you must use another debugger, call the function |
| 813 | @code{debug_print} with the object as an argument.) The @code{pr} |
| 814 | command is defined by the file @file{.gdbinit}, and it works only if you |
| 815 | are debugging a running process (not with a core dump). |
| 816 | |
| 817 | To make Lisp errors stop Emacs and return to GDB, put a breakpoint at |
| 818 | @code{Fsignal}. |
| 819 | |
| 820 | For a short listing of Lisp functions running, type the GDB |
| 821 | command @code{xbacktrace}. |
| 822 | |
| 823 | The file @file{.gdbinit} defines several other commands that are useful |
| 824 | for examining the data types and contents of Lisp objects. Their names |
| 825 | begin with @samp{x}. These commands work at a lower level than |
| 826 | @code{pr}, and are less convenient, but they may work even when |
| 827 | @code{pr} does not, such as when debugging a core dump or when Emacs has |
| 828 | had a fatal signal. |
| 829 | |
| 830 | @cindex debugging Emacs, tricks and techniques |
| 831 | More detailed advice and other useful techniques for debugging Emacs |
| 832 | are available in the file @file{etc/DEBUG} in the Emacs distribution. |
| 833 | That file also includes instructions for investigating problems |
| 834 | whereby Emacs stops responding (many people assume that Emacs is |
| 835 | ``hung,'' whereas in fact it might be in an infinite loop). |
| 836 | |
| 837 | To find the file @file{etc/DEBUG} in your Emacs installation, use the |
| 838 | directory name stored in the variable @code{data-directory}. |
| 839 | @end itemize |
| 840 | |
| 841 | Here are some things that are not necessary in a bug report: |
| 842 | |
| 843 | @itemize @bullet |
| 844 | @item |
| 845 | A description of the envelope of the bug---this is not necessary for a |
| 846 | reproducible bug. |
| 847 | |
| 848 | Often people who encounter a bug spend a lot of time investigating |
| 849 | which changes to the input file will make the bug go away and which |
| 850 | changes will not affect it. |
| 851 | |
| 852 | This is often time-consuming and not very useful, because the way we |
| 853 | will find the bug is by running a single example under the debugger |
| 854 | with breakpoints, not by pure deduction from a series of examples. |
| 855 | You might as well save time by not searching for additional examples. |
| 856 | It is better to send the bug report right away, go back to editing, |
| 857 | and find another bug to report. |
| 858 | |
| 859 | Of course, if you can find a simpler example to report @emph{instead} of |
| 860 | the original one, that is a convenience. Errors in the output will be |
| 861 | easier to spot, running under the debugger will take less time, etc. |
| 862 | |
| 863 | However, simplification is not vital; if you can't do this or don't have |
| 864 | time to try, please report the bug with your original test case. |
| 865 | |
| 866 | @item |
| 867 | A core dump file. |
| 868 | |
| 869 | Debugging the core dump might be useful, but it can only be done on |
| 870 | your machine, with your Emacs executable. Therefore, sending the core |
| 871 | dump file to the Emacs maintainers won't be useful. Above all, don't |
| 872 | include the core file in an email bug report! Such a large message |
| 873 | can be extremely inconvenient. |
| 874 | |
| 875 | @item |
| 876 | A system-call trace of Emacs execution. |
| 877 | |
| 878 | System-call traces are very useful for certain special kinds of |
| 879 | debugging, but in most cases they give little useful information. It is |
| 880 | therefore strange that many people seem to think that @emph{the} way to |
| 881 | report information about a crash is to send a system-call trace. Perhaps |
| 882 | this is a habit formed from experience debugging programs that don't |
| 883 | have source code or debugging symbols. |
| 884 | |
| 885 | In most programs, a backtrace is normally far, far more informative than |
| 886 | a system-call trace. Even in Emacs, a simple backtrace is generally |
| 887 | more informative, though to give full information you should supplement |
| 888 | the backtrace by displaying variable values and printing them as Lisp |
| 889 | objects with @code{pr} (see above). |
| 890 | |
| 891 | @item |
| 892 | A patch for the bug. |
| 893 | |
| 894 | A patch for the bug is useful if it is a good one. But don't omit the |
| 895 | other information that a bug report needs, such as the test case, on the |
| 896 | assumption that a patch is sufficient. We might see problems with your |
| 897 | patch and decide to fix the problem another way, or we might not |
| 898 | understand it at all. And if we can't understand what bug you are |
| 899 | trying to fix, or why your patch should be an improvement, we mustn't |
| 900 | install it. |
| 901 | |
| 902 | @ifinfo |
| 903 | @xref{Sending Patches}, for guidelines on how to make it easy for us to |
| 904 | understand and install your patches. |
| 905 | @end ifinfo |
| 906 | |
| 907 | @item |
| 908 | A guess about what the bug is or what it depends on. |
| 909 | |
| 910 | Such guesses are usually wrong. Even experts can't guess right about |
| 911 | such things without first using the debugger to find the facts. |
| 912 | @end itemize |
| 913 | |
| 914 | @node Sending Patches |
| 915 | @subsection Sending Patches for GNU Emacs |
| 916 | |
| 917 | @cindex sending patches for GNU Emacs |
| 918 | @cindex patches, sending |
| 919 | If you would like to write bug fixes or improvements for GNU Emacs, |
| 920 | that is very helpful. When you send your changes, please follow these |
| 921 | guidelines to make it easy for the maintainers to use them. If you |
| 922 | don't follow these guidelines, your information might still be useful, |
| 923 | but using it will take extra work. Maintaining GNU Emacs is a lot of |
| 924 | work in the best of circumstances, and we can't keep up unless you do |
| 925 | your best to help. |
| 926 | |
| 927 | @itemize @bullet |
| 928 | @item |
| 929 | Send an explanation with your changes of what problem they fix or what |
| 930 | improvement they bring about. For a bug fix, just include a copy of the |
| 931 | bug report, and explain why the change fixes the bug. |
| 932 | |
| 933 | (Referring to a bug report is not as good as including it, because then |
| 934 | we will have to look it up, and we have probably already deleted it if |
| 935 | we've already fixed the bug.) |
| 936 | |
| 937 | @item |
| 938 | Always include a proper bug report for the problem you think you have |
| 939 | fixed. We need to convince ourselves that the change is right before |
| 940 | installing it. Even if it is correct, we might have trouble |
| 941 | understanding it if we don't have a way to reproduce the problem. |
| 942 | |
| 943 | @item |
| 944 | Include all the comments that are appropriate to help people reading the |
| 945 | source in the future understand why this change was needed. |
| 946 | |
| 947 | @item |
| 948 | Don't mix together changes made for different reasons. |
| 949 | Send them @emph{individually}. |
| 950 | |
| 951 | If you make two changes for separate reasons, then we might not want to |
| 952 | install them both. We might want to install just one. If you send them |
| 953 | all jumbled together in a single set of diffs, we have to do extra work |
| 954 | to disentangle them---to figure out which parts of the change serve |
| 955 | which purpose. If we don't have time for this, we might have to ignore |
| 956 | your changes entirely. |
| 957 | |
| 958 | If you send each change as soon as you have written it, with its own |
| 959 | explanation, then two changes never get tangled up, and we can consider |
| 960 | each one properly without any extra work to disentangle them. |
| 961 | |
| 962 | @item |
| 963 | Send each change as soon as that change is finished. Sometimes people |
| 964 | think they are helping us by accumulating many changes to send them all |
| 965 | together. As explained above, this is absolutely the worst thing you |
| 966 | could do. |
| 967 | |
| 968 | Since you should send each change separately, you might as well send it |
| 969 | right away. That gives us the option of installing it immediately if it |
| 970 | is important. |
| 971 | |
| 972 | @item |
| 973 | Use @samp{diff -c} to make your diffs. Diffs without context are hard |
| 974 | to install reliably. More than that, they are hard to study; we must |
| 975 | always study a patch to decide whether we want to install it. Unidiff |
| 976 | format is better than contextless diffs, but not as easy to read as |
| 977 | @samp{-c} format. |
| 978 | |
| 979 | If you have GNU diff, use @samp{diff -c -F'^[_a-zA-Z0-9$]+ *('} when |
| 980 | making diffs of C code. This shows the name of the function that each |
| 981 | change occurs in. |
| 982 | |
| 983 | @item |
| 984 | Avoid any ambiguity as to which is the old version and which is the new. |
| 985 | Please make the old version the first argument to diff, and the new |
| 986 | version the second argument. And please give one version or the other a |
| 987 | name that indicates whether it is the old version or your new changed |
| 988 | one. |
| 989 | |
| 990 | @item |
| 991 | Write the change log entries for your changes. This is both to save us |
| 992 | the extra work of writing them, and to help explain your changes so we |
| 993 | can understand them. |
| 994 | |
| 995 | The purpose of the change log is to show people where to find what was |
| 996 | changed. So you need to be specific about what functions you changed; |
| 997 | in large functions, it's often helpful to indicate where within the |
| 998 | function the change was. |
| 999 | |
| 1000 | On the other hand, once you have shown people where to find the change, |
| 1001 | you need not explain its purpose in the change log. Thus, if you add a |
| 1002 | new function, all you need to say about it is that it is new. If you |
| 1003 | feel that the purpose needs explaining, it probably does---but put the |
| 1004 | explanation in comments in the code. It will be more useful there. |
| 1005 | |
| 1006 | Please read the @file{ChangeLog} files in the @file{src} and @file{lisp} |
| 1007 | directories to see what sorts of information to put in, and to learn the |
| 1008 | style that we use. If you would like your name to appear in the header |
| 1009 | line, showing who made the change, send us the header line. |
| 1010 | @xref{Change Log}. |
| 1011 | |
| 1012 | @item |
| 1013 | When you write the fix, keep in mind that we can't install a change that |
| 1014 | would break other systems. Please think about what effect your change |
| 1015 | will have if compiled on another type of system. |
| 1016 | |
| 1017 | Sometimes people send fixes that @emph{might} be an improvement in |
| 1018 | general---but it is hard to be sure of this. It's hard to install |
| 1019 | such changes because we have to study them very carefully. Of course, |
| 1020 | a good explanation of the reasoning by which you concluded the change |
| 1021 | was correct can help convince us. |
| 1022 | |
| 1023 | The safest changes are changes to the configuration files for a |
| 1024 | particular machine. These are safe because they can't create new bugs |
| 1025 | on other machines. |
| 1026 | |
| 1027 | Please help us keep up with the workload by designing the patch in a |
| 1028 | form that is clearly safe to install. |
| 1029 | @end itemize |
| 1030 | |
| 1031 | @node Contributing, Service, Bugs, Top |
| 1032 | @section Contributing to Emacs Development |
| 1033 | |
| 1034 | If you would like to help pretest Emacs releases to assure they work |
| 1035 | well, or if you would like to work on improving Emacs, please contact |
| 1036 | the maintainers at @email{bug-gnu-emacs@@gnu.org}. A pretester |
| 1037 | should be prepared to investigate bugs as well as report them. If you'd |
| 1038 | like to work on improving Emacs, please ask for suggested projects or |
| 1039 | suggest your own ideas. |
| 1040 | |
| 1041 | If you have already written an improvement, please tell us about it. If |
| 1042 | you have not yet started work, it is useful to contact |
| 1043 | @email{bug-gnu-emacs@@gnu.org} before you start; it might be |
| 1044 | possible to suggest ways to make your extension fit in better with the |
| 1045 | rest of Emacs. |
| 1046 | |
| 1047 | @node Service, Command Arguments, Contributing, Top |
| 1048 | @section How To Get Help with GNU Emacs |
| 1049 | |
| 1050 | If you need help installing, using or changing GNU Emacs, there are two |
| 1051 | ways to find it: |
| 1052 | |
| 1053 | @itemize @bullet |
| 1054 | @item |
| 1055 | Send a message to the mailing list |
| 1056 | @email{help-gnu-emacs@@gnu.org}, or post your request on |
| 1057 | newsgroup @code{gnu.emacs.help}. (This mailing list and newsgroup |
| 1058 | interconnect, so it does not matter which one you use.) |
| 1059 | |
| 1060 | @item |
| 1061 | Look in the service directory for someone who might help you for a fee. |
| 1062 | The service directory is found in the file named @file{etc/SERVICE} in the |
| 1063 | Emacs distribution. |
| 1064 | @end itemize |