Mercurial > p > roundup > code

annotate doc/user_guide.stx @ 639:2f3e82a69eb5

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