   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.

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.

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.

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

Invoking `query-pr'
-------------------

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

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

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

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

   The usage for `query-pr' is:

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

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

     C-x `     *or*       M-x next-error

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

          Submitter-Id   Originator     Synopsis
          Category       Release        Responsible
          Arrival-Date

     See Querying using regular expressions.

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

`-m TEXT'

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

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

     See Querying using regular expressions.

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

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

          query-pr --confidential=no

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

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

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

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

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

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

          Number         Responsible    Category
          State          Severity       Priority
          Submitter-Id   Synopsis

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

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

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

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

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

   `query-pr' also accepts the following options:

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

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

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

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

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

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

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

Example queries
---------------

   The following simple query:

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

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

     >Category:     rats         *and*
     >Responsible:  fred         *and*
     >State:        analyzed

   The following query:

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

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

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

   The following query:

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

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

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.

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

GNATS Administration
********************

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

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

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

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

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

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

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

          rmcat CATEGORY...

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

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

*adding and removing maintainers*
     Edit the `responsible' file to add a new maintainer or to remove an
     existing maintainer.  See The `responsible' file.

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

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

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

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

   See Where GNATS lives.

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

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

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

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

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

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

   See Where GNATS lives.

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

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

        * The address where your site receives Problem Reports.

        * The address of the GNATS administrator.

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

        * The nametag for your local Submitter Site.

        * The default release for your site.

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

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

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

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

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

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

        * The values which define business hours.

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

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

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

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.

The `config' file
-----------------

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

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

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

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

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

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

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

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

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

     The default is the value of `GNATS_SITE'.

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

     The default is `unknown-1.0'.

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

     The default is the value of `GNATS_SITE'.

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

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

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

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

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

     The acknowledgment is of the form:

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

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

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

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

     To disable the feature of GNATS which tracks the `>Submitter-Id:',
     simply alter the `submitters' file to only contain the
     SUBMITTER-ID value which appears in `DEFAULT_SUBMITTER', and 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).

The `categories' file
---------------------

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

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

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

     CATEGORY:DESCRIPTION:RESPONSIBLE:NOTIFY

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

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

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

DESCRIPTION
     A terse textual description of the category.

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

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

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

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

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

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

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

   Only one category must be present for GNATS to function:

     pending:Category for faulty PRs: gnats-admin:

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

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

The `submitters' file
---------------------

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

   Entries are of the format:

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

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

NAME
     A textual description of this entity.

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

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

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

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

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

A few example entries in the `submitters' file:

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

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

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

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.

The `index' file
----------------

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

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

     Category       Number         Submitter-Id
     Responsible    State          Confidential
     Severity       Priority

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

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.

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

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

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

   To add new categories to the database:

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

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

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

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