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