|
112
|
1 \input texinfo @c -*-texinfo-*-
|
|
|
2 @setfilename gnats.info
|
|
|
3
|
|
|
4 @include version.texi
|
|
|
5
|
|
|
6 @ifinfo
|
|
|
7 @format
|
|
|
8 START-INFO-DIR-ENTRY
|
|
|
9 * Keeping Track: (gnats). GNU Problem Report Management System
|
|
|
10 END-INFO-DIR-ENTRY
|
|
|
11 @end format
|
|
|
12 @end ifinfo
|
|
|
13
|
|
|
14 @ifinfo
|
|
|
15 Copyright @copyright{} 1993, 1995 Free Software Foundation, Inc.
|
|
|
16
|
|
|
17 Permission is granted to make and distribute verbatim copies of
|
|
|
18 this manual provided the copyright notice and this permission notice
|
|
|
19 are preserved on all copies.
|
|
|
20
|
|
|
21 @ignore
|
|
|
22 Permission is granted to process this file through TeX and print the
|
|
|
23 results, provided the printed document carries a copying permission
|
|
|
24 notice identical to this one except for the removal of this paragraph
|
|
|
25 (this paragraph not being relevant to the printed manual).
|
|
|
26 @end ignore
|
|
|
27
|
|
|
28 Permission is granted to copy and distribute modified versions of this
|
|
|
29 manual under the conditions for verbatim copying, provided also that
|
|
|
30 the entire resulting derived work is distributed under the terms of a
|
|
|
31 permission notice identical to this one.
|
|
|
32
|
|
|
33 Permission is granted to copy and distribute translations of this manual
|
|
|
34 into another language, under the above conditions for modified versions.
|
|
|
35 @end ifinfo
|
|
|
36
|
|
|
37 @c NOTE TO ANYONE FORMATTING THIS DOCUMENT FOR PRINTING...
|
|
|
38 @c Comment the following line out if you don't have access to a
|
|
|
39 @c PostScript printer or viewer
|
|
|
40
|
|
|
41 @set POSTSCRIPT
|
|
|
42
|
|
|
43 @settitle Keeping Track
|
|
|
44 @setchapternewpage odd
|
|
|
45 @finalout
|
|
|
46 @titlepage
|
|
|
47 @title Keeping Track
|
|
|
48 @subtitle Managing Messages With GNATS
|
|
|
49 @subtitle The @sc{gnu} Problem Report Management System
|
|
|
50 @subtitle Version @value{VERSION}
|
|
|
51 @subtitle January 1996
|
|
|
52 @author Jeffrey M. Osier
|
|
|
53 @author Brendan Kehoe
|
|
|
54 @author Cygnus Support
|
|
|
55 @page
|
|
|
56
|
|
|
57 @vskip 0pt plus 1filll
|
|
|
58 Copyright @copyright{} 1993, 1995 Free Software Foundation, Inc.
|
|
|
59
|
|
|
60 Permission is granted to make and distribute verbatim copies of
|
|
|
61 this manual provided the copyright notice and this permission notice
|
|
|
62 are preserved on all copies.
|
|
|
63
|
|
|
64 Permission is granted to copy and distribute modified versions of this
|
|
|
65 manual under the conditions for verbatim copying, provided also that
|
|
|
66 the entire resulting derived work is distributed under the terms of a
|
|
|
67 permission notice identical to this one.
|
|
|
68
|
|
|
69 Permission is granted to copy and distribute translations of this manual
|
|
|
70 into another language, under the above conditions for modified versions.
|
|
|
71
|
|
|
72 @end titlepage
|
|
|
73
|
|
|
74 @node Top
|
|
|
75 @top Overview
|
|
|
76 @cindex overview to GNATS
|
|
|
77 @cindex foreword
|
|
|
78
|
|
|
79 This manual documents @sc{gnats}, the @sc{gnu} Problem Report Management
|
|
|
80 System, version @value{VERSION}. @sc{gnats} is a bug-tracking tool
|
|
|
81 designed for use at a central @dfn{Support Site}. Users who experience
|
|
|
82 problems use electronic mail to communicate these problems to
|
|
|
83 @dfn{maintainers} at that Support Site. @sc{gnats} partially automates
|
|
|
84 the tracking of these @dfn{Problem Reports} (@dfn{PR}s) by:
|
|
|
85
|
|
|
86 @itemize @bullet
|
|
|
87 @item
|
|
|
88 organizing problem reports into a database and notifying responsible
|
|
|
89 parties of suspected bugs;
|
|
|
90
|
|
|
91 @item
|
|
|
92 allowing support personnel and their managers to edit and query
|
|
|
93 accumulated bugs; and
|
|
|
94
|
|
|
95 @item
|
|
|
96 providing a reliable archive of problems (and their subsequent
|
|
|
97 solutions) with a given program.
|
|
|
98 @end itemize
|
|
|
99
|
|
|
100 @sc{gnats} offers many of the same features offered by more generalized
|
|
|
101 databases, including editing, querying, and basic reporting. The
|
|
|
102 @sc{gnats} database itself is an ordered repository for problem reports;
|
|
|
103 each PR receives a unique, incremental @dfn{PR number} which identifies
|
|
|
104 it throughout its lifetime. For a discussion on the working system
|
|
|
105 adopted by @sc{gnats}, see @ref{Paradigm,,The database paradigm}.
|
|
|
106
|
|
|
107 You can access the submitting, editing, and querying functions of
|
|
|
108 @sc{gnats} from within @sc{gnu} Emacs. @xref{Invoking the
|
|
|
109 tools,,Invoking the @sc{gnats} tools}.
|
|
|
110
|
|
|
111 @menu
|
|
|
112 * Introduction:: Introducing GNATS
|
|
|
113 * Invoking the tools:: Invoking the GNATS tools
|
|
|
114 * Management:: GNATS Administration
|
|
|
115 * Installation:: Installing GNATS
|
|
|
116 * Locations:: Where @sc{gnats} lives
|
|
|
117 * Regexps:: Querying using regular expressions
|
|
|
118 * Index::
|
|
|
119 @end menu
|
|
|
120
|
|
|
121 @c ===============================================================
|
|
|
122 @node Introduction
|
|
|
123 @chapter Introducing @sc{gnats}
|
|
|
124 @cindex introduction to GNATS
|
|
|
125 @cindex rationale
|
|
|
126 @cindex database rationale
|
|
|
127
|
|
|
128 Any support organization realizes that a large amount of data flows back
|
|
|
129 and forth between the maintainers and the users of their products. This
|
|
|
130 data often takes the form of problem reports and communication via
|
|
|
131 electronic mail. @sc{gnats} addresses the problem of organizing this
|
|
|
132 communication by defining a database made up of archived and indexed
|
|
|
133 electronic mail messages.
|
|
|
134
|
|
|
135 @sc{gnats} was designed as a tool for software maintainers. It consists
|
|
|
136 of several utilities which, when used in concert, formulate and
|
|
|
137 administer a database of Problem Reports grouped by site-defined
|
|
|
138 @dfn{problem categories}. It allows a support organization to keep
|
|
|
139 track of problems (hence the term @dfn{Problem Report}) in an organized
|
|
|
140 fashion. Essentially, @sc{gnats} acts as an active archive for
|
|
|
141 field-separated textual data submitted through electronic mail.
|
|
|
142
|
|
|
143 @menu
|
|
|
144 * Paradigm:: The database paradigm
|
|
|
145 * Flowchart:: Flowchart of GNATS activities
|
|
|
146 * States:: States of Problem Reports
|
|
|
147 * Fields:: Problem Report format
|
|
|
148 @end menu
|
|
|
149
|
|
|
150 @node Paradigm
|
|
|
151 @section The database paradigm
|
|
|
152 @cindex paradigm
|
|
|
153 @cindex database paradigm
|
|
|
154 @cindex why GNATS
|
|
|
155 @cindex support site
|
|
|
156 @cindex maintenance
|
|
|
157 @cindex so what does it do
|
|
|
158
|
|
|
159 It is in your best interest as the maintainer of a body of work to
|
|
|
160 organize the feedback you receive on that work, and to make it easy for
|
|
|
161 users of your work to report problems and suggestions.
|
|
|
162
|
|
|
163 @sc{gnats} makes this easy by automatically filing incoming problem
|
|
|
164 reports into appropriate places, by notifying responsible parties of the
|
|
|
165 existence of the problem and (optionally) sending an acknowledgement to
|
|
|
166 the submitter that the report was received, and by making these Problem
|
|
|
167 Reports accessible to queries and easily editable. @sc{gnats} is a
|
|
|
168 database specialized for a specific task.
|
|
|
169
|
|
|
170 @sc{gnats} was designed for use at a Support Site that handles a high
|
|
|
171 level of problem-related traffic though electronic mail. It maintains
|
|
|
172 Problem Reports in the form of text files with defined @dfn{fields}
|
|
|
173 (@pxref{Fields,,@sc{gnats} data fields}). The location of the database,
|
|
|
174 as well as the categories it accepts as valid, the maintainers for whom
|
|
|
175 it provides service, and the submitters from whom it accepts Problem
|
|
|
176 Reports, are all definable by the @dfn{Support Site}.
|
|
|
177 @xref{Management,,@sc{gnats} administration}.
|
|
|
178
|
|
|
179 @cindex what is a PR
|
|
|
180 Each PR is a separate file within a main repository
|
|
|
181 (@pxref{Locations,,Where @sc{gnats} lives}). Editing access to the
|
|
|
182 database is regulated to maintain consistency, but anyone with
|
|
|
183 electronic mail access may submit Problem Reports. To make queries on
|
|
|
184 the database faster, an index is kept automatically (@pxref{index
|
|
|
185 file,,The @code{index} file}).
|
|
|
186
|
|
|
187 We provide several software tools so that users may submit new Problem
|
|
|
188 Reports, edit existing Problem Reports, and query the database.
|
|
|
189
|
|
|
190 @itemize @bullet
|
|
|
191 @item
|
|
|
192 @w{@code{send-pr}} is used by both product maintainers and the end users
|
|
|
193 of the products they support to submit PRs to the database.
|
|
|
194
|
|
|
195 @item
|
|
|
196 @w{@code{edit-pr}} is used by maintainers to use when editing problem
|
|
|
197 reports in the database.
|
|
|
198
|
|
|
199 @item
|
|
|
200 Maintainers, managers and administrators can use @w{@code{query-pr}} to
|
|
|
201 make inquiries about indidvidual PRs or groups of PRs.
|
|
|
202
|
|
|
203 @end itemize
|
|
|
204
|
|
|
205 @code{send-pr} can also be packaged by itself and distributed to anyone
|
|
|
206 you wish to receive Problem Reports from; see @ref{mkdist,,Configuring
|
|
|
207 @code{send-pr} for the outside world}.
|
|
|
208
|
|
|
209 @cindex GNATS administrator
|
|
|
210 At the Support Site, a @sc{gnats} @dfn{administrator} is charged with the
|
|
|
211 duty of maintaining @sc{gnats}. These duties are discussed in detail in
|
|
|
212 @ref{Management,,@sc{gnats} Administration}, and generally include
|
|
|
213 configuring @sc{gnats} for the Support Site, editing PRs that @sc{gnats}
|
|
|
214 cannot process, pruning log files, setting up new problem categories,
|
|
|
215 backing up the database, and distributing @code{send-pr} so that others
|
|
|
216 may submit Problem Reports.
|
|
|
217
|
|
|
218 Responsibility for a given Problem Report depends on the category of the
|
|
|
219 problem. Optionally, an automated reminder can be sent to the
|
|
|
220 responsible person if a problem report is neglected for a requisite time
|
|
|
221 period. @xref{Local configuration,,Changing your local configuration}.
|
|
|
222
|
|
|
223 @cindex @code{pending} directory
|
|
|
224 @cindex unparseable incoming PRs
|
|
|
225 @cindex incoming PRs that @sc{gnats} cannot parse
|
|
|
226 @sc{gnats} does not have the ability to decipher random text, so any
|
|
|
227 problem reports which arrive in a format @sc{gnats} does not recognize
|
|
|
228 are placed in a separate directory pending investigation by the
|
|
|
229 @sc{gnats} administrator (@pxref{Management,,@sc{gnats} Administration}).
|
|
|
230
|
|
|
231 Once a problem is recorded in the database, work can begin toward a
|
|
|
232 solution. A problem's initial @dfn{state} is @samp{open}
|
|
|
233 (@pxref{States,,States of Problem Reports}). An acknowledgement is sent
|
|
|
234 to the originator of the bug report (if that feature of @sc{gnats} is
|
|
|
235 activated). @sc{gnats} forwards copies of the report to the party
|
|
|
236 responsible for that problem category and to the person responsible for
|
|
|
237 problems arriving from that @dfn{Submitter Site}.
|
|
|
238 @c (@pxref{Glossary,,Glossary}).
|
|
|
239
|
|
|
240 When a problem has been identified, the maintainer can change its state
|
|
|
241 to @samp{analyzed}, and then to @samp{feedback} when a solution is
|
|
|
242 found. Each time the state of a PR changes, the submitter of the
|
|
|
243 problem report is notified of the reason for the change. If the party
|
|
|
244 responsible for the PR changes, the previous responsible party and the
|
|
|
245 new responsible party receive notice of the change. The change and
|
|
|
246 reason are also recorded in the @samp{>Audit-Trail:} field of the
|
|
|
247 Problem Report. (@xref{edit-pr,,Editing existing Problem Reports}. For
|
|
|
248 information on the @samp{>Audit-Trail:} field, see @ref{Fields,,Problem
|
|
|
249 Report format}.)
|
|
|
250
|
|
|
251 When the originator of the Problem Report confirms that the solution
|
|
|
252 works, the maintainer can change the state to @dfn{closed}. If the PR
|
|
|
253 cannot be closed, the maintainer can change its state to @dfn{suspended}
|
|
|
254 as a last resort. (For a more detailed description of these states, see
|
|
|
255 @ref{States,,States of Problem Reports}.)
|
|
|
256
|
|
|
257 @node Flowchart
|
|
|
258 @section Flowchart of @sc{gnats} activities
|
|
|
259 @cindex flowchart of GNATS activities
|
|
|
260 @cindex visual map of data flow
|
|
|
261
|
|
|
262 This informal flowchart shows the relationships of the @sc{gnats} tools
|
|
|
263 to each other and to the files with which they interoperate.
|
|
|
264
|
|
|
265 @sp 2
|
|
|
266
|
|
|
267 @ifset POSTSCRIPT
|
|
|
268 @tex
|
|
|
269 \input epsf
|
|
|
270 \epsffile{flowchart.eps}
|
|
|
271 @end tex
|
|
|
272 @end ifset
|
|
|
273
|
|
|
274 @ifinfo
|
|
|
275 @clear POSTSCRIPT
|
|
|
276 @end ifinfo
|
|
|
277
|
|
|
278 @ifclear POSTSCRIPT
|
|
|
279 @cartouche
|
|
|
280 @smallexample
|
|
|
281 @include flowchart.txt
|
|
|
282 @end smallexample
|
|
|
283 @end cartouche
|
|
|
284
|
|
|
285 @end ifclear
|
|
|
286
|
|
|
287 @sp 2
|
|
|
288
|
|
|
289 @c ---------------------------------------------------------------
|
|
|
290
|
|
|
291 @include states.texi
|
|
|
292
|
|
|
293 @c ---------------------------------------------------------------
|
|
|
294 @include fields.texi
|
|
|
295
|
|
|
296 @c ===============================================================
|
|
|
297
|
|
|
298 @include p-usage.texi
|
|
|
299
|
|
|
300 @c ===============================================================
|
|
|
301
|
|
|
302 @include p-admin.texi
|
|
|
303
|
|
|
304 @c ===============================================================
|
|
|
305
|
|
|
306 @node Installation
|
|
|
307 @appendix Installing @sc{gnats}
|
|
|
308
|
|
|
309 @include p-inst.texi
|
|
|
310
|
|
|
311 @c ===============================================================
|
|
|
312
|
|
|
313 @node Locations
|
|
|
314 @appendix Where @sc{gnats} lives
|
|
|
315 @cindex locations
|
|
|
316 @cindex where GNATS lives
|
|
|
317 @cindex default installation locations
|
|
|
318
|
|
|
319 We use a few conventions when referring to the installation structure
|
|
|
320 @sc{gnats} uses. These values are adjustable when you build and install
|
|
|
321 @sc{gnats} (@pxref{Installation,,Installing @sc{gnats}}).
|
|
|
322
|
|
|
323 @menu
|
|
|
324 * prefix::
|
|
|
325 * exec-prefix::
|
|
|
326 * GNATS_ROOT::
|
|
|
327 * defaults:: Default installation locations
|
|
|
328 @end menu
|
|
|
329
|
|
|
330 @node prefix
|
|
|
331 @section @var{prefix}
|
|
|
332 @cindex @var{prefix}
|
|
|
333
|
|
|
334 @var{prefix} corresponds to the variable @samp{prefix} for
|
|
|
335 @code{configure}, which passes it on to the @file{Makefile} it creates.
|
|
|
336 @var{prefix} sets the root installation directory for
|
|
|
337 @dfn{host-independent} files as follows:
|
|
|
338
|
|
|
339 @c FIXME - check these
|
|
|
340 @table @asis
|
|
|
341 @item libraries
|
|
|
342 @file{@var{prefix}/lib}@*
|
|
|
343
|
|
|
344 @item @code{man} pages
|
|
|
345 @file{@var{prefix}/man}
|
|
|
346
|
|
|
347 @item @code{info} documents
|
|
|
348 @file{@var{prefix}/info}
|
|
|
349
|
|
|
350 @item @code{include} files
|
|
|
351 @file{@var{prefix}/include}
|
|
|
352
|
|
|
353 @item @emph{etc@dots{}}
|
|
|
354 @end table
|
|
|
355
|
|
|
356 The default value for @var{prefix} is @w{@file{/usr/local}}, which can
|
|
|
357 be changed on the command line to @code{configure} using
|
|
|
358
|
|
|
359 @smallexample
|
|
|
360 configure --prefix=@var{prefix} @dots{}
|
|
|
361 @end smallexample
|
|
|
362
|
|
|
363 @noindent
|
|
|
364 @xref{Configure and make,,Configuring and compiling the software}.
|
|
|
365
|
|
|
366 @node exec-prefix
|
|
|
367 @section @var{exec-prefix}
|
|
|
368 @cindex @var{exec-prefix}
|
|
|
369
|
|
|
370 @var{exec-prefix} corresponds to the variable @samp{exec_prefix} for
|
|
|
371 @code{configure}, which passes it on to the @file{Makefile} it creates.
|
|
|
372 @w{@var{exec-prefix}} sets the root installation for
|
|
|
373 @dfn{host-dependent} files as follows:
|
|
|
374
|
|
|
375 @c FIXME - check these
|
|
|
376 @table @asis
|
|
|
377 @item binary tools
|
|
|
378 @file{@var{exec-prefix}/bin}
|
|
|
379
|
|
|
380 @item binary support utilities
|
|
|
381 @file{@var{exec-prefix}/lib/gnats}
|
|
|
382
|
|
|
383 @item compiled libraries
|
|
|
384 @file{@var{exec-prefix}/lib}@*
|
|
|
385
|
|
|
386 @item @emph{etc@dots{}}
|
|
|
387 @end table
|
|
|
388
|
|
|
389 Since most installations are not intended to be distributed around a
|
|
|
390 network, the default value for @w{@var{exec-prefix}} is the value of
|
|
|
391 @samp{prefix}, i.e., @w{@file{/usr/local}}. However, using
|
|
|
392 @var{exec-prefix} saves space when you are installing a package on
|
|
|
393 several different platforms for which many files are identical; rather
|
|
|
394 than duplicate them for each host, these files can be shared in a common
|
|
|
395 repository, and you can use symbolic links on each host to find the
|
|
|
396 host-dependent files. @emph{It is not necessary to use this paradigm
|
|
|
397 when building the @sc{gnats} tools}. @xref{Configure and
|
|
|
398 make,,Configuring and compiling the software}.
|
|
|
399
|
|
|
400 Use @var{exec-prefix} in conjunction with @var{prefix} to share
|
|
|
401 host-independent files, like libraries and @code{info} documents. For
|
|
|
402 example:
|
|
|
403
|
|
|
404 @smallexample
|
|
|
405 @emph{for each host:}
|
|
|
406 configure --prefix=/usr/gnu --exec-prefix=/usr/gnu/H-@var{host}
|
|
|
407 make all install @dots{}
|
|
|
408 @end smallexample
|
|
|
409
|
|
|
410 @noindent
|
|
|
411 Using this paradigm, all host-dependent binary files are installed into
|
|
|
412 @w{@file{/usr/gnu/H-@var{host}/bin}}, while files which do not depend on
|
|
|
413 the host type for which they were configured are installed into
|
|
|
414 @w{@file{/usr/gnu}}.
|
|
|
415
|
|
|
416 You can then use a different symbolic link for @w{@file{/usr/gnu}}
|
|
|
417 on each host (@file{/usr} is usually specific to a particular machine;
|
|
|
418 it is always specific to a particular architecture).
|
|
|
419
|
|
|
420 @smallexample
|
|
|
421 @emph{on host-1:}
|
|
|
422 ln -s /usr/gnu/H-@var{host-1} /usr/gnu
|
|
|
423 @emph{on host-2:}
|
|
|
424 ln -s /usr/gnu/H-@var{host-2} /usr/gnu
|
|
|
425 @end smallexample
|
|
|
426
|
|
|
427 @noindent
|
|
|
428 To the end user, then, placing @w{@file{/usr/gnu/bin}} in her or his
|
|
|
429 @code{PATH} simply works transparently for each @var{host} type.
|
|
|
430
|
|
|
431 You can change @w{@var{exec-prefix}} on the command line to
|
|
|
432 @code{configure} using
|
|
|
433
|
|
|
434 @smallexample
|
|
|
435 configure --exec-prefix=@var{exec-prefix} @dots{}
|
|
|
436 @end smallexample
|
|
|
437
|
|
|
438 We recommend that you consult @ref{Using configure,,Using
|
|
|
439 @code{configure},configure,Cygnus configure}, before attempting this.
|
|
|
440 Again, @emph{it is not necessary to use this paradigm when building the
|
|
|
441 @sc{gnats} tools}.
|
|
|
442
|
|
|
443 @node GNATS_ROOT
|
|
|
444 @section @var{GNATS_ROOT}
|
|
|
445 @cindex @var{GNATS_ROOT}
|
|
|
446
|
|
|
447 The location of the database and the administrative data files, by
|
|
|
448 default @w{@file{@var{prefix}/lib/gnats/gnats-db}}. You can change this
|
|
|
449 value on the command line to @code{configure} using
|
|
|
450
|
|
|
451 @smallexample
|
|
|
452 configure --with-gnats-root=@w{@var{GNATS_ROOT}}
|
|
|
453 @end smallexample
|
|
|
454
|
|
|
455 @noindent
|
|
|
456 Administrative data files reside in @w{@file{@var{GNATS_ROOT}/gnats-adm}}.
|
|
|
457 These include @file{categories}, @file{submitters}, @file{responsible},
|
|
|
458 and @file{config}, as well as two files generated and maintained by
|
|
|
459 @sc{gnats}, @file{index} and @file{current}. @xref{Local configuration,,
|
|
|
460 Changing your local configuration}, and @ref{Admin files,,Administrative
|
|
|
461 data files}.
|
|
|
462
|
|
|
463 @node defaults
|
|
|
464 @section Default installation locations
|
|
|
465 @cindex default installation locations
|
|
|
466
|
|
|
467 @table @asis
|
|
|
468 @item @var{prefix}
|
|
|
469 defaults to @file{/usr/local}; change using @code{configure}
|
|
|
470 (@pxref{Configure and make,,Configuring and compiling the software}).
|
|
|
471
|
|
|
472 @item @var{exec-prefix}
|
|
|
473 defaults to @var{prefix}; change using @code{configure}
|
|
|
474 (@pxref{Configure and make,,Configuring and compiling the software}).
|
|
|
475
|
|
|
476 @item @w{@var{GNATS_ROOT}}
|
|
|
477 defaults to @w{@file{@var{prefix}/lib/gnats/gnats-db}}; change using
|
|
|
478 @code{configure} (@pxref{Configure and make,,Configuring and compiling
|
|
|
479 the software}).
|
|
|
480 @end table
|
|
|
481
|
|
|
482 @noindent
|
|
|
483 @sc{gnats} installs tools, utilities, and files into the following
|
|
|
484 locations.
|
|
|
485
|
|
|
486 @table @code
|
|
|
487
|
|
|
488 @item @var{exec-prefix}/bin
|
|
|
489
|
|
|
490 @table @code
|
|
|
491 @item send-pr
|
|
|
492 @xref{send-pr,,Submitting Problem Reports}.
|
|
|
493 @item edit-pr
|
|
|
494 @xref{edit-pr,,Editing existing Problem Reports}.
|
|
|
495 @item query-pr
|
|
|
496 @xref{query-pr,,Querying the database}.
|
|
|
497 @item nquery-pr
|
|
|
498 @xref{query-pr,,Querying the database over the network}.
|
|
|
499 @end table
|
|
|
500
|
|
|
501 @item @var{exec-prefix}/lib/gnats
|
|
|
502
|
|
|
503 @table @code
|
|
|
504 @item mkcat
|
|
|
505 @xref{mkcat,,Adding a problem category}.
|
|
|
506 @item rmcat
|
|
|
507 @xref{rmcat,,Removing a problem category}.
|
|
|
508 @item mkdist
|
|
|
509 @xref{mkdist,,Configuring @code{send-pr} for the outside world}.
|
|
|
510 @item gen-index
|
|
|
511 @xref{gen-index,,Regenerating the index}.
|
|
|
512 @item queue-pr
|
|
|
513 @xref{queue-pr,,Handling incoming traffic}.
|
|
|
514 @item file-pr
|
|
|
515 @xref{file-pr,,Processing incoming traffic}.
|
|
|
516 @ignore
|
|
|
517 @item gnatsd
|
|
|
518 @xref{gnats,,Remote @sc{gnats} daemon}.
|
|
|
519 @end ignore
|
|
|
520 @item at-pr
|
|
|
521 @xref{at-pr,,Timely reminders}.
|
|
|
522 @item pr-edit
|
|
|
523 @xref{pr-edit,,The @code{edit-pr} driver}.
|
|
|
524 @ignore
|
|
|
525 @item npr-edit
|
|
|
526 @xref{npr-edit,,The remote @code{edit-pr} driver}.
|
|
|
527 @end ignore
|
|
|
528 @item pr-addr
|
|
|
529 @xref{pr-addr,,Address retrieval}.
|
|
|
530 @item libiberty.a
|
|
|
531 The @sc{gnu} @code{libiberty} library.
|
|
|
532 @end table
|
|
|
533
|
|
|
534 @item @var{prefix}/lib/gnats/dist
|
|
|
535
|
|
|
536 @table @asis
|
|
|
537 @item A packageable distribution of @code{send-pr}.
|
|
|
538 @xref{mkdist,,Configuring @code{send-pr} for the outside world}.
|
|
|
539 @end table
|
|
|
540
|
|
|
541 @item @var{prefix}/lib/gnats
|
|
|
542
|
|
|
543 @table @var
|
|
|
544 @item site
|
|
|
545 The local list of valid categories, used by @code{send-pr}; @var{site}
|
|
|
546 is the value of @samp{GNATS_SITE} (@pxref{config,,The @code{config}
|
|
|
547 file}).
|
|
|
548 @end table
|
|
|
549
|
|
|
550 @item @var{prefix}/lib/emacs/lisp
|
|
|
551
|
|
|
552 @table @code
|
|
|
553 @item gnats.el
|
|
|
554 @itemx gnats.elc
|
|
|
555 The Emacs versions of the programs @code{query-pr}, @code{edit-pr}, and
|
|
|
556 @code{view-pr}. @xref{Invoking the tools,,Invoking the @sc{gnats}
|
|
|
557 tools}. To change this directory you must alter @file{Makefile.in}; see
|
|
|
558 @ref{Configure and make,,Configuring and compiling the software}.
|
|
|
559 @item send-pr.el
|
|
|
560 The Emacs version of the program @code{send-pr}.
|
|
|
561 @xref{send-pr,,Submitting Problem Reports}.
|
|
|
562 @end table
|
|
|
563
|
|
|
564 @item @var{prefix}/info
|
|
|
565
|
|
|
566 @table @code
|
|
|
567 @item gnats.info
|
|
|
568 @itemx send-pr.info
|
|
|
569 The @sc{gnats} manuals, in a form readable by @code{info} (the @sc{gnu}
|
|
|
570 hypertext browser). @xref{Info,,Reading GNU Online
|
|
|
571 Documentation,infoman,GNU Online Documentation}.
|
|
|
572 @end table
|
|
|
573
|
|
|
574 @item @var{prefix}/man/man1
|
|
|
575 @itemx @var{prefix}/man/man8
|
|
|
576
|
|
|
577 @table @asis
|
|
|
578 @item @code{man} pages for all the @sc{gnats} tools and utilities.
|
|
|
579 @xref{Invoking the tools,,Invoking the @sc{gnats} tools}.
|
|
|
580 @end table
|
|
|
581
|
|
|
582 @c FIXME - does this happen?
|
|
|
583 @item @var{prefix}/src
|
|
|
584
|
|
|
585 @table @asis
|
|
|
586 @item Source code for @sc{gnats}.
|
|
|
587 @end table
|
|
|
588
|
|
|
589 @item @var{prefix}/sample
|
|
|
590
|
|
|
591 @table @asis
|
|
|
592 @item Example administrative files, including @file{categories},
|
|
|
593 @file{submitters}, @file{responsible}, and @file{config}. @xref{Local
|
|
|
594 configuration,,Changing your local configuration}.
|
|
|
595 @end table
|
|
|
596
|
|
|
597 @item @w{@var{GNATS_ROOT}}
|
|
|
598
|
|
|
599 @table @code
|
|
|
600 @item gnats-adm
|
|
|
601 Administration and configuration data files. The files
|
|
|
602 @table @code
|
|
|
603 @item config
|
|
|
604 @item categories
|
|
|
605 @item submitters
|
|
|
606 @item responsible
|
|
|
607 @item gnatsd.conf
|
|
|
608 @item index
|
|
|
609 (@emph{This file is created by @sc{gnats}.})
|
|
|
610 @item current
|
|
|
611 (@emph{This file is created by @sc{gnats}.})
|
|
|
612 @end table
|
|
|
613 @noindent
|
|
|
614 exist here. @xref{Local configuration,,Changing your local
|
|
|
615 configuration}, and @ref{Admin files,,Administrative data files}.
|
|
|
616 @item gnats-queue
|
|
|
617 Incoming Problem Reports are queued here until the next iteration of
|
|
|
618 @w{@samp{queue-pr -r}} (@pxref{queue-pr,,Handling incoming traffic}).
|
|
|
619 @item pending
|
|
|
620 Problem Reports which arrive without a valid category value are
|
|
|
621 reassigned to the category @samp{pending} and placed here pending
|
|
|
622 intervention by the @sc{gnats} administrator.
|
|
|
623 @xref{Management,,@sc{gnats} administration}.
|
|
|
624 @item @var{category}
|
|
|
625 Each valid category has a corresponding subdirectory in the database.
|
|
|
626 All Problem Reports associated with that category are kept in that
|
|
|
627 subdirectory, along with lock files for PRs which are being edited.
|
|
|
628 @end table
|
|
|
629
|
|
|
630 @end table
|
|
|
631
|
|
|
632 @c ===============================================================
|
|
|
633 @node Regexps
|
|
|
634 @appendix Querying using regular expressions
|
|
|
635 @cindex querying using regexps
|
|
|
636 @cindex regular expressions
|
|
|
637 @cindex syntax of regexps
|
|
|
638
|
|
|
639 @c FIXME - all my examples just use . and *
|
|
|
640 @sc{gnats} uses @sc{gnu} regular expression syntax with these settings:
|
|
|
641
|
|
|
642 @smallexample
|
|
|
643 RE_SYNTAX_POSIX_EXTENDED | RE_BK_PLUS_QM & RE_DOT_NEWLINE
|
|
|
644 @end smallexample
|
|
|
645
|
|
|
646 @noindent
|
|
|
647 This means that parentheses (@samp{(} and @samp{)}) and pipe symbols
|
|
|
648 (@samp{|}) do not need to be used with the escape symbol @samp{\}. The
|
|
|
649 tokens @samp{+} and @samp{?} do need the escape symbol, however.
|
|
|
650
|
|
|
651 Unfortunately, we do not have room in this manual for an adequate
|
|
|
652 tutorial on regular expressions. The following is a basic summary of
|
|
|
653 some regular expressions you might wish to use.
|
|
|
654
|
|
|
655 @xref{Regular Expression Syntax,,Regular Expression Syntax,regex,Regex},
|
|
|
656 for details on regular expression syntax. Also see @ref{Regexps,,Syntax
|
|
|
657 of Regular Expressions,emacs,GNU Emacs Manual}, but beware that the
|
|
|
658 syntax for regular expressions in Emacs is slightly different.
|
|
|
659
|
|
|
660 All search criteria options to @code{query-pr} rely on regular
|
|
|
661 expression syntax to construct their search patterns. For example,
|
|
|
662
|
|
|
663 @smallexample
|
|
|
664 query-pr --state=open
|
|
|
665 @end smallexample
|
|
|
666
|
|
|
667 @noindent
|
|
|
668 matches all PRs whose @samp{>State:} values match with the regular
|
|
|
669 expression @samp{open}.
|
|
|
670
|
|
|
671 We can substitute the expression @samp{o} for @samp{open}, according
|
|
|
672 to @sc{gnu} regular expression syntax. This matches all values of
|
|
|
673 @samp{>State:} which begin with the letter @samp{o}.
|
|
|
674
|
|
|
675 @smallexample
|
|
|
676 query-pr --state=o
|
|
|
677 @end smallexample
|
|
|
678
|
|
|
679 is equivalent to
|
|
|
680
|
|
|
681 @smallexample
|
|
|
682 query-pr --state=open
|
|
|
683 @end smallexample
|
|
|
684
|
|
|
685 @noindent
|
|
|
686 in this case, since the only value for @samp{>State:} which matches the
|
|
|
687 expression @samp{o} is @samp{open}. (Double quotes (@kbd{"}) are used
|
|
|
688 to protect the asterix (@kbd{*}) from the shell.) @samp{--state=o} also
|
|
|
689 matches @samp{o}, @samp{oswald}, and even @samp{oooooo}, but none of
|
|
|
690 those values are valid states for a Problem Report.
|
|
|
691
|
|
|
692 Regular expression syntax considers a regexp token surrounded with
|
|
|
693 parentheses, as in @w{@samp{(@var{regexp})}}, to be a @dfn{group}. This
|
|
|
694 means that @w{@samp{(ab)*}} matches any number of contiguous instances
|
|
|
695 of @samp{ab}, including zero. Matches include @samp{}, @samp{ab}, and
|
|
|
696 @samp{ababab}.
|
|
|
697
|
|
|
698 Regular expression syntax considers a regexp token surrounded with
|
|
|
699 square brackets, as in @w{@samp{[@var{regexp}]}}, to be a @dfn{list}.
|
|
|
700 This means that @w{@samp{Char[(ley)(lene)(broiled)}} matches any of the
|
|
|
701 words @samp{Charley}, @samp{Charlene}, or @samp{Charbroiled} (case is
|
|
|
702 significant; @samp{charbroiled} is not matched).
|
|
|
703
|
|
|
704 Using groups and lists, we see that
|
|
|
705
|
|
|
706 @smallexample
|
|
|
707 query-pr --category="gcc|gdb|gas"
|
|
|
708 @end smallexample
|
|
|
709
|
|
|
710 @noindent
|
|
|
711 is equivalent to
|
|
|
712
|
|
|
713 @smallexample
|
|
|
714 query-pr --category="g(cc|db|as)"
|
|
|
715 @end smallexample
|
|
|
716
|
|
|
717 @noindent
|
|
|
718 and is also very similar to
|
|
|
719
|
|
|
720 @smallexample
|
|
|
721 query-pr --category="g[cda]"
|
|
|
722 @end smallexample
|
|
|
723
|
|
|
724 @noindent
|
|
|
725 with the exception that this last search matches any values which begin
|
|
|
726 with @samp{gc}, @samp{gd}, or @samp{ga}.
|
|
|
727
|
|
|
728 The @samp{.} character is known as a @dfn{wildcard}. @samp{.} matches
|
|
|
729 on any single character. @samp{*} matches the previous character
|
|
|
730 (except newlines), list, or group any number of times, including zero.
|
|
|
731 Therefore, we can understand @samp{.*} to mean ``match zero or more
|
|
|
732 instances of any character.'' For this reason, we never specify it at
|
|
|
733 the end of a regular expression, as that would be redundant. The
|
|
|
734 expression @samp{o} matches any instance of the letter @samp{o}
|
|
|
735 (followed by anything) at the beginning of a line, while the expression
|
|
|
736 @samp{o.*} matches any instance of the letter @samp{o} at the beginning
|
|
|
737 of a line followed by any number (including zero) of any characters.
|
|
|
738
|
|
|
739 We can also use the expression operator @samp{|} to signify a logical
|
|
|
740 @code{OR}, such that
|
|
|
741
|
|
|
742 @smallexample
|
|
|
743 query-pr --state="o|a"
|
|
|
744 @end smallexample
|
|
|
745
|
|
|
746 @noindent
|
|
|
747 matches all @samp{open} or @samp{analyzed} Problem Reports. (Double
|
|
|
748 quotes (@kbd{"}) are used to protect the pipe symbol (@kbd{|}) from the
|
|
|
749 shell.)
|
|
|
750
|
|
|
751 By the same token,@footnote{No pun intended.} using
|
|
|
752
|
|
|
753 @smallexample
|
|
|
754 query-pr --state=".*a"
|
|
|
755 @end smallexample
|
|
|
756
|
|
|
757 @noindent
|
|
|
758 matches all values for @samp{>State:} which contain an @samp{a}. (These
|
|
|
759 include @samp{analyzed} and @samp{feedback}.)
|
|
|
760
|
|
|
761 Another way to understand what wildcards do is to follow them on their
|
|
|
762 search for matching text. By our syntax, @samp{.*} matches any
|
|
|
763 character any number of times, including zero. Therefore, @samp{.*a}
|
|
|
764 searches for any group of characters which end with @samp{a}, ignoring
|
|
|
765 the rest of the field. @samp{.*a} matches @samp{analyzed} (stopping at
|
|
|
766 the first @samp{a}) as well as @samp{feedback}.
|
|
|
767
|
|
|
768 @emph{Note:} When using @samp{--text} or @samp{--multitext}, you do not
|
|
|
769 have to specify the token @samp{.*} at the beginning of @var{text} to
|
|
|
770 match the entire field. For the technically minded, this is because
|
|
|
771 @samp{--text} and @samp{--multitext} use @samp{re_search} rather than
|
|
|
772 @samp{re_match}. @samp{re_match} @dfn{anchors} the search at the
|
|
|
773 beginning of the field, while @samp{re_search} does not anchor the
|
|
|
774 search.
|
|
|
775
|
|
|
776 For example, to search in the @code{>Description:} field for the text
|
|
|
777
|
|
|
778 @smallexample
|
|
|
779 The defrobulator component returns a nil value.
|
|
|
780 @end smallexample
|
|
|
781
|
|
|
782 @noindent
|
|
|
783 we can use
|
|
|
784
|
|
|
785 @smallexample
|
|
|
786 query-pr --multitext="defrobulator.*nil"
|
|
|
787 @end smallexample
|
|
|
788
|
|
|
789 To also match newlines, we have to include the expression @samp{(.|^M)}
|
|
|
790 instead of just a dot (@samp{.}). @samp{(.|^M)} matches ``any single
|
|
|
791 character except a newline (@samp{.}) @emph{or} (@samp{|}) any newline
|
|
|
792 (@samp{^M}).'' This means that to search for the text
|
|
|
793
|
|
|
794 @smallexample
|
|
|
795 The defrobulator component enters the bifrabulator routine
|
|
|
796 and returns a nil value.
|
|
|
797 @end smallexample
|
|
|
798
|
|
|
799 @noindent
|
|
|
800 we must use
|
|
|
801
|
|
|
802 @smallexample
|
|
|
803 query-pr --multitext="defrobulator(.|^M)*nil"
|
|
|
804 @end smallexample
|
|
|
805
|
|
|
806 To generate the newline character @samp{^M}, type the following
|
|
|
807 depending on your shell:
|
|
|
808
|
|
|
809 @table @code
|
|
|
810 @item csh
|
|
|
811 @samp{@emph{control}-V @emph{control}-M}
|
|
|
812
|
|
|
813 @item tcsh
|
|
|
814 @samp{@emph{control}-V @emph{control}-J}
|
|
|
815
|
|
|
816 @item sh (@emph{or} bash)
|
|
|
817 Use the @key{RETURN} key, as in
|
|
|
818
|
|
|
819 @smallexample
|
|
|
820 (.|
|
|
|
821 )
|
|
|
822 @end smallexample
|
|
|
823 @end table
|
|
|
824
|
|
|
825 Again, see @ref{Regular Expression Syntax,,Regular Expression
|
|
|
826 Syntax,regex,Regex}, for a much more complete discussion on regular
|
|
|
827 expression syntax.
|
|
|
828
|
|
|
829 @c ===============================================================
|
|
|
830
|
|
|
831 @ignore
|
|
|
832 @c complete this someday...
|
|
|
833 @node Glossary
|
|
|
834 @unnumbered Glossary
|
|
|
835
|
|
|
836 @table @strong
|
|
|
837 @item PR
|
|
|
838 Short for ``Problem Report''. An electronic mail message which reports
|
|
|
839 a problem. A @dfn{record} in the @sc{gnats} database.
|
|
|
840
|
|
|
841 @item Support Site
|
|
|
842 A central site that provides resources for maintainers of a body of
|
|
|
843 work, such as a software package. We refer to the Support Site as the
|
|
|
844 location where @sc{gnats} is installed and functional.
|
|
|
845
|
|
|
846 @item Database
|
|
|
847 An organized collection of information.
|
|
|
848
|
|
|
849 @item @sc{gnats}
|
|
|
850 The @sc{gnu} Problem Report Management System.
|
|
|
851
|
|
|
852 @item Field
|
|
|
853 A location for specific information. A group of fields make up a
|
|
|
854 Problem Report.
|
|
|
855
|
|
|
856 @item Mail header
|
|
|
857 Defined by the Internet Internet standard RFC-822
|
|
|
858
|
|
|
859 @item Category
|
|
|
860 @item Submitter
|
|
|
861 @item Originator
|
|
|
862 @item Query
|
|
|
863 @item Report
|
|
|
864 @item Site
|
|
|
865 @item Edit
|
|
|
866 @item Submit
|
|
|
867 @item Bug
|
|
|
868 @item State
|
|
|
869 @item ID Number
|
|
|
870 @item Synopsis
|
|
|
871 @item Confidential
|
|
|
872 @item Severity
|
|
|
873 @item Priority
|
|
|
874 @item Responsible
|
|
|
875 @item Configuration
|
|
|
876 @item Class
|
|
|
877 @item Environment
|
|
|
878 @item Description
|
|
|
879 @item Audit-Trail
|
|
|
880 @item Unformatted
|
|
|
881 @item Fix
|
|
|
882 @item Release
|
|
|
883 @item Makefile
|
|
|
884 @item gnats-admin
|
|
|
885 @item pending
|
|
|
886 @item send-pr
|
|
|
887 @item edit-pr
|
|
|
888 @item Maintainers
|
|
|
889 @item timestamp
|
|
|
890 @item utility
|
|
|
891 @item tool
|
|
|
892
|
|
|
893 @end table
|
|
|
894
|
|
|
895 @end ignore
|
|
|
896
|
|
|
897 @node Index
|
|
|
898 @unnumbered Index
|
|
|
899
|
|
|
900 @printindex cp
|
|
|
901
|
|
|
902 @contents
|
|
|
903
|
|
|
904 @bye
|
|
|
905
|
