   Copyright (C) 1993 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

Overview
********

   This manual documents `send-pr', which uses electronic mail to
submit support questions and software bugs to a central site.  No piece
of software is perfect, and software organizations understand this;
`send-pr' is designed to allow users who have problems to submit
reports of these problems to sites responsible for supporting the
software in question, in a defined form which can be read by an
electronically managed database.

   `send-pr' is part of a suite of programs known collectively as
`GNATS', the GNU Problem Report Management System.  `GNATS' consists of
several programs which, used in concert, formulate and partially
administer a database of Problem Reports, or "PRs", at a central
support site.  A PR goes through several states in its lifetime; `GNATS'
tracks the PR and all information associated with it through each state
and finally acts as an archive for PRs which have been "closed".

   Because `send-pr' exists as a shell script and as an `elisp' file
for use within GNU Emacs, it is quite portable.  It can be used from
any machine on your network which can run a shell script and/or Emacs.

   Throughout this manual, the personal pronouns "you" and "your" refer
to the originator of the Problem Report.

   The `GNATS' utility suite is currently at version 3.00.

An introduction to `send-pr'
****************************

   `GNATS' uses electronic mail to begin processing reported problems
and support requests.  It also automatically forwards the report to
those responsible for the problem in question, and returns mail
acknowledging that the Problem Report ("PR") was received.

   All PRs should follow a specific format in order for `GNATS' to
handle them properly.  The easiest way to avoid format problems when
submitting bugs is to use the `send-pr' utility.  `send-pr' invokes an
editor on a default Problem Report template, attempting to
automatically fill in some fields with predefined values.  You then
complete the form with relevant information.  `send-pr' takes over once
you quit the editor, and electronically mails the completed PR using
your local `mail' program.  When a Problem Report is received by `GNATS'
at the support site, its state is considered to be "open".

   In general, you can use any editor and mailer to submit valid Problem
Reports, as long as the format required by `GNATS' is preserved.
`send-pr' automates the process, however, and ensures that certain
fields necessary for automatic processing are present.  `send-pr' is
strongly recommended for all initial problem-oriented correspondence
with your support site.  The organization you submit Problem Reports to
will supply an address to which further information can be sent; the
person responsible for the category of the problem you report will
probably contact you direcly.

The Life of a Problem Report
============================

   Each PR goes through a defined series of states between origination
and closure, and is considered "active" until it has been resolved or
otherwise explicitly "closed".  As the originator of a PR, you are
automatically notified of any state changes that occur as long as your
email address in the mail header is correct.

"open"
     This is the initial state of a Problem Report.  This means the PR
     has been filed and the responsible person(s) notified.

"analyzed"
     The bug has been analyzed by the responsible person.  The analysis
     should contain a preliminary evaluation of the problem and an
     estimate of the amount of time and resources necessary to solve
     the problem.  It should also suggest possible workarounds.

"suspended"
     Work on the problem has been postponed.  This happens if a timely
     solution is not possible or is not cost-effective at the present
     time.  The PR continues to exist, though a solution is not being
     actively sought.  If the problem cannot be solved at all, it
     should be closed rather than suspended.

"feedback"
     This state indicates that the problem has been solved, and you've
     been given a patch or other fix.  The PR remains in this state
     until you acknowledge that the solution works.

"closed"
     A Problem Report is closed only when any changes to the software in
     question have been documented, integrated and tested, and you've
     confirmed the solution.

Problem Report format
=====================

   The format of a PR is designed to reflect the nature of `GNATS' as a
database; information is arranged into fields.  A "PR" can be
considered a record that is electronically entered into the `GNATS'
database.  Thus, the level a PR adheres to the standard format
determines the level of interaction that is required by a database
administrator to route the information to the proper place.  (Hint: Keep
in mind that anything that requires human interaction also requires time
that might be better spent in actually fixing the bug.  It is therefore
in the best interest of all parties involved that the information
contained in a PR be as correct as possible at the time of submission.)

   The PR form has two main sections, the "mail header" and the
"problem report".  Each has fields that must contain entries before the
PR can be considered complete.

Mail Header fields
------------------

   A Problem Report may contain any mail header field described in the
Internet standard RFC-822.  However, only the fields which identify the
sender and the subject are required for `send-pr' to function properly:

`To:'
     Automatically supplied by `send-pr'.  It is the preconfigured mail
     address for the support site where the PR is sent.

`Subject:'
     Complete this field with a terse description of the problem.

`From:'
     Usually supplied automatically by your mailer; should contain your
     electronic mail address.

`Reply-To:'
     A return address to which electronic replies can be sent.  In most
     cases, this is probably the same address as the `From:' field.

