This is ../../info/gnats.info, produced by makeinfo version 4.6 from
gnats.texi.

START-INFO-DIR-ENTRY
* Keeping Track: (gnats).        GNU Problem Report Management System
END-INFO-DIR-ENTRY

   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.


File: gnats.info,  Node: Top,  Next: Introduction,  Up: (dir)

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 *Note The database paradigm: Paradigm.

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

* Menu:

* Introduction::          Introducing GNATS
* Invoking the tools::    Invoking the GNATS tools
* Management::            GNATS Administration
* Installation::          Installing GNATS
* Locations::             Where GNATS lives
* Regexps::               Querying using regular expressions
* Index::


File: gnats.info,  Node: Introduction,  Next: Invoking the tools,  Prev: Top,  Up: Top

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.

* Menu:

* Paradigm::       The database paradigm
* Flowchart::      Flowchart of GNATS activities
* States::         States of Problem Reports
* Fields::         Problem Report format


File: gnats.info,  Node: Paradigm,  Next: Flowchart,  Up: Introduction

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" (*note
GNATS data fields: 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".  *Note GNATS
administration: Management.

   Each PR is a separate file within a main repository (*note Where
GNATS lives: Locations.).  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 (*note The `index' file: 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 *Note Configuring
`send-pr' for the outside world: mkdist.

   At the Support Site, a GNATS "administrator" is charged with the
duty of maintaining GNATS.  These duties are discussed in detail in
*Note GNATS Administration: Management, 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.  *Note Changing your local configuration: 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 (*note GNATS Administration: Management.).

   Once a problem is recorded in the database, work can begin toward a
solution.  A problem's initial "state" is `open' (*note States of
Problem Reports: States.).  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.  (*Note Editing existing Problem Reports: edit-pr.  For
information on the `>Audit-Trail:' field, see *Note Problem Report
format: Fields.)

   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
*Note States of Problem Reports: States.)


File: gnats.info,  Node: Flowchart,  Next: States,  Prev: Paradigm,  Up: Introduction

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     ||#
     #     |+------------------------------------+|#
     #     +--------------------------------------+#
     +=============================================+




File: gnats.info,  Node: States,  Next: Fields,  Prev: Flowchart,  Up: Introduction

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.


File: gnats.info,  Node: Fields,  Prev: States,  Up: Introduction

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

* Menu:

* Mail header fields::
* Problem Report fields::


File: gnats.info,  Node: Mail header fields,  Next: Problem Report fields,  Up: Fields

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.  *Note Changing your local configuration: Local
configuration.


File: gnats.info,  Node: Problem Report fields,  Prev: Mail header fields,  Up: Fields

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
     (*note The `config' file: config.).

`>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.  *Note The `categories' file: categories, 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 *Note
     Helpful hints: 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; *note Changing your local
     configuration: 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'.  *Note States of Problem
     Reports: States.

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

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


File: gnats.info,  Node: Invoking the tools,  Next: Management,  Prev: Introduction,  Up: Top

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 (*note
     Submitting Problem Reports: send-pr.).

`query-pr'
     Used by software maintainers to query the GNATS database (*note
     Querying the database: query-pr.).

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

`view-pr'
     Used by software maintainers to view individual Problem Reports
     using Emacs (*note Viewing individual Problem Reports: view-pr.).

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

These tools are used by the GNATS administrator; see also *Note GNATS
Administration: Management.  For complete explanations of these
utilities, see *Note Administrative utilities: Admin utils.

`mkcat'
     Creates new categories (*note Adding a problem category: mkcat.).

`rmcat'
     Removes existing categories (*note Removing a problem category:
     rmcat.).

`gen-index'
     Generates an up-to-date copy of the index used by `query-pr' and
     `edit-pr' (*note The `index' file: 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 (*note Regenerating the
     index: gen-index.).

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

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 *Note
Internal utilities: Internal utils.

`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 *note Editing existing Problem Reports: edit-pr.).

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

   *Note Where GNATS lives: Locations.

* Menu:

* send-pr::           Submitting Problem Reports
* edit-pr::           Editing existing Problem Reports
* query-pr::          Querying the database
* view-pr::           Viewing individual Problem Reports


File: gnats.info,  Node: send-pr,  Next: edit-pr,  Up: Invoking the tools

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.

   *Note Configuring `send-pr' for the outside world: mkdist, 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'.

* Menu:

* using send-pr::             Creating new Problem Reports
* send-pr in Emacs::          Using send-pr from within Emacs
* send-pr from the shell::    Invoking send-pr from the shell
* Helpful hints::


File: gnats.info,  Node: using send-pr,  Next: send-pr in Emacs,  Up: send-pr

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.  (*Note
     Problem Report format: Fields.)

"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.  (*Note Problem
     Report format: Fields.  Also see *Note Helpful hints: Helpful
     hints.)

   The default template contains your preconfigured `>Submitter-Id:'.
`send-pr' attempts to determine values for the `>Originator:' and
`>Organization:' fields (*note Problem Report format: Fields.).
`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.  *Note Helpful hints: 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
(*note Problem Report format: Fields.), `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.


File: gnats.info,  Node: send-pr in Emacs,  Next: send-pr from the shell,  Prev: using send-pr,  Up: send-pr

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 (*note Introduction:
(emacs)Introduction.).

   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 *Note Introduction:
(emacs)Introduction.

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

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


File: gnats.info,  Node: send-pr from the shell,  Next: Helpful hints,  Prev: send-pr in Emacs,  Up: send-pr

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.


File: gnats.info,  Node: Helpful hints,  Prev: send-pr from the shell,  Up: send-pr

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 *Note Reporting Bugs: (gcc)Bugs, 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.


File: gnats.info,  Node: edit-pr,  Next: query-pr,  Prev: send-pr,  Up: Invoking the tools

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:' (*note Problem
Report format: Fields.).  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
(*note The `index' file: index file.).  For information on `pr-edit',
the main driver for `edit-pr', see *Note Internal utilities: Internal
utils.

* Menu:

* edit-pr in Emacs::        Using `edit-pr' from within Emacs
* edit-pr from the shell::  Invoking `edit-pr' from the shell


File: gnats.info,  Node: edit-pr in Emacs,  Next: edit-pr from the shell,  Up: edit-pr

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.


File: gnats.info,  Node: edit-pr from the shell,  Prev: edit-pr in Emacs,  Up: edit-pr

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.


File: gnats.info,  Node: query-pr,  Next: view-pr,  Prev: edit-pr,  Up: Invoking the tools

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

* Menu:

* Invoking query-pr::
* Example queries::
* Reporting::


File: gnats.info,  Node: Invoking query-pr,  Next: Example queries,  Up: query-pr

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 *Note Querying using regular expressions:
Regexps.

   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.  *Note
     Querying using regular expressions: Regexps.  Also see *Note
     Example queries: 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 (*note The `index' file: 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 (*note The `index' file: 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

     *Note Querying using regular expressions: Regexps.

     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
     (*note The `index' file: 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

     *Note Querying using regular expressions: Regexps.

     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 (*note The `index' file: 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 *Note Reporting on groups of Problem
     Reports: Reporting.

     `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.  *Note
     Reporting on groups of Problem Reports: Reporting, 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 *Note Reporting: Reporting.


File: gnats.info,  Node: Example queries,  Next: Reporting,  Prev: Invoking query-pr,  Up: query-pr

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' (*note Querying using regular expressions:
Regexps..  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 *Note Reporting on groups of Problem Reports:
Reporting.  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.  *Note Querying using regular
expressions: Regexps.


File: gnats.info,  Node: Reporting,  Prev: Example queries,  Up: query-pr

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.


File: gnats.info,  Node: view-pr,  Prev: query-pr,  Up: Invoking the tools

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


File: gnats.info,  Node: Management,  Next: Installation,  Prev: Invoking the tools,  Up: Top

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 (*note Where the
     tools and utilities reside: Locations.).  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.  *Note Adding a problem category: mkcat.  Also *Note The
     `categories' file: categories.

_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.  *Note Removing a problem category: rmcat.  Also *Note
     The `categories' file: categories.

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

_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'.  *Note
     Configuring `send-pr' for the outside world: mkdist.  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' (*note
     Regenerating the index: gen-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.
     (*Note Setting up mail aliases: 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.


   *Note Where GNATS lives: Locations.

* Menu:

* Networked management::  Managing GNATS over a network
* Local configuration::   Changing your local configuration
* Admin files::           Administrative data files
* Admin utils::           Administrative utilities
* Internal utils::        Internal utilities


File: gnats.info,  Node: Networked management,  Next: Local configuration,  Up: Management

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'
(*note The `config' file: config.).

   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, *note
Installing the user tools: Installing tools..


File: gnats.info,  Node: Local configuration,  Next: Admin files,  Prev: Networked management,  Up: Management

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

*Note Where GNATS lives: Locations.

   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.  *Note The `config'
     file: config.  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 *Note The `submitters' file:
          submitters, and *Note Timely Reminders: at-pr.

        * 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.  *Note The `categories' file:
     categories.  Also see *Note Adding a new problem category: mkcat,
     and *Note Removing a problem category: rmcat.

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

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

* Menu:

* default behavior::
* config::          The `config' file
* categories::      The `categories' file
* responsible::     The `responsible' file
* submitters::      The `submitters' file


File: gnats.info,  Node: default behavior,  Next: config,  Up: Local configuration

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.


File: gnats.info,  Node: config,  Next: categories,  Prev: default behavior,  Up: Local configuration

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' (*note Installing the utilities:
     Installing utils.).

     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.  *Note
     Installing the utilities: Installing utils.

     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
     (*note Setting up mail aliases: 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 *Note
     Timely Reminders: at-pr.

     This requisite time is determined for each submitter individually;
     see *Note The `submitters' file: submitters.  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 *Note The `submitters'
     file: submitters.

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



File: gnats.info,  Node: categories,  Next: responsible,  Prev: config,  Up: Local configuration

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 *Note Adding a problem category: mkcat.

   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 (*note The
     `responsible' file: responsible.).

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 (*note The
`responsible' file: responsible.).

   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' (*note Configuring and compiling the software: Configure
and make.).


File: gnats.info,  Node: responsible,  Next: submitters,  Prev: categories,  Up: Local configuration

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


File: gnats.info,  Node: submitters,  Prev: responsible,  Up: Local configuration

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 (*note Changing your local configuration: Local
     configuration.).  If `NOTIFY' is `0', this field is ignored.  For
     information on `at-pr', the program which sends out this reminder,
     see *Note Timely Reminders: at-pr.

CONTACT
     The name tag of the main "contact" at the Support Site for this
     submitter.  This contact should be in the `responsible' file
     (*note The `responsible' file: responsible.).  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 (*note The `config' file: config.), and instruct your submitters
to ignore the field.


File: gnats.info,  Node: Admin files,  Next: Admin utils,  Prev: Local configuration,  Up: Management

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.

* Menu:

* index file::      The `index' file
* current file::    The `current' file


File: gnats.info,  Node: index file,  Next: current file,  Up: Admin files

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 (*note
Regenerating the index: gen-index.).


File: gnats.info,  Node: current file,  Prev: index file,  Up: Admin files

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.


File: gnats.info,  Node: Admin utils,  Next: Internal utils,  Prev: Admin files,  Up: Management

Administrative utilities
========================

These tools are used by the GNATS administrator as part of the periodic
maintenance and configuration of GNATS.  *Note GNATS Administration:
Management.

* Menu:

* mkcat::       Adding a problem category
* rmcat::       Removing a problem category
* gen-index::   Regenerating the index
* mkdist::      Configuring send-pr for the outside world


File: gnats.info,  Node: mkcat,  Next: rmcat,  Up: Admin utils

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.  *Note The `categories' file: categories.

  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' (*note Where GNATS lives: Locations..

   _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).  *Note Managing GNATS over a
network: Networked management.

   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 (*note Configuring `send-pr' for the outside world:
mkdist.).


File: gnats.info,  Node: rmcat,  Next: gen-index,  Prev: mkcat,  Up: Admin utils

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' (*note
     Where GNATS lives: Locations.).

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

   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 (*note Configuring `send-pr' for the outside world:
mkdist.).


File: gnats.info,  Node: gen-index,  Next: mkdist,  Prev: rmcat,  Up: Admin utils

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 (*note Where GNATS lives: Locations.).

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


File: gnats.info,  Node: mkdist,  Prev: gen-index,  Up: Admin utils

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.


File: gnats.info,  Node: Internal utils,  Prev: Admin utils,  Up: Management

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.

* Menu:

* queue-pr::    Handling incoming traffic
* file-pr::     Processing incoming traffic
* at-pr::       Timely reminders
* pr-edit::     The edit-pr driver
* pr-addr::     Address retrieval


File: gnats.info,  Node: queue-pr,  Next: file-pr,  Up: Internal utils

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.  *Note
Installing GNATS: Installation.

   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' (*note Where GNATS lives: Locations.).

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


File: gnats.info,  Node: file-pr,  Next: at-pr,  Prev: queue-pr,  Up: Internal utils

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; *note The `categories'
file: categories.), 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 (*note The `categories' file: categories.) and the person
responsible for the submitter site where the PR originated (*note The
`submitters' file: submitters.) 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 (*note Changing your
local configuration: 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'.


File: gnats.info,  Node: at-pr,  Next: pr-edit,  Prev: file-pr,  Up: Internal utils

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:' (*note The `submitters' file: submitters.).  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 (*note The `config' file: config.).

   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)


File: gnats.info,  Node: pr-edit,  Next: pr-addr,  Prev: at-pr,  Up: Internal utils

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.


File: gnats.info,  Node: pr-addr,  Prev: pr-edit,  Up: Internal utils

Address retrieval
-----------------

Returns an electronic mail address when given a valid "nametag", as it
appears in the `responsible' file (*note The `responsible' file:
responsible.).  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


File: gnats.info,  Node: Installation,  Next: Locations,  Prev: Management,  Up: Top

Installing GNATS
****************

*Note Where the tools and utilities reside: Locations.

   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 *Note Upgrading from older versions: Upgrading.

   To build GNATS, you must:

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

   * Compile the GNATS programs on your system.  *Note Configuring and
     compiling the software: Configure and make.

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

   * Set up mail aliases for GNATS.  *Note Setting up mail aliases:
     Aliases.

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

   * Install the GNATS daemon `gnatsd'.

   * Update the local configuration files

          config      categories  submitters  responsible  gnatsd.conf

     in `GNATS_ROOT/gnats-adm'.  *Note Changing your local
     configuration: Local configuration.

   * Create a distribution of `send-pr' for submitters outside your
     organization.  *Note Configuring `send-pr' for the outside world:
     mkdist.

* Menu:

* Configure and make::    Configuring and compiling the software
* Installing utils::      Installing the utilities
* Aliases::               Setting up mail aliases
* Installing the daemon:: Installing the daemon
* Installing tools::      Installing the user tools
* Upgrading::             Upgrading from older versions


File: gnats.info,  Node: Configure and make,  Next: Installing utils,  Up: Installation

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 *Note PREFIX: 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' (*note
          Where GNATS lives: Locations.).

        * GNATS operates by default behavior (*note Default behavior:
          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
          *Note Installing the user tools: Installing 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'.  *Note Where GNATS lives: Locations.

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

    `--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'.  *Note Where GNATS lives:
          Locations.

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

     *Note Using `configure': (configure)Using 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'.


File: gnats.info,  Node: Installing utils,  Next: Aliases,  Prev: Configure and make,  Up: Installation

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 (*note
          Where GNATS lives: Locations.).

    `install-info'
          Installs `info' files into their configured locations (*note
          Where GNATS lives: Locations.).

     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' (*note Changing your
          local configuration: Local configuration.) to reflect your
          local needs.  Be sure to run `mkcat' after you update the
          `categories' file (*note Adding a new problem category:
          mkcat.).  _Note:_ these templates are not installed if they
          already exist, i.e. if you are upgrading.  *Note Upgrading
          from older versions: Upgrading.

        * If you wish to install the GNATS user tools on other machines
          on your network, see *Note Installing the user tools:
          Installing 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'.


