0001: @c This is part of the Emacs manual.
0002: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2019 Free Software
0003: @c Foundation, Inc.
0004: @c See file emacs.texi for copying conditions.
0005: @iftex
0006: @chapter Dealing with Common Problems
0007: 
0008:   If you type an Emacs command you did not intend, the results are often
0009: mysterious.  This chapter tells what you can do to cancel your mistake or
0010: recover from a mysterious situation.  Emacs bugs and system crashes are
0011: also considered.
0012: @end iftex
0013: 
0014: @ifnottex
0015: @raisesections
0016: @end ifnottex
0017: 
0018: @node Quitting
0019: @section Quitting and Aborting
0020: 
0021: @table @kbd
0022: @item C-g
0023: @itemx C-@key{Break} @r{(MS-DOS only)}
0024: Quit: cancel running or partially typed command.
0025: @item C-]
0026: Abort innermost recursive editing level and cancel the command which
0027: invoked it (@code{abort-recursive-edit}).
0028: @item @key{ESC} @key{ESC} @key{ESC}
0029: Either quit or abort, whichever makes sense (@code{keyboard-escape-quit}).
0030: @item M-x top-level
0031: Abort all recursive editing levels that are currently executing.
0032: @item C-/
0033: @itemx C-x u
0034: @itemx C-_
0035: Cancel a previously made change in the buffer contents (@code{undo}).
0036: @end table
0037: 
0038:   There are two ways of canceling a command before it has finished:
0039: @dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]} or
0040: @kbd{M-x top-level}.  Quitting cancels a partially typed command, or
0041: one which is still running.  Aborting exits a recursive editing level
0042: and cancels the command that invoked the recursive edit
0043: (@pxref{Recursive Edit}).
0044: 
0045: @cindex quitting
0046: @kindex C-g
0047:   Quitting with @kbd{C-g} is the way to get rid of a partially typed
0048: command, or a numeric argument that you don't want.  Furthermore, if
0049: you are in the middle of a command that is running, @kbd{C-g} stops
0050: the command in a relatively safe way.  For example, if you quit out of
0051: a kill command that is taking a long time, either your text will
0052: @emph{all} still be in the buffer, or it will @emph{all} be in the
0053: kill ring, or maybe both.  If the region is active, @kbd{C-g}
0054: deactivates the mark, unless Transient Mark mode is off
0055: (@pxref{Disabled Transient Mark}).  If you are in the middle of an
0056: incremental search, @kbd{C-g} behaves specially; it may take two
0057: successive @kbd{C-g} characters to get out of a search.
0058: @xref{Incremental Search}, for details.
0059: 
0060:   On MS-DOS, the character @kbd{C-@key{Break}} serves as a quit character
0061: like @kbd{C-g}.  The reason is that it is not feasible, on MS-DOS, to
0062: recognize @kbd{C-g} while a command is running, between interactions
0063: with the user.  By contrast, it @emph{is} feasible to recognize
0064: @kbd{C-@key{Break}} at all times.
0065: @iftex
0066: @xref{MS-DOS Keyboard,,,emacs-xtra, Specialized Emacs Features}.
0067: @end iftex
0068: @ifnottex
0069: @xref{MS-DOS Keyboard}.
0070: @end ifnottex
0071: 
0072: @findex keyboard-quit
0073:   @kbd{C-g} works by setting the variable @code{quit-flag} to @code{t}
0074: the instant @kbd{C-g} is typed; Emacs Lisp checks this variable
0075: frequently, and quits if it is non-@code{nil}.  @kbd{C-g} is only
0076: actually executed as a command if you type it while Emacs is waiting for
0077: input.  In that case, the command it runs is @code{keyboard-quit}.
0078: 
0079:   On a text terminal, if you quit with @kbd{C-g} a second time before
0080: the first @kbd{C-g} is recognized, you activate the emergency-escape
0081: feature and return to the shell.  @xref{Emergency Escape}.
0082: 
0083: @cindex NFS and quitting
0084:   There are some situations where you cannot quit.  When Emacs is
0085: waiting for the operating system to do something, quitting is
0086: impossible unless special pains are taken for the particular system
0087: call within Emacs where the waiting occurs.  We have done this for the
0088: system calls that users are likely to want to quit from, but it's
0089: possible you will encounter a case not handled.  In one very common
0090: case---waiting for file input or output using NFS---Emacs itself knows
0091: how to quit, but many NFS implementations simply do not allow user
0092: programs to stop waiting for NFS when the NFS server is hung.
0093: 
0094: @cindex aborting recursive edit
0095: @findex abort-recursive-edit
0096: @kindex C-]
0097:   Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get
0098: out of a recursive editing level and cancel the command which invoked
0099: it.  Quitting with @kbd{C-g} does not do this, and could not do this,
0100: because it is used to cancel a partially typed command @emph{within} the
0101: recursive editing level.  Both operations are useful.  For example, if
0102: you are in a recursive edit and type @kbd{C-u 8} to enter a numeric
0103: argument, you can cancel that argument with @kbd{C-g} and remain in the
0104: recursive edit.
0105: 
0106: @findex keyboard-escape-quit
0107: @kindex ESC ESC ESC
0108:   The sequence @kbd{@key{ESC} @key{ESC} @key{ESC}}
0109: (@code{keyboard-escape-quit}) can either quit or abort.  (We defined
0110: it this way because @key{ESC} means ``get out'' in many PC programs.)
0111: It can cancel a prefix argument, clear a selected region, or get out
0112: of a Query Replace, like @kbd{C-g}.  It can get out of the minibuffer
0113: or a recursive edit, like @kbd{C-]}.  It can also get out of splitting
0114: the frame into multiple windows, as with @kbd{C-x 1}.  One thing it
0115: cannot do, however, is stop a command that is running.  That's because
0116: it executes as an ordinary command, and Emacs doesn't notice it until
0117: it is ready for the next command.
0118: 
0119: @findex top-level
0120:   The command @kbd{M-x top-level} is equivalent to enough
0121: @kbd{C-]} commands to get you out of all the levels of recursive edits
0122: that you are in; it also exits the minibuffer if it is active.
0123: @kbd{C-]} gets you out one level at a time, but @kbd{M-x top-level}
0124: goes out all levels at once.  Both @kbd{C-]} and @kbd{M-x top-level}
0125: are like all other commands, and unlike @kbd{C-g}, in that they take
0126: effect only when Emacs is ready for a command.  @kbd{C-]} is an
0127: ordinary key and has its meaning only because of its binding in the
0128: keymap.  @xref{Recursive Edit}.
0129: 
0130:   @kbd{C-/} (@code{undo}) is not strictly speaking a way of canceling
0131: a command, but you can think of it as canceling a command that already
0132: finished executing.  @xref{Undo}, for more information about the undo
0133: facility.
0134: 
0135: @node Lossage
0136: @section Dealing with Emacs Trouble
0137: @cindex troubleshooting Emacs
0138: 
0139:   This section describes how to recognize and deal with situations in
0140: which Emacs does not work as you expect, such as keyboard code mixups,
0141: garbled displays, running out of memory, and crashes and hangs.
0142: 
0143:   @xref{Bugs}, for what to do when you think you have found a bug in
0144: Emacs.
0145: 
0146: @menu
0147: * DEL Does Not Delete::   What to do if @key{DEL} doesn't delete.
0148: * Stuck Recursive::       '[...]' in mode line around the parentheses.
0149: * Screen Garbled::        Garbage on the screen.
0150: * Text Garbled::          Garbage in the text.
0151: * Memory Full::           How to cope when you run out of memory.
0152: * Crashing::              What Emacs does when it crashes.
0153: * After a Crash::         Recovering editing in an Emacs session that crashed.
0154: * Emergency Escape::      What to do if Emacs stops responding.
0155: @end menu
0156: 
0157: @node DEL Does Not Delete
0158: @subsection If @key{DEL} Fails to Delete
0159: @cindex @key{DEL} vs @key{BACKSPACE}
0160: @cindex @key{BACKSPACE} vs @key{DEL}
0161: @cindex @key{DEL} does not delete
0162: 
0163:   Every keyboard has a large key, usually labeled @key{BACKSPACE},
0164: which is ordinarily used to erase the last character that you typed.
0165: In Emacs, this key is supposed to be equivalent to @key{DEL}.
0166: 
0167:   When Emacs starts up on a graphical display, it determines
0168: automatically which key should be @key{DEL}.  In some unusual cases,
0169: Emacs gets the wrong information from the system, and @key{BACKSPACE}
0170: ends up deleting forwards instead of backwards.
0171: 
0172:   Some keyboards also have a @key{Delete} key, which is ordinarily
0173: used to delete forwards.  If this key deletes backward in Emacs, that
0174: too suggests Emacs got the wrong information---but in the opposite
0175: sense.
0176: 
0177:   On a text terminal, if you find that @key{BACKSPACE} prompts for a
0178: Help command, like @kbd{Control-h}, instead of deleting a character,
0179: it means that key is actually sending the @samp{BS} character.  Emacs
0180: ought to be treating @key{BS} as @key{DEL}, but it isn't.
0181: 
0182: @findex normal-erase-is-backspace-mode
0183:   In all of those cases, the immediate remedy is the same: use the
0184: command @kbd{M-x normal-erase-is-backspace-mode}.  This toggles
0185: between the two modes that Emacs supports for handling @key{DEL}, so
0186: if Emacs starts in the wrong mode, this should switch to the right
0187: mode.  On a text terminal, if you want to ask for help when @key{BS}
0188: is treated as @key{DEL}, use @key{F1} instead of @kbd{C-h}; @kbd{C-?}
0189: may also work, if it sends character code 127.
0190: 
0191:   To fix the problem in every Emacs session, put one of the following
0192: lines into your initialization file (@pxref{Init File}).  For the
0193: first case above, where @key{BACKSPACE} deletes forwards instead of
0194: backwards, use this line to make @key{BACKSPACE} act as @key{DEL}:
0195: 
0196: @lisp
0197: (normal-erase-is-backspace-mode 0)
0198: @end lisp
0199: 
0200: @noindent
0201: For the other two cases, use this line:
0202: 
0203: @lisp
0204: (normal-erase-is-backspace-mode 1)
0205: @end lisp
0206: 
0207: @vindex normal-erase-is-backspace
0208:   Another way to fix the problem for every Emacs session is to
0209: customize the variable @code{normal-erase-is-backspace}: the value
0210: @code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is
0211: @key{DEL}, and @code{nil} specifies the other mode.  @xref{Easy
0212: Customization}.
0213: 
0214: @node Stuck Recursive
0215: @subsection Recursive Editing Levels
0216: @cindex stuck in recursive editing
0217: @cindex recursive editing, cannot exit
0218: 
0219:   Recursive editing levels are important and useful features of Emacs, but
0220: they can seem like malfunctions if you do not understand them.
0221: 
0222:   If the mode line has square brackets @samp{[@dots{}]} around the
0223: parentheses that contain the names of the major and minor modes, you
0224: have entered a recursive editing level.  If you did not do this on
0225: purpose, or if you don't understand what that means, you should just
0226: get out of the recursive editing level.  To do so, type @kbd{M-x
0227: top-level}.  @xref{Recursive Edit}.
0228: 
0229: @node Screen Garbled
0230: @subsection Garbage on the Screen
0231: @cindex garbled display
0232: @cindex display, incorrect
0233: @cindex screen display, wrong
0234: 
0235:   If the text on a text terminal looks wrong, the first thing to do is
0236: see whether it is wrong in the buffer.  Type @kbd{C-l}
0237: (@code{recenter-top-bottom}) to redisplay the entire screen.  If the
0238: screen appears correct after this, the problem was entirely in the
0239: previous screen update.  (Otherwise, see the following section.)
0240: 
0241:   Display updating problems often result from an incorrect terminfo
0242: entry for the terminal you are using.  The file @file{etc/TERMS} in
0243: the Emacs distribution gives the fixes for known problems of this
0244: sort.  @file{INSTALL} contains general advice for these problems in
0245: one of its sections.  If you seem to be using the right terminfo
0246: entry, it is possible that there is a bug in the terminfo entry, or a
0247: bug in Emacs that appears for certain terminal types.
0248: 
0249: @node Text Garbled
0250: @subsection Garbage in the Text
0251: @cindex garbled text
0252: @cindex buffer text garbled
0253: 
0254:   If @kbd{C-l} shows that the text is wrong, first type @kbd{C-h l}
0255: (@code{view-lossage}) to see what commands you typed to produce the
0256: observed results.  Then try undoing the changes step by step using
0257: @kbd{C-x u} (@code{undo}), until it gets back to a state you consider
0258: correct.
0259: 
0260:   If a large portion of text appears to be missing at the beginning or
0261: end of the buffer, check for the word @samp{Narrow} in the mode line.
0262: If it appears, the text you don't see is probably still present, but
0263: temporarily off-limits.  To make it accessible again, type @kbd{C-x n
0264: w} (@code{widen}).  @xref{Narrowing}.
0265: 
0266: @node Memory Full
0267: @subsection Running out of Memory
0268: @cindex memory full
0269: @cindex out of memory
0270: 
0271:   If you get the error message @samp{Virtual memory exceeded}, save
0272: your modified buffers with @kbd{C-x s} (@code{save-some-buffers}).
0273: This method of saving them has the smallest need for additional
0274: memory.  Emacs keeps a reserve of memory which it makes available when
0275: this error happens; that should be enough to enable @kbd{C-x s} to
0276: complete its work.  When the reserve has been used, @samp{!MEM FULL!}
0277: appears at the beginning of the mode line, indicating there is no more
0278: reserve.
0279: 
0280:   Once you have saved your modified buffers, you can exit this Emacs
0281: session and start another, or you can use @kbd{M-x kill-some-buffers}
0282: to free space in the current Emacs job.  If this frees up sufficient
0283: space, Emacs will refill its memory reserve, and @samp{!MEM FULL!}
0284: will disappear from the mode line.  That means you can safely go on
0285: editing in the same Emacs session.
0286: 
0287:   Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run
0288: out of memory, because the Buffer Menu needs a fair amount of memory
0289: itself, and the reserve supply may not be enough.
0290: 
0291: @node Crashing
0292: @subsection When Emacs Crashes
0293: 
0294: @cindex crash report
0295: @cindex backtrace
0296: @cindex @file{emacs_backtrace.txt} file, MS-Windows
0297:   Emacs is not supposed to crash, but if it does, it produces a
0298: @dfn{crash report} prior to exiting.  The crash report is printed to
0299: the standard error stream.  If Emacs was started from a graphical
0300: desktop on a GNU or Unix system, the standard error stream is commonly
0301: redirected to a file such as @file{~/.xsession-errors}, so you can
0302: look for the crash report there.  On MS-Windows, the crash report is
0303: written to a file named @file{emacs_backtrace.txt} in the current
0304: directory of the Emacs process, in addition to the standard error
0305: stream.
0306: 
0307:   The format of the crash report depends on the platform.  On some
0308: platforms, such as those using the GNU C Library, the crash report
0309: includes a @dfn{backtrace} describing the execution state prior to
0310: crashing, which can be used to help debug the crash.  Here is an
0311: example for a GNU system:
0312: 
0313: @example
0314: Fatal error 11: Segmentation fault
0315: Backtrace:
0316: emacs[0x5094e4]
0317: emacs[0x4ed3e6]
0318: emacs[0x4ed504]
0319: /lib64/libpthread.so.0[0x375220efe0]
0320: /lib64/libpthread.so.0(read+0xe)[0x375220e08e]
0321: emacs[0x509af6]
0322: emacs[0x5acc26]
0323: @dots{}
0324: @end example
0325: 
0326: @noindent
0327: The number @samp{11} is the system signal number corresponding to the
0328: crash---in this case a segmentation fault.  The hexadecimal numbers
0329: are program addresses, which can be associated with source code lines
0330: using a debugging tool.  For example, the GDB command
0331: @samp{list *0x509af6} prints the source-code lines corresponding to
0332: the @samp{emacs[0x509af6]} entry.  If your system has the
0333: @command{addr2line} utility, the following shell command outputs a
0334: backtrace with source-code line numbers:
0335: 
0336: @example
0337: sed -n 's/.*\[\(.*\)]$/\1/p' @var{backtrace} |
0338:   addr2line -C -f -i -p -e @var{bindir}/@var{emacs-binary}
0339: @end example
0340: 
0341: @noindent
0342: Here, @var{backtrace} is the name of a text file containing a copy of
0343: the backtrace, @var{bindir} is the name of the directory that
0344: contains the Emacs executable, and @var{emacs-binary} is the name of
0345: the Emacs executable file, normally @file{emacs} on GNU and Unix
0346: systems and @file{emacs.exe} on MS-Windows and MS-DOS@.  Omit the
0347: @option{-p} option if your version of @command{addr2line} is too old
0348: to have it.
0349: 
0350: @cindex core dump
0351:   Optionally, Emacs can generate a @dfn{core dump} when it crashes, on
0352: systems that support core files.  A core dump is a file containing
0353: voluminous data about the state of the program prior to the crash,
0354: usually examined by loading it into a debugger such as GDB@.  On many
0355: platforms, core dumps are disabled by default, and you must explicitly
0356: enable them by running the shell command @samp{ulimit -c unlimited}
0357: (e.g., in your shell startup script).
0358: 
0359: @node After a Crash
0360: @subsection Recovery After a Crash
0361: @cindex recovering crashed session
0362: 
0363:   If Emacs or the computer crashes, you can recover the files you were
0364: editing at the time of the crash from their auto-save files.  To do
0365: this, start Emacs again and type the command @kbd{M-x recover-session}.
0366: 
0367:   This command initially displays a buffer which lists interrupted
0368: session files, each with its date.  You must choose which session to
0369: recover from.  Typically the one you want is the most recent one.  Move
0370: point to the one you choose, and type @kbd{C-c C-c}.
0371: 
0372:   Then @code{recover-session} considers each of the files that you
0373: were editing during that session; for each such file, it asks whether
0374: to recover that file.  If you answer @kbd{y} for a file, it shows the
0375: dates of that file and its auto-save file, then asks once again
0376: whether to recover that file.  For the second question, you must
0377: confirm with @kbd{yes}.  If you do, Emacs visits the file but gets the
0378: text from the auto-save file.
0379: 
0380:   When @code{recover-session} is done, the files you've chosen to
0381: recover are present in Emacs buffers.  You should then save them.  Only
0382: this---saving them---updates the files themselves.
0383: 
0384:   As a last resort, if you had buffers with content which were not
0385: associated with any files, or if the autosave was not recent enough to
0386: have recorded important changes, you can use the
0387: @file{etc/emacs-buffer.gdb} script with GDB (the GNU Debugger) to
0388: retrieve them from a core dump--provided that a core dump was saved,
0389: and that the Emacs executable was not stripped of its debugging
0390: symbols.
0391: 
0392:   As soon as you get the core dump, rename it to another name such as
0393: @file{core.emacs}, so that another crash won't overwrite it.
0394: 
0395:   To use this script, run @code{gdb} with the file name of your Emacs
0396: executable and the file name of the core dump, e.g., @samp{gdb
0397: /usr/bin/emacs core.emacs}.  At the @code{(gdb)} prompt, load the
0398: recovery script: @samp{source /usr/src/emacs/etc/emacs-buffer.gdb}.
0399: Then type the command @code{ybuffer-list} to see which buffers are
0400: available.  For each buffer, it lists a buffer number.  To save a
0401: buffer, use @code{ysave-buffer}; you specify the buffer number, and
0402: the file name to write that buffer into.  You should use a file name
0403: which does not already exist; if the file does exist, the script does
0404: not make a backup of its old contents.
0405: 
0406: @node Emergency Escape
0407: @subsection Emergency Escape
0408: @cindex emergency escape
0409: 
0410:   On text terminals, the @dfn{emergency escape} feature suspends Emacs
0411: immediately if you type @kbd{C-g} a second time before Emacs can
0412: actually respond to the first one by quitting.  This is so you can
0413: always get out of GNU Emacs no matter how badly it might be hung.
0414: When things are working properly, Emacs recognizes and handles the
0415: first @kbd{C-g} so fast that the second one won't trigger emergency
0416: escape.  However, if some problem prevents Emacs from handling the
0417: first @kbd{C-g} properly, then the second one will get you back to the
0418: shell.
0419: 
0420:   When you resume Emacs after a suspension caused by emergency escape,
0421: it reports the resumption and asks a question or two before going back
0422: to what it had been doing:
0423: 
0424: @example
0425: Emacs is resuming after an emergency escape.
0426: Auto-save? (y or n)
0427: Abort (and dump core)? (y or n)
0428: @end example
0429: 
0430: @noindent
0431: Answer each question with @kbd{y} or @kbd{n} followed by @key{RET}.
0432: 
0433:   Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of
0434: all modified buffers in which auto-saving is enabled.  Saying @kbd{n}
0435: skips this.  This question is omitted if Emacs is in a state where
0436: auto-saving cannot be done safely.
0437: 
0438:   Saying @kbd{y} to @samp{Abort (and dump core)?} causes Emacs to
0439: crash, dumping core.  This is to enable a wizard to figure out why
0440: Emacs was failing to quit in the first place.  Execution does not
0441: continue after a core dump.
0442: 
0443:   If you answer this question @kbd{n}, Emacs execution resumes.  With
0444: luck, Emacs will ultimately do the requested quit.  If not, each
0445: subsequent @kbd{C-g} invokes emergency escape again.
0446: 
0447:   If Emacs is not really hung, just slow, you may invoke the double
0448: @kbd{C-g} feature without really meaning to.  Then just resume and
0449: answer @kbd{n} to both questions, and you will get back to the former
0450: state.  The quit you requested will happen by and by.
0451: 
0452:   Emergency escape is active only for text terminals.  On graphical
0453: displays, you can use the mouse to kill Emacs or switch to another
0454: program.
0455: 
0456:   On MS-DOS, you must type @kbd{C-@key{Break}} (twice) to cause
0457: emergency escape---but there are cases where it won't work, when a
0458: system call hangs or when Emacs is stuck in a tight loop in C code.
0459: 
0460: @node Bugs
0461: @section Reporting Bugs
0462: 
0463: @cindex bugs
0464:   If you think you have found a bug in Emacs, please report it.  We
0465: cannot promise to fix it, or always to agree that it is a bug, but we
0466: certainly want to hear about it.  The same applies for new features
0467: you would like to see added.  The following sections will help you to
0468: construct an effective bug report.
0469: 
0470: @menu
0471: * Known Problems::               How to read about known problems and bugs.
0472: * Criteria:  Bug Criteria.       Have you really found a bug?
0473: * Understanding Bug Reporting::  How to report a bug effectively.
0474: * Checklist::                    Steps to follow for a good bug report.
0475: * Sending Patches::              How to send a patch for GNU Emacs.
0476: @end menu
0477: 
0478: @node Known Problems
0479: @subsection Reading Existing Bug Reports and Known Problems
0480: 
0481:   Before reporting a bug, if at all possible please check to see if it
0482: is already known about.  Indeed, it may already have been fixed in a
0483: later release of Emacs, or in the development version.  Here is a list
0484: of the main places you can read about known issues:
0485: 
0486: @itemize
0487: @item
0488: The @file{etc/PROBLEMS} file; type @kbd{C-h C-p} to read it.  This
0489: file contains a list of particularly well-known issues that have been
0490: encountered in compiling, installing and running Emacs.  Often, there
0491: are suggestions for workarounds and solutions.
0492: 
0493: @cindex bug tracker
0494: @item
0495: The GNU Bug Tracker at @url{https://debbugs.gnu.org}.  Emacs bugs are
0496: filed in the tracker under the @samp{emacs} package.  The tracker
0497: records information about the status of each bug, the initial bug
0498: report, and the follow-up messages by the bug reporter and Emacs
0499: developers.  You can search for bugs by subject, severity, and other
0500: criteria.
0501: 
0502: @cindex debbugs package
0503: Instead of browsing the bug tracker as a webpage, you can browse it
0504: from Emacs using the @code{debbugs} package, which can be downloaded
0505: via the Package Menu (@pxref{Packages}).  This package provides the
0506: command @kbd{M-x debbugs-gnu} to list bugs, and @kbd{M-x
0507: debbugs-gnu-search} to search for a specific bug.  User tags, applied
0508: by the Emacs maintainers, are shown by @kbd{M-x debbugs-gnu-usertags}.
0509: 
0510: @item
0511: The @samp{bug-gnu-emacs} mailing list (also available as the newsgroup
0512: @samp{gnu.emacs.bug}).  You can read the list archives at
0513: @url{https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs}.  This list
0514: works as a mirror of the Emacs bug reports and follow-up messages
0515: which are sent to the bug tracker.  It also contains old bug reports
0516: from before the bug tracker was introduced (in early 2008).
0517: 
0518: If you like, you can subscribe to the list.  Be aware that its purpose
0519: is to provide the Emacs maintainers with information about bugs and
0520: feature requests, so reports may contain fairly large amounts of data;
0521: spectators should not complain about this.
0522: 
0523: @item
0524: The @samp{emacs-pretest-bug} mailing list.  This list is no longer
0525: used, and is mainly of historical interest.  At one time, it was used
0526: for bug reports in development (i.e., not yet released) versions of
0527: Emacs.  You can read the archives for 2003 to mid 2007 at
0528: @url{https://lists.gnu.org/r/emacs-pretest-bug/}.  Nowadays,
0529: it is an alias for @samp{bug-gnu-emacs}.
0530: 
0531: @item
0532: The @samp{emacs-devel} mailing list.  Sometimes people report bugs to
0533: this mailing list.  This is not the main purpose of the list, however,
0534: and it is much better to send bug reports to the bug list.  You should
0535: not feel obliged to read this list before reporting a bug.
0536: 
0537: @end itemize
0538: 
0539: 
0540: @node Bug Criteria
0541: @subsection When Is There a Bug
0542: @cindex bug criteria
0543: @cindex what constitutes an Emacs bug
0544: 
0545:   If Emacs accesses an invalid memory location (a.k.a.@:
0546: ``segmentation fault'') or exits with an operating system error
0547: message that indicates a problem in the program (as opposed to
0548: something like ``disk full''), then it is certainly a bug.
0549: 
0550:   If the Emacs display does not correspond properly to the contents of
0551: the buffer, then it is a bug.  But you should check that features like
0552: buffer narrowing (@pxref{Narrowing}), which can hide parts of the
0553: buffer or change how it is displayed, are not responsible.
0554: 
0555:   Taking forever to complete a command can be a bug, but you must make
0556: sure that it is really Emacs's fault.  Some commands simply take a
0557: long time.  Type @kbd{C-g} (@kbd{C-@key{Break}} on MS-DOS) and then
0558: @kbd{C-h l} to see whether the input Emacs received was what you
0559: intended to type; if the input was such that you @emph{know} it should
0560: have been processed quickly, report a bug.  If you don't know whether
0561: the command should take a long time, find out by looking in the manual
0562: or by asking for assistance.
0563: 
0564:   If a command you are familiar with causes an Emacs error message in a
0565: case where its usual definition ought to be reasonable, it is probably a
0566: bug.
0567: 
0568:   If a command does the wrong thing, that is a bug.  But be sure you
0569: know for certain what it ought to have done.  If you aren't familiar
0570: with the command, it might actually be working right.  If in doubt,
0571: read the command's documentation (@pxref{Name Help}).
0572: 
0573:   A command's intended definition may not be the best possible
0574: definition for editing with.  This is a very important sort of
0575: problem, but it is also a matter of judgment.  Also, it is easy to
0576: come to such a conclusion out of ignorance of some of the existing
0577: features.  It is probably best not to complain about such a problem
0578: until you have checked the documentation in the usual ways, feel
0579: confident that you understand it, and know for certain that what you
0580: want is not available.  Ask other Emacs users, too.  If you are not
0581: sure what the command is supposed to do after a careful reading of the
0582: manual, check the index and glossary for any terms that may be
0583: unclear.
0584: 
0585:   If after careful rereading of the manual you still do not understand
0586: what the command should do, that indicates a bug in the manual, which
0587: you should report.  The manual's job is to make everything clear to
0588: people who are not Emacs experts---including you.  It is just as
0589: important to report documentation bugs as program bugs.
0590: 
0591:   If the built-in documentation for a function or variable disagrees
0592: with the manual, one of them must be wrong; that is a bug.
0593: 
0594:   For problems with packages that are not part of Emacs, it is better
0595: to begin by reporting them to the package developers.
0596: 
0597: @node Understanding Bug Reporting
0598: @subsection Understanding Bug Reporting
0599: @cindex bug reporting
0600: @cindex report an Emacs bug, how to
0601: 
0602:   When you decide that there is a bug, it is important to report it
0603: and to report it in a way which is useful.  What is most useful is an
0604: exact description of what commands you type, starting with the shell
0605: command to run Emacs, until the problem happens.
0606: 
0607:   The most important principle in reporting a bug is to report
0608: @emph{facts}.  Hypotheses and verbal descriptions are no substitute
0609: for the detailed raw data.  Reporting the facts is straightforward,
0610: but many people strain to posit explanations and report them instead
0611: of the facts.  If the explanations are based on guesses about how
0612: Emacs is implemented, they will be useless; meanwhile, lacking the
0613: facts, we will have no real information about the bug.  If you want to
0614: actually @emph{debug} the problem, and report explanations that are
0615: more than guesses, that is useful---but please include the raw facts
0616: as well.
0617: 
0618:   For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh
0619: @key{RET}}, visiting a file which (you know) happens to be rather
0620: large, and Emacs displays @samp{I feel pretty today}.  The bug report
0621: would need to provide all that information.  You should not assume
0622: that the problem is due to the size of the file and say, ``I visited a
0623: large file, and Emacs displayed @samp{I feel pretty today}.''  This is
0624: what we mean by ``guessing explanations''.  The problem might be due
0625: to the fact that there is a @samp{z} in the file name.  If this is so,
0626: then when we got your report, we would try out the problem with some
0627: large file, probably with no @samp{z} in its name, and not see any
0628: problem.  There is no way we could guess that we should try visiting a
0629: file with a @samp{z} in its name.
0630: 
0631:   You should not even say ``visit a file'' instead of @kbd{C-x C-f}.
0632: Similarly, rather than saying ``if I have three characters on the
0633: line'', say ``after I type @kbd{@key{RET} A B C @key{RET} C-p}'', if
0634: that is the way you entered the text.
0635: 
0636:   If possible, try quickly to reproduce the bug by invoking Emacs with
0637: @command{emacs -Q} (so that Emacs starts with no initial
0638: customizations; @pxref{Initial Options}), and repeating the steps that
0639: you took to trigger the bug.  If you can reproduce the bug this way,
0640: that rules out bugs in your personal customizations.  Then your bug
0641: report should begin by stating that you started Emacs with
0642: @command{emacs -Q}, followed by the exact sequence of steps for
0643: reproducing the bug.  If possible, inform us of the exact contents of
0644: any file that is needed to reproduce the bug.
0645: 
0646:   Some bugs are not reproducible from @command{emacs -Q}; some are not
0647: easily reproducible at all.  In that case, you should report what you
0648: have---but, as before, please stick to the raw facts about what you
0649: did to trigger the bug the first time.
0650: 
0651:   If you have multiple issues that you want to report, please make a
0652: separate bug report for each.
0653: 
0654: @node Checklist
0655: @subsection Checklist for Bug Reports
0656: @cindex checklist before reporting a bug
0657: @cindex bug reporting, checklist
0658: 
0659:   Before reporting a bug, first try to see if the problem has already
0660: been reported (@pxref{Known Problems}).
0661: 
0662: If you are able to, try the latest release of Emacs to see if the
0663: problem has already been fixed.  Even better is to try the latest
0664: development version.  We recognize that this is not easy for some
0665: people, so do not feel that you absolutely must do this before making
0666: a report.
0667: 
0668: @findex report-emacs-bug
0669:   The best way to write a bug report for Emacs is to use the command
0670: @kbd{M-x report-emacs-bug}.  This sets up a mail buffer
0671: (@pxref{Sending Mail}) and automatically inserts @emph{some} of the
0672: essential information.  However, it cannot supply all the necessary
0673: information; you should still read and follow the guidelines below, so
0674: you can enter the other crucial information by hand before you send
0675: the message.  You may feel that some of the information inserted by
0676: @kbd{M-x report-emacs-bug} is not relevant, but unless you are
0677: absolutely sure it is best to leave it, so that the developers can
0678: decide for themselves.
0679: 
0680: When you have finished writing your report, type @kbd{C-c C-c} and it
0681: will be sent to the Emacs maintainers at
0682: @ifnothtml
0683: @email{bug-gnu-emacs@@gnu.org}.
0684: @end ifnothtml
0685: @ifhtml
0686: @url{https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs, bug-gnu-emacs}.
0687: @end ifhtml
0688: (If you want to suggest an improvement or new feature, use the same
0689: address.)  If you cannot send mail from inside Emacs, you can copy the
0690: text of your report to your normal mail client (if your system
0691: supports it, you can type @kbd{C-c M-i} to have Emacs do this for you)
0692: and send it to that address.  Or you can simply send an email to that
0693: address describing the problem.
0694: 
0695: Your report will be sent to the @samp{bug-gnu-emacs} mailing list, and
0696: stored in the GNU Bug Tracker at @url{https://debbugs.gnu.org}.  Please
0697: include a valid reply email address, in case we need to ask you for
0698: more information about your report.  Submissions are moderated, so
0699: there may be a delay before your report appears.
0700: 
0701: You do not need to know how the GNU Bug Tracker works in order to
0702: report a bug, but if you want to, you can read the tracker's online
0703: documentation to see the various features you can use.
0704: 
0705: All mail sent to the @samp{bug-gnu-emacs} mailing list is also
0706: gatewayed to the @samp{gnu.emacs.bug} newsgroup.  The reverse is also
0707: true, but we ask you not to post bug reports (or replies) via the
0708: newsgroup.  It can make it much harder to contact you if we need to ask
0709: for more information, and it does not integrate well with the bug
0710: tracker.
0711: 
0712: If your data is more than 500,000 bytes, please don't include it
0713: directly in the bug report; instead, offer to send it on request, or
0714: make it available online and say where.
0715: 
0716: The GNU Bug Tracker will assign a bug number to your report; please
0717: use it in the following discussions.
0718: 
0719:   To enable maintainers to investigate a bug, your report
0720: should include all these things:
0721: 
0722: @itemize @bullet
0723: @item
0724: The version number of Emacs.  Without this, we won't know whether there is any
0725: point in looking for the bug in the current version of GNU Emacs.
0726: 
0727: @findex emacs-version
0728: @kbd{M-x report-emacs-bug} includes this information automatically,
0729: but if you are not using that command for your report you can get the
0730: version number by typing @kbd{M-x emacs-version @key{RET}}.  If that
0731: command does not work, you probably have something other than GNU
0732: Emacs, so you will have to report the bug somewhere else.
0733: 
0734: @item
0735: The type of machine you are using, and the operating system name and
0736: version number (again, automatically included by @kbd{M-x
0737: report-emacs-bug}).  @kbd{M-x emacs-version @key{RET}} provides this
0738: information too.  Copy its output from the @file{*Messages*} buffer,
0739: so that you get it all and get it accurately.
0740: 
0741: @item
0742: The operands given to the @code{configure} command when Emacs was
0743: installed (automatically included by @kbd{M-x report-emacs-bug}).
0744: 
0745: @item
0746: A complete list of any modifications you have made to the Emacs source.
0747: (We may not have time to investigate the bug unless it happens in an
0748: unmodified Emacs.  But if you've made modifications and you don't tell
0749: us, you are sending us on a wild goose chase.)
0750: 
0751: Be precise about these changes.  A description in English is not
0752: enough---send a unified context diff for them.
0753: 
0754: Adding files of your own, or porting to another machine, is a
0755: modification of the source.
0756: 
0757: @item
0758: Details of any other deviations from the standard procedure for installing
0759: GNU Emacs.
0760: 
0761: @item
0762: The complete text of any files needed to reproduce the bug.
0763: 
0764:   If you can tell us a way to cause the problem without visiting any files,
0765: please do so.  This makes it much easier to debug.  If you do need files,
0766: make sure you arrange for us to see their exact contents.  For example, it
0767: can matter whether there are spaces at the ends of lines, or a
0768: newline after the last line in the buffer (nothing ought to care whether
0769: the last line is terminated, but try telling the bugs that).
0770: 
0771: @item
0772: The precise commands we need to type to reproduce the bug.  If at all
0773: possible, give a full recipe for an Emacs started with the @samp{-Q}
0774: option (@pxref{Initial Options}).  This bypasses your personal
0775: customizations.
0776: 
0777: @findex open-dribble-file
0778: @cindex dribble file
0779: @cindex logging keystrokes
0780: One way to record the input to Emacs precisely is to write a dribble
0781: file.  To start the file, use the @kbd{M-x open-dribble-file} command.
0782: From then on, Emacs copies all your input to the specified dribble
0783: file until the Emacs process is killed.  Be aware that sensitive
0784: information (such as passwords) may end up recorded in the dribble
0785: file.
0786: 
0787: @item
0788: @findex open-termscript
0789: @cindex termscript file
0790: @vindex TERM@r{, environment variable, and display bugs}
0791: For possible display bugs on text-mode terminals, the terminal type
0792: (the value of environment variable @env{TERM}), the complete termcap
0793: entry for the terminal from @file{/etc/termcap} (since that file is
0794: not identical on all machines), and the output that Emacs actually
0795: sent to the terminal.
0796: 
0797: The way to collect the terminal output is to execute the Lisp expression
0798: 
0799: @example
0800: (open-termscript "~/termscript")
0801: @end example
0802: 
0803: @noindent
0804: using @kbd{M-:} or from the @file{*scratch*} buffer just after
0805: starting Emacs.  From then on, Emacs copies all terminal output to the
0806: specified termscript file as well, until the Emacs process is killed.
0807: If the problem happens when Emacs starts up, put this expression into
0808: your Emacs initialization file so that the termscript file will be
0809: open when Emacs displays the screen for the first time.
0810: 
0811: Be warned: it is often difficult, and sometimes impossible, to fix a
0812: terminal-dependent bug without access to a terminal of the type that
0813: stimulates the bug.
0814: 
0815: @item
0816: If non-@acronym{ASCII} text or internationalization is relevant, the locale that
0817: was current when you started Emacs.  On GNU/Linux and Unix systems, or
0818: if you use a POSIX-style shell such as Bash, you can use this shell
0819: command to view the relevant values:
0820: 
0821: @smallexample
0822: echo LC_ALL=$LC_ALL LC_COLLATE=$LC_COLLATE LC_CTYPE=$LC_CTYPE \
0823:   LC_MESSAGES=$LC_MESSAGES LC_TIME=$LC_TIME LANG=$LANG
0824: @end smallexample
0825: 
0826: Alternatively, use the @command{locale} command, if your system has it,
0827: to display your locale settings.
0828: 
0829: You can use the @kbd{M-!} command to execute these commands from
0830: Emacs, and then copy the output from the @file{*Messages*} buffer into
0831: the bug report.  Alternatively, @kbd{M-x getenv @key{RET} LC_ALL
0832: @key{RET}} will display the value of @code{LC_ALL} in the echo area, and
0833: you can copy its output from the @file{*Messages*} buffer.
0834: 
0835: @item
0836: A description of what behavior you observe that you believe is
0837: incorrect.  For example, ``The Emacs process gets a fatal signal'', or,
0838: ``The resulting text is as follows, which I think is wrong.''
0839: 
0840: Of course, if the bug is that Emacs gets a fatal signal, then one can't
0841: miss it.  But if the bug is incorrect text, the maintainer might fail to
0842: notice what is wrong.  Why leave it to chance?
0843: 
0844: Even if the problem you experience is a fatal signal, you should still
0845: say so explicitly.  Suppose something strange is going on, such as, your
0846: copy of the source is out of sync, or you have encountered a bug in the
0847: C library on your system.  (This has happened!)  Your copy might crash
0848: and the copy here might not.  If you @emph{said} to expect a crash, then
0849: when Emacs here fails to crash, we would know that the bug was not
0850: happening.  If you don't say to expect a crash, then we would not know
0851: whether the bug was happening---we would not be able to draw any
0852: conclusion from our observations.
0853: 
0854: @item
0855: If the bug is that the Emacs Manual or the Emacs Lisp Reference Manual
0856: fails to describe the actual behavior of Emacs, or that the text is
0857: confusing, copy in the text from the manual which you think is
0858: at fault.  If the section is small, just the section name is enough.
0859: 
0860: @item
0861: If the manifestation of the bug is an Emacs error message, it is
0862: important to report the precise text of the error message, and a
0863: backtrace showing how the Lisp program in Emacs arrived at the error.
0864: 
0865: To get the error message text accurately, copy it from the
0866: @file{*Messages*} buffer into the bug report.  Copy all of it, not just
0867: part.
0868: 
0869: @findex toggle-debug-on-error
0870: @pindex Edebug
0871: To make a backtrace for the error, use @kbd{M-x toggle-debug-on-error}
0872: before the error happens (that is to say, you must give that command
0873: and then make the bug happen).  This causes the error to start the Lisp
0874: debugger, which shows you a backtrace.  Copy the text of the
0875: debugger's backtrace into the bug report.  @xref{Edebug,, Edebug,
0876: elisp, the Emacs Lisp Reference Manual}, for information on debugging
0877: Emacs Lisp programs with the Edebug package.
0878: 
0879: This use of the debugger is possible only if you know how to make the
0880: bug happen again.  If you can't make it happen again, at least copy
0881: the whole error message.
0882: 
0883: @vindex debug-on-quit
0884: If Emacs appears to be stuck in an infinite loop or in a very long
0885: operation, typing @kbd{C-g} with the variable @code{debug-on-quit}
0886: non-@code{nil} will start the Lisp debugger and show a backtrace.
0887: This backtrace is useful for debugging such long loops, so if you can
0888: produce it, copy it into the bug report.
0889: 
0890: @vindex debug-on-event
0891: If you cannot get Emacs to respond to @kbd{C-g} (e.g., because
0892: @code{inhibit-quit} is set), then you can try sending the signal
0893: specified by @code{debug-on-event} (default SIGUSR2) from outside
0894: Emacs to cause it to enter the debugger.
0895: 
0896: @item
0897: Check whether any programs you have loaded into the Lisp world,
0898: including your initialization file, set any variables that may affect
0899: the functioning of Emacs.  Also, see whether the problem happens in a
0900: freshly started Emacs without loading your initialization file (start
0901: Emacs with the @code{-Q} switch to prevent loading the init files).
0902: If the problem does @emph{not} occur then, you must report the precise
0903: contents of any programs that you must load into the Lisp world in
0904: order to cause the problem to occur.
0905: 
0906: @item
0907: If the problem does depend on an init file or other Lisp programs that
0908: are not part of the standard Emacs system, then you should make sure it
0909: is not a bug in those programs by complaining to their maintainers
0910: first.  After they verify that they are using Emacs in a way that is
0911: supposed to work, they should report the bug.
0912: 
0913: @item
0914: If you wish to mention something in the GNU Emacs source, show the line
0915: of code with a few lines of context.  Don't just give a line number.
0916: 
0917: The line numbers in the development sources don't match those in your
0918: sources.  It would take extra work for the maintainers to determine what
0919: code is in your version at a given line number, and we could not be
0920: certain.
0921: 
0922: @item
0923: Additional information from a C debugger such as GDB might enable
0924: someone to find a problem on a machine which he does not have available.
0925: If you don't know how to use GDB, please read the GDB manual---it is not
0926: very long, and using GDB is easy.  You can find the GDB distribution,
0927: including the GDB manual in online form, in most of the same places you
0928: can find the Emacs distribution.  To run Emacs under GDB, you should
0929: switch to the @file{src} subdirectory in which Emacs was compiled, then
0930: do @samp{gdb emacs}.  It is important for the directory @file{src} to be
0931: current so that GDB will read the @file{.gdbinit} file in this
0932: directory.
0933: 
0934: However, you need to think when you collect the additional information
0935: if you want it to show what causes the bug.
0936: 
0937: @cindex backtrace for bug reports
0938: For example, many people send just a C-level backtrace, but that is
0939: not very useful by itself.  A simple backtrace with arguments often
0940: conveys little about what is happening inside GNU Emacs, because most
0941: of the arguments listed in the backtrace are pointers to Lisp objects.
0942: The numeric values of these pointers have no significance whatever;
0943: all that matters is the contents of the objects they point to (and
0944: most of the contents are themselves pointers).
0945: 
0946: @findex debug_print
0947: To provide useful information, you need to show the values of Lisp
0948: objects in Lisp notation.  Do this for each variable which is a Lisp
0949: object, in several stack frames near the bottom of the stack.  Look at
0950: the source to see which variables are Lisp objects, because the debugger
0951: thinks of them as integers.
0952: 
0953: To show a variable's value in Lisp syntax, first print its value, then
0954: use the user-defined GDB command @code{pr} to print the Lisp object in
0955: Lisp syntax.  (If you must use another debugger, call the function
0956: @code{debug_print} with the object as an argument.)  The @code{pr}
0957: command is defined by the file @file{.gdbinit}, and it works only if you
0958: are debugging a running process (not with a core dump).
0959: 
0960: To make Lisp errors stop Emacs and return to GDB, put a breakpoint at
0961: @code{Fsignal}.
0962: 
0963: For a short listing of Lisp functions running, type the GDB
0964: command @code{xbacktrace}.
0965: 
0966: The file @file{.gdbinit} defines several other commands that are useful
0967: for examining the data types and contents of Lisp objects.  Their names
0968: begin with @samp{x}.  These commands work at a lower level than
0969: @code{pr}, and are less convenient, but they may work even when
0970: @code{pr} does not, such as when debugging a core dump or when Emacs has
0971: had a fatal signal.
0972: 
0973: @cindex debugging Emacs, tricks and techniques
0974: More detailed advice and other useful techniques for debugging Emacs
0975: are available in the file @file{etc/DEBUG} in the Emacs distribution.
0976: That file also includes instructions for investigating problems
0977: whereby Emacs stops responding (many people assume that Emacs is
0978: ``hung'', whereas in fact it might be in an infinite loop).
0979: 
0980: To find the file @file{etc/DEBUG} in your Emacs installation, use the
0981: directory name stored in the variable @code{data-directory}.
0982: @end itemize
0983: 
0984: Here are some things that are not necessary in a bug report:
0985: 
0986: @itemize @bullet
0987: @item
0988: A description of the envelope of the bug---this is not necessary for a
0989: reproducible bug.
0990: 
0991: Often people who encounter a bug spend a lot of time investigating
0992: which changes to the input file will make the bug go away and which
0993: changes will not affect it.
0994: 
0995: This is often time-consuming and not very useful, because the way we
0996: will find the bug is by running a single example under the debugger
0997: with breakpoints, not by pure deduction from a series of examples.
0998: You might as well save time by not searching for additional examples.
0999: It is better to send the bug report right away, go back to editing,
1000: and find another bug to report.
1001: 
1002: Of course, if you can find a simpler example to report @emph{instead} of
1003: the original one, that is a convenience.  Errors in the output will be
1004: easier to spot, running under the debugger will take less time, etc.
1005: 
1006: However, simplification is not vital; if you can't do this or don't have
1007: time to try, please report the bug with your original test case.
1008: 
1009: @item
1010: A core dump file.
1011: 
1012: Debugging the core dump might be useful, but it can only be done on
1013: your machine, with your Emacs executable.  Therefore, sending the core
1014: dump file to the Emacs maintainers won't be useful.  Above all, don't
1015: include the core file in an email bug report!  Such a large message
1016: can be extremely inconvenient.
1017: 
1018: @item
1019: A system-call trace of Emacs execution.
1020: 
1021: System-call traces are very useful for certain special kinds of
1022: debugging, but in most cases they give little useful information.  It is
1023: therefore strange that many people seem to think that @emph{the} way to
1024: report information about a crash is to send a system-call trace.  Perhaps
1025: this is a habit formed from experience debugging programs that don't
1026: have source code or debugging symbols.
1027: 
1028: In most programs, a backtrace is normally far, far more informative than
1029: a system-call trace.  Even in Emacs, a simple backtrace is generally
1030: more informative, though to give full information you should supplement
1031: the backtrace by displaying variable values and printing them as Lisp
1032: objects with @code{pr} (see above).
1033: 
1034: @item
1035: A patch for the bug.
1036: 
1037: A patch for the bug is useful if it is a good one.  But don't omit the
1038: other information that a bug report needs, such as the test case, on the
1039: assumption that a patch is sufficient.  We might see problems with your
1040: patch and decide to fix the problem another way, or we might not
1041: understand it at all.  And if we can't understand what bug you are
1042: trying to fix, or why your patch should be an improvement, we mustn't
1043: install it.
1044: 
1045: @ifnottex
1046: @xref{Sending Patches}, for guidelines on how to make it easy for us to
1047: understand and install your patches.
1048: @end ifnottex
1049: 
1050: @item
1051: A guess about what the bug is or what it depends on.
1052: 
1053: Such guesses are usually wrong.  Even experts can't guess right about
1054: such things without first using the debugger to find the facts.
1055: @end itemize
1056: 
1057: @node Sending Patches
1058: @subsection Sending Patches for GNU Emacs
1059: 
1060: @cindex sending patches for GNU Emacs
1061: @cindex patches, sending
1062:   If you would like to write bug fixes or improvements for GNU Emacs,
1063: that is very helpful.  When you send your changes, please follow these
1064: guidelines to make it easy for the maintainers to use them.  If you
1065: don't follow these guidelines, your information might still be useful,
1066: but using it will take extra work.  Maintaining GNU Emacs is a lot of
1067: work in the best of circumstances, and we can't keep up unless you do
1068: your best to help.
1069: 
1070: Every patch must have several pieces of information before we
1071: can properly evaluate it.
1072: 
1073: When you have all these pieces, bundle them up in a mail message and
1074: send it to the developers.  Sending it to
1075: @email{bug-gnu-emacs@@gnu.org} (which is the bug/feature list) is
1076: recommended, because that list is coupled to a tracking system that
1077: makes it easier to locate patches.  If your patch is not complete and
1078: you think it needs more discussion, you might want to send it to
1079: @email{emacs-devel@@gnu.org} instead.  If you revise your patch,
1080: send it as a followup to the initial topic.
1081: 
1082: We prefer to get the patches as plain text, either inline (be careful
1083: your mail client does not change line breaks) or as MIME attachments.
1084: 
1085: @itemize @bullet
1086: @item
1087: Include an explanation with your changes of what problem they fix or what
1088: improvement they bring about.
1089: 
1090: @itemize
1091: @item
1092: For a fix for an existing bug, it is
1093: best to reply to the relevant discussion on the @samp{bug-gnu-emacs}
1094: list, or the bug entry in the GNU Bug Tracker at
1095: @url{https://debbugs.gnu.org}.  Explain why your change fixes the bug.
1096: 
1097: @item
1098: For a new feature, include a description of the feature and your
1099: implementation.
1100: 
1101: @item
1102: For a new bug, include a proper bug report for the problem you think
1103: you have fixed.  We need to convince ourselves that the change is
1104: right before installing it.  Even if it is correct, we might have
1105: trouble understanding it if we don't have a way to reproduce the
1106: problem.
1107: @end itemize
1108: 
1109: @item
1110: Include all the comments that are appropriate to help people reading the
1111: source in the future understand why this change was needed.
1112: 
1113: @item
1114: Don't mix together changes made for different reasons.
1115: Send them @emph{individually}.
1116: 
1117: If you make two changes for separate reasons, then we might not want to
1118: install them both.  We might want to install just one.  If you send them
1119: all jumbled together in a single set of diffs, we have to do extra work
1120: to disentangle them---to figure out which parts of the change serve
1121: which purpose.  If we don't have time for this, we might have to ignore
1122: your changes entirely.
1123: 
1124: If you send each change as soon as you have written it, with its own
1125: explanation, then two changes never get tangled up, and we can consider
1126: each one properly without any extra work to disentangle them.
1127: 
1128: @item
1129: Send each change as soon as that change is finished.  Sometimes people
1130: think they are helping us by accumulating many changes to send them all
1131: together.  As explained above, this is absolutely the worst thing you
1132: could do.
1133: 
1134: Since you should send each change separately, you might as well send it
1135: right away.  That gives us the option of installing it immediately if it
1136: is important.
1137: 
1138: @item
1139: The patch itself.
1140: 
1141: Use @samp{diff -u} to make your diffs.  Diffs without context are hard
1142: to install reliably.  More than that, they are hard to study; we must
1143: always study a patch to decide whether we want to install it.  Context
1144: format is better than contextless diffs, but we prefer the unified
1145: format.
1146: 
1147: If you have GNU diff, use @samp{diff -u -F'^[_a-zA-Z0-9$]\+ *('} when
1148: making diffs of C code.  This shows the name of the function that each
1149: change occurs in.
1150: 
1151: If you are using the Emacs repository, make sure your copy is
1152: up-to-date (e.g., with @code{git pull}).  You can commit your changes
1153: to a private branch and generate a patch from the master version by
1154: using @code{git format-patch master}. Or you can leave your changes
1155: uncommitted and use @code{git diff}.
1156: 
1157: @item
1158: Avoid any ambiguity as to which is the old version and which is the new.
1159: Please make the old version the first argument to diff, and the new
1160: version the second argument.  And please give one version or the other a
1161: name that indicates whether it is the old version or your new changed
1162: one.
1163: 
1164: @item
1165: Write the commit log entries for your changes.  This is both to save us
1166: the extra work of writing them, and to help explain your changes so we
1167: can understand them.
1168: 
1169: The purpose of the commit log is to show people where to find what was
1170: changed.  So you need to be specific about what functions you changed;
1171: in large functions, it's often helpful to indicate where within the
1172: function the change was.
1173: 
1174: On the other hand, once you have shown people where to find the change,
1175: you need not explain its purpose in the change log.  Thus, if you add a
1176: new function, all you need to say about it is that it is new.  If you
1177: feel that the purpose needs explaining, it probably does---but put the
1178: explanation in comments in the code.  It will be more useful there.
1179: 
1180: Please look at the commit log entries of recent commits to see what
1181: sorts of information to put in, and to learn the style that we use.
1182: Note that, unlike some other projects, we do require commit logs for
1183: documentation, i.e., Texinfo files.
1184: @xref{Change Log},
1185: @ifset WWW_GNU_ORG
1186: see
1187: @url{https://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html},
1188: @end ifset
1189: @xref{Change Log Concepts, Change Log Concepts,
1190: Change Log Concepts, standards, GNU Coding Standards}.
1191: 
1192: @item
1193: When you write the fix, keep in mind that we can't install a change that
1194: would break other systems.  Please think about what effect your change
1195: will have if compiled on another type of system.
1196: 
1197: Sometimes people send fixes that @emph{might} be an improvement in
1198: general---but it is hard to be sure of this.  It's hard to install
1199: such changes because we have to study them very carefully.  Of course,
1200: a good explanation of the reasoning by which you concluded the change
1201: was correct can help convince us.
1202: 
1203: The safest changes are changes to the configuration files for a
1204: particular machine.  These are safe because they can't create new bugs
1205: on other machines.
1206: 
1207: Please help us keep up with the workload by designing the patch in a
1208: form that is clearly safe to install.
1209: @end itemize
1210: 
1211: @node Contributing
1212: @section Contributing to Emacs Development
1213: @cindex contributing to Emacs
1214: 
1215: Emacs is a collaborative project and we encourage contributions from
1216: anyone and everyone.
1217: 
1218: There are many ways to contribute to Emacs:
1219: 
1220: @itemize
1221: @item
1222: find and report bugs; @xref{Bugs}.
1223: 
1224: @item
1225: answer questions on the Emacs user mailing list
1226: @url{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs}.
1227: 
1228: @item
1229: write documentation, either on the @uref{https://www.emacswiki.org/,
1230: wiki}, or in the Emacs source repository (@pxref{Sending Patches}).
1231: 
1232: @item
1233: check if existing bug reports are fixed in newer versions of Emacs
1234: @url{https://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs}.
1235: 
1236: @item
1237: fix existing bug reports.
1238: 
1239: @item
1240: @c etc/TODO not in WWW_GNU_ORG
1241: implement a feature listed in the @file{etc/TODO} file in the Emacs
1242: distribution, and submit a patch.
1243: 
1244: @item
1245: implement a new feature, and submit a patch.
1246: 
1247: @item
1248: develop a package that works with Emacs, and publish it on your own
1249: or in GNU ELPA (@url{https://elpa.gnu.org/}).
1250: 
1251: @item
1252: port Emacs to a new platform, but that is not common nowadays.
1253: 
1254: @end itemize
1255: 
1256: If you would like to work on improving Emacs, please contact the maintainers at
1257: @ifnothtml
1258: @email{emacs-devel@@gnu.org}.
1259: @end ifnothtml
1260: @ifhtml
1261: @url{https://lists.gnu.org/mailman/listinfo/emacs-devel, the
1262: emacs-devel mailing list}.
1263: @end ifhtml
1264: You can ask for suggested projects or suggest your own ideas.
1265: 
1266: If you have already written an improvement, please tell us about it.  If
1267: you have not yet started work, it is useful to contact
1268: @ifnothtml
1269: @email{emacs-devel@@gnu.org}
1270: @end ifnothtml
1271: @ifhtml
1272: @url{https://lists.gnu.org/mailman/listinfo/emacs-devel, emacs-devel}
1273: @end ifhtml
1274: before you start; it might be possible to suggest ways to make your
1275: extension fit in better with the rest of Emacs.
1276: 
1277: When implementing a feature, please follow the Emacs coding standards;
1278: @xref{Coding Standards}. In addition, non-trivial contributions
1279: require a copyright assignment to the FSF; @xref{Copyright Assignment}.
1280: 
1281: The development version of Emacs can be downloaded from the
1282: repository where it is actively maintained by a group of developers.
1283: See the Emacs project page
1284: @url{https://savannah.gnu.org/projects/emacs/} for access details.
1285: 
1286: It is important to write your patch based on the current working
1287: version.  If you start from an older version, your patch may be
1288: outdated (so that maintainers will have a hard time applying it), or
1289: changes in Emacs may have made your patch unnecessary.  After you have
1290: downloaded the repository source, you should read the file
1291: @file{INSTALL.REPO} for build instructions (they differ to some extent
1292: from a normal build).
1293: 
1294: If you would like to make more extensive contributions, see the
1295: @file{CONTRIBUTE} file in the Emacs distribution for information on
1296: how to be an Emacs developer.
1297: 
1298: For documentation on Emacs (to understand how to implement your
1299: desired change), refer to:
1300: 
1301: @itemize
1302: @item
1303: @ifset WWW_GNU_ORG
1304: @ifhtml
1305: the Emacs Manual
1306: @url{https://www.gnu.org/software/emacs/manual/emacs.html}.
1307: @end ifhtml
1308: @ifnothtml
1309: @xref{Top, Emacs Manual,,emacs}.
1310: @end ifnothtml
1311: @end ifset
1312: @ifclear WWW_GNU_ORG
1313: @xref{Top, Emacs Manual,,emacs}.
1314: @end ifclear
1315: 
1316: @item
1317: @ifset WWW_GNU_ORG
1318: @ifhtml
1319: the Emacs Lisp Reference Manual
1320: @url{https://www.gnu.org/software/emacs/manual/elisp.html}.
1321: @end ifhtml
1322: @ifnothtml
1323: @xref{Top, Emacs Lisp Reference Manual,,elisp}.
1324: @end ifnothtml
1325: @end ifset
1326: @ifclear WWW_GNU_ORG
1327: @xref{Top, Emacs Lisp Reference Manual,,elisp}.
1328: @end ifclear
1329: 
1330: @item
1331: @url{https://www.gnu.org/software/emacs}
1332: 
1333: @item
1334: @url{https://www.emacswiki.org/}
1335: @end itemize
1336: 
1337: @menu
1338: * Coding Standards::        GNU Emacs coding standards
1339: * Copyright Assignment::    assigning copyright to the FSF
1340: @end menu
1341: 
1342: @node Coding Standards
1343: @subsection Coding Standards
1344: @cindex coding standards
1345: 
1346: Contributed code should follow the GNU Coding Standards
1347: @url{https://www.gnu.org/prep/standards/}. This may also be available
1348: in info on your system.
1349: 
1350: If it doesn't, we'll need to find someone to fix the code before we
1351: can use it.
1352: 
1353: Emacs has additional style and coding conventions:
1354: 
1355: @itemize
1356: @item
1357: @ifset WWW_GNU_ORG
1358: @ifhtml
1359: the ``Tips and Conventions'' Appendix in the Emacs Lisp Reference
1360: @url{https://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html}.
1361: @end ifhtml
1362: @ifnothtml
1363: @xref{Tips, ``Tips and Conventions'' Appendix in the Emacs Lisp Reference, Tips
1364: Appendix, elisp, Emacs Lisp Reference}.
1365: @end ifnothtml
1366: @end ifset
1367: @ifclear WWW_GNU_ORG
1368: @xref{Tips, ``Tips and Conventions'' Appendix in the Emacs Lisp Reference, Tips
1369: Appendix, elisp, Emacs Lisp Reference}.
1370: @end ifclear
1371: 
1372: @item
1373: Avoid using @code{defadvice} or @code{with-eval-after-load} for Lisp code
1374: to be included in Emacs.
1375: 
1376: @item
1377: Remove all trailing whitespace in all source and text files.
1378: 
1379: @item
1380: Emacs has no convention on whether to use tabs in source code; please
1381: don't change whitespace in the files you edit.
1382: 
1383: @item
1384: Use @code{?\s} instead of @code{? } in Lisp code for a space character.
1385: 
1386: @end itemize
1387: 
1388: @node Copyright Assignment
1389: @subsection Copyright Assignment
1390: @cindex copyright assignment
1391: 
1392: The FSF (Free Software Foundation) is the copyright holder for GNU Emacs.
1393: The FSF is a nonprofit with a worldwide mission to promote computer
1394: user freedom and to defend the rights of all free software users.
1395: For general information, see the website @url{https://www.fsf.org/}.
1396: 
1397: Generally speaking, for non-trivial contributions to GNU Emacs and
1398: packages stored in GNU ELPA, we require that the copyright be assigned
1399: to the FSF@.  For the reasons behind this, see
1400: @url{https://www.gnu.org/licenses/why-assign.html}.
1401: 
1402: Copyright assignment is a simple process.  Residents of some countries
1403: can do it entirely electronically.  We can help you get started,
1404: including sending you the forms you should fill, and answer any
1405: questions you may have (or point you to the people with the answers),
1406: at the @email{emacs-devel@@gnu.org} mailing list.
1407: 
1408: (Please note: general discussion about why some GNU projects ask
1409: for a copyright assignment is off-topic for emacs-devel.
1410: See gnu-misc-discuss instead.)
1411: 
1412: A copyright disclaimer is also a possibility, but we prefer an assignment.
1413: Note that the disclaimer, like an assignment, involves you sending
1414: signed paperwork to the FSF (simply saying ``this is in the public domain''
1415: is not enough).  Also, a disclaimer cannot be applied to future work, it
1416: has to be repeated each time you want to send something new.
1417: 
1418: We can accept small changes (roughly, fewer than 15 lines) without
1419: an assignment.  This is a cumulative limit (e.g., three separate 5 line
1420: patches) over all your contributions.
1421: 
1422: @node Service
1423: @section How To Get Help with GNU Emacs
1424: @cindex help in using Emacs
1425: @cindex @samp{help-gnu-emacs} mailing list
1426: @cindex @samp{gnu.emacs.help} newsgroup
1427: 
1428: If you need help installing, using or changing GNU Emacs, there are
1429: two ways to find it:
1430: 
1431: @itemize @bullet
1432: @item
1433: Send a message to
1434: @ifnothtml
1435: the mailing list @email{help-gnu-emacs@@gnu.org},
1436: @end ifnothtml
1437: @ifhtml
1438: @url{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs, the
1439: help-gnu-emacs mailing list},
1440: @end ifhtml
1441: or post your request on newsgroup @code{gnu.emacs.help}.  (This
1442: mailing list and newsgroup interconnect, so it does not matter which
1443: one you use.)
1444: 
1445: @item
1446: Look in the @uref{https://www.fsf.org/resources/service/, service
1447: directory} for someone who might help you for a fee.
1448: @end itemize
1449: 
1450: @ifnottex
1451: @lowersections
1452: @end ifnottex
1453: