Bugs

(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 bug-gnu-utils@prep.ai.mit.edu. 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)!

• Bug criteria: Have you found a bug?
• Bug reporting: How to effectively report a bug.

Bug criteria

If you are not sure whether you have found a bug, here are some guidelines:

• 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 of 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.

Bug reporting

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 everyone uses!

• Necessary information: What you need to send.
• Unnecessary information: What you don't need to send.
• Documentation bugs: Report the bugs in the manual, too.

Necessary information

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 send it!

Unnecessary information

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 fixed. 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!

Documentation bugs

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 explain it."

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).