Mercurial > p > roundup > code
annotate doc/user_guide.txt @ 8266:43dc610bbd24
doc: known issues with possible dependent tests
When reversing the testing order, two blocks of tests fail. Document
these.
I spent time trying to fix them, but got nowhere. Obviously I am
missing something. But this doc gives future me or somebody else a
starting point.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Thu, 09 Jan 2025 09:32:10 -0500 |
| parents | 7d72b9a9fe9c |
| children | 2bf0c4e7795e |
| rev | line source |
|---|---|
|
6586
24e2eeb2ed9a
Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents:
6469
diff
changeset
|
1 .. meta:: |
|
6774
e7b4ad2c57ac
landmarks, skiplink, remove bad attrs, autocomplete search
John Rouillard <rouilj@ieee.org>
parents:
6613
diff
changeset
|
2 :description: |
|
7048
6f5054751fb6
Update meta description. Also fix test command in code.txt.
John Rouillard <rouilj@ieee.org>
parents:
6807
diff
changeset
|
3 Describes how to interact with a tracker based on the |
|
6f5054751fb6
Update meta description. Also fix test command in code.txt.
John Rouillard <rouilj@ieee.org>
parents:
6807
diff
changeset
|
4 Roundup Issue Tracker. Covers web (html), and email |
|
6f5054751fb6
Update meta description. Also fix test command in code.txt.
John Rouillard <rouilj@ieee.org>
parents:
6807
diff
changeset
|
5 interfaces. |
|
6586
24e2eeb2ed9a
Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents:
6469
diff
changeset
|
6 |
|
688
b38f4f95bffd
More doc tweaks
Richard Jones <richard@users.sourceforge.net>
parents:
686
diff
changeset
|
7 ========== |
|
659
e429649ed124
More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
8 User Guide |
|
e429649ed124
More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
9 ========== |
|
e429649ed124
More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
10 |
|
686
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
659
diff
changeset
|
11 .. contents:: |
|
4890
609edf9de0a5
docs: Remove one nesting level from ToC on subpages
anatoly techtonik <techtonik@gmail.com>
parents:
4792
diff
changeset
|
12 :local: |
|
686
c52122f38c9b
Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents:
659
diff
changeset
|
13 |
| 2409 | 14 .. hint:: |
| 15 This document will refer to *issues* as the primary store of | |
| 16 information in the tracker. This is the default of the classic template, | |
| 17 but may vary in any given installation. | |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
18 |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
19 |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
20 Your Tracker in a Nutshell |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
21 ========================== |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
22 |
|
8061
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
23 Your tracker holds information about issues in bundles called *items*. |
|
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
24 An item can be an *issue* (a bug or feature request) or a *user*. The |
|
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
25 issue-ness or user-ness is called the item's *class*. For bug |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
26 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
|
27 "user". |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
28 |
|
8061
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
29 Each item in the tracker possesses an ID number that identifies it |
|
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
30 alongside its item class. The combination of the class and ID number |
|
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
31 into a label identifies a specific issue or user. For instance, user 1 |
|
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
32 (who, by the way, always serves as the "admin" user) gets referred to |
|
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
33 as "user1". Issue number 315 gets denoted as "issue315". This label |
|
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
34 receives the designation of the item's :term:designator. |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
35 |
|
8061
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
36 Roundup never deletes items from the database. Instead, items get |
|
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
37 "retired". Viewing the item using its ID is still possible - thus, |
|
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
38 "removing" an item does not disrupt references to it. A retired item |
|
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
39 will not appear in the class listing. |
|
1615
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
40 |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
41 Accessing the Tracker |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
42 --------------------- |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
43 |
|
7278
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
44 You may access your tracker in three ways: |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
45 |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
46 1. through the `web interface`_, |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
47 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
|
48 3. using the `command line tool`_. |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
49 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
50 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
|
51 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
|
52 |
|
7279
0bf616cfa178
Move mail gateway and roundup-admin doc to admin guide from user guide
John Rouillard <rouilj@ieee.org>
parents:
7278
diff
changeset
|
53 .. _command line tool: admin_guide.html#using-roundup-admin |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
54 |
|
1615
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
55 Issue life cycles in Roundup |
|
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
56 ---------------------------- |
|
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
57 |
|
3529
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
58 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
|
59 |
|
8061
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
60 By default, the issue will have the status "unread". When the issue |
|
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
61 receives another message, its status will change to "chatting". |
|
1615
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
62 |
|
8061
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
63 Often, the "home" page for a tracker display all open issues (closed |
|
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
64 issues have a status of resolved, or done-cbb (cbb - could be |
|
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
65 better)). |
|
1615
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
66 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
67 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
|
68 reopened to the state of "chatting". |
|
1615
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
69 |
| 5827 | 70 The full set of **priority** and **status** values are: |
|
3650
77e067e64035
copy over status/priority descriptions from old overview doc
Richard Jones <richard@users.sourceforge.net>
parents:
3529
diff
changeset
|
71 |
|
7278
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
72 .. table:: Default priorities defined for the classic template. |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
73 :name: priority table |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
74 :widths: auto |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
75 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
76 =========== ===================================== |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
77 Priority Description |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
78 =========== ===================================== |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
79 "critical" panic: work is stopped! |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
80 "urgent" important, but not deadly |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
81 "bug" lost work or incorrect results |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
82 "feature" want missing functionality |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
83 "wish" avoidable bugs, missing conveniences |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
84 =========== ===================================== |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
85 |
|
3650
77e067e64035
copy over status/priority descriptions from old overview doc
Richard Jones <richard@users.sourceforge.net>
parents:
3529
diff
changeset
|
86 |
|
7278
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
87 .. table:: Default statuses defined for the classic template. |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
88 :name: status table |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
89 :widths: auto |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
90 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
91 ============= ===================================== |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
92 Status Description |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
93 ============= ===================================== |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
94 "unread" submitted but no action yet |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
95 "deferred" intentionally set aside |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
96 "chatting" under review or seeking clarification |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
97 "need-eg" need a reproducible example of a bug |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
98 "in-progress" understood; development in progress |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
99 "testing" we think it's done; others, please test |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
100 "done-cbb" okay for now, but could be better |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
101 "resolved" fix has been released |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
102 ============= ===================================== |
|
3650
77e067e64035
copy over status/priority descriptions from old overview doc
Richard Jones <richard@users.sourceforge.net>
parents:
3529
diff
changeset
|
103 |
|
8061
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
104 The tracker you are using may have different priorities and |
|
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
105 statuses. See your tracker admin for local details. |
|
1615
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
106 |
|
4929
57a482110a24
doc: Link XMLRPC `filter` doc to User Guide chapter about querying
anatoly techtonik <techtonik@gmail.com>
parents:
4890
diff
changeset
|
107 .. _query-tracker: |
|
57a482110a24
doc: Link XMLRPC `filter` doc to User Guide chapter about querying
anatoly techtonik <techtonik@gmail.com>
parents:
4890
diff
changeset
|
108 |
|
1588
1ac46e7e4150
more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents:
1575
diff
changeset
|
109 Entering values in your Tracker |
|
1ac46e7e4150
more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents:
1575
diff
changeset
|
110 ------------------------------- |
| 1575 | 111 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
112 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
|
113 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
|
114 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
|
115 administration tool. |
|
1588
1ac46e7e4150
more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents:
1575
diff
changeset
|
116 |
|
8255
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8253
diff
changeset
|
117 String Properties |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8253
diff
changeset
|
118 ~~~~~~~~~~~~~~~~~ |
| 1575 | 119 |
|
8061
b1d384d23cdb
docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents:
8052
diff
changeset
|
120 These fields just take a plain text value, like ``It's broken``. |
|
1588
1ac46e7e4150
more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents:
1575
diff
changeset
|
121 |
|
8255
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8253
diff
changeset
|
122 Number Properties |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8253
diff
changeset
|
123 ~~~~~~~~~~~~~~~~~ |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8253
diff
changeset
|
124 |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8253
diff
changeset
|
125 These fields take a real number with decimal point like ``+12456.78``, |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8253
diff
changeset
|
126 ``-12456.78`` ``12456.78``. It supports scientific/exponent notation |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8253
diff
changeset
|
127 like ``3.1415E-2``. Decimal commas (e.g. ``123456,78``) or thousand |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8253
diff
changeset
|
128 separators ``-12,456.78`` are not supported. |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8253
diff
changeset
|
129 |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8253
diff
changeset
|
130 Integer Properties |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8253
diff
changeset
|
131 ~~~~~~~~~~~~~~~~~~ |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8253
diff
changeset
|
132 |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8253
diff
changeset
|
133 These fields take a whole/integer number without decimal marker like |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8253
diff
changeset
|
134 ``123``, ``+123``, ``-123``. Exponents are not supported. |
| 1575 | 135 |
| 136 Boolean properties | |
| 137 ~~~~~~~~~~~~~~~~~~ | |
| 138 | |
| 139 These fields take a value which indicates "yes"/"no", "true"/"false", | |
| 140 "1"/"0" or "on"/"off". | |
| 141 | |
|
1588
1ac46e7e4150
more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents:
1575
diff
changeset
|
142 |
| 1575 | 143 Constrained (link and multilink) properties |
| 144 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 145 | |
|
3904
91008ec8f9a0
retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents:
3756
diff
changeset
|
146 Fields like "Assigned To" and "Keywords" hold references to items in other |
| 1575 | 147 classes ("user" and "keyword" in those two cases.) |
| 148 | |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
149 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
|
150 To" field. |
|
1588
1ac46e7e4150
more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents:
1575
diff
changeset
|
151 |
|
1ac46e7e4150
more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents:
1575
diff
changeset
|
152 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
|
153 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
|
154 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
|
155 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
|
156 not set. For example, the following searches on the issues: |
| 1575 | 157 |
| 158 ``assignedto=richard,george`` | |
| 159 match issues which are assigned to richard or george. | |
| 160 ``assignedto=-1`` | |
| 161 match issues that are not assigned to a user. | |
| 162 ``assignedto=2,3,40`` | |
| 163 match issues that are assigned to users 2, 3 or 40. | |
|
3904
91008ec8f9a0
retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents:
3756
diff
changeset
|
164 ``keyword=user interface`` |
|
91008ec8f9a0
retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents:
3756
diff
changeset
|
165 match issues with the keyword "user interface" in their keyword list |
|
91008ec8f9a0
retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents:
3756
diff
changeset
|
166 ``keyword=web interface,e-mail interface`` |
|
3529
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
167 match issues with the keyword "web interface" or "e-mail interface" in |
|
3904
91008ec8f9a0
retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents:
3756
diff
changeset
|
168 their keyword list |
|
91008ec8f9a0
retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents:
3756
diff
changeset
|
169 ``keyword=-1`` |
|
91008ec8f9a0
retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents:
3756
diff
changeset
|
170 match issues with no keywords set |
| 1575 | 171 |
|
7971
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
172 When entering the value for a constrained property you may have a |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
173 helper (also called classhelper) available by clicking on a link |
| 8032 | 174 usually displayed as ``(list)``. See the section `Using the |
|
7971
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
175 Classhelper`_ for details. |
| 1575 | 176 |
| 177 Date properties | |
| 178 ~~~~~~~~~~~~~~~ | |
| 179 | |
|
2750
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
180 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
|
181 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
|
182 (``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
|
183 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
|
184 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
|
185 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
|
186 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
|
187 |
|
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
188 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
|
189 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
|
190 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
|
191 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
|
192 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
|
193 ``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
|
194 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
|
195 |
|
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
196 - "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
|
197 - "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
|
198 - "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
|
199 - "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
|
200 - "11-07.09:32:43" means <Date yyyy-11-07.14:32:43> |
|
4650
0485b47a39a8
issue2550766: Minor formatting issues in the docs for date properties, thanks John Kristensen.
Bernhard Reiter <bernhard@intevation.de>
parents:
4402
diff
changeset
|
201 - "14:25" means <Date yyyy-mm-dd.19:25:00> |
|
0485b47a39a8
issue2550766: Minor formatting issues in the docs for date properties, thanks John Kristensen.
Bernhard Reiter <bernhard@intevation.de>
parents:
4402
diff
changeset
|
202 - "8:47:11" means <Date yyyy-mm-dd.13:47:11> |
|
2750
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
203 - 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
|
204 |
|
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
205 |
|
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
206 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
|
207 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
|
208 specify range of dates in one of two formats: |
| 1575 | 209 |
| 210 1. English syntax:: | |
| 211 | |
|
1599
cc96bf971b33
extended date syntax to make range searches even more useful
Andrey Lebedev <kedder@users.sourceforge.net>
parents:
1596
diff
changeset
|
212 [From <value>][To <value>] |
| 1575 | 213 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
214 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
|
215 optional. |
| 1575 | 216 |
| 217 2. "Geek" syntax:: | |
| 218 | |
|
1599
cc96bf971b33
extended date syntax to make range searches even more useful
Andrey Lebedev <kedder@users.sourceforge.net>
parents:
1596
diff
changeset
|
219 [<value>];[<value>] |
| 1575 | 220 |
| 221 Either first or second ``<value>`` can be omitted in both syntaxes. | |
| 222 | |
| 223 For example, if you enter string "from 9:00" to "Creation date" field, | |
| 224 roundup will find all issues, that were created today since 9 AM. | |
| 225 | |
|
2750
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
226 The ``<value>`` may also be an interval, as described in the next section. |
| 1575 | 227 Searching of "-2m; -1m" on activity field gives you issues which were |
| 228 active between period of time since 2 months up-till month ago. | |
| 229 | |
| 2910 | 230 Other possible examples (consider local time is 2003-03-08.22:07:48): |
| 1575 | 231 |
|
2750
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
232 - "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
|
233 <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
|
234 - "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
|
235 <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
|
236 - "12:00;" means |
|
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
237 <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
|
238 - "tO +3d" means |
|
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
239 <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
|
240 - "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
|
241 <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
|
242 - "; 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
|
243 <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
|
244 - "2003" means |
|
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
245 <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
|
246 - "2003-04" means |
|
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
247 <Range from 2003-04-01.00:00:00 to 2003-04-30.23:59:59> |
|
7064
3359dc1dabb0
Add OAuth authentication to the mailgw script
Ralf Schlatterbeck <rsc@runtux.com>
parents:
7048
diff
changeset
|
248 |
| 1575 | 249 |
| 250 Interval properties | |
| 251 ~~~~~~~~~~~~~~~~~~~ | |
| 252 | |
|
2750
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
253 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
|
254 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
|
255 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
|
256 may not). |
| 1575 | 257 |
|
2750
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
258 - "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
|
259 - "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
|
260 - "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
|
261 - "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
|
262 - "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
|
263 - "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
|
264 - "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
|
265 |
| 1575 | 266 |
|
2138
f76d1642014a
doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents:
2136
diff
changeset
|
267 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
|
268 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
f76d1642014a
doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents:
2136
diff
changeset
|
269 |
|
f76d1642014a
doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents:
2136
diff
changeset
|
270 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
|
271 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
|
272 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
|
273 |
|
f76d1642014a
doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents:
2136
diff
changeset
|
274 |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
275 Web Interface |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
276 ============= |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
277 |
| 2409 | 278 .. note:: |
| 279 This document contains screenshots of the default look and feel. | |
| 280 Your site may have a slightly (or very) different look, but the | |
| 281 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
|
282 |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
283 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
|
284 |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
285 1. `lists of items`_, |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
286 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
|
287 3. `searching page`_. |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
288 |
|
7278
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
289 In addition to the graphical web interface, Roundup has `REST`_ and |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
290 `XMLRPC`_ interfaces. These can be used by advanced users and |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
291 programmers to automate tasks and integrate with other programs. |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
292 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
293 .. _REST: rest.html |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
294 .. _XMLRPC: xmlrpc.html |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
295 |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
296 Lists of Items |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
297 -------------- |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
298 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
299 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
|
300 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
|
301 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
|
302 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
303 .. image:: images/index_logged_out.png |
|
7278
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
304 :width: 675 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
305 :height: 450 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
306 :alt: Image of the classic Roundup tracker showing a list of issues |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
307 that one would see before logging in. |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
308 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
309 The screen is divided up into three sections. There's a title which tells |
|
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
310 you where you are, a sidebar which contains useful navigation tools and a |
|
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
311 body which usually displays either a list of items or a single item from |
|
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
312 the tracker. |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
313 |
|
6257
f9c059921ccc
Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents:
6174
diff
changeset
|
314 You may register, reset your password or log in. Registration takes |
|
f9c059921ccc
Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents:
6174
diff
changeset
|
315 you to: |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
316 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
317 .. image:: images/registration.png |
|
7278
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
318 :width: 675 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
319 :height: 450 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
320 :alt: A registration form with fields for name, login name, |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
321 password etc. |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
322 |
|
6257
f9c059921ccc
Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents:
6174
diff
changeset
|
323 Clicking on the "Lost your login?" link allows you to reset your |
|
f9c059921ccc
Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents:
6174
diff
changeset
|
324 password. Resetting your password takes you to: |
|
f9c059921ccc
Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents:
6174
diff
changeset
|
325 |
|
f9c059921ccc
Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents:
6174
diff
changeset
|
326 .. image:: images/reset.png |
|
7278
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
327 :width: 605 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
328 :height: 495 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
329 :alt: A form with email address and username fields that will |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
330 trigger a password reset when submitted. |
|
6257
f9c059921ccc
Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents:
6174
diff
changeset
|
331 |
|
f9c059921ccc
Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents:
6174
diff
changeset
|
332 You can enter your username to get a reset email sent to your primary |
|
f9c059921ccc
Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents:
6174
diff
changeset
|
333 E-mail address. Otherwise you can enter your primary E-mail address or |
|
f9c059921ccc
Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents:
6174
diff
changeset
|
334 an Alternate E-mail address to get a reset email sent to that address. |
|
f9c059921ccc
Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents:
6174
diff
changeset
|
335 The reset email includes a verification link that can be used to |
|
6807
30bb17dc9f82
add expiration of verification link
John Rouillard <rouilj@ieee.org>
parents:
6774
diff
changeset
|
336 complete the password reset. The verification link expires in a week. |
|
6257
f9c059921ccc
Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents:
6174
diff
changeset
|
337 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
338 Once you're logged in, the sidebar changes to: |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
339 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
340 .. image:: images/index_logged_in.png |
|
7278
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
341 :width: 182 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
342 :height: 399 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
343 :alt: Navigation sidebar after login showing multiple links. It now |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
344 includes a link labeled "My Details" for the user's settings. |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
345 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
346 You can now get to your "My Details" page: |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
347 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
348 .. image:: images/my_details.png |
|
7278
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
349 :width: 667 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
350 :height: 558 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
351 :alt: A form allowing the user to change username, real name, email |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
352 address and it also shows activity done by the user. |
| 1228 | 353 |
| 354 Display, edit or entry of an item | |
| 355 --------------------------------- | |
| 356 | |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
357 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
|
358 will take you to: |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
359 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
360 .. image:: images/new_issue.png |
|
7278
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
361 :width: 648 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
362 :height: 277 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
363 :alt: A form for entering a new issue with title, priority, status |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
364 and other fields. All fields are empty. It also includes an |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
365 entry box for typing free form text to describe the issue. |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
366 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
367 Editing an issue uses the same form, though now you'll see attached files |
|
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
368 and messages, and the issue history at the bottom of the page: |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
369 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
370 .. image:: images/edit_issue.png |
|
7278
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
371 :width: 650 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
372 :height: 535 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
373 :alt: A form for editing an issue with title, priority, status |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
374 and other fields filled in. It also includes an entry box for |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
375 typing free form text to describe the issue. |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
376 |
|
6469
98082155ffea
Document "Make a copy" link
John Rouillard <rouilj@ieee.org>
parents:
6408
diff
changeset
|
377 The "Make a copy" link duplicate the current issue copying most of the |
|
98082155ffea
Document "Make a copy" link
John Rouillard <rouilj@ieee.org>
parents:
6408
diff
changeset
|
378 properties to a new issue. This is useful for splitting am issue into |
|
98082155ffea
Document "Make a copy" link
John Rouillard <rouilj@ieee.org>
parents:
6408
diff
changeset
|
379 sub-issues that can be assigned to different people. |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
380 |
| 1228 | 381 Searching Page |
| 382 -------------- | |
| 383 | |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
384 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
|
385 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
|
386 |
|
1ac46e7e4150
more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents:
1575
diff
changeset
|
387 |
|
2136
ee3cf6a44f29
queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents:
2028
diff
changeset
|
388 Saving queries |
|
ee3cf6a44f29
queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents:
2028
diff
changeset
|
389 ~~~~~~~~~~~~~~ |
|
ee3cf6a44f29
queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents:
2028
diff
changeset
|
390 |
|
ee3cf6a44f29
queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents:
2028
diff
changeset
|
391 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
|
392 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
|
393 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
|
394 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
|
395 |
|
ee3cf6a44f29
queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents:
2028
diff
changeset
|
396 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
|
397 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
|
398 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
|
399 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
|
400 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
|
401 |
|
ee3cf6a44f29
queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents:
2028
diff
changeset
|
402 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
|
403 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
|
404 above. |
|
ee3cf6a44f29
queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents:
2028
diff
changeset
|
405 |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
406 |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
407 Under the covers |
| 1575 | 408 ~~~~~~~~~~~~~~~~ |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
409 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
410 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
|
411 arguments: |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
412 |
|
3036
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
413 ============ ============================================================= |
|
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
414 Argument Description |
|
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
415 ============ ============================================================= |
| 5827 | 416 @sort sort by prop name, optionally preceded with '-' to give |
|
3696
790363e96852
Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents:
3650
diff
changeset
|
417 descending or nothing for ascending sorting. The sort |
|
790363e96852
Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents:
3650
diff
changeset
|
418 argument can have several props separated with comma. |
| 5827 | 419 @group group by prop name, optionally preceded with '-' or to sort |
|
3696
790363e96852
Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents:
3650
diff
changeset
|
420 in descending or nothing for ascending order. The group |
|
790363e96852
Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents:
3650
diff
changeset
|
421 argument can have several props separated with comma. |
|
3036
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
422 @columns selects the columns that should be displayed. Default is |
|
7064
3359dc1dabb0
Add OAuth authentication to the mailgw script
Ralf Schlatterbeck <rsc@runtux.com>
parents:
7048
diff
changeset
|
423 all. |
|
3036
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
424 @filter indicates which properties are being used in filtering. |
|
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
425 Default is none. |
|
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
426 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
|
427 have (very basic search/filter). |
|
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
428 @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
|
429 etc) |
|
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
430 ============ ============================================================= |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
431 |
|
7406
8bc4246480bf
Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
7279
diff
changeset
|
432 You may manually write URLs that contain these arguments, like so |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
433 (whitespace has been added for clarity):: |
| 1575 | 434 |
| 435 /issue?status=unread,in-progress,resolved& | |
|
3904
91008ec8f9a0
retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents:
3756
diff
changeset
|
436 keyword=security,ui& |
|
3696
790363e96852
Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents:
3650
diff
changeset
|
437 @group=priority,-status& |
|
3036
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
438 @sort=-activity& |
|
3904
91008ec8f9a0
retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents:
3756
diff
changeset
|
439 @filters=status,keyword& |
|
3036
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
440 @columns=title,status,fixer |
| 1575 | 441 |
|
6592
828e2eaee7cd
Document full text search
John Rouillard <rouilj@ieee.org>
parents:
6586
diff
changeset
|
442 Full text search using the xapian, whoosh and native indexers treats |
|
828e2eaee7cd
Document full text search
John Rouillard <rouilj@ieee.org>
parents:
6586
diff
changeset
|
443 the search query as a series of space separated words. Any word less |
|
6613
2eec7a500333
Doc updates for indexers.
John Rouillard <rouilj@ieee.org>
parents:
6592
diff
changeset
|
444 than 2 characters or more than 50 characters is discarded. Also a |
|
6592
828e2eaee7cd
Document full text search
John Rouillard <rouilj@ieee.org>
parents:
6586
diff
changeset
|
445 stoplist is used to remove common words like "with", "and" |
|
828e2eaee7cd
Document full text search
John Rouillard <rouilj@ieee.org>
parents:
6586
diff
changeset
|
446 etc. Additional stoplist words can be added in the tracker's |
|
828e2eaee7cd
Document full text search
John Rouillard <rouilj@ieee.org>
parents:
6586
diff
changeset
|
447 config.ini file. Once filtering of the word list is done, each indexed |
|
828e2eaee7cd
Document full text search
John Rouillard <rouilj@ieee.org>
parents:
6586
diff
changeset
|
448 item (e.g. title, file or message content ...) is searched and if all |
|
828e2eaee7cd
Document full text search
John Rouillard <rouilj@ieee.org>
parents:
6586
diff
changeset
|
449 the terms are found in the item the item is returned. Then the items |
|
828e2eaee7cd
Document full text search
John Rouillard <rouilj@ieee.org>
parents:
6586
diff
changeset
|
450 are mapped to an issue and the list of matching issues is generated. |
|
828e2eaee7cd
Document full text search
John Rouillard <rouilj@ieee.org>
parents:
6586
diff
changeset
|
451 |
|
828e2eaee7cd
Document full text search
John Rouillard <rouilj@ieee.org>
parents:
6586
diff
changeset
|
452 Other searching backends such as native-fts can be used in which case |
|
828e2eaee7cd
Document full text search
John Rouillard <rouilj@ieee.org>
parents:
6586
diff
changeset
|
453 the filtering above is not used. The search query can support |
|
828e2eaee7cd
Document full text search
John Rouillard <rouilj@ieee.org>
parents:
6586
diff
changeset
|
454 structure such as quoted phrases, matching one term or another rather |
|
828e2eaee7cd
Document full text search
John Rouillard <rouilj@ieee.org>
parents:
6586
diff
changeset
|
455 than both (or search), prefixes etc. In this case you should look at |
|
6613
2eec7a500333
Doc updates for indexers.
John Rouillard <rouilj@ieee.org>
parents:
6592
diff
changeset
|
456 the `documentation for configuring the native-fts`_ backend to find |
|
2eec7a500333
Doc updates for indexers.
John Rouillard <rouilj@ieee.org>
parents:
6592
diff
changeset
|
457 the supported format and features. |
|
2eec7a500333
Doc updates for indexers.
John Rouillard <rouilj@ieee.org>
parents:
6592
diff
changeset
|
458 |
|
2eec7a500333
Doc updates for indexers.
John Rouillard <rouilj@ieee.org>
parents:
6592
diff
changeset
|
459 .. _`documentation for configuring the native-fts`: admin_guide.html#configuring-native-fts-full-text-search |
| 1575 | 460 |
|
8171
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
461 Advanced Searching with Property Expressions |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
462 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
463 |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
464 You can create more advanced searches in your tracker by using Reverse |
|
8173
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
465 Polish Notation (`RPN`_) to make property expressions. By default, |
|
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
466 when filtering by multiple items, the expression type is 'or'. For |
|
8171
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
467 instance, if you filter the property assignedto by adding the query |
|
8173
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
468 string element ``assignedto=2,3,40``, it matches users numbered ``2 or |
|
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
469 3 or 40``. In RPN, this would be written as ``2, 3, or, 4, |
|
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
470 or``. Roundup uses negative numbers to represent operators. For |
|
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
471 example, using "-1" for a single value (e.g. the assignedto Link |
|
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
472 property, but not the keyword multivalued/MultiLink property) matches |
|
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
473 an issue where the property is 'not set'. |
|
8171
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
474 |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
475 The operators and their corresponding numbers are: |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
476 |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
477 * 'not' is represented by -2 |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
478 * 'and' is represented by -3 |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
479 * 'or' is represented by -4 |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
480 |
|
8173
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
481 So, ``assignedto=2,3,40`` is the same as |
|
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
482 ``assignedto=2,3,-4,40,-4``. While this example is the same as |
|
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
483 ``2,3,40``, the expression ``keyword=1,2,-3,-2`` filters issues that |
|
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
484 don't have both keywords 1 and 2. |
|
8171
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
485 |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
486 Another example is: ``creator=3,-2,1,-2,-3``. This is the same as the |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
487 expression: ``(not user3) and (not user1)``. Using the rules of logic, |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
488 this is the same as: ``not (user3 or user1)`` which is expressed in |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
489 RPN as ``creator=3,1,-4,-2``. Compare this to ``creator=3,1,-2`` which |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
490 returns issues created by user3 or any user other than user1. |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
491 |
|
8173
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
492 Another example, useful when filtering issues, is:: |
|
8172
6a58acc3f39f
docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8171
diff
changeset
|
493 |
|
6a58acc3f39f
docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8171
diff
changeset
|
494 keyword=-1,-2,1,8,-3,-2,-3 |
|
6a58acc3f39f
docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8171
diff
changeset
|
495 |
|
6a58acc3f39f
docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8171
diff
changeset
|
496 which returns issues that have one or more keywords set and the issue |
|
6a58acc3f39f
docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8171
diff
changeset
|
497 does not have keyword1 and keyword8 both set. In more standard infix |
|
8173
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
498 form:: |
|
8172
6a58acc3f39f
docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8171
diff
changeset
|
499 |
|
6a58acc3f39f
docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8171
diff
changeset
|
500 not empty and not (keyword1 and keyword8) |
|
6a58acc3f39f
docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8171
diff
changeset
|
501 |
|
8173
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
502 Typing these expressions manually can be tiresome and tricky. On the |
|
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
503 search page, there's an expression editor. You can access it by |
|
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
504 clicking on the ``(expr)`` link, which makes creating these |
|
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
505 expressions a bit easier. |
|
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
506 |
|
8253
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
507 If your expression has an error, you will be returned to the search |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
508 page and an error will be reported. For example using the expression |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
509 ``1, -3`` to search the nosy property of an issue generates the |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
510 following error:: |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
511 |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
512 There was an error searching issue by nosy using: [1, -3]. The |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
513 operator -3 (and) at position 2 has too few arguments. |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
514 |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
515 The error message gives you the problem element (``-3``), it's meaning |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
516 (``and``) and its position: the second element. The problem was caused |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
517 because ``and`` requires two arguments, but only one argument (``1``) |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
518 was given. |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
519 |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
520 Another error message:: |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
521 |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
522 There was an error searching issue by status using: [1, 2, -3, |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
523 -3]. The operator -3 (and) at position 4 has too few arguments. |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
524 |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
525 reports that the second ``-3`` in the 4th position is the problem |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
526 operator. Note that this search expression will never return any |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
527 values. This is because ``status`` is a single value (link) type |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
528 property. It can't have the values ``1`` and ``2``, so the expression |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
529 ``1,2,-3`` will never return an issue. |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
530 |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
531 In the examples above, the error was caused by not having enough |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
532 arguments. However you can also have too many arguments. An example of |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
533 this type of message is:: |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
534 |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
535 There was an error searching issue by nosy using: [4, 5, 1, 2, -3, |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
536 -3]. There are too many arguments for the existing operators. The |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
537 values on the stack are: [Value 4, (Value 5 AND (Value 1 AND Value |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
538 2))] |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
539 |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
540 This message gives you the expression as far as it was able to compose |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
541 it, but value 1 is not combined with the rest of the expression. So |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
542 another binary operator is needed to complete the expression. |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
543 |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
544 If you have multiple incorrect expressions in your search, only one |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
545 expression will be reported each time you submit the search. |
|
8171
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
546 |
|
7971
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
547 Using the Classhelper |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
548 --------------------- |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
549 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
550 The classhelper makes finding the id number or name for linked items |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
551 easier. It is usually invoked from the parent window by clicking on |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
552 the ``(list)`` link. There are two classhelpers: classic and |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
553 component. This documentation discusses the newer component |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
554 classhelper available with Roundup 2.4.0 or newer. If there is a |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
555 problem with the component classhelper, it reports the problem and |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
556 falls back to using the classic classhelper. |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
557 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
558 The component classhelper is displayed in a popup window. You can |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
559 interact with the original window by moving the popup out of the way |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
560 or minimizing it. If you don't see a popup, check to see if your |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
561 browser has disabled popup windows. |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
562 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
563 The classhelper has three parts: |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
564 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
565 1. an optional search pane |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
566 2. a selection pane |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
567 3. an accumulator pane |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
568 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
569 .. image:: images/classhelper-issue-all.png |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
570 :width: 675 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
571 :height: 914 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
572 :alt: Image of the new component classhelper popup. The image shows |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
573 the operating system window decorations with a title of "Superseder |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
574 Classhelper - issue2". Then it shows a search panel with options to |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
575 enter text to search issue titles or status and a select/dropdown |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
576 to search by a keyword on the issue. Below the options are search |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
577 and reset buttons. Below the search panel is a selection |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
578 panel that shows buttons to move to the previous or next pages and |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
579 says that it is displaying items 26 to 50. This is followed by a |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
580 scrollable table of issues where each row has a checkbox and the |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
581 box for issue 114 is checked. At the bottom of the window is a text |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
582 box that lists a number of issue numbers including 114. To the |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
583 right of the text box are apply and cancel buttons. |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
584 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
585 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
586 The search pane has text or select/dropdown fields to search for a |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
587 matching item. The image above shows a search for issues. The Title |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
588 and Status properties can be matched using a text input while the |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
589 Keyword property can be selected from a dropdown. Hitting enter while |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
590 in a text input will trigger a search and the results will be |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
591 displayed below the search pane in the selection pane. Tabbing to the |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
592 search button and pressing enter will also trigger a search. The reset |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
593 button will clear the search form. |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
594 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
595 Below the search pane is the select pane. It lists the number of items |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
596 displayed (26-50) and includes two buttons to move to the previous or |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
597 next page of search results. If there is no search pane, this will |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
598 display a page of items from all the items in the class. Below the |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
599 pagination component is the scrollable selection table. Each row in |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
600 the table has a checkbox and one or more columns of data about the |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
601 item. Clicking on a row toggles the item's checkbox and adds or |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
602 removes the id or name for the item in the accumulator's |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
603 display. Arrow keys or tab/shift-tab can be used to scroll through |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
604 each item in the selection table. The space key or enter will |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
605 select/deselect the item. You can jump to the page controls using the |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
606 '<' and '>' keys. Once the page control button is focused, press enter |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
607 to trigger a page change. |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
608 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
609 The bottom pane consists of a text input called the accumulator |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
610 display. It lists all the items that have been selected. The first two |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
611 items in this example were selected from the previous selection |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
612 page. Next to the display are the apply and cancel buttons. You can |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
613 jump to the apply button quickly by pressing Shift-Enter as long as |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
614 you are not in a search input. Once the apply button is focused, press |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
615 enter to copy the items in the display to the associated field on the |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
616 parent window. If you activate the cancel button or close the window |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
617 using the window decoration, the classhelper will close and not change |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
618 the parent window. |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
619 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
620 The classhelper can also be used in read-only mode. In this mode, the |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
621 accumulator is not shown. Also the checkboxes are not displayed. To |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
622 close the classhelper in read-only mode use the window decoration or a |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
623 hotkey (e.g. control-w). |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
624 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
625 You can have multiple classhelpers up at a time. The title on the |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
626 window identifies the property and item the classhelper will |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
627 modify. For example the image shows the superseder for issue2. |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
628 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
629 Do not refresh the classhelper window using the ``F5`` key. This will |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
630 erase the contents of the window and you will have to close it and |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
631 invoke the link from the parent window again. |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
632 |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
633 Access Controls |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
634 --------------- |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
635 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
636 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
|
637 into Roles, and users have a comma-separated list of Roles assigned to |
|
7406
8bc4246480bf
Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
7279
diff
changeset
|
638 them. Roles can allow you to access: |
|
1317
28ae91aae74f
clarifications
Richard Jones <richard@users.sourceforge.net>
parents:
1282
diff
changeset
|
639 |
|
7406
8bc4246480bf
Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
7279
diff
changeset
|
640 - an entire class of items (e.g. issues) |
|
8bc4246480bf
Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
7279
diff
changeset
|
641 - only certain fields of a class (e.g. you can see the username but |
|
8bc4246480bf
Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
7279
diff
changeset
|
642 not the phone number of other users) |
|
8bc4246480bf
Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
7279
diff
changeset
|
643 - fields or classes based on your relationship to an item (e.g. |
|
8bc4246480bf
Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
7279
diff
changeset
|
644 you can see the phone number of your user entry since you are the |
|
8bc4246480bf
Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
7279
diff
changeset
|
645 owner of your user entry) |
|
8bc4246480bf
Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
7279
diff
changeset
|
646 |
|
8bc4246480bf
Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
7279
diff
changeset
|
647 Other permissions divide access controls up into answering questions |
|
8bc4246480bf
Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
7279
diff
changeset
|
648 like: |
|
1317
28ae91aae74f
clarifications
Richard Jones <richard@users.sourceforge.net>
parents:
1282
diff
changeset
|
649 |
|
28ae91aae74f
clarifications
Richard Jones <richard@users.sourceforge.net>
parents:
1282
diff
changeset
|
650 - may the user edit issues ("Edit", "issue") |
|
28ae91aae74f
clarifications
Richard Jones <richard@users.sourceforge.net>
parents:
1282
diff
changeset
|
651 - is the user allowed to use the web interface ("Web Access") |
|
28ae91aae74f
clarifications
Richard Jones <richard@users.sourceforge.net>
parents:
1282
diff
changeset
|
652 - 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
|
653 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
654 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
|
655 the customisation documentation. Examples of new access controls are: |
|
1317
28ae91aae74f
clarifications
Richard Jones <richard@users.sourceforge.net>
parents:
1282
diff
changeset
|
656 |
|
28ae91aae74f
clarifications
Richard Jones <richard@users.sourceforge.net>
parents:
1282
diff
changeset
|
657 - only managers may sign off issues as complete |
|
3529
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
658 - don't give users who register through e-mail web access |
|
1317
28ae91aae74f
clarifications
Richard Jones <richard@users.sourceforge.net>
parents:
1282
diff
changeset
|
659 - 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
|
660 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
661 E-Mail Gateway |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
662 ============== |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
663 |
|
3529
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
664 Roundup trackers may be used to facilitate e-mail conversations around |
|
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
665 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
|
666 should receive e-mail when messages are added to the issue. |
|
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
667 |
|
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
668 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
|
669 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
|
670 |
|
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
671 You may even create new issues from e-mail messages. |
|
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
672 |
|
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
673 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
|
674 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
675 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
|
676 2. `sender identification`_ using the sender of the message |
|
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
677 3. `e-mail message content`_ which is to be extracted |
|
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
678 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
|
679 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
680 |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
681 Subject-line information |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
682 ------------------------ |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
683 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
684 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
|
685 |
| 5827 | 686 1. a case insensitive ``help``, |
|
5056
d995ee7d49bf
issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents:
5045
diff
changeset
|
687 2. a match for ``-- key <OneTimeKey>``, |
|
d995ee7d49bf
issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents:
5045
diff
changeset
|
688 3. the item that the message is responding to, |
|
d995ee7d49bf
issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents:
5045
diff
changeset
|
689 4. the type of item the message should create, or |
|
d995ee7d49bf
issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents:
5045
diff
changeset
|
690 5. we default the item class and try some trickiness. |
|
d995ee7d49bf
issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents:
5045
diff
changeset
|
691 |
|
d995ee7d49bf
issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents:
5045
diff
changeset
|
692 If the subject is ``help`` (case insensitive), the gateway responds |
| 5827 | 693 with an explanation of the interface. |
|
5056
d995ee7d49bf
issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents:
5045
diff
changeset
|
694 |
|
d995ee7d49bf
issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents:
5045
diff
changeset
|
695 If a one-time key is found, we're processing an in-progress |
|
d995ee7d49bf
issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents:
5045
diff
changeset
|
696 registration confirmation. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
697 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
698 If the subject line contains a prefix in ``[square brackets]`` then |
|
7234
86862ed039fa
issue2551262 - make mail gateway subject prefix parsing accept spaces
John Rouillard <rouilj@ieee.org>
parents:
7093
diff
changeset
|
699 we're looking at case 3 or 4 above. Spaces are allowed inside the |
|
86862ed039fa
issue2551262 - make mail gateway subject prefix parsing accept spaces
John Rouillard <rouilj@ieee.org>
parents:
7093
diff
changeset
|
700 brackets and after the class item name. So ``[issue2]`` and |
|
7252
9c067ed4568b
add pragma command to roundup-admin
John Rouillard <rouilj@ieee.org>
parents:
7234
diff
changeset
|
701 ``[ issue 2 ]`` are treated the same where any white space is optional. |
|
7234
86862ed039fa
issue2551262 - make mail gateway subject prefix parsing accept spaces
John Rouillard <rouilj@ieee.org>
parents:
7093
diff
changeset
|
702 Any "re:" or "fwd:" prefixes are stripped off the subject line before |
|
86862ed039fa
issue2551262 - make mail gateway subject prefix parsing accept spaces
John Rouillard <rouilj@ieee.org>
parents:
7093
diff
changeset
|
703 we start looking for real information. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
704 |
|
7406
8bc4246480bf
Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
7279
diff
changeset
|
705 If an item :term:`designator` (class name and id number, for example |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
706 ``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
|
707 "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
|
708 the "files" property for the item. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
709 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
710 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
|
711 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
|
712 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
|
713 new "file" items. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
714 |
|
5056
d995ee7d49bf
issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents:
5045
diff
changeset
|
715 The fifth case above - where no ``[information]`` is provided, the |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
716 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
|
717 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
|
718 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
|
719 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
|
720 default class is created. |
|
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
721 |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
722 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
723 Setting Properties |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
724 ~~~~~~~~~~~~~~~~~~ |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
725 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
726 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
|
727 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
|
728 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
|
729 roundup set shell command. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
730 |
|
8052
d54af8964fe3
docs: fix unwanted highlighting.
John Rouillard <rouilj@ieee.org>
parents:
8032
diff
changeset
|
731 .. highlight:: text |
|
d54af8964fe3
docs: fix unwanted highlighting.
John Rouillard <rouilj@ieee.org>
parents:
8032
diff
changeset
|
732 |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
733 For example, |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
734 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
735 - setting the priority of an issue:: |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
736 |
|
4298
f6468c5e1493
Fix typo in email section of user guide, fixes issue2550607
Richard Jones <richard@users.sourceforge.net>
parents:
4036
diff
changeset
|
737 Subject: Re: [issue2] the coffee machine is broken! [priority=urgent] |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
738 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
739 - adding yourself to a nosy list:: |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
740 |
|
7234
86862ed039fa
issue2551262 - make mail gateway subject prefix parsing accept spaces
John Rouillard <rouilj@ieee.org>
parents:
7093
diff
changeset
|
741 Subject: Re: [ issue2 ] we're out of widgets [nosy=+richard] |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
742 |
|
1282
2feb3e0a9955
included doc ideas from Bernhard Reiter
Richard Jones <richard@users.sourceforge.net>
parents:
1267
diff
changeset
|
743 - 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
|
744 |
|
7234
86862ed039fa
issue2551262 - make mail gateway subject prefix parsing accept spaces
John Rouillard <rouilj@ieee.org>
parents:
7093
diff
changeset
|
745 Subject: Re: [issue 2] we're out of widgets [nosy=richard,cliff] |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
746 |
|
1282
2feb3e0a9955
included doc ideas from Bernhard Reiter
Richard Jones <richard@users.sourceforge.net>
parents:
1267
diff
changeset
|
747 - 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
|
748 |
|
7234
86862ed039fa
issue2551262 - make mail gateway subject prefix parsing accept spaces
John Rouillard <rouilj@ieee.org>
parents:
7093
diff
changeset
|
749 Subject: Re: [ issue 2 ] 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
|
750 |
|
8052
d54af8964fe3
docs: fix unwanted highlighting.
John Rouillard <rouilj@ieee.org>
parents:
8032
diff
changeset
|
751 .. highlight:: python3 |
|
d54af8964fe3
docs: fix unwanted highlighting.
John Rouillard <rouilj@ieee.org>
parents:
8032
diff
changeset
|
752 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
753 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
|
754 stripped off. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
755 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
756 |
|
1267
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
757 Automatic Properties |
|
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
758 ~~~~~~~~~~~~~~~~~~~~ |
|
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
759 |
|
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
760 **status of new issues** |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
761 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
|
762 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
|
763 issue is defaulted to "unread". |
|
1267
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
764 |
|
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
765 **reopening of resolved issues** |
|
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
766 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
|
767 automatically reset to "chatting" to indicate new information has been |
|
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
768 received. |
|
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
769 |
|
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
770 |
|
1615
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
771 Sender identification |
|
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
772 --------------------- |
|
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
773 |
|
3529
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
774 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
|
775 primary e-mail addresses and their alternate addresses) then a new user |
|
4018
17bdd79a3ae1
clarify default permission change
Richard Jones <richard@users.sourceforge.net>
parents:
3904
diff
changeset
|
776 may be created, depending on tracker configuration (see the `Admin |
|
17bdd79a3ae1
clarify default permission change
Richard Jones <richard@users.sourceforge.net>
parents:
3904
diff
changeset
|
777 Guide`_ section "Users and Security" for configuration details.) |
|
17bdd79a3ae1
clarify default permission change
Richard Jones <richard@users.sourceforge.net>
parents:
3904
diff
changeset
|
778 |
|
17bdd79a3ae1
clarify default permission change
Richard Jones <richard@users.sourceforge.net>
parents:
3904
diff
changeset
|
779 .. _`Admin Guide`: admin_guide.html |
|
17bdd79a3ae1
clarify default permission change
Richard Jones <richard@users.sourceforge.net>
parents:
3904
diff
changeset
|
780 |
|
17bdd79a3ae1
clarify default permission change
Richard Jones <richard@users.sourceforge.net>
parents:
3904
diff
changeset
|
781 The new user will have their username set to the "user" part of |
|
17bdd79a3ae1
clarify default permission change
Richard Jones <richard@users.sourceforge.net>
parents:
3904
diff
changeset
|
782 "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
|
783 completely randomised, and they'll have to visit the web interface to |
| 2409 | 784 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
|
785 via e-mail like this. |
|
1615
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
786 |
|
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
787 |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
788 E-Mail Message Content |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
789 ---------------------- |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
790 |
|
6408
ef7bc1fac35a
Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents:
6257
diff
changeset
|
791 By default Roundup only associates plain text (MIME type |
|
ef7bc1fac35a
Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents:
6257
diff
changeset
|
792 ``text/plain``) as messages for items. Any other parts of a message |
|
ef7bc1fac35a
Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents:
6257
diff
changeset
|
793 are associated as downloadable files. If no plain text part is found, |
|
ef7bc1fac35a
Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents:
6257
diff
changeset
|
794 the message is rejected. The tracker can be configured to enable |
|
ef7bc1fac35a
Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents:
6257
diff
changeset
|
795 ``convert_htmltotext``. If this is enabled, an email with an HTML |
|
ef7bc1fac35a
Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents:
6257
diff
changeset
|
796 message (MIME type ``text/html``) and no ``text/plain`` part will be |
|
ef7bc1fac35a
Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents:
6257
diff
changeset
|
797 accepted. The first HTML part will be converted to text and used as |
|
ef7bc1fac35a
Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents:
6257
diff
changeset
|
798 the message for the item. Subsequent parts will be treated as |
|
ef7bc1fac35a
Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents:
6257
diff
changeset
|
799 attachments. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
800 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
801 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
|
802 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
803 * 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
|
804 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
|
805 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
|
806 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
|
807 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
|
808 * 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
|
809 subpart and ignore the other parts. |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
810 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
811 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
|
812 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
|
813 ``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
|
814 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
815 Message summary |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
816 ~~~~~~~~~~~~~~~ |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
817 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
818 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
|
819 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
|
820 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
|
821 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
|
822 "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
|
823 becomes the summary of the message. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
824 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
825 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
826 Address handling |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
827 ---------------- |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
828 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
829 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
|
830 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
|
831 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
|
832 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
|
833 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
|
834 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
|
835 and a username equal to the address. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
836 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
837 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
|
838 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
|
839 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
840 ``ADD_AUTHOR_TO_NOSY`` |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
841 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
|
842 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
|
843 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
|
844 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
|
845 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
846 ``ADD_RECIPIENTS_TO_NOSY`` |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
847 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
|
848 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
|
849 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
|
850 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
|
851 |
|
5045
a46d5d0fd5f8
Fix issue1615201: Added a new configuration option EMAIL_KEEP_REAL_FROM
Peter Funk <pf@artcom-gmbh.de>
parents:
4929
diff
changeset
|
852 Some organisations might prefer to have someone moderate emails before |
|
7064
3359dc1dabb0
Add OAuth authentication to the mailgw script
Ralf Schlatterbeck <rsc@runtux.com>
parents:
7048
diff
changeset
|
853 they are delivered into Roundup. Those might want to set the |
|
5045
a46d5d0fd5f8
Fix issue1615201: Added a new configuration option EMAIL_KEEP_REAL_FROM
Peter Funk <pf@artcom-gmbh.de>
parents:
4929
diff
changeset
|
854 configuration option ``EMAIL_KEEP_REAL_FROM`` to ``'yes'`` to avoid |
|
a46d5d0fd5f8
Fix issue1615201: Added a new configuration option EMAIL_KEEP_REAL_FROM
Peter Funk <pf@artcom-gmbh.de>
parents:
4929
diff
changeset
|
855 having the moderators address appearing as the creator of issues. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
856 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
857 Nosy List |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
858 ~~~~~~~~~ |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
859 |
| 1228 | 860 Roundup watches for additions to the "messages" property of items. |
| 861 | |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
862 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
|
863 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
|
864 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
|
865 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
|
866 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
|
867 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
|
868 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
869 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
|
870 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
|
871 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
|
872 |
|
8171
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
873 .. _`RPN`: https://en.wikipedia.org/wiki/Reverse_Polish_notation |