Mercurial > p > roundup > code

annotate doc/user_guide.txt @ 834:568eed5fb4fd

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