Mercurial > p > roundup > code

annotate doc/user_guide.txt @ 1566:053065585406

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
added command-line functionality for roundup-adming (feature [SF#687664])
author Richard Jones <richard@users.sourceforge.net>
date Wed, 26 Mar 2003 11:02:28 +0000
parents 3f2e516b8de3
children 93e0a565cee5
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
1566
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
5 :Version: $Revision: 1.16 $
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
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
9 Note: this document will refer to *issues* as the primary store of information
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
10 in the tracker. This is the default of the classic template, bubt may vary in
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
11 any given installation.
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
12
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
13 Your Tracker in a Nutshell
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
14 ==========================
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
15
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
16 Your tracker holds information about issues in bundles we call *items*. An
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
17 item may be an *issue* (a bug or feature request) or a *user*. The issue-ness or
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
18 user-ness is called the item's *class*. So, for bug reports and features, the
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
19 class is "issue", and for users the class is "user".
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
20
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
21 Each item in the tracker has an id number that identifies it along with its
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
22 item class. To identify a particular issue or user, we combine the class with
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
23 the number to create a unique label, so that user 1 (who, incidentally, is
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
24 *always* the "admin" user) is referred to as "user1". Issue number 315 is
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
25 referred to as "issue315". We call that label the item's *designator*.
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
26
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
27 Accessing the Tracker
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
28 ---------------------
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
29
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
30 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
31
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
32 1. through the `web interface`_,
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
33 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
34 3. using the `command line tool`_.
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
35
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
36 The last is usually only used by administrators. Most users will use the web
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
37 and email interfaces. All three are explained below.
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
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
40 Web Interface
1199
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
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
43 Note: this document contains screenshots of the default look and feel. Your
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
44 site may have a slightly (or very) different look, but the functionality will
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
45 be very similar, and the concepts still hold.
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
46
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
47 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
48
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
49 1. `lists of items`_,
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
50 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
51 3. `searching page`_.
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
52
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
53
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
54 Lists of Items
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
55 --------------
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
56
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
57 The first thing you'll see when you log into Roundup will be a list of open
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
58 (ie. not resolved) issues. This list has been generated by a bunch of controls
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
59 `under the covers`_ but for now, you can see something like:
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
60
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
61 .. img: images/index_logged_out.png
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
62
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
63 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
64
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
65 .. img: images/page_layout.png
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
66
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
67 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
68
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
69 .. img: images/registration.png
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
70
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
71 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
72
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
73 .. img: images/index_logged_in.png
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
74
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
75 Note that the sidebar menu has changed slightly, so you can now get to your
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
76 "My Details" page:
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
77
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
78 .. img: images/my_details.png
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
79
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
80 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
81
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
82
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
83 Display, edit or entry of an item
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
84 ---------------------------------
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
85
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
86 Create a new issue with "create new" under the issue subheading. This will
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
87 take you to:
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
88
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
89 .. img: images/new_issue.png
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
90
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
91 The `nosy list`_ is explained below.
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
92 Enter some information and click "submit new entry" and you'll be rewarded
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
93 with:
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
94
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
95 .. img: images/new_issue_created.png
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
96
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
97 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
98 occurs) you'll get something like:
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
99
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
100 .. img: images/new_issue_error.png
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
101
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
102
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
103 Searching Page
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
104 --------------
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
105
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
106 XXX: some information about how searching works
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
107
1499
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
108 Some fields in the search page (e.g. "Activity" or "Creation date") accept
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
109 ranges of dates. You can specify range of dates in one of two formats:
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
110
1560
3f2e516b8de3 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1499
diff changeset
111 1. Native english syntax::
3f2e516b8de3 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1499
diff changeset
112
3f2e516b8de3 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1499
diff changeset
113 [[From] <value>][ To <value>]
3f2e516b8de3 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1499
diff changeset
114
3f2e516b8de3 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1499
diff changeset
115 Keywords "From" and "To" are case insensitive. Keyword "From" is optional.
1499
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
116
1560
3f2e516b8de3 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1499
diff changeset
117 2. "Geek" syntax::
1499
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
118
1560
3f2e516b8de3 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1499
diff changeset
119 [<value>][; <value>]
3f2e516b8de3 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1499
diff changeset
120
3f2e516b8de3 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1499
diff changeset
121 Either first or second ``<value>`` can be omitted in both syntaxes.
1499
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
122
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
123 For example:
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
124
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
125 if you enter string "from 9:00" to "Creation date" field, roundup
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
126 will find all issues, that were created today since 9 AM.
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
127
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
128 Searching of "-2m; -1m" on activity field gives you issues, which were
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
129 active between period of time since 2 months up-till month ago.
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
130
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
131 Other possible examples (consider local time is Sat Mar 8 22:07:48 EET 2003):
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
132
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
133 >>> Range("from 2-12 to 4-2")
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
134 <Range from 2003-02-12.00:00:00 to 2003-04-02.00:00:00>
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
135
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
136 >>> Range("18:00 TO +2m")
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
137 <Range from 2003-03-08.18:00:00 to 2003-05-08.20:07:48>
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
138
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
139 >>> Range("12:00")
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
140 <Range from 2003-03-08.12:00:00 to None>
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
141
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
142 >>> Range("tO +3d")
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
143 <Range from None to 2003-03-11.20:07:48>
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
144
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
145 >>> Range("2002-11-10; 2002-12-12")
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
146 <Range from 2002-11-10.00:00:00 to 2002-12-12.00:00:00>
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
147
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
148 >>> Range("; 20:00 +1d")
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
149 <Range from None to 2003-03-09.20:00:00>
8ee69708da0c added support for searching on ranges of dates
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1359
diff changeset
150
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
151
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
152 Under the covers
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
153 ----------------
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
154
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
155 Index views may be modified by the following arguments:
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
156
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
157 ========== =============================================================
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
158 Argument Description
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
159 ========== =============================================================
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
160 :sort sort by prop name, optionally preceeded with '-'
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
161 to give descending or nothing for ascending sorting.
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
162 :group group by prop name, optionally preceeded with '-' or
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
163 to sort in descending or nothing for ascending order.
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
164 :filter selects which props should be displayed in the filter
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
165 section. Default is all.
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
166 :columns selects the columns that should be displayed.
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
167 Default is all.
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
168 propname selects the values the item properties given by propname
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
169 must have (very basic search/filter).
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
170 ========== =============================================================
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
171
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
172 Access Controls
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
173 ---------------
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
174
1317
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
175 User access is controlled through Permissions. These are are grouped into
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
176 Roles, and users have a comma-separated list of Roles assigned to them.
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
177
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
178 Permissions divide access controls up into answering questions like:
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
179
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
180 - may the user edit issues ("Edit", "issue")
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
181 - is the user allowed to use the web interface ("Web Access")
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
182 - 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
183
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
184 Any number of new Permissions and Roles may be created as described in the
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
185 customisation documentation. Examples of new access controls are:
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
186
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
187 - only managers may sign off issues as complete
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
188 - don't give users who register through email web access
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
189 - 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
190
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
191
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
192 E-Mail Gateway
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
193 ==============
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
194
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
195 E-mail sent to Roundup is examined for several pieces of information:
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
196
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
197 1. `subject-line information`_ identifying the purpose of the e-mail
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
198 2. `e-mail message content`_ which is to be extracted
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
199 3. e-mail attachments which should be associated with the message
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
200
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
201 Subject-line information
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
202 ------------------------
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
203
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
204 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
205
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
206 1. the item that the message is responding to,
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
207 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
208 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
209
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
210 If the subject line contains a prefix in ``[square brackets]`` then we're
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
211 looking at case 1 or 2 above. Note that any "re:" or "fwd:" prefixes are
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
212 stripped off the subject line before we start looking for real information.
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
213
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
214 If an item designator (class name and id number, for example ``issue123``)
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 881
diff changeset
215 is found there, a new "msg" item is added to the "messages" property for
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 881
diff changeset
216 that item, and any new "file" items are added to the "files" property for
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
217 the item.
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
218
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
219 If just an item class name is found there, we attempt to create a new item of
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
220 that class with its "messages" property initialized to contain the new "msg"
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 881
diff changeset
221 item and its "files" property initialized to contain any new "file" items.
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
222
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
223 The third case above - where no ``[information]`` is provided, the tracker's
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
224 ``MAIL_DEFAULT_CLASS`` configuration variable defines what class of item
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
225 the message relates to. We try to match the subject line to an existing
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
226 item of the default class, and if there's a match, the message is related to
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
227 that matched item. If not, then a new item of the default class is created.
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
228
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
229 Setting Properties
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
230 ~~~~~~~~~~~~~~~~~~
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
231
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
232 The e-mail interface also provides a simple way to set properties on items. At
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
233 the end of the subject line, propname=value pairs can be specified in square
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
234 brackets, using the same conventions as for the roundup set shell command.
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
235
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
236 For example,
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
237
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
238 - setting the priority of an issue::
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
239
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
240 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
241
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
242 - adding yourself to a nosy list::
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
243
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
244 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
245
1282
2feb3e0a9955 included doc ideas from Bernhard Reiter
Richard Jones <richard@users.sourceforge.net>
parents: 1267
diff changeset
246 - 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
247
1282
2feb3e0a9955 included doc ideas from Bernhard Reiter
Richard Jones <richard@users.sourceforge.net>
parents: 1267
diff changeset
248 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
249
1282
2feb3e0a9955 included doc ideas from Bernhard Reiter
Richard Jones <richard@users.sourceforge.net>
parents: 1267
diff changeset
250 - 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
251
1282
2feb3e0a9955 included doc ideas from Bernhard Reiter
Richard Jones <richard@users.sourceforge.net>
parents: 1267
diff changeset
252 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
253
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
254 In all cases, the message relates to issue 2. The ``Re:`` prefix is stripped
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
255 off.
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
256
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
257
1267
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
258 Automatic Properties
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
259 ~~~~~~~~~~~~~~~~~~~~
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
260
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
261 **status of new issues**
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
262 When a new message is received that is not identified as being related to an
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
263 existing issue, it creates a new issue. The status of the new issue is
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
264 defaulted to "unread".
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
265
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
266 **reopening of resolved issues**
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
267 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
268 automatically reset to "chatting" to indicate new information has been
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
269 received.
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
270
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
271
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
272 E-Mail Message Content
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
273 ----------------------
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
274
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
275 Roundup only associates plain text (MIME type ``text/plain``) as messages for
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
276 items. Any other parts of a message are associated as downloadable files. If
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
277 no plain text part is found, the message is rejected.
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
278
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
279 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
280
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
281 * In a multipart/mixed message or part, each subpart is extracted and
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
282 examined. The text/plain subparts are assembled to form the textual body
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
283 of the message, to be stored in the file associated with a "msg" class
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 881
diff changeset
284 item. Any parts of other types are each stored in separate files and
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 881
diff changeset
285 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
286 * 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
287 subpart and ignore the other parts.
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
288
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
289 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
290 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
291 ``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
292
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
293 Message summary
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
294 ~~~~~~~~~~~~~~~
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
295
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 881
diff changeset
296 The "summary" property on message items is taken from the first non-quoting
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
297 section in the message body. The message body is divided into sections by blank
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
298 lines. Sections where the second and all subsequent lines begin with a ">" or
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
299 "|" character are considered "quoting sections". The first line of the first
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
300 non-quoting section becomes the summary of the message.
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
301
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
302
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
303 Address handling
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
304 ----------------
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
305
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
306 All of the addresses in the ``To:`` and ``Cc:`` headers of the incoming
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
307 message are
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
308 looked up among the tracker users, and the corresponding users are placed
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
309 in the
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 881
diff changeset
310 "recipients" property on the new "msg" item. The address in the ``From:`` header
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 881
diff changeset
311 similarly determines the "author" property of the new "msg" item. The default
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
312 handling for addresses that don't have corresponding users is to create new
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
313 users with no passwords and a username equal to the address.
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
314
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
315 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
316 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
317
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
318 ``ADD_AUTHOR_TO_NOSY``
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
319 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
320 If 'new' is used, then the author will only be added when a message
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
321 creates a new issue. If 'yes', then the author will be added on followups
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
322 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
323
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
324 ``ADD_RECIPIENTS_TO_NOSY``
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
325 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
326 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
327 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
328 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
329
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
330
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
331 Nosy List
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
332 ~~~~~~~~~
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
333
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
334 Roundup watches for additions to the "messages" property of items.
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
335
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
336 When a new message is added, it is sent to all the users
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
337 on the "nosy" list for the item that are not already on the "recipients" list
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
338 of the message. Those users are then appended to the "recipients" property on
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
339 the message, so multiple copies of a message are never sent to the same user.
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
340 The journal recorded by the hyperdatabase on the "recipients" property then
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
341 provides a log of when the message was sent to whom.
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
342
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
343 If the author of the message is also in the nosy list for the item that the
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
344 message is attached to, then the config var ``MESSAGES_TO_AUTHOR`` is queried
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
345 to determine if they get a nosy list copy of the message too.
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
346
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
347
1359
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
348 Mail gateway script command line
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
349 --------------------------------
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
350
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
351 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
352
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
353 . with an instance home as the only argument,
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
354 . with both an instance home and a mail spool file, or
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
355 . with both an instance home and a pop server account.
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
356
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
357 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
358 fields for a class created by the roundup-mailgw. The default class if
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
359 not specified is msg, but the other classes: issue, file, user can
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
360 also be used. The -S or --set options uses the same
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
361 property=value[;property=value] notation accepted by the command line
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
362 roundup command or the commands that can be given on the Subject line
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
363 of an email message.
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
364
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
365 It can let you set the type of the message on a per email address basis.
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
366
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
367 PIPE:
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
368 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
369 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
370
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
371 UNIX mailbox:
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
372 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
373 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
374 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
375 specified as::
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
376
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
377 mailbox /path/to/mailbox
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
378
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
379 POP:
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
380 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
381 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
382 server is specified as::
1560
3f2e516b8de3 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1499
diff changeset
383
1359
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
384 pop username:password@server
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
385
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
386 The username and password may be omitted::
1560
3f2e516b8de3 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1499
diff changeset
387
1359
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
388 pop username@server
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
389 pop server
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
390
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
391 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
392 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
393
1560
3f2e516b8de3 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1499
diff changeset
394 APOP:
3f2e516b8de3 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1499
diff changeset
395 Same as POP, but using Authenticated POP::
3f2e516b8de3 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1499
diff changeset
396
3f2e516b8de3 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1499
diff changeset
397 apop username:password@server
3f2e516b8de3 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1499
diff changeset
398
1359
ebfd8dd1cce7 missed this part of the patch, added doc
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
399
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
400 Command Line Tool
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
401 =================
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
402
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
403 The basic usage is::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
404
1566
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
405 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
406
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
407 Options:
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
408 -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
409 -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
410 -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
411 -c -- when outputting lists of data, comma-separate them.
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
412 Same as '-S ","'.
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
413 -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
414 -s -- when outputting lists of data, space-separate them.
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
415 Same as '-S " "'.
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
416
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
417 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
418
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
419 Help:
1566
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
420 roundup-admin -h
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
421 roundup-admin help -- this help
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
422 roundup-admin help <command> -- command-specific help
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
423 roundup-admin help all -- all available help
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
424
1566
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
425 Commands:
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
426 commit
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
427 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
428 display designator[,designator]*
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
429 export [class[,class]] export_dir
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
430 find classname propname=value ...
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
431 get property designator[,designator]*
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
432 help topic
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
433 history designator
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
434 import import_dir
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
435 initialise [adminpw]
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
436 install [template [backend [admin password]]]
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
437 list classname [property]
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
438 pack period | date
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
439 reindex
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
440 retire designator[,designator]*
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
441 rollback
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
442 security [Role name]
1566
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
443 set [items] property=value property=value ...
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
444 specification classname
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
445 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
446 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
447 command, e.g. l == li == lis == list.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
448
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
449
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
450 All commands (except help) require a tracker specifier. This is just the
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
451 path to the roundup tracker you're working with. A roundup tracker is where
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
452 roundup keeps the database and configuration file that defines an issue
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
453 tracker. It may be thought of as the issue tracker's "home directory".
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
454 It may be specified in the environment variable ``TRACKER_HOME`` or on
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
455 the command line as "``-i tracker``".
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
456
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 881
diff changeset
457 A designator is a classname and an itemid concatenated, eg. bug1, user10, ...
1566
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
458 Property values are represented as strings in command arguments and in the
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
459 printed results:
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
460
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
461 - Strings are, well, strings.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
462 - Password values will display as their encoded value.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
463 - Date values are printed in the full date format in the local time zone,
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
464 and accepted in the full format or any of the partial formats explained
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
465 below.::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
466
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
467 Input of... Means...
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
468 "2000-04-17.03:45" 2000-04-17.08:45:00
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
469 "2000-04-17" 2000-04-17.00:00:00
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
470 "01-25" yyyy-01-25.00:00:00
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
471 "08-13.22:13" yyyy-08-14.03:13:00
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
472 "11-07.09:32:43" yyyy-11-07.14:32:43
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
473 "14:25" yyyy-mm-dd.19:25:00
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
474 "8:47:11" yyyy-mm-dd.13:47:11
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
475 "." "right now"
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
476
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 881
diff changeset
477 - Link values are printed as item designators. When given as an argument,
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 881
diff changeset
478 item designators and key strings are both accepted.
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 881
diff changeset
479 - Multilink values are printed as lists of item designators joined by
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 881
diff changeset
480 commas. When given as an argument, item designators and key strings are
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 881
diff changeset
481 both accepted; an empty string, a single item, or a list of items joined
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
482 by commas is accepted.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
483
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
484 When multiple items are specified to the roundup get or roundup set
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
485 commands, the specified properties are retrieved or set on all the listed
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
486 items. When multiple results are returned by the roundup get or roundup
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
487 find commands, they are printed one per line (default) or joined by commas
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
488 (with the "``-c``" option).
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
489
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
490 Where the command changes data, a login name/password is required. The login may
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
491 be specified as either "``name``" or "``name:password``".
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
492
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
493 - ``ROUNDUP_LOGIN`` environment variable
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
494 - the "``-u``" command-line option
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
495
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
496 If either the name or password is not supplied, they are obtained from the
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
497 command-line.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
498
1566
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
499 Using with the shell
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
500 ~~~~~~~~~~~~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
501
1566
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
502 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
503 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
504
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
505 To find all messages regarding chatting issues that
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
506 contain the word "spam", for example, you could execute the
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
507 following command from the directory where the database
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
508 dumps its files::
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
509
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
510 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
511 > 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
512 > done
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
513 msg23
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
514 msg49
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
515 msg50
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
516 msg61
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
517 shell%
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
518
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
519 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
520
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
521 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
522 \`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
523 msg23
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
524 msg49
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
525 msg50
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
526 msg61
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
527 shell%
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
528
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
529 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
530
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
531 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
532 issue3,issue1`
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
533 files: []
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
534 inreplyto: None
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
535 recipients: []
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
536 author: 1
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
537 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
538 messageid: None
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
539 summary: jkdskldjf
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
540 files: []
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
541 inreplyto: None
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
542 recipients: []
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
543 author: 1
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
544 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
545 messageid: None
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
546 summary: jlkfjadsf
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
547
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
548 or status::
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
549
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
550 shell% 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
551 -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
552 unread
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
553 deferred
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
554
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
555 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
556
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
557 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
558 -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
559 unread deferred
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
560
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
561 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
562
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
563 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
564 -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
565 unread deferred
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
566
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
567 Also the tautological::
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
568
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
569 shell% roundup-admin get name \
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
570 `roundup-admin -dc get status \`roundup-admin -dc find issue \
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
571 status=chatting\``
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
572 chatting
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
573 chatting
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
574
053065585406 added command-line functionality for roundup-adming (feature [SF#687664])
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
575 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
576 them ',' separated so using '-dc' is almost always required.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
577
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
578 -----------------
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
579
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
580 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
581
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
582 .. _`Table of Contents`: index.html
1317
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
583 .. _`customisation documentation`: customizing.html
Roundup Issue Tracker: http://roundup-tracker.org/