   Copyright (C) 1993, 1995 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 GNATS, the GNU Problem Report Management System,
version 3.101.  GNATS is a bug-tracking tool designed for use at a
central "Support Site".  Users who experience problems use electronic
mail to communicate these problems to "maintainers" at that Support
Site.  GNATS partially automates the tracking of these "Problem Reports"
("PR"s) by:

   * organizing problem reports into a database and notifying
     responsible parties of suspected bugs;

   * allowing support personnel and their managers to edit and query
     accumulated bugs; and

   * providing a reliable archive of problems (and their subsequent
     solutions) with a given program.

   GNATS offers many of the same features offered by more generalized
databases, including editing, querying, and basic reporting.  The GNATS
database itself is an ordered repository for problem reports; each PR
receives a unique, incremental "PR number" which identifies it
throughout its lifetime.  For a discussion on the working system adopted
by GNATS, see The database paradigm.

   You can access the submitting, editing, and querying functions of
GNATS from within GNU Emacs.  See Invoking the GNATS tools.

1 Introducing GNATS
*******************

Any support organization realizes that a large amount of data flows back
and forth between the maintainers and the users of their products.  This
data often takes the form of problem reports and communication via
electronic mail.  GNATS addresses the problem of organizing this
communication by defining a database made up of archived and indexed
electronic mail messages.

   GNATS was designed as a tool for software maintainers.  It consists
of several utilities which, when used in concert, formulate and
administer a database of Problem Reports grouped by site-defined
"problem categories".  It allows a support organization to keep track of
problems (hence the term "Problem Report") in an organized fashion.
Essentially, GNATS acts as an active archive for field-separated textual
data submitted through electronic mail.

1.1 The database paradigm
=========================

It is in your best interest as the maintainer of a body of work to
organize the feedback you receive on that work, and to make it easy for
users of your work to report problems and suggestions.

   GNATS makes this easy by automatically filing incoming problem
reports into appropriate places, by notifying responsible parties of the
existence of the problem and (optionally) sending an acknowledgement to
the submitter that the report was received, and by making these Problem
Reports accessible to queries and easily editable.  GNATS is a database
specialized for a specific task.

   GNATS was designed for use at a Support Site that handles a high
level of problem-related traffic though electronic mail.  It maintains
Problem Reports in the form of text files with defined "fields" (see
GNATS data fields).  The location of the database, as well as
the categories it accepts as valid, the maintainers for whom it provides
service, and the submitters from whom it accepts Problem Reports, are
all definable by the "Support Site".  See GNATS administration.

   Each PR is a separate file within a main repository (see Where GNATS lives).
Editing access to the database is regulated
to maintain consistency, but anyone with electronic mail access may
submit Problem Reports.  To make queries on the database faster, an
index is kept automatically (see The 'index' file).

   We provide several software tools so that users may submit new
Problem Reports, edit existing Problem Reports, and query the database.

   * 'send-pr' is used by both product maintainers and the end users of
     the products they support to submit PRs to the database.

   * 'edit-pr' is used by maintainers to use when editing problem
     reports in the database.

   * Maintainers, managers and administrators can use 'query-pr' to make
     inquiries about indidvidual PRs or groups of PRs.

   'send-pr' can also be packaged by itself and distributed to anyone
you wish to receive Problem Reports from; see Configuring 'send-pr' for the outside world.

   At the Support Site, a GNATS "administrator" is charged with the duty
of maintaining GNATS.  These duties are discussed in detail in
GNATS Administration, and generally include configuring
GNATS for the Support Site, editing PRs that GNATS cannot process,
pruning log files, setting up new problem categories, backing up the
database, and distributing 'send-pr' so that others may submit Problem
Reports.

   Responsibility for a given Problem Report depends on the category of
the problem.  Optionally, an automated reminder can be sent to the
responsible person if a problem report is neglected for a requisite time
period.  See Changing your local configuration.

   GNATS does not have the ability to decipher random text, so any
problem reports which arrive in a format GNATS does not recognize are
placed in a separate directory pending investigation by the GNATS
administrator (see GNATS Administration).

   Once a problem is recorded in the database, work can begin toward a
solution.  A problem's initial "state" is 'open' (see States of Problem Reports).
An acknowledgement is sent to the originator
of the bug report (if that feature of GNATS is activated).  GNATS
forwards copies of the report to the party responsible for that problem
category and to the person responsible for problems arriving from that
"Submitter Site".

   When a problem has been identified, the maintainer can change its
state to 'analyzed', and then to 'feedback' when a solution is found.
Each time the state of a PR changes, the submitter of the problem report
is notified of the reason for the change.  If the party responsible for
the PR changes, the previous responsible party and the new responsible
party receive notice of the change.  The change and reason are also
recorded in the '>Audit-Trail:' field of the Problem Report.  (see
Editing existing Problem Reports.  For information on the
'>Audit-Trail:' field, see Problem Report format)

   When the originator of the Problem Report confirms that the solution
works, the maintainer can change the state to "closed".  If the PR
cannot be closed, the maintainer can change its state to "suspended" as
a last resort.  (For a more detailed description of these states, see
States of Problem Reports)

1.2 Flowchart of GNATS activities
=================================

This informal flowchart shows the relationships of the GNATS tools to
each other and to the files with which they interoperate.

     +===========+    +===========+    +===========+
     # USER SITE #    # USER SITE #    # USER SITE #
     #           #    #           #    #           #
     # *send-pr* #    # *send-pr* #    # *send-pr* #
     +=====|=====+    +=====|=====+    +=====|=====+
           |                V                |
           `--------->    Email....  <-------'
                     ,--->     |
     +===============|=========|===================+
     # SUPPORT SITE  |         `---> /etc/aliases  #
     #          *send-pr*                |         #
     #     +-----------------------------V--------+#
     #     | GNATS         GNATS_ROOT/gnats-queue/|#
     #     |                             |        |#
     #     |        _________            V        |#
     #     |       |*file-pr*|<--- *queue-pr -r*  |#
     #     |       |         |                    |#
     #  _  |       |  valid  |                    |#
     # |M| |       |Category?|N--.                |#
     # |A| |       |_________|   |      GNATS     |#
     # |I| |              Y|     |  ADMINISTRATOR |#
     # |N| |               |     |                |#
     # |T|<----------------|     |                |#
     # |A| |               |     |  .-> *edit-pr* |#
     # |I|--->*edit-pr*-.  |     V  |           | |#
     # |N| |            |  |GNATS_ROOT/pending  | |#
     # |E|<--*query-pr* |  |                    | |#
     # |R| |       |    |  |                    | |#
     # |S| |       |    V  V                    V |#
     # |_| |+------------------------------------+|#
     #     ||         GNATS Database             ||#
     #     ||   GNATS_ROOT/CATEGORY/GNATS-ID     ||#
     #     |+------------------------------------+|#
     #     +--------------------------------------+#
     +=============================================+

1.3 States of Problem Reports
=============================

Each PR goes through a defined series of states between origination and
closure.  The originator of a PR receives notification automatically of
any state changes.

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

"analyzed"
     The responsible person has analyzed the problem.  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.

"feedback"
     The problem has been solved, and the originator has been given a
     patch or other fix.  The PR remains in this state until the
     originator acknowledges that the solution works.

"closed"
     A Problem Report is closed ("the bug stops here") only when any
     changes have been integrated, documented, and tested, and the
     submitter has confirmed the solution.

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

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

The format of a PR is designed to reflect the nature of GNATS as a
database.  Information is arranged into "fields", and kept in individual
records (Problem Reports).

   Problem Report fields are denoted by a keyword which begins with '>'
and ends with ':', as in '>Confidential:'.  Fields belong to one of
three data types:

ENUMERATED
     One of a specific set of values, which vary according to the field.
     The value for each keyword must be on the same line as the keyword.
     These values are not configurable (yet).

     The following fields are ENUMERATED format; see the descriptions of
     fields below for explanations of each field in detail:

          >Confidential:   >Severity:       >Priority:
          >Class:          >State:          >Number:

TEXT
     One single line of text which must begin and end on the same line
     (i.e., before a newline) as the keyword.  See the descriptions of
     fields below for explanations of each field in detail.  The
     following fields are TEXT format:

          >Submitter-Id:   >Originator:     >Synopsis:
          >Category:       >Release:        >Responsible:
          >Arrival-Date:

MULTITEXT
     Text of any length may occur in this field.  MULTITEXT may span
     multiple lines and may also include blank lines.  A MULTITEXT field
     ends only when another keyword appears.  See the descriptions of
     fields below for explanations of each field in detail.

     The following fields are MULTITEXT format:

          >Organization:   >Environment:    >Description:
          >How-To-Repeat:  >Fix:            >Audit-Trail:
          >Unformatted:

   A Problem Report contains two different types of fields: "Mail
Header" fields, which are used by the mail handler for delivery, and
"Problem Report" fields, which contain information relevant to the
Problem Report and its submitter.  A Problem Report is essentially a
specially formatted electronic mail message.

Example Problem Report
----------------------

The following is an example Problem Report.  Mail headers are at the
top, followed by GNATS fields, which begin with '>' and end with ':'.
The 'Subject:' line in the mail header and the '>Synopsis:' field are
usually duplicates of each other.

     Message-Id:  MESSAGE-ID
     Date:        DATE
     From:        ADDRESS
     Reply-To:    ADDRESS
     To:          BUG-ADDRESS
     Subject:     SUBJECT

     >Number:       GNATS-ID
     >Category:     CATEGORY
     >Synopsis:     SYNOPSIS
     >Confidential: yes _or_ no
     >Severity:     critical, serious, _or_ non-critical
     >Priority:     high, medium _or_ low
     >Responsible:  RESPONSIBLE
     >State:        open, analyzed, suspended, feedback, _or_ closed
     >Class:        sw-bug, doc-bug, change-request, support,
     duplicate, _or_ mistaken
     >Submitter-Id: SUBMITTER-ID
     >Arrival-Date: DATE
     >Originator:   NAME
     >Organization: ORGANIZATION
     >Release:      RELEASE
     >Environment:
        ENVIRONMENT
     >Description:
        DESCRIPTION
     >How-To-Repeat:
        HOW-TO-REPEAT
     >Fix:
        FIX
     >Audit-Trail:
     APPENDED-MESSAGES...
     State-Changed-From-To: FROM-TO
     State-Changed-When: DATE
     State-Changed-Why:
        REASON
     Responsible-Changed-From-To: FROM-TO
     Responsible-Changed-When: DATE
     Responsible-Changed-Why:
        REASON
     >Unformatted:
        MISCELLANEOUS

1.4.1 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 by 'send-pr':

'To:'
     The preconfigured mail address for the Support Site where the PR is
     to be sent, automatically supplied by 'send-pr'.

'Subject:'
     A terse description of the problem.  This field normally contains
     the same information as the '>Synopsis:' field.

'From:'
     Usually supplied automatically by the originator's mailer; should
     contain the originator's electronic mail address.

'Reply-To:'
     A return address to which electronic replies can be sent; in most
     cases, the same address as the 'From:' field.

   One of the configurable options for GNATS is whether or not to retain
'Received-By:' headers, which often consume a lot of space and are not
often used.  See Changing your local configuration.

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

Field descriptions
------------------

The following fields are present whenever a PR is submitted via the
program 'send-pr'.  GNATS adds additional fields when the PR arrives at
the Support Site; explanations of these follow this list.

'>Submitter-Id:'
     (TEXT) A unique identification code assigned by the Support Site.
     It is used to identify all Problem Reports coming from a particular
     site.  (Submitters without a value for this field can invoke
     'send-pr' with the '--request-id' option to apply for one from the
     support organization.  Problem Reports from those not affiliated
     with the support organization should use the default value of 'net'
     for this field.)

'>Originator:'
     (TEXT) Originator's real name.  The default is the value of the
     originator's environment variable 'NAME'.

'>Organization:'
     (MULTITEXT) The originator's organization.  The default value is
     set with the variable 'DEFAULT_ORGANIZATION' in the 'config' file
     (see The 'config' file).

'>Confidential:'
     (ENUMERATED) Use of this field depends on the originator's
     relationship with the support organization; contractual agreements
     often have provisions for preserving confidentiality.  Conversely,
     a lack of a contract often means that any data provided will not be
     considered confidential.  Submitters should be advised to contact
     the support organization directly if this is an issue.

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

'>Synopsis:'
     (TEXT) One-line summary of the problem.  'send-pr' copies this
     information to the 'Subject:' line when you submit a Problem
     Report.

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

     '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 behavior, does something wrong,
          or doesn't match its documentation.
     The default value is 'serious'.

'>Priority:'
     (ENUMERATED) How soon the originator requires a solution.  Accepted
     values include:

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

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

     'low'
          The problem should be solved in a future release.
     The default value is 'medium'.

'>Category:'
     (TEXT) The name of the product, component or concept where the
     problem lies.  The values for this field are defined by the Support
     Site.  See The 'categories' file, for details.

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

     'sw-bug'
          A general product problem.  ('sw' stands for "software".)

     'doc-bug'
          A problem with the documentation.

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

     'support'
          A support problem or question.

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

     'mistaken'
          No problem, user error or misunderstanding.  This value is
          valid only at the Support Site.

     The default is 'sw-bug'.

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

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

'>Description:'
     (MULTITEXT) Precise description of the problem.

'>How-To-Repeat:'
     (MULTITEXT) Example code, input, or activities to reproduce the
     problem.  The support organization uses example code both to
     reproduce the problem and to test whether the problem is fixed.
     Include all preconditions, inputs, outputs, conditions after the
     problem, and symptoms.  Any additional important information should
     be included.  Include all the details that would be necessary for
     someone else to recreate the problem reported, however obvious.
     Sometimes seemingly arbitrary or obvious information can point the
     way toward a solution.  See also Helpful hints.

