diff man/trouble.texi @ 25829:ac7e9e5e2ccb

#

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