File: gnats.info,  Node: Aliases,  Next: Installing the daemon,  Prev: Installing utils,  Up: Installation

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' (*note The `config' file: config.),
     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 (*note Submitting Problem
     Reports: send-pr.).  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; *note GNATS Administration:
     Management..)

   * 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
     (*note Querying the database: query-pr.).



File: gnats.info,  Node: Installing the daemon,  Next: Installing tools,  Prev: Aliases,  Up: Installation

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.


File: gnats.info,  Node: Installing tools,  Next: Upgrading,  Prev: Installing the daemon,  Up: Installation

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 (*note
     Configuring and compiling the software: Configure and make.).  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; *note EXEC-PREFIX:
     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' (*note Configuring
     and compiling the software: Configure and make.).

  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 (*note Where
     GNATS lives: Locations.).  SITE is your local site, the value of
     `GNATS_SITE' in the `config' file (*note The `config' file:
     config.).



File: gnats.info,  Node: Upgrading,  Prev: Installing tools,  Up: Installation

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

     (*Note Configuring and compiling the software: Configure and make.)

   * 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' (*note Where GNATS lives: Locations.).

   * 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
     (*note Installing the user tools: Installing tools.).

   * Redistribute `send-pr' to your Submitter Sites (*note Configuring
     `send-pr' for the outside world: mkdist.).  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.



