/[gnats]/gnats/doc/s-usage.texi
ViewVC logotype

Diff of /gnats/doc/s-usage.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.3 by pdm, Mon May 20 12:23:43 2002 UTC revision 1.4 by yngves, Tue Oct 22 22:46:17 2002 UTC
# Line 6  Line 6 
6  @c FIXME!  This still seems jumbled...  @c FIXME!  This still seems jumbled...
7    
8  You can invoke @code{send-pr} from a shell prompt, or from within  You can invoke @code{send-pr} from a shell prompt, or from within
9  @sc{gnu} Emacs using @w{@samp{M-x send-pr}}.  @sc{gnu} Emacs using @w{@samp{M-x send-pr}} (@pxref{Emacs
10    submitting,,Submitting Problem Reports from Emacs}.)
11    
12  @menu  @menu
13  * using send-pr::             Creating new Problem Reports  * using send-pr::             Creating new Problem Reports
# Line 16  You can invoke @code{send-pr} from a she Line 17  You can invoke @code{send-pr} from a she
17  * Helpful hints::  * Helpful hints::
18  @end menu  @end menu
19    
20    @node send-pr from the shell
21    @section Invoking @code{send-pr} from the shell
22    @cindex command line options
23    @cindex invoking @code{send-pr} from the shell
24    @cindex shell invocation
25    
26    @smallexample
27    send-pr [ -b | --batch ]
28            [ -c @var{address} [ , @var{address} ... ]
29              | -cc @var{address} [ , @var{address} ... ] ]
30            [ -d @var{database} | --database @var{database} ]
31            [ -f @var{file} | --file @var{file} ]
32            [ -p | --print ] [ --request-id ]
33            [ -s @var{severity} | --severity @var{severity} ]
34            [ -V | --version ] [ -h | --help ]
35    @end smallexample
36    
37    Invoking @code{send-pr} with no options assumes that you want to
38    submit to the local @sc{gnats} database named @var{default} and calls
39    the editor named in your environment variable @code{EDITOR} on a PR
40    template for this database.
41    
42    @table @code
43    @item -b
44    @itemx --batch
45    Suppresses printing of most of the messages @code{send-pr} usually
46    prints while running.
47    
48    @item -c @var{mail-address} [ , @var{mail-address} ... ]
49    @itemx --cc @var{mail-address} [ , @var{mail-address} ... ]
50    Allows the user to specify one or more comma-separated
51    @var{mail-address}es to be placed in the @code{Cc:} header field of
52    the message to be sent.
53    
54    @item -d @var{database}, --database @var{database}
55    Specifies the database to which the PR is to be submitted; if no
56    database is specified, the local database named @samp{default} is
57    assumed.  This option overrides the database specified in the
58    @code{GNATSDB} environment variable.  @var{database} can also be set
59    to a remote database by using the format for @code{GNATSDB} described
60    in @ref{Environment,,Environment variables and @sc{gnats} tools}.
61    
62    @item -f @var{problem-report}
63    @itemx --file @var{problem-report}
64    Specifies a file, @var{problem-report}, where a completed Problem
65    Report or a PR template exists.  @code{send-pr} verifies that the
66    contents of the file constitute a valid PR and asks you if you want to
67    edit it or send it directly.  If the PR text is invalid you will be
68    told what is wrong and be given the option to edit it. If
69    @var{problem-report} is @samp{-}, @w{@code{send-pr}} reads from
70    standard input.
71    
72    @item -p
73    @itemx --print
74    Displays the PR template for the specified database, or if the
75    @code{-d} or @code{--database} options aren't specified, print the
76    template for the local @var{default} database.  No PR is submitted.
77    
78    @item --request-id
79    Sends a request for a @code{Submitter-Id} to the Support Site.
80    
81    @item -s @var{severity}
82    @itemx --severity @var{severity}
83    @cindex @code{send-pr} fields
84    Sets the initial value of the @code{Severity} field to @var{severity}.
85    
86    @item -V
87    @itemx --version
88    Displays the @code{send-pr} version number and a usage summary.  No mail
89    is sent.
90    
91    @item -h
92    @itemx --help
93    Displays a usage summary for @code{send-pr}.  No mail is sent.
94    @end table
95    
96    @c ---------------------------------------------------------------
97    @node send-pr in Emacs
98    @section Using @code{send-pr} from within Emacs
99    @cindex using @code{send-pr} from within Emacs
100    @cindex @code{send-pr} within Emacs
101    @cindex invoking @code{send-pr} from Emacs
102    @cindex interactive interface
103    
104    You can use an interactive @code{send-pr} interface from within @sc{gnu}
105    Emacs to fill out your Problem Report.  We recommend that you
106    familiarize yourself with Emacs before using this feature
107    (@pxref{Introduction,,Introduction,emacs,GNU Emacs}).
108    
109    Call @code{send-pr} with @w{@samp{M-x send-pr}}.@footnote{If typing
110    @w{@samp{M-x send-pr}} doesn't work, see your system administrator for
111    help loading @file{gnats.el} into Emacs.}  @code{send-pr} responds
112    with a preconfigured Problem Report template.  The Emacs interface is
113    described in more detail in a separate section, @xref{Emacs,,The Emacs
114    interface to @sc{gnats}}.
115    
116  @node using send-pr  @node using send-pr
117  @section Creating new Problem Reports  @section Creating new Problem Reports
118    
119  @c FIXME - this is a long node  @c FIXME - this is a long node
120  Invoking @code{send-pr} presents a PR @dfn{template} with a number of  Invoking @code{send-pr} presents a PR @dfn{template} with a number of
121  fields already filled in.  Complete the template as thoroughly as  fields already filled in with default values for the database you are
122  possible to make a useful bug report.  Submit only one bug with each PR.  submitting to.  Complete the template as thoroughly as possible to
123    make a useful bug report.  Submit only one bug with each PR.
124    
125  @cindex template  @cindex template
126  A template consists of three sections:  A template consists of three sections:
# Line 31  A template consists of three sections: Line 129  A template consists of three sections:
129  @item Comments  @item Comments
130  The top several lines of a blank template consist of a series of  The top several lines of a blank template consist of a series of
131  comments that provide some basic instructions for completing the Problem  comments that provide some basic instructions for completing the Problem
132  Report, as well as a list of valid entries for the @samp{>Category:}  Report, as well as a list of valid entries for the @samp{Category:}
133  field.  These comments are all preceded by the string @samp{SEND-PR:}  field.  These comments are all preceded by the string @samp{SEND-PR:}
134  and are erased automatically when the PR is submitted.  The  and are erased automatically when the PR is submitted.  The
135  instructional comments within @samp{<} and @samp{>} are also removed.  instructional comments within @samp{<} and @samp{>} are also removed.
# Line 40  those characters in them, such as exampl Line 138  those characters in them, such as exampl
138  are not affected.)  are not affected.)
139    
140  @item Mail Header  @item Mail Header
141  @code{send-pr} creates a standard mail header.  @code{send-pr} completes  @code{send-pr} creates a standard mail header.  @code{send-pr} can be
142  all fields except the @samp{Subject:} line with default values.  set up to submit PRs by e-mail or by speaking directly to the
143  (@xref{Fields,,Problem Report format}.)  @sc{gnats} server, but since this header is part of the standard
144    format of Problem Reports, @code{send-pr} includes it even when it is
145    set up to speak directly to the server.
146    
147    @code{send-pr} completes all the mail header fields except the
148    @samp{Subject} line with default values.  (@xref{Fields,,Problem
149    Report format}.)
150    
151  @item @sc{gnats} fields  @item @sc{gnats} fields
152  These are the informational fields that @sc{gnats} uses to route your  These are the fields that form the bulk of a @sc{gnats} Problem
153  Problem Report to the responsible party for further action.  They should  Report.  They should be filled out as completely as possible.
154  be filled out as completely as possible.  (@xref{Fields,,Problem Report  (@xref{Fields,,Problem Report format}.  Also see @ref{Helpful
155  format}.  Also see @ref{Helpful hints,,Helpful hints}.)  hints,,Helpful hints}.)
156  @end table  @end table
157    
158  @ifset SENDPR  @ifset SENDPR
# Line 57  For examples of a Problem Report templat Line 161  For examples of a Problem Report templat
161  see @ref{An Example}.  see @ref{An Example}.
162  @end ifset  @end ifset
163    
164  The default template contains your preconfigured @samp{>Submitter-Id:}.  The default template contains your preconfigured @samp{Submitter-Id}
165  @code{send-pr} attempts to determine values for the @samp{>Originator:}  (@pxref{send-pr.conf file,,The send-pr.conf configuration file}.)
166  and @samp{>Organization:} fields (@pxref{Fields,,Problem Report  @code{send-pr} attempts to determine values for the @samp{Originator}
167  format}).  @code{send-pr} will set the @samp{>Originator:} field to  and @samp{Organization} fields (@pxref{Fields,,Problem Report
168  the value of the @code{NAME} environment variable if it has been set;  format}).  @code{send-pr} will set the @samp{Originator} field to the
169  similarly, @samp{>Organization:} will be set to the value of @code{ORGANIZATION}.  value of the @code{NAME} environment variable if it has been set;
170  @code{send-pr} also attempts to find out some information  similarly, @samp{Organization} will be set to the value of
171  about your system and architecture, and places this information in the  @code{ORGANIZATION}.  If these variables aren't set in you
172  @samp{>Environment:} field if it finds any.  environment, @code{send-pr} uses the values set in the local
173    @file{send-pr.conf} configuration file, if that exists.  If not, these
174  You may submit problem reports to different Support Sites from the  values are left blank in the template.  @code{send-pr} also attempts
175  default site by specifying the alternate site when you invoke  to find out some information about your system and architecture, and
176  @code{send-pr}.  @xref{send-pr from the shell}.  places this information in the @samp{Environment} field if it finds
177  Each @code{site} has its own list of categories for  any.
 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  
178    
179  @code{send-pr} also provides the mail header section of the template  @code{send-pr} also provides the mail header section of the template
180  with default values in the @samp{To:}, @samp{From:}, and  with default values in the @samp{To}, @samp{From}, and @samp{Reply-To}
181  @samp{Reply-To:} fields.  The @samp{Subject:} field is empty.  fields.  The @samp{Subject} field is empty.
182    
183    
184    @c Version 4 OK up till here.
185    
186  The template begins with a comment section:  The template begins with a comment section:
187    
# Line 224  Messages which arrive with @samp{Subject Line 324  Messages which arrive with @samp{Subject
324  automatically appended to the Problem Report in the @samp{>Audit-Trail:}  automatically appended to the Problem Report in the @samp{>Audit-Trail:}
325  field in the order received.  field in the order received.
326    
 @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 @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{-},  
 @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 -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  
   
327  @c -------------------------------------------------------------------------  @c -------------------------------------------------------------------------
328  @node Submitting via e-mail  @node Submitting via e-mail
329  @section Submitting a Problem Report via direct e-mail  @section Submitting a Problem Report via direct e-mail

Legend:
Removed from v.1.3  
changed lines
  Added in v.1.4

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26