Problem Report fields
---------------------

   These fields should comprise the only text in the body of the
message in order to avoid confusion.

   Problem Report fields begin with a keyword enclosed with `>' and
`:', and belong to one of three data types:

ENUMERATED
     One value out of a specific set of choices.  The value must be on
     the same line as the keyword.  For each ENUMERATED keyword, the
     possible choices are listed in the template as a comment.

STRING
     One single line of text which must begin and end on the same line
     as the keyword.

TEXT
     Text of any length may occur in this field.  TEXT may span multiple
     lines and may also include blank lines.  A TEXT field ends only
     when another keyword appears.

   The level of completeness and correctness in the following fields
when the PR is submitted helps determine the speed and quality of the
solution to the problem.

`>Submitter-Id:'
     (ENUMERATED) A unique identification code assigned by your support
     site.  It is used to identify all Problem Reports coming from a
     particular site.  (If you don't have an identification code,
     please use `send-pr --request-id' to apply for one from your
     support organization.  Problem Reports from those not affiliated
     with the support organization should use the default value of
     `net' for this field.)

`>Originator:'
     (STRING) Your real name.  The default is the value of the
     environment variable `NAME'.

`>Organization:'
     (TEXT) The address of your organization.  The default value is the
     contents of the environment variable `ORGANIZATION', or the
     contents of the file `.signature' in your home directory if
     `ORGANIZATION' isn't set.

`>Confidential:'
     (ENUMERATED) Use of this field depends on your relationship with
     the support organization; contractual agreements often have
     provisions for preserving confidentiality.  Conversely, a lack of
     a contract often means that any data you provide will not be
     considered confidential.  Contact the support organization
     directly if this is an issue.

     If your relationship to the support organization provides for
     confidentiality, then if the value of this field is `yes' the
     support organization treats your PR as confidential; any code
     samples you provide are not made publicly available (e.g., in
     regression test suites).  The default value is `yes'.

`>Synopsis:'
     (STRING) One-line summary of the problem.

`>Severity:'
     (ENUMERATED) The severity of the problem.  Accepted values are:

    `critical'
          The product, component or concept is completely
          non-operational or some essential functionality is missing.
          No workaround is known.

    `serious'
          The product, component or concept is not working properly or
          significant functionality is missing.  Problems that would
          otherwise be considered `critical' are rated `serious' when a
          workaround is known.

    `non-critical'
          The product, component or concept is working in general, but
          lacks features, has irritating behaviour, does something
          wrong, or doesn't match its documentation.  The default value
     is `serious'.

`>Priority:'
     (ENUMERATED) How soon a solution is required.  Accepted values are:

    `high'
          A solution is needed as soon as possible.

    `medium'
          The problem should be solved in the next release of the
          software.

    `low'
          The problem should be solved in a future release.

     The default value is `medium'.

`>Category:'
     (ENUMERATED) The name of the product, component or concept where
     the problem lies.  Your support organization provides a list of
     valid categories.  Try `send-pr -L' to see the listing provided
     with your distribution.  For an example list, see Valid Categories.

`>Class:'
     (ENUMERATED) The class of a problem can be one of the following:

    `support'
          A support problem or question.

    `sw-bug'
          A software bug.

    `doc-bug'
          A bug in the documentation.

    `change-request'
          A request for a change in behavior, etc.

    `duplicate (PR-NUMBER)'
          Duplicate PR.  PR-NUMBER should be the number of the original
          PR.

     The default is `sw-bug'.

`>Release:'
     (STRING) Release number or version of the product, component or
     concept.

`>Environment:'
     (TEXT) Description of the environment where the problem occured:
     machine architecture, operating system, host and target types,
     libraries, pathnames, etc.

`>Description:'
     (TEXT) Precise description of the problem, including all
     preconditions, inputs, outputs, conditions after the problem, and
     symptoms.  Please feel free to provide any additional information
     you think is important.  Include all the details that would be
     necessary for someone else to recreate the problem you're
     submitting, however obvious.  Sometimes seemingly arbitrary or
     obvious information can point the way toward a solution.  See
     Helpful hints, for the types of information to include.

`>How-To-Repeat:'
     (TEXT) Example code, input, or activities to reproduce the problem.
     The support organization uses your example code both to reproduce
     the problem and to test whether the problem is fixed.  Again, see
     Helpful hints, for helpful hints.