File: gnats.info,  Node: Locations,  Next: Regexps,  Prev: Installation,  Up: Top

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 (*note Installing GNATS: Installation.).

* Menu:

* prefix::
* exec-prefix::
* GNATS_ROOT::
* defaults::       Default installation locations


File: gnats.info,  Node: prefix,  Next: exec-prefix,  Up: Locations

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

*Note Configuring and compiling the software: Configure and make.


File: gnats.info,  Node: exec-prefix,  Next: GNATS_ROOT,  Prev: prefix,  Up: Locations

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_.  *Note
Configuring and compiling the software: Configure and make.

   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 *Note Using `configure':
(configure)Using configure, before attempting this.  Again, _it is not
necessary to use this paradigm when building the GNATS tools_.


File: gnats.info,  Node: GNATS_ROOT,  Next: defaults,  Prev: exec-prefix,  Up: Locations

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'.  *Note Changing your local configuration: Local
configuration, and *Note Administrative data files: Admin files.


File: gnats.info,  Node: defaults,  Prev: GNATS_ROOT,  Up: Locations

Default installation locations
==============================

PREFIX
     defaults to `/usr/local'; change using `configure' (*note
     Configuring and compiling the software: Configure and make.).

EXEC-PREFIX
     defaults to PREFIX; change using `configure' (*note Configuring
     and compiling the software: Configure and make.).

GNATS_ROOT
     defaults to `PREFIX/lib/gnats/gnats-db'; change using `configure'
     (*note Configuring and compiling the software: Configure and
     make.).

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

