path: root/doc/bugs.texi

@c Copyright (C) 1992, 2004, 2011 Free Software Foundation, Inc.
@c This is part of the GNU font utilities manual.
@c For copying conditions, see the file fontutil.texi.

@node Bugs
@chapter Bugs

(This chapter is adapted from the analogous one in the GCC manual,
written by Richard Stallman.)

@cindex bug reports, purpose of
Your bug reports are essential in making these programs reliable.

@cindex service directory
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.

@cindex improvements, suggesting
Send bug reports for the GNU font utilities, or for their documentation,
to the address @code{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)!

@menu
* Bug criteria::                Have you found a bug?
* Bug reporting::               How to effectively report a bug.
@end menu


@node Bug criteria
@section Bug criteria

@cindex criteria for bugs
@cindex bugs, criteria for

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

@itemize @bullet

@item
@cindex fatal signals
If a program gets a fatal signal, for any input whatsoever, that
is a bug.  Reliable programs never crash.

@item
@cindex invalid output fonts
@cindex bad output fonts
@cindex validity of fonts, checking
@cindex fatal errors and invalid output fonts
@pindex gftype@r{, checking validity font}
@pindex tftopl@r{, checking validity font}
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 @code{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.

@item
@cindex error messages, spurious
@cindex spurious error messages
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.

@item
@cindex error messages, missing
If a program does not give an error message for invalid input, that is a bug.

@end itemize


@node Bug reporting
@section Bug reporting

@cindex bugs, reporting
@cindex compilation bugs, reporting
@cindex installation bugs, 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!

@menu
* 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.
@end menu


@node Necessary information
@subsection 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.  @xref{Problems}.

You should include all of the following in your bug report:

@itemize @bullet

@item
The version number of the program.  You can get this from the top-level
files @file{ChangeLog} or @file{GNUmakefile.in}, or from the
@samp{-version} option which all the programs have.

@item
The type of machine you are using, and the operating system name
and version number.

@item
A description of the bug.  For example, ``The program gets a fatal
signal,'' or ``The baselines in the generated font are too high.''

@item
All the command-line arguments you gave the program.

@item
The relevant input files.  Since fonts and images are typically binary
files, be sure to use @file{uuencode} or @file{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 @samp{-verbose} option.  It
should then be straightforward to cut that single character out of the
font with either the @samp{-range} option and/or the @samp{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!

@end itemize

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!


@node Unnecessary information
@subsection Unnecessary information

Here are some things that are not necessary to include in a bug report.

@itemize @bullet

@item
@cindex envelope of bugs
@cindex bugs, envelope of
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.

@item
@cindex patches for bugs
@cindex bugs, sending patches for
@cindex sending patches for bugs
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.

@xref{Sending Patches, , Sending Patches for GNU CC, gcc, GCC Manual},
for more details on the best way to write changes.

@item
@cindex bugs, sending backtraces for
@cindex backtraces, sending for bugs
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.

@item
@cindex bugs, guesses about cause
@cindex guesses about bugs
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!

@end itemize


@node Documentation bugs
@subsection Documentation bugs

@cindex manual bugs, reporting
@cindex documentation bugs, reporting

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 @var{x}; I
looked in the manual in sections @var{a} and @var{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).