Changes to gnats/doc/s-usage.texi

[Yngve Svendsen]

Index: gnats/doc/s-usage.texi
diff -c gnats/doc/s-usage.texi:1.4 gnats/doc/s-usage.texi:1.5
*** gnats/doc/s-usage.texi:1.4  Tue Oct 22 18:46:17 2002
--- gnats/doc/s-usage.texi      Thu Oct 24 07:38:25 2002
***************
*** 1,10 ****
- @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 @address@hidden send-pr}} (@pxref{Emacs
  submitting,,Submitting Problem Reports from Emacs}.)
--- 1,3 ----
***************
*** 53,59 ****
  
  @item -d @var{database}, --database @var{database}
  Specifies the database to which the PR is to be submitted; if no
! database is specified, the local database named @samp{default} is
  assumed.  This option overrides the database specified in the
  @code{GNATSDB} environment variable.  @var{database} can also be set
  to a remote database by using the format for @code{GNATSDB} described
--- 46,52 ----
  
  @item -d @var{database}, --database @var{database}
  Specifies the database to which the PR is to be submitted; if no
! database is specified, the local database named @code{default} is
  assumed.  This option overrides the database specified in the
  @code{GNATSDB} environment variable.  @var{database} can also be set
  to a remote database by using the format for @code{GNATSDB} described
***************
*** 114,189 ****
  interface to @sc{gnats}}.
  
  @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 with default values for the database you are
  submitting to.  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} can be
- set up to submit PRs by e-mail or by speaking directly to the
- @sc{gnats} server, but since this header is part of the standard
- format of Problem Reports, @code{send-pr} includes it even when it is
- set up to speak directly to the server.
- 
- @code{send-pr} completes all the mail header fields except the
- @samp{Subject} line with default values.  (@xref{Fields,,Problem
- Report format}.)
- 
  @item @sc{gnats} fields
! These are the fields that form the bulk of a @sc{gnats} Problem
! Report.  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}
! (@pxref{send-pr.conf file,,The send-pr.conf configuration file}.)
! @code{send-pr} attempts to determine values for the @samp{Originator}
! and @samp{Organization} fields (@pxref{Fields,,Problem Report
! format}).  @code{send-pr} will set the @samp{Originator} field to the
! value of the @code{NAME} environment variable if it has been set;
! similarly, @samp{Organization} will be set to the value of
! @code{ORGANIZATION}.  If these variables aren't set in you
! environment, @code{send-pr} uses the values set in the local
! @file{send-pr.conf} configuration file, if that exists.  If not, these
! values are left blank in the template.  @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.
  
! @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.
! 
! 
! @c Version 4 OK up till here.
! 
! The template begins with a comment section:
  
  @cindex template comment section
  @cindex comment section in the PR template
--- 107,133 ----
  interface to @sc{gnats}}.
  
  @node using send-pr
! @section The Problem Report template
  
  Invoking @code{send-pr} presents a PR @dfn{template} with a number of
  fields already filled in with default values for the database you are
  submitting to.  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:
  
! @itemize @bullet
  @item Comments
  @item Mail Header
  @item @sc{gnats} fields
! @end itemize
  
! The @strong{Comments section} at the top of the template contains basic
! instructions for completing the Problem Report, as well as a list of
! valid entries for the @code{Category} field.  One (and only one) of
! these values should be placed in the @code{Category} field further down
! in the Problem Report.
  
  @cindex template comment section
  @cindex comment section in the PR template
***************
*** 202,212 ****
  @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
--- 146,151 ----
***************
*** 214,228 ****
  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}
--- 153,176 ----
  Categories}, for a sample list of categories, .
  @end ifset
  
! The comments lines 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.)
! 
! The @strong{Mail Header} section of the template contains a standard
! mail header constructed by @code{send-pr}.  @code{send-pr} can be set up
! to submit PRs by e-mail or by speaking directly to the @sc{gnats}
! server, but since this header is part of the standard format of Problem
! Reports, @code{send-pr} includes it even when it is set up to speak
! directly to the server.
  
  @cindex mail header section
  @smallexample
  @group
! To: @var{PR submission address}
  Subject: @emph{complete this field}
  From: @var{your-login}@@@var{your-site}
  Reply-To: @var{your-login}@@@var{your-site}
***************
*** 231,256 ****
  @end smallexample
  
  @noindent
! where @var{support-site} is an alias on your local machine 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:  
--- 179,218 ----
  @end smallexample
  
  @noindent
! @code{send-pr} automatically completes all the mail header fields except
! the @code{Subject} line with default values.  (@xref{Fields,,Problem
! Report format}.)
! 
! The @address@hidden fields} below the mail header form the bulk of a
! @sc{gnats} Problem Report.
  
