Mercurial > p > roundup > code

annotate doc/index.html @ 475:a1a44636bace

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix breakage caused by transaction changes. Sorry for the huge checkin message - I was only intending to implement [SF#496356] but I found a number of places where things had been broken by transactions: . modified ROUNDUPDBSENDMAILDEBUG to be SENDMAILDEBUG and hold a filename for _all_ roundup-generated smtp messages to be sent to. . the transaction cache had broken the roundupdb.Class set() reactors . newly-created author users in the mailgw weren't being committed to the db Stuff that made it into CHANGES.txt (ie. the stuff I was actually working on when I found that stuff :): . [SF#496356] Use threading in messages . detectors were being registered multiple times . added tests for mailgw . much better attaching of erroneous messages in the mail gateway
author Richard Jones <richard@users.sourceforge.net>
date Wed, 02 Jan 2002 02:31:38 +0000
parents d35e51360175
children 8298fea69bc3 c242455d9b46
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1 <html><head>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2 <title>Roundup: an Issue-Tracking System for Knowledge Workers</title>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3 </head><body>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
4
461
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
5 <h1 align=center>Roundup (0.3.1)</h1>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
6 <h3 align=center>An Issue-Tracking System for Knowledge Workers</h2>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
7
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
8 <h1>Contents</h1>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
9
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
10 <ul>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
11 <li><a href="overview.html">Overview</a> (Initial submission to SC Track)
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
12 <li><a href="#installation">Installation</a>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
13 <ul>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
14 <li><a href="#requires">Prerequisites</a>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
15 <li><a href="#getting">Getting Roundup</a>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
16 <li><a href="#installing">Installing Roundup</a>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
17 </ul>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
18 <li><a href="#starting">Getting Started</a>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
19 <ul>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
20 <li><a href="#instance">The Instance</a>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
21 <li><a href="#startcmd">Command Line Tool</a>
469
d35e51360175 mention POP interface
Richard Jones <richard@users.sourceforge.net>
parents: 461
diff changeset
22 <li><a href="#startmail">E-Mail Interface</a>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
23 <li><a href="#startweb">Web Interface</a>
270
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
24 <li><a href="#users">Users and Access Control</a> (Users and permissions, Adding users)
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
25 <li><a href="#issues">Issues</a>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
26 </ul>
253
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
27 <li><a href="#guide">User Guide</a>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
28 <ul>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
29 <li><a href="#cmd">Command Line Tool</a>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
30 <li><a href="#web">Web Interface</a>
265
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
31 <li><a href="#mail">E-Mail Gateway</a> (Message content summary, Address handling, Performing Actions)
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
32 </ul>
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
33 <li><a href="#custom">Customising Roundup</a>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
34 <ul>
260
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
35 <li><a href="#config">Instance Configuration</a>
265
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
36 <li><a href="#custinst">Instance Schema</a> (Creating a new information store)
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
37 <li><a href="#custweb">Web Interface</a> (Displaying properties, Index views, Item views)
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
38 </ul>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
39 <li><a href="spec.html">Roundup's Design Document</a> ("Implementation Guide")
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
40 <li><a href="#ack">Acknowledgements</a>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
41 </ul>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
42
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
43 <p><hr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
44 <h1><a name="installation">Installation</a></h1>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
45
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
46
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
47 <h2><a name="requires">Prerequisites</a></h2>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
48
461
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
49 <p>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
50 Python 2.1.1 is required for the correct operation of roundup.
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
51 </p>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
52
461
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
53 <p>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
54 Download the latest version from
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
55 <a href="http://www.python.org/">http://www.python.org/</a>.
461
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
56 </p>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
57
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
58
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
59
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
60 <h2><a name="getting">Getting Roundup</a></h2>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
61
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
62 Download the latest version from
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
63 <a href="http://roundup.sf.net/">http://roundup.sf.net/</a>.
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
64
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
65
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
66 <h2><a name="installing">Installing Roundup</a></h2>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
67
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
68 <ol>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
69 <li>Run:
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
70 <br><tt>python setup.py install</tt>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
71 <li>If you would prefer the scripts installed in somewhere other than
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
72 <tt>/usr/local/bin</tt>, add <tt>"--install-scripts=&lt;dir&gt;"</tt>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
73 to the command:
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
74 <br><tt>python setup.py install --install-scripts=&lt;dir&gt;</tt>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
75 <li>The command:
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
76 <br><tt>python setup.py install --help</tt>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
77 <br>gives all the options available for installation.
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
78 </ol>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
79
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
80
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
81 <p><hr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
82 <h1><a name="starting">Getting Started</a></h1>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
83
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
84 The following instructions assume that you have installed roundup. If you
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
85 haven't, you may still proceed - just preface all commands with "./"
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
86 ie. "./roundup-admin init".
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
87
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
88
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
89 <h2><a name="instance">The Instance</a></h2>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
90
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
91 We'll be referring to the term <em>instance</em> a lot from now on. An
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
92 instance is
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
93 a directory in your filesystem that is where all the information about a
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
94 live issue tracker database is stored. The data that is entered as issues,
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
95 the users who access the database and the definition of the database itself
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
96 all reside there:
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
97 <ol>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
98 <li><strong>Hyperdatabase</strong>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
99 <br>This is the lowest component of Roundup and is where all the
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
100 issues, users, file attachments and messages are stored.
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
101 <li><strong>Database schema</strong>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
102 <br>This describes the content of the hyperdatabase - what fields are
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
103 stored for issues, what user information, etc. Being stored in the
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
104 instance, this allows it to be customised for a particular application.
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
105 It also means that changes in the Roundup core code do not affect a
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
106 running instance.
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
107 <li><strong>Web Interface</strong>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
108 <br>The web interface templates are defined in the instance too - and
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
109 the actual CGI interface class is defined (mostly using base classes in
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
110 the Roundup core code) so it, like the database, may be customised for
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
111 each instance in use.
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
112 </ol>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
113
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
114 Instances are created using the <tt>roundup-admin</tt> tool.
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
115
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
116 <h2><a name="startcmd">Command Line Tool</a></h2>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
117
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
118 To initiliase a new instance, run <tt>roundup-admin init</tt>. You will be
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
119 asked a series of questions:
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
120
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
121 <ol>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
122 <li>Instance home directory
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
123 <li>Schema to use
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
124 <li>Database back-end to use
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
125 <li>Administration user "admin" password.
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
126 </ol>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
127
270
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
128 You should also think about whether there is going to be controlled access
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
129 to the instance on the machine the instance is running on. That is, who can
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
130 actually make changes to the database using the roundup-admin tool. See
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
131 the section on <a href="#users">Users and Access Control</a> for
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
132 information on how to secure your instance from the start.
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
133
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
134 <p>
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
135
260
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
136 Roundup is configurable using an instance_config.py file in the instance home.
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
137 It should be edited before roundup is used, and may have the following
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
138 variable declarations:
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
139
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
140 <ol>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
141 <li>MAILHOST
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
142 <br>The SMTP mail host that roundup will use to send mail
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
143 <li>MAIL_DOMAIN
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
144 <br>The domain name used for email addresses
260
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
145 <li>ISSUE_TRACKER_WEB
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
146 <br>The web address of the issue tracker's web interface
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
147 </ol>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
148
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
149 <p>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
150 The email addresses used by the system by default are:
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
151
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
152 <ol>
260
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
153 <li>ISSUE_TRACKER_EMAIL - issue_tracker@MAIL_DOMAIN
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
154 <br>submissions of issues
260
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
155 <li>ADMIN_EMAIL - roundup-admin@MAIL_DOMAIN
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
156 <br>roundup's internal use (problems, etc)
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
157 </ol>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
158
469
d35e51360175 mention POP interface
Richard Jones <richard@users.sourceforge.net>
parents: 461
diff changeset
159 <h2><a name="startmail">E-Mail Interface</a></h2>
370
745f9cacfba0 Info on setting up a local spool handling mail gateway.
Richard Jones <richard@users.sourceforge.net>
parents: 338
diff changeset
160
745f9cacfba0 Info on setting up a local spool handling mail gateway.
Richard Jones <richard@users.sourceforge.net>
parents: 338
diff changeset
161 <h3>Setup 1: As a mail alias pipe process</h3>
438
9d97c1a4ddad Notes from changes.
Richard Jones <richard@users.sourceforge.net>
parents: 402
diff changeset
162 Set up a mail alias called "issue_tracker" as (include the quote marks):
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
163 <blockquote>
438
9d97c1a4ddad Notes from changes.
Richard Jones <richard@users.sourceforge.net>
parents: 402
diff changeset
164 <tt>"|/usr/bin/python /usr/local/bin/roundup-mailgw &lt;instance_home&gt;"</tt>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
165 </blockquote>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
166
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
167 In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
168 so sendmail will accept the pipe command. In that case, symlink
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
169 /etc/smrsh/roundup-mailgw to /usr/local/bin/roundup-mailgw and change the
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
170 command to:
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
171 <blockquote>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
172 <tt>|roundup-mailgw &lt;instance_home&gt;</tt>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
173 </blockquote>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
174
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
175 To test the mail gateway on unix systems, try:
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
176
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
177 <blockquote>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
178 <tt>echo test |mail -s '[issue] test' issue_tracker@your.domain</tt>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
179 </blockquote>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
180
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
181
469
d35e51360175 mention POP interface
Richard Jones <richard@users.sourceforge.net>
parents: 461
diff changeset
182 <h3>Setup 2: As a regular cron job using a mailbox source</h3>
370
745f9cacfba0 Info on setting up a local spool handling mail gateway.
Richard Jones <richard@users.sourceforge.net>
parents: 338
diff changeset
183 Set the roundup-mailgw up to run every 10 minutes or so. For example:
745f9cacfba0 Info on setting up a local spool handling mail gateway.
Richard Jones <richard@users.sourceforge.net>
parents: 338
diff changeset
184 <blockquote>
469
d35e51360175 mention POP interface
Richard Jones <richard@users.sourceforge.net>
parents: 461
diff changeset
185 <tt>10 * * * * /usr/local/bin/roundup-mailgw &lt;instance_home&gt; mailbox &lt;mail_spool_file&gt;</tt>
370
745f9cacfba0 Info on setting up a local spool handling mail gateway.
Richard Jones <richard@users.sourceforge.net>
parents: 338
diff changeset
186 </blockquote>
745f9cacfba0 Info on setting up a local spool handling mail gateway.
Richard Jones <richard@users.sourceforge.net>
parents: 338
diff changeset
187 Where the mail_spool_file argument is the location of the roundup
745f9cacfba0 Info on setting up a local spool handling mail gateway.
Richard Jones <richard@users.sourceforge.net>
parents: 338
diff changeset
188 submission user's mail spool. On most systems, the spool for a user
745f9cacfba0 Info on setting up a local spool handling mail gateway.
Richard Jones <richard@users.sourceforge.net>
parents: 338
diff changeset
189 "issue_tracker" will be "/var/mail/issue_tracker".
745f9cacfba0 Info on setting up a local spool handling mail gateway.
Richard Jones <richard@users.sourceforge.net>
parents: 338
diff changeset
190
469
d35e51360175 mention POP interface
Richard Jones <richard@users.sourceforge.net>
parents: 461
diff changeset
191 <h3>Setup 3: As a regular cron job using a POP source</h3>
d35e51360175 mention POP interface
Richard Jones <richard@users.sourceforge.net>
parents: 461
diff changeset
192 To retrieve from a POP mailbox, use a similar cron entry to the mailbox
d35e51360175 mention POP interface
Richard Jones <richard@users.sourceforge.net>
parents: 461
diff changeset
193 one:
d35e51360175 mention POP interface
Richard Jones <richard@users.sourceforge.net>
parents: 461
diff changeset
194 <blockquote>
d35e51360175 mention POP interface
Richard Jones <richard@users.sourceforge.net>
parents: 461
diff changeset
195 <tt>10 * * * * /usr/local/bin/roundup-mailgw &lt;instance_home&gt; pop &lt;pop_spec&gt;</tt>
d35e51360175 mention POP interface
Richard Jones <richard@users.sourceforge.net>
parents: 461
diff changeset
196 </blockquote>
d35e51360175 mention POP interface
Richard Jones <richard@users.sourceforge.net>
parents: 461
diff changeset
197 where pop_spec is "username:password@server" that specifies the roundup
d35e51360175 mention POP interface
Richard Jones <richard@users.sourceforge.net>
parents: 461
diff changeset
198 submission user's POP account name, password and server.
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
199
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
200 <h2><a name="startweb">Web Interface</a></h2>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
201 This software will work through apache or stand-alone.
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
202 <p>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
203 <strong>Stand-alone:</strong>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
204 <ol>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
205 <li>Edit roundup-server at the top - ROUNDUP_INSTANCE_HOMES needs to know
469
d35e51360175 mention POP interface
Richard Jones <richard@users.sourceforge.net>
parents: 461
diff changeset
206 about your instance. You may also specify the values for
d35e51360175 mention POP interface
Richard Jones <richard@users.sourceforge.net>
parents: 461
diff changeset
207 ROUNDUP_INSTANCE_HOMES on the command-line using "name=home" pairs.
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
208 <li><tt>roundup-server [hostname port]</tt> (hostname may be "")
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
209 <li>Load up the page <tt>/&lt;instance name&gt;/index</tt> where
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
210 instance name is the
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
211 name you nominated in <tt>ROUNDUP_INSTANCE_HOMES</tt>.
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
212 </ol>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
213
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
214 <strong>Apache:</strong>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
215 <ol>
402
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
216 <li>The CGI script is found in the cgi-bin directory of the roundup
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
217 distribution.
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
218 </li>
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
219 <li>Make sure roundup.cgi is executable. Edit it at the top -
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
220 ROUNDUP_INSTANCE_HOMES needs to know about your instance.
402
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
221 </li>
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
222 <li>Edit your /etc/httpd/conf/httpd.conf and make sure that the
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
223 /home/httpd/html/roundup/roundup.cgi script will be treated as a CGI
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
224 script.
402
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
225 </li>
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
226 <li>Re-start your apache to re-load the config if necessary.
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
227 </li>
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
228 <li>Load up the page "/roundup/roundup.cgi/<instance name>/index" where
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
229 instance name is the name you nominated in ROUNDUP_INSTANCE_HOMES.
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
230 </li>
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
231 <li>To use the CGI script unchanged, which allows much easier updates,
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
232 add these directives to your "httpd.conf":
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
233 <pre>
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
234 SetEnv ROUNDUP_LOG "/var/log/roundup.log"
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
235 SetEnv ROUNDUP_INSTANCE_HOMES "Default=/usr/local/share/roundup/instances/Default"
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
236 SetEnv ROUNDUP_DEBUG "0"
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
237 </pre>
402
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
238 </li>
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
239 <li>On Windows, write a batch file "roundup.bat" similar to the one below
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
240 and place it into your cgi-bin directory:
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
241 <pre>
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
242 @echo off
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
243 set ROUNDUP_LOG=c:\Python21\share\roundup\cgi.log
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
244 set ROUNDUP_INSTANCE_HOMES=Default=c:\Python21\share\roundup\instances\Default;
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
245 set ROUNDUP_DEBUG=0
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
246 c:\Python21\python.exe c:\Python21\share\roundup\cgi-bin\roundup.cgi
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
247 </pre>
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
248 </li>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
249 </ol>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
250
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
251
402
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
252
00f120add0f7 Some version number and documentation fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 370
diff changeset
253
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
254 <h2><a name="users">Users</a></h2>
265
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
255
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
256 <h3>Users and permissions</h3>
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
257 By default, roundup automatically creates one user when the instance
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
258 database is initialised (using roundup-admin init). The user is "admin" and
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
259 the password is the one you supply at that time.
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
260 <p>
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
261 If users attempt to use roundup in any manner and are not identified to
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
262 roundup, they will be using the database in a read-only mode. That is, if
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
263 roundup doesn't know who they are, they can't change anything. This has the
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
264 following repurcussions:
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
265 <dl>
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
266 <dt><strong>Command-line interface</strong>
270
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
267 <dd>The data modification commands (create, init, retire, set) are
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
268 performed as the "admin" user. It is therefore important that the database
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
269 be protected by the filesystem if protection is required. On a Unix system,
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
270 the easiest and most flexible method of doing so is:
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
271 <ol>
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
272 <li>Add a new user and group to your system (e.g. "issue_tracker")
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
273 <li>When creating a new instance home, use the following commands
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
274 (substituting instance_home for the directory you want to use):<br>
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
275 <pre>
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
276 mkdir instance_home
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
277 chown issue_tracker:issue_tracker instance_home
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
278 chmod g+rwxs instance_home
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
279 roundup-admin -i instance_home init
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
280 </pre>
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
281 <li>Now, edit the /etc/group line for the issue_tracker group so it includes
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
282 the unix logins of all the users who are going to administer your roundup
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
283 instance. If you're running the web or mail gateways, then be sure to
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
284 include those users in the group too (on some Linux systems, these
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
285 users are "www" or "apache" and "mail".)
270
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
286 </ol>
a4241ddd22d7 Added the Password property type.
Richard Jones <richard@users.sourceforge.net>
parents: 268
diff changeset
287
265
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
288 <dt><strong>E-Mail interface</strong>
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
289 <dd>Users are identified by e-mail address - a new user entry will be
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
290 created for any e-mail address that is not recognised, so users are
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
291 <em>always</em> identified by roundup.
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
292 <dt><strong>Web interface</strong>
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
293 <dd>Unidentified users have read-only access. If the users database has an
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
294 entry with the username "anonymous", then unidentified users are
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
295 automatically logged in as that user. This gives them write access.
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
296 </dl>
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
297 <p>
316
c0ca7f35e0c5 Added configuration for:
Richard Jones <richard@users.sourceforge.net>
parents: 314
diff changeset
298 *** anonymous access and the ANONYMOUS_* configuratins.
265
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
299
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
300 <h3>Adding users</h3>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
301 To add users, use one of the following interfaces:
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
302
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
303 <ol>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
304 <li>On the web, access the URL <tt>.../&lt;instance name&gt;/newuser</tt>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
305 to bring up a form which may be used to add a new user.
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
306 <li>On the command-line, use:
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
307 <br><tt>roundup-admin -i &lt;instance home&gt; create user
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
308 username=bozo password=bozo address=richard@clown.org</tt>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
309 <br>Supply the admin username and password. roundup-admin will print the
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
310 id of the new user.
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
311 <li>Any e-mail sent to roundup from an address that doesn't match an
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
312 existing user in the database will result in a new user entry being
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
313 created for that user.
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
314 </ol>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
315
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
316
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
317
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
318 <h2><a name="issues">Issues</a></h2>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
319 To add issues, use one of the following interfaces:
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
320
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
321 <ol>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
322 <li>On the web, access the URL <tt>.../&lt;instance name&gt;/newissue</tt>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
323 to bring up a form which may be used to add a new issue.
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
324 <li>On the command-line, use:
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
325 <br><tt>roundup-admin -i &lt;instance home&gt; create issue
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
326 title="test issue"</tt>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
327 <br>Supply the admin username and password. roundup-admin will print the
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
328 id of the new issue.
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
329 <li>Any e-mail sent to roundup with the subject line containing [issue]
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
330 will automatically created a new issue in the database using the
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
331 contents of the e-mail.
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
332 </ol>
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
333
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
334 <p><hr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
335 <h1><a name="guide">User Guide</a></h1>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
336 <h2><a name="cmd">Command Line Tool</a></h2>
253
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
337
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
338 Usage:
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
339 <tt>roundup-admin [-i instance home] [-u login] [-c] &lt;command&gt;
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
340 &lt;arguments&gt;</tt>
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
341
253
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
342 <p>
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
343 <table><tr><th colspan=2>Options:</th></tr>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
344 <tr><td>-i instance home </td><td>specify the issue tracker "home directory" to administer
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
345 </td></tr>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
346 <tr><td>-u </td><td>the user[:password] to use for commands
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
347 </td></tr>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
348 <tr><td>-c </td><td>when outputting lists of data, just comma-separate them
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
349 </td></tr>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
350 </table>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
351
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
352 <p>
461
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
353 <table width=100% border=1 cellspacing=0>
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
354 <tr><th colspan=2>Command Help</th></tr>
461
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
355
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
356
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
357 <tr><td valign=top><strong>commit</strong></td>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
358 <td><tt>Usage: commit</tt><p>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
359 <pre>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
360 The changes made during an interactive session are not
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
361 automatically written to the database - they must be committed
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
362 using this command.
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
363
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
364 One-off commands on the command-line are automatically committed if
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
365 they are successful.
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
366
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
367 </pre></td></tr>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
368
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
369
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
370 <tr><td valign=top><strong>create</strong></td>
461
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
371 <td><tt>Usage: create classname property=value ...</tt><p>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
372 <pre>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
373 This creates a new entry of the given class using the property
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
374 name=value arguments provided on the command line after the "create"
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
375 command.
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
376
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
377 </pre></td></tr>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
378
279
231a031e4765 Updated doc for recent roundup-admin changes
Richard Jones <richard@users.sourceforge.net>
parents: 277
diff changeset
379
461
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
380 <tr><td valign=top><strong>display</strong></td>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
381 <td><tt>Usage: display designator</tt><p>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
382 <pre>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
383 This lists the properties and their associated values for the given
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
384 node.
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
385
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
386 </pre></td></tr>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
387
279
231a031e4765 Updated doc for recent roundup-admin changes
Richard Jones <richard@users.sourceforge.net>
parents: 277
diff changeset
388
231a031e4765 Updated doc for recent roundup-admin changes
Richard Jones <richard@users.sourceforge.net>
parents: 277
diff changeset
389 <tr><td valign=top><strong>export</strong></td>
461
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
390 <td><tt>Usage: export class[,class] destination_dir</tt><p>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
391 <pre>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
392 This action exports the current data from the database into
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
393 tab-separated-value files that are placed in the nominated destination
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
394 directory. The journals are not exported.
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
395
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
396 </pre></td></tr>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
397
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
398
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
399 <tr><td valign=top><strong>find</strong></td>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
400 <td><tt>Usage: find classname propname=value ...</tt><p>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
401 <pre>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
402 Find the nodes of the given class with a given link property value. The
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
403 value may be either the nodeid of the linked node, or its key value.
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
404
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
405 </pre></td></tr>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
406
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
407
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
408 <tr><td valign=top><strong>get</strong></td>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
409 <td><tt>Usage: get property designator[,designator]*</tt><p>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
410 <pre>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
411 Retrieves the property value of the nodes specified by the designators.
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
412
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
413 </pre></td></tr>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
414
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
415
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
416 <tr><td valign=top><strong>help</strong></td>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
417 <td><tt>Usage: help topic</tt><p>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
418 <pre>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
419 commands -- list commands
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
420 <command> -- help specific to a command
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
421 initopts -- init command options
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
422 all -- all available help
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
423
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
424 </pre></td></tr>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
425
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
426
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
427 <tr><td valign=top><strong>history</strong></td>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
428 <td><tt>Usage: history designator</tt><p>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
429 <pre>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
430 Lists the journal entries for the node identified by the designator.
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
431
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
432 </pre></td></tr>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
433
279
231a031e4765 Updated doc for recent roundup-admin changes
Richard Jones <richard@users.sourceforge.net>
parents: 277
diff changeset
434
231a031e4765 Updated doc for recent roundup-admin changes
Richard Jones <richard@users.sourceforge.net>
parents: 277
diff changeset
435 <tr><td valign=top><strong>import</strong></td>
461
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
436 <td><tt>Usage: import class file</tt><p>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
437 <pre>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
438 The file must define the same properties as the class (including having
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
439 a "header" line with those property names.) The new nodes are added to
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
440 the existing database - if you want to create a new database using the
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
441 imported data, then create a new database (or, tediously, retire all
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
442 the old data.)
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
443
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
444 </pre></td></tr>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
445
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
446
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
447 <tr><td valign=top><strong>initialise</strong></td>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
448 <td><tt>Usage: initialise [template [backend [admin password]]]</tt><p>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
449 <pre>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
450 The command will prompt for the instance home directory (if not supplied
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
451 through INSTANCE_HOME or the -i option. The template, backend and admin
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
452 password may be specified on the command-line as arguments, in that
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
453 order.
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
454
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
455 See also initopts help.
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
456
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
457 </pre></td></tr>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
458
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
459
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
460 <tr><td valign=top><strong>list</strong></td>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
461 <td><tt>Usage: list classname [property]</tt><p>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
462 <pre>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
463 Lists all instances of the given class. If the property is not
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
464 specified, the "label" property is used. The label property is tried
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
465 in order: the key, "name", "title" and then the first property,
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
466 alphabetically.
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
467
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
468 </pre></td></tr>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
469
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
470
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
471 <tr><td valign=top><strong>retire</strong></td>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
472 <td><tt>Usage: retire designator[,designator]*</tt><p>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
473 <pre>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
474 This action indicates that a particular node is not to be retrieved by
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
475 the list or find commands, and its key value may be re-used.
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
476
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
477 </pre></td></tr>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
478
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
479
461
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
480 <tr><td valign=top><strong>rollback</strong></td>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
481 <td><tt>Usage: rollback</tt><p>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
482 <pre>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
483 The changes made during an interactive session are not
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
484 automatically written to the database - they must be committed
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
485 manually. This command undoes all those changes, so a commit
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
486 immediately after would make no changes to the database.
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
487
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
488 </pre></td></tr>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
489
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
490
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
491 <tr><td valign=top><strong>set</strong></td>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
492 <td><tt>Usage: set designator[,designator]* propname=value ...</tt><p>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
493 <pre>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
494 Sets the property to the value for all designators given.
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
495
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
496 </pre></td></tr>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
497
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
498
461
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
499 <tr><td valign=top><strong>specification</strong></td>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
500 <td><tt>Usage: specification classname</tt><p>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
501 <pre>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
502 This lists the properties for a given class.
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
503
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
504 </pre></td></tr>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
505
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
506
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
507 <tr><td valign=top><strong>table</strong></td>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
508 <td><tt>Usage: table classname [property[,property]*]</tt><p>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
509 <pre>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
510 Lists all instances of the given class. If the properties are not
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
511 specified, all properties are displayed. By default, the column widths
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
512 are the width of the property names. The width may be explicitly defined
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
513 by defining the property as "name:width". For example::
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
514 roundup> table priority id,name:10
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
515 Id Name
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
516 1 fatal-bug
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
517 2 bug
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
518 3 usability
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
519 4 feature
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
520
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
521 </pre></td></tr>
b579418f7ed1 Implemented file store rollback.
Richard Jones <richard@users.sourceforge.net>
parents: 449
diff changeset
522
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
523 </table>
253
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
524
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
525 <p>
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
526 All commands (except help) require an instance specifier. This is just the path
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
527 to the roundup instance you're working with. A roundup instance is where
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
528 roundup keeps the database and configuration file that defines an issue
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
529 tracker. It may be thought of as the issue tracker's "home directory". It may
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
530 be specified in the environment variable ROUNDUP_INSTANCE or on the command
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
531 line as "-i instance".
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
532
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
533 <p>
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
534 A designator is a classname and a nodeid concatenated, eg. bug1, user10, ...
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
535
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
536 <p>
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
537 Property values are represented as strings in command arguments and in the
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
538 printed results:
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
539 <ul>
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
540 <li>Strings are, well, strings.
271
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
541 <li>Password values will display as their encoded value.
253
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
542 <li>Date values are printed in the full date format in the local time zone, and
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
543 accepted in the full format or any of the partial formats explained below.
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
544 <table>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
545 <tr><th>Input of...</th><th>Means...</th></tr>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
546 <tr><td>"2000-04-17.03:45"</td><td>2000-04-17.08:45:00</td></tr>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
547 <tr><td>"2000-04-17"</td><td>2000-04-17.00:00:00</td></tr>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
548 <tr><td>"01-25"</td><td>yyyy-01-25.00:00:00</td></tr>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
549 <tr><td>"08-13.22:13"</td><td>yyyy-08-14.03:13:00</td></tr>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
550 <tr><td>"11-07.09:32:43"</td><td>yyyy-11-07.14:32:43</td></tr>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
551 <tr><td>"14:25"</td><td>yyyy-mm-dd.19:25:00</td></tr>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
552 <tr><td>"8:47:11"</td><td>yyyy-mm-dd.13:47:11</td></tr>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
553 <tr><td>"."</td><td>"right now"</td></tr>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
554 </table>
253
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
555 <li>Link values are printed as node designators. When given as an argument,
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
556 node designators and key strings are both accepted.
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
557 <li>Multilink values are printed as lists of node designators joined by commas.
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
558 When given as an argument, node designators and key strings are both
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
559 accepted; an empty string, a single node, or a list of nodes joined by
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
560 commas is accepted.
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
561 </ul>
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
562 When multiple nodes are specified to the roundup get or roundup set
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
563 commands, the specified properties are retrieved or set on all the listed
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
564 nodes.
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
565 <p>
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
566 When multiple results are returned by the roundup get or roundup find
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
567 commands, they are printed one per line (default) or joined by commas (with
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
568 the -c) option.
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
569 <p>
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
570 Where the command changes data, a login name/password is required. The
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
571 login may be specified as either "name" or "name:password".
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
572 <ul>
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
573 <li>ROUNDUP_LOGIN environment variable
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
574 <li>the -u command-line option
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
575 </ul>
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
576 If either the name or password is not supplied, they are obtained from the
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
577 command-line.
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
578
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
579 <h2><a name="web">Web Interface</a></h2>
266
e0a54a571f78 more doc cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 265
diff changeset
580 Index views may be modified by the following arguments:
e0a54a571f78 more doc cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 265
diff changeset
581 <pre>
e0a54a571f78 more doc cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 265
diff changeset
582 :sort - sort by prop name, optionally preceeded with '-'
e0a54a571f78 more doc cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 265
diff changeset
583 to give descending or nothing for ascending sorting.
e0a54a571f78 more doc cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 265
diff changeset
584 :group - group by prop name, optionally preceeded with '-' or
e0a54a571f78 more doc cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 265
diff changeset
585 to sort in descending or nothing for ascending order.
e0a54a571f78 more doc cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 265
diff changeset
586 :filter - selects which props should be displayed in the filter
e0a54a571f78 more doc cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 265
diff changeset
587 section. Default is all.
e0a54a571f78 more doc cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 265
diff changeset
588 :columns - selects the columns that should be displayed.
e0a54a571f78 more doc cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 265
diff changeset
589 Default is all.
e0a54a571f78 more doc cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 265
diff changeset
590 propname - selects the values the node properties given by propname
e0a54a571f78 more doc cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 265
diff changeset
591 must have (very basic search/filter).
e0a54a571f78 more doc cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 265
diff changeset
592 </pre>
e0a54a571f78 more doc cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 265
diff changeset
593
e0a54a571f78 more doc cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 265
diff changeset
594 <strong>Not sure what to put in here...</strong>
253
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
595
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
596 <h2><a name="mail">E-Mail Gateway</a></h2>
253
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
597
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
598 <h3>Performing Actions</h3>
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
599 The subject line of the incoming message is examined to determine whether
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
600 the message is an attempt to create a new item or to discuss an existing
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
601 item. A designator enclosed in square brackets is sought as the first thing
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
602 on the subject line (after skipping any "Fwd:" or "Re:" prefixes).
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
603 <p>
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
604 If an item designator (class name and id number) is found there, the newly
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
605 created "msg" node is added to the "messages" property for that item, and
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
606 any new "file" nodes are added to the "files" property for the item.
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
607 <p>
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
608 If just an item class name is found there, we attempt to create a new item
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
609 of that class with its "messages" property initialized to contain the new
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
610 "msg" node and its "files" property initialized to contain any new "file"
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
611 nodes.
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
612
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
613 <h3>Setting Properties</h3>
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
614 The e-mail interface also provides a simple way to set
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
615 properties on items. At the end of the subject line,
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
616 <em>propname</em><tt>=</tt><em>value</em> pairs can be
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
617 specified in square brackets, using the same conventions
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
618 as for the <tt>roundup&nbsp;set</tt> shell command.
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
619 explanatory message given in the exception.
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
620
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
621 <h3>Message content</h3>
253
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
622 Incoming messages are examined for multiple parts:
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
623 <ul>
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
624 <li>In a multipart/mixed message or part, each subpart is extracted and
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
625 examined. The text/plain subparts are assembled to form the textual
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
626 body of the message, to be stored in the file associated with a "msg"
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
627 class node. Any parts of other types are each stored in separate files
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
628 and given "file" class nodes that are linked to the "msg" node.
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
629 <li>In a multipart/alternative message or part, we look for a text/plain
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
630 subpart and ignore the other parts.
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
631 </ul>
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
632
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
633 <h4>Message summary</h4>
253
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
634 The "summary" property on message nodes is taken from the first non-quoting
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
635 section in the message body. The message body is divided into sections by
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
636 blank lines. Sections where the second and all subsequent lines begin with
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
637 a "&gt;" or "|" character are considered "quoting sections". The first line of
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
638 the first non-quoting section becomes the summary of the message.
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
639
265
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
640 <h3>Address handling</h3>
253
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
641 All of the addresses in the To: and Cc: headers of the incoming message are
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
642 looked up among the user nodes, and the corresponding users are placed in
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
643 the "recipients" property on the new "msg" node. The address in the From:
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
644 header similarly determines the "author" property of the new "msg"
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
645 node. The default handling for addresses that don't have corresponding
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
646 users is to create new users with no passwords and a username equal to the
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
647 address. (The web interface does not permit logins for users with no
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
648 passwords.) If we prefer to reject mail from outside sources, we can simply
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
649 register an auditor on the "user" class that prevents the creation of user
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
650 nodes with no passwords.
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
651
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
652 <h3>Triggers</h3>
253
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
653 Both cases may trigger detectors (in the first case we are calling the
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
654 set() method to add the message to the item's spool; in the second case we
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
655 are calling the create() method to create a new node). If an auditor raises
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
656 an exception, the original message is bounced back to the sender with the
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
657
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
658 <h4>Nosy Lists</h4>
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
659 A standard detector is provided that watches for additions
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
660 to the "messages" property. When a new message is added, the
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
661 detector sends it to all the users on the "nosy" list for the
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
662 item that are not already on the "recipients" list of the
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
663 message. Those users are then appended to the "recipients"
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
664 property on the message, so multiple copies of a message
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
665 are never sent to the same user. The journal recorded by
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
666 the hyperdatabase on the "recipients" property then provides
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
667 a log of when the message was sent to whom.
253
5973f1d80ace More doc, straight out of the mailgw module and roundup-admin help
Richard Jones <richard@users.sourceforge.net>
parents: 251
diff changeset
668
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
669 <p><hr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
670 <h1><a name="custom">Customising Roundup</a></h1>
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
671
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
672 Instances have the following structure:
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
673 <table>
260
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
674 <tr><td valign=top><strong>instance_config.py</strong></td>
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
675 <td>Holds the basic <a href="#config">instance configuration</a></td></tr>
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
676 <tr><td valign=top><strong>dbinit.py</strong></td>
260
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
677 <td>Holds the <a href="#custinst">instance schema</a></td></tr>
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
678 <tr><td valign=top><strong>interfaces.py</strong></td>
260
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
679 <td>Defines the <a href="#custweb">Web</a> and E-Mail interfaces for the instance</td></tr>
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
680 <tr><td valign=top><strong>select_db.py</strong></td>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
681 <td>Selects the database back-end for the instance</td></tr>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
682 <tr><td valign=top><strong>db/</strong></td>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
683 <td>Holds the instance's database</td></tr>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
684 <tr><td valign=top><strong>db/files/</strong></td>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
685 <td>Holds the instance's upload files and messages</td></tr>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
686 <tr><td valign=top><strong>detectors/</strong></td>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
687 <td>Auditors and reactors for this instance</td></tr>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
688 <tr><td valign=top><strong>html/</strong></td>
260
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
689 <td>Web interface <a href="#custweb">templates</a>, images and style sheets</td></tr>
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
690 </table>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
691
260
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
692 <h2><a name="config">Instance Configuration</a></h2>
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
693 The <tt>instance_config.py</tt> located in your instance home contains the
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
694 basic configuration for the web and e-mail components of roundup's
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
695 interfaces. This file is a Python module. The default
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
696 <tt>instance_config.py</tt> is given below - as you can see, the
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
697 MAIL_DOMAIN must be edited before any interaction with the instance is
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
698 attempted.
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
699
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
700 <p>
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
701 <pre>
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
702 MAIL_DOMAIN=MAILHOST=HTTP_HOST=None
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
703 HTTP_PORT=0
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
704
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
705 # roundup home is this package's directory
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
706 INSTANCE_HOME=os.path.split(__file__)[0]
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
707
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
708 # The SMTP mail host that roundup will use to send mail
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
709 if not MAILHOST:
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
710 MAILHOST = 'localhost'
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
711
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
712 # The domain name used for email addresses.
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
713 if not MAIL_DOMAIN:
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
714 MAIL_DOMAIN = 'fill.me.in.'
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
715
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
716 # the next two are only used for the standalone HTTP server.
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
717 if not HTTP_HOST:
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
718 HTTP_HOST = ''
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
719 if not HTTP_PORT:
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
720 HTTP_PORT = 9080
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
721
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
722 # This is the directory that the database is going to be stored in
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
723 DATABASE = os.path.join(INSTANCE_HOME, 'db')
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
724
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
725 # This is the directory that the HTML templates reside in
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
726 TEMPLATES = os.path.join(INSTANCE_HOME, 'html')
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
727
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
728 # The email address that mail to roundup should go to
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
729 ISSUE_TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
730
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
731 # The web address that the instance is viewable at
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
732 ISSUE_TRACKER_WEB = 'http://some.useful.url/'
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
733
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
734 # The email address that roundup will complain to if it runs into trouble
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
735 ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
736
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
737 # Somewhere for roundup to log stuff internally sent to stdout or stderr
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
738 LOG = os.path.join(INSTANCE_HOME, 'roundup.log')
338
b24754a5c629 Feeble addition to documentation for instance configuration. Well, it'll
Richard Jones <richard@users.sourceforge.net>
parents: 316
diff changeset
739
b24754a5c629 Feeble addition to documentation for instance configuration. Well, it'll
Richard Jones <richard@users.sourceforge.net>
parents: 316
diff changeset
740 # Where to place the web filtering HTML on the index page
b24754a5c629 Feeble addition to documentation for instance configuration. Well, it'll
Richard Jones <richard@users.sourceforge.net>
parents: 316
diff changeset
741 FILTER_POSITION = 'bottom' # one of 'top', 'bottom', 'top and bottom'
b24754a5c629 Feeble addition to documentation for instance configuration. Well, it'll
Richard Jones <richard@users.sourceforge.net>
parents: 316
diff changeset
742
b24754a5c629 Feeble addition to documentation for instance configuration. Well, it'll
Richard Jones <richard@users.sourceforge.net>
parents: 316
diff changeset
743 # Deny or allow anonymous access to the web interface
b24754a5c629 Feeble addition to documentation for instance configuration. Well, it'll
Richard Jones <richard@users.sourceforge.net>
parents: 316
diff changeset
744 ANONYMOUS_ACCESS = 'deny'
b24754a5c629 Feeble addition to documentation for instance configuration. Well, it'll
Richard Jones <richard@users.sourceforge.net>
parents: 316
diff changeset
745
b24754a5c629 Feeble addition to documentation for instance configuration. Well, it'll
Richard Jones <richard@users.sourceforge.net>
parents: 316
diff changeset
746 # Deny or allow anonymous users to register through the web interface
b24754a5c629 Feeble addition to documentation for instance configuration. Well, it'll
Richard Jones <richard@users.sourceforge.net>
parents: 316
diff changeset
747 ANONYMOUS_REGISTER = 'deny'
b24754a5c629 Feeble addition to documentation for instance configuration. Well, it'll
Richard Jones <richard@users.sourceforge.net>
parents: 316
diff changeset
748
b24754a5c629 Feeble addition to documentation for instance configuration. Well, it'll
Richard Jones <richard@users.sourceforge.net>
parents: 316
diff changeset
749 # Send nosy messages to the author of the message
b24754a5c629 Feeble addition to documentation for instance configuration. Well, it'll
Richard Jones <richard@users.sourceforge.net>
parents: 316
diff changeset
750 MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no'
260
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
751 </pre>
2099d0d052ed More documentation and a new TODO item.
Richard Jones <richard@users.sourceforge.net>
parents: 257
diff changeset
752
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
753 <h2><a name="custinst">Instance Schema</a></h2>
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
754 An instance schema defines what data is stored in the instance's database.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
755 The two schemas shipped with Roundup turn it into a typical software bug
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
756 tracker (the extended schema allowing for support issues as well as bugs).
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
757 Schemas are defined using Python code. The "classic" schema looks like
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
758 this:
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
759 <p>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
760 <pre>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
761 pri = Class(db, "priority", name=String(), order=String())
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
762 pri.setkey("name")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
763 pri.create(name="critical", order="1")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
764 pri.create(name="urgent", order="2")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
765 pri.create(name="bug", order="3")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
766 pri.create(name="feature", order="4")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
767 pri.create(name="wish", order="5")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
768
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
769 stat = Class(db, "status", name=String(), order=String())
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
770 stat.setkey("name")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
771 stat.create(name="unread", order="1")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
772 stat.create(name="deferred", order="2")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
773 stat.create(name="chatting", order="3")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
774 stat.create(name="need-eg", order="4")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
775 stat.create(name="in-progress", order="5")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
776 stat.create(name="testing", order="6")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
777 stat.create(name="done-cbb", order="7")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
778 stat.create(name="resolved", order="8")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
779
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
780 keyword = Class(db, "keyword", name=String())
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
781 keyword.setkey("name")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
782
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
783 user = Class(db, "user", username=String(), password=String(),
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
784 address=String(), realname=String(), phone=String(), organisation=String())
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
785 user.setkey("username")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
786 user.create(username="admin", password=adminpw, address=instance_config.ADMIN_EMAIL)
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
787
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
788 msg = FileClass(db, "msg", author=Link("user"), recipients=Multilink("user"),
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
789 date=Date(), summary=String(), files=Multilink("file"))
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
790
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
791 file = FileClass(db, "file", name=String(), type=String())
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
792
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
793 issue = IssueClass(db, "issue", assignedto=Link("user"),
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
794 topic=Multilink("keyword"), priority=Link("priority"), status=Link("status"))
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
795 issue.setkey('title')
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
796 </pre>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
797
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
798 <h3>Classes and Properties - creating a new information store</h3>
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
799 In the instance above, we've defined 7 <em>classes</em> of information:
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
800 <dl>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
801 <dt><strong>priority</strong>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
802 <dd>Defines the possible levels of urgency for issues.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
803 <dt><strong>status</strong>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
804 <dd>Defines the possible states of processing the issue may be in.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
805 <dt><strong>keyword</strong>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
806 <dd>Initially empty, will hold keywords useful for searching issues.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
807 <dt><strong>user</strong>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
808 <dd>Initially holding the "admin" user, will eventually have an entry
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
809 for all users using roundup.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
810 <dt><strong>msg</strong>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
811 <dd>Initially empty, will all e-mail messages sent to or generated by roundup.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
812 <dt><strong>file</strong>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
813 <dd>Initially empty, will all files attached to issues.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
814 <dt><strong>issue</strong>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
815 <dd>Initially emtyp, this is where the issue information is stored.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
816 </dl>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
817 <p>
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
818 We define the "priority" and "status" classes to allow two things: reduction
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
819 in the amount of information stored on the issue and more powerful, accurate
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
820 searching of issues by priority and status. By only requiring a link on
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
821 the issue (which is stored as a single number) we reduce the chance
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
822 that someone mis-types a priority or status - or simply makes a new one
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
823 up.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
824
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
825 <h4>Class and Nodes</h4>
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
826 A <em>Class</em> defines a particular class (or type) of data that will be
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
827 stored in the database. A class comprises one or more properties, which
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
828 given the information about the class nodes.
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
829 <p>
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
830 The actual data entered into the database, using <em>class</em>.create()
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
831 are called <em>nodes</em>. They have a special immutable property called
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
832 id. We sometimes refer to this as the <em>nodeid</em>.
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
833
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
834
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
835 <h4>Properties</h4>
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
836 A Class is comprised of one or more <em>properties</em> of the following types:
271
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
837
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
838 <ul>
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
839 <li><em>String</em> properties are for storing arbitrary-length
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
840 strings.
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
841
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
842 <li><em>Password</em> properties are for storing encoded arbitrary-length
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
843 strings. The default encoding is defined on the roundup.password.Password
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
844 class.
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
845
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
846 <li><em>Date</em> properties store date-and-time stamps.
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
847 Their values are Timestamp objects.
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
848
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
849 <li>A <em>Link</em> property refers to a single other node
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
850 selected from a specified class. The class is part of the property;
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
851 the value is an integer, the id of the chosen node.
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
852
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
853 <li>A <em>Multilink</em> property refers to possibly many nodes
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
854 in a specified class. The value is a list of integers.
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
855 </ul>
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
856
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
857 <h4>FileClass</h4>
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
858 FileClasses save their "content" attribute off in a separate file from the
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
859 rest of the database. This reduces the number of large entries in the
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
860 database, which generally makes databases more efficient, and also allows
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
861 us to use command-line tools to operate on the files. They are stored in
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
862 the files sub-directory of the db directory in your instance.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
863
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
864 <h4>IssueClass</h4>
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
865 IssueClasses automatically include the "messages", "files", "nosy", and
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
866 "superseder" properties.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
867 <p>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
868 The messages and files properties list the links to the messages and files
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
869 related to the issue. The nosy property is a list of links to users who
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
870 wish to be informed of changes to the issue - they get "CC'ed" e-mails when
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
871 messages are sent to or generated by the issue. The nosy reactor (in the
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
872 detectors directory) handles this action. The superceder link indicates an
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
873 issue which has superceded this one.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
874 <p>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
875 They also have the dynamically generated
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
876 "creation", "activity" and "creator" properties.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
877 <p>
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
878 The value of the "creation" property is the date when a node was created,
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
879 and the value of the "activity" property is the date when any property on
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
880 the node was last edited (equivalently, these are the dates on the first
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
881 and last records in the node's journal). The "creator" property holds a
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
882 link to the user that created the issue.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
883
265
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
884 <h4>setkey(property)</h4>
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
885 Select a String property of the class to be the key property. The key
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
886 property muse be unique, and allows references to the nodes in the class by
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
887 the content of the key property. That is, we can refer to users by their
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
888 username, e.g. let's say that there's an issue in roundup, issue 23. There's
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
889 also a user, richard who happens to be user 2. To assign an issue to him,
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
890 we could do either of:
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
891 <p>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
892 <blockquote><tt>roundup-admin set issue assignedto=2</tt></blockquote>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
893 <p>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
894 or
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
895 <p>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
896 <blockquote><tt>roundup-admin set issue
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
897 assignedto=richard</tt></blockquote>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
898 <p>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
899 Note, the same thing can be done in the web and e-mail interfaces.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
900
265
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
901 <h4>create(information)</h4>
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
902 Create a node in the database. This is generally used to create nodes in
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
903 the "definitional" classes like "priority" and "status".
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
904
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
905
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
906 <h2><a name="custweb">Web Interface</a></h2>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
907
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
908 The web interface works behind the cgi-bin/roundup.cgi or roundup-server
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
909 scripts. In both cases, the scripts determine which instance is being
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
910 accessed (the first part of the URL path inside the scope of the CGI
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
911 handler) and pass control on to the instance interfaces.Client class which
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
912 handles the rest of the access through its main() method. This means that
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
913 you can do pretty much anything you want as a web interface to your
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
914 instance.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
915 <p>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
916 Most customisation of the web view can be done by modifying the templates
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
917 in the instance html directory. These are divided into index, item and
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
918 newitem views. The newitem view is optional - the item view will be used if
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
919 the newitem view doesn't exist.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
920
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
921 <h3>Displaying Properties</h3>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
922
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
923 <p>
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
924 Properties appear in the user interface in three contexts:
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
925 in indices, in editors, and as filters. For each type of
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
926 property, there are several display possibilities. For example,
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
927 in an index view, a string property may just be printed as
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
928 a plain string, but in an editor view, that property should
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
929 be displayed in an editable field.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
930
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
931 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
932 The display of a property is handled by functions in
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
933 the htmltemplate module.
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
934
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
935 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
936 Displayer functions are triggered by <tt>&lt;display&gt;</tt>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
937 tags in templates. The <tt>call</tt> attribute of the tag
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
938 provides a Python expression for calling the displayer
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
939 function. The three standard arguments are inserted in
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
940 front of the arguments given. For example, the occurrence of
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
941
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
942 <blockquote><pre><small
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
943 > &lt;display call="plain('status')"&gt;
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
944 </small></pre></blockquote>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
945
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
946 in a template triggers a call the "plain" function. The displayer
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
947 functions can accept extra arguments to further specify
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
948 details about the widgets that should be generated. By defining new
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
949 displayer functions, the user interface can be highly customized.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
950
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
951 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
952 <table border=1 cellspacing=0>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
953 <tr><th colspan=2>The displayer functions are</th></tr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
954
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
955 <tr><td valign="top"><strong>plain</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
956 <td>Display a String property directly.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
957 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
958 Display a Date property in a specified time zone with an option
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
959 to omit the time from the date stamp.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
960 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
961 For a Link or Multilink
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
962 property, display the key strings of the linked nodes (or the
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
963 ids if the linked class has no key property).
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
964 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
965 <em>Options:</em><br>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
966 escape (boolean) - HTML-escape the resulting text.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
967 </td></tr>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
968
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
969 <tr><td valign="top"><strong>field</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
970 <td>Display a property like the
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
971 <strong>plain</strong> displayer above, but in a form field
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
972 to be edited. Strings, Dates and Intervals use TEXT fields, Links use
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
973 SELECT fields and Multilinks use SELECT MULTIPLE fields.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
974 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
975 <em>Options:</em><br>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
976 size (number) - width of TEXT fields.<br>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
977 height (number) - number of nows in SELECT MULTIPLE tags.<br>
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
978 showid (boolean) - true includes the id of linked nodes in the SELECT
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
979 MULTIPLE fields.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
980 </td></tr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
981
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
982 <tr><td valign="top"><strong>menu</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
983 <td>For a Links and Multilinks, display the same field as would be
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
984 generated using <strong>field</strong>.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
985 </td></tr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
986
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
987 <tr><td valign="top"><strong>link</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
988 <td>For a Link or Multilink property, display the names of the linked
314
baf901f72977 Updated the documentation for recent html template changes.
Richard Jones <richard@users.sourceforge.net>
parents: 279
diff changeset
989 nodes, hyperlinked to the item views on those nodes.
baf901f72977 Updated the documentation for recent html template changes.
Richard Jones <richard@users.sourceforge.net>
parents: 279
diff changeset
990 <p>
baf901f72977 Updated the documentation for recent html template changes.
Richard Jones <richard@users.sourceforge.net>
parents: 279
diff changeset
991 For other properties, link to this node with the property as the text.
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
992 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
993 <em>Options:</em><br>
314
baf901f72977 Updated the documentation for recent html template changes.
Richard Jones <richard@users.sourceforge.net>
parents: 279
diff changeset
994 property (property name) - the property to use in the second case.<br>
baf901f72977 Updated the documentation for recent html template changes.
Richard Jones <richard@users.sourceforge.net>
parents: 279
diff changeset
995 is_download (boolean) - to be used for links te <em>file</em> class nodes -
baf901f72977 Updated the documentation for recent html template changes.
Richard Jones <richard@users.sourceforge.net>
parents: 279
diff changeset
996 this indicates that the URL should have the specified property (usually
baf901f72977 Updated the documentation for recent html template changes.
Richard Jones <richard@users.sourceforge.net>
parents: 279
diff changeset
997 <em>name</em>) appended so that the download has the correct name (instead
baf901f72977 Updated the documentation for recent html template changes.
Richard Jones <richard@users.sourceforge.net>
parents: 279
diff changeset
998 of the node designator.)
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
999 </td></tr>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1000
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1001 <tr><td valign="top"><strong>count</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1002 <td>For a Multilink property, display
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1003 a count of the number of links in the list.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1004 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1005 <em>Arguments:</em><br>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1006 property (property name) - the property to use.
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1007
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1008 </td></tr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1009
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1010 <tr><td valign="top"><strong>reldate</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1011 <td>Display a Date property in terms
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1012 of an interval relative to the current date (e.g. "+ 3w", "- 2d").
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1013 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1014 <em>Arguments:</em><br>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1015 property (property name) - the property to use.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1016 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1017 <em>Options:</em><br>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1018 pretty (boolean) - display the relative date in an English form.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1019 </td></tr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1020
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1021 <tr><td valign="top"><strong>download</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1022 <td>Show a Link("file") or Multilink("file")
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1023 property using links that allow you to download files.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1024 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1025 <em>Arguments:</em><br>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1026 property (property name) - the property to use.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1027 </td></tr>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1028
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1029 <tr><td valign="top"><strong>checklist</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1030 <td>For a Link or Multilink property,
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1031 display checkboxes for the available choices to permit filtering.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1032 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1033 <em>Arguments:</em><br>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1034 property (property name) - the property to use.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1035 </td></tr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1036
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1037 <tr><td valign="top"><strong>note</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1038 <td>Display the special notes field, which is a text area for entering a
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1039 note to go along with a change.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1040 </td></tr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1041
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1042 <tr><td valign="top"><strong>list</strong></td>
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
1043 <td>List the nodes specified by property using the standard index for
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1044 the class.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1045 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1046 <em>Arguments:</em><br>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1047 property (property name) - the property to use.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1048 </td></tr>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1049
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1050 <tr><td valign="top"><strong>history</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1051 <td>List the history of the item.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1052 </td></tr>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1053
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1054 <tr><td valign="top"><strong>submit</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1055 <td>Add a submit button for the item.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1056 </td></tr>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1057
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1058 </table>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1059
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1060 <h3>Index Views</h3>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1061
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1062 <p>An index view contains two sections: a filter section
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1063 and an index section.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1064 The filter section provides some widgets for selecting
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1065 which items appear in the index. The index section is
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1066 a table of items.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1067
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1068 <h4>Index View Specifiers</h4>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1069
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1070 <p>An index view specifier (URL fragment) looks like this (whitespace
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1071 has been added for clarity):
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1072
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1073 <blockquote><pre><small
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1074 >/issue?status=unread,in-progress,resolved&amp;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1075 topic=security,ui&amp;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1076 :group=+priority&amp;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1077 :sort=-activity&amp;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1078 :filters=status,topic&amp;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1079 :columns=title,status,fixer
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1080 </small></pre></blockquote>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1081
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1082 <p>The index view is determined by two parts of the
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1083 specifier: the layout part and the filter part.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1084 The layout part consists of the query parameters that
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1085 begin with colons, and it determines the way that the
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1086 properties of selected nodes are displayed.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1087 The filter part consists of all the other query parameters,
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1088 and it determines the criteria by which nodes
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1089 are selected for display.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1090
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1091 <p>The filter part is interactively manipulated with
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1092 the form widgets displayed in the filter section. The
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1093 layout part is interactively manipulated by clicking
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1094 on the column headings in the table.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1095
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1096 <p>The filter part selects the <em>union</em> of the
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1097 sets of items with values matching any specified Link
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1098 properties and the <em>intersection</em> of the sets
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1099 of items with values matching any specified Multilink
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1100 properties.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1101
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1102 <p>The example specifies an index of "issue" nodes.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1103 Only items with a "status" of <em>either</em>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1104 "unread" or "in-progres" or "resolved" are displayed,
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1105 and only items with "topic" values including <em>both</em>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1106 "security" <em>and</em> "ui" are displayed. The items
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1107 are grouped by priority, arranged in ascending order;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1108 and within groups, sorted by activity, arranged in
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1109 descending order. The filter section shows filters
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1110 for the "status" and "topic" properties, and the
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1111 table includes columns for the "title", "status", and
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1112 "fixer" properties.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1113
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1114 <p>Associated with each item class is a default
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1115 layout specifier. The layout specifier in the above
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1116 example is the default layout to be provided with
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1117 the default bug-tracker schema described above in
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1118 section 4.4.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1119
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1120 <h4>Filter Section</h4>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1121
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1122 <p>The template for a filter section provides the
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1123 filtering widgets at the top of the index view.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1124 Fragments enclosed in <tt>&lt;property&gt;</tt>...<tt>&lt;/property&gt;</tt>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1125 tags are included or omitted depending on whether the
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1126 view specifier requests a filter for a particular property.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1127
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1128 <p>Here's a simple example of a filter template.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1129
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1130 <blockquote><pre><small
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1131 >&lt;property name=status&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1132 &lt;display call="checklist('status')"&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1133 &lt;/property&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1134 &lt;br&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1135 &lt;property name=priority&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1136 &lt;display call="checklist('priority')"&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1137 &lt;/property&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1138 &lt;br&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1139 &lt;property name=fixer&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1140 &lt;display call="menu('fixer')"&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1141 &lt;/property&gt;</small></pre></blockquote>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1142
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1143 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1144 The standard index generation code appends a section to the index pages
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1145 which allows selection of the filters - from those which are defined in the
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1146 filter template.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1147
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1148 <h4>Index Section</h4>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1149
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1150 <p>The template for an index section describes one row of
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1151 the index table.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1152 Fragments enclosed in <tt>&lt;property&gt;</tt>...<tt>&lt;/property&gt;</tt>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1153 tags are included or omitted depending on whether the
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1154 view specifier requests a column for a particular property.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1155 The table cells should contain <tt>&lt;display&gt;</tt> tags
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1156 to display the values of the item's properties.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1157
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1158 <p>Here's a simple example of an index template.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1159
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1160 <blockquote><pre><small
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1161 >&lt;tr&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1162 &lt;property name=title&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1163 &lt;td&gt;&lt;display call="plain('title', max=50)"&gt;&lt;/td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1164 &lt;/property&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1165 &lt;property name=status&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1166 &lt;td&gt;&lt;display call="plain('status')"&gt;&lt;/td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1167 &lt;/property&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1168 &lt;property name=fixer&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1169 &lt;td&gt;&lt;display call="plain('fixer')"&gt;&lt;/td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1170 &lt;/property&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1171 &lt;/tr&gt;</small></pre></blockquote>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1172
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1173 <h4>Sorting</h4>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1174
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1175 <p>String and Date values are sorted in the natural way.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1176 Link properties are sorted according to the value of the
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1177 "order" property on the linked nodes if it is present; or
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1178 otherwise on the key string of the linked nodes; or
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1179 finally on the node ids. Multilink properties are
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1180 sorted according to how many links are present.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1181
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1182 <h3>Item Views</h3>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1183
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1184 <p>An item view contains an editor section and a spool section.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1185 At the top of an item view, links to superseding and superseded
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1186 items are always displayed.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1187
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1188
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1189
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1190 <h4>Editor Section</h4>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1191
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1192 <p>The editor section is generated from a template
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1193 containing <tt>&lt;display&gt;</tt> tags to insert
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1194 the appropriate widgets for editing properties.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1195
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1196 <p>Here's an example of a basic editor template.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1197
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1198 <blockquote><pre><small
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1199 >&lt;table&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1200 &lt;tr&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1201 &lt;td colspan=2&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1202 &lt;display call="field('title', size=60)"&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1203 &lt;/td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1204 &lt;/tr&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1205 &lt;tr&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1206 &lt;td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1207 &lt;display call="field('fixer', size=30)"&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1208 &lt;/td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1209 &lt;td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1210 &lt;display call="menu('status')&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1211 &lt;/td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1212 &lt;/tr&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1213 &lt;tr&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1214 &lt;td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1215 &lt;display call="field('nosy', size=30)"&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1216 &lt;/td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1217 &lt;td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1218 &lt;display call="menu('priority')&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1219 &lt;/td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1220 &lt;/tr&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1221 &lt;tr&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1222 &lt;td colspan=2&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1223 &lt;display call="note()"&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1224 &lt;/td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1225 &lt;/tr&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1226 &lt;/table&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1227 </small></pre></blockquote>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1228
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1229 <p>As shown in the example, the editor template can also
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1230 request the display of a "note" field, which is a
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1231 text area for entering a note to go along with a change.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1232
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1233 <p>When a change is submitted, the system automatically
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1234 generates a message describing the changed properties.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1235
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1236 <p>If a note is given in the "note" field, the note is
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1237 appended to the description. The message is then added
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1238 to the item's message spool (thus triggering the standard
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1239 detector to react by sending out this message to the nosy list).
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1240
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1241 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1242 The message also displays all of the property values on the
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1243 item and indicates which ones have changed.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1244 An example of such a message might be this:
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1245
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1246 <blockquote><pre>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1247 Polly's taken a turn for the worse - this is now really important!
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1248 -----
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1249 title: Polly Parrot is dead
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1250 priority: critical
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1251 status: unread -&gt; in-progress
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1252 fixer: terry
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1253 keywords: parrot,plumage,perch,nailed,dead
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1254 </pre></blockquote>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1255
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1256 <h4>Spool Section</h4>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1257
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1258 <p>The spool section lists messages in the item's "messages"
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1259 property. The index of messages displays the "date", "author",
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1260 and "summary" properties on the message nodes, and selecting a
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1261 message takes you to its content.
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
1262
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1263 <p>The &lt;property&gt; tag used in the index may also be used here -
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1264 it checks to see if the nominated Multilink property has any entries.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1265 This can be used to eliminate sections of the spool section if the
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1266 property has no entries.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1267
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1268 <blockquote><pre>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1269 &lt;property name="files"&gt;
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1270 &lt;tr class="strong-header"&gt;
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1271 &lt;td&gt;&lt;b&gt;Files&lt;/b&gt;&lt;/td&gt;
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1272 &lt;/tr&gt;
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1273
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1274 &lt;tr&gt;
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1275 &lt;td&gt;&lt;display call="list('files')"&gt;&lt;/td&gt;
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1276 &lt;/tr&gt;
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1277 &lt;/property&gt;
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1278 </pre></blockquote>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1279
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
1280 <p><hr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1281 <h1><a name="ack">Acknowledgements</a></h1>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1282
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1283 Go Ping, you rock! Also, go Bizar Software for letting me implement this
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1284 system on their time.
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1285
254
af6e10660e27 cvs tag
Richard Jones <richard@users.sourceforge.net>
parents: 253
diff changeset
1286 <p>&nbsp;</p>
af6e10660e27 cvs tag
Richard Jones <richard@users.sourceforge.net>
parents: 253
diff changeset
1287 <hr>
469
d35e51360175 mention POP interface
Richard Jones <richard@users.sourceforge.net>
parents: 461
diff changeset
1288 $Id: index.html,v 1.23 2001-12-31 03:07:04 richard Exp $
254
af6e10660e27 cvs tag
Richard Jones <richard@users.sourceforge.net>
parents: 253
diff changeset
1289 <p>&nbsp;</p>
af6e10660e27 cvs tag
Richard Jones <richard@users.sourceforge.net>
parents: 253
diff changeset
1290
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1291 </body></html>
254
af6e10660e27 cvs tag
Richard Jones <richard@users.sourceforge.net>
parents: 253
diff changeset
1292
Roundup Issue Tracker: http://roundup-tracker.org/