annotate doc/user_guide.txt @ 3696:790363e96852

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

Roundup Issue Tracker: http://roundup-tracker.org/