Premiere version : mise en route du suivi.
[auf_roundup.git] / doc / .svn / text-base / user_guide.txt.svn-base
1 ==========
2 User Guide
3 ==========
4
5 .. contents::
6
7 .. hint::
8    This document will refer to *issues* as the primary store of
9    information in the tracker. This is the default of the classic template,
10    but may vary in any given installation.
11
12
13 Your Tracker in a Nutshell
14 ==========================
15
16 Your tracker holds information about issues in bundles we call *items*.
17 An item may be an *issue* (a bug or feature request) or a *user*. The
18 issue-ness or user-ness is called the item's *class*. So, for bug
19 reports and features, the class is "issue", and for users the class is
20 "user".
21
22 Each item in the tracker has an ID number that identifies it along with
23 its item class. To identify a particular issue or user, we combine the
24 class with the number to create a unique label, so that user 1 (who,
25 incidentally, is *always* the "admin" user) is referred to as "user1".
26 Issue number 315 is referred to as "issue315". We call that label the
27 item's *designator*.
28
29 Items in the database are never deleted, they're just "retired". You
30 can still refer to them by ID - hence removing an item won't break
31 references to the item. It's just that the item won't appear in any
32 listings.
33
34
35 Accessing the Tracker
36 ---------------------
37
38 You may access your tracker through one of three ways:
39
40 1. through the `web interface`_,
41 2. through the `e-mail gateway`_, or
42 3. using the `command line tool`_.
43
44 The last is usually only used by administrators. Most users will use the
45 web and e-mail interfaces. All three are explained below.
46
47
48 Issue life cycles in Roundup
49 ----------------------------
50
51 New issues may be submitted via the web or e-mail.
52
53 By default, the issue will have the status "unread". If another message
54 is received for the issue, its status will change to "chatting". 
55
56 The "home" page for a tracker will generally display all issues which
57 are not "resolved".
58
59 If an issue is closed, and a new message is received then it'll be
60 reopened to the state of "chatting".
61
62 The full set of **prority** and **status** values are:
63
64 =========== =====================================
65 Priority    Description
66 =========== =====================================
67 "critical"  panic: work is stopped!
68 "urgent"    important, but not deadly
69 "bug"       lost work or incorrect results
70 "feature"   want missing functionality
71 "wish"      avoidable bugs, missing conveniences
72 =========== =====================================
73
74 ============= =====================================
75 Status        Description
76 ============= =====================================
77 "unread"      submitted but no action yet
78 "deferred"    intentionally set aside
79 "chatting"    under review or seeking clarification
80 "need-eg"     need a reproducible example of a bug
81 "in-progress" understood; development in progress
82 "testing"     we think it's done; others, please test
83 "done-cbb"    okay for now, but could be better
84 "resolved"    fix has been released
85 ============= =====================================
86
87
88 Entering values in your Tracker
89 -------------------------------
90
91 All interfaces to your tracker use the same format for entering values.
92 This means the web interface for entering a new issue, the web interface
93 for searching issues, the e-mail interface and even the command-line
94 administration tool.
95
96
97 String and Numeric properties
98 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
99
100 These fields just take a simple text value, like ``It's broken``.
101
102
103 Boolean properties
104 ~~~~~~~~~~~~~~~~~~
105
106 These fields take a value which indicates "yes"/"no", "true"/"false",
107 "1"/"0" or "on"/"off".
108
109
110 Constrained (link and multilink) properties
111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112
113 Fields like "Assigned To" and "Keywords" hold references to items in other
114 classes ("user" and "keyword" in those two cases.)
115
116 Sometimes, the selection is done through a menu, like in the "Assigned
117 To" field.
118
119 Where the input is not a simple menu selection, we use a comma-separated
120 list of values to indicated which values of "user" or "keyword" are
121 interesting. The values may be either numeric ids or the names of items.
122 The special value "-1" may be used to match items where the property is
123 not set. For example, the following searches on the issues:
124
125 ``assignedto=richard,george``
126   match issues which are assigned to richard or george.
127 ``assignedto=-1``
128   match issues that are not assigned to a user.
129 ``assignedto=2,3,40``
130   match issues that are assigned to users 2, 3 or 40.
131 ``keyword=user interface``
132   match issues with the keyword "user interface" in their keyword list
133 ``keyword=web interface,e-mail interface``
134   match issues with the keyword "web interface" or "e-mail interface" in
135   their keyword list
136 ``keyword=-1``
137   match issues with no keywords set
138
139
140 Date properties
141 ~~~~~~~~~~~~~~~
142
143 Date-and-time stamps are specified with the date in
144 international standard format (``yyyy-mm-dd``) joined to the time
145 (``hh:mm:ss``) by a period ``.``.  Dates in this form can be easily
146 compared and are fairly readable when printed.  An example of a valid
147 stamp is ``2000-06-24.13:03:59``. We'll call this the "full date
148 format".  When Timestamp objects are printed as strings, they appear in
149 the full date format.
150
151 For user input, some partial forms are also permitted: the whole time or
152 just the seconds may be omitted; and the whole date may be omitted or
153 just the year may be omitted.  If the time is given, the time is
154 interpreted in the user's local time zone. The Date constructor takes
155 care of these conversions. In the following examples, suppose that
156 ``yyyy`` is the current year, ``mm`` is the current month, and ``dd`` is
157 the current day of the month.
158
159 -   "2000-04-17" means <Date 2000-04-17.00:00:00>
160 -   "01-25" means <Date yyyy-01-25.00:00:00>
161 -   "2000-04-17.03:45" means <Date 2000-04-17.08:45:00>
162 -   "08-13.22:13" means <Date yyyy-08-14.03:13:00>
163 -   "11-07.09:32:43" means <Date yyyy-11-07.14:32:43>
164 -   "14:25" means
165 -   <Date yyyy-mm-dd.19:25:00>
166 -   "8:47:11" means
167 -   <Date yyyy-mm-dd.13:47:11>
168 -   the special date "." means "right now"
169
170
171 When searching, a plain date entered as a search field will match that date
172 exactly in the database.  We may also accept ranges of dates. You can
173 specify range of dates in one of two formats:
174
175 1. English syntax::
176
177     [From <value>][To <value>]
178
179    Keywords "From" and "To" are case insensitive. Keyword "From" is
180    optional.
181
182 2. "Geek" syntax::
183
184     [<value>];[<value>]
185
186 Either first or second ``<value>`` can be omitted in both syntaxes.
187
188 For example, if you enter string "from 9:00" to "Creation date" field,
189 roundup will find  all issues, that were created today since 9 AM.
190
191 The ``<value>`` may also be an interval, as described in the next section.
192 Searching of "-2m; -1m" on activity field gives you issues which were
193 active between period of time since 2 months up-till month ago.
194
195 Other possible examples (consider local time is 2003-03-08.22:07:48):
196
197 - "from 2-12 to 4-2" means
198   <Range from 2003-02-12.00:00:00 to 2003-04-02.00:00:00>
199 - "FROM 18:00 TO +2m" means
200   <Range from 2003-03-08.18:00:00 to 2003-05-08.20:07:48>
201 - "12:00;" means
202   <Range from 2003-03-08.12:00:00 to None>
203 - "tO +3d" means
204   <Range from None to 2003-03-11.20:07:48>
205 - "2002-11-10; 2002-12-12" means
206   <Range from 2002-11-10.00:00:00 to 2002-12-12.00:00:00>
207 - "; 20:00 +1d" means
208   <Range from None to 2003-03-09.20:00:00>
209 - "2003" means
210   <Range from 2003-01-01.00:00:00 to 2003-12-31.23:59:59>
211 - "2003-04" means
212   <Range from 2003-04-01.00:00:00 to 2003-04-30.23:59:59>
213     
214
215 Interval properties
216 ~~~~~~~~~~~~~~~~~~~
217
218 Date intervals are specified using the suffixes "y", "m", and "d".  The
219 suffix "w" (for "week") means 7 days. Time intervals are specified in
220 hh:mm:ss format (the seconds may be omitted, but the hours and minutes
221 may not).
222
223 -   "3y" means three years
224 -   "2y 1m" means two years and one month
225 -   "1m 25d" means one month and 25 days
226 -   "2w 3d" means two weeks and three days
227 -   "1d 2:50" means one day, two hours, and 50 minutes
228 -   "14:00" means 14 hours
229 -   "0:04:33" means four minutes and 33 seconds
230
231
232 Simple support for collision detection
233 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
234
235 Item edit pages remember when the item was last edited. When a form is
236 submitted, the user will be informed if someone else has edited the item
237 at the same time they tried to.
238
239
240 Web Interface
241 =============
242
243 .. note::
244    This document contains screenshots of the default look and feel.
245    Your site may have a slightly (or very) different look, but the
246    functionality will be very similar, and the concepts still hold.
247
248 The web interface is broken up into the following parts:
249
250 1. `lists of items`_,
251 2. `display, edit or entry of an item`_, and
252 3. `searching page`_.
253
254
255 Lists of Items
256 --------------
257
258 The first thing you'll see when you log into Roundup will be a list of
259 open (ie. not resolved) issues. This list has been generated by a bunch
260 of controls `under the covers`_ but for now, you can see something like:
261
262 .. image:: images/index_logged_out.png
263
264 The screen is divided up into three sections. There's a title which tells
265 you where you are, a sidebar which contains useful navigation tools and a
266 body which usually displays either a list of items or a single item from
267 the tracker.
268
269 You may either register or log in. Registration takes you to:
270
271 .. image:: images/registration.png
272
273 Once you're logged in, the sidebar changes to:
274
275 .. image:: images/index_logged_in.png
276
277 You can now get to your "My Details" page:
278
279 .. image:: images/my_details.png
280
281
282 Display, edit or entry of an item
283 ---------------------------------
284
285 Create a new issue with "create new" under the issue subheading. This
286 will take you to:
287
288 .. image:: images/new_issue.png
289
290 Editing an issue uses the same form, though now you'll see attached files
291 and messages, and the issue history at the bottom of the page:
292
293 .. image:: images/edit_issue.png
294
295
296 Searching Page
297 --------------
298
299 See `entering values in your tracker`_ for an explanation of what you
300 may type into the search form.
301
302
303 Saving queries
304 ~~~~~~~~~~~~~~
305
306 You may save queries in the tracker by giving the query a name. Each user
307 may only have one query with a given name - if a subsequent search is
308 performed with the same query name supplied, then it will edit the
309 existing query of the same name.
310
311 Queries may be marked as "private". These queries are only visible to the
312 user that created them. If they're not marked "private" then all other
313 users may include the query in their list of "Your Queries". Marking it as
314 private at a later date does not affect users already using the query, nor
315 does deleting the query.
316
317 If a user subsequently creates or edits a public query, a new personal
318 version of that query is made, with the same editing rules as described
319 above.
320
321
322 Under the covers
323 ~~~~~~~~~~~~~~~~
324
325 The searching page converts your selections into the following
326 arguments:
327
328 ============ =============================================================
329 Argument     Description
330 ============ =============================================================
331 @sort        sort by prop name, optionally preceeded with '-' to give
332              descending or nothing for ascending sorting. The sort
333              argument can have several props separated with comma.
334 @group       group by prop name, optionally preceeded with '-' or to sort
335              in descending or nothing for ascending order. The group
336              argument can have several props separated with comma.
337 @columns     selects the columns that should be displayed. Default is
338              all.                     
339 @filter      indicates which properties are being used in filtering.
340              Default is none.
341 propname     selects the values the item properties given by propname must
342              have (very basic search/filter).
343 @search_text performs a full-text search (message bodies, issue titles,
344              etc)
345 ============ =============================================================
346
347 You may manually write URLS that contain these arguments, like so
348 (whitespace has been added for clarity)::
349
350     /issue?status=unread,in-progress,resolved&
351         keyword=security,ui&
352         @group=priority,-status&
353         @sort=-activity&
354         @filters=status,keyword&
355         @columns=title,status,fixer
356
357
358 Access Controls
359 ---------------
360
361 User access is controlled through Permissions. These are are grouped
362 into Roles, and users have a comma-separated list of Roles assigned to
363 them.
364
365 Permissions divide access controls up into answering questions like:
366
367 - may the user edit issues ("Edit", "issue")
368 - is the user allowed to use the web interface ("Web Access")
369 - may the user edit other user's Roles through the web ("Web Roles")
370
371 Any number of new Permissions and Roles may be created as described in
372 the customisation documentation. Examples of new access controls are:
373
374 - only managers may sign off issues as complete
375 - don't give users who register through e-mail web access
376 - let some users edit the details of all users
377
378
379 E-Mail Gateway
380 ==============
381
382 Roundup trackers may be used to facilitate e-mail conversations around
383 issues. The "nosy" list attached to each issue indicates the users who
384 should receive e-mail when messages are added to the issue.
385
386 When e-mail comes into a tracker that identifies an issue in the subject
387 line, the content of the e-mail is attached to the issue.
388
389 You may even create new issues from e-mail messages.
390
391 E-mail sent to a tracker is examined for several pieces of information:
392
393 1. `subject-line information`_ identifying the purpose of the e-mail
394 2. `sender identification`_ using the sender of the message
395 3. `e-mail message content`_ which is to be extracted
396 4. e-mail attachments which should be associated with the message
397
398
399 Subject-line information
400 ------------------------
401
402 The subject line of the incoming message is examined to find one of:
403
404 1. the item that the message is responding to,
405 2. the type of item the message should create, or
406 3. we default the item class and try some trickiness
407
408 If the subject line contains a prefix in ``[square brackets]`` then
409 we're looking at case 1 or 2 above. Any "re:" or "fwd:" prefixes are
410 stripped off the subject line before we start looking for real
411 information.
412
413 If an item designator (class name and id number, for example
414 ``issue123``) is found there, a new "msg" item is added to the
415 "messages" property for that item, and any new "file" items are added to
416 the "files" property for the item.
417
418 If just an item class name is found there, we attempt to create a new
419 item of that class with its "messages" property initialized to contain
420 the new "msg" item and its "files" property initialized to contain any
421 new "file" items.
422
423 The third case above - where no ``[information]`` is provided, the
424 tracker's ``MAIL_DEFAULT_CLASS`` configuration variable defines what
425 class of item the message relates to. We try to match the subject line
426 to an existing item of the default class, and if there's a match, the
427 message is related to that matched item. If not, then a new item of the
428 default class is created.
429
430
431 Setting Properties
432 ~~~~~~~~~~~~~~~~~~
433
434 The e-mail interface also provides a simple way to set properties on
435 items. At the end of the subject line, propname=value pairs can be
436 specified in square brackets, using the same conventions as for the
437 roundup set shell command.
438
439 For example,
440
441 - setting the priority of an issue::
442
443    Subject: Re: [issue2] the coffee machine is broken! [priority=urgent]
444
445 - adding yourself to a nosy list::
446
447    Subject: Re: [issue2] we're out of widgets [nosy=+richard]
448
449 - setting the nosy list to just you and cliff::
450
451    Subject: Re: [issue2] we're out of widgets [nosy=richard,cliff]
452
453 - removing yourself from a nosy list and setting the priority::
454
455    Subject: Re: [issue2] we're out of widgets [nosy=-richard;priority=bug]
456
457 In all cases, the message relates to issue 2. The ``Re:`` prefix is
458 stripped off.
459
460
461 Automatic Properties
462 ~~~~~~~~~~~~~~~~~~~~
463
464 **status of new issues**
465  When a new message is received that is not identified as being related
466  to an existing issue, it creates a new issue. The status of the new
467  issue is defaulted to "unread".
468
469 **reopening of resolved issues**
470  When a message is is received for a resolved issue, the issue status is
471  automatically reset to "chatting" to indicate new information has been
472  received.
473
474
475 Sender identification
476 ---------------------
477
478 If the sender of an e-mail is unknown to Roundup (looking up both user
479 primary e-mail addresses and their alternate addresses) then a new user
480 may be created, depending on tracker configuration (see the `Admin
481 Guide`_ section "Users and Security" for configuration details.)
482
483 .. _`Admin Guide`: admin_guide.html
484
485 The new user will have their username set to the "user" part of
486 "user@domain" in their e-mail address. Their password will be
487 completely randomised, and they'll have to visit the web interface to
488 have it changed. Some sites don't allow web access by users who register
489 via e-mail like this.
490
491
492 E-Mail Message Content
493 ----------------------
494
495 Roundup only associates plain text (MIME type ``text/plain``) as
496 messages for items. Any other parts of a message are associated as
497 downloadable files. If no plain text part is found, the message is
498 rejected.
499
500 To do this, incoming messages are examined for multiple parts:
501
502 * In a multipart/mixed message or part, each subpart is extracted and
503   examined. The text/plain subparts are assembled to form the textual
504   body of the message, to be stored in the file associated with a "msg"
505   class item. Any parts of other types are each stored in separate files
506   and given "file" class items that are linked to the "msg" item.
507 * In a multipart/alternative message or part, we look for a text/plain
508   subpart and ignore the other parts.
509
510 If the message is a response to a previous message, and contains quoted
511 sections, then these will be stripped out of the message if the
512 ``EMAIL_KEEP_QUOTED_TEXT`` configuration variable is set to ``'no'``.
513
514 Message summary
515 ~~~~~~~~~~~~~~~
516
517 The "summary" property on message items is taken from the first
518 non-quoting section in the message body. The message body is divided
519 into sections by blank lines. Sections where the second and all
520 subsequent lines begin with a ">" or "|" character are considered
521 "quoting sections". The first line of the first non-quoting section
522 becomes the summary of the message.
523
524
525 Address handling
526 ----------------
527
528 All of the addresses in the ``To:`` and ``Cc:`` headers of the incoming
529 message are looked up among the tracker users, and the corresponding
530 users are placed in the "recipients" property on the new "msg" item. The
531 address in the ``From:`` header similarly determines the "author"
532 property of the new "msg" item. The default handling for addresses that
533 don't have corresponding users is to create new users with no passwords
534 and a username equal to the address.
535
536 The addresses mentioned in the ``To:``, ``From:`` and ``Cc:`` headers of
537 the message may be added to the `nosy list`_ depending on:
538
539 ``ADD_AUTHOR_TO_NOSY``
540  Does the author of a message get placed on the nosy list automatically?
541  If 'new' is used, then the author will only be added when a message
542  creates a new issue. If 'yes', then the author will be added on
543  followups too. If 'no', they're never added to the nosy.
544
545 ``ADD_RECIPIENTS_TO_NOSY``
546  Do the recipients (To:, Cc:) of a message get placed on the nosy list?
547  If 'new' is used, then the recipients will only be added when a message
548  creates a new issue. If 'yes', then the recipients will be added on
549  followups too. If 'no', they're never added to the nosy.
550
551
552 Nosy List
553 ~~~~~~~~~
554
555 Roundup watches for additions to the "messages" property of items.
556
557 When a new message is added, it is sent to all the users on the "nosy"
558 list for the item that are not already on the "recipients" list of the
559 message. Those users are then appended to the "recipients" property on
560 the message, so multiple copies of a message are never sent to the same
561 user. The journal recorded by the hyperdatabase on the "recipients"
562 property then provides a log of when the message was sent to whom.
563
564 If the author of the message is also in the nosy list for the item that
565 the message is attached to, then the config var ``MESSAGES_TO_AUTHOR``
566 is queried to determine if they get a nosy list copy of the message too.
567
568
569 Mail gateway script command line
570 --------------------------------
571
572 Usage::
573
574   roundup-mailgw [[-C class] -S field=value]* <instance home> [method]
575
576 The roundup mail gateway may be called in one of three ways:
577
578  - with an instance home as the only argument,
579  - with both an instance home and a mail spool file, or
580  - with both an instance home and a pop server account.
581  
582 It also supports optional -C and -S arguments that allows you to set a
583 fields for a class created by the roundup-mailgw. The default class if
584 not specified is msg, but the other classes: issue, file, user can also
585 be used. The -S or --set options uses the same
586 property=value[;property=value] notation accepted by the command line
587 roundup command or the commands that can be given on the Subject line of
588 an e-mail message.
589
590 It can let you set the type of the message on a per e-mail address basis.
591
592 PIPE:
593  In the first case, the mail gateway reads a single message from the
594  standard input and submits the message to the roundup.mailgw module.
595
596 UNIX mailbox:
597  In the second case, the gateway reads all messages from the mail spool
598  file and submits each in turn to the roundup.mailgw module. The file is
599  emptied once all messages have been successfully handled. The file is
600  specified as::
601
602    mailbox /path/to/mailbox
603
604 POP:
605  In the third case, the gateway reads all messages from the POP server
606  specified and submits each in turn to the roundup.mailgw module. The
607  server is specified as::
608
609     pop username:password@server
610
611  The username and password may be omitted::
612
613     pop username@server
614     pop server
615
616  are both valid. The username and/or password will be prompted for if
617  not supplied on the command-line.
618
619 APOP:
620  Same as POP, but using Authenticated POP::
621
622     apop username:password@server
623
624
625 Command Line Tool
626 =================
627
628 The basic usage is::
629
630  Usage: roundup-admin [options] [<command> <arguments>]
631
632  Options:
633   -i instance home  -- specify the issue tracker "home directory" to administer
634   -u                -- the user[:password] to use for commands
635   -d                -- print full designators not just class id numbers
636   -c                -- when outputting lists of data, comma-separate them.
637                Same as '-S ","'.
638   -S <string>       -- when outputting lists of data, string-separate them
639   -s                -- when outputting lists of data, space-separate them.
640                Same as '-S " "'.
641
642   Only one of -s, -c or -S can be specified.
643
644  Help:
645   roundup-admin -h
646   roundup-admin help                       -- this help
647   roundup-admin help <command>             -- command-specific help
648   roundup-admin help all                   -- all available help
649
650  Commands: 
651   commit
652   create classname property=value ...
653   display designator[,designator]*
654   export [class[,class]] export_dir
655   find classname propname=value ...
656   get property designator[,designator]*
657   help topic
658   history designator
659   import import_dir
660   initialise [adminpw]
661   install [template [backend [admin password]]]
662   list classname [property]
663   pack period | date
664   reindex
665   retire designator[,designator]*
666   rollback
667   security [Role name]
668   set items property=value property=value ...
669   specification classname
670   table classname [property[,property]*]
671  Commands may be abbreviated as long as the abbreviation matches only one
672  command, e.g. l == li == lis == list.
673
674
675 All commands (except help) require a tracker specifier. This is just the
676 path to the roundup tracker you're working with. A roundup tracker is
677 where roundup keeps the database and configuration file that defines an
678 issue tracker. It may be thought of as the issue tracker's "home
679 directory". It may be specified in the environment variable
680 ``TRACKER_HOME`` or on the command line as "``-i tracker``".
681
682 A designator is a classname and an itemid concatenated, eg. bug1,
683 user10, ... Property values are represented as strings in command
684 arguments and in the printed results:
685
686 - Strings are, well, strings.
687 - Password values will display as their encoded value.
688 - Date values are printed in the full date format in the local time
689   zone, and accepted in the full format or any of the partial formats
690   explained below.::
691   
692     Input of...        Means...
693     "2000-04-17.03:45" 2000-04-17.03:45:00
694     "2000-04-17"       2000-04-17.00:00:00
695     "01-25"            yyyy-01-25.00:00:00
696     "08-13.22:13"      yyyy-08-13.22:13:00
697     "11-07.09:32:43"   yyyy-11-07.09:32:43
698     "14:25"            yyyy-mm-dd.14:25:00
699     "8:47:11"          yyyy-mm-dd.08:47:11
700     "2003"             2003-01-01.00:00:00
701     "2003-04"          2003-04-01.00:00:00
702     "."                "right now"
703     
704 - Link values are printed as item designators. When given as an
705   argument, item designators and key strings are both accepted.
706 - Multilink values are printed as lists of item designators joined by
707   commas. When given as an argument, item designators and key strings
708   are both accepted; an empty string, a single item, or a list of items
709   joined by commas is accepted.
710   
711 When multiple items are specified to the roundup get or roundup set
712 commands, the specified properties are retrieved or set on all the
713 listed items.  When multiple results are returned by the roundup get or
714 roundup find commands, they are printed one per line (default) or joined
715 by commas (with the "``-c``" option).
716
717 Where the command changes data, a login name/password is required. The
718 login may be specified as either "``name``" or "``name:password``".
719
720 - ``ROUNDUP_LOGIN`` environment variable
721 - the "``-u``" command-line option
722
723 If either the name or password is not supplied, they are obtained from
724 the command-line.
725
726
727 Using with the shell
728 --------------------
729
730 With version 0.6.0 or newer of roundup (which introduced support for
731 multiple designators to display and the -d, -S and -s flags):
732
733 To find all messages regarding chatting issues that contain the word
734 "spam", for example, you could execute the following command from the
735 directory where the database dumps its files::
736
737     shell% for issue in `roundup-admin -ds find issue status=chatting`; do
738     > grep -l spam `roundup-admin -ds ' ' get messages $issue`
739     > done
740     msg23
741     msg49
742     msg50
743     msg61
744     shell%
745
746 Or, using the -dc option, this can be written as a single command::
747
748     shell% grep -l spam `roundup get messages \
749         \`roundup -dc find issue status=chatting\``
750     msg23
751     msg49
752     msg50
753     msg61
754     shell%
755
756 You can also display issue contents::
757
758     shell% roundup-admin display `roundup-admin -dc get messages \
759                issue3,issue1`
760     files: []
761     inreplyto: None
762     recipients: []
763     author: 1
764     date: 2003-02-16.21:23:03
765     messageid: None
766     summary: jkdskldjf
767     files: []
768     inreplyto: None
769     recipients: []
770     author: 1
771     date: 2003-02-15.01:59:11
772     messageid: None
773     summary: jlkfjadsf    
774     
775 or status::
776
777     shell% roundup-admin get name `/tools/roundup/bin/roundup-admin \
778           -dc -i /var/roundup/sysadmin get status issue3,issue1`
779     unread
780     deferred
781
782 or status on a single line::
783
784     shell% echo `roundup-admin get name \`/tools/roundup/bin/roundup-admin \
785              -dc -i /var/roundup/sysadmin get status issue3,issue1\``
786     unread deferred
787
788 which is the same as::
789
790     shell% roundup-admin -s get name `/tools/roundup/bin/roundup-admin \
791              -dc -i /var/roundup/sysadmin get status issue3,issue1`
792     unread deferred
793
794 Also the tautological::
795
796    shell% roundup-admin get name \
797       `roundup-admin -dc get status \`roundup-admin -dc find issue \
798           status=chatting\``
799    chatting
800    chatting
801
802 Remember the roundup commands that accept multiple designators accept
803 them ',' separated so using '-dc' is almost always required.
804