changeset 84205:81449b7e624b

Move to ../doc/emacs/, misc/
author Glenn Morris <rgm@gnu.org>
date Thu, 06 Sep 2007 04:41:11 +0000
parents ac4ff6c38950
children 601a0a792d7b
files man/trouble.texi
diffstat 1 files changed, 0 insertions(+), 1066 deletions(-) [+]
line wrap: on
line diff
--- a/man/trouble.texi	Thu Sep 06 04:41:05 2007 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,1066 +0,0 @@
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
-@c   2003, 2004, 2005, 2006, 2007 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 C-@key{BREAK} @r{(MS-DOS only)}
-Quit: cancel running or partially typed command.
-@item C-]
-Abort innermost recursive editing level and cancel the command which
-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 a command before it has finished:
-@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 still 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 the way to get 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 a kill command; 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; 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.
-@iftex
-@xref{MS-DOS Keyboard,,,emacs-xtra, Specialized Emacs Features}.
-@end iftex
-@ifnottex
-@xref{MS-DOS Keyboard}.
-@end ifnottex
-
-
-@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 non-@code{nil}.  @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}.
-
-  On a text terminal, 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 are some situations where 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 a case not handled.  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 sequence @kbd{@key{ESC} @key{ESC} @key{ESC}}
-(@code{keyboard-escape-quit}) can either quit or abort.  (We defined
-it this way because @key{ESC} means ``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, as with @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 the next 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.
-* 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 on a graphical display, it determines
-automatically which key should be @key{DEL}.  In some unusual cases
-Emacs gets the wrong information from the system.  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.
-
-  On a graphical display, 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, this 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}.
-
-  On a graphical display, 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 if you do 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 text on a text terminal looks wrong, the first thing to do is
-see whether it is wrong in the buffer.  Type @kbd{C-l} to redisplay
-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 terminfo
-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.  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 terminfo 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, first type @kbd{C-h l} to
-see what commands you typed to produce the observed results.  Then try
-undoing the changes step by step using @kbd{C-x u}, until it gets back
-to a state you consider correct.
-
-  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 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.  When the
-reserve has been used, @samp{!MEM FULL!} appears at the beginning of
-the mode line, indicating there is no more reserve.
-
-  Once you have saved your modified buffers, you can exit this Emacs
-session and start another, or you can use @kbd{M-x kill-some-buffers}
-to free space in the current Emacs job.  If this frees up sufficient
-space, Emacs will refill its memory reserve, and @samp{!MEM FULL!}
-will disappear from the mode line.  That means you can safely go on
-editing in the same Emacs session.
-
-  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} considers each of the files that you
-were editing during that session; for each such file, 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.
-
-  As a last resort, if you had buffers with content which were not
-associated with any files, or if the autosave was not recent enough to
-have recorded important changes, you can use the
-@file{etc/emacs-buffer.gdb} script with GDB (the GNU Debugger) to
-retrieve them from a core dump--provided that a core dump was saved,
-and that the Emacs executable was not stripped of its debugging
-symbols.
-
-  As soon as you get the core dump, rename it to another name such as
-@file{core.emacs}, so that another crash won't overwrite it.
-
-  To use this script, run @code{gdb} with the file name of your Emacs
-executable and the file name of the core dump, e.g. @samp{gdb
-/usr/bin/emacs core.emacs}.  At the @code{(gdb)} prompt, load the
-recovery script: @samp{source /usr/src/emacs/etc/emacs-buffer.gdb}.
-Then type the command @code{ybuffer-list} to see which buffers are
-available.  For each buffer, it lists a buffer number.  To save a
-buffer, use @code{ysave-buffer}; you specify the buffer number, and
-the file name to write that buffer into.  You should use a file name
-which does not already exist; if the file does exist, the script does
-not make a backup of its old contents.
-
-@node Emergency Escape
-@subsection Emergency Escape
-
-  On text-only terminals, the @dfn{emergency escape} feature suspends
-Emacs immediately if you type @kbd{C-g} a second time before Emacs can
-actually respond to the first one by quitting.  This is so you can
-always get out of GNU Emacs no matter how badly it might be hung.
-When things are working properly, Emacs recognizes and handles the
-first @kbd{C-g} so fast that the second one won't trigger emergency
-escape.  However, if some problem prevents Emacs from handling the
-first @kbd{C-g} properly, then the second one will get you back to the
-shell.
-
-  When you resume Emacs after a suspension caused by emergency escape,
-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{n}
-skips this.
-
-  Saying @kbd{y} to @samp{Abort (and dump core)?} causes Emacs to
-crash, 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 this question @kbd{n}, Emacs execution resumes.  With
-luck, Emacs will ultimately do the requested quit.  If not, each
-subsequent @kbd{C-g} invokes emergency escape 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 get back to the former
-state.  The quit you requested will happen by and by.
-
-  Emergency escape is active only for text terminals.  On graphical
-displays, you can use the mouse to kill Emacs or switch to another
-program.
-
-  On MS-DOS, you must type @kbd{C-@key{BREAK}} (twice) to cause
-emergency escape---but there are cases where it won't work, when
-system call hangs or when Emacs is stuck in a tight loop in C code.
-
-@node 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 Emacs psychotherapist will help you feel better.  Each time you
-say something to the psychotherapist, you must end it by typing
-@key{RET} @key{RET}.  This indicates you are finished typing.
-
-@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 accesses an invalid memory location (``segmentation
-fault''), or exits 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 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.  Ask other Emacs users, too.  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 displays @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.
-
-  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.
-
-@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 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 bug.
-
-@item
-If non-@acronym{ASCII} 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 start the Lisp
-debugger, which shows you a backtrace.  Copy the text of the
-debugger's backtrace into the bug report.  @xref{Debugger,, The Lisp
-Debugger, elisp, the Emacs Lisp Reference Manual}, for information on
-debugging Emacs Lisp programs with the Edebug package.
-
-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.
-
-@ifnottex
-@xref{Sending Patches}, for guidelines on how to make it easy for us to
-understand and install your patches.
-@end ifnottex
-
-@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.  @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{emacs-devel@@gnu.org}.  A pretester
-should be prepared to investigate bugs as well as report them.  If you'd
-like to work on improving Emacs, please ask for suggested projects or
-suggest your own ideas.
-
-If you have already written an improvement, please tell us about it.  If
-you have not yet started work, it is useful to contact
-@email{emacs-devel@@gnu.org} before you start; it might be
-possible to suggest ways to make your extension fit in better with the
-rest of Emacs.
-
-The development version of Emacs can be downloaded from the CVS
-repository where it is actively maintained by a group of developers.
-See the Emacs project page
-@url{http://savannah.gnu.org/projects/emacs/} for details.
-
-@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