Editing and sending PRs
***********************

   Invoking `send-pr' presents a partially completed template with a
number of fields already filled in.  Complete the template as fully as
possible to make a useful bug report.  Submit only one bug with each PR.

   A template consists of three sections:

"Comments"
     The top several lines of a blank template consist of a series of
     comments that provide some basic information about completing the
     Problem Report, as well as a list of valid entries for the
     `>Category:' field.  These comments are all preceded by the string
     `SEND-PR:' and are erased automatically when the PR is submitted.
     Note that the instructional comments within `<' and `>' are also
     removed.  (Only these comments are removed; lines you provide that
     happen to have those characters in them, such as examples of
     shell-level redirection, are not affected.)

"Mail Header"
     A standard mail header is provided.  All fields except the
     `Subject:' line are filled with default values.

"`send-pr' Fields"
     These are the informational fields that `GNATS' uses to route your
     Problem Report to the responsible party for further action.  They
     should be filled out as completely as possible.

An example template and complete Problem Report are provided in
An Example.

   The default template contains your preconfigured `>Submitter-Id:'.
When you invoke `send-pr', it attempts to determine values for the
`>Originator:' and `>Organization:' fields (see Problem Report fields.).
`send-pr' also attempts to find out some information about
your system and architecture, and places this information in the
`>Environment:' field if it finds any.

   `send-pr' also provides the mail header section of the template with
default values in the `To:', `From:', and `Reply-To:' fields.  The
`Subject:' field is empty.

   Above the main part of the template is a comment section, beginning
with the messages:

     SEND-PR: -*- text  -*-
     SEND-PR: Lines starting with `SEND-PR' will be removed
     SEND-PR: automatically as well as all comments (the text
     SEND-PR: below enclosed in `<' and `>').
     SEND-PR:
     SEND-PR: Please consult the document `Reporting Problems
     SEND-PR: With send-pr' if you are not sure how to fill out
     SEND-PR: a problem report.
     SEND-PR:
     SEND-PR: Choose from the following categories:

and also containing a list of valid `>Category:' values.  One (and only
one) of these values should be placed in the `>Category:' field.  A
complete sample bug report, from template to completed PR, is shown in
An Example.  See Valid Categories, for a
sample list of categories, or for a complete list type `send-pr -L' at
your prompt.

   The mail header is just below the comment section.  Fill out the
`Subject:' field.  The `To:' field will contain a default value if you
neglected to specify a SITE when invoking `send-pr'.

     To: SUPPORT-SITE
     Subject: *complete this field*
     From: YOUR-LOGIN@YOUR-SITE
     Reply-To: YOUR-LOGIN@YOUR-SITE
     X-send-pr-version: send-pr 3.00

where SUPPORT-SITE is an alias for the support site you wish to submit
this PR to.

   The rest of the template contains `GNATS' fields.  Each field is
