Add info installation

7 files changed, 1874 insertions, 0 deletions

diff --git a/gnu/usr.bin/send-pr/doc/Makefile b/gnu/usr.bin/send-pr/doc/Makefile
new file mode 100644
index 0000000..3a09e56
--- /dev/null
+++ b/gnu/usr.bin/send-pr/doc/Makefile
@@ -0,0 +1,3 @@
+INFO = send-pr
+
+.include <bsd.info.mk>
diff --git a/gnu/usr.bin/send-pr/doc/categ.texi b/gnu/usr.bin/send-pr/doc/categ.texi
new file mode 100644
index 0000000..b02243e
--- /dev/null
+++ b/gnu/usr.bin/send-pr/doc/categ.texi
@@ -0,0 +1,123 @@
+@node Valid Categories
+@unnumberedsec Valid Categories
+@cindex valid categories
+@cindex example of a list of valid categories
+
+@table @code
+@item bfd
+@sc{gnu} binary file descriptor library.
+
+@item bifrabulator
+This one doesn't actually exist.
+
+@item binutils
+@sc{gnu} utilities for binary files (@code{ar}, @code{nm}, @code{size}@dots{}).
+
+@item bison
+@sc{gnu} parser generator.
+
+@item byacc
+Free parser generator.
+
+@item config
+Cygnus Support Software configuration and installation.
+
+@item cvs
+Concurrent Version System.
+
+@item diff
+@sc{gnu} @code{diff} program.
+
+@item doc
+Documentation and manuals.
+
+@item emacs
+@sc{gnu} Emacs editor and related functions.
+
+@item flex
+@sc{gnu} lexical analyzer.
+
+@item g++
+@sc{gnu} C++ compiler.
+
+@item gas
+@sc{gnu} assembler.
+
+@item gcc
+@sc{gnu} C compiler.
+
+@item gdb
+@sc{gnu} source code debugger.
+
+@item glob
+The filename globbing functions.
+
+@item gprof
+@sc{gnu} profiler.
+
+@item grep
+@sc{gnu} @code{grep} program.
+
+@item info
+@sc{gnu} @code{info} hypertext reader.
+
+@item ispell
+@sc{gnu} spelling checker.
+
+@item kerberos
+Kerberos authentication system.
+
+@item ld
+@sc{gnu} linker.
+
+@item libc
+Cygnus Support C Support Library.
+
+@item libg++
+@sc{gnu} C++ class library.
+
+@item libiberty
+@sc{gnu} @samp{libiberty} library.
+
+@item libm
+Cygnus Support C Math Library.
+
+@item make
+@sc{gnu} @code{make} program.
+
+@item makeinfo
+@sc{gnu} utility to build Info files from Texinfo documents.
+
+@item mas
+@sc{gnu} Motorola syntax assembler.
+
+@item newlib
+Cygnus Support C Support and Math Libraries.
+
+@item patch
+@sc{gnu} bug patch program.
+
+@item gnats
+@sc{gnu} Problem Report Management System.
+
+@item rcs
+Revision Control System.
+
+@item readline
+@sc{gnu} @code{readline} library.
+
+@item send-pr
+@sc{gnu} Problem Report submitting program.
+
+@item test
+Category to use when testing @code{send-pr}.
+
+@item texindex
+@sc{gnu} documentation indexing utility.
+
+@item texinfo
+@sc{gnu} documentation macros.
+
+@item other
+Anything which is not covered by the above categories.
+@end table
diff --git a/gnu/usr.bin/send-pr/doc/fields.texi b/gnu/usr.bin/send-pr/doc/fields.texi
new file mode 100644
index 0000000..e8921d6
--- /dev/null
+++ b/gnu/usr.bin/send-pr/doc/fields.texi
@@ -0,0 +1,518 @@
+@node Fields
+@section Problem Report format
+@cindex Problem Report format
+@cindex format
+@cindex database similarities
+@cindex fields
+
+The format of a PR is designed to reflect the nature of @sc{gnats} as a
+database.  Information is arranged into @dfn{fields}, and kept in
+individual records (Problem Reports).
+
+Problem Report fields are denoted by a keyword which begins with
+@samp{>} and ends with @samp{:}, as in @samp{>Confidential:}.  Fields
+belong to one of three data types:
+
+@table @asis
+@cindex Problem Report data types
+@cindex @emph{Enumerated} data types
+@item @sc{Enumerated}
+One of a specific set of values, which vary according to the field.  The
+value for each keyword must be on the same line as the keyword.  These
+values are not configurable (yet).
+
+@ifset SENDPR
+For each @sc{Enumerated} keyword, the possible choices are listed in the
+@code{send-pr} template as a comment.
+@end ifset
+The following fields are @sc{Enumerated} format; see the descriptions of
+fields below for explanations of each field in detail:
+
+@smallexample
+@group
+>Confidential:   >Severity:       >Priority:
+>Class:          >State:          >Number:
+@end group
+@end smallexample
+
+@cindex @emph{Text} data types
+@item @sc{Text}
+One single line of text which must begin and end on the same line (i.e.,
+before a newline) as the keyword.  See the descriptions of fields below
+for explanations of each field in detail.  The following fields are
+@sc{Text} format:
+
+@smallexample
+@group
+>Submitter-Id:   >Originator:     >Synopsis:
+>Category:       >Release:        >Responsible:
+>Arrival-Date:
+@end group
+@end smallexample
+
+@cindex @emph{MultiText} data types
+@item @sc{MultiText}
+Text of any length may occur in this field.  @sc{MultiText} may span
+multiple lines and may also include blank lines.  A @sc{MultiText} field
+ends only when another keyword appears.  See the descriptions of fields
+below for explanations of each field in detail.  
+
+The following fields are @sc{MultiText} format:
+
+@smallexample
+@group
+>Organization:   >Environment:    >Description:
+>How-To-Repeat:  >Fix:            >Audit-Trail:
+>Unformatted:
+@end group
+@end smallexample
+
+@end table
+
+A Problem Report contains two different types of fields: @dfn{Mail
+Header} fields, which are used by the mail handler for delivery, and
+@dfn{Problem Report} fields, which contain information relevant to the
+Problem Report and its submitter.  A Problem Report is essentially a
+specially formatted electronic mail message.
+
+@ifclear SENDPR
+@subheading Example Problem Report
+@end ifclear
+
+The following is an example Problem Report.  Mail headers are at the
+top, followed by @sc{gnats} fields, which begin with @samp{>} and end
+with @samp{:}.  The @samp{Subject:} line in the mail header and the
+@samp{>Synopsis:} field are usually duplicates of each other.
+
+@cindex sample Problem Report
+@cindex example Problem Report
+@cindex Problem Report template
+@cartouche
+@smallexample
+@group
+Message-Id:  @var{message-id}
+Date:        @var{date}
+From:        @var{address}
+Reply-To:    @var{address}
+To:          @var{bug-address}
+Subject:     @var{subject}
+
+>Number:       @var{gnats-id}
+>Category:     @var{category}
+>Synopsis:     @var{synopsis}
+>Confidential: yes @emph{or} no
+>Severity:     critical, serious, @emph{or} non-critical
+>Priority:     high, medium @emph{or} low
+>Responsible:  @var{responsible}
+>State:        open, analyzed, suspended, feedback, @emph{or} closed
+>Class:        sw-bug, doc-bug, change-request, support, 
+@ifset SENDPR
+@emph{or} duplicate
+@end ifset
+@ifclear SENDPR
+duplicate, @emph{or} mistaken
+@end ifclear
+>Submitter-Id: @var{submitter-id}
+>Arrival-Date: @var{date}
+>Originator:   @var{name}
+>Organization: @var{organization}
+>Release:      @var{release}
+>Environment:
+   @var{environment}
+>Description:
+   @var{description}
+>How-To-Repeat:
+   @var{how-to-repeat}
+>Fix:
+   @var{fix}
+>Audit-Trail:
+@var{appended-messages@dots{}}
+State-Changed-From-To: @var{from}-@var{to}
+State-Changed-When: @var{date}
+State-Changed-Why:
+   @var{reason}
+Responsible-Changed-From-To: @var{from}-@var{to}
+Responsible-Changed-When: @var{date}
+Responsible-Changed-Why:
+   @var{reason}
+>Unformatted:
+   @var{miscellaneous}
+@end group
+@end smallexample
+@end cartouche
+
+@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 by @code{send-pr}:
+
+@table @code
+@cindex @code{To:} header
+@item To:
+The preconfigured mail address for the Support Site where the PR is to
+be sent, automatically supplied by @code{send-pr}.
+
+@cindex @code{Subject:} header
+@item Subject:
+A terse description of the problem.  This field normally contains the
+same information as the @samp{>Synopsis:} field.
+
+@cindex @code{From:} header
+@item From:
+Usually supplied automatically by the originator's mailer; should
+contain the originator's electronic mail address.
+
+@cindex @code{Reply-To:} header
+@item Reply-To:
+A return address to which electronic replies can be sent; in most cases,
+the same address as the @code{From:} field.
+@end table
+
+@ifclear SENDPR
+@cindex @code{Received-By:} headers
+One of the configurable options for @sc{gnats} is whether or not to
+retain @w{@samp{Received-By:}} headers, which often consume a lot of
+space and are not often used.  @xref{Local configuration,,Changing your
+local configuration}.
+@end ifclear
+
+@c ----------------------
+@node Problem Report fields
+@subsection Problem Report fields
+@cindex GNATS database fields
+@cindex field format
+
+@c FIXME - this node is loooooooooooooooong...
+
+@subheading Field descriptions
+
+The following fields are present whenever a PR is submitted via the
+program @code{send-pr}.  @sc{gnats} adds additional fields when the PR
+arrives at the Support Site; explanations of these follow this list.
+
+@cindex fields - list
+@cindex GNATS fields - list
+@table @code
+@item >Submitter-Id:
+@cindex @code{Submitter-Id} field
+@cindex @code{>Submitter-Id:}
+(@sc{Text}) A unique identification code assigned by the Support Site.
+It is used to identify all Problem Reports coming from a particular
+site.  (Submitters without a value for this field can invoke
+@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 @code{Originator} field
+@cindex @code{>Originator:}
+(@sc{Text}) Originator's real name.  The default is the value of the
+originator's environment variable @code{NAME}.
+
+@item >Organization:
+@cindex @code{>Organization:}
+@cindex @code{Organization} field
+(@sc{MultiText}) The originator's organization.  The default value is 
+set with the variable @w{@code{DEFAULT_ORGANIZATION}} in the
+@ifclear SENDPR
+@file{config} file (@pxref{config,,The @code{config} file}).
+@end ifclear
+@ifset SENDPR
+@code{send-pr} shell script.
+@end ifset
+
+@item >Confidential:
+@cindex @code{Confidential} field
+@cindex @code{>Confidential:}
+@cindex confidentiality in PRs
+@cindex PR confidentiality
+(@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
+provided are not made publicly available (e.g., in regression test
+suites).  The default value is @samp{yes}.
+
+@item >Synopsis:
+@cindex @code{Synopsis} field
+@cindex @code{>Synopsis:}
+(@sc{Text}) One-line summary of the problem.  @w{@code{send-pr}} copies
+this information to the @samp{Subject:} line when you submit a Problem
+Report.
+
+@item >Severity:
+@cindex @code{Severity} field
+@cindex @code{>Severity:}
+(@sc{Enumerated}) The severity of the problem.  Accepted values include:
+
+@table @code
+@cindex @emph{critical} severity problems
+@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 problems
+@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 problems
+@item non-critical
+The product, component or concept is working in general, but lacks
+features, has irritating behavior, does something wrong, or doesn't
+match its documentation.
+@end table
+The default value is @samp{serious}.
+@sp 1
+
+@item >Priority:
+@cindex @code{Priority} field
+@cindex @code{>Priority:}
+(@sc{Enumerated}) How soon the originator requires a solution.  Accepted
+values include:
+
+@table @code
+@cindex @emph{high} priority problems
+@item high
+A solution is needed as soon as possible.
+
+@cindex @emph{medium} priority problems
+@item medium
+The problem should be solved in the next release.
+
+@cindex @emph{low} priority problems
+@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 @code{Category} field
+@cindex @code{>Category:}
+(@sc{Text}) The name of the product, component or concept where
+the problem lies.  The values for this field are defined by the Support
+Site. 
+@ifclear SENDPR
+@xref{categories,,The @code{categories} file}, for details.
+@end ifclear
+
+@item >Class:
+@cindex @code{Class} field
+@cindex @code{>Class:}
+(@sc{Enumerated}) The class of a problem can be one of the following:
+
+@table @code
+@cindex @emph{sw-bug} class
+@item sw-bug
+A general product problem.  (@samp{sw} stands for ``software''.)
+
+@cindex @emph{doc-bug} class
+@item doc-bug
+A problem with the documentation.
+
+@cindex @emph{change-request} class
+@item change-request
+A request for a change in behavior, etc.
+
+@cindex @emph{support} class
+@item support
+A support problem or question.
+
+@cindex @emph{duplicate} class
+@item duplicate (@var{pr-number})
+Duplicate PR.  @var{pr-number} should be the number of the original PR.
+
+@ifclear SENDPR
+@cindex @emph{mistaken} class
+@item mistaken  
+No problem, user error or misunderstanding.  This value is valid only at
+the Support Site.
+@end ifclear
+@end table
+
+@noindent
+The default is @samp{sw-bug}.
+@sp 1
+
+@item >Release:
+@cindex @code{Release} field
+@cindex @code{>Release:}
+(@sc{Text}) Release or version number of the product, component or
+concept.
+
+@item >Environment:
+@cindex @code{Environment} field
+@cindex @code{>Environment:}
+(@sc{MultiText}) Description of the environment where the problem occured:
+machine architecture, operating system, host and target types,
+libraries, pathnames, etc.
+
+@item >Description:
+@cindex @code{Description} field
+@cindex @code{>Description:}
+(@sc{MultiText}) Precise description of the problem.
+
+@item >How-To-Repeat:
+@cindex @code{How-To-Repeat} field
+@cindex @code{>How-To-Repeat:}
+(@sc{MultiText}) Example code, input, or activities to reproduce the
+problem.  The support organization uses example code both to reproduce
+the problem and to test whether the problem is fixed.  Include all
+preconditions, inputs, outputs, conditions after the problem, and
+symptoms.  Any additional important information should be included.
+Include all the details that would be necessary for someone else to
+recreate the problem reported, however obvious.  Sometimes seemingly
+arbitrary or obvious information can point the way toward a solution.
+See also @ref{Helpful hints,,Helpful hints}.
+
+@item >Fix:
+@cindex @code{Fix} field
+@cindex @code{>Fix:}
+(@sc{MultiText}) A description of a solution to the problem, or a patch
+which solves the problem.  (This field is most often filled in at the
+Support Site; we provide it to the submitter in case she has solved the
+problem.)
+
+@end table
+
+@noindent
+@sc{gnats} adds the following fields when the PR arrives at the Support
+Site:
+
+@table @code
+@cindex @code{Number} field
+@cindex @code{>Number:}
+@item >Number:
+(@sc{Enumerated}) The incremental identification number for this PR.
+@ifclear SENDPR
+This is included in the automated reply to the submitter (if that
+feature of @sc{gnats} is activated; @pxref{Local configuration,,Changing
+your local configuration}).  It is also included in the copy of the PR
+that is sent to the maintainer.
+@end ifclear
+
+The @samp{>Number:} field is often paired with the @samp{>Category:}
+field as
+
+@smallexample
+@var{category}/@var{number}
+@end smallexample
+
+@noindent
+in subsequent email messages.  This is for historical reasons, as well
+as because Problem Reports are stored in subdirectories which are named
+by category.
+
+@cindex @code{State} field
+@cindex @code{>State:}
+@item >State:
+(@sc{Enumerated}) The current state of the PR.  Accepted values are:
+
+@table @code
+@item open
+The PR has been filed and the responsible person notified.
+
+@item analyzed
+The responsible person has analyzed the problem.
+
+@item feedback
+The problem has been solved, and the originator has been given a patch
+or other fix.
+
+@item closed
+The changes have been integrated, documented, and tested, and the
+originator has confirmed that the solution works.
+
+@item suspended
+Work on the problem has been postponed.
+@end table
+
+@noindent
+The initial state of a PR is @samp{open}.  @xref{States,,States of
+Problem Reports}.
+
+@cindex @code{Responsible} field
+@cindex @code{>Responsible:}
+@item >Responsible:
+(@sc{Text}) The person responsible for this category.
+@ifclear SENDPR
+@sc{gnats} retrieves this information from the @file{categories} file
+(@pxref{categories,,The @code{categories} file}).
+@end ifclear
+
+@item >Arrival-Date:
+@cindex @code{>Arrival-Date:}
+@cindex @code{Arrival-Date} field
+(@sc{Text}) The time that this PR was received by @sc{gnats}.  The date
+is provided automatically by @sc{gnats}.
+
+@item >Audit-Trail:
+@cindex @code{>Audit-Trail:}
+@cindex @code{Audit-Trail} field
+(@sc{MultiText}) Tracks related electronic mail as well as changes in
+the @samp{>State:} and @samp{>Responsible:} fields with the sub-fields:
+
+@table @code
+@cindex @code{State-Changed-<From>-<To>:} in @code{>Audit-Trail:}
+@item @w{State-Changed-<From>-<To>: @var{oldstate}>-<@var{newstate}}
+The old and new @samp{>State:} field values.
+
+@cindex @code{Responsible-Changed-<From>-<To>:} in @code{>Audit-Trail:}
+@item @w{Responsible-Changed-<From>-<To>: @var{oldresp}>-<@var{newresp}}
+The old and new @samp{>Responsible:} field values.
+
+@cindex @code{State-Changed-By:} in @code{>Audit-Trail:}
+@cindex @code{Responsible-Changed-By:} in @code{>Audit-Trail:}
+@item State-Changed-By: @var{name}
+@itemx Responsible-Changed-By: @var{name}
+The name of the maintainer who effected the change.
+
+@cindex @code{State-Changed-When:} in @code{>Audit-Trail:}
+@cindex @code{Responsible-Changed-When:} in @code{>Audit-Trail:}
+@item State-Changed-When: @var{timestamp}
+@itemx Responsible-Changed-When: @var{timestamp}
+The time the change was made.
+
+@cindex @code{State-Changed-Why:} in @code{>Audit-Trail:}
+@cindex @code{Responsible-Changed-Why:} in @code{>Audit-Trail:}
+@item State-Changed-Why: @var{reason@dots{}}
+@itemx Responsible-Changed-Why: @var{reason@dots{}}
+The reason for the change.
+@end table
+
+@noindent
+@cindex subsequent mail
+@cindex other mail
+@cindex appending PRs
+@cindex saving related mail
+@cindex related mail
+The @samp{>Audit-Trail:} field also contains any mail messages received
+by @sc{gnats} related to this PR, in the order received.
+
+@item >Unformatted:
+@cindex @code{>Unformatted:}
+@cindex @code{Unformatted} field
+(@sc{MultiText}) Any random text found outside the fields in the
+original Problem Report.
+@end table
+
diff --git a/gnu/usr.bin/send-pr/doc/s-usage.texi b/gnu/usr.bin/send-pr/doc/s-usage.texi
new file mode 100644
index 0000000..06fefee
--- /dev/null
+++ b/gnu/usr.bin/send-pr/doc/s-usage.texi
@@ -0,0 +1,519 @@
+@c This is the usage section for send-pr.  It is called as 
+@c chapter (Invoking send-pr) by send-pr.texi, and also as
+@c section (Submitting Problem Reports) by gnats.texi (chapter/section
+@c identifiers are adjusted accordingly)
+
+@c FIXME!  This still seems jumbled...
+
+You can invoke @code{send-pr} from a shell prompt or from within
+@sc{gnu} Emacs using @w{@samp{M-x send-pr}}.
+
+@menu
+* using send-pr::             Creating new Problem Reports
+* send-pr in Emacs::          Using send-pr from within Emacs
+* send-pr from the shell::    Invoking send-pr from the shell
+* Helpful hints::
+@end menu
+
+@node using send-pr
+@section Creating new Problem Reports
+
+@c FIXME - this is a long node
+Invoking @code{send-pr} presents a PR @dfn{template} with a number of
+fields already filled in.  Complete the template as thoroughly as
+possible to make a useful bug report.  Submit only one bug with each PR.
+
+@cindex template
+A template consists of three sections:
+
+@table @dfn
+@item Comments
+The top several lines of a blank template consist of a series of
+comments that provide some basic instructions for completing the Problem
+Report, as well as a list of valid entries for the @samp{>Category:}
+field.  These comments are all preceded by the string @samp{SEND-PR:}
+and are erased automatically when the PR is submitted.  The
+instructional comments within @samp{<} and @samp{>} are also removed.
+(Only these comments are removed; lines you provide that happen to have
+those characters in them, such as examples of shell-level redirection,
+are not affected.)
+
+@item Mail Header
+@code{send-pr} creates a standard mail header.  @code{send-pr} completes
+all fields except the @samp{Subject:} line with default values.
+(@xref{Fields,,Problem Report format}.)
+
+@item @sc{gnats} fields
+These are the informational fields that @sc{gnats} uses to route your
+Problem Report to the responsible party for further action.  They should
+be filled out as completely as possible.  (@xref{Fields,,Problem Report
+format}.  Also see @ref{Helpful hints,,Helpful hints}.)
+@end table
+
+@ifset SENDPR
+@noindent
+For examples of a Problem Report template and complete Problem Report,
+see @ref{An Example}.
+@end ifset
+
+The default template contains your preconfigured @samp{>Submitter-Id:}.
+@code{send-pr} attempts to determine values for the @samp{>Originator:}
+and @samp{>Organization:} fields (@pxref{Fields,,Problem Report
+format}).  @code{send-pr} also attempts to find out some information
+about your system and architecture, and places this information in the
+@samp{>Environment:} field if it finds any.
+
+You may submit problem reports to different Support Sites from the
+default site by specifying the alternate site when you invoke
+@code{send-pr}.  Each @code{site} has its own list of categories for
+which it accepts Problem Reports.
+@c FIXME!  This should go in..
+@c For a list of sites to whom @code{send-pr} is configured to send
+@c Problem Reports, type @w{@samp{send-pr -S}}.
+@ifset SENDPR
+(@xref{default site,,Setting a default @var{site}}.)
+@end ifset
+
+@code{send-pr} also provides the mail header section of the template
+with default values in the @samp{To:}, @samp{From:}, and
+@samp{Reply-To:} fields.  The @samp{Subject:} field is empty.
+
+The template begins with a comment section:
+
+@cindex template comment section
+@cindex comment section in the PR template
+@smallexample
+@group
+SEND-PR: -*- send-pr  -*-
+SEND-PR: Lines starting with `SEND-PR' will be removed
+SEND-PR: automatically as well as all comments (the text 
+SEND-PR: below enclosed in `<' and `>').
+SEND-PR: 
+SEND-PR: Please consult the document `Reporting Problems 
+SEND-PR: Using send-pr' if you are not sure how to fill out
+SEND-PR: a problem report.
+SEND-PR:
+SEND-PR: Choose from the following categories:
+@end group
+@end smallexample
+
+@noindent
+and also contains a list of valid @code{>Category:} values for the
+Support Site to whom you are submitting this Problem Report.  One (and
+only one) of these values should be placed in the @code{>Category:}
+field.
+@ifset SENDPR
+A complete sample bug report, from template to completed PR, is shown in
+@ref{An Example}.  For a complete list of valid categories, type
+@w{@samp{send-pr -L}} at your prompt.  @xref{Valid Categories,,Valid
+Categories}, for a sample list of categories, .
+@end ifset
+
+@c FIXME.. this sounds awkward
+The mail header is just below the comment section.  Fill out the
+@samp{Subject:} field, if it is not already completed using the value of
+@samp{>Synopsis:}.  The other mail header fields contain default values.
+
+@cindex mail header section
+@smallexample
+@group
+To: @var{support-site}
+Subject: @emph{complete this field}
+From: @var{your-login}@@@var{your-site}
+Reply-To: @var{your-login}@@@var{your-site}
+X-send-pr-version: send-pr @value{VERSION}
+@end group
+@end smallexample
+
+@noindent
+where @var{support-site} is an alias for the Support Site you wish to
+submit this PR to.
+
+The rest of the template contains @sc{gnats} fields.  Each field is
+either automatically completed with valid information (such as your
+@samp{>Submitter-Id:}) or contains a one-line instruction specifying the
+information that field requires in order to be correct.  For example,
+the @samp{>Confidential:} field expects a value of @samp{yes} or
+@samp{no}, and the answer must fit on one line; similarly, the
+@samp{>Synopsis:} field expects a short synopsis of the problem, which
+must also fit on one line.  Fill out the fields as completely as
+possible.  @xref{Helpful hints,,Helpful hints}, for suggestions as to
+what kinds of information to include.
+
+In this example, words in @emph{italics} are filled in with
+pre-configured information:
+
+@cindex @code{send-pr} fields
+@smallexample
+@group
+>Submitter-Id: @emph{your submitter-id}
+>Originator:   @emph{your name here}
+>Organization:  
+    @emph{your organization}
+>Confidential:<[ yes | no ] (one line)>
+>Synopsis:    <synopsis of the problem (one line)>
+>Severity:    <[non-critical | serious | critical](one line)>
+>Priority:    <[ low | medium | high ] (one line)>
+>Category:    <name of the product (one line)>
+>Class:       <[sw-bug | doc-bug | change-request | support]>
+>Release:     <release number or tag (one line)>
+>Environment:
+         <machine, os, target, libraries (multiple lines)>
+
+>Description:
+       <precise description of the problem (multiple lines)>
+>How-To-Repeat:
+       <code/input/activities to reproduce (multiple lines)>
+>Fix:
+       <how to correct or work around the problem, if known 
+        (multiple lines)>
+@end group
+@end smallexample
+
+@cindex @code{Submitter-Id} field
+@cindex @code{>Submitter-Id:}
+When you finish editing the Problem Report, @code{send-pr} mails it to
+the address named in the @samp{To:} field in the mail header.
+@code{send-pr} checks that the complete form contains a valid
+@samp{>Category:}.
+
+@ifset SENDPR
+Your copy of @code{send-pr} should have already been customized on
+installation to reflect your @samp{>Submitter-Id:}.  (@xref{Installing
+send-pr, , Installing @code{send-pr} on your system}.)  If you don't
+know your @samp{>Submitter-Id:}, you can request it using
+@w{@samp{send-pr --request-id}}.  If your organization is not affiliated
+with the site you send Problem Reports to, a good generic
+@samp{>Submitter-Id:} to use is @samp{net}.
+@end ifset
+
+@cindex bad Problem Reports
+@cindex errors
+@cindex invalid Problem Reports
+If your PR has an invalid value in one of the @sc{Enumerated} fields
+(@pxref{Fields,,Problem Report format}), @code{send-pr} places the PR in
+a temporary file named @samp{/tmp/pbad@var{nnnn}} on your machine.
+@var{nnnn} is the process identification number given to your current
+@code{send-pr} session.  If you are running @code{send-pr} from the
+shell, you are prompted as to whether or not you wish to try editing the
+same Problem Report again.  If you are running @code{send-pr} from
+Emacs, the Problem Report is placed in the buffer
+@w{@samp{*send-pr-error*}}; you can edit this file and then submit it
+with
+
+@smallexample
+M-x gnats-submit-pr
+@end smallexample
+
+@cindex subsequent mail
+@cindex other mail
+@cindex appending PRs
+@cindex saving related mail
+@cindex related mail
+Any further mail concerning this Problem Report should be carbon-copied
+to the @sc{gnats} mailing address as well, with the category and
+identification number in the @samp{Subject:} line of the message.
+
+@smallexample
+Subject: Re: PR @var{category}/@var{gnats-id}: @var{original message subject}
+@end smallexample
+
+@noindent
+Messages which arrive with @samp{Subject:} lines of this form are
+automatically appended to the Problem Report in the @samp{>Audit-Trail:}
+field in the order received.
+
+@c ---------------------------------------------------------------
+@node send-pr in Emacs 
+@section Using @code{send-pr} from within Emacs
+@cindex using @code{send-pr} from within Emacs
+@cindex @code{send-pr} within Emacs
+@cindex invoking @code{send-pr} from Emacs
+@cindex interactive interface
+
+You can use an interactive @code{send-pr} interface from within @sc{gnu}
+Emacs to fill out your Problem Report.  We recommend that you
+familiarize yourself with Emacs before using this feature
+(@pxref{Introduction,,Introduction,emacs,GNU Emacs}).
+
+Call @code{send-pr} with @w{@samp{M-x send-pr}}.@footnote{If typing
+@w{@samp{M-x send-pr}} doesn't work, see your system administrator for
+help loading @code{send-pr} into Emacs.}  @code{send-pr} responds with a
+Problem Report template preconfigured for the Support Site from which
+you received @code{send-pr}.  (If you use @code{send-pr} locally, the
+default Support Site is probably your local site.)
+
+You may also submit problem reports to different Support Sites from the
+default site.  To use this feature, invoke @code{send-pr} with
+
+@smallexample
+C-u M-x send-pr
+@end smallexample
+
+@code{send-pr} prompts you for the name of a @var{site}.  @var{site} is
+an alias on your local machine which points to an alternate Support
+Site.
+
+@cindex Emacs
+@code{send-pr} displays the template and prompts you in the minibuffer
+with the line:
+@smallexample
+>Category: other
+@end smallexample
+
+@noindent
+Delete the default value @samp{other} @emph{in the minibuffer} and
+replace it with the keyword corresponding to your problem (the list of
+valid categories is in the topmost section of the PR template).  For
+example, if the problem you wish to report has to do with the @sc{gnu} C
+compiler, and your support organization accepts bugs submitted for this
+program under the category @samp{gcc}, delete @samp{other} and then type
+@w{@samp{gcc[@key{RET}]}}.  @code{send-pr} replaces the line
+
+@smallexample
+>Category:       <name of the product (one line)>
+@end smallexample
+
+@noindent
+in the template with
+
+@smallexample
+>Category:       gcc
+@end smallexample
+
+@noindent
+and moves on to another field.  
+
+@cindex completion in Emacs
+@cindex name completion in Emacs
+@w{@code{send-pr}} provides name completion in the minibuffer.  For
+instance, you can also type @w{@samp{gc[@key{TAB}]}}, and @code{send-pr}
+attempts to complete the entry for you.  Typing @w{@samp{g[@key{TAB}]}}
+may not have the same effect if several possible entries begin with
+@samp{g}.  In that case @code{send-pr} cannot complete the entry because
+it cannot determine whether you mean @samp{gcc} or, for example,
+@samp{gdb}, if both of those are possible categories.
+@w{@code{send-pr}} continues to prompt you for a valid entry until you
+enter one.
+
+@w{@code{send-pr}} prompts you interactively to enter each field for
+which there is a range of specific choices.  If you attempt to enter a
+value which is not in the range of acceptable entries, @code{send-pr}
+responds with @w{@samp{[No match]}} and allows you to change the entry
+until it contains an acceptable value.  This avoids unusable information
+(at least in these fields) and also avoids typographical errors which
+could cause problems later.
+
+@code{send-pr} prompts you for the following fields:
+
+@c FIXME - should these go before the discussion on completion?
+@example
+@group
+>Category:
+>Confidential: (@emph{default}:  no)
+>Severity:     (@emph{default}:  serious)
+>Priority:     (@emph{default}:  medium)
+>Class:        (@emph{default}:  sw-bug)
+>Release:
+>Synopsis:     (@emph{this value is copied to @code{Subject:}})
+@end group
+@end example
+
+@noindent
+After you complete these fields, @w{@code{send-pr}} places the cursor in
+the @samp{>Description:} field and displays the message
+
+@smallexample
+To send the problem report use: C-c C-c
+@end smallexample
+
+@noindent
+in the minibuffer.  At this point, edit the file in the main buffer to
+reflect your specific problem, putting relevant information in the
+proper fields.
+@ifset SENDPR
+@xref{An Example}, for a sample Problem Report.
+@end ifset
+
+@w{@samp{send-pr}} provides a few key bindings to make moving
+around in a template buffer more simple:
+
+@table @code
+@item C-c C-f
+@itemx M-x change-field
+Changes the field under the cursor.  @code{edit-pr} prompts you for a
+new value.
+
+@item M-C-b
+@itemx M-x gnats-backward-field
+Moves the cursor to the beginning of the value of the current field.
+
+@item M-C-f
+@itemx M-x gnats-forward-field
+Moves the cursor to the end of the value of the current field.
+
+@item M-p
+@itemx M-x gnats-previous-field
+Moves the cursor back one field to the beginning of the value of the
+previous field.
+
+@item M-n
+@itemx M-x gnats-next-field
+Moves the cursor forward one field to the beginning of the value of the
+next field.
+@end table
+
+@code{send-pr} takes over again when you type @samp{C-c C-c} to send the
+message.  @code{send-pr} reports any errors in a separate buffer, which
+remains in existence until you send the PR properly (or, of course,
+until you explicitly kill the buffer).
+
+For detailed instructions on using Emacs, see
+@ref{Introduction,,,emacs,GNU Emacs}.
+
+@node send-pr from the shell
+@section Invoking @code{send-pr} from the shell
+@cindex command line options
+@cindex invoking @code{send-pr} from the shell
+@cindex shell invocation
+
+@c FIXME!  Add [ -S ] right after [ -L ]...
+@smallexample
+send-pr [ @var{site} ]
+        [ -f @var{problem-report} | --file @var{problem-report} ]
+        [ -t @var{mail-address} | --to @var{mail-address} ]
+        [ --request-id ]
+        [ -L | --list ] [ -P | --print ]
+        [ -V | --version] [ -h | --help ]
+@end smallexample
+
+@var{site} is an alias on your local machine which points to an address
+used by a Support Site.  If this argument is not present, the default
+@var{site} is usually the site which you received @code{send-pr} from,
+or your local site if you use @sc{gnats} locally.
+@ifset SENDPR
+(@xref{default site,,Setting a default @var{site}}.)
+@end ifset
+
+Invoking @code{send-pr} with no options calls the editor named in your
+environment variable @code{EDITOR} on a default PR template.  If the
+environment variable @code{PR_FORM} is set, its value is used as a file
+name which contains a valid template.  If @code{PR_FORM} points to a
+missing or unreadable file, or if the file is empty, @code{send-pr}
+generates an error message and opens the editor on a default template.
+
+@table @code
+@item -f @var{problem-report}
+@itemx --file @var{problem-report}
+Specifies a file, @var{problem-report}, where a completed Problem Report
+already exists.  @code{send-pr} sends the contents of the file without
+invoking an editor.  If @var{problem-report} is @samp{-},
+@w{@code{send-pr}} reads from standard input.
+
+@item -t @var{mail-address}
+@itemx --to @var{mail-address}
+Sends the PR to @var{mail-address}. The default is preset when
+@code{send-pr} is configured.  @emph{This option is not recommended};
+instead, use the argument @var{site} on the command line.
+
+@item --request-id
+Sends a request for a @code{>Submitter-Id:} to the Support Site.
+
+@item -L
+@item --list
+@cindex listing valid categories
+Prints the list of valid @code{>Category:} values on standard output.
+No mail is sent.
+
+@ignore
+@item -S
+@itemx --sites
+Displays a list of valid @var{site} values on standard output.  No mail
+is sent.
+@end ignore
+
+@item -P
+@itemx --print
+Displays the PR template.  If the variable @code{PR_FORM} is set in your
+environment, the file it specifies is printed.  If @code{PR_FORM} is not
+set, @code{send-pr} prints the standard blank form.  If the file
+specified by @code{PR_FORM} doesn't exist, @code{send-pr} displays an
+error message.  No mail is sent.
+
+@item -V
+@itemx --version
+Displays the @code{send-pr} version number and a usage summary.  No mail
+is sent.
+
+@item -h
+@itemx --help
+Displays a usage summary for @code{send-pr}.  No mail is sent.
+@end table
+
+@node Helpful hints
+@section Helpful hints
+@cindex helpful hints
+@cindex Using and Porting GNU CC
+@cindex effective problem reporting
+@cindex kinds of helpful information
+@cindex information to submit
+@cindex Report all the facts!
+
+There is no orthodox standard for submitting effective bug reports,
+though you might do well to consult the section on submitting bugs for
+@sc{gnu} @code{gcc} in @ref{Bugs, , Reporting Bugs, gcc, Using and
+Porting GNU CC}, by Richard Stallman.  This section contains
+instructions on what kinds of information to include and what kinds of
+mistakes to avoid.
+
+In general, common sense (assuming such an animal exists) dictates the
+kind of information that would be most helpful in tracking down and
+resolving problems in software.  
+@itemize @bullet
+@item 
+Include anything @emph{you} would want to know if you were looking at
+the report from the other end.  There's no need to include every minute
+detail about your environment, although anything that might be different
+from someone else's environment should be included (your path, for
+instance).
+
+@item 
+Narratives are often useful, given a certain degree of restraint.  If a
+person responsible for a bug can see that A was executed, and then B and
+then C, knowing that sequence of events might trigger the realization of
+an intermediate step that was missing, or an extra step that might have
+changed the environment enough to cause a visible problem.  Again,
+restraint is always in order (``I set the build running, went to get a
+cup of coffee (Columbian, cream but no sugar), talked to Sheila on the
+phone, and then THIS happened@dots{}'') but be sure to include anything
+relevant.
+
+@item 
+Richard Stallman writes, ``The fundamental principle of reporting bugs
+usefully is this: @strong{report all the facts}.  If you are not sure
+whether to state a fact or leave it out, state it!''  This holds true
+across all problem reporting systems, for computer software or social
+injustice or motorcycle maintenance.  It is especially important in the
+software field due to the major differences seemingly insignificant
+changes can make (a changed variable, a missing semicolon, etc.).
+
+@item
+Submit only @emph{one} problem with each Problem Report.  If you have
+multiple problems, use multiple PRs.  This aids in tracking each problem
+and also in analyzing the problems associated with a given program.
+
+@item
+It never hurts to do a little research to find out if the bug you've
+found has already been reported.  Most software releases contain lists
+of known bugs in the Release Notes which come with the software; see
+your system administrator if you don't have a copy of these.
+
+@item
+The more closely a PR adheres to the standard format, the less
+interaction is required by a database administrator to route the
+information to the proper place.  Keep in mind that anything that
+requires human interaction also requires time that might be better spent
+in actually fixing the problem.  It is therefore in everyone's best
+interest that the information contained in a PR be as correct as
+possible (in both format and content) at the time of submission.
+@end itemize
diff --git a/gnu/usr.bin/send-pr/doc/send-pr.texi b/gnu/usr.bin/send-pr/doc/send-pr.texi
new file mode 100644
index 0000000..b9edd9c
--- /dev/null
+++ b/gnu/usr.bin/send-pr/doc/send-pr.texi
@@ -0,0 +1,657 @@
+\input texinfo   @c -*-texinfo-*-
+@setfilename send-pr.info
+@settitle Reporting Problems Using send-pr
+
+@setchapternewpage odd
+
+@include version.texi
+@set SENDPR
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* send-pr::                     Reporting problems--using send-pr
+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
+
+@titlepage
+@finalout
+@title Reporting Problems
+@subtitle Using @code{send-pr}, version @value{VERSION}
+@subtitle October 1993
+@author Jeffrey M. Osier
+@author Cygnus Support
+@page
+
+@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
+
+@c ---------------------------------------------------------------
+@node Top
+@top Overview
+@cindex foreword to @code{send-pr}
+@cindex overview to @code{send-pr}
+@cindex introduction to @code{send-pr}
+
+This manual documents @code{send-pr}, 
+@ifinfo
+version @value{VERSION},
+@end ifinfo
+which uses electronic mail to submit support questions and problem
+reports to a central Support Site.  No body of work is perfect, and
+support organizations understand this; @code{send-pr} is designed to
+allow users who have problems to submit reports of these problems to
+sites responsible for supporting the products in question, in a defined
+form which can be read by an electronically managed database.
+
+@cindex GNATS
+@code{send-pr} is part of a suite of programs known collectively as
+@sc{gnats}, the @sc{gnu} Problem Report Management System.  @sc{gnats}
+consists of several programs which, used in concert, formulate and
+partially administer a database of @dfn{Problem Reports}, or @dfn{PRs},
+at a central Support Site.  A PR goes through several states in its
+lifetime; @sc{gnats} tracks the PR and all information associated with it
+through each state and finally acts as an archive for PRs which have
+been @dfn{closed}.
+
+Because @code{send-pr} exists as a shell (@file{/bin/sh}) script and as
+an Elisp file for use with @sc{gnu} Emacs, it can be used from any
+machine on your network which can run a shell script and/or Emacs.
+
+In general, you can use any editor and mailer to submit valid Problem
+Reports, as long as the format required by @sc{gnats} is preserved.
+@code{send-pr} automates the process, however, and ensures that certain
+fields necessary for automatic processing are present.  @code{send-pr}
+is strongly recommended for all initial problem-oriented correspondence
+with your Support Site.  The organization you submit Problem Reports to
+supplies an address to which further information can be sent; the person
+responsible for the category of the problem you report contacts you
+directly.
+
+@menu
+* send-pr in detail::     Details about send-pr and GNATS
+* Invoking send-pr::      Editing and sending PRs
+* An Example::            A working example
+* Installing send-pr::    Installing send-pr on your system
+* Index::
+@end menu
+
+@node send-pr in detail
+@chapter Details about send-pr and GNATS
+
+@cindex details about @code{send-pr}
+@cindex Problem Reports
+A @dfn{Problem Report} is a message that describes a problem you are
+having with a body of work.  @code{send-pr} organizes this message into
+a form which can be understood and automatically processed by @sc{gnats},
+the @sc{gnu} Problem Report Management System.  A Problem Report is
+organized into @dfn{fields} which contain data describing you, your
+organization, and the problem you are announcing (@pxref{Fields,,Problem
+Report format}).  Problem Reports go through several defined states in
+their lifetimes, from @dfn{open} to @dfn{closed} (@pxref{States,,States
+of Problem Reports}).
+
+@menu
+* States::                     States of Problem Reports
+* Fields::                     Problem Report format
+@end menu
+
+@include states.texi
+
+@include fields.texi
+
+@node Invoking send-pr
+@chapter Editing and sending PRs
+@cindex editing and sending PRs
+@cindex sending PRs
+@cindex invoking send-pr
+@cindex using send-pr
+@cindex generating new PRs
+
+@include s-usage.texi
+
+@node An Example
+@chapter An Example
+@cindex an example
+@cindex example PR
+@cindex Cygnus Support
+@cindex GNU software support
+
+Cygnus Support in Mountain View, CA, uses @sc{gnats} and @code{send-pr}
+extensively for their support activities.  As a support company, Cygnus
+finds problem tracking to be a crucial part of everyday business.
+Cygnus supports the @sc{gnu} compiling tools (including @sc{gnats} and
+@code{send-pr}) over several many platforms
+
+With each shipment of the Cygnus Support Developer's Kit, customers
+receive the latest version of @code{send-pr}, which contains an
+up-to-date listing of valid categories (values for the @code{>Category:}
+field).  Using these tools, Cygnus' customers can communicate their
+problems to Cygnus effectively and receive automatic confirmation of
+receipt as well as notification of changes in the status of their
+reported problems.  Much of Cygnus' support mechanism relies on
+electronic mail.
+
+As an example, let's pretend we're a customer of Cygnus Support, and
+that we're having a problem compiling some of our software using the
+@sc{gnu} C compiler, which Cygnus supports.
+
+Assume that we're getting an error in our @code{bifrabulator} program
+wherein the @samp{prestidigitation} routines don't match with the
+@samp{whatsitsname}.  We've made sure we're following the rules of the
+program and checked the Release Notes from Cygnus and found that the bug
+isn't already known.  In other words, we're pretty sure we've found a
+bug.
+
+@cindex Imaginary Software, Ltd.
+Our first step is to call @code{send-pr}.  It really doesn't matter
+whether we use @code{send-pr} from the shell or from within Emacs.
+Indeed, if we use Emacs as a primary editor, calling @code{send-pr} from
+the shell is likely to start @code{send-pr} in an Emacs buffer anyway.
+So, since our company, @emph{Imaginary Software, Ltd.}, uses @sc{gnu}
+software extensively, we're pretty familiar with Emacs, so from within
+Emacs we type
+@smallexample
+M-x send-pr
+@end smallexample
+@noindent
+and we're greeted with the following screen:
+
+@cindex default PR template
+@cindex example of a default template
+@cindex blank PR template
+@cindex @code{bifrabulator}
+@cartouche
+@smallexample
+SEND-PR: -*- text  -*-
+SEND-PR: Lines starting with `SEND-PR' will be removed 
+SEND-PR: automatically as well as all comments (the text
+SEND-PR: below enclosed in `<' and `>').
+SEND-PR: Please consult the manual if you are not sure
+SEND-PR: how to fill out a problem report.
+SEND-PR:
+SEND-PR: Choose from the following categories:
+SEND-PR:
+SEND-PR:           bfd       binutils  bison       
+SEND-PR: byacc     clib      config    cvs         diff        
+SEND-PR: doc       emacs     flex      g++         gas         
+SEND-PR: gcc       gdb       glob      gprof       grep        
+SEND-PR: info      ispell    kerberos  ld          libg++      
+SEND-PR: libiberty make      makeinfo  mas         newlib      
+SEND-PR: other     patch     rcs       readline    send-pr     
+SEND-PR: test      texindex  texinfo   texinfo.tex 
+SEND-PR: bifrabulator  <---@emph{note: this one is fake}
+SEND-PR:
+To: cygnus-bugs@@cygnus.com 
+Subject: 
+From: jeffrey@@imaginary.com
+Reply-To: jeffrey@@imaginary.com
+X-send-pr-version: send-pr @value{VERSION}
+
+>Submitter-Id:  imaginary
+>Originator:    Jeffrey Osier
+>Organization:  
+Imaginary Software, Ltd.
+>Confidential:  <[ yes | no ] (one line)>
+>Synopsis:      <synopsis of the problem (one line)>
+>Severity:      <[ non-critical | serious | critical ] (one line)>
+>Priority:      <[ low | medium | high ] (one line)>
+>Category:      <name of the product (one line)>
+>Class:         <[sw-bug|doc-bug|change-request|support](oneline)>
+>Release:       <release number or tag (one line)>
+>Environment:
+         <machine, os, target, libraries (multiple lines)>
+System: SunOS imaginary.com 4.1.1 1 sun4
+Architecture: sun4
+
+>Description:
+       <precise description of the problem (multiple lines)>
+>How-To-Repeat:
+       <code/input/activities to reproduce (multiple lines)>
+>Fix:
+@iftex
+@hrule
+@end iftex
+-----Emacs: *send-pr*   (send-pr Fill)----All------------------
+@iftex
+@hrule
+@end iftex
+>Category: other[]
+@end smallexample
+@end cartouche
+@page
+We know from past experience that we need to set certain information into
+each field, so we compile all the information we know about our problem.
+We have some sample code which we know should work, even though it
+doesn't, so we'll include that.  Below is the completed PR; we send this
+using @kbd{C-c C-c}.  (The comments have been truncated).
+
+@cindex completed Problem Report
+@cindex example of a completed PR
+@cartouche
+@smallexample
+SEND-PR: Lines starting with `SEND-PR' will be removed
+SEND-PR: automatically as well as all comments (the text
+SEND-PR: @dots{}
+SEND-PR:
+To: cygnus-bugs@@cygnus.com 
+Subject: bifrabulator routines don't match
+From: jeffrey@@imaginary.com
+Reply-To: jeffrey@@imaginary.com
+X-send-pr-version: send-pr @value{VERSION}
+
+>Submitter-Id:  imaginary
+>Originator:    Jeffrey Osier
+>Organization:  
+Imaginary Software, Ltd.
+>Confidential:  no
+>Synopsis:      bifrabulator routines don't match
+>Severity:      serious
+>Priority:      medium
+>Category:      bifrabulator
+>Class:         sw-bug
+>Release:       progressive-930101
+>Environment:   
+System: SunOS imaginary.com 4.1.1 1 sun4
+Architecture: sun4 (SPARC)
+
+>Description:
+   the following code I fed into the bifrabulator came back 
+   with a strange error.  apparently, the prestidigitation 
+   routine doesn't match with the whatsitsname in all cases.
+
+>How-To-Repeat:
+   call the bifrabulator on the following code.
+   @emph{code sample@dots{}}
+
+>Fix:
+@iftex
+@hrule
+@end iftex
+-----Emacs: *send-pr*   (send-pr Fill)----All------------------
+@iftex
+@hrule
+@end iftex
+To send the problem report use: C-c C-c
+@end smallexample
+@end cartouche
+
+We type @kbd{C-c C-c}, and off it goes.  Now, we depend on Cygnus
+Support to figure out the answer to our problem.
+
+Soon afterward, we get the following message from Cygnus:
+
+@smallexample
+@group
+From: gnats (GNATS management)
+Sender: gnats-admin
+Reply-To: hacker@@cygnus.com
+To: jeffrey@@imaginary.com
+Subject: Re: bifrabulator/1425: routines don't match
+
+Thank you very much for your problem report.
+It has the internal identification: g++/1425.
+The individual assigned to look at your bug is:  hacker
+(F.B. Hacker)
+
+Category: bifrabulator
+Responsible: hacker
+Synopsis: bifrabulator routines don't match
+Arrival-Date: Sat Feb 30 03:12:55 1993
+@end group
+@end smallexample
+
+@noindent
+This is our receipt that the bug has been accepted and forwarded to the
+responsible party.
+
+@noindent
+A while later, we get the analysis:
+
+@smallexample
+@group
+To:  jeffrey@@imaginary.com
+From:  hacker@@cygnus.com
+Subject:  Re: bifrabulator/1425: routines don't match
+Reply-To: hacker@@cygnus.com
+
+Got your message, Jeff.  It seems that the bifrabulator was 
+confusing the prestidigitation routines with the realitychecker
+when lexically parsing the whatsitsname.
+
+I'm working on robustisizing the bifrabulator now.
+
+How about lunch next week?
+--
+F.B. Hacker
+Cygnus Support, Mountain View, CA  415 903 1400
+#include <std-disclaimer.h>
+@end group
+@end smallexample
+
+@noindent
+About the same time, we get another message from Cygnus.
+
+@cindex state change example
+@cindex example of a state change
+@smallexample
+@group
+From: hacker@@cygnus.com
+To:  jeffrey@@imaginary.com
+Subject:  Re: bifrabulator/1425: doesn't match prestidig
+Reply-To:  hacker@@cygnus.com
+
+
+             `F.B. Hacker' changed the state to `analyzed'.
+
+State-Changed-From-To: open-analyzed
+State-Changed-By: hacker
+State-Changed-When: Fri Feb 31 1993 08:59:16 1993
+State-Changed-Why:
+    figured out the problem, working on a patch this afternoon
+--
+F.B. Hacker
+Cygnus Support, Mountain View, CA  415 903 1400
+#include <std-disclaimer.h>
+@end group
+@end smallexample
+
+@noindent
+The bug has now been analyzed, and Cygnus is working on a solution.
+
+@noindent
+Sometime later, we get more mail from F.B.:
+
+@smallexample
+@group
+To:  jeffrey@@imaginary.com
+From:  hacker@@cygnus.com
+Subject:  Re: bifrabulator/1425: routines don't match
+Reply-To: hacker@@cygnus.com
+
+There's a patch now that you can ftp over and check out.
+
+Hey, that joke you sent me was great!  The one about the
+strings walking into a bar...  my boss laughed for an hour!
+--
+F.B. Hacker
+Cygnus Support, Mountain View, CA  415 903 1400
+#include <std-disclaimer.h>
+@end group
+@end smallexample
+@sp 2
+@smallexample
+@group
+From: hacker@@cygnus.com
+To:  jeffrey@@imaginary.com
+Subject:  Re: bifrabulator/1425: doesn't match prestidig
+Reply-To:  hacker@@cygnus.com
+
+
+             `F.B. Hacker' changed the state to `feedback'.
+
+State-Changed-From-To: analyzed-feedback
+State-Changed-By: hacker
+State-Changed-When: Fri Feb 31 1993 23:43:16 1993
+State-Changed-Why:
+    got the patch finished, notified Jeff at Imaginary Software
+--
+F.B. Hacker
+Cygnus Support, Mountain View, CA  415 903 1400
+#include <std-disclaimer.h>
+@end group
+@end smallexample
+
+@noindent
+The bug has gone into @dfn{feedback} status now, until we get the patch,
+install it and test it.  When everything tests well, we can mail F.B.
+back and tell him the bug's been fixed, and he can change the state of
+the PR from @dfn{feedback} to @dfn{closed}.
+
+Following is a list of valid @samp{>Category:} entries that are
+supported by Cygnus.
+
+@menu
+* Valid Categories::
+@end menu
+
+@c FIXME - is this list up to date?
+@include categ.texi
+
+@node Installing send-pr
+@appendix Installing @code{send-pr} on your system
+@cindex installation
+
+If you receive @code{send-pr} as part of a larger software distribution,
+it probably gets installed when the full distribution is installed.  If
+you are using @sc{gnats} at your site as well, you must decide where
+@code{send-pr} sends Problem Reports by default; see @ref{default site,,
+Setting a default @var{site}}.
+
+@menu
+* installation::   installing `send-pr' by itself
+* default site::   setting a default site
+@end menu
+
+@node installation
+@section Installing @code{send-pr} by itself
+@cindex installation procedure
+
+Install @code{send-pr} by following these steps (you may need
+@code{root} access in order to change the @file{aliases} file and to
+install @code{send-pr}):
+
+@itemize @bullet
+@item
+Unpack the distribution into a directory which we refer to as
+@var{srcdir}.
+
+@item
+Edit the file @file{Makefile} to reflect local conventions.
+Specifically, you should edit the variable @samp{prefix} to alter the
+installation location.  The default is @file{/usr/local}.  All files are
+installed under @samp{prefix} (see below).
+
+@item @emph{Run}
+@smallexample
+make all install [ info ] [ install-info ] [ clean ]
+@end smallexample
+
+@noindent
+The targets mean the following:
+
+@table @code
+@item all
+Builds @code{send-pr} and @code{install-sid}
+
+@item install
+Installs the following:
+
+@table @code
+@item install-sid
+@itemx send-pr
+into @file{@var{prefix}/bin}
+
+@item send-pr.1
+into @file{@var{prefix}/man/man1}
+
+@item @var{site}
+the list of valid @var{categories} for the Support Site from which you
+received @code{send-pr}, installed as
+@w{@file{@var{prefix}/lib/gnats/@var{site}}}
+
+@item send-pr.el
+into @w{@file{@var{prefix}/lib/emacs/lisp}}@footnote{If your main Emacs
+lisp repository is in a different directory from this, substitute that
+directory for @w{@file{@var{prefix}/lib/emacs/lisp}}.}
+@end table
+
+@item info (@emph{optional})
+Builds @file{send-pr.info} from @file{send-pr.texi}@*
+@c FIXME - is this still true?
+(@file{send-pr.info} is included with this distribution)
+
+@item install-info (@emph{optional})
+Installs @file{send-pr.info} into @w{@file{@var{prefix}/info}}
+
+@item clean (@emph{optional})
+Removes all intermediary build files that can be rebuilt from source
+code
+@end table
+
+@item
+Run
+
+@smallexample
+install-sid @var{your-sid}
+@end smallexample
+
+@noindent
+where @var{your-sid} is the identification code you received with
+@w{@code{send-pr}}.  @code{send-pr} automatically inserts this value
+into the template field @samp{>Submitter-Id:}.  If you've downloaded
+@code{send-pr} from the Net, use @samp{net} for this value.
+
+@item 
+Place the following line in
+@w{@file{@var{prefix}/lib/emacs/lisp/default.el}}, or instruct your
+users to place the following line in their @file{.emacs} files:
+
+@smallexample
+(autoload 'send-pr "send-pr" "Submit a Problem Report." t)
+@end smallexample
+
+@item 
+Create a mail alias for the Support Site from which you received
+@code{send-pr}, and for every site with which you wish to use
+@code{send-pr} to communicate.  Each alias must have a suffix of
+@samp{-gnats}.  The Support Site(s) will provide the correct addresses
+where these aliases should point.  For instance, edit your mail aliases
+file to contain something like:
+
+@smallexample
+# support sites; for use with send-pr
+cygnus-gnats:     bugs@@cygnus.com            # Cygnus Support
+bumblebee-gnats:  bumblebugs@@bumblebee.com   # Bumblebee Inc.
+mycompany-gnats:  bugs@@my.company.com (@emph{if you use @sc{gnats} locally})
+@end smallexample
+
+@code{send-pr} automatically searches for these aliases when you type
+
+@smallexample
+send-pr cygnus
+send-pr bumblebee
+send-pr @var{site}@dots{}
+@end smallexample
+
+@noindent
+@code{send-pr} also uses @var{site} to determine the categories of
+problems accepted by the site in question by looking in
+
+@smallexample
+@var{prefix}/lib/gnats/@var{site}
+@end smallexample
+
+@end itemize
+
+@node default site
+@section Setting a default @var{site}
+@cindex default @var{site}
+@cindex setting a default @var{site}
+
+@code{send-pr} is capable of sending Problem Reports to any number of
+Support Sites, using mail aliases which have @samp{-gnats} appended them.
+@code{send-pr} automatically appends the suffix, so that when you type
+
+@smallexample
+send-pr @var{site}
+@end smallexample
+
+@noindent
+the Problem Report goes to the address noted in the @file{aliases} file
+as @w{@samp{@var{site}-gnats}}.  You can do this in the Emacs version of
+@code{send-pr} by invoking the program with
+
+@smallexample
+C-u M-x send-pr
+@end smallexample
+
+@noindent
+You are prompted for @var{site}.
+
+@var{site} is also used to error-check the @samp{>Category:} field, as a
+precaution against sending mistaken information (and against sending
+information to the wrong site).
+
+You may also simply type
+
+@smallexample
+send-pr
+@end smallexample
+
+@noindent
+from the shell (or @w{@samp{M-x send-pr}} in Emacs), and the Problem
+Report you generate will be sent to the @var{site}, which is usually the
+site from which you received your distribution of @w{@code{send-pr}}.
+If you use @sc{gnats} at your own organization, the default is usually
+your local address for reporting problems.
+
+To change this, simply edit the file @file{Makefile} before installing
+and change the line 
+
+@smallexample
+GNATS_SITE = @var{site}
+@end smallexample
+
+@noindent
+to reflect the site where you wish to send PRs by default.
+
+@c ---------------------------------------------------------------
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@c ---------------------------------------------------------------
+@contents
+@bye
diff --git a/gnu/usr.bin/send-pr/doc/states.texi b/gnu/usr.bin/send-pr/doc/states.texi
new file mode 100644
index 0000000..16ea890
--- /dev/null
+++ b/gnu/usr.bin/send-pr/doc/states.texi
@@ -0,0 +1,53 @@
+@node States
+@section States of Problem Reports
+
+@cindex life-cycle of a Problem Report
+@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.  The originator of a PR receives notification automatically of
+any state changes.
+
+@table @dfn
+@cindex @emph{open} state
+@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 problem.  The analysis should
+contain a preliminary evaluation of the problem and an estimate of the
+amount of time and resources necessary to solve the problem.  It should
+also suggest possible workarounds.
+
+@item feedback
+@cindex @emph{feedback} state
+@cindex state---@dfn{feedback}
+The problem has been solved, and the originator has been given a patch
+or other fix.  The PR remains in this state until the originator
+acknowledges that the solution works.
+
+@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 have been integrated, documented, 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
+
diff --git a/gnu/usr.bin/send-pr/doc/version.texi b/gnu/usr.bin/send-pr/doc/version.texi
new file mode 100644
index 0000000..7aff863
--- /dev/null
+++ b/gnu/usr.bin/send-pr/doc/version.texi
@@ -0,0 +1 @@
+@set VERSION 3.2