`EXEC-PREFIX/bin'

    `send-pr'
          *Note Submitting Problem Reports: send-pr.

    `edit-pr'
          *Note Editing existing Problem Reports: edit-pr.

    `query-pr'
          *Note Querying the database: query-pr.

    `nquery-pr'
          *Note Querying the database over the network: query-pr.

`EXEC-PREFIX/lib/gnats'

    `mkcat'
          *Note Adding a problem category: mkcat.

    `rmcat'
          *Note Removing a problem category: rmcat.

    `mkdist'
          *Note Configuring `send-pr' for the outside world: mkdist.

    `gen-index'
          *Note Regenerating the index: gen-index.

    `queue-pr'
          *Note Handling incoming traffic: queue-pr.

    `file-pr'
          *Note Processing incoming traffic: file-pr.

    `at-pr'
          *Note Timely reminders: at-pr.

    `pr-edit'
          *Note The `edit-pr' driver: pr-edit.

    `pr-addr'
          *Note Address retrieval: pr-addr.

    `libiberty.a'
          The GNU `libiberty' library.

`PREFIX/lib/gnats/dist'

    A packageable distribution of `send-pr'.
          *Note Configuring `send-pr' for the outside world: mkdist.

`PREFIX/lib/gnats'

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

`PREFIX/lib/emacs/lisp'

    `gnats.el'
    `gnats.elc'
          The Emacs versions of the programs `query-pr', `edit-pr', and
          `view-pr'.  *Note Invoking the GNATS tools: Invoking the
          tools.  To change this directory you must alter
          `Makefile.in'; see *Note Configuring and compiling the
          software: Configure and make.

    `send-pr.el'
          The Emacs version of the program `send-pr'.  *Note Submitting
          Problem Reports: send-pr.

