annotate doc/user_guide.txt @ 3682:193f316dbbe9

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

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