60.1 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 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 C-g (C-<BREAK> on MS-DOS) and then C-h l
to see whether the input Emacs received was what you intended to type;
if the input was such that you 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.
