/[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.4 by yngves, Tue Oct 22 22:46:17 2002 UTC revision 1.5 by yngves, Thu Oct 24 11:38:25 2002 UTC
# Line 1  Line 1 
 @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...  
   
1  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
2  @sc{gnu} Emacs using @w{@samp{M-x send-pr}} (@pxref{Emacs  @sc{gnu} Emacs using @w{@samp{M-x send-pr}} (@pxref{Emacs
3  submitting,,Submitting Problem Reports from Emacs}.)  submitting,,Submitting Problem Reports from Emacs}.)
# Line 53  the message to be sent. Line 46  the message to be sent.
46    
47  @item -d @var{database}, --database @var{database}  @item -d @var{database}, --database @var{database}
48  Specifies the database to which the PR is to be submitted; if no  Specifies the database to which the PR is to be submitted; if no
49  database is specified, the local database named @samp{default} is  database is specified, the local database named @code{default} is
50  assumed.  This option overrides the database specified in the  assumed.  This option overrides the database specified in the
51  @code{GNATSDB} environment variable.  @var{database} can also be set  @code{GNATSDB} environment variable.  @var{database} can also be set
52  to a remote database by using the format for @code{GNATSDB} described  to a remote database by using the format for @code{GNATSDB} described
# Line 114  described in more detail in a separate s Line 107  described in more detail in a separate s
107  interface to @sc{gnats}}.  interface to @sc{gnats}}.
108    
109  @node using send-pr  @node using send-pr
110  @section Creating new Problem Reports  @section The Problem Report template
111    
 @c FIXME - this is a long node  
112  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
113  fields already filled in with default values for the database you are  fields already filled in with default values for the database you are
114  submitting to.  Complete the template as thoroughly as possible to  submitting to.  Complete the template as thoroughly as possible to
115  make a useful bug report.  Submit only one bug with each PR.  make a useful bug report.  Submit only one bug with each PR.
116    
117  @cindex template  @cindex{template}
118  A template consists of three sections:  A template consists of three sections:
119    
120  @table @dfn  @itemize @bullet
121  @item Comments  @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.)  
   
122  @item Mail Header  @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}.)  
   
123  @item @sc{gnats} fields  @item @sc{gnats} fields
124  These are the fields that form the bulk of a @sc{gnats} Problem  @end itemize
 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.  
125    
126  @code{send-pr} also provides the mail header section of the template  The @strong{Comments section} at the top of the template contains basic
127  with default values in the @samp{To}, @samp{From}, and @samp{Reply-To}  instructions for completing the Problem Report, as well as a list of
128  fields.  The @samp{Subject} field is empty.  valid entries for the @code{Category} field.  One (and only one) of
129    these values should be placed in the @code{Category} field further down
130    in the Problem Report.
 @c Version 4 OK up till here.  
   
 The template begins with a comment section:  
131    
132  @cindex template comment section  @cindex template comment section
133  @cindex comment section in the PR template  @cindex comment section in the PR template
# Line 202  SEND-PR: Choose from the following categ Line 146  SEND-PR: Choose from the following categ
146  @end group  @end group
147  @end smallexample  @end smallexample
148    
 @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.  
