Mercurial > p > roundup > code
annotate doc/user_guide.txt @ 8506:b6c6891754e9
bug: fix mis-commit of perf tests and crash fix for setTranslation
The commit included more than it should have.
It included some memory dump code that is not part of production.
Also removed WIP for fixing crash bug when translation unable to
create .mo file - issue2551405
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Thu, 25 Dec 2025 12:14:53 -0500 |
| parents | b99e76e76496 |
| children |
| 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 |
|
8286
6445e63bb423
feat(web) - Use native number type input for Number() and Integer().
John Rouillard <rouilj@ieee.org>
parents:
8285
diff
changeset
|
134 ``123``, ``+123``, ``-123``. Exponents are not supported. Your browser |
|
8300
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8286
diff
changeset
|
135 may show an up/down arrow spinner to change the value. |
| 1575 | 136 |
| 137 Boolean properties | |
| 138 ~~~~~~~~~~~~~~~~~~ | |
| 139 | |
| 140 These fields take a value which indicates "yes"/"no", "true"/"false", | |
| 141 "1"/"0" or "on"/"off". | |
| 142 | |
|
1588
1ac46e7e4150
more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents:
1575
diff
changeset
|
143 |
| 1575 | 144 Constrained (link and multilink) properties |
| 145 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 146 | |
|
3904
91008ec8f9a0
retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents:
3756
diff
changeset
|
147 Fields like "Assigned To" and "Keywords" hold references to items in other |
| 1575 | 148 classes ("user" and "keyword" in those two cases.) |
| 149 | |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
150 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
|
151 To" field. |
|
1588
1ac46e7e4150
more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents:
1575
diff
changeset
|
152 |
|
1ac46e7e4150
more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents:
1575
diff
changeset
|
153 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
|
154 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
|
155 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
|
156 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
|
157 not set. For example, the following searches on the issues: |
| 1575 | 158 |
| 159 ``assignedto=richard,george`` | |
| 160 match issues which are assigned to richard or george. | |
| 161 ``assignedto=-1`` | |
| 162 match issues that are not assigned to a user. | |
| 163 ``assignedto=2,3,40`` | |
| 164 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
|
165 ``keyword=user interface`` |
|
91008ec8f9a0
retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents:
3756
diff
changeset
|
166 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
|
167 ``keyword=web interface,e-mail interface`` |
|
3529
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
168 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
|
169 their keyword list |
|
91008ec8f9a0
retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents:
3756
diff
changeset
|
170 ``keyword=-1`` |
|
91008ec8f9a0
retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents:
3756
diff
changeset
|
171 match issues with no keywords set |
| 1575 | 172 |
|
7971
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
173 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
|
174 helper (also called classhelper) available by clicking on a link |
| 8032 | 175 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
|
176 Classhelper`_ for details. |
| 1575 | 177 |
| 178 Date properties | |
| 179 ~~~~~~~~~~~~~~~ | |
| 180 | |
|
8300
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8286
diff
changeset
|
181 Date properties can be shown using a native HTML date (or |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8286
diff
changeset
|
182 datetime-local) element by setting ``use_browser_date_input=yes`` in |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8286
diff
changeset
|
183 section ``[web]`` in ``config.ini``. This provides a calendar button for |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8286
diff
changeset
|
184 choosing the date. The date is shown in the normal format for your |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8286
diff
changeset
|
185 location. |
|
8285
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
186 |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
187 Native date inputs do not allow the use of partial forms as |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
188 defined below. For this reason, you may edit a date/time |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
189 stamp directly. |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
190 |
|
2750
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
191 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
|
192 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
|
193 (``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
|
194 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
|
195 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
|
196 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
|
197 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
|
198 |
|
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
199 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
|
200 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
|
201 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
|
202 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
|
203 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
|
204 ``yyyy`` is the current year, ``mm`` is the current month, and ``dd`` is |
|
8285
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
205 the current day of the month and the local timezone is GMT-5. |
|
2750
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
206 |
|
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
207 - "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
|
208 - "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
|
209 - "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
|
210 - "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
|
211 - "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
|
212 - "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
|
213 - "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
|
214 - 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
|
215 |
|
8285
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
216 The native date input doesn't allow copy or paste. Roundup |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
217 enhances the native date field. If you double-click on a native |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
218 date field, it changes to a text input mode with the date already |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
219 selected. You can use control-C to copy the date or control-V to |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
220 paste into the field. Double-clicking also lets you add seconds |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
221 in a date-time value if you need to. |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
222 |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
223 It will switch back to a date input and save the value when: |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
224 |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
225 - you move to another field using the mouse or the Tab key. |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
226 - you press enter/return (press return again if you want to |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
227 submit the form). |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
228 |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
229 If you press Escape, it will restore the original value and |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
230 change back to a date input. |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
231 |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
232 When using native date elements in text input mode, the date |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
233 looks like a full data with ``T`` replacing ``.``. If the ``T`` |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
234 is missing, the native date elements will not recognize the value |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
235 as a date. |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
236 |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
237 There is no support for activating text mode using the |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
238 keyboard. Tablet/touch support is mixed. Chrome supports |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
239 double-tap to activate text mode input. Firefox does not. |
|
2750
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
240 |
|
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
241 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
|
242 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
|
243 specify range of dates in one of two formats: |
| 1575 | 244 |
| 245 1. English syntax:: | |
| 246 | |
|
1599
cc96bf971b33
extended date syntax to make range searches even more useful
Andrey Lebedev <kedder@users.sourceforge.net>
parents:
1596
diff
changeset
|
247 [From <value>][To <value>] |
| 1575 | 248 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
249 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
|
250 optional. |
| 1575 | 251 |
| 252 2. "Geek" syntax:: | |
| 253 | |
|
1599
cc96bf971b33
extended date syntax to make range searches even more useful
Andrey Lebedev <kedder@users.sourceforge.net>
parents:
1596
diff
changeset
|
254 [<value>];[<value>] |
| 1575 | 255 |
| 256 Either first or second ``<value>`` can be omitted in both syntaxes. | |
| 257 | |
| 258 For example, if you enter string "from 9:00" to "Creation date" field, | |
| 259 roundup will find all issues, that were created today since 9 AM. | |
| 260 | |
|
2750
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
261 The ``<value>`` may also be an interval, as described in the next section. |
| 1575 | 262 Searching of "-2m; -1m" on activity field gives you issues which were |
| 263 active between period of time since 2 months up-till month ago. | |
| 264 | |
| 2910 | 265 Other possible examples (consider local time is 2003-03-08.22:07:48): |
| 1575 | 266 |
|
2750
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
267 - "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
|
268 <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
|
269 - "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
|
270 <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
|
271 - "12:00;" means |
|
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
272 <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
|
273 - "tO +3d" means |
|
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
274 <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
|
275 - "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
|
276 <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
|
277 - "; 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
|
278 <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
|
279 - "2003" means |
|
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
280 <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
|
281 - "2003-04" means |
|
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
282 <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
|
283 |
| 1575 | 284 |
| 285 Interval properties | |
| 286 ~~~~~~~~~~~~~~~~~~~ | |
| 287 | |
|
2750
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
288 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
|
289 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
|
290 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
|
291 may not). |
| 1575 | 292 |
|
2750
a97bbd72a643
copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents:
2409
diff
changeset
|
293 - "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
|
294 - "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
|
295 - "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
|
296 - "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
|
297 - "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
|
298 - "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
|
299 - "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
|
300 |
| 1575 | 301 |
|
2138
f76d1642014a
doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents:
2136
diff
changeset
|
302 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
|
303 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
f76d1642014a
doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents:
2136
diff
changeset
|
304 |
|
f76d1642014a
doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents:
2136
diff
changeset
|
305 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
|
306 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
|
307 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
|
308 |
|
f76d1642014a
doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents:
2136
diff
changeset
|
309 |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
310 Web Interface |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
311 ============= |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
312 |
| 2409 | 313 .. note:: |
| 314 This document contains screenshots of the default look and feel. | |
| 315 Your site may have a slightly (or very) different look, but the | |
| 316 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
|
317 |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
318 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
|
319 |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
320 1. `lists of items`_, |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
321 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
|
322 3. `searching page`_. |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
323 |
|
7278
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
324 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
|
325 `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
|
326 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
|
327 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
328 .. _REST: rest.html |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
329 .. _XMLRPC: xmlrpc.html |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
330 |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
331 Lists of Items |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
332 -------------- |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
333 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
334 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
|
335 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
|
336 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
|
337 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
338 .. 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
|
339 :width: 675 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
340 :height: 450 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
341 :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
|
342 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
|
343 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
344 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
|
345 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
|
346 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
|
347 the tracker. |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
348 |
|
6257
f9c059921ccc
Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents:
6174
diff
changeset
|
349 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
|
350 you to: |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
351 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
352 .. 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
|
353 :width: 675 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
354 :height: 450 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
355 :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
|
356 password etc. |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
357 |
|
6257
f9c059921ccc
Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents:
6174
diff
changeset
|
358 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
|
359 password. Resetting your password takes you to: |
|
f9c059921ccc
Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents:
6174
diff
changeset
|
360 |
|
f9c059921ccc
Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents:
6174
diff
changeset
|
361 .. 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
|
362 :width: 605 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
363 :height: 495 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
364 :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
|
365 trigger a password reset when submitted. |
|
6257
f9c059921ccc
Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents:
6174
diff
changeset
|
366 |
|
f9c059921ccc
Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents:
6174
diff
changeset
|
367 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
|
368 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
|
369 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
|
370 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
|
371 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
|
372 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
373 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
|
374 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
375 .. 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
|
376 :width: 182 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
377 :height: 399 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
378 :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
|
379 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
|
380 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
381 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
|
382 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
383 .. 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
|
384 :width: 667 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
385 :height: 558 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
386 :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
|
387 address and it also shows activity done by the user. |
| 1228 | 388 |
| 389 Display, edit or entry of an item | |
| 390 --------------------------------- | |
| 391 | |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
392 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
|
393 will take you to: |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
394 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
395 .. 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
|
396 :width: 648 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
397 :height: 277 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
398 :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
|
399 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
|
400 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
|
401 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
402 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
|
403 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
|
404 |
|
3756
068b3d7d4279
images for user guide
Richard Jones <richard@users.sourceforge.net>
parents:
3754
diff
changeset
|
405 .. 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
|
406 :width: 650 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
407 :height: 535 |
|
e2f257ef737f
alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents:
7252
diff
changeset
|
408 :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
|
409 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
|
410 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
|
411 |
|
6469
98082155ffea
Document "Make a copy" link
John Rouillard <rouilj@ieee.org>
parents:
6408
diff
changeset
|
412 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
|
413 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
|
414 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
|
415 |
| 1228 | 416 Searching Page |
| 417 -------------- | |
| 418 | |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
419 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
|
420 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
|
421 |
|
1ac46e7e4150
more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents:
1575
diff
changeset
|
422 |
|
2136
ee3cf6a44f29
queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents:
2028
diff
changeset
|
423 Saving queries |
|
ee3cf6a44f29
queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents:
2028
diff
changeset
|
424 ~~~~~~~~~~~~~~ |
|
ee3cf6a44f29
queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents:
2028
diff
changeset
|
425 |
|
ee3cf6a44f29
queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents:
2028
diff
changeset
|
426 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
|
427 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
|
428 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
|
429 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
|
430 |
|
ee3cf6a44f29
queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents:
2028
diff
changeset
|
431 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
|
432 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
|
433 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
|
434 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
|
435 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
|
436 |
|
ee3cf6a44f29
queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents:
2028
diff
changeset
|
437 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
|
438 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
|
439 above. |
|
ee3cf6a44f29
queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents:
2028
diff
changeset
|
440 |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
441 |
|
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
442 Under the covers |
| 1575 | 443 ~~~~~~~~~~~~~~~~ |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
444 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
445 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
|
446 arguments: |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
447 |
|
3036
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
448 ============ ============================================================= |
|
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
449 Argument Description |
|
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
450 ============ ============================================================= |
| 5827 | 451 @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
|
452 descending or nothing for ascending sorting. The sort |
|
790363e96852
Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents:
3650
diff
changeset
|
453 argument can have several props separated with comma. |
| 5827 | 454 @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
|
455 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
|
456 argument can have several props separated with comma. |
|
3036
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
457 @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
|
458 all. |
|
3036
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
459 @filter indicates which properties are being used in filtering. |
|
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
460 Default is none. |
|
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
461 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
|
462 have (very basic search/filter). |
|
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
463 @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
|
464 etc) |
|
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
465 ============ ============================================================= |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
466 |
|
7406
8bc4246480bf
Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
7279
diff
changeset
|
467 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
|
468 (whitespace has been added for clarity):: |
| 1575 | 469 |
| 470 /issue?status=unread,in-progress,resolved& | |
|
3904
91008ec8f9a0
retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents:
3756
diff
changeset
|
471 keyword=security,ui& |
|
3696
790363e96852
Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents:
3650
diff
changeset
|
472 @group=priority,-status& |
|
3036
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
473 @sort=-activity& |
|
3904
91008ec8f9a0
retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents:
3756
diff
changeset
|
474 @filters=status,keyword& |
|
3036
8fa6b5747a53
updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents:
2910
diff
changeset
|
475 @columns=title,status,fixer |
| 1575 | 476 |
|
6592
828e2eaee7cd
Document full text search
John Rouillard <rouilj@ieee.org>
parents:
6586
diff
changeset
|
477 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
|
478 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
|
479 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
|
480 stoplist is used to remove common words like "with", "and" |
|
828e2eaee7cd
Document full text search
John Rouillard <rouilj@ieee.org>
parents:
6586
diff
changeset
|
481 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
|
482 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
|
483 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
|
484 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
|
485 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
|
486 |
|
828e2eaee7cd
Document full text search
John Rouillard <rouilj@ieee.org>
parents:
6586
diff
changeset
|
487 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
|
488 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
|
489 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
|
490 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
|
491 the `documentation for configuring the native-fts`_ backend to find |
|
2eec7a500333
Doc updates for indexers.
John Rouillard <rouilj@ieee.org>
parents:
6592
diff
changeset
|
492 the supported format and features. |
|
2eec7a500333
Doc updates for indexers.
John Rouillard <rouilj@ieee.org>
parents:
6592
diff
changeset
|
493 |
|
2eec7a500333
Doc updates for indexers.
John Rouillard <rouilj@ieee.org>
parents:
6592
diff
changeset
|
494 .. _`documentation for configuring the native-fts`: admin_guide.html#configuring-native-fts-full-text-search |
| 1575 | 495 |
|
8171
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
496 Advanced Searching with Property Expressions |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
497 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
498 |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
499 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
|
500 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
|
501 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
|
502 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
|
503 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
|
504 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
|
505 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
|
506 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
|
507 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
|
508 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
|
509 |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
510 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
|
511 |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
512 * 'not' is represented by -2 |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
513 * 'and' is represented by -3 |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
514 * 'or' is represented by -4 |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
515 |
|
8173
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
516 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
|
517 ``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
|
518 ``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
|
519 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
|
520 |
|
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
521 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
|
522 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
|
523 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
|
524 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
|
525 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
|
526 |
|
8173
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
527 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
|
528 |
|
6a58acc3f39f
docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8171
diff
changeset
|
529 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
|
530 |
|
6a58acc3f39f
docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8171
diff
changeset
|
531 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
|
532 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
|
533 form:: |
|
8172
6a58acc3f39f
docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8171
diff
changeset
|
534 |
|
6a58acc3f39f
docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8171
diff
changeset
|
535 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
|
536 |
|
8173
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
537 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
|
538 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
|
539 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
|
540 expressions a bit easier. |
|
079958914ed7
doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents:
8172
diff
changeset
|
541 |
|
8253
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
542 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
|
543 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
|
544 ``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
|
545 following error:: |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
546 |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
547 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
|
548 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
|
549 |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
550 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
|
551 (``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
|
552 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
|
553 was given. |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
554 |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
555 Another error message:: |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
556 |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
557 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
|
558 -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
|
559 |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
560 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
|
561 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
|
562 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
|
563 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
|
564 ``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
|
565 |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
566 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
|
567 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
|
568 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
|
569 |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
570 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
|
571 -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
|
572 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
|
573 2))] |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
574 |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
575 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
|
576 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
|
577 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
|
578 |
|
cae1bbf2536b
fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents:
8173
diff
changeset
|
579 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
|
580 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
|
581 |
|
7971
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
582 Using the Classhelper |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
583 --------------------- |
|
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 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
|
586 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
|
587 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
|
588 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
|
589 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
|
590 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
|
591 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
|
592 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
593 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
|
594 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
|
595 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
|
596 browser has disabled popup windows. |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
597 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
598 The classhelper has three parts: |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
599 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
600 1. an optional search pane |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
601 2. a selection pane |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
602 3. an accumulator pane |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
603 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
604 .. 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
|
605 :width: 675 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
606 :height: 914 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
607 :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
|
608 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
|
609 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
|
610 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
|
611 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
|
612 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
|
613 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
|
614 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
|
615 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
|
616 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
|
617 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
|
618 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
|
619 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
620 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
621 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
|
622 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
|
623 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
|
624 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
|
625 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
|
626 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
|
627 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
|
628 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
|
629 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
630 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
|
631 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
|
632 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
|
633 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
|
634 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
|
635 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
|
636 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
|
637 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
|
638 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
|
639 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
|
640 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
|
641 '<' 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
|
642 to trigger a page change. |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
643 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
644 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
|
645 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
|
646 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
|
647 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
|
648 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
|
649 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
|
650 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
|
651 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
|
652 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
|
653 the parent window. |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
654 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
655 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
|
656 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
|
657 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
|
658 hotkey (e.g. control-w). |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
659 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
660 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
|
661 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
|
662 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
|
663 |
|
fe0348bbe45b
issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents:
7406
diff
changeset
|
664 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
|
665 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
|
666 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
|
667 |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
668 Access Controls |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
669 --------------- |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
670 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
671 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
|
672 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
|
673 them. Roles can allow you to access: |
|
1317
28ae91aae74f
clarifications
Richard Jones <richard@users.sourceforge.net>
parents:
1282
diff
changeset
|
674 |
|
7406
8bc4246480bf
Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
7279
diff
changeset
|
675 - 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
|
676 - 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
|
677 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
|
678 - 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
|
679 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
|
680 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
|
681 |
|
8bc4246480bf
Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
7279
diff
changeset
|
682 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
|
683 like: |
|
1317
28ae91aae74f
clarifications
Richard Jones <richard@users.sourceforge.net>
parents:
1282
diff
changeset
|
684 |
|
28ae91aae74f
clarifications
Richard Jones <richard@users.sourceforge.net>
parents:
1282
diff
changeset
|
685 - may the user edit issues ("Edit", "issue") |
|
28ae91aae74f
clarifications
Richard Jones <richard@users.sourceforge.net>
parents:
1282
diff
changeset
|
686 - is the user allowed to use the web interface ("Web Access") |
|
28ae91aae74f
clarifications
Richard Jones <richard@users.sourceforge.net>
parents:
1282
diff
changeset
|
687 - 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
|
688 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
689 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
|
690 the customisation documentation. Examples of new access controls are: |
|
1317
28ae91aae74f
clarifications
Richard Jones <richard@users.sourceforge.net>
parents:
1282
diff
changeset
|
691 |
|
28ae91aae74f
clarifications
Richard Jones <richard@users.sourceforge.net>
parents:
1282
diff
changeset
|
692 - only managers may sign off issues as complete |
|
3529
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
693 - don't give users who register through e-mail web access |
|
1317
28ae91aae74f
clarifications
Richard Jones <richard@users.sourceforge.net>
parents:
1282
diff
changeset
|
694 - 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
|
695 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
696 E-Mail Gateway |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
697 ============== |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
698 |
|
3529
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
699 Roundup trackers may be used to facilitate e-mail conversations around |
|
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
700 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
|
701 should receive e-mail when messages are added to the issue. |
|
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
702 |
|
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
703 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
|
704 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
|
705 |
|
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
706 You may even create new issues from e-mail messages. |
|
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
707 |
|
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
708 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
|
709 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
710 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
|
711 2. `sender identification`_ using the sender of the message |
|
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
712 3. `e-mail message content`_ which is to be extracted |
|
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
713 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
|
714 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
715 |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
716 Subject-line information |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
717 ------------------------ |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
718 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
719 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
|
720 |
| 5827 | 721 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
|
722 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
|
723 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
|
724 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
|
725 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
|
726 |
|
d995ee7d49bf
issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents:
5045
diff
changeset
|
727 If the subject is ``help`` (case insensitive), the gateway responds |
| 5827 | 728 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
|
729 |
|
d995ee7d49bf
issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents:
5045
diff
changeset
|
730 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
|
731 registration confirmation. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
732 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
733 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
|
734 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
|
735 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
|
736 ``[ 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
|
737 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
|
738 we start looking for real information. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
739 |
|
7406
8bc4246480bf
Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
7279
diff
changeset
|
740 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
|
741 ``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
|
742 "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
|
743 the "files" property for the item. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
744 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
745 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
|
746 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
|
747 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
|
748 new "file" items. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
749 |
|
5056
d995ee7d49bf
issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents:
5045
diff
changeset
|
750 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
|
751 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
|
752 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
|
753 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
|
754 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
|
755 default class is created. |
|
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
756 |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
757 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
758 Setting Properties |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
759 ~~~~~~~~~~~~~~~~~~ |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
760 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
761 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
|
762 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
|
763 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
|
764 roundup set shell command. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
765 |
|
8052
d54af8964fe3
docs: fix unwanted highlighting.
John Rouillard <rouilj@ieee.org>
parents:
8032
diff
changeset
|
766 .. highlight:: text |
|
d54af8964fe3
docs: fix unwanted highlighting.
John Rouillard <rouilj@ieee.org>
parents:
8032
diff
changeset
|
767 |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
768 For example, |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
769 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
770 - setting the priority of an issue:: |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
771 |
|
4298
f6468c5e1493
Fix typo in email section of user guide, fixes issue2550607
Richard Jones <richard@users.sourceforge.net>
parents:
4036
diff
changeset
|
772 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
|
773 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
774 - adding yourself to a nosy list:: |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
775 |
|
7234
86862ed039fa
issue2551262 - make mail gateway subject prefix parsing accept spaces
John Rouillard <rouilj@ieee.org>
parents:
7093
diff
changeset
|
776 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
|
777 |
|
1282
2feb3e0a9955
included doc ideas from Bernhard Reiter
Richard Jones <richard@users.sourceforge.net>
parents:
1267
diff
changeset
|
778 - 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
|
779 |
|
7234
86862ed039fa
issue2551262 - make mail gateway subject prefix parsing accept spaces
John Rouillard <rouilj@ieee.org>
parents:
7093
diff
changeset
|
780 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
|
781 |
|
1282
2feb3e0a9955
included doc ideas from Bernhard Reiter
Richard Jones <richard@users.sourceforge.net>
parents:
1267
diff
changeset
|
782 - 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
|
783 |
|
7234
86862ed039fa
issue2551262 - make mail gateway subject prefix parsing accept spaces
John Rouillard <rouilj@ieee.org>
parents:
7093
diff
changeset
|
784 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
|
785 |
|
8052
d54af8964fe3
docs: fix unwanted highlighting.
John Rouillard <rouilj@ieee.org>
parents:
8032
diff
changeset
|
786 .. highlight:: python3 |
|
d54af8964fe3
docs: fix unwanted highlighting.
John Rouillard <rouilj@ieee.org>
parents:
8032
diff
changeset
|
787 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
788 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
|
789 stripped off. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
790 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
791 |
|
1267
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
792 Automatic Properties |
|
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
793 ~~~~~~~~~~~~~~~~~~~~ |
|
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
794 |
|
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
795 **status of new issues** |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
796 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
|
797 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
|
798 issue is defaulted to "unread". |
|
1267
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
799 |
|
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
800 **reopening of resolved issues** |
|
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
801 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
|
802 automatically reset to "chatting" to indicate new information has been |
|
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
803 received. |
|
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
804 |
|
a28dfdb6c9a5
doc refinement
Richard Jones <richard@users.sourceforge.net>
parents:
1228
diff
changeset
|
805 |
|
1615
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
806 Sender identification |
|
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
807 --------------------- |
|
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
808 |
|
3529
4fd84dcfed33
more explanation
Richard Jones <richard@users.sourceforge.net>
parents:
3036
diff
changeset
|
809 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
|
810 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
|
811 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
|
812 Guide`_ section "Users and Security" for configuration details.) |
|
17bdd79a3ae1
clarify default permission change
Richard Jones <richard@users.sourceforge.net>
parents:
3904
diff
changeset
|
813 |
|
17bdd79a3ae1
clarify default permission change
Richard Jones <richard@users.sourceforge.net>
parents:
3904
diff
changeset
|
814 .. _`Admin Guide`: admin_guide.html |
|
17bdd79a3ae1
clarify default permission change
Richard Jones <richard@users.sourceforge.net>
parents:
3904
diff
changeset
|
815 |
|
17bdd79a3ae1
clarify default permission change
Richard Jones <richard@users.sourceforge.net>
parents:
3904
diff
changeset
|
816 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
|
817 "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
|
818 completely randomised, and they'll have to visit the web interface to |
| 2409 | 819 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
|
820 via e-mail like this. |
|
1615
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
821 |
|
7b680b906417
more user docco
Richard Jones <richard@users.sourceforge.net>
parents:
1599
diff
changeset
|
822 |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
823 E-Mail Message Content |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
824 ---------------------- |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
825 |
|
6408
ef7bc1fac35a
Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents:
6257
diff
changeset
|
826 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
|
827 ``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
|
828 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
|
829 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
|
830 ``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
|
831 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
|
832 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
|
833 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
|
834 attachments. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
835 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
836 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
|
837 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
838 * 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
|
839 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
|
840 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
|
841 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
|
842 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
|
843 * 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
|
844 subpart and ignore the other parts. |
|
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 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
|
847 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
|
848 ``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
|
849 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
850 Message summary |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
851 ~~~~~~~~~~~~~~~ |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
852 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
853 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
|
854 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
|
855 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
|
856 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
|
857 "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
|
858 becomes the summary of the message. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
859 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
860 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
861 Address handling |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
862 ---------------- |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
863 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
864 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
|
865 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
|
866 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
|
867 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
|
868 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
|
869 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
|
870 and a username equal to the address. |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
871 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
872 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
|
873 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
|
874 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
875 ``ADD_AUTHOR_TO_NOSY`` |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
876 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
|
877 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
|
878 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
|
879 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
|
880 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
881 ``ADD_RECIPIENTS_TO_NOSY`` |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
882 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
|
883 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
|
884 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
|
885 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
|
886 |
|
5045
a46d5d0fd5f8
Fix issue1615201: Added a new configuration option EMAIL_KEEP_REAL_FROM
Peter Funk <pf@artcom-gmbh.de>
parents:
4929
diff
changeset
|
887 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
|
888 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
|
889 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
|
890 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
|
891 |
|
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
892 Nosy List |
|
1199
cd58a8603424
half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents:
1098
diff
changeset
|
893 ~~~~~~~~~ |
|
881
85cc6e6a94b8
better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents:
753
diff
changeset
|
894 |
| 1228 | 895 Roundup watches for additions to the "messages" property of items. |
| 896 | |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
897 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
|
898 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
|
899 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
|
900 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
|
901 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
|
902 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
|
903 |
|
1661
b9c1226cb600
Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents:
1615
diff
changeset
|
904 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
|
905 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
|
906 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
|
907 |
|
8171
188b7a549f20
docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents:
8061
diff
changeset
|
908 .. _`RPN`: https://en.wikipedia.org/wiki/Reverse_Polish_notation |