[Emacs-diffs] Changes to emacs/man/trouble.texi [gnus-5_10-branch]

[Miles Bader]

Index: emacs/man/trouble.texi
diff -c /dev/null emacs/man/trouble.texi:1.43.2.1
*** /dev/null   Sat Sep  4 12:03:10 2004
--- emacs/man/trouble.texi      Sat Sep  4 12:01:15 2004
***************
*** 0 ****
--- 1,1076 ----
+ @c This is part of the Emacs manual.
+ @c Copyright (C) 1985,86,87,93,94,95,1997,2001,2004 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
+ 
+ @ifnottex
+ @raisesections
+ @end ifnottex
+ 
+ @node Quitting, Lossage, Customization, Top
+ @section Quitting and Aborting
+ @cindex quitting
+ 
+ @table @kbd
+ @item C-g
+ @itemx address@hidden @r{(MS-DOS only)}
+ 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 @address@hidden 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
+ @address@hidden at all times.  @xref{MS-DOS Input}.
+ 
+ @findex keyboard-quit
+   @kbd{C-g} works by setting the variable @code{quit-flag} to @code{t}
+ the instant @kbd{C-g} is typed; Emacs Lisp checks this variable
+ frequently and quits if it is address@hidden  @kbd{C-g} is only
+ actually executed as a command if you type it while Emacs is waiting for
+ input.  In that case, the command it runs is @code{keyboard-quit}.
+ 
+   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 many 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 @address@hidden @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}, for more information
+ about the undo facility.
+ 
+ @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.  For a list of
+ additional problems you might encounter, see @ref{Bugs and problems, ,
+ Bugs and problems, efaq, GNU Emacs FAQ}, and the file @file{etc/PROBLEMS}
+ in the Emacs distribution.  Type @kbd{C-h C-f} to read the FAQ; type
+ @kbd{C-h C-e} to read the @file{PROBLEMS} file.
+ 
+ @menu
+ * DEL Does Not Delete::   What to do if @key{DEL} doesn't delete.
+ * Stuck Recursive::       `[...]' in mode line around the parentheses.
+ * Screen Garbled::        Garbage on the screen.
+ * Text Garbled::          Garbage in the text.
+ * 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 Does Not Delete
+ @subsection If @key{DEL} Fails to Delete
+ @cindex @key{DEL} vs @key{BACKSPACE}
+ @cindex @key{BACKSPACE} vs @key{DEL}
+ @cindex usual erasure key
+ 
+   Every keyboard has a large key, a little ways above the @key{RET} or
+ @key{ENTER} key, which you normally use outside Emacs to erase the
+ last character that you typed.  We call this key @dfn{the usual
+ erasure key}.  In Emacs, it is supposed to be equivalent to @key{DEL},
+ and when Emacs is properly configured for your terminal, it translates
+ that key into the character @key{DEL}.
+ 
+   When Emacs starts up using a window system, it determines
+ automatically which key should be @key{DEL}.  In some unusual cases
+ Emacs gets the wrong information from the system.  If the usual
+ erasure key deletes forwards instead of backwards, that is probably
+ what happened---Emacs ought to be treating the @key{DELETE} key as
+ @key{DEL}, but it isn't.
+ 
+   With a window system, if the usual erasure key is labeled
+ @key{BACKSPACE} and there is a @key{DELETE} key elsewhere, but the
+ @key{DELETE} key deletes backward instead of forward, that too
+ suggests Emacs got the wrong information---but in the opposite sense.
+ It ought to be treating the @key{BACKSPACE} key as @key{DEL}, and
+ treating @key{DELETE} differently, but it isn't.
+ 
+   On a text-only terminal, if you find the usual erasure key 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 ought to be treating @key{BS} as @key{DEL}, but it
+ isn't.
+ 
+   In all of those cases, the immediate remedy is the same: use the
+ command @kbd{M-x normal-erase-is-backspace-mode}.  This toggles
+ between the two modes that Emacs supports for handling @key{DEL}, so
+ if Emacs starts in the wrong mode, it should switch to the right mode.
+ On a text-only terminal, if you want to ask for help when @key{BS} is
+ treated as @key{DEL}, use @key{F1}; @kbd{C-?} may also work, if it
+ sends character code 127.
+ 
+ @findex normal-erase-is-backspace-mode
+   To fix the problem automatically for every Emacs session, you can
+ put one of the following lines into your @file{.emacs} file
+ (@pxref{Init File}).  For the first case above, where @key{DELETE}
+ deletes forwards instead of backwards, use this line to make
+ @key{DELETE} act as @key{DEL} (resulting in behavior compatible
+ with Emacs 20 and previous versions):
+ 
+ @lisp
+ (normal-erase-is-backspace-mode 0)
+ @end lisp
+ 
+ @noindent
+ For the other two cases, where @key{BACKSPACE} ought to act as
+ @key{DEL}, use this line:
+ 
+ @lisp
+ (normal-erase-is-backspace-mode 1)
+ @end lisp
+ 
+ @vindex normal-erase-is-backspace
+   Another way to fix the problem for every Emacs session is to
+ customize the variable @code{normal-erase-is-backspace}: the value
+ @code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is
+ @key{DEL}, and @code{nil} specifies the other mode.  @xref{Easy
+ Customization}.
+ 
+   With a window system, it can also happen that the usual erasure key
+ is labeled @key{BACKSPACE}, there is a @key{DELETE} key elsewhere, and
+ both keys delete forward.  This probably means that someone has
+ redefined your @key{BACKSPACE} key as a @key{DELETE} key.  With X,
+ this is typically done with a command to the @code{xmodmap} program
+ when you start the server or log in.  The most likely motive for this
+ customization was to support old versions of Emacs, so we recommend
+ you simply remove it now.
+ 
+ @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 @address@hidden 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 the following
+ section.)
+ 
+   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 of 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 @address@hidden
+ 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 @address@hidden 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.
+ 
+   Before reporting a bug, it is a good idea to see if it is already
+ known.  You can find the list of known problems in the file
+ @file{etc/PROBLEMS} in the Emacs distribution; type @kbd{C-h C-e} to read
+ it.  Some additional user-level problems can be found in @ref{Bugs and
+ problems, , Bugs and problems, efaq, GNU Emacs FAQ}.  Looking up your
+ problem in these two documents might provide you with a solution or a
+ work-around, or give you additional information about related issues.
+ 
+ @menu
+ * Criteria:  Bug Criteria.     Have you really found a bug?
+ * Understanding Bug Reporting::        How to report a bug effectively.
+ * Checklist::                  Steps to follow for a good bug report.
+ * Sending Patches::            How to send a patch for GNU Emacs.
+ @end menu
+ 
+ @node Bug Criteria
+ @subsection When Is There a Bug
+ 
+   If Emacs 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} (@address@hidden 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 the best
+ possible definition 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 @address@hidden A B C @key{RET} C-p},'' if that is
+ the way you entered the address@hidden
+ 
+   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 @email{bug-gnu-emacs@@gnu.org}, or to
+ @email{emacs-pretest-bug@@gnu.org} if you are pretesting an Emacs beta
+ release.  (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 fairly
+ 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 your data is more than
+ 500,000 bytes, please don't include it directly in the bug report;
+ instead, offer to send it on request, or make it available by ftp and
+ say where.
+ 
+   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
+ @cindex logging keystrokes
+   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 @env{TERM} environment variable
+ For possible display bugs, the terminal type (the value of environment
+ variable @env{TERM}), the complete termcap entry for the terminal from
+ @file{/etc/termcap} (since that file is not identical on all machines),
+ and the output that Emacs actually sent to the terminal.
+ 
+ The way to collect the terminal output is to execute the Lisp expression
+ 
+ @example
+ (open-termscript "~/termscript")
+ @end example
+ 
+ @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 address@hidden
+ 
+ @item
+ If address@hidden text or internationalization is relevant, the locale that
+ was current when you started Emacs.  On GNU/Linux and Unix systems, or
+ if you use a Posix-style shell such as Bash, you can use this shell
+ command to view the relevant values:
+ 
+ @smallexample
+ echo LC_ALL=$LC_ALL LC_COLLATE=$LC_COLLATE LC_CTYPE=$LC_CTYPE \
+   LC_MESSAGES=$LC_MESSAGES LC_TIME=$LC_TIME LANG=$LANG
+ @end smallexample
+ 
+ Alternatively, use the @command{locale} command, if your system has it,
+ to display your locale settings.
+ 
+ You can use the @kbd{M-!} command to execute these commands from
+ Emacs, and then copy the output from the @samp{*Messages*} buffer into
+ the bug report.  Alternatively, @kbd{M-x getenv @key{RET} LC_ALL
+ @key{RET}} will display the value of @code{LC_ALL} in the echo area, and
+ you can copy its output from the @samp{*Messages*} buffer.
+ 
+ @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 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
+ at fault.  If the section is small, just the section name is enough.
+ 
+ @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.
+ 
+ @findex toggle-debug-on-error
+ @pindex Edebug
+ To make a backtrace for the error, use @kbd{M-x toggle-debug-on-error}
+ before the error happens (that is to say, you must give that command
+ 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.  @xref{Debugger,, The Lisp
+ Debugger, 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
+ 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}.
+ 
+ For a short listing of Lisp functions running, type the GDB
+ command @code{xbacktrace}.
+ 
+ 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.
+ 
+ @cindex debugging Emacs, tricks and techniques
+ More detailed advice and other useful techniques for debugging Emacs
+ are available in the file @file{etc/DEBUG} in the Emacs distribution.
+ That file also includes instructions for investigating problems
+ whereby Emacs stops responding (many people assume that Emacs is
+ ``hung,'' whereas in fact it might be in an infinite loop).
+ 
+ To find the file @file{etc/DEBUG} in your Emacs installation, use the
+ directory name stored in the variable @code{data-directory}.
+ @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.
+ It is better to send the bug report right away, go back to editing,
+ and find another bug to report.
+ 
+ Of course, if you can find a simpler example to report @emph{instead} 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 core dump file.
+ 
+ Debugging the core dump might be useful, but it can only be done on
+ your machine, with your Emacs executable.  Therefore, sending the core
+ dump file to the Emacs maintainers won't be useful.  Above all, don't
+ include the core file in an email bug report!  Such a large message
+ can be extremely inconvenient.
+ 
+ @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 @email{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
+ @email{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, Copying, 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
+ @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.)
+ 
+ @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
+ 
+ @ifnottex
+ @lowersections
+ @end ifnottex
+ 
+ @ignore
+    arch-tag: c9cba76d-b2cb-4e0c-ae3f-19d5ef35817c
+ @end ignore