149  @ifset SENDPR  @ifset SENDPR
150  A complete sample bug report, from template to completed PR, is shown in  A complete sample bug report, from template to completed PR, is shown in
151  @ref{An Example}.  For a complete list of valid categories, type  @ref{An Example}.  For a complete list of valid categories, type
# Line 214  A complete sample bug report, from templ Line 153  A complete sample bug report, from templ
153  Categories}, for a sample list of categories, .  Categories}, for a sample list of categories, .
154  @end ifset  @end ifset
155    
156  @c FIXME.. this sounds awkward  The comments lines are all preceded by the string @samp{SEND-PR:} and
157  The mail header is just below the comment section.  Fill out the  are erased automatically when the PR is submitted.  The instructional
158  @samp{Subject:} field, if it is not already completed using the value of  comments within @samp{<} and @samp{>} are also removed.  (Only these
159  @samp{>Synopsis:}.  The other mail header fields contain default values.  comments are removed; lines you provide that happen to have those
160    characters in them, such as examples of shell-level redirection, are not
161    affected.)
162    
163    The @strong{Mail Header} section of the template contains a standard
164    mail header constructed by @code{send-pr}.  @code{send-pr} can be set up
165    to submit PRs by e-mail or by speaking directly to the @sc{gnats}
166    server, but since this header is part of the standard format of Problem
167    Reports, @code{send-pr} includes it even when it is set up to speak
168    directly to the server.
169    
170  @cindex mail header section  @cindex mail header section
171  @smallexample  @smallexample
172  @group  @group
173  To: @var{support-site}  To: @var{PR submission address}
174  Subject: @emph{complete this field}  Subject: @emph{complete this field}
175  From: @var{your-login}@@@var{your-site}  From: @var{your-login}@@@var{your-site}
176  Reply-To: @var{your-login}@@@var{your-site}  Reply-To: @var{your-login}@@@var{your-site}
# Line 231  X-send-pr-version: send-pr @value{VERSIO Line 179  X-send-pr-version: send-pr @value{VERSIO
179  @end smallexample  @end smallexample
180    
181  @noindent  @noindent
182  where @var{support-site} is an alias on your local machine for the  @code{send-pr} automatically completes all the mail header fields except
183  Support Site you wish to submit this PR to.  the @code{Subject} line with default values.  (@xref{Fields,,Problem
184    Report format}.)
185    
186    The @strong{@sc{gnats} fields} below the mail header form the bulk of a
187    @sc{gnats} Problem Report.
188    
189  The rest of the template contains @sc{gnats} fields.  Each field is  Each field is either automatically completed with valid information
190  either automatically completed with valid information (such as your  (such as your @code{Submitter-Id}) or contains a one-line instruction
191  @samp{>Submitter-Id:}) or contains a one-line instruction specifying the  specifying the information that field requires in order to be correct.
192  information that field requires in order to be correct.  For example,  For example, the @code{Confidential} field expects a value of @samp{yes}
193  the @samp{>Confidential:} field expects a value of @samp{yes} or  or @samp{no}, and the answer must fit on one line; similarly, the
194  @samp{no}, and the answer must fit on one line; similarly, the  @code{Synopsis} field expects a short synopsis of the problem, which
 @samp{>Synopsis:} field expects a short synopsis of the problem, which  
195  must also fit on one line.  Fill out the fields as completely as  must also fit on one line.  Fill out the fields as completely as
196  possible.  @xref{Helpful hints,,Helpful hints}, for suggestions as to  possible.  @xref{Helpful hints,,Helpful hints}, for suggestions as to
197  what kinds of information to include.  what kinds of information to include.
198    
199    The mechanisms @code{send-pr} uses to fill in default values is as
200    follows: Your preconfigured @code{Submitter-Id} is taken from the local
201    @file{send-pr.conf} configuration file.  {send-pr} will set the
202    @code{Originator} field to the value of the @code{NAME} environment
203    variable if it has been set; similarly, @code{Organization} will be set
204    to the value of @code{ORGANIZATION}.  If these variables aren't set in
205    you environment, @code{send-pr} uses the values set in the local
206    @file{send-pr.conf} configuration file, if that exists.  If not, these
207    values are left blank in the template.  @code{send-pr} also attempts to
208    find out some information about your system and architecture, and places
209    this information in the @code{Environment} field if it finds any.
210    
211  In this example, words in @emph{italics} are filled in with  In this example, words in @emph{italics} are filled in with
212  pre-configured information:  pre-configured information:
213    
214  @cindex @code{send-pr} fields  @cindex @code{send-pr} fields
215  @smallexample  @smallexample
 @group  
216  >Submitter-Id: @emph{your submitter-id}  >Submitter-Id: @emph{your submitter-id}
217  >Originator:   @emph{your name here}  >Originator:   @emph{your name here}
218  >Organization:    >Organization:  
# Line 272  pre-configured information: Line 234  pre-configured information:
234  >Fix:  >Fix:
235         <how to correct or work around the problem, if known         <how to correct or work around the problem, if known
236          (multiple lines)>          (multiple lines)>
 @end group  
237  @end smallexample  @end smallexample
238    
239  @cindex @code{Submitter-Id} field  @cindex @code{Submitter-Id} field
240  @cindex @code{>Submitter-Id}  @cindex @code{>Submitter-Id}
241  When you finish editing the Problem Report, @code{send-pr} mails it to  When you finish editing the Problem Report, @code{send-pr} validates the
242  the address named in the @samp{To:} field in the mail header.  contents and if it looks OK either submits it directly to the
243  @code{send-pr} checks that the complete form contains a valid  @sc{gnats} server or submits it by mail to the address named in the
244  @samp{>Category:}.  @code{To} field in the mail header.
   
 @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  
