Changes to gnats/doc/p-usage.texi

[Yngve Svendsen]

Index: gnats/doc/p-usage.texi
diff -c gnats/doc/p-usage.texi:1.10 gnats/doc/p-usage.texi:1.11
*** gnats/doc/p-usage.texi:1.10 Thu Oct 24 07:38:25 2002
--- gnats/doc/p-usage.texi      Thu Dec 12 09:27:18 2002
***************
*** 116,123 ****
--- 116,128 ----
  entries will also cause a copy of the new @samp{Audit-Trail} message to
  be sent.
  
+ Mail received at the PR submission email address and recognized by
+ @sc{gnats} as relating to an existing PR is also appended to the
+ @samp{Audit-Trail} field, see @ref{follow-up via email}.
+ 
  @menu
  * edit-pr from the shell::  Invoking @code{edit-pr} from the shell
+ * follow-up via email:: Following up via direct email
  @end menu
  
  @node edit-pr from the shell
***************
*** 184,189 ****
--- 189,246 ----
  information.  When you exit the editor, @code{edit-pr} prompts you on
  standard input for a reason if you have changed a field that requires
  specifying a reason for the change.
+ 
+ @node follow-up via email
+ @subsection Following up via direct email
+ @cindex follow-up via email
+ @cindex subsequent mail
+ @cindex related mail
+ 
+ If you have some additional information for a PR and for some reason
+ do not want to (or cannot) edit the PR directly, you may append
+ the information to the Audit-Trail field by mailing it to the PR
+ submission address.
+ 
+ In order for GNATS to be able to recognize the mail as pertaining to an
+ existing PR (as opposed to a new PR, see @ref{Submitting via e-mail,,}),
+ the Subject mail header field must contain a reference to the PR.
+ GNATS matches the Subject header against the regular expression
+ 
+ @smallexample
+ \<(PR[ \t#/]?|[-\w+.]+/)[0-9]+
+ @end smallexample
+ 
+ @noindent
+ to determine whether such a reference is present. Any text may precede
+ or follow the reference in the Subject header. If more than one reference
+ is present, the first is used and the rest ignored.
+ 
+ A PR reference matching the regular expression above has two parts. The
+ second is the PR number (one or more digits). The first is either the
+ capital letters 'PR' optionally followed by a separator character (blank,
+ tab, hash mark or forward slash) or the category name followed by a
+ forward slash. Following are some examples which match the regular
+ expression:
+ 
+ @smallexample
+ PR 123 PR4567 PR#890 gnats/4711
+ @end smallexample
+ 
+ The PR number and the category (if present) are checked for existence,
+ and if the outcome is positive, the mail is appended to the Audit-Trail
+ field of the PR. Note that the PR need not belong to the category because
+ PRs may move between categories.
+ 
+ Outgoing emails sent by GNATS itself may be configured to have a Subject
+ header field that refers to the PR in question:
+ 
+ @smallexample
+ Subject: Re: PR @var{category}/@var{gnats-id}: @var{original message subject}
+ @end smallexample
+ 
+ This makes it extremely easy to follow up on a PR by replying to such an
+ email, see @ref{dbconfig file,,The @code{dbconfig} file} and the sample,
+ default @code{dbconfig} file installed by @code{mkdb}.
  
  @c ---------------------------------------------------------------
  @node query-pr