either completed with valid information (such as your `>Submitter-Id:')
or contains a one-line instruction specifying the information that
field needs in order to be correct.  For example, the `>Confidential:'
field expects a value of `yes' or `no', and the answer must fit on one
line; similarly, the `>Synopsis:' field expects a short synopsis of the
problem, which must also fit on one line.  Fill out the fields as
completely as possible.

     >Submitter-Id:   SUBMITTER-ID
     >Originator:    YOUR NAME HERE
     >Organization:
     YOUR SITE HERE
     >Confidential:<[ yes | no ] (one line)>
     >Synopsis:    <synopsis of the problem (one line)>
     >Severity:    <[ non-critical | serious | critical ] (one line)>
     >Priority:    <[ low | medium | high ] (one line)>
     >Category:    <name of the product (one line)>
     >Class:       <[sw-bug|doc-bug|change-request|support](one line)>
     >Release:     <release number or tag (one line)>
     >Environment:
              <machine, os, target, libraries (multiple lines)>

     >Description:
            <precise description of the problem (multiple lines)>
     >How-To-Repeat:
            <code/input/activities to reproduce (multiple lines)>

   When you're finished editing the Problem Report, `send-pr' sends the
completed PR to the address named in the `To:' field in the mail
header.  `send-pr' checks that the complete form contains a valid
`>Submitter-Id:' and a valid `>Category:'.  Your copy of `send-pr'
should have already been customized on installation to reflect your
`>Submitter-Id:' (see Installing `send-pr' on your system).
If you don't know your `>Submitter-Id:' value, you can
request it using `send-pr --request-id'.  If your organization is not
affiliated with the site you send Problem Reports to, a good generic
`>Submitter-Id:' to use is `net'.

   A PR which has a `>Submitter-Id:' equal to `unknown' or which has an
invalid `>Category:' is left in a temporary file named `/tmp/pbadNNNN'
on your machine, where NNNN is replaced by the process id given to your
current `send-pr' session.  An error message is generated specifying
the exact name of the bad file.  You can then edit this file and
resubmit it with

     send-pr -f FILENAME

   Invoke `send-pr' from a shell prompt or from within GNU Emacs using
`M-x send-pr'.

Invoking `send-pr' from the shell
=================================

     send-pr [ SITE ][ -f PROBLEM-REPORT ] [ -t MAIL-ADDRESS ]
             [ -L ] [ -p ] [ -P ] [ --request-id ] [ -V ]

   SITE is an alias on your local machine which points to an address
used by a support site.  If this argument is not present, the default
SITE is usually the site which you received `send-pr' from, or your
local site if you use `GNATS' locally.  (see Setting a default SITE.)

   Invoking `send-pr' with no options calls the editor named in your
environment variable `EDITOR'.  If the environment variable `PR_FORM'
is set, its value is used as a file name which contains a valid
template.  If `PR_FORM' contains a missing or unreadable file, or if
the file is empty, `send-pr' generates an error message and opens the
editor on a default template.

`-f PROBLEM-REPORT'
     Use this option to specify a file, PROBLEM-REPORT, where a
     completed Problem Report already exists.  `send-pr' sends the
     contents of the file without invoking an editor.  (If
     PROBLEM-REPORT is `-', `send-pr' reads from the standard input;
     `send-pr' uses this feature internally.)

`-t MAIL-ADDRESS'
     Sets the electronic mail address to receive the PR.  The default is
     preset when `send-pr' is configured.  This option is not
     recommended; instead, use the argument SITE on the command line.

`-L'
     This prints the list of valid `>Category:' values on standard
     output.  No mail is sent.

`-p'
     Prints the standard blank template on the standard output.  You can
     print this blank form and use it to generate forms to FAX or
     physically mail to the support site if electronic mail fails to get
     through.  You can also complete some default fields, such as your
     organization's name in the `>Organization:' field, your
     `Submitter-Id:', and details about your machine's architecture in
     the `>Environment:' field, and use it as a custom form.  Specify
     `send-pr' to use this custom form by setting your environment
     variable `PR_FORM' to the name of the customized file.  No mail is
     sent when you use this option.

`-P'
     Prints out the template specified by the variable `PR_FORM' in your
     environment.  If `PR_FORM' is not set, the standard blank form is
     printed.  If the file specified by `PR_FORM' doesn't exist, an
     error message is printed.  No mail is sent.

`--request-id'
     Specifying this option sends a request for a `>Submitter-Id:' to
     the support site (or to the mail address specified either with the
     `-t' option or in the `To:' field in the mail header).

`-V'
`--version'
     Displays the `send-pr' version number and a usage summary.  No mail
     is sent.

Using `send-pr' from within Emacs
=================================

   You can use an interactive `send-pr' interface from within GNU Emacs
to fill out your Problem Report.  We recommend that you familiarize
yourself with Emacs before using this feature (see Introduction (emacs)).

   The interface is called with `M-x send-pr'.  The interactive
interface prompts you for input for certain fields and then places you
in an Emacs buffer so you can complete the fields specific to your
problem.  It also sets up a few extra key bindings for ease of use.

   To start the interactive `send-pr', type

     M-x send-pr

from inside Emacs.  Emacs responds with a template specifying your
preconfigured template as described above.  You may also submit problem
reports to support sites different from the default site.  To use this
feature, invoke `send-pr' with

     C-u SITE M-x send-pr

   *Note:* if typing `M-x send-pr' doesn't work, see your system
administrator for help in loading `send-pr' in Emacs.  In short, any
users who wish to use the Emacs version of `send-pr' must place the
following line in their `.emacs' files:

     (autoload 'send-pr "send-pr" "Submit a Problem Report." t)

For more details on installing `send-pr', see Installing `send-pr' on your system.

   If you are using `M-x send-pr', you are prompted in the minibuffer
with the line:
     >Category: other

Delete the default value `other' and replace it with the keyword
corresponding to your problem.  For example, if the problem you're
reporting has to do with the GNU C compiler, and your support
organization accepts bugs submitted for this program under the category
`gcc', delete `other' *in the minibuffer* and then type `gcc [RET]'.
Emacs replaces the
     >Category:       <name of the product (one line)>

line in the template with
     >Category:       gcc

and moves on to another field.

   The `M-x send-pr' function provides completion as well; in the above
example you can also type `gc[TAB]', and Emacs will try to complete the
entry for you.  Note that typing `g[TAB]' may not have the same effect
if there are several possible entries beginning with `g'.  In that case
Emacs will not be able to complete the entry because it can not know
whether you meant `gcc' or, say, `gas', if both of those are possible
categories.  `M-x send-pr' continues to prompt you for a valid entry
until you enter one.

   `M-x send-pr' prompts you interactively to enter each field for
which there is a range of specific choices.  If you attempt to enter a
value which is not in the range of acceptable entries, Emacs responds
with `[No match]' and allows you to change the entry until it contains
an acceptable value.  This is an excellent way both to avoid unusable
information (at least in these enumerated fields) and also to avoid
typographical errors which could cause problems later.

   The interactive mode prompts you for the following fields:

`>Category:'
`>Confidential: (DEFAULT=`yes')'
`>Severity: (DEFAULT=`serious')'
`>Priority: (DEFAULT=`medium')'
`>Class: (DEFAULT=`sw-bug')'
`>Release:'
   After you complete these fields, `M-x send-pr' places the cursor in
the `Subject:' line of the mail header and displays the message
     To send the problem report use: C-c C-c

in the minibuffer.  At this point, edit the file in the main buffer to
reflect your specific problem, putting relevant information in the
proper fields.  See An Example, for a sample Problem Report.

   `M-x send-pr' provides a few key bindings to make it simpler to move
around in a template buffer.

`M-p'
`M-x gnats-previous-field'
     moves the cursor to the beginning of the previous field

`M-n'
`M-x gnats-next-field'
     moves the cursor to the beginning of the next field

`M-C-b'
`M-x gnats-backward-field'
     moves the cursor to the end of the previous field

`M-C-f'
`M-x gnats-forward-field'
     moves the cursor to the end of the next field

   `send-pr' takes over again when you type `C-c C-c' to send the
message.  Any errors are reported in a separate window.  This window
remains active until you send the PR properly (or, of course, until you
explicitly kill the window).

   For detailed instructions for using Emacs, see Introduction (emacs).

Installing `send-pr' on your system
***********************************

   If you receive `send-pr' as part of a larger software distribution,
it will most likely be automatically installed when the full
distribution is installed.  If you are using `GNATS' at your site as
well, you must decide where `send-pr' is to send bug reports by
default; see Setting a default SITE.

Installing `send-pr' by itself
==============================

   The `send-pr' directory, is easily installed by itself by following
these steps (you may need `root' access in order to change the
`aliases' file and to install `send-pr'):

  1. *Unpack the distribution* into a directory which we will refer to
     as SRCDIR.

  2. *Edit the `Makefile' to reflect local conventions.*
     Specifically, you should edit the variable `prefix' to alter the
     installation location.  The default is `/usr/local'.  All files are
     installed under `prefix' (see below).

  3. *Run*
          make all install [ info ] install-info [ clean ]

     The targets mean the following:

    `all'
          Builds `send-pr' and `install-sid'

    `install'
          Installs the following:

         `install-sid'
         `send-pr'
               into `PREFIX/bin'

         `send-pr.1'
               into `PREFIX/man/man1'

         `SITE'
               the list of valid CATEGORIES for the support site you
               received `send-pr' from, installed as
               `PREFIX/lib/gnats/SITE'

         `send-pr.el'
               into `PREFIX/lib/emacs/lisp'

    `info (*optional*)'
          Builds `send-pr.info' from `send-pr.texi'
          (`send-pr.info' is included with this distribution)

    `install-info'
          Installs `send-pr.info' into `PREFIX/info'

    `clean (*optional*)'
          Removes all intermediary build files that can be rebuilt from
          source code

  4. *Run*
          install-sid YOUR-SID

     where YOUR-SID is the identification code you received with
     `send-pr'.  `send-pr' will automatically insert this value into
     the template field `>Submitter-Id'.  If you've downloaded
     `send-pr' from the Net, use `net' for this value.

  5. *Any users who wish to use the Emacs version of `send-pr'* must
     place the following line in their `.emacs' files:

          (autoload 'send-pr "send-pr" "Submit a Problem Report." t)

  6. *Create a mail alias* for the support site you received `send-pr'
     from, and for every site with which you wish to use `send-pr' to
     communicate, each with a suffix of `-gnats'.  The support site(s)
     will provide the correct addresses toward which these aliases
     should point.  For instance, edit your mail aliases file to
     contain something like:

          # support sites; for use with send-pr
          cygnus-gnats:     bugs@cygnus.com            # Cygnus Support
          bumblebee-gnats:  bumblebugs@bumblebee.com   # Bumblebee Inc.
          mycompany-gnats:  bugs@my.company.com (*if you use `GNATS' locally*)

     `send-pr' automatically searches for these aliases when you type

          send-pr cygnus
          send-pr bumblebee
          send-pr SITE...

     `send-pr' also uses SITE to determine the categories of bugs the
     site in question accepts by looking in

          PREFIX/lib/gnats/SITE

Setting a default SITE
======================

   `send-pr' is capable of sending bug reports to any number of support
sites via mail aliases which have `-gnats' appended them.  `send-pr'
automatically appends the suffix, so that when you type

     send-pr SITE

the bug report will go to the address noted in the `aliases' file as
`SITE-gnats'.  This is done in the Emacs version of `send-pr' by
invoking the program with

     C-u SITE M-x send-pr

This value is also used to error-check the `>Category:' field, as a
precaution against sending mistaken information (and against sending
information to the wrong site).

   You may also simply type

     send-pr

from the shell (or simply "`M-x send-pr'" in Emacs), and the problem
report you generate will be sent to the "default" site, which is
usually the site from which you received your distribution of
`send-pr'.  If you use `GNATS' at your own organization, the default is
your local bug-reporting address.

   To change this, simply edit the file `Makefile' before installing
and change the line

     GNATS_SITE = SITE

to reflect the site you wish to send PRs to by default.  Again,
`send-pr' automatically appends the `-gnats' to the SITE given on the
command line.

Helpful hints
*************

   There is no orthodox standard for submitting effective bug reports,
though you might do well to consult the section on submitting bugs for
GNU `gcc' in Reporting Bugs (gcc), by Richard Stallman, for
information that can typically be useful as well as mistakes to avoid.

   In general, common sense (assuming such an animal exists) dictates
the kind of information that would be most helpful in tracking down and
resolving problems in software.
   * Include anything *you* would want to know if you were looking at
     the report from the other end.  There's no need to include every
     minute detail about your environment (users have been known to
     provide the values of every variable in their environments),
     although anything that might be different from someone else's
     environment should be included (your path, for instance).

   * Narratives are often useful, given a certain degree of restraint.
     If a person responsible for a bug can see that A was executed, and
     then B and then C, knowing that sequence of events might trigger
     the finding of an intermediate step that was missing, or an extra
     step that might have changed the environment enough to cause a
     visible problem.  Again, restraint is always in order ("I set the
     build running, went to get a cup of coffee (Columbian, cream but
     no sugar), talked to Sheila on the phone, and then THIS
     happened...") but be sure to include anything relevant.

   * Richard Stallman writes, "The fundamental principle of reporting
     bugs usefully is this: *report all the facts*.  If you are not sure
     whether to state a fact or leave it out, state it!"  This holds
     true across all problem reporting systems, for computer software
     or social injustice or motorcycle maintenance.  It is especially
     important in the software field due to the major differences
     seemingly insignificant changes can make (a changed variable, a
     missing semicolon).

   * Submit only *one* problem with each Problem Report.  If you have
     multiple problems, use multiple PRs.  This aids in tracking each
     problem and also in analyzing the problems associated with a given
     program.

   * It never hurts to do a little research to find out if the bug
     you've found has already been reported.  Most software releases
     will have lists of known bugs in the Release Notes which should
     have come with the software; see your system administrator if you
     don't have a copy of these.

An Example
**********

   Cygnus Support in Mountain View, CA, is a heavy user of `GNATS' and
`send-pr'.  As a support company, Cygnus finds problem tracking to be a
crucial part of everyday business.  Cygnus mainly supports the GNU
compiling tools, including `GNATS' and `send-pr', over several Un*x and
Un*x-like platforms, and is an example of `GNATS' in action.

   With each shipment of the Cygnus Developer's Toolkit, customers
receive the latest version of `send-pr', which contains an up-to-date
listing of valid categories (values for the `>Category:' field).  Using
these tools, Cygnus' customers can communicate their problems to Cygnus
effectively and receive automatic confirmation of receipt as well as
notification of changes in the status of their reported problems.  Much
of Cygnus' support mechanism relies on electronic mail.

   As an example, let's pretend we're a customer of Cygnus Support, and
that we're having a problem with some of our software.

   Assume that we're getting an error in our bifrabulator program
wherein the prestidigitation routines don't match with the
whatsitsname.  We've made sure we're following the rules of the program
and checked the Release Notes from Cygnus and found that the bug isn't
already known.  In other words, we're pretty sure we've found a bug.

   Our first step is to call `send-pr'.  It really doesn't matter
whether we use `send-pr' from the shell or from within Emacs.  Indeed,
if we use Emacs as a primary editor, calling `send-pr' from the shell
is likely to start `send-pr' in an Emacs buffer anyway.  So, since our
company, *Imaginary Software, Ltd.*, is a heavy user of GNU software,
we're pretty familiar with Emacs, so from within Emacs we type
     M-x send-pr

and we're greeted with the following screen:

     SEND-PR: -*- text  -*-
     SEND-PR: Lines starting with `SEND-PR' will be removed
     SEND-PR: automatically as well as all comments (the text
     SEND-PR: below enclosed in `<' and `>').
     SEND-PR: Please consult the manual if you are not sure
     SEND-PR: how to fill out a problem report.
     SEND-PR:
     SEND-PR: Choose from the following categories:
     SEND-PR:
     SEND-PR:           bfd       binutils  bison
     SEND-PR: byacc     clib      config    cvs         diff
     SEND-PR: doc       emacs     flex      g++         gas
     SEND-PR: gcc       gdb       glob      gprof       grep
     SEND-PR: info      ispell    kerberos  ld          libg++
     SEND-PR: libiberty make      makeinfo  mas         newlib
     SEND-PR: other     patch     rcs       readline    send-pr
     SEND-PR: test      texindex  texinfo   texinfo.tex
     SEND-PR: bifrabulator  <---*note: this one is fake*
     SEND-PR:
     To: cygnus-bugs@cygnus.com
     Subject:
     From: jeffrey@imaginary.com
     Reply-To: jeffrey@imaginary.com
     X-send-pr-version: send-pr 3.00

     >Submitter-Id:  imaginary
     >Originator:    Jeffrey Osier
     >Organization:
     Imaginary Software, Ltd.
     >Confidential:  <[ yes | no ] (one line)>
     >Synopsis:      <synopsis of the problem (one line)>
     >Severity:      <[ non-critical | serious | critical ] (one line)>
     >Priority:      <[ low | medium | high ] (one line)>
     >Category:      <name of the product (one line)>
     >Class:         <[sw-bug|doc-bug|change-request|support](oneline)>
     >Release:       <release number or tag (one line)>
     >Environment:
              <machine, os, target, libraries (multiple lines)>
     System: SunOS imaginary.com 4.1.1 1 sun4
     Architecture: sun4

     >Description:
            <precise description of the problem (multiple lines)>
     >How-To-Repeat:
            <code/input/activities to reproduce (multiple lines)>

     -----Emacs: *send-pr*   (send-pr Fill)----All------------------
     >Category: other[]

   We know from past experience that we need to set certain information
into each field, so we compile all the information we know about our
problem.  We have some sample code which we know should work, even
though it doesn't, so we'll include that.  Below is the completed PR;
we send this using `C-c C-c'.  (The comments have been truncated).

     SEND-PR: Lines starting with `SEND-PR' will be removed
     SEND-PR: automatically as well as all comments (the text
     SEND-PR: ...
     SEND-PR:
     To: cygnus-bugs@cygnus.com
     Subject: bifrabulator routines don't match
     From: jeffrey@imaginary.com
     Reply-To: jeffrey@imaginary.com
     X-send-pr-version: send-pr 3.00

     >Submitter-Id:  imaginary
     >Originator:    Jeffrey Osier
     >Organization:
     Imaginary Software, Ltd.
     >Confidential:  no
     >Synopsis:      bifrabulator routines don't match
     >Severity:      serious
     >Priority:      medium
     >Category:      bifrabulator
     >Class:         sw-bug
     >Release:       progressive-930101
     >Environment:
     System: SunOS imaginary.com 4.1.1 1 sun4
     Architecture: sun4 (SPARC)

     >Description:
        the following code I fed into the bifrabulator came back
        with a strange error.  apparently, the prestidigitation
        routine doesn't match with the whatsitsname in all cases.

     >How-To-Repeat:
        call the bifrabulator on the following code.
        CODE SAMPLE...

     -----Emacs: *send-pr*   (send-pr Fill)----All------------------
     To send the problem report use: C-c C-c

   We type `C-c C-c', and off it goes.  Now, we depend on Cygnus
Support to figure out the answer to our problem.

   Soon afterward, we get the following message from Cygnus:

     From: gnats (GNATS management)
     Sender: gnats-admin
     Reply-To: hacker@cygnus.com
     To: jeffrey@imaginary.com
     Subject: Re: bifrabulator/1425: routines don't match

     Thank you very much for your problem report.
     It has the internal identification: g++/1425.
     The individual assigned to look at your bug is:  hacker
     (F.B. Hacker)

     Category: bifrabulator
     Responsible: hacker
     Synopsis: bifrabulator routines don't match
     Arrival-Date: Sat Feb 30 03:12:55 1993

This is our "receipt" that the bug has been accepted and forwarded to
the responsible party.

A while later, we get the analysis:

     To:  jeffrey@imaginary.com
     From:  hacker@cygnus.com
     Subject:  Re: bifrabulator/1425: routines don't match
     Reply-To: hacker@cygnus.com

     Got your message, Jeff.  It seems that the bifrabulator was
     confusing the prestidigitation routines with the realitychecker
     when lexically parsing the whatsitsname.

     I'm working on robustisizing the bifrabulator now.

     How about lunch next week?
     --
     F.B. Hacker
     Cygnus Support, Mountain View, CA  415 903 1400
     #include <std-disclaimer.h>

About the same time, we get another message from Cygnus.

     From: hacker@cygnus.com
     To:  jeffrey@imaginary.com
     Subject:  Re: bifrabulator/1425: doesn't match prestidig
     Reply-To:  hacker@cygnus.com

                  `F.B. Hacker' changed the state to `analyzed'.

     State-Changed-From-To: open-analyzed
     State-Changed-By: hacker
     State-Changed-When: Fri Feb 31 1993 08:59:16 1993
     State-Changed-Why:
         figured out the problem, working on a patch this afternoon
     --
     F.B. Hacker
     Cygnus Support, Mountain View, CA  415 903 1400
     #include <std-disclaimer.h>

The bug has now been analyzed, and Cygnus is working on a solution.
Sometime later, we get more mail from F.B.:

     To:  jeffrey@imaginary.com
     From:  hacker@cygnus.com
     Subject:  Re: bifrabulator/1425: routines don't match
     Reply-To: hacker@cygnus.com

     There's a patch now that you can ftp over and check out.

     Hey, that joke you sent me was great!  The one about the
     strings walking into a bar...  my boss laughed for an hour!
     --
     F.B. Hacker
     Cygnus Support, Mountain View, CA  415 903 1400
     #include <std-disclaimer.h>

     From: hacker@cygnus.com
     To:  jeffrey@imaginary.com
     Subject:  Re: bifrabulator/1425: doesn't match prestidig
     Reply-To:  hacker@cygnus.com

                  `F.B. Hacker' changed the state to `feedback'.

     State-Changed-From-To: analyzed-feedback
     State-Changed-By: hacker
     State-Changed-When: Fri Feb 31 1993 23:43:16 1993
     State-Changed-Why:
         got the patch finished, notified Jeff at Imaginary Software
     --
     F.B. Hacker
     Cygnus Support, Mountain View, CA  415 903 1400
     #include <std-disclaimer.h>

The bug has gone into "feedback" status now, until we get the patch,
install it and test it.  When everything tests well, we can mail F.B.
back and tell him the bug's been fixed, and he can change the state of
the PR from "feedback" to "closed".

   Following is a list of valid `>Category:' entries that are supported
by Cygnus.

Valid Categories
================

`bfd'
     GNU binary file descriptor library.

`bifrabulator'
     This one doesn't actually exist.

`binutils'
     GNU utilities for binary files (`ar', `nm', `size'...).

`bison'
     GNU parser generator.

`byacc'
     Free parser generator.

`config'
     Cygnus Support Software configuration and installation.

`cvs'
     Concurrent Version System.

`diff'
     GNU `diff' program.

`doc'
     Documentation and manuals.

`emacs'
     GNU Emacs editor and related functions.

`flex'
     GNU lexical analyzer.

`g++'
     GNU C++ compiler.

`gas'
     GNU assembler.

`gcc'
     GNU C compiler.

`gdb'
     GNU source code debugger.

`glob'
     The filename globbing functions.

`gprof'
     GNU profiler.

`grep'
     GNU `grep' program.

`info'
     GNU `info' hypertext reader.

`ispell'
     GNU spelling checker.

`kerberos'
     Kerberos authentication system.

`ld'
     GNU linker.

`libc'
     Cygnus Support C Support Library.

`libg++'
     GNU C++ class library.

`libiberty'
     GNU `libiberty' library.

`libm'
     Cygnus Support C Math Library.

`make'
     GNU `make' program.

`makeinfo'
     GNU utility to build Info files from Texinfo documents.

`mas'
     GNU Motorola syntax assembler.

`newlib'
     Cygnus Support C Support and Math Libraries.

`patch'
     GNU bug patch program.

`gnats'
     GNU Problem Report Management System.

`rcs'
     Revision Control System.

`readline'
     GNU `readline' library.

`send-pr'
     GNU Problem Report submitting program.

`test'
     Category to use when testing `send-pr'.

`texindex'
     GNU documentation indexing utility.

`texinfo'
     GNU documentation macros.

`other'
     Anything which is not covered by the above categories.