245    
246  @cindex bad Problem Reports  @cindex bad Problem Reports
247  @cindex errors  @cindex errors
248  @cindex invalid Problem Reports  @cindex invalid Problem Reports
249  If your PR has an invalid value in one of the @sc{Enumerated} fields  If your PR contains one or more invalid field values, {send-pr} places
250  (@pxref{Fields,,Problem Report format}), @code{send-pr} places the PR in  the PR in a temporary file named @file{/tmp/pbad@var{nnnn}} on your
251  a temporary file named @samp{/tmp/pbad@var{nnnn}} on your machine.  machine.  @var{nnnn} is the process identification number given to your
252  @var{nnnn} is the process identification number given to your current  current @code{send-pr} session.  If you are running @code{send-pr} from
253  @code{send-pr} session.  If you are running @code{send-pr} from the  the shell, you are prompted as to whether or not you wish to try editing
254  shell, you are prompted as to whether or not you wish to try editing the  the same Problem Report again.  If you are running @code{send-pr} from
 same Problem Report again.  If you are running @code{send-pr} from  
255  Emacs, the Problem Report is placed in the buffer  Emacs, the Problem Report is placed in the buffer
256  @w{@samp{*gnats-send*}}; you can edit this file and then submit it  @w{@samp{*gnats-send*}}; you can edit this file and then submit it with
257  with @kbd{C-c C-c}.  @kbd{C-c C-c}.
258    
259  @cindex subsequent mail  @cindex subsequent mail
260  @cindex other mail  @cindex other mail
# Line 313  with @kbd{C-c C-c}. Line 263  with @kbd{C-c C-c}.
263  @cindex related mail  @cindex related mail
264  Any further mail concerning this Problem Report should be carbon-copied  Any further mail concerning this Problem Report should be carbon-copied
265  to the @sc{gnats} mailing address as well, with the category and  to the @sc{gnats} mailing address as well, with the category and
266  identification number in the @samp{Subject:} line of the message.  identification number in the @code{Subject} line of the message.
267    
268  @smallexample  @smallexample
269  Subject: Re: PR @var{category}/@var{gnats-id}: @var{original message subject}  Subject: Re: PR @var{category}/@var{gnats-id}: @var{original message subject}
270  @end smallexample  @end smallexample
271    
272  @noindent  @noindent
273  Messages which arrive with @samp{Subject:} lines of this form are  Messages which arrive with @code{Subject} lines of this form are
274  automatically appended to the Problem Report in the @samp{>Audit-Trail:}  automatically appended to the Problem Report in the @code{Audit-Trail}
275  field in the order received.  field in the order they are received.
276    
277  @c -------------------------------------------------------------------------  @c -------------------------------------------------------------------------
278  @node Submitting via e-mail  @node Submitting via e-mail
279  @section Submitting a Problem Report via direct e-mail  @section Submitting a Problem Report via direct e-mail
280  @cindex Direct e-mail  @cindex Direct e-mail
281  @cindex Submitting a PR via e-mail  @cindex Submitting a PR via e-mail
282  In addition to using @code{send-pr}, there is another way to submit a problem  In addition to using @code{send-pr}, there is another way to submit a
283  report.  You can simply send an e-mail message to the support site.  problem report.  You can simply send an e-mail message to the PR
284    submission e-mail address of the support site (This address should be
285    published by the support site.)
286    
287  To do this, look at the address in the @samp{To:} field of the @code{send-pr}  When you send unformatted e-mail to this address, @sc{gnats} processes
288  template.  When you send unformatted e-mail to this address, @sc{gnats}  the message as a new problem report, filling in as many fields from
 processes the message as a new problem report, filling in as many fields from  
289  defaults as it can:  defaults as it can:
290    
291  @table @code  @table @code
292  @item Synopsis  @item Synopsis
293  The @samp{>Synopsis} field is filled in by the @samp{Subject:} header.  The @code{Synopsis} field is filled in by the @code{Subject} header of
294    the e-mail message.
295    
296  @item Submitter ID  @item Submitter ID
297  @sc{gnats} will try to derive the @samp{>Submitter} field from the address  @sc{gnats} will try to derive the @code{Submitter} field from the address
298  in the @samp{From:} header.  in the @code{From} header of the e-mail.
299    
300  @item Description  @item Description
301  All of the text in the body of the e-mail message is put into the  All of the text in the body of the e-mail message is put into the
302  @samp{>Description} field.  Each line of the text is indented by one space,  @code{Description} field.
 indicating that it is "quoted text" from the sender.  
303  @end table  @end table
304    
305  Other fields, such as category, version, severity, etc. are set to default  Other fields, such as @code{Category}, @code{Version}, @code{Severity},
306  values (if the @sc{gnats} administrator has set them).  etc. are set to default values as defined by the @sc{gnats} administrator.
307    
308  @c --------------------------------------------------------------------------  @c --------------------------------------------------------------------------
309  @node Helpful hints  @node Helpful hints

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

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