Download GNU Emacs Manual - Programming Systems Lab

Chapter 33: Dealing with Common Problems
415
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.
33.3.2 Understanding Bug Reporting
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 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 C-x C-f /glorp/baz.ugh RET, visiting a file which
(you know) happens to be rather large, and Emacs displays ‘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 ‘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 ‘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 ‘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
‘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 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 C-x C-f unless you 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 RET A B C 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
debug the problem, and report explanations that are more than guesses, that is useful—but
please include the facts as well.