! Each field is either automatically completed with valid information
! (such as your @code{Submitter-Id}) or contains a one-line instruction
! specifying the information that field requires in order to be correct.
! For example, the @code{Confidential} field expects a value of @samp{yes}
! or @samp{no}, and the answer must fit on one line; similarly, the
! @code{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.
  
+ The mechanisms @code{send-pr} uses to fill in default values is as
+ follows: Your preconfigured @code{Submitter-Id} is taken from the local
+ @file{send-pr.conf} configuration file.  {send-pr} will set the
+ @code{Originator} field to the value of the @code{NAME} environment
+ variable if it has been set; similarly, @code{Organization} will be set
+ to the value of @code{ORGANIZATION}.  If these variables aren't set in
+ you environment, @code{send-pr} uses the values set in the local
+ @file{send-pr.conf} configuration file, if that exists.  If not, these
+ values are left blank in the template.  @code{send-pr} also attempts to
+ find out some information about your system and architecture, and places
+ this information in the @code{Environment} field if it finds any.
+ 
  In this example, words in @emph{italics} are filled in with
  pre-configured information:
  
  @cindex @code{send-pr} fields
  @smallexample
  >Submitter-Id: @emph{your submitter-id}
  >Originator:   @emph{your name here}
  >Organization:  
***************
*** 272,310 ****
  >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
! @address@hidden --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/address@hidden 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
! @address@hidden; you can edit this file and then submit it
! with @kbd{C-c C-c}.
  
  @cindex subsequent mail
  @cindex other mail
--- 234,260 ----
  >Fix:
         <how to correct or work around the problem, if known 
          (multiple lines)>
  @end smallexample
  
  @cindex @code{Submitter-Id} field
  @cindex @code{>Submitter-Id}
! When you finish editing the Problem Report, @code{send-pr} validates the
! contents and if it looks OK either submits it directly to the
! @sc{gnats} server or submits it by mail to the address named in the
! @code{To} field in the mail header.
  
  @cindex bad Problem Reports
  @cindex errors
  @cindex invalid Problem Reports
! If your PR contains one or more invalid field values, {send-pr} places
! the PR in a temporary file named @file{/tmp/address@hidden 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
! @address@hidden; you can edit this file and then submit it with
! @kbd{C-c C-c}.
  
  @cindex subsequent mail
  @cindex other mail
***************
*** 313,358 ****
  @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 Submitting via e-mail
  @section Submitting a Problem Report via direct e-mail
  @cindex Direct e-mail
  @cindex Submitting a PR via e-mail
! In addition to using @code{send-pr}, there is another way to submit a problem
! report.  You can simply send an e-mail message to the support site.
  
! To do this, look at the address in the @samp{To:} field of the @code{send-pr}
! template.  When you send unformatted e-mail to this address, @sc{gnats}
! processes the message as a new problem report, filling in as many fields from 
  defaults as it can:
  
  @table @code
  @item Synopsis
! The @samp{>Synopsis} field is filled in by the @samp{Subject:} header.
  
  @item Submitter ID
! @sc{gnats} will try to derive the @samp{>Submitter} field from the address
! in the @samp{From:} header.
  
  @item Description
  All of the text in the body of the e-mail message is put into the 
! @samp{>Description} field.  Each line of the text is indented by one space,
! indicating that it is "quoted text" from the sender.
  @end table
  
! Other fields, such as category, version, severity, etc. are set to default
! values (if the @sc{gnats} administrator has set them).
  
  @c --------------------------------------------------------------------------
  @node Helpful hints
--- 263,309 ----
  @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 @code{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 @code{Subject} lines of this form are
! automatically appended to the Problem Report in the @code{Audit-Trail}
! field in the order they are received.
  
  @c -------------------------------------------------------------------------
  @node Submitting via e-mail
  @section Submitting a Problem Report via direct e-mail
  @cindex Direct e-mail
  @cindex Submitting a PR via e-mail
! In addition to using @code{send-pr}, there is another way to submit a
! problem report.  You can simply send an e-mail message to the PR
! submission e-mail address of the support site (This address should be
! published by the support site.)
  
! When you send unformatted e-mail to this address, @sc{gnats} processes
! the message as a new problem report, filling in as many fields from
  defaults as it can:
  
  @table @code
  @item Synopsis
! The @code{Synopsis} field is filled in by the @code{Subject} header of
! the e-mail message.
  
  @item Submitter ID
! @sc{gnats} will try to derive the @code{Submitter} field from the address
! in the @code{From} header of the e-mail.
  
  @item Description
  All of the text in the body of the e-mail message is put into the 
! @code{Description} field.
  @end table
  
! Other fields, such as @code{Category}, @code{Version}, @code{Severity},
! etc. are set to default values as defined by the @sc{gnats} administrator.
  
  @c --------------------------------------------------------------------------
  @node Helpful hints