Mercurial > p > roundup > code

comparison doc/user_guide.stx @ 633:7875cd9af1cb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
documentation in structured text source form
author Richard Jones <richard@users.sourceforge.net>
date Thu, 21 Feb 2002 06:22:00 +0000
parents
children
comparison
equal deleted inserted replaced
632:71bf8f97fe30 633:7875cd9af1cb
1 User Guide
2 ==========
3
4 Command Line Tool
5 -----------------
6
7 Usage: ``roundup-admin [-i instance home] [-u login] [-c] <command> <arguments>``
8
9 Options:
10
11 -i instance home specify the issue tracker "home directory" to administer
12 -u the ``user[:password]`` to use for commands
13 -c when outputting lists of data, comma-separate them
14
15 +-----------------------------------------------------------------------------+
16 | Command Help |
17 +=============+===============================================================+
18 |commit |Usage: commit |
19 | |The changes made during an interactive session are not |
20 | |automatically written to the database - they must be committed |
21 | |using this command. |
22 | | |
23 | |One-off commands on the command-line are automatically |
24 | |committed if they are successful. |
25 +-------------+---------------------------------------------------------------+
26 |create |Usage: create classname property=value ... |
27 | |This creates a new entry of the given class using the property |
28 | |name=value arguments provided on the command line after the |
29 | |"create" command. |
30 +-------------+---------------------------------------------------------------+
31 |display |Usage: display designator |
32 | |This lists the properties and their associated values for the |
33 | |given node. |
34 +-------------+---------------------------------------------------------------+
35 |export |Usage: export class[,class] destination dir |
36 | |This action exports the current data from the database into |
37 | |tab-separated-value files that are placed in the nominated |
38 | |destination |
39 | |directory. The journals are not exported. |
40 +-------------+---------------------------------------------------------------+
41 |find |Usage: find classname propname=value ... |
42 | |Find the nodes of the given class with a given link property |
43 | |value. The |
44 | |value may be either the nodeid of the linked node, or its key |
45 | |value. |
46 +-------------+---------------------------------------------------------------+
47 |get |Usage: get property designator[,designator]* |
48 | |Retrieves the property value of the nodes specified by the |
49 | |designators. |
50 +-------------+---------------------------------------------------------------+
51 |help |Usage: help topic |
52 | |commands -- list commands |
53 | |x -- help specific to a command |
54 | |initopts -- init command options |
55 | |all -- all available help |
56 +-------------+---------------------------------------------------------------+
57 |history |Usage: history designator |
58 | |Lists the journal entries for the node identified by the |
59 | |designator. |
60 +-------------+---------------------------------------------------------------+
61 |import |Usage: import class file |
62 | |The file must define the same properties as the class |
63 | |(including having |
64 | |a "header" line with those property names.) The new nodes are |
65 | |added to |
66 | |the existing database - if you want to create a new database |
67 | |using the |
68 | |imported data, then create a new database (or, tediously, |
69 | |retire all |
70 | |the old data.) |
71 +-------------+---------------------------------------------------------------+
72 |initialise |Usage: initialise [template [backend [admin password]]] |
73 | |The command will prompt for the instance home directory (if not|
74 | |supplied |
75 | |through INSTANCE HOME or the -i option. The template, backend |
76 | |and admin |
77 | |password may be specified on the command-line as arguments, in |
78 | |that |
79 | |order. |
80 | | |
81 | |See also initopts help. |
82 +-------------+---------------------------------------------------------------+
83 |list |Usage: list classname [property] |
84 | |Lists all instances of the given class. If the property is not |
85 | |specified, the "label" property is used. The label property is|
86 | |tried |
87 | |in order: the key, "name", "title" and then the first property,|
88 | |alphabetically. |
89 +-------------+---------------------------------------------------------------+
90 |retire |Usage: retire designator[,designator]* |
91 | |This action indicates that a particular node is not to be |
92 | |retrieved by |
93 | |the list or find commands, and its key value may be re-used. |
94 +-------------+---------------------------------------------------------------+
95 |rollback |Usage: rollback |
96 | |The changes made during an interactive session are not |
97 | |automatically written to the database - they must be committed |
98 | |manually. This command undoes all those changes, so a commit |
99 | |immediately after would make no changes to the database. |
100 +-------------+---------------------------------------------------------------+
101 |set |Usage: set designator[,designator]* propname=value ... |
102 | |Sets the property to the value for all designators given. |
103 +-------------+---------------------------------------------------------------+
104 |specification|Usage: specification classname |
105 | |This lists the properties for a given class. |
106 +-------------+---------------------------------------------------------------+
107 |table |Usage: table classname [property[,property]*] |
108 | |Lists all instances of the given class. If the properties are |
109 | |not |
110 | |specified, all properties are displayed. By default, the column|
111 | |widths |
112 | |are the width of the property names. The width may be |
113 | |explicitly defined |
114 | |by defining the property as "name:width". For example:: |
115 | | |
116 | | roundup> table priority id,name:10 |
117 | | Id Name |
118 | | 1 fatal-bug |
119 | | 2 bug |
120 | | 3 usability |
121 | | 4 feature |
122 +-------------+---------------------------------------------------------------+
123
124
125 All commands (except help) require an instance specifier. This is just the path to
126 the roundup instance you're working with. A roundup instance is where roundup
127 keeps the database and configuration file that defines an issue tracker. It may be
128 thought of as the issue tracker's "home directory". It may be specified in the
129 environment variable ``ROUNDUP_INSTANCE`` or on the command line as "``-i instance``".
130
131 A designator is a classname and a nodeid concatenated, eg. bug1, user10, ...
132 Property values are represented as strings in command arguments and in the printed
133 results:
134
135 - Strings are, well, strings.
136 - Password values will display as their encoded value.
137 - Date values are printed in the full date format in the local time zone,
138 and accepted in the full format or any of the partial formats explained
139 below.::
140
141 Input of... Means...
142 "2000-04-17.03:45" 2000-04-17.08:45:00
143 "2000-04-17" 2000-04-17.00:00:00
144 "01-25" yyyy-01-25.00:00:00
145 "08-13.22:13" yyyy-08-14.03:13:00
146 "11-07.09:32:43" yyyy-11-07.14:32:43
147 "14:25" yyyy-mm-dd.19:25:00
148 "8:47:11" yyyy-mm-dd.13:47:11
149 "." "right now"
150
151 - Link values are printed as node designators. When given as an argument,
152 node designators and key strings are both accepted.
153 - Multilink values are printed as lists of node designators joined by
154 commas. When given as an argument, node designators and key strings are
155 both accepted; an empty string, a single node, or a list of nodes joined
156 by commas is accepted.
157
158 When multiple nodes are specified to the roundup get or roundup set commands, the
159 specified properties are retrieved or set on all the listed nodes. When multiple
160 results are returned by the roundup get or roundup find commands, they are printed
161 one per line (default) or joined by commas (with the "``-c``" option).
162
163 Where the command changes data, a login name/password is required. The login may
164 be specified as either "``name``" or "``name:password``".
165
166 - ``ROUNDUP_LOGIN`` environment variable
167 - the "``-u``" command-line option
168
169 If either the name or password is not supplied, they are obtained from the
170 command-line.
171
172
173 Web Interface
174 -------------
175
176 Index views may be modified by the following arguments:
177
178 +-----------+--------------------------------------------------------------+
179 | :sort | sort by prop name, optionally preceeded with '-' |
180 | | to give descending or nothing for ascending sorting. |
181 +-----------+--------------------------------------------------------------+
182 | :group | group by prop name, optionally preceeded with '-' or |
183 | | to sort in descending or nothing for ascending order. |
184 +-----------+--------------------------------------------------------------+
185 | :filter | selects which props should be displayed in the filter |
186 | | section. Default is all. |
187 +-----------+--------------------------------------------------------------+
188 | :columns | selects the columns that should be displayed. |
189 | | Default is all. |
190 +-----------+--------------------------------------------------------------+
191 | propname | selects the values the node properties given by propname |
192 | | must have (very basic search/filter). |
193 +-----------+--------------------------------------------------------------+
194
195 Not sure what to put in here...
196
197 E-Mail Gateway
198 --------------
199
200 Performing Actions
201 ~~~~~~~~~~~~~~~~~~
202
203 The subject line of the incoming message is examined to determine whether the
204 message is an attempt to create a new item or to discuss an existing item. A
205 designator enclosed in square brackets is sought as the first thing on the
206 subject line (after skipping any "Fwd:" or "Re:" prefixes).
207 If an item designator (class name and id number) is found there, the newly
208 created "msg" node is added to the "messages" property for that item, and any
209 new "file" nodes are added to the "files" property for the item.
210 If just an item class name is found there, we attempt to create a new item of
211 that class with its "messages" property initialized to contain the new "msg"
212 node and its "files" property initialized to contain any new "file" nodes.
213
214 Setting Properties
215 ~~~~~~~~~~~~~~~~~~
216
217 The e-mail interface also provides a simple way to set properties on items. At
218 the end of the subject line, propname=value pairs can be specified in square
219 brackets, using the same conventions as for the roundup set shell command.
220 explanatory message given in the exception.
221
222 Message content
223 ~~~~~~~~~~~~~~~
224
225 Incoming messages are examined for multiple parts:
226
227 * In a multipart/mixed message or part, each subpart is extracted and
228 examined. The text/plain subparts are assembled to form the textual body
229 of the message, to be stored in the file associated with a "msg" class
230 node. Any parts of other types are each stored in separate files and
231 given "file" class nodes that are linked to the "msg" node.
232 * In a multipart/alternative message or part, we look for a text/plain
233 subpart and ignore the other parts.
234
235 Message summary
236 :::::::::::::::
237
238 The "summary" property on message nodes is taken from the first non-quoting
239 section in the message body. The message body is divided into sections by blank
240 lines. Sections where the second and all subsequent lines begin with a ">" or
241 "|" character are considered "quoting sections". The first line of the first
242 non-quoting section becomes the summary of the message.
243
244 Address handling
245 ~~~~~~~~~~~~~~~~
246
247 All of the addresses in the To: and Cc: headers of the incoming message are
248 looked up among the user nodes, and the corresponding users are placed in the
249 "recipients" property on the new "msg" node. The address in the From: header
250 similarly determines the "author" property of the new "msg" node. The default
251 handling for addresses that don't have corresponding users is to create new
252 users with no passwords and a username equal to the address. (The web interface
253 does not permit logins for users with no passwords.) If we prefer to reject
254 mail from outside sources, we can simply register an auditor on the "user"
255 class that prevents the creation of user nodes with no passwords.
256
257 Triggers
258 ~~~~~~~~
259
260 Both cases may trigger detectors (in the first case we are calling the set()
261 method to add the message to the item's spool; in the second case we are
262 calling the create() method to create a new node). If an auditor raises an
263 exception, the original message is bounced back to the sender with the
264
265 Nosy Lists
266 ::::::::::
267
268 A standard detector is provided that watches for additions to the "messages"
269 property. When a new message is added, the detector sends it to all the users
270 on the "nosy" list for the item that are not already on the "recipients" list
271 of the message. Those users are then appended to the "recipients" property on
272 the message, so multiple copies of a message are never sent to the same user.
273 The journal recorded by the hyperdatabase on the "recipients" property then
274 provides a log of when the message was sent to whom.
275
276
Roundup Issue Tracker: http://roundup-tracker.org/