procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update Lossage chapter of Emacs manual.

Browse source 
* doc/emacs/trouble.texi (Lossage): Refer to Bugs node for problems.
(DEL Does Not Delete): Don't use "usual erasure key" teminology.
(Screen Garbled): Don't refer to terminal "manufacturers".
(Total Frustration): Node deleted.  Eliza is documented in
Amusements now.
(Known Problems): More info about using the bug tracker.  Mention
debbugs package.
(Bug Criteria): Copyedits.
(Understanding Bug Reporting): Mention emacs -Q.
This commit is contained in:
Chong Yidong 2012-01-07 11:15:48 +08:00
parent e7719ea1b2
commit c61ab18c89
4 changed files with 149 additions and 159 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
admin/FOR-RELEASE
View file

@ -171,7 +171,7 @@ screen.texi cyd
search.texi cyd
sending.texi cyd
text.texi cyd
trouble.texi
trouble.texi cyd
vc-xtra.texi cyd
vc1-xtra.texi cyd
windows.texi cyd

12
doc/emacs/ChangeLog
View file

@ -1,3 +1,15 @@
2012-01-07 Chong Yidong <cyd@gnu.org>
* trouble.texi (Lossage): Refer to Bugs node for problems.
(DEL Does Not Delete): Don't use "usual erasure key" teminology.
(Screen Garbled): Don't refer to terminal "manufacturers".
(Total Frustration): Node deleted. Eliza is documented in
Amusements now.
(Known Problems): More info about using the bug tracker. Mention
debbugs package.
(Bug Criteria): Copyedits.
(Understanding Bug Reporting): Mention emacs -Q.
2012-01-06 Chong Yidong <cyd@gnu.org>
* custom.texi (Specifying File Variables): The mode: keyword

4
doc/emacs/emacs.texi
View file

@ -1088,9 +1088,7 @@ Dealing with Emacs Trouble
* 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.
* Emergency Escape:: What to do if Emacs stops responding.
Reporting Bugs

290
doc/emacs/trouble.texi
View file

