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 |
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: |
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. |
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 |
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 |
|
|
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 |