\input texinfo   @c -*-texinfo-*-
@setfilename gnats.info   

@c upper-case
@set NAMEUC GNATS
@c lower-case
@set NAMELC gnats
@c version number
@set VERSION 3.01

@settitle Bug Management With @value{NAMEUC}

@setchapternewpage odd

@ifinfo
@format
START-INFO-DIR-ENTRY
* Bug Management With GNATS: (gnats).  GNU Problem Report Management System
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@ifinfo
Copyright @copyright{} 1993 Free Software Foundation, Inc.

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

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore

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.
@end ifinfo

@c NOTE TO ANYONE FORMATTING THIS DOCUMENT FOR PRINTING...
@c Comment the following line out if you don't have access to a
@c PostScript printer or viewer

@set POSTSCRIPT

@finalout
@smallbook
@c @cropmarks
@titlepage
@title Bug Management With @value{NAMEUC}
@subtitle @sc{gnu} Problem Report Management System
@subtitle Version @value{VERSION}
@subtitle February 1993
@author Jeffrey M. Osier
@author Cygnus Support
@page

@cite{Reporting Problems With send-pr} is a separate manual which
contains the same text as the chapter ``Reporting problems with
@code{send-pr}'' in this manual, so that support sites who use
@code{@value{NAMEUC}} may copy and distribute the @code{send-pr} manual
when they distribute @code{send-pr} (@pxref{Configuring send-pr, ,
Configuring @code{send-pr} for the outside world}).

Throughout this manual, the personal pronouns @dfn{you} and @dfn{your}
refer to the @code{@value{NAMEUC}} installer/administrator at a given site.

@vskip 0pt plus 1filll
Copyright @copyright{} 1993 Free Software Foundation, Inc.

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

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

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

@end titlepage

@node Top
@top Overview
@cindex overview to @code{@value{NAMEUC}}

This manual documents a suite of utilities called @code{@value{NAMEUC}},
the @sc{gnu} Problem Report Management System.  @code{@value{NAMEUC}} is a
bug-tracking tool designed for use at a central support site.  Software
users who experience problems use electronic mail to communicate these
problems to the maintainers of that software; @code{@value{NAMEUC}}
partially automates the tracking of these problem reports (@dfn{PR}s)
by:

@itemize @bullet
@item
organizing problem reports into a database and notifying responsible
parties of suspected bugs;

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

@item
providing a reliable archive of problems with a given program and a
history of the life of the program by preserving its reported problems
and their subsequent solutions.
@end itemize

@code{@value{NAMEUC}} offers many of the same features offered by more generic
databases.  The database itself is simply an ordered repository for
problem reports; each PR receives a unique, incremental @dfn{PR number}
which identifies it throughout its lifetime.

Many of the primary functions available with @code{@value{NAMEUC}} are
accessible from within @sc{gnu} Emacs.  @xref{Usage, , Invoking the
@code{@value{NAMEUC}} tools}.  Also see 
@ifinfo
@ref{send-pr within Emacs, , Using @code{send-pr} from within Emacs,
send-pr, Reporting Problems With send-pr},
@end ifinfo
@iftex
@ref{send-pr within Emacs, , Using @code{send-pr} from within Emacs},
@end iftex
for information about submitting problem reports from within Emacs.

Problem reports go through several defined states in their lifetimes.
The database considers the initial state of every PR to be @dfn{open};
this means the PR has been filed and the person or group responsible for
it has been notified of the suspected problem.  Once the problem has
been examined, its state changes to @dfn{analyzed}, and work toward a
solution begins.  When a solution has been found and tested at the
support site, that solution is sent to the party who reported the
problem (the @dfn{submitter}).  The PR goes into @dfn{feedback} state
until the solution is confirmed by the submitter, at which point the
state changes to @dfn{closed}.  In some cases, it may be necessary to
suspend work on a bug; in this case, its state changes to
@dfn{suspended} rather than @dfn{closed}.  For a detailed explanation of
what each state means, see @ref{states, , States of Problem Reports}.

Please report all bugs to one of these addresses: 