@ -40,8 +40,8 @@ Cancel a previously made change in the buffer contents (@code{undo}).
@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}.)
and cancels the command that invoked the recursive edit
(@pxref{Recursive Edit}).
@cindex quitting
@kindex C-g
@ -54,7 +54,7 @@ a kill command that is taking a long time, either your text will
kill ring, or maybe both. If the region is active, @kbd{C-g}
deactivates the mark, unless Transient Mark mode is off
(@pxref{Disabled Transient Mark}). If you are in the middle of an
incremental search, @kbd{C-g} does special things; it may take two
incremental search, @kbd{C-g} behaves specially; it may take two
successive @kbd{C-g} characters to get out of a search.
@xref{Incremental Search}, for details.
@ -136,12 +136,12 @@ 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-p} to read the @file{PROBLEMS} file.
This section describes how to recognize and deal with situations in
which Emacs does not work as you expect, such as keyboard code mixups,
garbled displays, running out of memory, and crashes and hangs.
@xref{Bugs}, for what to do when you think you have found a bug in
Emacs.
@menu
* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete.
@ -150,40 +150,35 @@ in the Emacs distribution. Type @kbd{C-h C-f} to read the FAQ; type
* 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.
* Emergency Escape:: What to do if Emacs stops responding.
@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, usually labeled @key{Backspace},
which is ordinarily used 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}.
In Emacs, this key is supposed to be equivalent to @key{DEL}.
When Emacs starts up on a graphical display, it determines
automatically which key should be @key{DEL}. In some unusual cases,
Emacs gets the wrong information from the system. If the usual
erasure key deletes forwards instead of backwards, that is probably
what happened---Emacs ought to be treating the @key{Backspace} key as
@key{DEL}, but it isn't.
Emacs gets the wrong information from the system, and @key{Backspace}
ends up deleting forwards instead of backwards.
Some keyboards also have a @key{Delete} key, which is ordinarily
used to delete forwards. If this key deletes backward in Emacs, that
too suggests Emacs got the wrong information---but in the opposite
sense.
On a text-only terminal, if you find the usual erasure key prompts
On a text-only terminal, if you find that @key{Backspace} prompts
for a Help command, like @kbd{Control-h}, instead of deleting a
character, it means that key is actually sending the @key{BS}
character. Emacs ought to be treating @key{BS} as @key{DEL}, but it
isn't.
@findex normal-erase-is-backspace-mode
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
@ -192,13 +187,10 @@ 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{Backspace}
deletes forwards instead of backwards, use this line to make
@key{Backspace} act as @key{DEL} (resulting in behavior compatible
with Emacs 20 and previous versions):
To fix the problem in every Emacs session, put one of the following
lines into your initialization file (@pxref{Init File}). For the
first case above, where @key{Backspace} deletes forwards instead of
backwards, use this line to make @key{Backspace} act as @key{DEL}:
@lisp
(normal-erase-is-backspace-mode 0)
@ -224,12 +216,12 @@ Customization}.
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}.
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}. @xref{Recursive Edit}.
@node Screen Garbled
@subsection Garbage on the Screen
@ -244,12 +236,9 @@ the following section.)
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.
one of its sections. If you seem to be using the right terminfo
entry, it is possible that there is a bug in the terminfo entry, or a
bug in Emacs that appears for certain terminal types.
@node Text Garbled
@subsection Garbage in the Text
@ -385,25 +374,6 @@ program.
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
@ -432,41 +402,51 @@ of the main places you can read about known issues:
@itemize
@item
The @file{etc/PROBLEMS} file in the Emacs distribution; type @kbd{C-h
C-p} to read it. This file contains a list of particularly well-known
issues that have been encountered in compiling, installing and running
Emacs. Often, there are suggestions for workarounds and solutions.
The @file{etc/PROBLEMS} file; type @kbd{C-h C-p} to read it. This
file contains a list of particularly well-known issues that have been
encountered in compiling, installing and running Emacs. Often, there
are suggestions for workarounds and solutions.
@item
Some additional user-level problems can be found in @ref{Bugs and
problems, , Bugs and problems, efaq, GNU Emacs FAQ}.
@cindex bug tracker
@item
The GNU Bug Tracker at @url{http://debbugs.gnu.org}. Emacs bugs are
filed in the tracker under the @samp{emacs} package. The tracker
records information about the status of each bug, the initial bug
report, and the follow-up messages by the bug reporter and Emacs
developers. You can search for bugs by subject, severity, and other
criteria.
@cindex debbugs package
Instead of browsing the bug tracker as a webpage, you can browse it
from Emacs using the @code{debbugs} package, which can be downloaded
via the Package Menu (@pxref{Packages}). This package provides the
command @kbd{M-x debbugs-gnu} to list bugs, and @kbd{M-x
debbugs-gnu-search} to search for a specific bug.
@item
The @samp{bug-gnu-emacs} mailing list (also available as the newsgroup
@samp{gnu.emacs.bug}). You can read the list archives at
@url{http://lists.gnu.org/mailman/listinfo/bug-gnu-emacs}. If you
like, you can also subscribe to the list. Be aware that the sole
purpose of this list is to provide the Emacs maintainers with
information about bugs and feature requests. Reports may contain
fairly large amounts of data; spectators should not complain about
this.
@url{http://lists.gnu.org/mailman/listinfo/bug-gnu-emacs}. This list
works as a ``mirror'' of the Emacs bug reports and follow-up messages
which are sent to the bug tracker. It also contains old bug reports
from before the bug tracker was introduced (in early 2008).
@item
The bug tracker at @url{http://debbugs.gnu.org}. From early 2008,
reports from the @samp{bug-gnu-emacs} list have also been sent here.
The tracker contains the same information as the mailing list, just in
a different format. You may prefer to browse and read reports using
the tracker.
If you like, you can subscribe to the list. Be aware that its purpose
is to provide the Emacs maintainers with information about bugs and
feature requests, so reports may contain fairly large amounts of data;
spectators should not complain about this.
@item
The @samp{emacs-pretest-bug} mailing list. This list is no longer
used, and is mainly of historical interest. At one time, it was used
for bug reports in development (i.e., not yet released) versions of
Emacs. You can read the archives for 2003 to mid 2007 at
@url{http://lists.gnu.org/archive/html/emacs-pretest-bug/}. From
late 2007 to mid 2008, the address was an alias for the
@samp{emacs-devel} mailing list. From mid 2008 onwards, it has been
an alias for @samp{bug-gnu-emacs}.
@url{http://lists.gnu.org/archive/html/emacs-pretest-bug/}. Nowadays,
it is an alias for @samp{bug-gnu-emacs}.
@item
The @samp{emacs-devel} mailing list. Sometimes people report bugs to
@ -485,33 +465,32 @@ 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.
If the Emacs display does not correspond properly to the contents of
the buffer, then it is a bug. But you should check that features like
buffer narrowing (@pxref{Narrowing}), which can hide parts of the
buffer or change how it is displayed, are not responsible.
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.
sure that it is really Emacs's fault. Some commands simply take a
long time. Type @kbd{C-g} (@kbd{C-@key{BREAK}} on MS-DOS) and then
@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.
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, it might actually be working right. If in doubt,
read the command's documentation (@pxref{Name Help}).
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
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
@ -527,59 +506,61 @@ 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
If the built-in documentation for 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.
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.
@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. If you want to
actually @emph{debug} the problem, and report explanations that are
more than guesses, that is useful---but please include the raw facts
as well.
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
large, and Emacs displays @samp{I feel pretty today}. The bug report
would need to provide all that information. You should not 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 might 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 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}.
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.
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.
If possible, try quickly to reproduce the bug by invoking Emacs with
@command{emacs -Q} (so that Emacs starts with no initial
customizations; @pxref{Initial Options}), and repeating the steps that
you took to trigger the bug. If you can reproduce the bug this way,
that rules out bugs in your personal customizations. Then your bug
report should begin by stating that you started Emacs with
@command{emacs -Q}, followed by the exact sequence of steps for
reproducing the bug. If possible, inform us of the exact contents of
any file that is needed to reproduce the bug.
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.
Some bugs are not reproducible from @command{emacs -Q}; some are not
easily reproducible at all. In that case, you should report what you
have---but, as before, please stick to the raw facts about what you
did to trigger the bug the first time.
@node Checklist
@subsection Checklist for Bug Reports
@ -616,15 +597,14 @@ address. Or you can simply send an email to that address describing
the problem.
Your report will be sent to the @samp{bug-gnu-emacs} mailing list, and
stored in the tracker at @url{http://debbugs.gnu.org}. Please try to
stored in the GNU Bug Tracker at @url{http://debbugs.gnu.org}. Please
include a valid reply email address, in case we need to ask you for
more information about your report. Submissions are moderated, so
there may be a delay before your report appears.
You do not need to know how the @url{http://debbugs.gnu.org} bug
tracker works in order to report a bug, but if you want to, you can
read the tracker's online documentation to see the various features
you can use.
You do not need to know how the Gnu Bug Tracker works in order to
report a bug, but if you want to, you can read the tracker's online
documentation to see the various features you can use.
All mail sent to the @samp{bug-gnu-emacs} mailing list is also
gatewayed to the @samp{gnu.emacs.bug} newsgroup. The reverse is also
@ -689,10 +669,10 @@ 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.
If at all possible, give a full recipe for an Emacs started with the
@samp{-Q} option (@pxref{Initial Options}). This bypasses your
@file{.emacs} customizations.
The precise commands we need to type to reproduce the bug. If at all
possible, give a full recipe for an Emacs started with the @samp{-Q}
option (@pxref{Initial Options}). This bypasses your personal
customizations.
@findex open-dribble-file
@cindex dribble file
@ -722,8 +702,8 @@ 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.
your Emacs initialization 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
@ -806,13 +786,13 @@ produce it, copy it into the bug report.
@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 files). 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.
including your initialization 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 initialization file (start
Emacs with the @code{-Q} switch to prevent loading the init files).
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
@ -983,8 +963,8 @@ your best to help.
Send an explanation with your changes of what problem they fix or what
improvement they bring about. For a fix for an existing bug, it is
best to reply to the relevant discussion on the @samp{bug-gnu-emacs}
list, or item in the @url{http://debbugs.gnu.org} tracker. Explain
why your change fixes the bug.
list, or the bug entry in the GNU Bug Tracker at
@url{http://debbugs.gnu.org}. Explain why your change fixes the bug.
@item
Always include a proper bug report for the problem you think you have