`PREFIX/info'

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

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

    `man' pages for all the GNATS tools and utilities.
          *Note Invoking the GNATS tools: Invoking the tools.

`PREFIX/src'

    Source code for GNATS.

`PREFIX/sample'

    Example administrative files, including `categories',
          `submitters', `responsible', and `config'.  *Note Changing
          your local configuration: 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.  *Note Changing your local configuration: Local
          configuration, and *Note Administrative data files: Admin
          files.

    `gnats-queue'
          Incoming Problem Reports are queued here until the next
          iteration of `queue-pr -r' (*note Handling incoming traffic:
          queue-pr.).

    `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.  *Note GNATS
          administration: Management.

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



File: gnats.info,  Node: Regexps,  Next: Index,  Prev: Locations,  Up: Top

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.

   *Note Regular Expression Syntax: (regex)Regular Expression Syntax,
for details on regular expression syntax.  Also see *Note Syntax of
Regular Expressions: (emacs)Regexps, 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 *Note Regular Expression Syntax: (regex)Regular
Expression Syntax, for a much more complete discussion on regular
expression syntax.

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

   (1) No pun intended.


File: gnats.info,  Node: Index,  Prev: Regexps,  Up: Top

Index
*****

* Menu:

* -with-gnats-port:                      Configure and make.
* -with-gnats-server:                    Configure and make.
* -with-gnats-service:                   Configure and make.
* -with-gnats-user:                      Configure and make.
* >Arrival-Date::                        Problem Report fields.
* >Audit-Trail::                         Problem Report fields.
* >Category::                            Problem Report fields.
* >Class::                               Problem Report fields.
* >Confidential::                        Problem Report fields.
* >Description::                         Problem Report fields.
* >Environment::                         Problem Report fields.
* >Fix::                                 Problem Report fields.
* >How-To-Repeat::                       Problem Report fields.
* >Number::                              Problem Report fields.
* >Organization::                        Problem Report fields.
* >Originator::                          Problem Report fields.
* >Priority::                            Problem Report fields.
* >Release::                             Problem Report fields.
* >Responsible::                         Problem Report fields.
* >Severity::                            Problem Report fields.
* >State::                               Problem Report fields.
* >Submitter-Id: <1>:                    Problem Report fields.
* >Submitter-Id::                        using send-pr.
* >Synopsis::                            Problem Report fields.
* >Unformatted::                         Problem Report fields.
* _analyzed_ state:                      States.
* _change-request_ class:                Problem Report fields.
* _closed_ state:                        States.
* _critical_ severity problems:          Problem Report fields.
* _doc-bug_ class:                       Problem Report fields.
* _duplicate_ class:                     Problem Report fields.
* _Enumerated_ data types:               Fields.
* _feedback_ state:                      States.
* _high_ priority problems:              Problem Report fields.
* _low_ priority problems:               Problem Report fields.
* _medium_ priority problems:            Problem Report fields.
* _mistaken_ class:                      Problem Report fields.
* _MultiText_ data types:                Fields.
* _non-critical_ severity problems:      Problem Report fields.
* _open_ state:                          States.
* _serious_ severity problems:           Problem Report fields.
* _support_ class:                       Problem Report fields.
* _suspended_ state:                     States.
* _sw-bug_ class:                        Problem Report fields.
* _Text_ data types:                     Fields.
* ACKNOWLEDGE:                           config.
* adding a problem category <1>:         mkcat.
* adding a problem category:             Management.
* adding and removing maintainers:       Management.
* address retrieval:                     pr-addr.
* admin files:                           Admin files.
* administering GNATS:                   Management.
* administrative utilities <1>:          Admin utils.
* administrative utilities:              Invoking the tools.
* alias for incoming Problem Reports:    Aliases.
* alias for your _site_:                 Aliases.
* aliases:                               Aliases.
* appending PRs <1>:                     using send-pr.
* appending PRs:                         Problem Report fields.
* Arrival-Date field:                    Problem Report fields.
* at:                                    Installing utils.
* at-pr:                                 at-pr.
* Audit-Trail field:                     Problem Report fields.
* autoload commands <1>:                 Installing utils.
* autoload commands:                     Installing tools.
* automatic notification <1>:            States.
* automatic notification:                at-pr.
* BACK UP YOUR DATA:                     Management.
* bad Problem Reports:                   using send-pr.
* bug alias:                             Aliases.
* building a distribution of send-pr:    Management.
* building a new index:                  Management.
* building GNATS:                        Installation.
* building in a different directory:     Configure and make.
* business hours:                        config.
* categories file <1>:                   mkcat.
* categories file <2>:                   rmcat.
* categories file <3>:                   categories.
* categories file:                       Local configuration.
* Category field:                        Problem Report fields.
* changing your local configuration:     Local configuration.
* Class field:                           Problem Report fields.
* command line options:                  send-pr from the shell.
* comment section in the PR template:    using send-pr.
* compiling the software:                Configure and make.
* completion in Emacs:                   send-pr in Emacs.
* Confidential field:                    Problem Report fields.
* confidentiality in PRs:                Problem Report fields.
* config file <1>:                       Local configuration.
* config file:                           config.
* configure:                             Configure and make.
* configuring  GNATS:                    Installation.
* configuring and compiling the software: Configure and make.
* configuring GNATS on a network:        Installing tools.
* configuring send-pr for the outside world: mkdist.
* creating an account for GNATS <1>:     Installing utils.
* creating an account for GNATS:         Installing tools.
* cron:                                  Installing utils.
* crontab:                               Installing utils.
* current file:                          current file.
* daemon:                                Installing the daemon.
* database paradigm:                     Paradigm.
* database rationale:                    Introduction.
* database similarities:                 Fields.
* default behavior:                      default behavior.
* default installation locations <1>:    Locations.
* default installation locations:        defaults.
* DEFAULT_ORGANIZATION:                  config.
* DEFAULT_RELEASE:                       config.
* DEFAULT_SUBMITTER:                     config.
* Description field:                     Problem Report fields.
* disabling SUBMITTER-ID <1>:            config.
* disabling SUBMITTER-ID:                submitters.
* driver for edit-pr:                    pr-edit.
* duties for gnats-admin:                Management.
* edit-pr:                               edit-pr.
* edit-pr driver:                        pr-edit.
* edit-pr from the shell:                edit-pr from the shell.
* edit-pr in Emacs:                      edit-pr in Emacs.
* effective problem reporting:           Helpful hints.
* Emacs:                                 send-pr in Emacs.
* Emacs functions <1>:                   Installing utils.
* Emacs functions:                       Installing tools.
* Emacs lisp file installation:          Configure and make.
* emptying the pending directory:        Management.
* Environment field:                     Problem Report fields.
* errors:                                using send-pr.
* example Problem Report:                Fields.
* example queries:                       Example queries.
* EXEC-PREFIX <1>:                       exec-prefix.
* EXEC-PREFIX:                           Configure and make.
* field format:                          Problem Report fields.
* fields:                                Fields.
* fields - list:                         Problem Report fields.
* file-pr:                               file-pr.
* files used for GNATS administration:   Admin files.
* final state ("closed"):                States.
* Fix field:                             Problem Report fields.
* flowchart of GNATS activities:         Flowchart.
* foreword:                              Top.
* format:                                Fields.
* From: header:                          Mail header fields.
* gen-index <1>:                         Management.
* gen-index:                             gen-index.
* GNATS administrator:                   Paradigm.
* GNATS database fields:                 Problem Report fields.
* GNATS fields - list:                   Problem Report fields.
* GNATS management:                      Management.
* gnats-admin alias:                     Aliases.
* GNATS_ADDR:                            config.
* GNATS_ADMIN:                           config.
* GNATS_ROOT <1>:                        Configure and make.
* GNATS_ROOT:                            GNATS_ROOT.
* GNATS_SITE:                            config.
* handling incoming traffic:             queue-pr.
* helpful hints:                         Helpful hints.
* How-To-Repeat field:                   Problem Report fields.
* incoming alias for Problem Reports:    Aliases.
* incoming PRs that GNATS cannot parse:  Paradigm.
* index file <1>:                        index file.
* index file:                            gen-index.
* information to submit:                 Helpful hints.
* initial state ("open"):                States.
* installing GNATS:                      Installation.
* installing the utilities:              Installing utils.
* interactive interface:                 send-pr in Emacs.
* internal utilities <1>:                Internal utils.
* internal utilities:                    Invoking the tools.
* Internet standard RFC-822:             Mail header fields.
* introduction to GNATS:                 Introduction.
* invalid Problem Reports:               using send-pr.
* invoking edit-pr:                      edit-pr.
* invoking mkdist:                       mkdist.
* invoking query-pr:                     query-pr.
* invoking send-pr:                      send-pr.
* invoking send-pr from Emacs:           send-pr in Emacs.
* invoking send-pr from the shell:       send-pr from the shell.
* invoking the GNATS tools:              Invoking the tools.
* KEEP_RECEIVED_HEADERS:                 config.
* kinds of helpful information:          Helpful hints.
* life-cycle of a Problem Report:        States.
* lisp file installation:                Configure and make.
* listing valid categories:              send-pr from the shell.
* loading .el files <1>:                 Installing tools.
* loading .el files:                     Installing utils.
* local configuration:                   Local configuration.
* locations:                             Locations.
* locks:                                 pr-edit.
* mail alias for your _site_:            Aliases.
* mail aliases:                          Aliases.
* mail header fields:                    Mail header fields.
* mail header section:                   using send-pr.
* maintenance:                           Paradigm.
* make:                                  Configure and make.
* managing GNATS:                        Management.
* managing GNATS over a network:         Networked management.
* mkcat <1>:                             Management.
* mkcat:                                 mkcat.
* mkdist:                                Management.
* name completion in Emacs:              send-pr in Emacs.
* networked management:                  Networked management.
* networks:                              Installing tools.
* new problem categories:                mkcat.
* notification of overdue PRs:           at-pr.
* NOTIFY:                                config.
* Number field:                          Problem Report fields.
* OBJDIR:                                Configure and make.
* Organization field:                    Problem Report fields.
* Originator field:                      Problem Report fields.
* other mail <1>:                        using send-pr.
* other mail:                            Problem Report fields.
* overview to GNATS:                     Top.
* paradigm:                              Paradigm.
* pending directory:                     Paradigm.
* pending file:                          categories.
* PR confidentiality:                    Problem Report fields.
* PR locks:                              pr-edit.
* pr-addr:                               pr-addr.
* pr-edit:                               pr-edit.
* PREFIX <1>:                            Configure and make.
* PREFIX:                                prefix.
* Priority field:                        Problem Report fields.
* Problem Report data types:             Fields.
* Problem Report format:                 Fields.
* Problem Report states:                 States.
* Problem Report template:               Fields.
* processing incoming traffic:           file-pr.
* pruning log files:                     Management.
* query-pr:                              query-pr.
* query-pr by mail:                      Invoking query-pr.
* querying invdividual problem reports:  query-pr.
* querying using regexps:                Regexps.
* queue-pr:                              queue-pr.
* queue-pr -q:                           Aliases.
* rationale:                             Introduction.
* Received-By: headers:                  Mail header fields.
* regular expressions:                   Regexps.
* related mail <1>:                      Problem Report fields.
* related mail:                          using send-pr.
* Release field:                         Problem Report fields.
* reminder message:                      at-pr.
* removing a problem category <1>:       Management.
* removing a problem category:           rmcat.
* Reply-To: header:                      Mail header fields.
* Report all the facts!:                 Helpful hints.
* reporting:                             Reporting.
* reporting problems with send-pr:       send-pr.
* Responsible field:                     Problem Report fields.
* responsible file <1>:                  Local configuration.
* responsible file:                      responsible.
* Responsible-Changed-<From>-<To>: in >Audit-Trail:: Problem Report fields.
* Responsible-Changed-By: in >Audit-Trail:: Problem Report fields.
* Responsible-Changed-When: in >Audit-Trail:: Problem Report fields.
* Responsible-Changed-Why: in >Audit-Trail:: Problem Report fields.
* rmcat <1>:                             rmcat.
* rmcat:                                 Management.
* sample Problem Report:                 Fields.
* saving related mail <1>:               Problem Report fields.
* saving related mail:                   using send-pr.
* send-pr:                               send-pr.
* send-pr fields <1>:                    using send-pr.
* send-pr fields:                        send-pr from the shell.
* send-pr within Emacs:                  send-pr in Emacs.
* setting up GNATS:                      Installation.
* Severity field:                        Problem Report fields.
* shell invocation:                      send-pr from the shell.
* SITE alias:                            Aliases.
* so what does it do:                    Paradigm.
* State field:                           Problem Report fields.
* state--"analyzed":                     States.
* state--"closed":                       States.
* state--"feedback":                     States.
* state--"open":                         States.
* state--"suspended":                    States.
* State-Changed-<From>-<To>: in >Audit-Trail:: Problem Report fields.
* State-Changed-By: in >Audit-Trail::    Problem Report fields.
* State-Changed-When: in >Audit-Trail::  Problem Report fields.
* State-Changed-Why: in >Audit-Trail::   Problem Report fields.
* states of Problem Reports:             States.
* Subject: header:                       Mail header fields.
* SUBMITTER:                             config.
* Submitter-Id field <1>:                Problem Report fields.
* Submitter-Id field:                    using send-pr.
* submitters file <1>:                   Local configuration.
* submitters file:                       submitters.
* subsequent mail <1>:                   using send-pr.
* subsequent mail:                       Problem Report fields.
* support site:                          Paradigm.
* Synopsis field:                        Problem Report fields.
* syntax of regexps:                     Regexps.
* template:                              using send-pr.
* template comment section:              using send-pr.
* the section on query-by-mail needs to be relocated: Invoking query-pr.
* timely reminders:                      at-pr.
* To: header:                            Mail header fields.
* tool usage for software maintainers:   Invoking the tools.
* Unformatted field:                     Problem Report fields.
* unpacking the distribution:            Configure and make.
* unparseable incoming PRs:              Paradigm.
* upgrading from older versions:         Upgrading.
* usage for the GNATS tools:             Invoking the tools.
* user utilities:                        Invoking the tools.
* Using and Porting GNU CC:              Helpful hints.
* using edit-pr:                         edit-pr.
* using GNATS over a network <1>:        Installing the daemon.
* using GNATS over a network:            Installing tools.
* using mkdist:                          mkdist.
* using query-pr:                        query-pr.
* using send-pr:                         send-pr.
* using send-pr from within Emacs:       send-pr in Emacs.
* view-pr in Emacs:                      view-pr.
* visual map of data flow:               Flowchart.
* what is a PR:                          Paradigm.
* where GNATS lives:                     Locations.
* why GNATS:                             Paradigm.
* with-full-gnats:                       Configure and make.
* writing reports:                       Reporting.