'>Fix:'
     (MULTITEXT) A description of a solution to the problem, or a patch
     which solves the problem.  (This field is most often filled in at
     the Support Site; we provide it to the submitter in case she has
     solved the problem.)

GNATS adds the following fields when the PR arrives at the Support Site:

'>Number:'
     (ENUMERATED) The incremental identification number for this PR.
     This is included in the automated reply to the submitter (if that
     feature of GNATS is activated; see Changing your local configuration).
     It is also included in the
     copy of the PR that is sent to the maintainer.

     The '>Number:' field is often paired with the '>Category:' field as

          CATEGORY/NUMBER

     in subsequent email messages.  This is for historical reasons, as
     well as because Problem Reports are stored in subdirectories which
     are named by category.

'>State:'
     (ENUMERATED) The current state of the PR. Accepted values are:

     'open'
          The PR has been filed and the responsible person notified.

     'analyzed'
          The responsible person has analyzed the problem.

     'feedback'
          The problem has been solved, and the originator has been given
          a patch or other fix.

     'closed'
          The changes have been integrated, documented, and tested, and
          the originator has confirmed that the solution works.

     'suspended'
          Work on the problem has been postponed.

     The initial state of a PR is 'open'.  See States of Problem Reports.

'>Responsible:'
     (TEXT) The person responsible for this category.  GNATS retrieves
     this information from the 'categories' file (see The 'categories' file).

'>Arrival-Date:'
     (TEXT) The time that this PR was received by GNATS.  The date is
     provided automatically by GNATS.

'>Audit-Trail:'
     (MULTITEXT) Tracks related electronic mail as well as changes in
     the '>State:' and '>Responsible:' fields with the sub-fields:

     'State-Changed-<From>-<To>: OLDSTATE>-<NEWSTATE'
          The old and new '>State:' field values.

     'Responsible-Changed-<From>-<To>: OLDRESP>-<NEWRESP'
          The old and new '>Responsible:' field values.

     'State-Changed-By: NAME'
     'Responsible-Changed-By: NAME'
          The name of the maintainer who effected the change.

     'State-Changed-When: TIMESTAMP'
     'Responsible-Changed-When: TIMESTAMP'
          The time the change was made.

     'State-Changed-Why: REASON...'
     'Responsible-Changed-Why: REASON...'
          The reason for the change.

     The '>Audit-Trail:' field also contains any mail messages received
     by GNATS related to this PR, in the order received.

     >Unformatted: (MULTITEXT) Any random text found outside the fields
     in the original Problem Report.

2 Invoking the GNATS tools
**************************

The following programs comprise GNATS:

User Utilities
--------------

These tools are used by the maintainers of a body of work ('send-pr' is
also used by the end users of the product).

'send-pr'
     Used by anyone who has a problem with a body of work to submit a
     report of the problem to the maintainers of that work (see
     Submitting Problem Reports).

'query-pr'
     Used by software maintainers to query the GNATS database (see
     Querying the database).

'edit-pr'
     Used by software maintainers to edit Problem Reports (to record new
     data, to change the responsible party, etc.)  (see Editing existing Problem Reports).

'view-pr'
     Used by software maintainers to view individual Problem Reports
     using Emacs (see Viewing individual Problem Reports).

Administrative Utilities
------------------------

These tools are used by the GNATS administrator; see also GNATS Administration.
For complete explanations of these
utilities, see Administrative utilities.

'mkcat'
     Creates new categories (see Adding a problem category).

'rmcat'
     Removes existing categories (see Removing a problem category).

'gen-index'
     Generates an up-to-date copy of the index used by 'query-pr' and
     'edit-pr' (see The 'index' file).  Use 'gen-index'
     to rebuild the index if it becomes corrupted, or if you need a copy
     of the current index for some reason (see Regenerating the index).

'mkdist'
     Creates a distribution of the program 'send-pr' for offsite
     submitters of PRs (see Configuring 'send-pr' for the outside world).

Internal Utilities
------------------

These tools are used internally by GNATS.  You should not need to run
these by hand.  For complete explanations of these utilities, see
Internal utilities.

'queue-pr'
     Handles incoming bugs, first through a mail alias by queueing
     incoming PRs as they arrive, and second as a periodic transfer
     agent between the queue and the database.

'file-pr'
     Files Problem Reports as they come in.

'at-pr'
     Sends reminders to maintainers based on quoted response times.

'pr-edit'
     Used by 'edit-pr' to error-check and submit edited Problem Reports
     (also Editing existing Problem Reports).

'pr-addr'
     Used by the 'edit-pr' script to retrieve correct addresses from the
     'responsible' file.

   See Where GNATS lives.

2.1 Submitting Problem Reports
==============================

Use 'send-pr' to submit Problem Reports to the database.  'send-pr' is
both a shell script and a Lisp program for GNU Emacs; both
implementations provide a template for submitters to complete.  In most
cases, 'send-pr' can determine intelligent default values for several
fields, partially automating the bug-reporting process.

   See Configuring 'send-pr' for the outside world, for
information on distributing a version of 'send-pr' customized with your
site's configuration.

   You can invoke 'send-pr' from a shell prompt or from within GNU Emacs
using 'M-x send-pr'.

2.1.1 Creating new Problem Reports
----------------------------------

Invoking 'send-pr' presents a PR "template" with a number of fields
already filled in.  Complete the template as thoroughly 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 instructions for 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.
     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"
     'send-pr' creates a standard mail header.  'send-pr' completes all
     fields except the 'Subject:' line with default values.  (see
     Problem Report format.)

"GNATS 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.  (see Problem Report format.
     Also see Helpful hints)

   The default template contains your preconfigured '>Submitter-Id:'.
'send-pr' attempts to determine values for the '>Originator:' and
'>Organization:' fields (see Problem Report format).
'send-pr' will set the '>Originator:' field to the value of the 'NAME'
environment variable if it has been set; similarly, '>Organization:'
will be set to the value of 'ORGANIZATION'.  '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.

   You may submit problem reports to different Support Sites from the
default site by specifying the alternate site when you invoke 'send-pr'.
Each 'site' has its own list of categories for which it accepts Problem
Reports.

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

   The template begins with a comment section:

     SEND-PR: -*- send-pr  -*-
     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: Using 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 contains a list of valid '>Category:' values for the Support
Site to whom you are submitting this Problem Report.  One (and only one)
of these values should be placed in the '>Category:' field.

   The mail header is just below the comment section.  Fill out the
'Subject:' field, if it is not already completed using the value of
'>Synopsis:'.  The other mail header fields contain default values.

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

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
automatically completed with valid information (such as your
'>Submitter-Id:') or contains a one-line instruction specifying the
information that field requires 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.  See Helpful hints,
for suggestions as to what kinds of information to include.

   In this example, words in _italics_ are filled in with pre-configured
information:

     >Submitter-Id: _your submitter-id_
     >Originator:   _your name here_
     >Organization:
         _your organization_
     >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]>
     >Release:     <release number (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)>
     >Fix:
            <how to correct or work around the problem, if known
             (multiple lines)>

   When you finish editing the Problem Report, 'send-pr' mails it to the
address named in the 'To:' field in the mail header.  'send-pr' checks
that the complete form contains a valid '>Category:'.

   If your PR has an invalid value in one of the ENUMERATED fields
(see Problem Report format), 'send-pr' places the PR in a
temporary file named '/tmp/pbadNNNN' on your machine.  NNNN is the
process identification number given to your current 'send-pr' session.
If you are running 'send-pr' from the shell, you are prompted as to
whether or not you wish to try editing the same Problem Report again.
If you are running 'send-pr' from Emacs, the Problem Report is placed in
the buffer '*send-pr-error*'; you can edit this file and then submit it
with

     M-x gnats-submit-pr

   Any further mail concerning this Problem Report should be
carbon-copied to the GNATS mailing address as well, with the category
and identification number in the 'Subject:' line of the message.

     Subject: Re: PR CATEGORY/GNATS-ID: ORIGINAL MESSAGE SUBJECT

Messages which arrive with 'Subject:' lines of this form are
automatically appended to the Problem Report in the '>Audit-Trail:'
field in the order received.

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

   Call 'send-pr' with 'M-x send-pr'.(1)  'send-pr' responds with a
Problem Report template preconfigured for the Support Site from which
you received 'send-pr'.  (If you use 'send-pr' locally, the default
Support Site is probably your local site.)

   You may also submit problem reports to different Support Sites from
the default site.  To use this feature, invoke 'send-pr' with

     C-u M-x send-pr

   'send-pr' prompts you for the name of a SITE.  SITE is an alias on
your local machine which points to an alternate Support Site.

   'send-pr' displays the template and prompts you in the minibuffer
with the line:
     >Category: other

Delete the default value 'other' _in the minibuffer_ and replace it with
the keyword corresponding to your problem (the list of valid categories
is in the topmost section of the PR template).  For example, if the
problem you wish to report has to do with the GNU C compiler, and your
support organization accepts bugs submitted for this program under the
category 'gcc', delete 'other' and then type 'gcc[<RET>]'.  'send-pr'
replaces the line

     >Category:       <name of the product (one line)>

in the template with

     >Category:       gcc

and moves on to another field.

   'send-pr' provides name completion in the minibuffer.  For instance,
you can also type 'gc[<TAB>]', and 'send-pr' attempts to complete the
entry for you.  Typing 'g[<TAB>]' may not have the same effect if
several possible entries begin with 'g'.  In that case 'send-pr' cannot
complete the entry because it cannot determine whether you mean 'gcc'
or, for example, 'gdb', if both of those are possible categories.
'send-pr' continues to prompt you for a valid entry until you enter one.

   '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, 'send-pr' responds with
'[No match]' and allows you to change the entry until it contains an
acceptable value.  This avoids unusable information (at least in these
fields) and also avoids typographical errors which could cause problems
later.

   'send-pr' prompts you for the following fields:

     >Category:
     >Confidential: (_default_:  no)
     >Severity:     (_default_:  serious)
     >Priority:     (_default_:  medium)
     >Class:        (_default_:  sw-bug)
     >Release:
     >Synopsis:     (_this value is copied to Subject:_)

After you complete these fields, 'send-pr' places the cursor in the
'>Description:' field 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.

   'send-pr' provides a few key bindings to make moving around in a
template buffer more simple:

'C-c C-f'
'M-x change-field'
     Changes the field under the cursor.  'edit-pr' prompts you for a
     new value.

'M-C-b'
'M-x gnats-backward-field'
     Moves the cursor to the beginning of the value of the current
     field.

'M-C-f'
'M-x gnats-forward-field'
     Moves the cursor to the end of the value of the current field.

'M-p'
'M-x gnats-previous-field'
     Moves the cursor back one field to the beginning of the value of
     the previous field.

'M-n'
'M-x gnats-next-field'
     Moves the cursor forward one field to the beginning of the value of
     the next field.

   'send-pr' takes over again when you type 'C-c C-c' to send the
message.  'send-pr' reports any errors in a separate buffer, which
remains in existence until you send the PR properly (or, of course,
until you explicitly kill the buffer).

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

   ---------- Footnotes ----------

   (1) If typing 'M-x send-pr' doesn't work, see your system
administrator for help loading 'send-pr' into Emacs.

2.1.3 Invoking 'send-pr' from the shell
---------------------------------------

     send-pr [ SITE ]
             [ -f PROBLEM-REPORT | --file PROBLEM-REPORT ]
             [ -t MAIL-ADDRESS | --to MAIL-ADDRESS ]
             [ --request-id ]
             [ -L | --list ] [ -P | --print ]
             [ -V | --version] [ -h | --help ]

   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.

   Invoking 'send-pr' with no options calls the editor named in your
environment variable 'EDITOR' on a default PR template.  If the
environment variable 'PR_FORM' is set, its value is used as a file name
which contains a valid template.  If 'PR_FORM' points to 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'
'--file PROBLEM-REPORT'
     Specifies 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
     standard input.

'-t MAIL-ADDRESS'
'--to MAIL-ADDRESS'
     Sends the PR to MAIL-ADDRESS.  The default is preset when 'send-pr'
     is configured.  _This option is not recommended_; instead, use the
     argument SITE on the command line.

'-c MAIL-ADDRESS'
'--cc MAIL-ADDRESS'
     Places MAIL-ADDRESS in the 'Cc:' header field of the message to be
     sent.

'--request-id'
     Sends a request for a '>Submitter-Id:' to the Support Site.

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

'-s SEVERITY'
'--severity SEVERITY'
     Sets the initial value of the '>Severity:' field to SEVERITY.

'-P'
'--print'
     Displays the PR template.  If the variable 'PR_FORM' is set in your
     environment, the file it specifies is printed.  If 'PR_FORM' is not
     set, 'send-pr' prints the standard blank form.  If the file
     specified by 'PR_FORM' doesn't exist, 'send-pr' displays an error
     message.  No mail is sent.

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

'-h'
'--help'
     Displays a usage summary for 'send-pr'.  No mail is sent.

2.1.4 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.
This section contains instructions on what kinds of information to
include and what kinds of 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, 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 realization 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, etc.).

   * 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
     contain lists of known bugs in the Release Notes which come with
     the software; see your system administrator if you don't have a
     copy of these.

   * The more closely a PR adheres to the standard format, the less
     interaction is required by a database administrator to route the
     information to the proper place.  Keep in mind that anything that
     requires human interaction also requires time that might be better
     spent in actually fixing the problem.  It is therefore in
     everyone's best interest that the information contained in a PR be
     as correct as possible (in both format and content) at the time of
     submission.

2.2 Editing existing Problem Reports
====================================

Use 'edit-pr' to make changes to existing PRs in the database.
'edit-pr' is both a shell script and a Lisp program for GNU Emacs.  Both
implementations are essentially identical, though the Emacs interface
provides interactive prompting for some of the fields.

   'edit-pr' first examines the PR you wish to edit and locks it if it
