@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 Free Software
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2015 Free Software
@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@iftex
@table @kbd
@item C-g
-@itemx C-@key{BREAK} @r{(MS-DOS only)}
+@itemx C-@key{Break} @r{(MS-DOS only)}
Quit: cancel running or partially typed command.
@item C-]
Abort innermost recursive editing level and cancel the command which
successive @kbd{C-g} characters to get out of a search.
@xref{Incremental Search}, for details.
- On MS-DOS, the character @kbd{C-@key{BREAK}} serves as a quit character
+ On MS-DOS, the character @kbd{C-@key{Break}} serves as a quit character
like @kbd{C-g}. The reason is that it is not feasible, on MS-DOS, to
recognize @kbd{C-g} while a command is running, between interactions
with the user. By contrast, it @emph{is} feasible to recognize
-@kbd{C-@key{BREAK}} at all times.
+@kbd{C-@key{Break}} at all times.
@iftex
@xref{MS-DOS Keyboard,,,emacs-xtra, Specialized Emacs Features}.
@end iftex
@node Lossage
@section Dealing with Emacs Trouble
+@cindex troubleshooting Emacs
This section describes how to recognize and deal with situations in
which Emacs does not work as you expect, such as keyboard code mixups,
@subsection If @key{DEL} Fails to Delete
@cindex @key{DEL} vs @key{BACKSPACE}
@cindex @key{BACKSPACE} vs @key{DEL}
+@cindex @key{DEL} does not delete
- Every keyboard has a large key, usually labeled @key{Backspace},
+ Every keyboard has a large key, usually labeled @key{BACKSPACE},
which is ordinarily used to erase the last character that you typed.
In Emacs, this key is supposed to be equivalent to @key{DEL}.
When Emacs starts up on a graphical display, it determines
automatically which key should be @key{DEL}. In some unusual cases,
-Emacs gets the wrong information from the system, and @key{Backspace}
+Emacs gets the wrong information from the system, and @key{BACKSPACE}
ends up deleting forwards instead of backwards.
Some keyboards also have a @key{Delete} key, which is ordinarily
too suggests Emacs got the wrong information---but in the opposite
sense.
- On a text terminal, if you find that @key{Backspace} prompts for a
+ On a text terminal, if you find that @key{BACKSPACE} prompts for a
Help command, like @kbd{Control-h}, instead of deleting a character,
-it means that key is actually sending the @key{BS} character. Emacs
+it means that key is actually sending the @samp{BS} character. Emacs
ought to be treating @key{BS} as @key{DEL}, but it isn't.
@findex normal-erase-is-backspace-mode
To fix the problem in every Emacs session, put one of the following
lines into your initialization file (@pxref{Init File}). For the
-first case above, where @key{Backspace} deletes forwards instead of
-backwards, use this line to make @key{Backspace} act as @key{DEL}:
+first case above, where @key{BACKSPACE} deletes forwards instead of
+backwards, use this line to make @key{BACKSPACE} act as @key{DEL}:
@lisp
(normal-erase-is-backspace-mode 0)
@node Stuck Recursive
@subsection Recursive Editing Levels
+@cindex stuck in recursive editing
+@cindex recursive editing, cannot exit
Recursive editing levels are important and useful features of Emacs, but
they can seem like malfunctions if you do not understand them.
@node Screen Garbled
@subsection Garbage on the Screen
+@cindex garbled display
+@cindex display, incorrect
+@cindex screen display, wrong
If the text on a text terminal looks wrong, the first thing to do is
see whether it is wrong in the buffer. Type @kbd{C-l} to redisplay
@node Text Garbled
@subsection Garbage in the Text
+@cindex garbled text
+@cindex buffer text garbled
If @kbd{C-l} shows that the text is wrong, first type @kbd{C-h l} to
see what commands you typed to produce the observed results. Then try
@node After a Crash
@subsection Recovery After a Crash
+@cindex recovering crashed session
If Emacs or the computer crashes, you can recover the files you were
editing at the time of the crash from their auto-save files. To do
@node Emergency Escape
@subsection Emergency Escape
+@cindex emergency escape
On text terminals, the @dfn{emergency escape} feature suspends Emacs
immediately if you type @kbd{C-g} a second time before Emacs can
displays, you can use the mouse to kill Emacs or switch to another
program.
- On MS-DOS, you must type @kbd{C-@key{BREAK}} (twice) to cause
+ On MS-DOS, you must type @kbd{C-@key{Break}} (twice) to cause
emergency escape---but there are cases where it won't work, when
system call hangs or when Emacs is stuck in a tight loop in C code.
@node Bug Criteria
@subsection When Is There a Bug
+@cindex bug criteria
+@cindex what constitutes an Emacs bug
If Emacs accesses an invalid memory location (``segmentation
fault''), or exits with an operating system error message that
Taking forever to complete a command can be a bug, but you must make
sure that it is really Emacs's fault. Some commands simply take a
-long time. Type @kbd{C-g} (@kbd{C-@key{BREAK}} on MS-DOS) and then
+long time. Type @kbd{C-g} (@kbd{C-@key{Break}} on MS-DOS) and then
@kbd{C-h l} to see whether the input Emacs received was what you
intended to type; if the input was such that you @emph{know} it should
have been processed quickly, report a bug. If you don't know whether
@node Understanding Bug Reporting
@subsection Understanding Bug Reporting
+@cindex bug reporting
+@cindex report an Emacs bug, how to
@findex emacs-version
When you decide that there is a bug, it is important to report it
have---but, as before, please stick to the raw facts about what you
did to trigger the bug the first time.
+ If you have multiple issues that you want to report, please make a
+separate bug report for each.
+
@node Checklist
@subsection Checklist for Bug Reports
-
-@cindex reporting bugs
+@cindex checklist before reporting a bug
+@cindex bug reporting, checklist
Before reporting a bug, first try to see if the problem has already
been reported (@pxref{Known Problems}).
decide for themselves.
When you have finished writing your report, type @kbd{C-c C-c} and it
-will be sent to the Emacs maintainers at @email{bug-gnu-emacs@@gnu.org}.
+will be sent to the Emacs maintainers at
+@ifnothtml
+@email{bug-gnu-emacs@@gnu.org}.
+@end ifnothtml
+@ifhtml
+@url{http://lists.gnu.org/mailman/listinfo/bug-gnu-emacs, bug-gnu-emacs}.
+@end ifhtml
(If you want to suggest an improvement or new feature, use the same
address.) If you cannot send mail from inside Emacs, you can copy the
text of your report to your normal mail client (if your system
One way to record the input to Emacs precisely is to write a dribble
file. To start the file, use the @kbd{M-x open-dribble-file
@key{RET}} command. From then on, Emacs copies all your input to the
-specified dribble file until the Emacs process is killed.
+specified dribble file until the Emacs process is killed. Be aware
+that sensitive information (such as passwords) may end up recorded in
+the dribble file.
@item
@findex open-termscript
@item
If the bug is that the Emacs Manual or the Emacs Lisp Reference Manual
fails to describe the actual behavior of Emacs, or that the text is
-confusing, copy in the text from the online manual which you think is
+confusing, copy in the text from the manual which you think is
at fault. If the section is small, just the section name is enough.
@item
before the error happens (that is to say, you must give that command
and then make the bug happen). This causes the error to start the Lisp
debugger, which shows you a backtrace. Copy the text of the
-debugger's backtrace into the bug report. @xref{Debugger,, The Lisp
-Debugger, elisp, the Emacs Lisp Reference Manual}, for information on
-debugging Emacs Lisp programs with the Edebug package.
+debugger's backtrace into the bug report. @xref{Edebug,, Edebug,
+elisp, the Emacs Lisp Reference Manual}, for information on debugging
+Emacs Lisp programs with the Edebug package.
This use of the debugger is possible only if you know how to make the
bug happen again. If you can't make it happen again, at least copy
work in the best of circumstances, and we can't keep up unless you do
your best to help.
+Every patch must have several pieces of information before we
+can properly evaluate it.
+
+When you have all these pieces, bundle them up in a mail message and
+send it to the developers. Sending it to
+@email{bug-gnu-emacs@@gnu.org} (which is the bug/feature list) is
+recommended, because that list is coupled to a tracking system that
+makes it easier to locate patches. If your patch is not complete and
+you think it needs more discussion, you might want to send it to
+@email{emacs-devel@@gnu@@gnu.org} instead. If you revise your patch,
+send it as a followup to the initial topic.
+
+We prefer to get the patches as plain text, either inline (be careful
+your mail client does not change line breaks) or as MIME attachments.
+
@itemize @bullet
@item
-Send an explanation with your changes of what problem they fix or what
-improvement they bring about. For a fix for an existing bug, it is
+Include an explanation with your changes of what problem they fix or what
+improvement they bring about.
+
+@itemize
+@item
+For a fix for an existing bug, it is
best to reply to the relevant discussion on the @samp{bug-gnu-emacs}
list, or the bug entry in the GNU Bug Tracker at
@url{http://debbugs.gnu.org}. Explain why your change fixes the bug.
@item
-Always include a proper bug report for the problem you think you have
-fixed. We need to convince ourselves that the change is right before
-installing it. Even if it is correct, we might have trouble
-understanding it if we don't have a way to reproduce the problem.
+For a new feature, include a description of the feature and your
+implementation.
+
+@item
+For a new bug, include a proper bug report for the problem you think
+you have fixed. We need to convince ourselves that the change is
+right before installing it. Even if it is correct, we might have
+trouble understanding it if we don't have a way to reproduce the
+problem.
+@end itemize
@item
Include all the comments that are appropriate to help people reading the
is important.
@item
+The patch itself.
+
Use @samp{diff -c} to make your diffs. Diffs without context are hard
to install reliably. More than that, they are hard to study; we must
always study a patch to decide whether we want to install it. Unidiff
making diffs of C code. This shows the name of the function that each
change occurs in.
+If you are using the Emacs repository, make sure your copy is
+up-to-date (e.g. with @code{git pull}). You can commit your changes
+to a private branch and generate a patch from the master version by
+using @code{git format-patch master}. Or you can leave your changes
+uncommitted and use @code{git diff}.
+
@item
Avoid any ambiguity as to which is the old version and which is the new.
Please make the old version the first argument to diff, and the new
feel that the purpose needs explaining, it probably does---but put the
explanation in comments in the code. It will be more useful there.
-Please read the @file{ChangeLog} files in the @file{src} and
-@file{lisp} directories to see what sorts of information to put in,
-and to learn the style that we use. @xref{Change Log}.
+Please look at the change log entries of recent commits to see what
+sorts of information to put in, and to learn the style that we use. Note that,
+unlike some other projects, we do require change logs for
+documentation, i.e. Texinfo files.
+@xref{Change Log},
+@ifset WWW_GNU_ORG
+see
+@url{http://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html},
+@end ifset
+@xref{Change Log Concepts, Change Log Concepts,
+Change Log Concepts, gnu-coding-standards, GNU Coding Standards}.
@item
When you write the fix, keep in mind that we can't install a change that
@section Contributing to Emacs Development
@cindex contributing to Emacs
-If you would like to help pretest Emacs releases to assure they work
-well, or if you would like to work on improving Emacs, please contact
-the maintainers at @email{emacs-devel@@gnu.org}. A pretester
-should be prepared to investigate bugs as well as report them. If you'd
-like to work on improving Emacs, please ask for suggested projects or
-suggest your own ideas.
+Emacs is a collaborative project and we encourage contributions from
+anyone and everyone.
+
+There are many ways to contribute to Emacs:
+
+@itemize
+@item
+find and report bugs; @xref{Bugs}.
+
+@item
+answer questions on the Emacs user mailing list
+@url{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs}.
+
+@item
+write documentation, either on the wiki, or in the Emacs source
+repository (@pxref{Sending Patches}).
+
+@item
+check if existing bug reports are fixed in newer versions of Emacs
+@url{http://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs}.
+
+@item
+fix existing bug reports
+@url{http://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs}.
+
+@item
+@c etc/TODO not in WWW_GNU_ORG
+implement a feature listed in the @file{etc/TODO} file in the Emacs
+distribution, and submit a patch.
+
+@item
+implement a new feature, and submit a patch.
+
+@item
+develop a package that works with Emacs, and publish it on your own
+or in Gnu ELPA (@url{https://elpa.gnu.org/}).
+
+@item
+port Emacs to a new platform, but that is not common nowadays.
+
+@end itemize
+
+If you would like to work on improving Emacs, please contact the maintainers at
+@ifnothtml
+@email{emacs-devel@@gnu.org}.
+@end ifnothtml
+@ifhtml
+@url{http://lists.gnu.org/mailman/listinfo/emacs-devel, the
+emacs-devel mailing list}.
+@end ifhtml
+You can ask for suggested projects or suggest your own ideas.
If you have already written an improvement, please tell us about it. If
you have not yet started work, it is useful to contact
-@email{emacs-devel@@gnu.org} before you start; it might be
-possible to suggest ways to make your extension fit in better with the
-rest of Emacs.
+@ifnothtml
+@email{emacs-devel@@gnu.org}
+@end ifnothtml
+@ifhtml
+@url{http://lists.gnu.org/mailman/listinfo/emacs-devel, emacs-devel}
+@end ifhtml
+before you start; it might be possible to suggest ways to make your
+extension fit in better with the rest of Emacs.
+
+When implementing a feature, please follow the Emacs coding standards;
+@xref{Coding Standards}. In addition, non-trivial contributions
+require a copyright assignment to the FSF; @xref{Copyright Assignment}.
The development version of Emacs can be downloaded from the
repository where it is actively maintained by a group of developers.
See the Emacs project page
-@url{http://savannah.gnu.org/projects/emacs/} for details.
+@url{http://savannah.gnu.org/projects/emacs/} for access details.
+
+It is important to write your patch based on the current working
+version. If you start from an older version, your patch may be
+outdated (so that maintainers will have a hard time applying it), or
+changes in Emacs may have made your patch unnecessary. After you have
+downloaded the repository source, you should read the file
+@file{INSTALL.REPO} for build instructions (they differ to some extent
+from a normal build).
+
+If you would like to make more extensive contributions, see the
+@file{./CONTRIBUTE} file in the Emacs distribution for information on
+how to be an Emacs developer.
+
+For documentation on Emacs (to understand how to implement your
+desired change), refer to:
+
+@itemize
+@item
+@ifset WWW_GNU_ORG
+@ifhtml
+the Emacs Manual
+@url{http://www.gnu.org/software/emacs/manual/emacs.html}.
+@end ifhtml
+@ifnothtml
+@xref{Top, Emacs Manual,,emacs}.
+@end ifnothtml
+@end ifset
+@ifclear WWW_GNU_ORG
+@xref{Top, Emacs Manual,,emacs}.
+@end ifclear
+
+@item
+@ifset WWW_GNU_ORG
+@ifhtml
+the Emacs Lisp Reference Manual
+@url{http://www.gnu.org/software/emacs/manual/elisp.html}.
+@end ifhtml
+@ifnothtml
+@xref{Top, Emacs Lisp Reference Manual,,elisp}.
+@end ifnothtml
+@end ifset
+@ifclear WWW_GNU_ORG
+@xref{Top, Emacs Lisp Reference Manual,,elisp}.
+@end ifclear
+
+@item
+@url{http://www.gnu.org/software/emacs}
+
+@item
+@url{http://www.emacswiki.org/}
+@end itemize
+
+@menu
+* Coding Standards:: Gnu Emacs coding standards
+* Copyright Assignment:: assigning copyright to the FSF
+@end menu
+
+@node Coding Standards
+@subsection Coding Standards
+@cindex coding standards
+
+Contributed code should follow the GNU Coding Standards
+@url{http://www.gnu.org/prep/standards/}. This may also be available
+in info on your system.
+
+If it doesn't, we'll need to find someone to fix the code before we
+can use it.
+
+Emacs has additional style and coding conventions:
+
+@itemize
+@item
+@ifset WWW_GNU_ORG
+@ifhtml
+the "Tips" Appendix in the Emacs Lisp Reference
+@url{http://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html}.
+@end ifhtml
+@ifnothtml
+@xref{Tips, "Tips" Appendix in the Emacs Lisp Reference, Tips
+Appendix, elisp, Emacs Lisp Reference}.
+@end ifnothtml
+@end ifset
+@ifclear WWW_GNU_ORG
+@xref{Tips, "Tips" Appendix in the Emacs Lisp Reference, Tips
+Appendix, elisp, Emacs Lisp Reference}.
+@end ifclear
+
+@item
+Avoid using @code{defadvice} or @code{eval-after-load} for Lisp code
+to be included in Emacs.
+
+@item
+Remove all trailing whitespace in all source and text files.
+
+@item
+Emacs has no convention on whether to use tabs in source code; please
+don't change whitespace in the files you edit.
+
+@item
+Use @code{?\s} instead of @code{? } in Lisp code for a space character.
+
+@end itemize
+
+@node Copyright Assignment
+@subsection Copyright Assignment
+@cindex copyright assignment
+
+The FSF (Free Software Foundation) is the copyright holder for GNU Emacs.
+The FSF is a nonprofit with a worldwide mission to promote computer
+user freedom and to defend the rights of all free software users.
+For general information, see the website @url{http://www.fsf.org/}.
+
+Generally speaking, for non-trivial contributions to GNU Emacs we
+require that the copyright be assigned to the FSF. For the reasons
+behind this, see @url{http://www.gnu.org/licenses/why-assign.html}.
+
+Copyright assignment is a simple process. Residents of some countries
+can do it entirely electronically. We can help you get started, and
+answer any questions you may have (or point you to the people with the
+answers), at the @email{emacs-devel@@gnu.org} mailing list.
+
+(Please note: general discussion about why some GNU projects ask
+for a copyright assignment is off-topic for emacs-devel.
+See gnu-misc-discuss instead.)
+
+A copyright disclaimer is also a possibility, but we prefer an assignment.
+Note that the disclaimer, like an assignment, involves you sending
+signed paperwork to the FSF (simply saying "this is in the public domain"
+is not enough). Also, a disclaimer cannot be applied to future work, it
+has to be repeated each time you want to send something new.
-For more information on how to contribute, see the @file{etc/CONTRIBUTE}
-file in the Emacs distribution.
+We can accept small changes (roughly, fewer than 15 lines) without
+an assignment. This is a cumulative limit (e.g. three separate 5 line
+patches) over all your contributions.
@node Service
@section How To Get Help with GNU Emacs
+@cindex help in using Emacs
+@cindex help-gnu-emacs mailing list
+@cindex gnu.emacs.help newsgroup
-If you need help installing, using or changing GNU Emacs, there are two
-ways to find it:
+If you need help installing, using or changing GNU Emacs, there are
+two ways to find it:
@itemize @bullet
@item
-Send a message to the mailing list
-@email{help-gnu-emacs@@gnu.org}, or post your request on
-newsgroup @code{gnu.emacs.help}. (This mailing list and newsgroup
-interconnect, so it does not matter which one you use.)
+Send a message to
+@ifnothtml
+the mailing list @email{help-gnu-emacs@@gnu.org},
+@end ifnothtml
+@ifhtml
+@url{http://lists.gnu.org/mailman/listinfo/help-gnu-emacs, the
+help-gnu-emacs mailing list},
+@end ifhtml
+or post your request on newsgroup @code{gnu.emacs.help}. (This
+mailing list and newsgroup interconnect, so it does not matter which
+one you use.)
@item
-Look in the service directory for someone who might help you for a fee.
-The service directory is found in the file named @file{etc/SERVICE} in the
-Emacs distribution.
+Look in the @uref{http://www.fsf.org/resources/service/, service
+directory} for someone who might help you for a fee.
@end itemize
@ifnottex