Go to the first, previous, next, last section, table of contents.
(This chapter is adapted from the analogous one in the GCC manual,
written by Richard Stallman.)
Your bug reports are essential in making these programs reliable.
Reporting a bug may help you by bringing a solution to your problem, or
it may not. (If it does not, look in the service directory, which is
part of the GNU CC and GNU Emacs distributions.) In any case, the
principal function of a bug report is to help the entire community by
making the next release work better.
Send bug reports for the GNU font utilities, or for their documentation,
to the address
firstname.lastname@example.org. We also welcome
suggestions for improvements, no matter how small.
In order for a bug report to serve its purpose, you must include the
information that makes for fixing the bug, as described below.
Thanks (in advance)!
If you are not sure whether you have found a bug, here are some
If a program gets a fatal signal, for any input whatsoever, that
is a bug. Reliable programs never crash.
If a program produces an invalid font, for any input whatsoever, that is
a bug--unless the program reported a fatal error that forced it to quit
prematurely. For example, if Metafont gives errors reading the output
bzrto -mf, that is a bug. You can run the TeX utility
programs GFtype and TFtoPL to check the validity of a GF or TFM file.
If a program gives an error message for valid input, that is a bug.
Similarly, if a program gives a fatal error when it could continue
processing, that is a bug. It is sometimes hard to tell if these
conditions obtain; you must use your best judgement.
If a program does not give an error message for invalid input, that is a bug.
The purpose of a bug report is to enable someone to
fix the bug if it is not known. It isn't important what happens if the
bug is already known. Therefore, always write your bug reports on the
assumption that the bug is not known.
Sometimes people give a few sketchy facts and ask, "Does this ring a
bell?" or "Should this be happening?" This cannot help us fix a bug,
so it is basically useless. We can only respond by asking for the
details below, so we can investigate. You might as well expedite
matters by sending them to begin with.
Try to make your bug report self-contained. If we ask you for more
information, it is best if you include all the original information in
your response, as well as the new information. We might have discarded
the previous message, or even if we haven't, it takes us time to search
for it. Similarly, if you've reported bugs before, it is still best to
send all the information; we can't possibly remember what environment
To enable us to fix a bug, please include all the information below. If
the bug was in compilation or installation, as opposed to in actually
running one of the programs, the last two items are irrelevant. But in
that case, please also make sure it is not a known problem before
reporting it. See section Problems.
You should include all of the following in your bug report:
The version number of the program. You can get this from the top-level
files `ChangeLog' or `GNUmakefile.in', or from the
`-version' option which all the programs have.
The type of machine you are using, and the operating system name
and version number.
A description of the bug. For example, "The program gets a fatal
signal," or "The baselines in the generated font are too high."
All the command-line arguments you gave the program.
The relevant input files. Since fonts and images are typically binary
files, be sure to use `uuencode' or `btoa' before mailing
them. Be sure to include the TFM file as well as the bitmap (GF or
PK) or BZR file, if the program needs both as input.
Bugs typically apply to a single character in a font; you can find out
what character is being processed with the `-verbose' option. It
should then be straightforward to cut that single character out of the
font with either the `-range' option and/or the `fontconvert'
program, to make a new (very small) font. It is easier for us to deal
with small files.
But if you don't want to take the time to break up the font, please send
in the bug report anyway (with the entire font). We much prefer that to
you not reporting the bug at all!
In other words, we need enough information so that we can run the
offending program under the debugger, so we can find out what's
happening. Without all the command-line arguments, or the input file in
question, we cannot do this. Since you must have found the bug by
running the program with a particular set of options and on a particular
input file, you already have this information; all you need to do is
Here are some things that are not necessary to include in a bug report.
A description of the envelope of the bug.
Often people who encounter a bug spend a lot of time investigating which
changes to the input file or command-line options 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 your time for something else.
A patch for the bug.
A patch for the bug is useful if it is a good one. But don't omit the
necessary information, such as the test case, on the assumption that a
patch is all we need. We might see problems with your patch and decide
to fix the problem another way, or we might not understand the patch at
all. Without an example, we won't be able to verify that the bug is
Also, if we can't understand what bug you are trying to fix, or why your
patch should be an improvement, we won't install it. A test case will
help us to understand.
See section `Sending Patches for GNU CC' in GCC Manual,
for more details on the best way to write changes.
Sometimes people send just a backtrace, but that is not useful by
itself. It is usually the values of local or global variables which
matter, sometimes very far away from the location where you noticed the
bug. We need to be able to run the debugger ourselves to investigate.
A guess about what the bug is or what it depends on.
Such guesses are not useful, and often wrong. It is impossible to guess
correctly without using the debugger to find the facts, so you might as
well save your imagination for other things!
It is just as important to report bugs in the documentation as in the
programs. If you want to do something using these programs, and reading
the manual doesn't tell you how, that is probably a bug. In fact, the
best way to report it is something like: "I want to do x; I
looked in the manual in sections a and b, but they didn't
If your bug report makes it clear that you've actually made an attempt
to find the answers using the manual, we will be much more likely to
take action (since we won't have to search the manual ourselves).
Go to the first, previous, next, last section, table of contents.