Tag Table:
Node: Top824
Node: Introduction2445
Node: Paradigm3587
Node: Flowchart8173
Node: States10278
Node: Fields11720
Node: Mail header fields15325
Node: Problem Report fields16405
Node: Invoking the tools24370
Node: send-pr27314
Node: using send-pr28242
Node: send-pr in Emacs34622
Ref: send-pr in Emacs-Footnote-138853
Node: send-pr from the shell38968
Node: Helpful hints41483
Node: edit-pr44578
Node: edit-pr in Emacs47294
Ref: edit-pr in Emacs-Footnote-151945
Node: edit-pr from the shell52060
Node: query-pr53157
Node: Invoking query-pr54098
Ref: Invoking query-pr-Footnote-162934
Node: Example queries63316
Node: Reporting64546
Node: view-pr67113
Node: Management67697
Node: Networked management72208
Node: Local configuration73631
Node: default behavior76508
Node: config77881
Node: categories84662
Node: responsible88051
Node: submitters89229
Node: Admin files92352
Node: index file92776
Node: current file93751
Node: Admin utils94003
Node: mkcat94501
Node: rmcat96009
Node: gen-index97877
Node: mkdist99107
Node: Internal utils100498
Node: queue-pr101022
Node: file-pr102806
Node: at-pr104980
Node: pr-edit106299
Ref: pr-edit-Footnote-1109244
Node: pr-addr109338
Node: Installation109741
Node: Configure and make111972
Node: Installing utils116435
Node: Aliases119992
Node: Installing the daemon123140
Node: Installing tools124589
Node: Upgrading128467
Node: Locations129957
Node: prefix130367
Node: exec-prefix131010
Node: GNATS_ROOT133261
Node: defaults133919
Node: Regexps138179
Ref: Regexps-Footnote-1143485
Node: Index143510

End Tag Table
