Skip to content

Commit 9d57cd7

Browse files
author
Richard Jones
committed
more doc
1 parent 998e3c2 commit 9d57cd7

File tree

2 files changed

+112
-50
lines changed

2 files changed

+112
-50
lines changed

‎doc/design.txt‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1187,8 +1187,6 @@ See the `customisation`_ documentation for the complete list.
11871187
Index Views
11881188
~~~~~~~~~~~
11891189

1190-
XXX The following needs to be clearer
1191-
11921190
An index view contains two sections: a filter section
11931191
and an index section.
11941192
The filter section provides some widgets for selecting

‎doc/user_guide.txt‎

Lines changed: 112 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
User Guide
33
==========
44

5-
:Version: $Revision: 1.17 $
5+
:Version: $Revision: 1.18 $
66

77
.. contents::
88

@@ -37,6 +37,102 @@ The last is usually only used by administrators. Most users will use the web
3737
and email interfaces. All three are explained below.
3838

3939

40+
Searching in your Tracker
41+
-------------------------
42+
43+
All interfaces to your tracker use the same format for sepcifying search
44+
parameters.
45+
46+
String and Numeric properties
47+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
48+
49+
These fields just take a simple text value, like ``topic=It's broken``.
50+
51+
Boolean properties
52+
~~~~~~~~~~~~~~~~~~
53+
54+
These fields take a value which indicates "yes"/"no", "true"/"false",
55+
"1"/"0" or "on"/"off".
56+
57+
Constrained (link and multilink) properties
58+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
59+
60+
Fields like "Assigned To" and "Topics" hold references to items in other
61+
classes ("user" and "keyword" in those two cases.)
62+
63+
We use a comma-separated list of values to indicated which values of "user"
64+
or "keyword" are interesting. The values may be either numeric ids or the
65+
names of items. The special value "-1" may be used to match items where the
66+
property is not set. For example, the following searches on the issues:
67+
68+
``assignedto=richard,george``
69+
match issues which are assigned to richard or george.
70+
``assignedto=-1``
71+
match issues that are not assigned to a user.
72+
``assignedto=2,3,40``
73+
match issues that are assigned to users 2, 3 or 40.
74+
``topic=user interface``
75+
match issues with the keyword "user interface" in their topic list
76+
``topic=web interface,email interface``
77+
match issues with the keyword "web interface" or "email interface" in
78+
their topic list
79+
``topic=-1``
80+
match issues with no topics set
81+
82+
83+
Date properties
84+
~~~~~~~~~~~~~~~
85+
86+
Some fields in the search page (e.g. "Activity" or "Creation date") hold
87+
dates. A plain date entered as a search field will match that date exactly
88+
in the database. We may also accept ranges of dates. You can specify range
89+
of dates in one of two formats:
90+
91+
1. English syntax::
92+
93+
[[From] <value>][ To <value>]
94+
95+
Keywords "From" and "To" are case insensitive. Keyword "From" is optional.
96+
97+
2. "Geek" syntax::
98+
99+
[<value>][; <value>]
100+
101+
Either first or second ``<value>`` can be omitted in both syntaxes.
102+
103+
For example, if you enter string "from 9:00" to "Creation date" field,
104+
roundup will find all issues, that were created today since 9 AM.
105+
106+
Searching of "-2m; -1m" on activity field gives you issues which were
107+
active between period of time since 2 months up-till month ago.
108+
109+
Other possible examples (consider local time is Sat Mar 8 22:07:48 2003)::
110+
111+
>>> Range("from 2-12 to 4-2")
112+
<Range from 2003-02-12.00:00:00 to 2003-04-02.00:00:00>
113+
114+
>>> Range("18:00 TO +2m")
115+
<Range from 2003-03-08.18:00:00 to 2003-05-08.20:07:48>
116+
117+
>>> Range("12:00")
118+
<Range from 2003-03-08.12:00:00 to None>
119+
120+
>>> Range("tO +3d")
121+
<Range from None to 2003-03-11.20:07:48>
122+
123+
>>> Range("2002-11-10; 2002-12-12")
124+
<Range from 2002-11-10.00:00:00 to 2002-12-12.00:00:00>
125+
126+
>>> Range("; 20:00 +1d")
127+
<Range from None to 2003-03-09.20:00:00>
128+
129+
130+
Interval properties
131+
~~~~~~~~~~~~~~~~~~~
132+
133+
XXX explain...
134+
135+
40136
Web Interface
41137
=============
42138

@@ -103,56 +199,13 @@ occurs) you'll get something like:
103199
Searching Page
104200
--------------
105201

106-
XXX: some information about how searching works
107-
108-
Some fields in the search page (e.g. "Activity" or "Creation date") accept
109-
ranges of dates. You can specify range of dates in one of two formats:
110-
111-
1. Native english syntax::
112-
113-
[[From] <value>][ To <value>]
114-
115-
Keywords "From" and "To" are case insensitive. Keyword "From" is optional.
116-
117-
2. "Geek" syntax::
118-
119-
[<value>][; <value>]
120-
121-
Either first or second ``<value>`` can be omitted in both syntaxes.
122-
123-
For example:
124-
125-
if you enter string "from 9:00" to "Creation date" field, roundup
126-
will find all issues, that were created today since 9 AM.
127-
128-
Searching of "-2m; -1m" on activity field gives you issues, which were
129-
active between period of time since 2 months up-till month ago.
130-
131-
Other possible examples (consider local time is Sat Mar 8 22:07:48 EET 2003):
132-
133-
>>> Range("from 2-12 to 4-2")
134-
<Range from 2003-02-12.00:00:00 to 2003-04-02.00:00:00>
135-
136-
>>> Range("18:00 TO +2m")
137-
<Range from 2003-03-08.18:00:00 to 2003-05-08.20:07:48>
138-
139-
>>> Range("12:00")
140-
<Range from 2003-03-08.12:00:00 to None>
141-
142-
>>> Range("tO +3d")
143-
<Range from None to 2003-03-11.20:07:48>
144-
145-
>>> Range("2002-11-10; 2002-12-12")
146-
<Range from 2002-11-10.00:00:00 to 2002-12-12.00:00:00>
147-
148-
>>> Range("; 20:00 +1d")
149-
<Range from None to 2003-03-09.20:00:00>
150-
202+
see `searching in your tracker`_ for an explanation of how the searching
203+
works.
151204

152205
Under the covers
153-
----------------
206+
~~~~~~~~~~~~~~~~
154207

155-
Index views may be modified by the following arguments:
208+
The searching page converts your selections into the following arguments:
156209

157210
========== =============================================================
158211
Argument Description
@@ -169,6 +222,17 @@ propname selects the values the item properties given by propname
169222
must have (very basic search/filter).
170223
========== =============================================================
171224

225+
You may manually write URLS that contain these arguments, like so (whitespace
226+
has been added for clarity)::
227+
228+
/issue?status=unread,in-progress,resolved&
229+
topic=security,ui&
230+
:group=priority&
231+
:sort=-activity&
232+
:filters=status,topic&
233+
:columns=title,status,fixer
234+
235+
172236
Access Controls
173237
---------------
174238

0 commit comments

Comments
 (0)