is not already locked.  This is to prevent you from editing a PR at the
same time as another user.  If the PR you wish to edit is already in the
process of being edited, 'edit-pr' tells you the name of the person who
owns the lock.

   You may edit any field in the database that you wish.  We recommend
that you avoid deleting any information in the TEXT and MULTITEXT fields
(such as '>Description:' and '>How-To-Repeat:' (see Problem Report format).
We also recommend that you record the final solution
to the problem in the '>Fix:' field for future reference.

   If you change the '>Responsible:' field, 'edit-pr' prompts you to
supply a reason for the change.  'edit-pr' then mails copies of the
change message to the previous responsible party, and to the new
responsible party.  The change is then recorded in the '>Audit-Trail:'
section of the PR as follows:

'Responsible-Changed-<From>-<To>': The value change, supplied
     automatically by 'edit-pr'.

'Responsible-Changed-By': Your name here, supplied
     automatically by 'edit-pr'.

'Responsible-Changed-When': The current date, supplied
     automatically by 'edit-pr'.

'Responsible-Changed-Why': Your reason for the change; you
     are prompted for this.

   If you change the '>State:' field, you are prompted to supply a
reason for the change.  Copies of the change message are then mailed to
the responsible party, and to the original submitter of the Problem
Report.  The change is then recorded in the 'Audit-Trail' section of the
PR as follows:

'State-Changed-<From>-<To>': The value change, supplied
     automatically by 'edit-pr'.

'State-Changed-By': Your name here, supplied
     automatically by 'edit-pr'.

'State-Changed-When': The current date, supplied
     automatically by 'edit-pr'.

'State-Changed-Why': Your reason for the change; you are
     prompted for this.

   The PR is then resubmitted to the database, and the index is updated
(see The 'index' file).  For information on 'pr-edit',
the main driver for 'edit-pr', see Internal utilities.

2.2.1 Using 'edit-pr' from within Emacs
---------------------------------------

Call 'edit-pr' from within Emacs with 'M-x edit-pr'(1).  When 'edit-pr'
prompts you for a PR identification number, type the number of the PR
you wish to edit.

   If the PR is locked, Emacs announces the login name of the person who
has locked the file.  If not, 'M-x edit-pr' locks the PR, loads it into
a buffer named '*edit-pr*', and places the cursor in the '>Number:'
field.  (_Do not change this field_.)

   Edit the PR to reflect correct information.  Resubmit the PR to the
database using 'C-c C-c' (see below).

   The easiest way to edit a PR from Emacs is to use the special key
bindings provided.  These are:

'C-c C-c'
'M-x gnats-submit-pr'
     Saves and resubmits the PR currently being edited.  Do this when
     you finish editing the PR; if you simply kill the buffer, your
     changes are lost.

'C-x C-s'
'M-x save-buffer'
     Saves the current buffer tp a file.  You are prompted for a
     filename.  This is not a special key binding, but at one point in
     the history of GNATS it was used to resubmit the PR (i.e., it was
     bound to 'M-x gnats-submit-pr').  'C-x C-s' now simply saves a copy
     of the PR. This command _does not_ resubmit the PR to the database.
     Use 'C-c C-c' to resubmit the PR.

'C-x k'
'M-x gnats:kill-buffer (_use this only with Emacs 18_)'
'M-x kill-buffer'
     Kills the current buffer (destroying all changes) and unlocks the
     current PR. Use this to back out of a change without affecting the
     database.

'C-c C-u'
'M-x unlock-pr'
     Unlocks a PR that you have locked.  Use this if you have a locked
     PR from a failed editing session.  You are prompted for the
     GNATS-ID of a PR to unlock.

'C-c C-q'
'M-x unlock-buffer'
     Removes the lock on the current PR, allowing others to edit it.
     The buffer remains active and non-writeable.  To relock a PR,
     simply type 'e' in the buffer containing the Problem Report.

'C-c C-e'
'M-x edit-pr'
     Runs 'edit-pr' in a new buffer.

'C-c C-f'
'M-x change-field'
     Changes the field under the cursor.  'edit-pr' prompts you for a
     new value.  If you use

          C-u C-c C-f  _or_
          C-u M-x change-field

     you are prompted for a field to change.

'C-c C-a'
'M-x gnats-mail-reply'
     Sends mail to the originator of this PR, using the address in the
     'From:' field of the mail header.  The 'Subject', 'To:', and 'Cc:'
     fields are constructed from the Problem Report currently being
     edited.  Edit the message, and use 'C-c C-c' to send it.

'C-c RET'
'C-c C-m'
'M-x gnats-mail-other-window'
     Splits the current window, and starts a mail message.  The
     'Subject:' field is constructed from the Problem Report currently
     being edited.  Edit the message, and use 'C-c C-c' to send it.

'C-c C-r'
'M-x gnats-responsible-change-from-to'
     Changes the '>Responsible:' field.  'edit-pr' prompts you for the
     new responsible person, and for a message describing the reason for
     the change.  When you type 'C-c C-c' to resubmit the PR, the cursor
     is placed in a mail buffer containing a copy of the change.  You
     can then edit this buffer and type 'C-c C-c' again to send the
     mail.

'C-c C-s'
'M-x gnats-state-change-from-to'
     Changes the '>State:' field.  'edit-pr' prompts you for the new
     state, and for a message describing the reason for the change.
     When you type 'C-c C-c' to resubmit the PR, the cursor is placed in
     a mail buffer containing a copy of the change.  You can then edit
     this buffer and type 'C-c C-c' again to send the mail.

'C-c C-t'
'M-x category-change-from-to'
     Changes the '>Category:' field of the PR. 'edit-pr' prompts you for
     the new category.  'edit-pr' also prompts you with the question

          Update the >Responsible field?

     Type 'y' to change the value of the '>Responsible:' field to the
     name of the party responsible for the new category.  Type 'n' to
     keep the current value of '>Responsible:'.

'M-C-b'
'M-x gnats-backward-field'
     Moves the cursor to the beginning of the value of the current
     field.

'M-C-f'
'M-x gnats-forward-field'
     Moves the cursor to the end of the value of the current field.

'M-p'
'M-x gnats-previous-field'
     Moves the cursor back one field to the beginning of the value of
     the previous field.

'M-n'
'M-x gnats-next-field'
     Moves the cursor forward one field to the beginning of the value of
     the next field.

   ---------- Footnotes ----------

   (1) If typing 'M-x edit-pr' doesn't work, see your system
administrator for help loading 'edit-pr' into Emacs.

2.2.2 Invoking 'edit-pr' from the shell
---------------------------------------

The usage for the 'edit-pr' shell script is:

     edit-pr GNATS-ID [ -V | --version ] [ -h | --help ]

You must first determine which PR you want to edit.  The options are:

'-V _or_ --version'
     Prints the version number for 'edit-pr'.

'-h _or_ --help'
     Prints the usage for 'edit-pr'.

   'edit-pr' calls the editor specified in your environment variable
'EDITOR' on a temporary copy of that PR. (If you don't have the variable
'EDITOR' defined in your environment, the default editor 'vi' is used.)

   Edit the PR, changing any relevant fields or adding to existing
information.  When you exit the editor, 'edit-pr' prompts you on
standard input for a reason if you've changed either the '>Responsible:'
field or the '>State:' field.  'edit-pr' tracks the information you
provide when changing either of these two fields, along with the change
that occurred, your name, and the time of change in the '>Audit-Trail:'
field.

2.3 Querying the database
=========================

Obtain information from the database by using the program 'query-pr'.
'query-pr' uses search parameters you provide to find matching Problem
Reports in the database.  You can invoke 'query-pr' from the shell or
from within Emacs.  'query-pr' uses the same arguments whether it is
invoked from the shell or from Emacs.

   All arguments and options to 'query-pr' are optional.  If you do not
specify a PR identification number and do not give any search
parameters, 'query-pr' displays the entire database.  All arguments are
considered identification numbers of Problem Reports to display.  Any
number of options can be given (though some make no sense when specified
on the same command line); all are connected with a logical 'AND'.

2.3.1 Invoking 'query-pr'
-------------------------

From the shell, simply type 'query-pr', followed by any search
parameters you wish to exercise.  From Emacs, type 'M-x query-pr'.
'query-pr' prompts you for search parameters in the minibuffer.

   'query-pr' can also be accessed by electronic mail, if your version
of GNATS is configured for this.  To use this feature, simply send mail
to the address 'query-pr@YOUR-SITE' with command line arguments or
options in the 'Subject:' line of the mail header.  GNATS replies to
your mail with the results of your query.  The default settings for the
'query-pr' mail server are

     --restricted --state="open|analyzed|feedback|suspended"

To override the '--state' parameter, specify '--state=STATE' in the
'Subject:' line of the mail header.  You can not query on confidential
Problem Reports by mail.

   The usage for 'query-pr' is:

     query-pr [ GNATS-ID ]
              [ -c CATEGORY | --category=CATEGORY ]
              [ -s STATE | --state=STATE ]
              [ -r RESPONSIBLE | --responsible=RESPONSIBLE ]
              [ -S SUBMITTER | --submitter=SUBMITTER ]
              [ -C [ YES | NO ] | --confidential=[ YES | NO ] ]
              [ -e SEVERITY | --severity=SEVERITY ]
              [ -p PRIORITY | --priority=PRIORITY ]
              [ -O ORIGINATOR | --originator=ORIGINATOR ]
              [ -L CLASS | --class=CLASS ]
              [ -t TEXT | --text=TEXT ]
              [ -m TEXT | --multitext=TEXT ]
              [ -R | --restricted ]
              [ -F | --full ] [ -q | --summary ] [ -i | --sql ]
              [ -P | --print-path ]
              [ -d DIRECTORY | --directory=DIRECTORY ]
              [ -o OUTFILE | --output=OUTFILE ]
              [ -V | --version ] [ -h | --help ]

   If you run 'query-pr' from within Emacs, you can use

     C-x `     _or_       M-x next-error

to scroll through Problem Reports one by one after the search is
finished.

Search criteria
---------------

The following arguments and options specify search criteria.  The lack
of a criterion indicates that all values for the corresponding field are
valid for the search.  Regular expressions may be used as arguments to
search criteria options; see Querying using regular expressions.

   Using an argument to 'query-pr' specifies the most stringent search
criteria, that of a single PR.

'GNATS-ID'
     The identification number of the PR you wish to view, as shown in
     the '>Number:' field.  Any number of GNATS-ID arguments may be
     given.

'-c CATEGORY'
'--category=CATEGORY'
     Search only for PRs with a '>Category:' value of CATEGORY.  For a
     list of valid categories, type 'send-pr -L' from the shell.

'-s STATE'
'--state=STATE'
     Search only for PRs with a '>State:' value of STATE.  STATE must be
     one of: 'open', 'analyzed', 'feedback', 'closed', or 'suspended'.

     This field may be searched using regular expressions.  See
     Querying using regular expressions.  Also see
     Example queries.

'-r RESPONSIBLE'
'--responsible=RESPONSIBLE'
     Search only for PRs with a '>Responsible:' value of RESPONSIBLE.

'-S SUBMITTER'
'--submitter=SUBMITTER'
     Search only for PRs with a '>Submitter:' value of SUBMITTER.

'-C [YES | NO]'
'--confidential=[YES | NO]'
     Search only for PRs with a '>Confidential:' value of either YES or
     NO.  If this option is not given, all PRs are eligible for the
     search regardless of their confidentiality.

'-e SEVERITY'
'--severity=SEVERITY'
     Search only for PRs with a '>Severity:' value of SEVERITY.
     SEVERITY must be one of: 'critical', 'serious', or 'non-critical'.

'-p PRIORITY'
'--priority=PRIORITY'
     Search only for PRs with a '>Priority:' value of PRIORITY.
     PRIORITY must be one of: 'high', 'medium', or 'low'.

'-O ORIGINATOR'
'--originator=ORIGINATOR'
     Search only for PRs with an '>Originator:' value of ORIGINATOR.

     Since this option does not reference the index, queries using it
     finish much faster if you also use another search criterion that
     _is_ part of the index (see The 'index' file).

'-L CLASS'
'--class=CLASS'
     Search only for PRs with a '>Class:' value of CLASS.  Since this
     option does not reference the index, queries using it finish much
     faster if you also use another search criterion that _is_ part of
     the index (see The 'index' file).

'-t TEXT'
'--text=TEXT'
     Search the TEXT fields in the database for the regular expression
     TEXT.  TEXT fields include the following (the '>' and ':' Problem
     Report fieldname delimiters have been removed for the sake of
     brevity and readability):

          Submitter-Id   Originator     Synopsis
          Category       Release        Responsible
          Arrival-Date

     See Querying using regular expressions.

     Queries using this option can be slow.  Since this option does not
     reference the index, queries using it finish much faster if you
     also use another search criterion that _is_ part of the index
     (see The 'index' file).

'-m TEXT'
'--multitext=TEXT'
     Search the MULTITEXT fields in the database for the regular
     expression TEXT.  MULTITEXT fields include the following (again,
     the fieldname delimiters '>' and ':' have been omitted):

          Organization   Environment    Description
          How-To-Repeat  Fix            Audit-Trail
          Unformatted

     See Querying using regular expressions.

     Queries using this option can be very slow.  Since this option does
     not reference the index, queries using it finish much faster if you
     also use another search criterion that _is_ part of the index
     (see The 'index' file).

'-R'
'--restricted'
     Omit from the search path PRs whose '>Confidential:' fields contain
     the value 'yes'.  This is equivalent to

          query-pr --confidential=no

     and also disallows the use of the options '--outfile=OUTFILE' and
     '--directory=DIRECTORY'.  This option is used with the 'mail-query'
     tool.

'-x'
'--skip-closed'
     Omit closed PRs from the search path.  This option is ignored if
     you also use '-s STATE' or '--state=STATE'.

Output format
-------------

Use the following options to select the format in which the Problem
Report is printed.  Use only one of these options for a given search.
If you do not specify one of these options, a header(1) for the Problem
Reports meeting the search criteria is printed.

'-F'
'--full'
     Prints all fields in the Problem Report rather than just summary
     information.

'-q'
'--summary'
     Print a short single-line summary of PR information, delimited by
     whitespace, including the following fields in order (the '>' and
     ':' Problem Report fieldname delimiters have been removed for the
     sake of brevity and readability):

          Number         Responsible    Category
          State          Severity       Priority
          Submitter-Id   Synopsis

'-i'
'--sql'
     Prints information on a single line with fields delimited by pipes
     ('|'), which can be uploaded into a relational database.  When you
     use this option, 'query-pr' outputs ENUMERATED fields numerically
     rather than textually; see Reporting on groups of Problem Reports.

     'query-pr -i' outputs the following fields, in order (again, the
     fieldname delimiters '>' and ':' have been omitted):

          Number         Category       Synopsis
          Confidential   Severity       Priority
          Responsible    State          Class
          Submitter-Id   Arrival-Date   Originator
          Release

     When you use the '-i' option, 'query-pr' outputs the ENUMERATED
     fields in the database, namely '>Severity:', '>Priority:',
     '>State:', and '>Class:', as numbers rather than text.  See
     Reporting on groups of Problem Reports, for details.

Other options
-------------

'query-pr' also accepts the following options:

'-P'
'--print-path'
     Prints the path which 'query-pr' used to find the current PR. A
     line of the form 'DIRECTORY/NUMBER:NUMBER' is printed before each
     PR. This option is automatically used from within Emacs to
     facilitate scrolling through groups of PRs with 'C-x `'.

'-d DIRECTORY'
'--directory=DIRECTORY'
     Changes the search directory to DIRECTORY from GNATS_ROOT.

'-o OUTFILE'
'--output=OUTFILE'
     Prints all output to OUTFILE rather than to the standard output.

'-V'
'--version'
     Prints the version number for 'query-pr'.

'-h'
'--help'
     Prints the usage for 'query-pr'.

   ---------- Footnotes ----------

   (1) A "header" includes the mail header fields as well as the
following fields: '>Number:', '>Category:', '>Synopsis:',
'>Confidential:', '>Severity:', '>Priority:', '>Responsible:',
'>State:', '>Class:', '>Submitter-Id:', '>Originator:', '>Release:', and
'>Arrival-Date:'.  For suggestions on using alternate output formats in
database reports, see Reporting.

2.3.2 Example queries
---------------------

The following simple query:

     query-pr --category=rats --responsible=fred --state=analyzed

yields all PRs in the database which contain the field values:

     >Category:     rats         _and_
     >Responsible:  fred         _and_
     >State:        analyzed

   The following query:

     query-pr --state="o|a"

yields all PRs in the database whose '>State:' values match either
'open' or 'analyzed' (see Querying using regular expressions.
This search is useful as a daily report that lists all Problem Reports
which require attention.

   The report can be further altered using an alternate output format
for 'query-pr'; see Reporting on groups of Problem Reports.
A more fine-grained report may be obtained by specifying
more search parameters, e.g.  narrowing the search down by '>Submitter:'
or by '>Responsible:'.

   The following query:

     query-pr --text="The quick.*brown fox"

yields all PRs whose TEXT fields contain the text 'The quick' followed
by 'brown fox' within the same field.  See Querying using regular expressions.

2.3.3 Reporting on groups of Problem Reports
--------------------------------------------

There currently exists no separate reporting mechanism in GNATS from
'query-pr'.  However, the '-q' and '-i' options to 'query-pr' allow for
easy reporting.

   For example, a report on the current open Problem Reports in the
database can be obtained using 'awk' with

     query-pr -q | awk '{print $3 "/" $1 ": " $4}'

which yields a list of the form

     CATEGORY/GNATS-ID: STATE
     _etc..._

For example:

     sprockets/123: open
     widgets/456: analyzed
     _etc..._

The '-i' option to 'query-pr' yields output delimited by pipes ('|').
This results in the following:

     GNATS-ID|CATEGORY|SYNOPSIS|CONFIDENTIAL|\
     SEVERITY|PRIORITY|RESPONSIBLE|STATE|CLASS|\
     SUBMITTER-ID|ARRIVAL-DATE|ORIGINATOR|RELEASE

   A report on Problem Reports in the database that are currently 'open'
or 'analyzed' might resemble the following (the example is split into
two lines in order to fit onto the page; it is intended to be typed on
one command line):

     query-pr -i -s "o|a" | \
       awk -F\| '{print $1 "  " $2 "  " $8 "  " $3}'

which yields

     GNATS-ID  CATEGORY  STATE  RESPONSIBLE SYNOPSIS
     _etc..._

For example:

     123  sprockets  1  fred    The sprockets program gives bad output
     456  widgets    2  barney  The foo widget doesn't work with 'bar'
     789  widgets    1  wilma   The 'baz' widget is broken

When you use the '-i' option, 'query-pr' outputs the ENUMERATED fields
in the database, namely '>Severity:', '>Priority:', '>State:', and
'>Class:', as numbers rather than text.  In the example above, a
'>State:' value of '1' means 'open', '2' means 'analyzed', and so forth.
ENUMERATED fields are output according to the following paradigm:

         >Severity:                   >Priority:
     critical        1             high            1
     serious         2             medium          2
     non-critical    3             low             3

          >State:                      >Class:
     open            1             sw-bug          1
     analyzed        2             doc-bug         2
     suspended       3             support         3
     feedback        4             change-request  4
     closed          5             mistaken        5
                                   duplicate       6

   This makes sorting on these values easy, when combined with 'sort'.
It is left as an exercise for the reader to figure out how to do this.

2.4 Viewing individual Problem Reports
======================================

Use 'view-pr' from within Emacs to view individual Problem Reports.
Invoke 'view-pr' with

     M-x view-pr

   You are prompted to enter a Problem Report identification number
(GNATS-ID).  You can also invoke 'view-pr' with

     C-u GNATS-ID M-x view-pr

   'view-pr' allows you to view GNATS-ID.  This is identical to using

     C-u GNATS-ID M-x query-pr

   except that you may choose to edit the PR at any time by pressing
'e'.

3 GNATS Administration
**********************

In daily usage, GNATS is self-maintaining.  However, there are various
administrative duties which need to be performed periodically:

_emptying the 'pending' directory_
     If a Problem Report arrives with a '>Category:' value that is
     unrecognized by the 'categories' file, or if that field is missing,
     GNATS places the PR in the 'pending' directory (see Where the tools and utilities reside).
     GNATS has no way of
     knowing which subdirectory the PR should be filed under.  GNATS
     sends a notice to the 'gnats-admin' and to the party responsible
     for that submitter (as listed in the 'submitters' file) when this
     occurs.

     To file these PRs, simply use 'edit-pr' to repair the problematic
     fields in each file in the 'pending' directory.  Be sure to change
     the '>Category:' field of the PR from 'pending' to an appropriate
     category.  In many cases the culprit is simply a typographical
     error, although it may be necessary sometimes to contact the
     submitter of the PR to decipher her or his intentions.

     Should you run out of disk space, there may be an empty PR in the
     'pending' directory.  In that case, look in the file
     'GNATS_ROOT/gnats-adm/bug.log', which should still contain the full
     message that was submitted.

_adding new categories_
     To add a new category, simply insert a new line in the 'categories'
     file and then run the program 'mkcat'.

     _Note_: this causes all category lists for 'send-pr' (except the
     one on the local machine) to become outdated.  Copy the new list on
     to every machine on your network that has 'send-pr' installed, and
     make sure you advise remote submitters that the category list has
     changed.  See Adding a problem category.  Also The 'categories' file.

_removing categories_
     To remove a category, you need to make sure the relevant
     subdirectory is empty (in other words, make sure no PRs exist for
     the category you wish to remove).  You can then remove the category
     listing from the 'categories' file, and invoke

          rmcat CATEGORY...

     to remove CATEGORY (any number of categories may be specified on
     the command line to 'rmcat', so long as they abide by the above
     constraints).

     _Note_: this causes all category lists for 'send-pr' (except the
     one on the local machine) to become outdated.  Copy the new list on
     to every machine on your network that has 'send-pr' installed, and
     make sure you advise remote submitters that the category list has
     changed.  See Removing a problem category.  Also The 'categories' file.

_adding and removing maintainers_
     Edit the 'responsible' file to add a new maintainer or to remove an
     existing maintainer.  See The 'responsible' file.

_building a distribution of 'send-pr'_
     You can build a distribution of 'send-pr' which contains valid
     information for your site by invoking the command 'mkdist'.  See
     Configuring 'send-pr' for the outside world.  You can then
     distribute your customized 'send-pr' to your customers, friends,
     relatives, etc., so that they can submit Problem Reports to your
     database.

_building a new index_
     If your index becomes corrupted, or if you wish to generate a new
     one for some reason, use the program 'gen-index' (see
     Regenerating the index).

_pruning log files_
     Log files often grow to unfathomable proportions.  As with
     gardening, it is best to prune these as they grow, lest they take
     over your disk and leave you with no room to gather more Problem
     Reports.  If you keep log files, be sure to keep an eye on them.
     (see Setting up mail aliases.)

_BACKING UP YOUR DATA_
     Any database is only useful if its data remains uncorrupted and
     safe.  Performing periodic backups ensures that problems like disk
     crashes and data corruption are reversible.

   See Where GNATS lives.

3.1 Managing GNATS over a network
=================================

If you have installed the GNATS user tools on machines around your local
network, there are a few things you need to remember.

   'mkcat' and 'rmcat' do not update the categories list for other
machines on your network which have 'send-pr' installed, unless those
machines share PREFIX with the host machine).  To update these lists,
copy the 'send-pr' categories list to each of the other hosts.  This
categories list is 'PREFIX/lib/gnats/SITE', where SITE is the name tag
for your local site, as specified in the 'config' file as 'GNATS_SITE'
(see The 'config' file).

   It is also important to note that only your local 'send-pr' has
access to this new information; any copies of 'send-pr' which you have
distributed to outside submitters now have outdated category lists.  You
must either contact your submitters and instruct them to update their
copy of the categories list, which they installed in
'PREFIX/lib/gnats/SUPPORT-SITE' from the distribution you provided, or
you must build another distribution of 'send-pr' with this new
information and redistribute it.

   If you need to use GNATS utilities, like 'query-pr' and 'edit-pr', on
other systems besides the one where GNATS itself resides, see
Installing the user tools.

3.2 Changing your local configuration
=====================================

See Where GNATS lives.

   Your local configuration is determined by the data files in the
directory 'GNATS_ROOT/gnats-adm'.  These can be altered at any time by
editing the pertinent file.

'config'
     Variables which control certain behavior.  See The 'config' file.
     Behaviors you can change here include

        * The address where your site receives Problem Reports.

        * The address of the GNATS administrator.

        * The nametag for your Support Site (your organization, company,
          group, etc.).

        * The nametag for your local Submitter Site.

        * The default release for your site.

        * The default value for the '>Organization:' field (this value
          appears as the default when you run 'send-pr').

        * Whether or not to remind maintainers if a requisite time
          period has passed before they change the state of a Problem
          Report to 'analyzed'.  (Also see The 'submitters' file,
          and Timely Reminders.

        * Whether or not to send an automatic acknowledgement to the
          originator of a problem report when the GNATS first receives
          the PR.

        * The value GNATS assigns to PRs which come in with missing or
          unknown values for the '>Submitter-Id:' field.

        * Whether or not GNATS should retain 'Received:' mail headers
          from incoming mail.

        * Whether or not GNATS is in a mode for debugging.

        * The values which define business hours.

'categories'
     The list of categories that GNATS accepts as valid for the
     '>Category:' field, and the maintainers responsible for each
     category.  Update this file whenever you have a new category, or
     whenever a category is no longer valid.  You must also update this
     file whenever responsiblility for a category changes, or if a
     maintainer is no longer valid.  See The 'categories' file.
     Also see Adding a new problem category,
     and Removing a problem category.

'responsible'
     The list of maintainers.  Update this file whenever you have a new
     maintainer, or whenever a maintainer is no longer valid.  See The 'responsible' file.

'submitters'
     The list of Submitter Sites from whom GNATS accepts Problem
     Reports.  This file is mandatory, although the feature it provides
     is not; see The 'submitters' file.

3.2.1 Default behavior
----------------------

The default behavior for GNATS is as follows:

   * The address where your site receives Problem Reports is 'bugs' (a
     local address).

   * The address of the GNATS administrator is 'gnats-admin' (a local
     address).

   * The nametag for your Support Site (your organization, company,
     group, etc.)  is the second-to-last field in your domain name.

   * The nametag for your local Submitter Site is the nametag for your
     Support Site.

   * The default release for your site is 'unknown-1.0'.

   * The default value for the '>Organization:' field (this value
     appears as the default when you run 'send-pr') is the nametag for
     your Support Site.

   * GNATS reminds maintainers if a requisite time period has passed
     before they change the state of a Problem Report to 'analyzed'.

   * An automatic acknowledgement is sent to the originator of a problem
     report when the GNATS first receives the PR.

   * The value GNATS assigns to the '>Submitter-Id:' field in PRs which
     arrive with missing or unknown values for that field is 'unknown'.

   * 'Received...' mail headers are retained.

   * GNATS is not in a debugging mode.

   * "business hours" are defined as 8:00am to 5:00pm, Monday through
     Friday.

3.2.2 The 'config' file
-----------------------

Much of the behavior GNATS exhibits depends on the values of fields in
the file 'GNATS_ROOT/gnats-adm/config'.  The 'config' file contains a
list of variables (using Bourne-shell syntax) which control the
following behavior.  These values can be changed at any time; the new
values take effect for all subsequent iterations of the tools.

'GNATS_ADDR="ADDRESS"'
     The address where your site receives Problem Reports.  This address
     is aliased in the file '/etc/aliases' so that it directs incoming
     mail into 'queue-pr' (see Installing the utilities).

     The default is 'bugs' (a local address).

'GNATS_ADMIN="ADDRESS"'
     The address of the GNATS administrator.  Normally this is set to
     'gnats-admin', which is an alias in '/etc/aliases' that points
     toward the person responsible for administrating GNATS.  See
     Installing the utilities.

     The default is 'gnats-admin' (a local address).

'GNATS_SITE="SITE"'
     The nametag for your Support Site (your organization, company,
     group, etc.).  This nametag should also appear in the 'submitters'
     file, so that users at your site can submit Problem Reports
     locally.

     SITE is also used as the name of the file containing a valid
     category list for your site.  This file is installed locally as
     'PREFIX/lib/gnats/SITE'.  _Warning:_ if you change this variable
     after GNATS is installed, you must also change the name of this
     file, as well as the name of the alias for your local submitters
     (see Setting up mail aliases).

     The default is the second-to-last field in your domain name.  For
     example, if your domain name is 'unleaded.truckstop.org', your
     default SITE is 'truckstop'.

'SUBMITTER="SUBMITTER-ID"'
     The nametag for your local Submitter Site (this value appears as
     the default value for '>Submitter-Id' when you run 'send-pr').
     Even though you are a Support Site, if you submit Problem Reports
     to your own organization you become a Submitter Site.  The value
     SUBMITTER-ID is the default value for the '>Submitter-Id:' field
     that your maintainers see when they submit Problem Reports locally.

     The default is the value of 'GNATS_SITE'.

'DEFAULT_RELEASE="RELEASE"'
     The default release for your site (this value appears as the
     default value for '>Release:' when you run 'send-pr').

     The default is 'unknown-1.0'.

'DEFAULT_ORGANIZATION="TEXT"'
     The default value for the '>Organization:' field (this value
     appears as the default when you run 'send-pr').

     The default is the value of 'GNATS_SITE'.

'NOTIFY=BOOLEAN'
     Determines whether or not to remind maintainers if a requisite time
     period has passed before they change the state of a Problem Report
     to 'analyzed'.  This feature uses the program 'at-pr'; see
     Timely Reminders.

     This requisite time is determined for each submitter individually;
     see The 'submitters' file.  The time is measured
     in "business hours", which by default are 8:00am to 5:00pm, Monday
     through Friday.  Business hours can be redefined by changing the
     variables 'BDAY_START', 'BDAY_END', 'BWEEK_START', and 'BWEEK_END'
     in the 'config' file (see below).

     If BOOLEAN is '1', this feature is active.  If BOOLEAN is '0', the
     feature is turned off.  The default value for 'NOTIFY' is '1'.

'ACKNOWLEDGE=BOOLEAN'
     Determines whether or not to send an automatic acknowledgement to
     the originator of a problem report when the GNATS first receives
     the PR.

     If BOOLEAN is '1', this feature is active.  If BOOLEAN is '0', the
     feature is turned off.  The default for 'ACKNOWLEDGE' is '1'.

     The acknowledgment is of the form:

          To: YOUR-ADDRESS
          From: gnats
          Subject: Re: CATEGORY/GNATS-ID:SYNOPSIS
          In-Reply-To: Your message of DATE

          Thank you very much for your problem report.
          It has the internal identification: CATEGORY/GNATS-ID
          The individual assigned to look at your bug is:
               RESPONSIBLE

          Category:     CATEGORY OF THE PR
          Responsible:  RESPONSIBLE
          Synopsis:     SYNOPSIS FROM SUBMITTED PR
          Arrival-Date: ARRIVAL DATE

'DEFAULT_SUBMITTER="submitter-id"'
     The value GNATS assigns to PRs which come in with missing or
     unknown values for the '>Submitter-Id:' field.  This value must
     also appear in the 'submitters' file; see The 'submitters' file.

     To disable the feature of GNATS which tracks the '>Submitter-Id:',
     simply alter the 'submitters' file to only contain the SUBMITTER-ID
     value which appears in 'DEFAULT_SUBMITTER', and instruct your
     submitters to ignore the field.

     The default value for 'DEFAULT_SUBMITTER' is 'unknown'.

'KEEP_RECEIVED_HEADERS=BOOLEAN'
     Determines whether or not GNATS should retain the 'Received:' mail
     headers from incoming mail.  These headers often take up a lot of
     space, and they are seldom used.

     If BOOLEAN is '1', this feature is active.  If BOOLEAN is '0', the
     feature is turned off.  The default value for
     'KEEP_RECEIVED_HEADERS' is '1'.

'DEBUG_MODE=BOOLEAN'
     Determines whether or not GNATS is operating in a mode for
     debugging.  When BOOLEAN is '1', GNATS forwards all mail to the
     GNATS administrator, 'gnats-admin'.

'BDAY_START=INTEGER'
'BDAY_END=INTEGER'
'BWEEK_START=INTEGER'
'BWEEK_END=INTEGER'
     The definition of "business hours".  These values are only used if
     'NOTIFY' is set to '1' in the 'config' file (see above).

     By default, business hours are 8:00am to 5:00pm Monday through
     Friday, local time.

     'BDAY_START=INTEGER'
          Defines the hour of the day when business hours begin.
          INTEGER values must fall between '0' (midnight) and '23'
          (11:00pm).  The default is '8' (8:00am).

     'BDAY_END=INTEGER'
          Defines the hour of the day when business hours end.  INTEGER
          values must fall between '0' (midnight) and '23' (11:00pm).
          The default is '17' (5:00pm).

     'BWEEK_START=INTEGER'
          Defines the beginning day of the business week.  INTEGER
          values must fall between '0' (Sunday) and '6' (Saturday).  The
          default is '1' (Monday).

     'BWEEK_END=INTEGER'
          Defines the ending day of the business week.  INTEGER values
          must fall between '0' (Sunday) and '6' (Saturday).  The
          default is '5' (Friday).

3.2.3 The 'categories' file
---------------------------

The 'categories' file contains a list of problem categories, specific to
your site, which GNATS tracks.  This file also matches responsible
people with these categories.  You must edit this file initially,
creating valid categories and then running 'mkcat' to create the
corresponding subdirectories of 'GNATS_ROOT' and update the valid
categories list for 'send-pr'.  For instructions on running 'mkcat', see
Adding a problem category.

   To create a new category, log in as GNATS, add a line to this file,
and run 'mkcat'.  Lines beginning with '#' are ignored.

   A line in the 'categories' file consists of four fields delimited by
colons, as follows:

     CATEGORY:DESCRIPTION:RESPONSIBLE:NOTIFY

CATEGORY
     A unique category name, made up of text characters.  This name
     cannot contain spaces or any of the following characters:

          ! $ & * ( ) { } [ ] ` ' " ; : < > ~

     Ideally, category names should not contain commas or begin with
     periods.  Each line has a corresponding subdirectory in the main
     GNATS directory (GNATS_ROOT).

DESCRIPTION
     A terse textual description of the category.

RESPONSIBLE
     The name tag of the party responsible for this category of
     problems, as listed in the 'responsible' file (see The 'responsible' file).

NOTIFY
     One or more other parties which should be notified when a Problem
     Report with this category arrives, such as a project manager, other
     members of the same project, other interested parties, or even log
     files.  These should be separated with commas.

   A good strategy for configuring this file is to have a different
category for each product your organization supports or wishes to track
information for, or perhaps with sub-categories within each category.
For instance, if you wish to track documentation problems in a variety
of areas, you could have entries such as

     doc:General Doc Questions:myboss:me,barney
     doc-rock:Doc for ROCK program:me:myboss
     doc-stone:Docs for STONE utils:barney:fred
     doc-local:in-house documentation:me:doc-local-log

   In the above example, the nametags 'myboss', 'me', 'fred', and
'barney' must be defined in the 'responsible' file (see The 'responsible' file).

   Problem Reports with a category of 'doc' are sent to the local mail
address (or alias) 'myboss', and also sent to the addresses 'me' and
'barney'.  PRs with a category of 'doc-rock' are sent to the local
addresses 'me' and 'myboss' only, while PRs with the category
'doc-stone' are sent to 'fred' as well as to 'barney'.  PRs with a
category of 'doc-local' are sent only to 'me', and are also filed in
'doc-local-log' (in this case, an alias should be set up in
'/etc/aliases' to reflect a location for the log file, such as
'doc-local-log: /users/me/local-log').

   Whenever you add a new category, be sure to run 'mkcat' to create a
subdirectory for it and update the local categories list.

   Only one category must be present for GNATS to function:

     pending:Category for faulty PRs: gnats-admin:

   The 'pending' directory is created automatically when you run
'make install' (see Configuring and compiling the software).

3.2.4 The 'responsible' file
----------------------------

This file contains a list of the responsible parties.  Lines beginning
with '#' are ignored.  Each entry contains three fields, separated by
colons:

     RESPONSIBLE:FULL-NAME:MAIL-ADDRESS

RESPONSIBLE
     A name-tag description of the party in question, such as her or his
     user name, or the name of the group.  This name is listed in the PR
     in the '>Responsible:' field.

FULL-NAME
     The full name of the party ("Charlotte Bronte"; "Compiler Group").

MAIL-ADDRESS
     The full, valid mail address of the party.  This field is only
     necessary if the responsible party has no local mail address or
     alias.

A sample 'responsible' listing might be:

     ren:Ren Hoek:
     stimpy:Stimpson J. Cat:stimpy@lederhosen.org

   Here, 'ren' is a local user.  'stimpy' is remote, so his full address
must be specified.

   The following entry must be present for GNATS to function:

     gnats-admin: GNATS administrator:

('gnats-admin' is a mail alias, so for this purpose 'gnats-admin' is a
local address.)

3.2.5 The 'submitters' file
---------------------------

This is a database of sites which submit bugs to your support site.  It
contains six fields delineated by colons.  Lines beginning with '#' will
be ignored.

   Entries are of the format:

     SUBMITTER-ID:NAME:TYPE:RESP-TIME:CONTACT:NOTIFY

SUBMITTER-ID
     A unique identifier for a specific site or other entity who submits
     Problem Reports.

NAME
     A textual description of this entity.

TYPE
     Optional description for the type of relationship this submitter to
     your support site.  This could indicate a contract type, a level of
     expertise, etc., or it can remain blank.

RESP-TIME
     Optional quoted response time, in "business hours".  GNATS is
     capable of reminding responsible parties when Problem Reports
     marked with a '>Severity' value of 'critical', or those with a
     '>Severity' of 'serious' and a '>Priority' value of 'high', are
     neglected for a certain period.  This argument defines that
     response period for each SUBMITTER-ID.  Business hours are defined
     by default as 8:00am to 5:00pm, Monday through Friday.  For
     example, three business days would be equal to 24 business hours.

     This function is active if the 'NOTIFY' field is defined as '1' in
     the 'config' file (see Changing your local configuration).
     If 'NOTIFY' is '0', this field is ignored.  For
     information on 'at-pr', the program which sends out this reminder,
     see Timely Reminders.

CONTACT
     The name tag of the main "contact" at the Support Site for this
     submitter.  This contact should be in the 'responsible' file (see
     The 'responsible' file).  Incoming bugs from
     SUBMITTER are sent to this contact.  Optionally, this field can be
     left blank.

NOTIFY
     Any other parties who should receive copies of Problem Reports sent
     in by SUBMITTER.

   A few example entries in the 'submitters' file:

     univ-hell: University of Hades:eternal:3:beelzebub:lucifer
     tta: Telephones and Telegraphs of America:support:720:dave:

In this example, when a PR comes in from the University of Hades (who
has an eternal contract), it should have 'univ-hell' in its
'Submitter-Id' field.  This Problem Report goes to 'beelzebub' (who
should be in the 'responsible' file), and if it is not analyzed within
three business hours a reminder message is sent.  'lucifer' also
receives a copy of the bug, and a copy of the reminder message as well
(if it is sent).  When Telephones and Telegraphs of America utilizes
their support contract and submits a bug, a copy is sent only to 'dave',
who has 720 business hours to return an analysis before a reminder is
sent.

   To disable the feature of GNATS which tracks the '>Submitter-Id:',
simply alter the 'submitters' file to only contain the SUBMITTER-ID
value which appears as the 'DEFAULT_SUBMITTER' value in the 'config'
file (see The 'config' file), and instruct your submitters to
ignore the field.

3.3 Administrative data files
=============================

The following files are located in 'GNATS_ROOT/gnats-adm', where
GNATS_ROOT is the resident directory of GNATS.  These files are
maintained by GNATS; you should never touch them.

3.3.1 The 'index' file
----------------------

The index is used to accelerate searches on the database by 'query-pr'
and 'edit-pr'.  This file is not created until the first PR comes in.
It is then kept up to date by GNATS; you should never touch this file.

   Any searches on subjects contained in the index are much faster than
searches which depend on data not in the index.  The index contains
single-line entries for the following fields, in order, separated by
colons (':') except for '>Category:' and '>Number:', which are separated
by a slash ('/') (the '>' and ':' Problem Report fieldname delimiters
have been removed for the sake of brevity and readability)::

     Category       Number         Submitter-Id
     Responsible    State          Confidential
     Severity       Priority

   To see an example index, run 'gen-index' without any options (see
Regenerating the index).

3.3.2 The 'current' file
------------------------

This file contains the last serial number assigned to an incoming PR. It
is used internally by GNATS; you need never touch this file.

3.4 Administrative utilities
============================

These tools are used by the GNATS administrator as part of the periodic
maintenance and configuration of GNATS.  See GNATS Administration.

3.4.1 Adding a problem category
-------------------------------

To add new categories to the database:

  1. Add a line to the 'categories' file under 'GNATS_ROOT/gnats-adm'
     for each new category.  See The 'categories' file.

  2. Run 'mkcat'.  'mkcat' creates a directory under GNATS_ROOT for any
     new categories which appear in the 'categories' file.  'mkcat' also
     recreates the list of valid categories for both your locally
     installed 'send-pr' and for the 'send-pr' distribution template in
     'PREFIX/lib/gnats/dist' (see Where GNATS lives.

   _Note:_ 'mkcat' does not update the categories list for other
machines on your network which have 'send-pr' installed (unless the two
machines share the directory PREFIX).  See Managing GNATS over a network.

   It is also important to note that only your local 'send-pr' has
access to this new information; any copies of 'send-pr' which you have
distributed to outside submitters now have outdated category lists.  You
must either contact your submitters and instruct them to update their
copy of the categories list, which they installed in
'PREFIX/lib/gnats/SUPPORT-SITE' (_Note:_ the value for PREFIX may be
different from yours) from the distribution you provided, or you must
build another distribution of 'send-pr' with this new information and
redistribute it (see Configuring 'send-pr' for the outside world).

3.4.2 Removing a problem category
---------------------------------

To remove a category from the database:

  1. Remove the Problem Reports from the subdirectories corresponding to
     the categories you wish to remove, or assign the PRs to new
     categories.  All PRs for a given category reside in
     'GNATS_ROOT/CATEGORY'.  Make sure you do this for each category you
     wish to remove.

  2. Run 'rmcat' using

          rmcat CATEGORY [ CATEGORY... ]

     where CATEGORY is the category you wish to remove.  You can specify
     as many categories as you wish as long as each category has no PRs
     associated with it.  'rmcat' removes the directory under GNATS_ROOT
     where the Problem Reports for that category had been stored.
     'rmcat' also deletes the category from the list of valid categories
     for both your locally installed 'send-pr' and for the 'send-pr'
     distribution template in 'PREFIX/lib/gnats/dist' (see Where GNATS lives).

   _Note:_ 'rmcat' does not update the categories list for other
machines on your network which have 'send-pr' installed.  See Managing GNATS over a network.

   It is also important to note that only your local 'send-pr' has
access to this new information; any copies of 'send-pr' which you have
distributed to outside submitters now have outdated category lists.  You
must either contact your submitters and instruct them to update their
copy of the categories list, which they installed in
'PREFIX/lib/gnats/SUPPORT-SITE' (_Note:_ the value for PREFIX may be
different from yours) from the distribution you provided, or you must
build another distribution of 'send-pr' with this new information and
redistribute it (see Configuring 'send-pr' for the outside world).

3.4.3 Regenerating the index
----------------------------

If your 'index' file becomes corrupted, or if you need a copy of the
current index for some reason, use

     gen-index [ -n | --numeric ]
               [ -d DIRECTORY | --directory=DIRECTORY ]
     	  [ -c FILENAME | --catfile=FILENAME ]
               [ -o FILENAME | --outfile=FILENAME ]
               [ -h | --help] [ -V | --version ]

With no options, 'gen-index' generates an index that is ordered the same
as the order of the categories as they appear in the 'categories' file,
and prints it to standard output.  The options are:

'-n'
'--numeric'
     Sorts index entries numerically.

'-d DIRECTORY'
'--directory=DIRECTORY'
     Uses DIRECTORY as the directory containing the database, by default
     GNATS_ROOT (see Where GNATS lives).

'-o FILENAME'
'--outfile=FILENAME'
     Places output in FILENAME rather than sending it to standard
     output.

'-c FILENAME'
'--catfile=FILENAME'
     Point to FILENAME, the file listing the valid categories.

'-h'
'--help'
     Prints the usage for 'gen-index'.

'-V'
'--version'
     Prints the version number for 'gen-index'.

3.4.4 Configuring 'send-pr' for the outside world
-------------------------------------------------

Now that GNATS is up and running on your system, you probably want to
distribute 'send-pr' to all your friends, relatives, enemies, etc.  so
they can more easily submit bugs to your organization.  To do this,
create a new directory DIST-DIRECTORY to hold the distribution.  Then
run the program

     mkdist --release=RELEASE DIST-DIRECTORY

This populates DIST-DIRECTORY with a full distribution of the program
'send-pr', including a 'Makefile' and all the 'send-pr' documentation.
You can then simply package up this directory and send it to your bug
report submitters.  For example, when logged in as 'gnats' you can do
the following:

     mkdir new-dist
     mkdist --release=tools-1.2 new-dist
     tar cvf send-pr.tar new-dist

   This creates a file called 'send-pr.tar' which contains a full
distribution of 'send-pr' customized for your site, with a default
release number of 'tools-1.2'.  You can then place this onto a disk or
tape and send it to your submitters, or instruct your submitters to
download it using 'ftp'.

   If you only have one submitter, you can set the Submitter ID in the
send-pr script by specifying the -submitter option to mkdist.  If you do
this, the submitter will not have to run install-sid.

3.5 Internal utilities
======================

These tools are used internally by GNATS.  You should never need to run
these by hand; however, a complete understanding may help you locate
problems with the GNATS tools or with your local implementation.

3.5.1 Handling incoming traffic
-------------------------------

The program 'queue-pr' handles traffic coming into GNATS.  'queue-pr'
queues incoming Problem Reports in the directory
'GNATS_ROOT/gnats-queue', and then periodically (via 'cron') passes them
on to 'file-pr' to be filed in the GNATS database.  See Installing GNATS.

   The usage for 'queue-pr' is as follows:

     queue-pr [ -q | --queue ] [ -r | --run ]
              [ -f FILENAME | --file=FILENAME ]
              [ -d DIRECTORY | --directory=DIRECTORY ]

   One of '-q' or '-r' (or their longer-named counterparts) must be
present upon each call to 'queue-pr'.  These options provide different
functions, as described below.

'-q'
'--queue'
     Accepts standard input as an incoming mail message, placing this
     message in an incrementally numbered file in the 'gnats-queue'
     directory under 'GNATS_ROOT' (see Where GNATS lives).

'-r'
'--run'
     Redirects files in the 'gnats-queue' directory into the program
     'file-pr' one by one.

'-f FILENAME'
'--file=FILENAME'
     Used with '-q' (or '--queue'), accepts the file denoted by FILENAME
     as input rather than reading from standard input.

'-d DIRECTORY'
'--directory=DIRECTORY'
     Resets the default DIRECTORY value, which is by default
     'GNATS_ROOT/gnats-queue'.  When '-d DIRECTORY' is used in
     conjunction with the '-q' (or '--queue') option, 'queue-pr' files
     incoming messages into DIRECTORY rather than the 'gnats-queue'
     directory.  When '-d DIRECTORY' is used in conjunction with the
     '-r' (or '--run') option, 'queue-pr' redirects into 'file-pr' files
     from DIRECTORY rather than from the 'gnats-queue' directory.

3.5.2 Processing incoming traffic
---------------------------------

'queue-pr' hands off queued Problem Reports to 'file-pr' one at a time.
'file-pr' checks each Problem Report for correct information in its
fields (particularly a correct '>Category:'), assigns it an
identification number, and files it in the database under the
appropriate category.

   If the '>Category:' field does not contain a valid category value
(i.e., matching a line in the 'categories' file; see The 'categories' file),
the PR is given a '>Category:' value of 'pending'
and is placed in the 'pending' directory.  The GNATS administrator is
notified of the unplaceable PR.

   'file-pr' assigns the Problem Report an identification number, files
it in the GNATS database (under 'pending', if the '>Category:' field
contains an invalid category), and sends acknowledgements to appropriate
parties.  The person responsible for that category of problem (see The 'categories' file)
and the person responsible for the
submitter site where the PR originated (see The 'submitters' file)
receive a copy of the PR in its entirety.  Optionally, the
originator of the PR receives an acknowledgement that the PR arrived and
was filed (see Changing your local configuration).

   The usage for 'file-pr' is as follows:

     file-pr [ -f FILENAME | --file=FILENAME ]
             [ -d DIRECTORY | --directory=DIRECTORYb ]
     	[ -D | --debug ] [ -h | --help ] [ -V | --version ]

   'file-pr' requires no options in order to operate, and takes input
from standard input (normally, the output of 'queue-pr -r') unless
otherwise specified.  The options include:

'-f FILENAME'
'--filename=FILENAME'
     Uses FILENAME as input rather than standard input.

'-d DIRECTORY'
'--directory=DIRECTORY'
     Performs refiling operations in DIRECTORY rather than in
     'GNATS_ROOT'.

'-D'
'--debug'
     Give debugging output while 'file-pr' is running.

'-h'
'--help'
     Prints the usage for 'file-pr'.

'-V'
'--version'
     Prints the version number for 'file-pr'.

3.5.3 Timely reminders
----------------------

'at-pr' creates a queued job using 'at' which, after an allotted
"response time" is past, checks the PR to see if its state has changed
from 'open'.

   The 'submitters' file contains the response time for each
'>Submitter-Id:' (see The 'submitters' file).  The time
is determined in "business hours", which are defined by default as
8:00am to 5:00pm Monday through Friday, local time.  These hours are
defined in the 'config' file (see The 'config' file).

   If the PR is still open after the requisite time period has passed,
'at-pr' sends a reminder to the GNATS administrator, to the maintainer
responsible for that submitter, and to the maintainer responsible for
the PR with the following message:

     To: SUBMITTER-CONTACT RESPONSIBLE GNATS-ADMIN
     Subject: PR GNATS-ID not analyzed in #HOURS hours

     PR GNATS-ID was not analyzed within the acknowledgment period
     of #HOURS business hours.  The pertinent information is:

      Submitter-Id: SUBMITTER
      Originator: FULL NAME OF THE SUBMITTER
      Synopsis: SYNOPSIS
      Person responsible for the PR: RESPONSIBLE

     --
     The GNU Problem Report Management System (GNATS)

3.5.4 The 'edit-pr' driver
--------------------------

'pr-edit' does the background work for 'edit-pr', including
error-checking and refiling newly edited Problem Reports and handling
file locks.  It can be called interactively, though it has no useable
editing interface.

   The usage for 'pr-edit' is:

     pr-edit [ -l MAINTAINER --lock=MAINTAINER ]
             [ -u | --unlock ] [ -c | --check ] [ -F ]
     	[ -L | --lockdb ] [ -U | --unlockdb ]
             [ -f FILENAME | --filename=FILENAME ]
             [ -d DIRECTORY | --directory=DIRECTORY ]
             [ -h | --help ] [ -V | --version ]
             [ GNATS-ID ]

   A "lock" is placed on a Problem Report while the PR is being edited.
The lock is simply a file in the same directory as the PR, with the name
'GNATS-ID.lock', which contains the name of the maintainer who created
the lock.  MAINTAINER then "owns" the lock, and must remove it before
the PR can be locked again, even by the same MAINTAINER(1).  If a PR is
already locked when you attempt to edit it, 'pr-edit' prints an error
message giving the name of the maintainer who is currently editing the
PR.

   If you do not specify GNATS-ID, 'pr-edit' reads from standard input.
You must specify GNATS-ID for the functions which affect PR locks,
'--lock=MAINTAINER' and '--unlock'.

'-l MAINTAINER'
'--lock=MAINTAINER'
     Locks Problem Report GNATS-ID, failing (and returning an error
     message) if GNATS-ID is already locked, or if GNATS-ID does not
     exist.  'pr-edit' requires that you specify GNATS-ID when using
     this option.

'-u'
'--unlock'
     Unlocks Problem Report GNATS-ID.  'pr-edit' requires that you
     specify GNATS-ID when using this option.  You must own a file lock
     to remove it.

'-L'
'--lockdb'
     Locks the GNATS database as a whole.  This will prevent any
     modification to any part of the system while it's locked.

'-U'
'--unlockdb'
     Unlocks the GNATS database as a whole, allowing modification of its
     files.

'-c'
'--check'
     Checks the Problem Report in GNATS-ID (or standard input, if
     GNATS-ID is not present) for correct information in its ENUMERATED
     fields.  'pr-edit' complains about any bogus information in the
     Problem Report.

'-F'
     Forces the PR to be submitted to the database, even if there is no
     current index entry for it (i.e., even if the PR did not exist in
     the database previously).

     _Warning: using this option may corrupt your index._  If you use
     it, be sure you know what you are doing.

'-f FILENAME'
'--filename=FILENAME'
     Reads FILENAME rather than standard input.

'-d DIRECTORY'
'--directory=DIRECTORY'
     Resets the operating directory ('GNATS_ROOT').

'-h'
'--help'
     Prints the usage for 'pr-edit'.

'-V'
'--version'
     Prints the version number for 'pr-edit'.

   ---------- Footnotes ----------

   (1) This approach may seem heavy-handed, but it ensures that changes
are not overwritten.

3.5.5 Address retrieval
-----------------------

Returns an electronic mail address when given a valid "nametag", as it
appears in the 'responsible' file (see The 'responsible' file).
If NAMETAG is not valid, 'pr-addr' will tell the user
that it could not find the requested address.

   Usage is simply:

     pr-addr NAME

Appendix A Installing GNATS
***************************

See Where the tools and utilities reside.

   There are several steps you need to follow to fully configure and
install GNATS on your system.  You need 'root' access in order to create
a new account for 'gnats' and to install the GNATS utilities.  You may
need 'root' access on some systems in order to set mail aliases in place
and to allow this new account access to 'cron' and 'at'.

   If you are updating an older version of GNATS rather than installing
from scratch, see Upgrading from older versions.

   To build GNATS, you must:

   * Run 'configure', with correct options if the defaults are
     unsuitable for your site.  See Configuring and compiling the software.
     Default installation locations are
     in Where GNATS lives.

   * Compile the GNATS programs on your system.  See Configuring and compiling the software.

   * Install the GNATS tools and utilities locally, and install the user
     tools on every machine in your local network.  See Installing the utilities.

   * Set up mail aliases for GNATS.  See Setting up mail aliases.

   * Install the GNATS user tools ('query-pr', 'nquery-pr', 'edit-pr',
     'send-pr') around your network.  See Installing the user tools.

   * Install the GNATS daemon 'gnatsd'.

   * Update the local configuration files

          config      categories  submitters  responsible  gnatsd.conf

     in 'GNATS_ROOT/gnats-adm'.  See Changing your local configuration.

   * Create a distribution of 'send-pr' for submitters outside your
     organization.  See Configuring 'send-pr' for the outside world.

A.1 Configuring and compiling the software
==========================================

  1. First, unpack your distribution.  We provide source code in a 'tar'
     file which was compressed using 'gzip'.  The code can be extracted
     into a directory UNPACKDIR using

          mkdir UNPACKDIR
          cd UNPACKDIR
          tar zxvf gnats-3.101.tar.z

     The sources reside in a directory called 'gnats-3.101' when
     unpacked.  We call this the "top level" of the source directory, or
     "srcdir".  The sources for the GNATS tools are in the subdirectory
     'gnats-3.101/gnats/*'.  Lists of files included in the distribution
     are in each directory in the file 'MANIFEST'.

  2. You may wish to alter the installation directory for the Emacs lisp
     files.  If your Emacs lisp library is not in
     'PREFIX/lib/emacs/lisp', edit the files

          SRCDIR/gnats/Makefile.in   _and_
          SRCDIR/send-pr/Makefile.in

     Change the variable 'lispdir' from '$(datadir)/emacs/lisp' to the
     directory containing your Emacs lisp library.  For information on
     PREFIX, see PREFIX.

  3. Run 'configure'.  You can nearly always run 'configure' with the
     command

          ./configure --with-full-gnats

     and the "Right Thing" happens:

        * GNATS is configured in the same directory you unpacked it in;

        * when built, GNATS runs on the machine you're building it on;

        * when installed, files are installed under '/usr/local' (see
          Where GNATS lives).

        * GNATS operates by default behavior (see Default behavior).

     The full usage for 'configure' is:

          configure [ --with-full-gnats ]
                    [ --prefix=PREFIX ]
                    [ --exec-prefix=EXEC-PREFIX ]
                    [ --with-gnats-root=GNATS_ROOT ]
                    [ --with-gnats-server=HOSTNAME ]
                    [ --with-gnats-service=SERVICE-NAME ]
                    [ --with-gnats-user=USERNAME ]
                    [ --with-gnats-port=PORT-NUMBER ]
                    [ --verbose ]

     '--with-full-gnats'
          All programs are to be built; this includes the user
          utilities, the administrative utilities, and the internal
          utilities.  Use this when configuring the utilities for the
          machine where GNATS is to run.  Omit it when building only the
          user utilities for other machines on your network; see
          Installing the user tools.

     '--prefix=PREFIX'
          All host-independent programs and files are to be installed
          under PREFIX.  (Host-dependent programs and files are also
          installed in PREFIX by default.)  The default for PREFIX is
          '/usr/local'.  See Where GNATS lives.

     '--exec-prefix=EXEC-PREFIX'
          All host-dependent programs and files are to be installed
          under EXEC-PREFIX.  The default for EXEC-PREFIX is PREFIX.
          See Where GNATS lives.

     '--with-gnats-root=GNATS_ROOT'
          The database and its data files are to be installed into
          GNATS_ROOT.  The default for GNATS_ROOT is
          'PREFIX/lib/gnats/gnats-db'.  See Where GNATS lives.

     '--with-gnats-root=hostname'
          FIXME

     '--with-gnats-root=SERVICE-NAME'
          FIXME

     '--with-gnats-user=USERNAME'
          FIXME

     '--with-gnats-port=PORT-NUMBER'
          FIXME

     '--verbose'
          Give verbose output while 'configure' runs.

     See Using 'configure' (configure).

     You can build GNATS in a different directory (OBJDIR) from the
     source code by calling the 'configure' program from the new
     directory, as in

          mkdir OBJDIR
          cd OBJDIR
          SRCDIR/configure ...
          make all

     By default, 'configure' compiles the programs in the same directory
     as the sources (SRCDIR).  Emacs lisp files are byte-compiled if
     'make' can find Emacs on your local system.

  4. Run

          make all info

     from the directory where 'configure' created a 'Makefile'.  (This
     may not be the same directory as the source directory.)  These
     targets indicate:

     'all'
          Compile all programs

     'info'
          Create 'info' files using 'makeinfo'.

A.2 Installing the utilities
============================

The following steps are necessary for a complete installation.  You may
need 'root' access for these.

  1. Install the utilities by invoking

          make install install-info

     These targets indicate:

     'install'
          Installs all programs into their configured locations (see
          Where GNATS lives).

     'install-info'
          Installs 'info' files into their configured locations (see
          Where GNATS lives).

     After you have installed GNATS, you can remove the object files
     with

          make clean

  2. Place the following lines in the file 'default.el' in your Emacs
     lisp library, or instruct your local responsible parties to place
     the lines in their local editions of '.emacs':

          (autoload 'edit-pr "gnats"
             "Command to edit a problem report." t)
          (autoload 'view-pr "gnats"
             "Command to view a problem report." t)
          (autoload 'unlock-pr "gnats"
             "Unlock a problem report." t)
          (autoload 'query-pr "gnats"
             "Command to query information about problem reports." t)
          (autoload 'send-pr-mode "send-pr"
             "Major mode for sending problem reports." t)
          (autoload 'send-pr "send-pr"
             "Command to create and send a problem report." t)

     Emacs lisp files are byte-compiled if 'make' can find Emacs on your
     local system.

  3. Create an account for a user named GNATS.  This user must have an
     entry in the file '/etc/passwd'.  The home directory for this
     account should be the same directory you specified for GNATS_ROOT
     in the file 'Makefile.in'.  Also, the default 'PATH' for this user
     should contain 'EXEC-PREFIX/bin' and 'EXEC-PREFIX/lib/gnats'.

  4. Allow the new user 'gnats' access to 'cron' and 'at'.  To do this,
     add the name 'gnats' to the files 'cron.allow' and 'at.allow',
     which normally reside in the directory '/var/spool/cron'.  If these
     files do not exist, make sure 'gnats' does not appear in either of
     the files 'cron.deny' and 'at.deny' (in the same directory).

     For the following steps, log in as 'gnats'.

        * Edit the files 'categories', 'responsible', and 'submitters'
          in the directory 'GNATS_ROOT/gnats-adm' (see Changing your local configuration)
          to reflect your
          local needs.  Be sure to run 'mkcat' after you update the
          'categories' file (see Adding a new problem category).
          _Note:_ these templates are not installed if they
          already exist, i.e.  if you are upgrading.  See Upgrading from older versions.

        * If you wish to install the GNATS user tools on other machines
          on your network, see Installing the user tools.

  5. Create a 'crontab' entry that periodically runs the program
     'queue-pr' with the '--run' option.  For example, to run
     'queue-pr --run' every ten minutes, create a file called '.mycron'
     in the home directory of the user 'gnats' which contains the line:

          0,10,20,30,40,50 * * * * EXEC-PREFIX/lib/gnats/queue-pr --run

     (Specify the full path name for 'queue-pr'.)  Then run

          crontab .mycron

     See the 'man' pages for 'cron' and 'crontab' for details on using
     'cron'.

A.3 Setting up mail aliases
===========================

The following mail aliases must be placed in the file '/etc/aliases' on
the same machine where the GNATS tools are installed.  You may need
'root' access to add these aliases.

   * Create an alias for the GNATS administrator.  This address should
     point to the address of the person in charge of administrating
     GNATS:

          gnats-admin:  ADDRESS

   * Create an alias to redirect incoming Problem Reports.  This alias
     should redirect incoming mail via a "pipe" to the program
     'queue-pr -q'.  For example, if Problem Reports coming to your site
     are to arrive at the address 'bugs@your.company.com', create an
     alias to the effect of:

          bugs:  "| EXEC-PREFIX/lib/gnats/queue-pr -q"

     This places incoming Problem Reports in 'GNATS_ROOT/gnats-queue'.

   * Create an alias for your site.  This alias should be the same
     nametag indicated by the variable 'GNATS_SITE' in the file
     'GNATS_ROOT/gnats-adm/config' (see The 'config' file),
     with an added suffix '-gnats'.  This alias, 'GNATS_SITE-gnats',
     should point toward the local submission address.  For instance, if
     your site is Tofu Technologies, the presence of GNATS on your SITE
     would be aliased as the following (the previous example is also
     shown):

          bugs:  "| EXEC-PREFIX/lib/gnats/queue-pr -q"
          tofu-gnats: bugs

     The report submission utility 'send-pr' automatically appends the
     '-gnats' to any arguments you specify (see Submitting Problem Reports).
     The 'send-pr' which was installed when you
     typed 'make install' has a default argument of GNATS_SITE, your
     site, so that when your local users simply type 'send-pr' mail is
     sent to your local GNATS.  Part of the installation process a
     Submitter Site follows when installing 'send-pr' is to set up an
     alias for the Support Site from whom this submitter received
     'send-pr'.  In other words, anyone you distribute 'send-pr' to is
     instructed to make an alias

          tofu-gnats: bugs@tofu.com

   * You may also wish to forward a copy of each incoming Problem Report
     to a log.  This can be accomplished with something like:

          bug-q: "| EXEC-PREFIX/lib/gnats/queue-pr -q"
          bug-log:  GNATS_ROOT/gnats-adm/bugs.log
          bugs:      bug-q, bug-log

     This configuration archives incoming Problem Reports in the file
     'GNATS_ROOT/gnats-adm/bug.log', and also feeds them to the program
     'queue-pr'.  (Remember, 'bug.log' needs to be world-writable, and
     should be pruned regularly; see GNATS Administration)

   * If you want your users to be able to query the database by mail,
     use the following alias:

          query-pr: "| EXEC-PREFIX/lib/gnats/mail-query"

     The 'mail-query' program uses '--restricted' to search on the
     database, and by default only searches for PRs that aren't closed
     (see Querying the database).

A.4 Installing the daemon
=========================

By default, the daemon and clients are set to use port 1529.  Add the
line

     support		1529/tcp			# GNATS

to your '/etc/services' file.  If you want a different port, or a
different service name or port, configure GNATS with

     --with-gnats-service=SERVICENAME
     --with-gnats-port=PORTNUMBER

   In your 'inetd.conf' file, add the line

     support	stream	tcp	nowait	gnats	/usr/local/lib/gnats/gnatsd gnatsd

adjusting the path accordingly.  To make inetd start spawning the GNATS
daemon when connected on that port, send it a hangup signal ('HUP').

   By default, the server for the GNATS daemon is assumed to be one with
the name of 'gnats'.  If you'd like something else, use

     --with-gnats-server=HOSTNAME

   In the 'gnats-adm' directory, you'll want to edit 'gnatsd.conf'.  It
lists the hosts allowed to access your server.  Or, if you're using
Kerberos, it shows the sites that don't require Kerberos authentication.
The format is reserved for future revision; only the first field is
actually used:

     site.com::

The second field may be used for things like controlling what
categories, submitter-id'd PRs, etc., can be accessed from that site.
In the file that logs syslog messages ('/var/adm/messages', for example)
you'll find the notification of denied access.

A.5 Installing the user tools
=============================

When you install the GNATS utilities, the user tools are installed by
default on the host machine.  If your machine is part of a network,
however, you may wish to install the user tools on each machine in the
network so that responsible parties on those machines can submit new
Problem Reports, query the database, and edit existing PRs.  To do this,
follow these steps _on each new host_.  You may need root access on each
machine.

  1. Make sure that the directory where GNATS resides is mounted to each
     system that will need access to it, so GNATS_ROOT will be the same
     for each host.  (You can do this with symbolic links as well.)

  2. Either mount the disk which contains your source directory, or make
     a copy of the GNATS source code tree in a separate directory on
     each system you wish to build on.

  3. Run 'configure', _without_ specifying '--with-full-gnats', and
     using the same argument (if any) for the option

          --with-gnats-root=GNATS_ROOT

     that you specified when building the GNATS utilites (see
     Configuring and compiling the software).  You
     may use different values for the other options to 'configure'.
     Again, _do not_ use '--with-full-gnats' at this point, as that
     creates all the GNATS programs.  Without this option, 'configure'
     only instructs the resulting 'Makefile' to create the user
     utilities.

     _You may need 'root' access on each host for the following steps._

  4. Create an account for a user named GNATS on the new host.  This
     user must have an entry in the file '/etc/passwd'.  The user ID for
     'gnats' must be the same as on the main GNATS host.

  5. Run

          make all info install install-info

     This builds and installs the 'gnats' user tools 'query-pr',
     'edit-pr', and 'send-pr' on the new host, and installs them in
     'EXEC-PREFIX/bin' on the new host (_Note:_ the value for
     EXEC-PREFIX on the new host may be different from the value you
     used when building the GNATS utilities; see EXEC-PREFIX).
     The programs 'pr-edit' and 'pr-addr' are installed
     into 'EXEC-PREFIX/lib/gnats'.

     'info' files are created as well, and are installed into
     'PREFIX/info'.  The Elisp files 'gnats.el' and 'send-pr.el' (and
     possibly 'gnats.elc' if 'make' was able to compile them using
     Emacs) are installed into 'PREFIX/lib/emacs/lisp' unless you change
     the 'lispdir' variable in 'Makefile.in' (see Configuring and compiling the software).

  6. Add the following lines to the file 'default.el' in the Emacs lisp
     repository on the new host, or instruct your responsible parties
     who use these hosts to add them to their '.emacs' files:

          (autoload 'edit-pr "gnats"
             "Command to edit a problem report." t)
          (autoload 'view-pr "gnats"
             "Command to view a problem report." t)
          (autoload 'unlock-pr "gnats"
             "Unlock a problem report." t)
          (autoload 'query-pr "gnats"
             "Command to query information about problem reports." t)
          (autoload 'send-pr-mode "send-pr"
             "Major mode for sending problem reports." t)
          (autoload 'send-pr "send-pr"
             "Command to create and send a problem report." t)

  7. Copy the file 'PREFIX/lib/gnats/SITE' from the original host to the
     new host (which may have a different value for PREFIX).  This is
     the list of valid categories that 'send-pr' uses (see Where GNATS lives).
     SITE is your local site, the value of
     'GNATS_SITE' in the 'config' file (see The 'config' file).

A.6 Upgrading from older versions
=================================

If you are upgrading from a previous release of GNATS, you probably do
not want to delete your current configuration files or your current
database.  The new GNATS can be installed around the older version.

   You need to:

   * Specify your current GNATS_ROOT on the command line to 'configure'
     when you build the new tools, with

          configure --with-full-gnats --with-gnats-root=GNATS_ROOT

     (see Configuring and compiling the software.)

   * Remove the directory 'gnats-bin' from GNATS_ROOT; it is no longer
     used.

   * Update your current mail aliases to reflect that 'queue-pr' now
     resides in 'EXEC-PREFIX/lib/gnats' rather than
     'GNATS_ROOT/gnats-bin' (see Where GNATS lives).

   * Change the default 'PATH' for the 'gnats' user to search the
     directories 'EXEC-PREFIX/bin' and 'EXEC-PREFIX/lib/gnats'.

   * Reinstall the GNATS user tools on all other hosts on your network
     (see Installing the user tools).

   * Redistribute 'send-pr' to your Submitter Sites (see Configuring 'send-pr' for the outside world).
     This is not absolutely
     necessary, as GNATS can read Problem Reports generated by older
     versions of 'send-pr'.  It should be done eventually, however, as
     'send-pr' is improved over older verisons.

Appendix B Where GNATS lives
****************************

We use a few conventions when referring to the installation structure
GNATS uses.  These values are adjustable when you build and install
GNATS (see Installing GNATS).

B.1 PREFIX
==========

PREFIX corresponds to the variable 'prefix' for 'configure', which
passes it on to the 'Makefile' it creates.  PREFIX sets the root
installation directory for "host-independent" files as follows:

libraries
     'PREFIX/lib'

'man' pages
     'PREFIX/man'

'info' documents
     'PREFIX/info'

'include' files
     'PREFIX/include'

_etc..._

   The default value for PREFIX is '/usr/local', which can be changed on
the command line to 'configure' using

     configure --prefix=PREFIX ...

See Configuring and compiling the software.

B.2 EXEC-PREFIX
===============

EXEC-PREFIX corresponds to the variable 'exec_prefix' for 'configure',
which passes it on to the 'Makefile' it creates.  EXEC-PREFIX sets the
root installation for "host-dependent" files as follows:

binary tools
     'EXEC-PREFIX/bin'

binary support utilities
     'EXEC-PREFIX/lib/gnats'

compiled libraries
     'EXEC-PREFIX/lib'

_etc..._

   Since most installations are not intended to be distributed around a
network, the default value for EXEC-PREFIX is the value of 'prefix',
i.e., '/usr/local'.  However, using EXEC-PREFIX saves space when you are
installing a package on several different platforms for which many files
are identical; rather than duplicate them for each host, these files can
be shared in a common repository, and you can use symbolic links on each
host to find the host-dependent files.  _It is not necessary to use this
paradigm when building the GNATS tools_.  See Configuring and compiling the software.

   Use EXEC-PREFIX in conjunction with PREFIX to share host-independent
files, like libraries and 'info' documents.  For example:

        _for each host:_
     configure --prefix=/usr/gnu --exec-prefix=/usr/gnu/H-HOST
     make all install ...

Using this paradigm, all host-dependent binary files are installed into
'/usr/gnu/H-HOST/bin', while files which do not depend on the host type
for which they were configured are installed into '/usr/gnu'.

   You can then use a different symbolic link for '/usr/gnu' on each
host ('/usr' is usually specific to a particular machine; it is always
specific to a particular architecture).

       _on host-1:_
     ln -s /usr/gnu/H-HOST-1 /usr/gnu
       _on host-2:_
     ln -s /usr/gnu/H-HOST-2 /usr/gnu

To the end user, then, placing '/usr/gnu/bin' in her or his 'PATH'
simply works transparently for each HOST type.

   You can change EXEC-PREFIX on the command line to 'configure' using

     configure --exec-prefix=EXEC-PREFIX ...

   We recommend that you consult Using 'configure' (configure),
before attempting this.  Again, _it is not
necessary to use this paradigm when building the GNATS tools_.

B.3 GNATS_ROOT
==============

The location of the database and the administrative data files, by
default 'PREFIX/lib/gnats/gnats-db'.  You can change this value on the
command line to 'configure' using

     configure --with-gnats-root=GNATS_ROOT

Administrative data files reside in 'GNATS_ROOT/gnats-adm'.  These
include 'categories', 'submitters', 'responsible', and 'config', as well
as two files generated and maintained by GNATS, 'index' and 'current'.
See Changing your local configuration, and
Administrative data files.

B.4 Default installation locations
==================================

PREFIX
     defaults to '/usr/local'; change using 'configure' (see
     Configuring and compiling the software).

EXEC-PREFIX
     defaults to PREFIX; change using 'configure' (see Configuring and compiling the software).

GNATS_ROOT
     defaults to 'PREFIX/lib/gnats/gnats-db'; change using 'configure'
     (see Configuring and compiling the software).

GNATS installs tools, utilities, and files into the following locations.

'EXEC-PREFIX/bin'

     'send-pr'
          See Submitting Problem Reports.
     'edit-pr'
          See Editing existing Problem Reports.
     'query-pr'
          See Querying the database.
     'nquery-pr'
          See Querying the database over the network.

'EXEC-PREFIX/lib/gnats'

     'mkcat'
          See Adding a problem category.
     'rmcat'
          See Removing a problem category.
     'mkdist'
          See Configuring 'send-pr' for the outside world.
     'gen-index'
          See Regenerating the index.
     'queue-pr'
          See Handling incoming traffic.
     'file-pr'
          See Processing incoming traffic.
     'at-pr'
          See Timely reminders.
     'pr-edit'
          See The 'edit-pr' driver.
     'pr-addr'
          See Address retrieval.
     'libiberty.a'
          The GNU 'libiberty' library.

'PREFIX/lib/gnats/dist'

     A packageable distribution of 'send-pr'.
          See Configuring 'send-pr' for the outside world.

'PREFIX/lib/gnats'

     SITE
          The local list of valid categories, used by 'send-pr'; SITE is
          the value of 'GNATS_SITE' (see The 'config' file).

'PREFIX/lib/emacs/lisp'

     'gnats.el'
     'gnats.elc'
          The Emacs versions of the programs 'query-pr', 'edit-pr', and
          'view-pr'.  See Invoking the GNATS tools.
          To change this directory you must alter 'Makefile.in';
          see Configuring and compiling the software.
     'send-pr.el'
          The Emacs version of the program 'send-pr'.  See Submitting Problem Reports.

'PREFIX/info'

     'gnats.info'
     'send-pr.info'
          The GNATS manuals, in a form readable by 'info' (the GNU
          hypertext browser).  See Reading GNU Online Documentation (infoman).

'PREFIX/man/man1'
'PREFIX/man/man8'

     'man' pages for all the GNATS tools and utilities.
          See Invoking the GNATS tools.

'PREFIX/src'

     Source code for GNATS.

'PREFIX/sample'

     Example administrative files, including 'categories',
          'submitters', 'responsible', and 'config'.  See Changing your local configuration.

'GNATS_ROOT'

     'gnats-adm'
          Administration and configuration data files.  The files
          'config'
          'categories'
          'submitters'
          'responsible'
          'gnatsd.conf'
          'index'
               (_This file is created by GNATS._)
          'current'
               (_This file is created by GNATS._)
          exist here.  See Changing your local configuration,
          and Administrative data files.
     'gnats-queue'
          Incoming Problem Reports are queued here until the next
          iteration of 'queue-pr -r' (see Handling incoming traffic).
     'pending'
          Problem Reports which arrive without a valid category value
          are reassigned to the category 'pending' and placed here
          pending intervention by the GNATS administrator.  See GNATS administration.
     'CATEGORY'
          Each valid category has a corresponding subdirectory in the
          database.  All Problem Reports associated with that category
          are kept in that subdirectory, along with lock files for PRs
          which are being edited.

Appendix C Querying using regular expressions
*********************************************

GNATS uses GNU regular expression syntax with these settings:

     RE_SYNTAX_POSIX_EXTENDED | RE_BK_PLUS_QM & RE_DOT_NEWLINE

This means that parentheses ('(' and ')') and pipe symbols ('|') do not
need to be used with the escape symbol '\'.  The tokens '+' and '?' do
need the escape symbol, however.

   Unfortunately, we do not have room in this manual for an adequate
tutorial on regular expressions.  The following is a basic summary of
some regular expressions you might wish to use.

   See Regular Expression Syntax (regex),
for details on regular expression syntax.  Also see Syntax of Regular Expressions (emacs),
but beware that the syntax for
regular expressions in Emacs is slightly different.

   All search criteria options to 'query-pr' rely on regular expression
syntax to construct their search patterns.  For example,

     query-pr --state=open

matches all PRs whose '>State:' values match with the regular expression
'open'.

   We can substitute the expression 'o' for 'open', according to GNU
regular expression syntax.  This matches all values of '>State:' which
begin with the letter 'o'.

     query-pr --state=o

   is equivalent to

     query-pr --state=open

in this case, since the only value for '>State:' which matches the
expression 'o' is 'open'.  (Double quotes ('"') are used to protect the
asterix ('*') from the shell.)  '--state=o' also matches 'o', 'oswald',
and even 'oooooo', but none of those values are valid states for a
Problem Report.

   Regular expression syntax considers a regexp token surrounded with
parentheses, as in '(REGEXP)', to be a "group".  This means that '(ab)*'
matches any number of contiguous instances of 'ab', including zero.
Matches include '', 'ab', and 'ababab'.

   Regular expression syntax considers a regexp token surrounded with
square brackets, as in '[REGEXP]', to be a "list".  This means that
'Char[(ley)(lene)(broiled)' matches any of the words 'Charley',
'Charlene', or 'Charbroiled' (case is significant; 'charbroiled' is not
matched).

   Using groups and lists, we see that

     query-pr --category="gcc|gdb|gas"

is equivalent to

     query-pr --category="g(cc|db|as)"

and is also very similar to

     query-pr --category="g[cda]"

with the exception that this last search matches any values which begin
with 'gc', 'gd', or 'ga'.

   The '.' character is known as a "wildcard".  '.' matches on any
single character.  '*' matches the previous character (except newlines),
list, or group any number of times, including zero.  Therefore, we can
understand '.*' to mean "match zero or more instances of any character."
For this reason, we never specify it at the end of a regular expression,
as that would be redundant.  The expression 'o' matches any instance of
the letter 'o' (followed by anything) at the beginning of a line, while
the expression 'o.*' matches any instance of the letter 'o' at the
beginning of a line followed by any number (including zero) of any
characters.

   We can also use the expression operator '|' to signify a logical
'OR', such that

     query-pr --state="o|a"

matches all 'open' or 'analyzed' Problem Reports.  (Double quotes ('"')
are used to protect the pipe symbol ('|') from the shell.)

   By the same token,(1) using

     query-pr --state=".*a"

matches all values for '>State:' which contain an 'a'.  (These include
'analyzed' and 'feedback'.)

   Another way to understand what wildcards do is to follow them on
their search for matching text.  By our syntax, '.*' matches any
character any number of times, including zero.  Therefore, '.*a'
searches for any group of characters which end with 'a', ignoring the
rest of the field.  '.*a' matches 'analyzed' (stopping at the first 'a')
as well as 'feedback'.

   _Note:_ When using '--text' or '--multitext', you do not have to
specify the token '.*' at the beginning of TEXT to match the entire
field.  For the technically minded, this is because '--text' and
'--multitext' use 're_search' rather than 're_match'.  're_match'
"anchors" the search at the beginning of the field, while 're_search'
does not anchor the search.

   For example, to search in the '>Description:' field for the text

     The defrobulator component returns a nil value.

we can use

     query-pr --multitext="defrobulator.*nil"

   To also match newlines, we have to include the expression '(.|^M)'
instead of just a dot ('.').  '(.|^M)' matches "any single character
except a newline ('.') _or_ ('|') any newline ('^M')."  This means that
to search for the text

     The defrobulator component enters the bifrabulator routine
     and returns a nil value.

we must use

     query-pr --multitext="defrobulator(.|^M)*nil"

   To generate the newline character '^M', type the following depending
on your shell:

'csh'
     '_control_-V _control_-M'

'tcsh'
     '_control_-V _control_-J'

'sh (_or_ bash)'
     Use the <RETURN> key, as in

          (.|
          )

   Again, see Regular Expression Syntax (regex),
for a much more complete discussion on regular expression
syntax.

   ---------- Footnotes ----------

   (1) No pun intended.