@smallexample 
bug-gnats@@prep.ai.mit.edu 
@{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gnats 
@end smallexample 

@noindent 

@cindex version @value{VERSION}
This manual documents the @value{VERSION} release of @code{@value{NAMEUC}}.

@menu
* Introduction::               Introducing @value{NAMEUC}
* Configuring and installing:: Configuring and installing @value{NAMEUC}
* Usage::                      Invoking the @value{NAMEUC} tools
* send-pr:(send-pr)Top.        Reporting problems with `send-pr'
* Index::
@end menu

@c ===============================================================
@node Introduction
@chapter Introducing @code{@value{NAMEUC}}
@cindex introduction to @code{@value{NAMEUC}}
@cindex rationale
@cindex paradigm
@cindex database rationale

Any support site which supports more than one product or category of
products realizes that a large amount of data flows back and forth in
the form of problem reports and communication between software
maintainers and software users.  @code{@value{NAMEUC}} addresses the
problem of organizing this communication by defining a database made up
entirely of messages filed automatically by electronic mail.

@code{@value{NAMEUC}} is a tool for software maintainers.  It consists
of ten different utilities which, when used in concert, formulate and
administer a database of problem reports grouped by site-defined
categories.  It was designed for use within a support organization to
keep track of problems with software (hence the term @dfn{Problem
Report}).  Essentially, @code{@value{NAMEUC}} acts as an active archive
for field-separated textual data submitted through electronic mail.

@menu 
* paradigm::       The database paradigm
* data flow::      Data Flow through the system
* flowchart::      Flowchart of @value{NAMEUC} activities
* states::         States of Problem Reports
* fields::         @value{NAMEUC} data fields
@end menu

@node paradigm
@section The database paradigm
@cindex paradigm
@cindex database paradigm
@cindex why @code{@value{NAMEUC}}?
@cindex support site
@cindex maintenance

It is in the best interests of any software maintainer to make it easy
for users of her or his software to report problems they might have with
that software.  It is also in her or his best interest to keep track of
reported problems in as organized a fashion as possible.
@code{@value{NAMEUC}} makes this easy by automatically filing incoming
bug reports into proper places, and making them accessible to queries
and easily editable.  It is a database specialized for a specific task.

@code{@value{NAMEUC}} was designed for use at a support site that
handles a high level of problem-related traffic though electronic mail.
It maintains PRs in the form of text files with defined @dfn{fields}.
Each bug report resides in a separate file within a main repository;
editing access to the database is regulated to maintain consistency.
The fields @code{@value{NAMEUC}} recognizes are discussed in
@ref{fields, , @code{@value{NAMEUC}} data fields}.  We provide
@code{edit-pr} with this distribution as a tool for software maintainers
to use when editing problem reports in the database.  Maintainers can
use @code{query-pr} for making inquiries about certain PRs or groups of
PRs with a very fast search mechanism based on an index which is kept
constantly up to date.  

At the support site, a @code{@value{NAMEUC}} @dfn{administrator} is
charged with the duty of maintaining @code{@value{NAMEUC}}.  These
duties are discussed in detail in @ref{Management, , Managing
@code{@value{NAMEUC}}}, and generally include pruning log files, setting
up new categories for @code{@value{NAMEUC}} to handle, and handling bug
reports that arrive in a format @code{@value{NAMEUC}} cannot understand.

Responsibility for a given problem report is determined by 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.  @xref{Configuring and installing, , Configuring and installing
@code{@value{NAMEUC}}}, and @ref{data flow, , Data Flow}.

The tool @code{send-pr} is provided with this distribution so that both
submitters may more easily submit bug reports that will have fewer
problems when being filed into the database.  @code{send-pr} is both a
shell script and a @sc{gnu} Emacs mode; both implementations provide a
template for submitters to complete.  In most cases, @code{send-pr} will
be able to ``figure out'' the values of several fields, thus at least
partially automating the bug-reporting process.  Of course, any editor
and mailer may be used to submit problem reports to the database.
However, the default values @code{@value{NAMEUC}} assigns to partially
formatted PRs are not always correct for each PR.  @code{send-pr} is
easy to use; it brings up a template which prompts a user for certain
useful kinds of information, which is a step forward in the process of
knowing what kind of data to provide.  (The @code{send-pr} manual also
provides a ``Helpful Hints'' chapter to help people to decide what kinds
of information to provide in reporting bugs;
@ifinfo
@pxref{Helpful hints, , Helpful hints, send-pr, Reporting Problems With
send-pr})
@end ifinfo
@iftex
@pxref{Helpful hints, , Helpful hints})
@end iftex

We also provide a utility called @code{mkdist}, which constructs a
complete distribution of @code{send-pr}, including documentation,
customized to your site's combination of categories.  @xref{Configuring
send-pr, , Configuring @code{send-pr} for the outside world}.

@node data flow
@section Data Flow
@cindex data flow
@cindex how it works
@cindex @code{@value{NAMEUC}} in action

@cindex @code{pending} directory
Once you configure @code{@value{NAMEUC}} to reflect the categories of
problem reports you wish to accept and the responsible parties, you can
start accepting problem reports from both internal and external sources.

For a flowchart describing the activity of @code{@value{NAMEUC}}, see
@ref{flowchart, , Flowchart of @code{@value{NAMEUC}} activities}.

All incoming problem reports should be directed to a single mail alias
which you determine when configuring @code{@value{NAMEUC}} for your
site.  This alias pipes incoming reports into a program called
@code{queue-pr}, which places them in the subdirectory
@file{@value{NAMELC}-queue} under the root @code{@value{NAMEUC}}
directory.  The program @code{queue-pr} is also run periodically via
@code{cron} with a different option; this iteration of @code{queue-pr}
feeds the queued PRs in @file{@value{NAMELC}-queue} to the program
@code{file-pr}, which assigns each bug report an incremental identifying
number and places it in the database according to its category, updating
the index as well.  @code{file-pr} also forwards a copy of the bug
report to the person responsible for solving the problem, and optionally
sends an acknowledgment to the submitter of the problem report.  The
@sc{gnu} Problem Report Tracking System does not yet have the ability to
decipher random text, so any problem reports which arrive in a format
@code{@value{NAMEUC}} does not recognize are kept in a separate
directory pending investigation by the @code{@value{NAMEUC}}
administrator.  This directory is called, creatively enough,
@file{pending}.

Depending on your configuration, @code{@value{NAMELC}} may invoke
@code{at-pr}, which, if a bug is listed with @samp{>Priority: high} or
@samp{Severity: critical}, sends a reminder to the person responsible
for the bug report if it isn't analyzed within a certain requisite time
period (relative to the submitter of the bug; @pxref{submitters, , The
@code{submitters} file}).  @code{at-pr} creates a queued job using
@code{at} which, after the allotted time (in @dfn{business hours}, 8am
to 5pm Monday through Friday) is past, checks the PR to see if its state
has changed from @samp{open}.  If this hasn't occurred, @code{at-pr}
sends mail to the responsible person and to @code{@value{NAMELC}-admin}
with the following message:

@cindex reminder message
@cindex @code{at-pr}
@smallexample
To: @var{originator} @var{responsible} @var{@value{NAMELC}-admin}
Subject: PR @var{id-number} not analyzed in @var{#hours} hours

PR @var{id-number} was not analyzed within the acknowledgment period
of @var{#hours} business hours.  The pertinent information is:

 Submitter-Id: @var{submitter}
 Originator: @var{full name of the submitter}
 Synopsis: @var{synopsis}
 Person responsible for the PR: @var{responsible}

--
The GNU Problem Report Tracking System (@value{NAMEUC})
@end smallexample

At this point, the bug report has been filed, the responsible parties
have been notified, and an acknowledgment has been sent to the submitter
of the problem report.  The state of the PR is @samp{open}, and it is up
to the responsible person to contact the submitter for any more
information needed to analyze the problem.  Any further mail should be
carbon-copied to the @code{@value{NAMEUC}} mailing address as well, with
the category and id-number in the Subject line of the message:

@cindex other mail
@cindex appending PRs
@cindex saving related mail
@cindex related mail
@smallexample
To: @var{submitter}@@@var{submitter-site}
From: @var{responsible} (@emph{or anyone wishing to reply to this message})
Subject: Re: PR @var{category}/@var{id-number}: @var{original message subject}
Cc: @var{@value{NAMEUC} address}

@var{message@dots{}}
@end smallexample

@noindent
This message is automatically appended to the Problem Report in the
@samp{>Audit-Trail:}.  Messages are recorded there in the order
received.  If the the PR in question is being edited when a reply comes
in, that message is placed in the queue to be appended to the PR
whenever @code{queue-pr} is run again.

@cindex sample code
@cindex test cases
@cindex other information
In order to maintain consistency, any large code samples or test cases
should reside in a separate directory.  One strategy is to create a
directory called @file{test-cases} or something similar in the home
directory of @code{@value{NAMEUC}}, with subdirectories in each named
@file{@var{id-number}-d}, storing all extra information according to the
PR identification number with which the information is related.  Be sure
to note in the PR that the other information exists, and where.  For
example:

@smallexample
@value{NAMELC}% ls -F ./test-cases
128-d/      432-d/      872-d/     1102-d/
322-d/      778-d/      995-d/
@end smallexample

@noindent
where each of these directories contains test cases which exhibit the
problem reported.

Software maintainers use the program @code{edit-pr} to alter fields in
certain PRs, and the program @code{query-pr} to obtain information from
the database.  @kbd{query-pr --summary} may also be used to generate a
one-line summary of each PR in the search, which can then be used with
@code{awk} or @code{sed} to create reports on the database:

@smallexample
query-pr --summary --state=open > Open-bugs
query-pr --summary --state=analyzed > Analyzed-bugs
cat Open-bugs Analyzed-bugs | awk -f ./bugsort.awk > current-bugs
@end smallexample

@code{@value{NAMEUC}} sends notifications of any changes in the state or
responsibility fields to the responsible party and to the submitter of
the bug report.

Maintainers now begin work on the bug, at first analyzing the problem
(and thus changing the state of the PR to @dfn{analyzed}) and then
seeking a solution for it.  Once a PR is analyzed, work begins toward a
solution.  When the solution is found, the maintainer changes the state
to @dfn{feedback} and provides the solution to the submitter of the bug
report so that it may be tested; when the submitter confirms that the
solution works, the state may be changed to @dfn{closed}.  If for some
reason the progress towards a solution must be stopped, the state can be
changed to @dfn{suspended}.  @xref{states, , States of Problem Reports}.

@node flowchart
@section Flowchart of @code{@value{NAMEUC}} activities
@cindex flowchart of @code{@value{NAMEUC}} activities
@cindex visual map of data flow

@ifset POSTSCRIPT
@tex
\input epsf
\epsffile{gnats-fc.eps}
@end tex
@end ifset

@ifinfo
@clear POSTSCRIPT
@end ifinfo

@ifclear POSTSCRIPT
@cartouche
@smallexample

             +------------------------------+
             | Software User                |
             |    +--------------------+    |
             |    |   Problem Report   |    |
             |    +---------+----------+    |
             |              |               |
             |              V               |
             |      (send-pr) or            |
             |  (alternate editor/mailer)   |
             |              |               |<-+
             +--------------|---------------+  |
                     to support site           |
                            |                  |
+---------------------------|---------------+  |
|Support Site               V               |  |
| +--------------------+<--(queue-pr -q)    |  |
| |@value{NAMELC}-queue|                    |  |
| |      directory     |                    |  |
| +--------------------+-->(queue-pr -r)    |  |
|                              |            |  |
|                              |   (at-pr)->|  |
| _____________________________|_____|_____ |\ |
| |                          __|_(file-pr)| | \|
| |                         /     \       |<---|
| | +-----------------+    /       \      | |  |
| | |    "pending"    |   /  valid  \     | |  |
| | |    directory    |<--\category?/     | |  |
| | +-----+-----------+  NO\       /      | |  |
| |       |                 \_____/       | |  |
| |    (edit-pr)-------------->|YES       |,-->(sendmail)
| |                            V          / |  |
| |                   "file incoming PR" /| |  |
| |               "update index"      __/ | |  V
| |         "send mail to Responsible"    | | +-------------+
| |_____________|_________________________| | | Software    |
|               |                           | | Maintainers |
|  +------------V------------+              | |             |
|  |                         |<--->(pr-edit)<--(edit-pr)    |
|  |     @value{NAMEUC} database       |              | |             |
|  |                         |---------------->(query-pr...)|  
|  +----------+--------------+              | +-------------+
|             |                             |
|  +----------+-------+                     |
|  |@value{NAMELC}-adm|                     |
|  |    directory     |                     |
|  +------------------+                     |
+-------------------------------------------+


@end smallexample
@end cartouche

@end ifclear

@node states
@section States of Problem Reports
@cindex states of Problem Reports
@cindex Problem Report states
@cindex automatic notification

Each PR goes through a defined series of states between origination and
closure, and is considered @dfn{active} until it has been resolved or
otherwise explicitly @dfn{closed}.  The originator of a PR receives
notification automatically of any state changes that occur.

@table @dfn
@cindex @emph{open} bugs
@cindex initial state (@dfn{open})
@cindex state---@dfn{open}
@item open
The initial state of a Problem Report.  This means the PR has been filed
and the responsible person(s) notified.

@item analyzed
@cindex @emph{analyzed} state
@cindex state---@dfn{analyzed}
The responsible person has analyzed the bug.  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.

@item feedback
@cindex @emph{feedback} state
@cindex state---@dfn{feedback}
This state indicates that 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 acknowledge that the solution works.

@item closed
@cindex @emph{closed} state
@cindex state---@dfn{closed}
@cindex final state (@dfn{closed})
A Problem Report is closed (``the bug stops here'') only when any
changes to the software in question have been documented, integrated and
tested, and the submitter has confirmed the solution.

@item suspended
@cindex @emph{suspended} state
@cindex state---@dfn{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.
@end table

@node fields
@section @code{@value{NAMEUC}} data fields
@cindex fields
@cindex @code{@value{NAMEUC}} data fields
@cindex data fields

@menu
* Mail Header fields::
* Problem Report fields::
@end menu

@c ----------------------
@node Mail Header fields
@subsection Mail Header fields
@cindex mail header fields
@cindex Internet standard RFC-822

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

@table @code
@item To:
The preconfigured mail alias for the support site where the PR is to be
sent, automatically supplied by @code{send-pr}.

@item Subject:
A terse description of the problem.

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

@item Reply-To:
A return address to which electronic replies can be sent; in most
cases, probably the same address as the @code{From:} field.
@end table

@c ----------------------
@node Problem Report fields
@subsection Problem Report fields
@cindex @code{@value{NAMEUC}} database fields
@cindex field format

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

@table @asis
@cindex Problem Report data types
@item @sc{Enumerated}
One of a specific set of values.  The value must be on the same line as
the keyword.  For each @sc{Enumerated} keyword, the possible choices are
listed in the @code{send-pr} template as a comment.

@item @sc{String}
One single line of text which must begin and end on the same line as the
keyword.

@item @sc{Text}
Text of any length may occur in this field.  @sc{Text} may span multiple
lines and may also include blank lines.  A @sc{Text} field ends only
when another keyword appears.
@end table

The following fields are present whenever a PR is submitted via the
program @code{send-pr}.  @code{@value{NAMEUC}} adds additional fields
when the PR arrives at the support site; explanations of these follow
this list.

@table @code
@cindex fields - list
@cindex @code{@value{NAMEUC}} fields - list
@item >Submitter-Id:
@cindex @samp{Submitter-Id} field
@cindex @samp{>Submitter-Id:}
@cindex @samp{--request-id} option
(@sc{Enumerated}) 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
@code{send-pr} with the @samp{--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 @samp{net}
for this field.)

@item >Originator:
@cindex @samp{Originator} field
@cindex @samp{>Originator:}
(@sc{String}) Originator's real name.  The default is the value of the
originator's environment variable @code{NAME}.

@item >Organization:
@cindex @samp{>Organization:}
@cindex @samp{Organization} field
(@sc{Text}) The originator's organization.  The default value is the
contents of the originator's environment variable @code{ORGANIZATION},
or the contents of the file @file{.signature} if @code{ORGANIZATION}
isn't set.

@item >Confidential:
@cindex @samp{Confidential} field
@cindex @samp{>Confidential:}
(@sc{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 @samp{yes} the
support organization treats the PR as confidential; any code samples
you provide are not made publicly available (e.g., in regression test
suites).  The default value is @samp{yes}.

@item >Synopsis:
@cindex @samp{Synopsis} field
@cindex @samp{>Synopsis:}
(@sc{String}) One-line summary of the problem.

@item >Severity:
@cindex @samp{Severity} field
@cindex @samp{>Severity:}
(@sc{Enumerated}) The severity of the problem.  Accepted values include:

@table @code
@cindex @emph{critical} severity bugs
@item critical  
The product, component or concept is completely non-operational or some
essential functionality is missing.  No workaround is known.

@cindex @emph{serious} severity bugs
@item serious
The product, component or concept is not working properly or significant
functionality is missing.  Problems that would otherwise be considered
@samp{critical} are rated @samp{serious} when a workaround is known.

@cindex @emph{non-critical} severity bugs
@item non-critical
The product, component or concept is working in general, but lacks
features, has irritating behaviour, does something wrong, or doesn't
match its documentation.
@end table
The default value is @samp{serious}.
@sp 1

@item >Priority:
@cindex @samp{Priority} field
@cindex @samp{>Priority:}
(@sc{Enumerated}) How soon the originator requires a solution.  Accepted
values include:

@table @code
@cindex @emph{high} priority bugs
@item high
A solution is needed as soon as possible.

@cindex @emph{medium} priority bugs
@item medium
The problem should be solved in the next release of the software.

@cindex @emph{low} priority bugs
@item low
The problem should be solved in a future release.
@end table
@noindent
The default value is @samp{medium}.
@sp 1

@item >Category:
@cindex @samp{Category} field
@cindex @samp{>Category:}
(@sc{Enumerated}) The name of the product, component or concept where
the problem lies.  The support organization provides a list of valid
categories; use @samp{send-pr -L} to see the listing provided with the
@code{send-pr} distribution.  For an example list, see
@iftex
@ref{Valid Categories}.
@end iftex
@ifinfo
@ref{Valid Categories, , Valid Categories, send-pr, Reporting Problems
With send-pr}.
@end ifinfo

@sp 1
@item >Class:
@cindex @samp{Class} field
@cindex @samp{>Class:}
(@sc{Enumerated}) The class of a problem can be one of the following:

@table @code
@cindex @emph{support} class bugs
@item support
A support problem or question.

@cindex @emph{sw-bug} class bugs
@item sw-bug
A software bug.

@cindex @emph{doc-bug} class bugs
@item doc-bug
A bug in the documentation.

@cindex @emph{change-request} class bugs
@item change-request
A request for a change in behavior, etc.

@cindex @emph{mistaken} class bugs
@item mistaken  
No bug, user error or misunderstanding.  This value is valid only at the
support site.

@cindex @emph{duplicate} class bugs
@item duplicate (@var{pr-number})
Duplicate PR.  @var{pr-number} should be the number of the original PR.
@end table
@noindent
The default is @samp{sw-bug}.
@sp 1

@item >Release:
@cindex @samp{Release} field
@cindex @samp{>Release:}
(@sc{String}) Release or version number of the product, component or
concept.

@item >Environment:
@cindex @samp{Environment} field
@cindex @samp{>Environment:}
(@sc{Text}) Description of the environment where the problem occured:
machine architecture, operating system, host and target types,
libraries, pathnames, etc.

@item >Description:
@cindex @samp{Description} field
@cindex @samp{>Description:}
(@sc{Text}) Precise description of the problem, including all
preconditions, inputs, outputs, conditions after the problem, and
symptoms.  Any additional important information should be included.  In
the @code{send-pr} manual, users are instructed to include all the
details that would be necessary for someone else to recreate the
problems they report, however obvious.  Sometimes seemingly arbitrary or
obvious information can point the way toward a solution.  For the types
of information to include, see
@ifinfo
@ref{Helpful hints, , Helpful hints, send-pr, Reporting Problems With
send-pr}.
@end ifinfo
@iftex
@ref{Helpful hints, , Helpful hints}.
@end iftex

@item >How-To-Repeat:
@cindex @samp{How-To-Repeat} field
@cindex @samp{>How-To-Repeat:}
(@sc{Text}) Example code, input, or activities to reproduce the problem.
The support organization uses your example code both to reproduce the
problem and to test whether the problem is fixed.  Again, see
@ifinfo
@ref{Helpful hints, , Helpful hints, send-pr, Reporting Problems With
send-pr},
@end ifinfo
@iftex
@ref{Helpful hints, , Helpful hints},
@end iftex
for helpful hints.
@end table

The following fields are added to the PR when the support site receives
it:

@table @code
@cindex @samp{Responsible} field
@cindex @samp{>Responsible:}
@item >Responsible:
The person responsible for this category, as noted in the
@file{categories} file.

@item >Arrival-Date:
@cindex @samp{>Arrival-Date:}
@cindex @samp{Arrival-Date} field
The time that this PR was received by @code{@value{NAMEUC}}.

@item >Audit-Trail:
@cindex @samp{>Audit-Trail:}
@cindex @samp{Audit-Trail} field
Tracks changes in @samp{>State:} and @samp{>Responsible:} with the
sub-fields:

@table @code
@cindex @samp{State-Changed-<From>-<To>:} in @samp{Audit-Trail}
@cindex @samp{Responsible-Changed-<From>-<To>:} in @samp{Audit-Trail}
@item State-Changed-<From>-<To>: <@var{oldstate}>-<@var{newstate}>
@itemx Responsible-Changed-<From>-<To>: <@var{oldresp}>-<@var{newresp}>
@sc{Enumerated} field containing the values the state or responsible was
changed from and to.

@cindex @samp{State-Changed-By:} in @samp{Audit-Trail}
@cindex @samp{Responsible-Changed-By:} in @samp{Audit-Trail}
@item State-Changed-By: @var{name}
@itemx Responsible-Changed-By: @var{name}
@sc{Enumerated} field containing the name of the maintainer who affected
the change.

@cindex @samp{State-Changed-When:} in @samp{Audit-Trail}
@cindex @samp{Responsible-Changed-When:} in @samp{Audit-Trail}
@item State-Changed-When: @var{date and time}
@itemx Responsible-Changed-When: @var{date and time}
@sc{String} containing the time the change was made.

@cindex @samp{State-Changed-Why:} in @samp{Audit-Trail}
@cindex @samp{Responsible-Changed-Why:} in @samp{Audit-Trail}
@item State-Changed-Why: @var{reason@dots{}}
@itemx Responsible-Changed-Why: @var{reason@dots{}}
@sc{Text} field with the reason for the change.
@end table

@noindent
Also contains any mail messages received by @code{@value{NAMEUC}}
related to this PR, in the order received.

@item >Unformatted:
@cindex @samp{>Unformatted:}
@cindex @samp{Unformatted} field
Any information that does not fit into any of the above fields.
@end table

@c ===============================================================
@node Configuring and installing 
@chapter Configuring and installing @code{@value{NAMEUC}}
@cindex configuring and installing @code{@value{NAMEUC}}
@cindex installing @code{@value{NAMEUC}}
@cindex setting up @code{@value{NAMEUC}}

There are several steps you need to go through to fully configure and
install @code{@value{NAMEUC}} on your system.  You will need @code{root}
access in order to make a new account for @code{@value{NAMELC}}, to
allow this ``user'' access to @code{cron} and @code{at}, and to install
the @code{@value{NAMEUC}} utilities.  You may need @code{root} access on
some systems in order to set mail aliases in place.

@enumerate 1
@item
@cindex unpacking the distribution
@emph{First, unpack your distribution}.@* Whether the distribution you
receive is on a tape or from the Net, all the sources reside in a
directory called @file{@value{NAMELC}-@value{VERSION}} when unpacked.
We will call this the ``top level'' of the @dfn{source directory}, or
@dfn{srcdir}.  The sources for the @code{@value{NAMEUC}} tools are in
the subdirectory @file{@value{NAMELC}-@value{VERSION}/@value{NAMELC}/*}.

Lists of files included in the distribution are in each directory in the
file @file{MANIFEST}.

@item
@cindex editing @file{@value{NAMELC}/Makefile.in}
@emph{From the top level of the source directory, edit
@w{@file{@value{NAMELC}/Makefile.in}}}.@* In the file
@w{@file{@value{NAMELC}-@value{VERSION}/@value{NAMELC}/Makefile.in}},
set the following variables (@emph{do not} edit any other
@file{Makefile} in the distribution):

@table @code
@cindex @code{@value{NAMEUC}_ROOT}
@item @value{NAMEUC}_ROOT
The directory where the database, all administration files, etc.,
resides.  After installing, any changes should be made in this
directory.  From now on, we will refer to this directory as
@var{@value{NAMEUC}_ROOT}.

@item @value{NAMEUC}_ADDR
@cindex @code{@value{NAMEUC}_ADDR}
The address to which software users should submit bugs.  For instance,
if you wish all problem reports to be sent to your site at
@w{@samp{bug-reports@@@var{your-organization}}}, this full address
should be the value of @code{@value{NAMEUC}_ADDR}.

@item @value{NAMEUC}_SITE
@cindex @code{@value{NAMEUC}_SITE}
A one-word name tag for your site, to be used as an alias for anyone who
submits bug reports.  You should also include this name in the
@file{submitters} file so @code{@value{NAMEUC}} can recognize bug reports
originating from inside your organization (see step 12).  This value
also becomes the name of a list of categories your organization
supports, which is kept up to date locally when you run the program
@code{mkcat} (@pxref{categories, , The @code{categories} file}) and is
created for outside users when you use the utility @code{mkdist}
(@pxref{Configuring send-pr, , Configuring @code{send-pr} for the
outside world}).

@item DEFAULT_RELEASE
@cindex @code{DEFAULT_RELEASE}
Used by @code{send-pr} as a default value for the @samp{>Release:}
field.  Use the name or release number of your most recent release, or
just leave it blank to set no default.

@item DEFAULT_ORGANIZATION
@cindex @code{DEFAULT_ORGANIZATION}
Used by your local @code{send-pr} as a default value for the
@samp{>Organization:} field.  Supply the name of your organization here.
@end table

@noindent
This is the only @file{Makefile} you should edit in this distribution.

@item
@cindex editing @file{@value{NAMELC}/config.h}
@emph{Edit the file
@file{@value{NAMELC}-@value{VERSION}/@value{NAMELC}/config.h}}.@* This
file contains variables which establish some behavior traits of
@code{@value{NAMEUC}}.  @xref{config.h, , The @code{config.h} file}.

@item
@cindex running @code{configure}
@cindex @code{configure}
@emph{Run @code{configure} at the top level}.@* You can nearly always
run @code{configure} from the top level of the source directory,
@file{@value{NAMELC}-@value{VERSION}}, with the command

@example
./configure @var{hosttype}
@end example

@noindent
(where @var{hosttype} is your host type) and the ``Right Thing'' will
happen: @code{@value{NAMEUC}} will be configured in the same directory
you unpacked it in; when built, it will be able to run on the machine
you're building it on; and when installed, files which should be public
will be installed in @file{/usr/local}.  You may omit @var{hosttype} on
most platforms; @code{configure} has magical ways of finding out what
kind of machine you're on.

You may wish to build @code{@value{NAMEUC}} in a different directory
from the source directory, or install the user utilities like
@code{query-pr} in a directory different from @file{/usr/local}.  For
instructions on this, see @ref{Configuring, , Configuring
@code{@value{NAMEUC}} on your system}.

@item
@cindex running @kbd{make all}
@cindex @kbd{make all}
@emph{Run @kbd{make all} at the top level}.@* @strong{Do not} run
@kbd{make install} at this point, as installation must be done with
@code{root} privileges.
@end enumerate

@emph{The following steps may require @code{root} privileges}.

@cartouche
@enumerate 6
@item
@cindex @code{root} priviledges
@emph{@kbd{su root} to acquire @code{root} privileges}.
@end enumerate
@end cartouche

@cartouche
@enumerate 7
@item
@cindex creating an account for @code{@value{NAMELC}}
@emph{Create a @file{passwd} entry for @code{@value{NAMELC}}}.@* In
other words, create an account for a user named
``@code{@value{NAMELC}}''.  The home directory for this account should
be the same directory you specified for @var{@value{NAMEUC}_ROOT} in the
file @file{Makefile.in}.  Also, the default path for this ``user''
should contain @w{@file{@var{@value{NAMEUC}_ROOT}/@value{NAMELC}-bin}}.
@end enumerate
@end cartouche

@cartouche
@enumerate 8
@item
@cindex running @kbd{make install}
@cindex @kbd{make install}
@emph{Run}@*

@smallexample
make install @value{NAMEUC}=install-@value{NAMELC}
@end smallexample

@noindent
from the top level of your source directory. This installs
@code{@value{NAMEUC}} in the directory you specified with
@samp{@value{NAMEUC}_ROOT}.  It also installs the other files associated
with @code{@value{NAMEUC}}, including the program @code{send-pr}, the
@sc{gnu} library @file{libiberty}, and several others.
@end enumerate
@end cartouche

@cartouche
@enumerate 9
@item
@cindex allowing @code{cron} and @code{at} commands
@cindex @code{cron} and @code{at}
@cindex @code{at} and @code{cron}
@cindex @file{cron.allow}
@cindex @file{at.allow}
@cindex @file{cron.deny}
@cindex @file{at.deny}
@emph{Allow @code{cron} and @code{at} commands for the user
@code{@value{NAMELC}}}.@* @code{@value{NAMEUC}} requires access to both
@code{cron} and @code{at}, so it may be necessary to explicitly allow
the user @code{@value{NAMELC}} access by adding it to the files
@w{@file{/var/spool/cron/cron.allow}} and @file{at.allow}, if these
files exist.  If they do @emph{not} exist, and the name
@code{@value{NAMELC}} does not appear in the corresponding files
@file{cron.deny} or @file{at.deny}, then no further action is necessary.
@end enumerate
@end cartouche

@cartouche
@enumerate 10
@item
@cindex networks
@emph{If you need to use @code{@value{NAMEUC}} utilities, like
@code{query-pr} and @code{edit-pr}, on other systems} besides the one
@code{@value{NAMEUC}} itself resides on, see @ref{networks, , Using
@code{@value{NAMEUC}} over a network}.
@end enumerate
@end cartouche

@cartouche
@enumerate 11
@item
@cindex account for @code{@value{NAMELC}-admin}
@cindex mail alias for @code{@value{NAMELC}-admin}
@emph{Create an alias for @code{@value{NAMELC}-admin}, the
@code{@value{NAMEUC}} administrator}, in the file @file{/etc/aliases},
or wherever your mail system looks for mail aliases.  Assign this alias
to the person in charge of @code{@value{NAMEUC}}.  @xref{Management, ,
Managing @code{@value{NAMEUC}}}.
@end enumerate
@end cartouche

@cartouche
@enumerate 12
@item
@cindex bug alias
@cindex incoming alias for bug reports
@cindex alias for incoming bug reports
@cindex @code{queue-pr -q}
@emph{Create an alias to redirect incoming bugs}.  This alias should redirect
incoming mail via a @dfn{pipe} to the program @w{@samp{queue-pr -q}}.
For example, if PRs coming to your site are to arrive at the address
@samp{bugs@@your.company.com}, create an alias to the effect of:

@smallexample
bugs:     "| @var{@value{NAMEUC}_ROOT}/@value{NAMELC}-bin/queue-pr -q > /dev/null 2>&1"
@end smallexample

@noindent
where @var{@value{NAMEUC}_ROOT} is the directory where
@code{@value{NAMEUC}} resides, which you indicated in the file
@file{Makefile.in}.  This places all incoming bugs in the directory
@w{@file{@var{@value{NAMEUC}_ROOT}/@value{NAMELC}-queue}}.
@end enumerate
@end cartouche

@cartouche
@enumerate 13
@item
@cindex @emph{site} alias
@cindex mail alias for your @emph{site}
@cindex alias for your @emph{site}
@emph{Create an alias for your site}.@* This name should be the same
name you indicated in @file{Makefile.in} above with the variable
@code{@value{NAMEUC}_SITE}, with the suffix @samp{-@value{NAMELC}}, and
should point toward the local submission address.  For instance, if your
site is Killer Technologies, the presence of @code{@value{NAMEUC}} on
your @var{site} would be aliased as

@smallexample
bugs:      "| @var{@value{NAMEUC}_ROOT}/@value{NAMELC}-bin/queue-pr -q > /dev/null 2>&1"
killer-@value{NAMELC}: bugs
@end smallexample

@noindent
The report-submission utility @code{send-pr} automatically appends the
@samp{-@value{NAMELC}} to any arguments you specify.  The @code{send-pr}
which was installed when you typed @w{@kbd{make install}} has a default
argument of @var{@value{NAMEUC}_SITE}, your site, so that when your
local users simply type @kbd{send-pr} mail will be sent to your local
@code{@value{NAMEUC}}.  Part of the installation process for
@code{send-pr} is to set up an alias for the support site they received
@code{send-pr} from, so that anyone you distribute @code{send-pr} to
will be instructed to make an alias

@smallexample
killer-@value{NAMELC}: bugs@@killer.com
@end smallexample

@noindent
This allows users at your site, as well as anyone to whom you distribute
@code{send-pr}, to type @w{@kbd{send-pr killer}} on the command line and
submit PRs to your site.  This aliasing allows your organization and its
affiliates to use the same @code{send-pr} to submit bugs to more than
one support site.  For instance, if you also submit PRs to a
@code{@value{NAMEUC}} located at Bumblebee BASIC, Inc., and Unencumbered
Unix (a well-known supporter of Free Software), your @file{/etc/aliases}
file might resemble something like the following:

@smallexample
# local and external @value{NAMEUC} sites
# local first
bugs:      "| @var{@value{NAMEUC}_ROOT}/@value{NAMELC}-bin/queue-pr -q > /dev/null 2>&1"
killer-@value{NAMELC}:       bugs
# other sites
bumblebee-@value{NAMELC}:    bumblebugs@@bumblebee.com
unencumbered-@value{NAMELC}: unencumberbugs@@unencumbered.org
@end smallexample

@noindent
With these aliases, your users may simply type @kbd{send-pr bumblebee}
to send Problem Reports to Bumblebee BASIC, or more precisely to
@code{bumblebugs}, their @code{@value{NAMEUC}} alias.

Anyone who receives @code{send-pr} from you will have a copy of
@code{send-pr} which sends mail by default to @samp{bugs@@killer.com}.
If these outside folk run @code{@value{NAMEUC}} themselves, it is up to
the system administrator at each local site to decide on a default
address.
@ifinfo
@xref{Installing send-pr, , Installing @code{send-pr} on your system,
send-pr, Reporting Problems With send-pr}.
@end ifinfo
@iftex
@xref{Installing send-pr, , Installing @code{send-pr} on your system}.
@end iftex
See also @ref{Introduction, , Introducing @code{@value{NAMEUC}}}, for more
discussion on the @code{@value{NAMEUC}} paradigm.
@end enumerate
@end cartouche

@cartouche
@enumerate 14
@item
@cindex log files
You may also wish to forward a copy of each incoming Problem Report to a
log.  This can be accomplished via the mail aliases function with
something like:

@smallexample
bugs-q:  "| @var{@value{NAMEUC}_ROOT}/@value{NAMELC}-bin/queue-pr -q > /dev/null 2>&1"
bugs-log:    @var{@value{NAMEUC}_ROOT}/bug.log
bugs:        bugs-q, bugs-log
@end smallexample

@noindent
where @var{@value{NAMEUC}_ROOT} is the directory @code{@value{NAMEUC}}
resides in, which you specified in the file
@file{@value{NAMELC}-@value{VERSION}/@value{NAMELC}/Makefile.in}.  This
configuration will archive mail in the file
@w{@file{@var{@value{NAMEUC}_ROOT}/bug.log}}, and also feed it to the
program @code{queue-pr}.  (Remember, @file{bug.log} needs to be
world-writable, and should be pruned regularly; @pxref{Management, ,
Managing @code{@value{NAMEUC}}}.)
@end enumerate
@end cartouche

@cartouche
@enumerate 15
@item
@emph{Exit from the @code{root} shell}.
@end enumerate
@end cartouche

@enumerate 16
@item
@emph{Log in as @code{@value{NAMELC}}}, the new account you created.

@item
@cindex configuring for your site
@cindex local conventions
@emph{Edit the files you just installed in
@file{@var{@value{NAMEUC}_ROOT}/@value{NAMELC}-adm}}.@* You will need to edit:

@itemize @bullet
@item @code{@var{@value{NAMEUC}_ROOT}/@value{NAMELC}-adm/categories},
@item @code{@var{@value{NAMEUC}_ROOT}/@value{NAMELC}-adm/submitters}, and
@item @code{@var{@value{NAMEUC}_ROOT}/@value{NAMELC}-adm/responsible}.
@end itemize

@noindent
to reflect your schema for collecting data.  @xref{Admin Files, , Files
used for @code{@value{NAMEUC}} administration}, for detailed discussions
of the formats of these files.  For more discussion on data collection
schematics, see @ref{Introduction, , Introducing @code{@value{NAMEUC}}}.

@item
@cindex @code{mkcat}
@emph{Run @kbd{@var{@value{NAMEUC}_ROOT}/@value{NAMELC}-bin/mkcat}}.@*
@code{mkcat} sets up the subdirectories of @var{@value{NAMEUC}_ROOT}
which will contain submitted Problem Reports.  Each subdirectory is
named for the category its bugs will belong to; for instance, all bugs
submitted with a category of @emph{carbuerator} will be filed in the
directory @w{@file{@var{@value{NAMEUC}_ROOT}/carbuerator}}.
@code{mkcat} creates these directories according to the data you placed
in the @file{categories} file (@pxref{categories, , The
@code{categories} file}); it also updates the local list of supported
categories used by @code{send-pr}.

Always run @code{mkcat} whenever you need to add a new category.
@xref{Management, , Managing @code{@value{NAMEUC}}}.

@item
@cindex running @code{queue-pr -r} via @code{cron}
@cindex @code{queue-pr -r} via @code{cron}
@emph{Create a @code{crontab} entry for the user @code{@value{NAMELC}}} to
periodically run the command

@smallexample
@var{@value{NAMEUC}_ROOT}/@value{NAMELC}-bin/queue-pr -r
@end smallexample

@noindent
The @samp{-r} option causes @code{queue-pr} to feed all the incoming
bugs from the directory
@w{@file{@var{@value{NAMEUC}_ROOT}/@value{NAMELC}-queue}} into the
program @code{file-pr}, which assigns each new bug an individual serial
number, notifies responsible parties of the existence of this bug,
updates the index, files the bug in the correct subdirectory, etc.
@xref{Introduction, , Introducing @code{@value{NAMEUC}}}.

@item
@emph{Log out from the @code{@value{NAMELC}} account}.
@end enumerate

@code{@value{NAMEUC}} is now ``live'' on your system.  The program
@code{send-pr} (invoked with @w{@kbd{M-x send-pr}} from within Emacs)
allows your local users to easily submit Problem Reports.  You should
pre-configure and distribute copies of @code{send-pr} to all parties you
wish to receive bug reports from using the program @code{mkdist}; see
@ref{Configuring send-pr, , Configuring @code{send-pr} for the outside
world}.  See also
@ifinfo
@ref{Top, , Overview, send-pr, Reporting Problems With send-pr}.
@end ifinfo
@iftex
@cite{Reporting problems with send-pr}.
@end iftex

@menu
* Configuring::     Configuring @value{NAMEUC} on your system
* networks::        Using @value{NAMEUC} over a network
* config.h::        The `config.h' file
* Admin Files::     Files used for @value{NAMEUC} administration
@end menu

@c ---------------------------------------------------------------
@node Configuring
@section Configuring @code{@value{NAMEUC}} on your system
@cindex @code{configure}
@cindex configuring @code{@value{NAMEUC}} on your system

@xref{What configure does, , What @code{configure} does, configure,
Cygnus configure}, for detailed information about @code{configure}.

@menu
* prefix::       Changing the installation location
* objdir::       Changing the build directory
* other flags::  Other flags to `configure'
@end menu

@node prefix
@subsection Changing the installation location
@cindex prefix (@code{configure)}
@cindex changing the installation location

@file{/usr/local} is the default installation directory, which can be
altered by invoking @code{configure} with

@example
./configure @var{hosttype} --prefix=@var{install-dir} 
@end example

@cindex utility installation locations
@cindex installation locations for user utilities
@noindent
where @var{install-dir} is the alternative installation directory.
Nearly all files associated with @code{@value{NAMEUC}} are installed in the
directory you indicated with @var{@value{NAMEUC}_ROOT}.  The only files which are
installed in the file indicated with @file{prefix} are:
@table @code
@item send-pr
@itemx query-pr
@itemx edit-pr
installed in @file{@var{prefix}/bin}

@item libiberty.a
installed in @file{@var{prefix}/lib}

@item @var{categories-list}
named the value of @var{@value{NAMEUC}_SITE}, installed and updated by
@code{mkcat} in @file{@var{prefix}/lib/@value{NAMELC}}

@item @value{NAMELC}.el
@itemx send-pr.el
installed in @w{@file{@var{prefix}/lib/emacs/lisp}} (for information on
byte-compiling these files, @pxref{Compiling Libraries, , Lisp
Libraries, emacs, GNU Emacs})

@item @value{NAMELC}.info, send-pr.info
installed in @file{@var{prefix}/info}

@item @value{NAMEUC} ``man'' @dfn{pages}
installed in @w{@file{@var{prefix}/man/man@var{N}}}, where @var{N}
refers to the ``@code{man}'' section (``1'' for commands, ``8'' for
admin utilities, etc.).
@end table

@noindent
It is not advised to change the values of these directories except
through the use of the flag @samp{--prefix=@var{dir}}.  All other
programs and files associated with @code{@value{NAMEUC}} are installed
under the directory you indicated in @file{Makefile.in} with the
variable @samp{@value{NAMEUC}_ROOT}.

@node objdir
@subsection Changing the build directory
@cindex changing the build directory
@cindex objdir
You may choose to build @code{@value{NAMEUC}} in a different location
from the source code.  In this case, you must first create the new
@dfn{build directory}, then call @code{configure} from there:

@example
mkdir @var{build-directory}
cd @var{build-directory}
@var{srcdir}/configure @var{hosttype} --srcdir=@var{srcdir}
@end example

@noindent
where @var{srcdir} is the top level of the directory holding the
@code{@value{NAMEUC}} distribution.  The @dfn{build directory} is always your
current directory when you call @code{configure}.

@node other flags
@subsection Other flags to @code{configure}
@cindex other flags to @code{configure}

You can also use the following flags to @code{configure}.  None will
actually cause @code{configure} to configure your @code{@value{NAMEUC}}
directory.

@table @code
@item -V @var{or} --version
Prints out the version number of @code{configure}.

@item --help
Prints out a list of all the flags @code{configure} recognizes.  Many
are not applicable to @code{@value{NAMEUC}}.
@end table

The documentation for @code{configure} is included with this
distribution in the directory
@w{@file{@var{srcdir}/@value{NAMELC}-@value{VERSION}/etc}}, and is
installed when @code{@value{NAMEUC}} is installed.  @xref{What configure
does, , What @code{configure} does, configure, Cygnus configure}.

@c ---------------------------------------------------------------
@node networks
@section Using @code{@value{NAMEUC}} over a network
@cindex networks
@cindex using @code{@value{NAMEUC}} over a network
@cindex configuring @code{@value{NAMEUC}} on a network

In order to install @code{@value{NAMEUC}} for use on a network, you may
need @code{root} privileges on each host you wish to install on.

@enumerate 1
@item
@emph{Make sure the directory in which @code{@value{NAMEUC}}
resides is NFS-mounted} to each system that will need access to it, so
@var{@value{NAMEUC}_ROOT} will be the same for each host.  (This can be
done with symbolic links as well.)

@item
@emph{Either NFS-mount your @dfn{source} and @dfn{build directories}}, or make
a copy of the @code{@value{NAMEUC}} source code tree in a separate
directory on each system you wish to build on.

@item
@emph{For each host, do the following:}

@table @kbd
@item configure @var{hosttype} (@emph{for the new @var{host} type})

@item make all @value{NAMEUC}=all-tools

@item su root @emph{on the new host}

@item make install @value{NAMEUC}=install-tools

@item @emph{exit from the} root @emph{shell}
@end table

@noindent
This does a normal @kbd{make all} and @kbd{make install} for all files
except those in the directory @file{@var{srcdir}/@value{NAMELC}}, which
will only install:

@table @code
@item query-pr
into @w{@file{@var{prefix}/bin}}

@item edit-pr
into @w{@file{@var{prefix}/bin}}

@item pr-edit
into @w{@file{@var{prefix}/lib/@value{NAMELC}}}

@item pr-addr
into @w{@file{@var{prefix}/lib/@value{NAMELC}}}

@item @value{NAMELC}.el
@item send-pr.el
into @w{@file{@var{prefix}/lib/emacs/lisp}} (for information on
byte-compiling these files, @pxref{Compiling Libraries, , Lisp
Libraries, emacs, GNU Emacs})
@end table

@noindent
on each system.

@item
@emph{Make sure you're back on the host @code{@value{NAMEUC}} will run on}.
@end enumerate

@c ---------------------------------------------------------------
@node config.h
@section The @code{config.h} file
@cindex @file{config.h}
@cindex the @file{config.h} file

The file @file{@value{NAMELC}-@value{VERSION}/@value{NAMELC}/config.h}
is used as a header file where you may define certain local conventions
you wish to implement or suppress.  The only local conventions
switchable by this file are the following:

@itemize @bullet
@item If you specify
@cindex @samp{NOTIFY}

@example
#define NOTIFY    TRUE
@end example

@noindent
in @file{config.h}, @code{@value{NAMEUC}} will automatically send out a
reminder to the responsible person for a given PR if that PR is not
analyzed within a requisite period of time.  The period is determined
for each submitter separately in the @file{submitters}.
@xref{submitters, , The @code{submitters} file}, for more information
about the @w{@file{submitters}} file.  For information on @code{at-pr},
the program which sends out this reminder, see @ref{Introduction, ,
Introducing @code{@value{NAMEUC}}}.

@item If you specify
@cindex @samp{ACKNOWLEDGE}

@example
#define ACKNOWLEDGE    TRUE
@end example

@noindent
@code{@value{NAMEUC}} will automatically send an acknowledgment to the
submitter of a Problem Report when the PR is first received.  The
acknowledgment is of the form:

@smallexample
To: @var{your address}
From: @value{NAMELC}
Subject: Re: @var{category}/@var{serial-number}:@var{Synopsis}
In-Reply-To: Your message of @var{date}

Thank you very much for your problem report.
It has the internal identification: @var{category}/@var{serial-number}
The individual assigned to look at your bug is: @var{responsible}


Category: @var{category of the bug}
Responsible: @var{responsible}
Synopsis: @var{Synopsis from submitted PR}
Arrival-Date: @var{arrival date}
@end smallexample

@item Define the following:
@cindex @samp{DEFAULT_SUBMITTER}
@example
#define DEFAULT_SUBMITTER     "@var{default}"
@end example

so that @code{@value{NAMEUC}} may assign the value @samp{default} to any
PR that arrives without a @samp{Submitter-Id}.  This value is usually
either @samp{net} or @samp{unknown}.

@item Define the following:
@cindex @samp{KEEP_RECEIVED_HEADERS}
@example
#define KEEP_RECEIVED_HEADERS     TRUE
@end example

@noindent
to specify whether @code{@value{NAMEUC}} should keep the
@samp{Received:} headers for mail messages.  Every email message has one
or more @samp{Received:} headers to tell you how a message got from the
sender to the recipient.  Define this to be TRUE if you want
@code{@value{NAMEUC}} to preserve all of those @samp{Received:} headers.
If you tend not to use the information, define it to be FALSE so
@code{@value{NAMEUC}} will only keep the first @samp{Received:} header.
@end itemize

@c ---------------------------------------------------------------
@node Admin Files
@section Files used for @code{@value{NAMEUC}} administration
@cindex admin files
@cindex files used for @code{@value{NAMEUC}} administration

The following files are located in
@file{@var{@value{NAMEUC}_ROOT}/@value{NAMELC}-adm}, where
@var{@value{NAMEUC}_ROOT} is the resident directory of
@code{@value{NAMEUC}}.  @xref{Introduction, , Introducing
@code{@value{NAMEUC}}}, to see how these files interact.

@menu
* categories::      The `categories' file
* responsible::     The `responsible' file
* submitters::      The `submitters' file
* index file::      The `index' file
* current::         The `current' file
@end menu

@node categories
@subsection The @code{categories} file
@cindex the @code{categories} file
@cindex @file{categories}

This file contains a list of problem categories, specific to your site,
which @code{@value{NAMEUC}} will track.  You must edit this file
initially, creating valid categories and then running
@w{@file{@var{@value{NAMEUC}_ROOT}/@value{NAMELC}-bin/mkcat}} to create
the corresponding subdirectories of @var{@value{NAMEUC}_ROOT}.  To
create a new category once the system is in place, simply log in as
@code{@value{NAMELC}}, add a line to this file, and run @code{mkcat}.
Lines beginning with a @samp{#} will be ignored.

Its consists of four fields delineated with colons, as follows:

@smallexample
@var{category}:@var{description}:@var{responsible}:@var{notify}
@end smallexample

@noindent
@table @var
@item category
A unique, valid category name, which can contain only text characters,
dashes, underbars, etc., and cannot contain spaces or any of the
following characters:

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

@noindent
Ideally, category names should not contain commas or begin with periods.
Each line will have a corresponding subdirectory in the main
@code{@value{NAMEUC}} directory (@var{@value{NAMEUC}_ROOT}).

@c It is possible that if you set up the database with categories
@c which contain characters that describe subdirectories, such as a slash
@c (@key{/}) in @sc{Un*x}, you could effectively build subdirectories
@c within each category, and @code{@value{NAMEUC}} would read and write to these
@c files as it would any other.  This is not recommended.  It doesn't
@c break any of the existing tools, and is a fine way to keep category
@c directories from growing too large.  It is, however, quite untested.

@item description
A terse textual description of the category.

@item responsible
The name tag of the party responsible for this category of
problems, as listed in the @file{responsible} file.

@item notify
One or more other parties which should be notified when a bug 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.
@end table

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 bugs in a variety of
areas, you could have entries such as

@smallexample
doc:General Doc Questions:myboss:me, mypal
doc-rock:Doc for ROCK program:me:myboss
doc-stone:Docs for STONE utilities:mypal:fred@@bedrock.com
doc-local:in-house documentation:me:doc-local-log
@end smallexample

In the above example, bugs sent with a category of @samp{doc} are sent
to the local mail address (or alias) @samp{myboss}, and also sent to the
addresses @samp{me} and @samp{mypal}.  Bugs with a category of
@samp{doc-rock} are sent to the local addresses @samp{me} and
@samp{myboss} only, while PRs sent with the category @samp{doc-stone}
are sent outside the local organization as well as to @samp{mypal}.  PRs
arriving for the category @samp{doc-local} are sent only to @samp{me},
and are also sent to @code{doc-local-log} (in this case, an alias should
be set up in @file{/etc/aliases} to reflect a location for the log file,
such as @w{@samp{doc-local-log: /users/me/local-log}}).

Whenever you add a new category, be sure to run

@smallexample
@var{@value{NAMEUC}_ROOT}/@value{NAMELC}-bin/mkcat
@end smallexample

@noindent
to create a subdirectory for it and update the local categories list.

Only one category must be present for @code{@value{NAMEUC}} to function:

@smallexample
pending:Category for faulty PRs: @value{NAMELC}-admin:
@end smallexample

The @file{pending} directory is created automatically when you run
@kbd{make install}.

@node responsible
@subsection The @code{responsible} file
@cindex @file{responsible}
@cindex the @code{responsible} file

This file contains a list of the responsible parties.  Lines beginning
with a @samp{#} will be ignored.  Each entry contains three fields,
separated by colons:

@smallexample
@var{responsible}:@var{full-name}:@var{mail-address}
@end smallexample

@noindent
@table @var
@item 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 will be listed in the PR in
the @samp{Responsible} field.

@item full-name
The full name of the party (``Butch Cassidy''; ``Compiler Group'').

@item 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.
@end table

@noindent
A sample @file{responsible} listing might be:

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

Here, @code{ren} is a local user.  @code{stimpy} is remote, so his full
address must be specified.

The following entry must be present for @code{@value{NAMEUC}} to function:

@smallexample
@value{NAMELC}-admin: @value{NAMEUC} administrator:
@end smallexample

@noindent
(Remember, you put in @code{@value{NAMELC}-admin} as a mail alias, so
for this purpose @code{@value{NAMELC}-admin} is a local address.)


@node submitters
@subsection The @code{submitters} file
@cindex @file{submitters}
@cindex the @code{submitters} file

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

Entries are in the format:

@smallexample
@var{submitter-id}:@var{name}:@var{type}:@var{resp-time}:@var{contact}:@var{notify}
@end smallexample

@noindent
@table @var
@item submitter-id

A unique identifier for a specific site or other entity which will be
submitting Problem Reports.

@item name
A textual description of this entity.

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

@item resp-time
@code{@value{NAMEUC}} is capable of reminding responsible parties of
bugs marked with a @samp{>Severity} value of @samp{critical}, or those
with a @samp{>Severity} of @samp{serious} and a @samp{>Priority} value
of @samp{high}, when these bugs are not analyzed within a certain
period.  This argument, in business hours, defines that response period.
This function is active if the @code{NOTIFY} field is defined as
@samp{TRUE} in @file{config.h} at build-time; see @ref{config.h, , The
@code{config.h} file}.  If @code{NOTIFY} is @samp{FALSE}, this field is
ignored.  For information on @code{at-pr}, the program which sends out
this reminder, see @ref{Introduction, , Introducing
@code{@value{NAMEUC}}}.

@item contact
The name tag of the ``main contact'' at the support site for this
submitter.  This contact should be in the @file{responsible} file.
Incoming bugs from @var{submitter} will be sent to this @var{contact}.
Optionally, this field can be left blank.

@item notify
Any other parties which should receive copies of Problem Reports sent in
by @var{submitter}.
@end table

A few example entries in the @file{submitters} file:

@smallexample
univ-hell: University of Southern Hades::3:beelzebub:lucifer
tta: Telephones and Telegraphs of America:support:720:dave:
@end smallexample

@noindent
In this example, when a PR comes in from the University of Hades, it
should have @samp{univ-hell} in its @samp{Submitter-Id} field; this bug
will go to @code{beelzebub} (who should be in the @file{responsible}
file), and if it is not analyzed within three hours a reminder message
will be sent.  @code{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 @code{dave}, who has 720 hours to
return an analysis before a reminder is sent.

@node index file
@subsection The @code{index} file
@cindex @file{index}
@cindex the @code{index} file

The index is used to accelerate searches on the database.  This file is
not created until the first PR comes in.  It is then kept up to date by
@code{@value{NAMEUC}}; you should never touch this file.

Any searches on subjects contained in the index will be much faster than
searches which depend on data not in the index.  The index contains
entries for: @var{id-number}; @var{category}; @var{responsible};
@var{submitter}; @var{state}; @var{class}; and @var{severity}.

@c uncomment this line when this chapter is written...
@c @xref{Writing Tools, , Writing @code{@value{NAMEUC}} tools}.

@node current
@subsection The @code{current} file
@cindex @file{current}
@cindex the @code{current} file

This file contains the last serial number assigned to an incoming PR.
It is used internally by @code{@value{NAMEUC}}; you need never touch
this file.

@c ===============================================================
@node Usage
@chapter Invoking the @code{@value{NAMEUC}} tools
@cindex usage for the @code{@value{NAMEUC}} tools
@cindex invoking the @code{@value{NAMEUC}} tools
@cindex tool usage for software maintainers

The following programs comprise @code{@value{NAMEUC}}:

@table @code
@item send-pr
Used by anyone who has a problem with a given set of software to submit
a report of the problem to the maintainers of that software
@ifinfo
(@pxref{Reporting problems, , Reporting problems, send-pr, Reporting
Problems With send-pr}).
@end ifinfo
@iftex
(@pxref{Reporting problems, , Reporting problems}).
@end iftex

@item query-pr
Used by software maintainers to query the @code{@value{NAMEUC}} database
(@pxref{Querying, , Querying individual Problem Reports}).

@item edit-pr
Used by software maintainers to edit Problem Reports (to record new
data, to change the responsible party, etc.) (@pxref{Editing, , Editing
existing Problem Reports}).

@item mkcat
Used by the @code{@value{NAMEUC}} administrator when creating new
categories (@pxref{categories, , The @code{categories} file}).

@item rmcat
Does the opposite of @code{mkcat}, i.e. removes categories
(@pxref{Management, , Managing @code{@value{NAMEUC}}}).

@item mkdist
Used by the @code{@value{NAMEUC}} administrator when creating a
distribution of the program @code{send-pr} for offsite submitters of PRs
(@pxref{Configuring send-pr, , Configuring send-pr for the outside
world}).

@item gen-index
Used by the @code{@value{NAMEUC}} administrator if the index file
becomes corrupted, or if an up-to-date copy of it is wanted for some
reason.  @code{gen-index} builds an index and prints it to the standard
output (@pxref{Management, , Managing @code{@value{NAMEUC}}}).

@item 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 (@pxref{Introduction, , Introducing
@code{@value{NAMEUC}}}).

@item file-pr
The internal program which files Problem Reports as they come in
(@pxref{Introduction, , Introducing @code{@value{NAMEUC}}}).

@item at-pr
Used internally by @code{@value{NAMEUC}} to send reminders to
maintainers based on quoted response times (@pxref{Introduction, ,
Introducing @code{@value{NAMEUC}}}).

@item pr-edit
Used by @code{edit-pr} to error-check and submit edited Problem Reports
(@pxref{Editing, , Editing existing Problem Reports}).
@c uncomment this line when this chapter is written...
@c ; also @pxref{Writing Tools, , Writing @code{@value{NAMEUC}} tools}).

@item pr-addr
Provides a valid electronic mail address for a given @var{responsible}
name tag.  Information is drawn from the file
@w{@file{@var{@value{NAMEUC}_ROOT}/@value{NAMELC}-adm/responsible}}.
Used internally.
@end table

Of these, only @code{send-pr}, @code{query-pr}, and @code{edit-pr} are
installed in a public directory.  The database itself is write-protected
solely to maintain data consistency.  @code{mkcat}, @code{rmcat},
@code{gen-index} and @code{mkdist} are designed for use by a database or
system administrator, while @code{at-pr}, @code{pr-edit},
@code{pr-addr}, @code{file-pr}, and @w{@samp{queue-pr -q}} are
completely internal and not meant to be called by hand.
@w{@samp{queue-pr -r}} can be run by hand, but it is usually easiest to
let it run periodically via @code{cron}.

@menu
* Querying::             Querying individual Problem Reports
* Editing::              Editing existing Problem Reports
* Management::           Managing @value{NAMEUC}
* Configuring send-pr::  Configuring `send-pr' for the outside world
@end menu

@c ---------------------------------------------------------------
@node Querying
@section Querying individual Problem Reports
@cindex using @code{query-pr}
@cindex invoking @code{query-pr}
@cindex @code{query-pr}
@cindex querying invdividual problem reports

You can obtaining data from the database through the program
@code{query-pr}, which uses the search parameters you provide with
options and/or arguments to find matching Problem Reports in the
database.  You can invoke @code{query-pr} from within Emacs as well as
from the shell.

All arguments to @code{query-pr} are optional.  If you don't specify a
PR and don't give any search parameters, @code{query-pr} will display
the entire database.  All arguments are considered as PR numbers to
display.  Any number of options can be given; all are connected with a
logical @code{AND}.

@menu
* invoking query-pr::
* example queries::
@end menu

@node invoking query-pr
@subsection Invoking @code{query-pr}

@code{query-pr} uses the same arguments whether it is invoked from the
shell or from Emacs.  From the shell, simply type @kbd{query-pr},
followed by any search parameters you wish to exercise.  From Emacs,
type @w{@kbd{M-x query-pr}}, and you will be prompted for search
parameters in the minibuffer.  Use 

@example
C-x `     @emph{or}
M-x next-error
@end example

@noindent
to scroll through the matching PRs.

The usage for @code{query-pr} is:

@smallexample
query-pr  [@var{@value{NAMELC}-id}] [-i | --sql] [-F | --full]
          [-d @var{directory} | --directory=@var{directory}]
          [-c @var{category} | --category=@var{category}]
          [-S @var{submitter} | --submitter=@var{submitter}]
          [-r @var{responsible} | --responsible=@var{responsible}]
          [-s @var{state} | --state=@var{state}]
          [-C [@var{yes} | @var{no}] | --confidential=[@var{yes} | @var{no}]]
          [-e @var{severity} | --severity=@var{severity}]
          [-p @var{priority} | --priority=@var{priority}]
          [-O @var{originator} | --originator=@var{originator}]
          [-o @var{outfile} | --output=@var{outfile}]
          [-P | --print-path]
          [-x | --skip-closed]
          [-q | --summary]
          [-V | --version] [-h | --help ]
@end smallexample

Without the @samp{-F} or @samp{--full} option, @code{query-pr} will only
display a ``header'' for each PR which meets the search criteria.  Any
number of the options listed may be included in the search criteria.

@table @code
@item @var{@value{NAMELC}-id}
The identification number of the PR you wish to view.

@item -i
@itemx --sql
Prints information in a form readable by an SQL database; see
@ref{example queries, , Example queries}.

@item -F
@itemx --full
Prints the full Problem Report rather than just summary information.

@item -d @var{directory}
@itemx --directory=@var{directory}
Changes the directory to @var{directory} from @var{@value{NAMEUC}_ROOT}.

@item -c @var{category}
@itemx --category=@var{category}
Search only for PRs with a @samp{Category} field of @var{category}.

@item -S @var{submitter}
@itemx --submitter=@var{submitter}
Search only for PRs with a @samp{Submitter} field of @var{submitter}.

@item -r @var{responsible}
@itemx --responsible=@var{responsible}
Search only for PRs with a @samp{Responsible} field of @var{responsible}.

@item -s @var{state}
@itemx --state=@var{state}
Search only for PRs with a @samp{State} field of @var{state}.  Values
will be one of: @code{open}, @code{analyzed}, @code{suspended},
@code{feedback}, or @code{closed}.

@item -C [@var{yes} | @var{no}]
@itemx --confidential=[@var{yes} | @var{no}]
Search only for PRs with a @samp{Confidential} field of either @var{yes}
or @var{no}.  If this option is not given, all PRs will be eligible for
the search regardless of their confidentiality.

@item -e @var{severity}
@itemx --severity=@var{severity}
Search only for PRs with a @samp{Severity} field of @var{severity}.
Values will be one of: @code{critical}, @code{serious}, or
@code{non-critical}.

@item -p @var{priority}
@itemx --priority=@var{priority}
Search only for PRs with a @samp{Priority} field of @var{priority}.
Values will be one of: @code{high}, @code{medium}, or @code{low}.

@item -O @var{originator}
@itemx --originator=@var{originator}
Search only for PRs with an @samp{Originator} field of @var{originator}.
Since this option does not reference the index, queries using it will be
much faster if another search criterion is used that @emph{is} part of
the index.

@item -o @var{outfile}
@itemx --output=@var{outfile}
Print all output to @var{outfile} rather than to the standard output.

@item -P
@itemx --print-path
Prints the path which @code{query-pr} used to find the current PR.  A
line of the form @samp{@var{directory}/@var{number}:@var{number}} will
be printed before each PR.  You will probably never want to use this
option; it is automatically used from within Emacs to facilitate
scrolling through groups of PRs with @kbd{C-x `}.

@item -x
@itemx --skip-closed
Omit closed PRs from the search path.  This option is ignored if you are
doing a search on the @samp{>State:} field (using @samp{-s} or
@samp{--state=@var{state}}).

@item -q
@itemx --summary
Print a short single-line summary of PR information.

@item -V
@itemx --version
Print the version number of @code{query-pr}.

@item -h
@itemx --help
Print a brief usage summary.
@end table

@node example queries
@subsection Example queries
@cindex example queries
@cindex @code{query-pr --sql}

The following query:

@smallexample
query-pr --category=rats --responsible=fred --state=analyzed
@end smallexample

@noindent
yields all PRs in the database which contain the fields:

@smallexample
>Category:     rats         @emph{and}
>Responsible:  fred         @emph{and}
>State:        analyzed
@end smallexample

The following query:

@smallexample
query-pr 500 --submitter=icabod
@end smallexample

@noindent
returns summary information for PR number 500 if and only if its
@samp{Submitter-Id} field contains the value @samp{mitchell} (i.e., only
if PR number 500 was submitted by @code{mitchell}.)

The following example shows another alternative output function:

@smallexample
query-pr --sql @var{search criteria@dots{}}
@end smallexample

@noindent
The @samp{--sql} (or @samp{-i}) option prints information in a format
which can be uploaded into a relational database.  The output is one
line per PR, delimited with pipe (@samp{|}) symbols, and contains the
following fields in order:

@smallexample
@var{id-number} | @var{category} | @var{synopsis} | @var{confidential} | \
@var{severity} | @var{priority} | @var{responsible} | @var{state} | @var{class} | \
@var{submitter-id} | @var{arrival-date} | @var{originator} | @var{release}
@end smallexample

@c ---------------------------------------------------------------
@node Editing
@section Editing existing Problem Reports
@cindex using @code{edit-pr}
@cindex invoking @code{edit-pr}
@cindex @code{edit-pr}

Use @code{edit-pr} to make changes to existing PRs in the database.  The
shell script and Emacs Lisp file are designed to keep the data in each
Problem Report and in the index consistent, and also provide an easy and
safe way to edit PRs.  State changes (when progress toward a solution is
being made) and responsibility changes (``passing the bug'') are tracked
in the @samp{>Audit-Trail:} field.

@menu
* edit-pr in Emacs::
* edit-pr from the shell::
@end menu

@node edit-pr in Emacs
@subsection @code{edit-pr} in Emacs
@cindex @code{edit-pr} in Emacs

Call @code{edit-pr} from within Emacs with @w{@kbd{M-x edit-pr}}.  You
will be prompted for a PR identification number; type the number of the
PR you wish to edit.

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

@table @code
@item C-c C-s
@itemx @value{NAMELC}-submit-pr
Save and submit the PR currently being edited.  Do this when you're
finished editing; if you simply kill the buffer, your changes will be
lost.

@item C-c C-e
@itemx edit-pr
Runs @code{edit-pr} in a new buffer.

@item C-c C-a
@itemx @value{NAMELC}-mail-reply
Sends mail to the originator of this PR, using the address in the
@samp{From:} field of the mail header.

@item C-c RET
@itemx @value{NAMELC}-mail-other-window
Splits the current window, and sends mail to the originator of this PR,
using the address in the @samp{From:} field of the mail header, in the
new window.

@item C-c C-r
@itemx @value{NAMELC}-responsible-change-from-to
Change the @samp{Responsible} field.  You will be prompted for the new
responsible person.  Each time the @samp{Responsible} field is changed,
the previous value and the reason for the change are both mailed to the
responsible parties and the submitter, and recorded in the
@samp{Audit-Trail} section of the PR as follows:

@table @asis
@item @code{Responsible-Changed-<From>-<To>}: Records the value change.

@item @code{Responsible-Changed-By}: Your name here.

@item @code{Responsible-Changed-When}: Records the current date.

@item @code{Responsible-Changed-Why}: Emacs places the point in this
field as a prompt for you to fill in the reason for the change. 
@end table

@item C-c C-s
@itemx @value{NAMELC}-state-change-from-to
Change the @samp{State} field.  You will be prompted for the new state.
Each time the @samp{State} field is changed, the previous value and the
reason for the change are both mailed to the responsible parties and the
submitter, and recorded in the @samp{Audit-Trail} section of the PR as
follows:

@table @asis
@item @code{State-Changed-<From>-<To>}: Records the value change.

@item @code{State-Changed-By}: Your name here.

@item @code{State-Changed-When}: Records the current date.

@item @code{State-Changed-Why}: Emacs places the point in this field as
a prompt for you to fill in the reason for the change. 
@end table

@item M-C-b
@itemx @value{NAMELC}-backward-field
Moves the point to the beginning of the value of the current field.

@item M-C-f
@itemx @value{NAMELC}-forward-field
Moves the point to the end of the value of the current field.

@item M-p
@itemx @value{NAMELC}-previous-field
Moves the point back one field to the beginning of the value of the
previous field.

@item M-n
@itemx @value{NAMELC}-next-field
Moves the point forward one field to the beginning of the value of the
next field.
@end table

@node edit-pr from the shell
@subsection @code{edit-pr} from the shell
@cindex @code{edit-pr} from the shell

The usage for the @code{edit-pr} shell script is:

@smallexample
edit-pr @var{@value{NAMELC}-id} [-v | --version] [-h | --help]
@end smallexample

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

@table @code
@item -v @emph{or} --version
Prints the current version number of @code{edit-pr}.

@item -h @emph{or} --help
Prints the usage message shown above.
@end table

@code{edit-pr} first examines the value you specify for
@var{@value{NAMELC}-id} and locks the corresponding PR 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, @code{edit-pr} will tell you the name of the
person who has it locked.  

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

Edit the PR, changing any relevant fields or adding to existing
information.  When you exit the editor, you will be asked on the
standard input to specify reasons for changes if you've changed either
the @samp{Responsible} field or the @samp{State} field; the information
you provide when changing either of these two fields is tracked along
with the change that occurred, your name, and the time of change in a
section of the PR called the @samp{Audit-Trail}.  Copies of the
@samp{Audit-Trail} are then mailed to you, to
@code{@value{NAMELC}-admin}, and to the person @code{Responsible} for
the bug as listed in the @w{@file{@value{NAMELC}-adm/responsible}} (both
the new @code{Responsible} and the old one, if that value changed).

@c ---------------------------------------------------------------
@node Management
@section Managing @code{@value{NAMEUC}}
@cindex administering @code{@value{NAMEUC}}
@cindex managing @code{@value{NAMEUC}}
@cindex @code{@value{NAMEUC}} management
@cindex duties for @code{@value{NAMELC}-admin}

In daily usage, @code{@value{NAMEUC}} is self-maintaining.  However,
there are various administrative duties which will have to be performed
periodically:

@table @emph
@item emptying the @code{pending} directory
@cindex emptying the @code{pending} directory
If a Problem Report arrives with a @samp{Category} field that is
unrecognized by the @file{@value{NAMELC}-adm/categories} file, it is
placed in the directory @w{@file{@var{@value{NAMEUC}_ROOT}/pending}}, as
@code{@value{NAMEUC}} has no way of knowing which subdirectory it should
be filed under.  @code{@value{NAMEUC}} sends a notice to the
@code{@value{NAMELC}-admin} and to the party responsible for that
submitter (as listed in the @file{submitters} file) when this occurs.

To file these PRs, simply call @code{edit-pr} on each file in the
@file{pending} directory and repair the problematic 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 the
originator's intentions.

@item adding new categories
@cindex adding new categories
@cindex @code{mkcat}
To add a new category, simply insert a new line in the
@w{@file{categories}} file and then run the program @code{mkcat}.  This
automatically creates a subdirectory in @var{@value{NAMEUC}_ROOT} for
this category, and updates the local list of known categories for
@code{send-pr}.  @xref{categories, , The @code{categories} file}.

It is important to note that only your local @code{send-pr} will have
access to this new information; any copies of @code{send-pr} which you
have distributed will 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
@w{@file{@var{libdir}/@value{NAMELC}/@var{support-site}}} from the
distribution you provided, or you must build another distribution of
@code{send-pr} with this new information and redistribute it.

@item removing categories
@cindex removing categories
@cindex @code{rmcat}
To remove a category, you need to:

@itemize @bullet
@item
make sure the relevant subdirectory is empty (in other words, make sure
no PRs exist for the category you wish to remove);

@item
remove the cateogry listing from the @file{categories} file;

@item
invoke @samp{rmcat @var{category}} to remove @var{category} (any number
of categories may be specified on the command line to @code{rmcat}, so
long as they abide by the above constraints).
@end itemize

@item building a distribution of @code{send-pr}
@cindex building a distribution of @code{send-pr}
@cindex @code{mkdist}
After you edit your @w{@file{categories}} file to reflect the nature of
your support activities, you can build a distribution of this custom
category configuration by invoking the command @code{mkdist}.

@code{mkdist} creates a @file{Makefile} and a valid category list in a
directory which you specify on the command line, which will contain a
full distribution of the program @code{send-pr}, including a
@code{Makefile}, an up-to-date list of categories your organization
supports, and all @code{send-pr} documentation.  @xref{Configuring
send-pr, , Configuring @code{send-pr} for the outside world}.

@item building a new index
@cindex building a new index
@cindex @code{gen-index}
If for some reason the @file{index} becomes corrupted, or if you wish to
generate a new one for some reason, use the program @code{gen-index} as
follows.

@example
gen-index [-n | --numeric] [-d @var{dir} | --directory=@var{dir}]
          [-o @var{file} | --outfile=@var{file}] [-h | --help]
@end example

@noindent
With no options, @code{gen-index} generates an index that is ordered the
same as the order of the categories as they appear in the
@file{categories} file.  The options are:

@table @code
@item -n
@itemx --numeric
Sort index entries numerically.

@item -d @var{dir}
@itemx --directory=@var{dir}
Use @var{dir} as the root directory.

@item -o @var{file}
@itemx --outfile=@var{file}
Place output in the file @var{file} rather than sending it to standard
output.

@item -h
@itemx --help
Print the usage for @code{gen-index}.
@end table

@item removing file locks from failed editing sessions
@cindex removing file locks from failed editing sessions
@code{edit-pr} ``locks'' each file while the file is being edited.  This
is to ensure that no two users edit the same PR at the same time, thus
avoiding data collisions.  If @code{edit-pr} crashes for some reason,
however, the lock remains in place, as @code{edit-pr} does not remove
the lock until the new PR is in place.  File locks are simply files in
the database named

@smallexample
@var{@value{NAMEUC}_ROOT}/@var{category}/@var{@value{NAMELC}-id}.lock
@end smallexample

@noindent
where @var{@value{NAMELC}-id} is the PR being edited.

If a @code{@value{NAMEUC}} user finds a PR locked, first make sure that
no one else is editing that PR (it has been known to occur that some
users will background an editing session and then forget that it
exists), then log in as @code{@value{NAMELC}} and run

@smallexample
@value{NAMELC}-bin/pr-edit --unlock @var{@value{NAMELC}-id}
@end smallexample

@item BACKING UP YOUR DATA
@cindex 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.

@item pruning log files
@cindex 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 bugs.
@end table

@c ---------------------------------------------------------------
@node Configuring send-pr
@section Configuring @code{send-pr} for the outside world
@cindex configuring @code{send-pr} for the outside world
@cindex invoking @code{mkdist}
@cindex using @code{mkdist}

Now that @code{@value{NAMEUC}} is up and running on your system, you
probably want to distribute @code{send-pr} to all your friends,
relatives, enemies, etc. so they can more easily submit bugs to your
organization.  To do this, log in as @code{@value{NAMELC}} and create a
directory to hold the distribution.  Then run the program

@smallexample
@value{NAMELC}-bin/mkdist @var{dist-directory} @var{release}
@end smallexample

@noindent
This creates a directory called @var{dist-directory} (you can specify a
full pathname) which contains a full distribution of the program
@code{send-pr}, including a @file{Makefile} and all the @code{send-pr}
documentation.  You can then simply package up this directory and send
it to your bug report submitters.

@c ===============================================================
@iftex
@chapter Reporting problems with @code{send-pr}
@cindex @code{send-pr}
@cindex using @code{send-pr}
@cindex invoking @code{send-pr}
@cindex reporting problems with @code{send-pr}

(@emph{Note:} This chapter consists of the text from the manual
@cite{Reporting Problems Using send-pr}, which is distributed with
@code{send-pr} as a standalone program (@pxref{Configuring send-pr, ,
Configuring @code{send-pr} for the outside world}).  In this chapter,
the pronouns @dfn{you} and @dfn{your} refer to a user of @code{send-pr},
who may or may not be at the same site which is running
@code{@value{NAMEUC}}.)

@down
@include send-pr.input
@up

@end iftex
@c ===============================================================
@ignore - this chapter is yet unwritten
@node Writing Tools
@chapter Writing @code{@value{NAMEUC}} tools

@end ignore
@c ===============================================================
@node Index
@unnumbered Index
@printindex cp

@contents

@bye

