Changes to gnats/doc/s-usage.texi

[Yngve Svendsen]

Index: gnats/doc/s-usage.texi
diff -c gnats/doc/s-usage.texi:1.3 gnats/doc/s-usage.texi:1.4
*** gnats/doc/s-usage.texi:1.3  Mon May 20 08:23:43 2002
--- gnats/doc/s-usage.texi      Tue Oct 22 18:46:17 2002
***************
*** 6,12 ****
  @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}}.
  
  @menu
  * using send-pr::             Creating new Problem Reports
--- 6,13 ----
  @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}.)
  
  @menu
  * using send-pr::             Creating new Problem Reports
***************
*** 16,28 ****
  * 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:
--- 17,126 ----
  * Helpful hints::
  @end menu
  
+ @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
+ 
+ @smallexample
+ send-pr [ -b | --batch ]
+         [ -c @var{address} [ , @var{address} ... ]
+           | -cc @var{address} [ , @var{address} ... ] ]
+         [ -d @var{database} | --database @var{database} ]
+         [ -f @var{file} | --file @var{file} ]
+         [ -p | --print ] [ --request-id ]
+         [ -s @var{severity} | --severity @var{severity} ]
+         [ -V | --version ] [ -h | --help ]
+ @end smallexample
+ 
+ Invoking @code{send-pr} with no options assumes that you want to
+ submit to the local @sc{gnats} database named @var{default} and calls
+ the editor named in your environment variable @code{EDITOR} on a PR
+ template for this database.
+ 
+ @table @code
+ @item -b
+ @itemx --batch
+ Suppresses printing of most of the messages @code{send-pr} usually
+ prints while running.
+ 
+ @item -c @var{mail-address} [ , @var{mail-address} ... ]
+ @itemx --cc @var{mail-address} [ , @var{mail-address} ... ]
+ Allows the user to specify one or more comma-separated
+ @var{mail-address}es to be placed in the @code{Cc:} header field of
+ the message to be sent.
+ 
+ @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
+ in @ref{Environment,,Environment variables and @sc{gnats} tools}.
+ 
+ @item -f @var{problem-report}
+ @itemx --file @var{problem-report}
+ Specifies a file, @var{problem-report}, where a completed Problem
+ Report or a PR template exists.  @code{send-pr} verifies that the
+ contents of the file constitute a valid PR and asks you if you want to
+ edit it or send it directly.  If the PR text is invalid you will be
+ told what is wrong and be given the option to edit it. If
+ @var{problem-report} is @samp{-}, @address@hidden reads from
+ standard input.
+ 
+ @item -p
+ @itemx --print
+ Displays the PR template for the specified database, or if the
+ @code{-d} or @code{--database} options aren't specified, print the
+ template for the local @var{default} database.  No PR is submitted.
+ 
+ @item --request-id
+ Sends a request for a @code{Submitter-Id} to the Support Site.
+ 
+ @item -s @var{severity}
+ @itemx --severity @var{severity}
+ @cindex @code{send-pr} fields
+ Sets the initial value of the @code{Severity} field to @var{severity}.
+ 
+ @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
+ 
+ @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 @address@hidden address@hidden typing
+ @address@hidden send-pr}} doesn't work, see your system administrator for
+ help loading @file{gnats.el} into Emacs.}  @code{send-pr} responds
+ with a preconfigured Problem Report template.  The Emacs interface is
+ described in more detail in a separate section, @xref{Emacs,,The Emacs
+ 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:
***************
*** 31,37 ****
  @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.
--- 129,135 ----
  @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.
***************
*** 40,54 ****
  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
--- 138,158 ----
  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
***************
*** 57,87 ****
  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} 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}.
! @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}.  @xref{send-pr from the shell}.
! 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 @address@hidden -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:
  
--- 161,187 ----
  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:
  
***************
*** 223,348 ****
  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 @address@hidden address@hidden typing
- @address@hidden send-pr}} doesn't work, see your system administrator for
- help loading @file{gnats.el} into Emacs.}  @code{send-pr} responds with a
- Problem Report template preconfigured for the Support Site to which
- you are going to send the report.
- 
- 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.  The Emacs interface to @sc{gnats} is described in a separate
- section, @xref{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{-},
- @address@hidden 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 -c @var{mail-address}
- @itemx --cc @var{mail-address}
- Places @var{mail-address} in the @code{Cc:} header field of the message
- to be sent.
- 
- @item --request-id
- Sends a request for a @code{>Submitter-Id:} to the Support Site.
- 
- @cindex listing valid categories
- @item -L
- @itemx --list
- Prints the list of valid @code{>Category:} values on standard output.
- No mail is sent.
- 
- @item -s @var{severity}
- @itemx --severity @var{severity}
- @cindex @code{send-pr} fields
- Sets the initial value of the @code{>Severity:} field to @var{severity}.
- 
- @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
  
  @c -------------------------------------------------------------------------
  @node Submitting via e-mail
--- 323,328 ----