Mercurial > p > roundup > code

annotate doc/index.html @ 602:c242455d9b46 config-0-4-0-branch

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Brought the config branch up to date with HEAD
author Richard Jones <richard@users.sourceforge.net>
date Wed, 06 Feb 2002 04:05:55 +0000
parents d35e51360175
children
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>
602
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
754 <b>Note:</b> if you modify the schema, you'll most likely need to
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
755 <a href="#schemarepurcussions">
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
756 web interface to reflect your changes</a>.
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
757 <p>
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
758 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
759 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
760 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
761 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
762 this:
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
763 <p>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
764 <pre>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
765 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
766 pri.setkey("name")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
767 pri.create(name="critical", order="1")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
768 pri.create(name="urgent", order="2")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
769 pri.create(name="bug", order="3")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
770 pri.create(name="feature", order="4")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
771 pri.create(name="wish", order="5")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
772
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
773 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
774 stat.setkey("name")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
775 stat.create(name="unread", order="1")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
776 stat.create(name="deferred", order="2")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
777 stat.create(name="chatting", order="3")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
778 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
779 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
780 stat.create(name="testing", order="6")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
781 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
782 stat.create(name="resolved", order="8")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
783
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
784 keyword = Class(db, "keyword", name=String())
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
785 keyword.setkey("name")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
786
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
787 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
788 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
789 user.setkey("username")
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
790 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
791
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
792 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
793 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
794
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
795 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
796
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
797 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
798 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
799 issue.setkey('title')
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
800 </pre>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
801
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
802 <h3>Classes and Properties - creating a new information store</h3>
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
803 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
804 <dl>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
805 <dt><strong>priority</strong>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
806 <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
807 <dt><strong>status</strong>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
808 <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
809 <dt><strong>keyword</strong>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
810 <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
811 <dt><strong>user</strong>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
812 <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
813 for all users using roundup.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
814 <dt><strong>msg</strong>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
815 <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
816 <dt><strong>file</strong>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
817 <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
818 <dt><strong>issue</strong>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
819 <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
820 </dl>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
821 <p>
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
822 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
823 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
824 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
825 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
826 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
827 up.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
828
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
829 <h4>Class and Nodes</h4>
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
830 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
831 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
832 given the information about the class nodes.
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
833 <p>
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
834 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
835 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
836 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
837
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
838
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
839 <h4>Properties</h4>
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
840 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
841
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
842 <ul>
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
843 <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
844 strings.
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>Password</em> properties are for storing encoded arbitrary-length
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
847 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
848 class.
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
849
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
850 <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
851 Their values are Timestamp objects.
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>Link</em> property refers to a single other node
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
854 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
855 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
856
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
857 <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
858 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
859 </ul>
85908e1f46ad Added some more doc.
Richard Jones <richard@users.sourceforge.net>
parents: 270
diff changeset
860
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
861 <h4>FileClass</h4>
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
862 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
863 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
864 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
865 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
866 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
867
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
868 <h4>IssueClass</h4>
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
869 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
870 "superseder" properties.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
871 <p>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
872 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
873 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
874 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
875 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
876 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
877 issue which has superceded this one.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
878 <p>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
879 They also have the dynamically generated
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
880 "creation", "activity" and "creator" properties.
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
881 <p>
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
882 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
883 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
884 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
885 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
886 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
887
265
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
888 <h4>setkey(property)</h4>
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
889 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
890 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
891 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
892 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
893 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
894 we could do either of:
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 assignedto=2</tt></blockquote>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
897 <p>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
898 or
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
899 <p>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
900 <blockquote><tt>roundup-admin set issue
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
901 assignedto=richard</tt></blockquote>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
902 <p>
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
903 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
904
265
0a28169a61b0 Some more documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 260
diff changeset
905 <h4>create(information)</h4>
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
906 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
907 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
908
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
909
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
910 <h2><a name="custweb">Web Interface</a></h2>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
911
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
912 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
913 scripts. In both cases, the scripts determine which instance is being
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
914 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
915 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
916 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
917 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
918 instance.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
919 <p>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
920 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
921 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
922 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
923 the newitem view doesn't exist.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
924
602
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
925 <h3><a name="schemarepurcussions">Repurcussions of changing the instance schema</a></h3>
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
926
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
927 If you choose to <a href="custinst">change the instance schema</a> you will need to
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
928 ensure the web interface knows about it:
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
929 <ol>
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
930 <li>Index, item and filter pages for the relevant classes may need to have properties
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
931 added or removed,
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
932 <li>The default page header relies on the existence of, and some values of the
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
933 priority, status, assignedto and activity classes. If you change any of these (specifically
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
934 if you remove any of the classes or their default values) you will need to implement your
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
935 own pagehead() method in your instance's interfaces.py module.
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
936 </ol>
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
937
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
938
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
939 <h3>Displaying Properties</h3>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
940
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
941 <p>
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
942 Properties appear in the user interface in three contexts:
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
943 in indices, in editors, and as filters. For each type of
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
944 property, there are several display possibilities. For example,
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
945 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
946 a plain string, but in an editor view, that property should
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
947 be displayed in an editable field.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
948
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
949 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
950 The display of a property is handled by functions in
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
951 the htmltemplate module.
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
952
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
953 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
954 Displayer functions are triggered by <tt>&lt;display&gt;</tt>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
955 tags in templates. The <tt>call</tt> attribute of the tag
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
956 provides a Python expression for calling the displayer
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
957 function. The three standard arguments are inserted in
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
958 front of the arguments given. For example, the occurrence of
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
959
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
960 <blockquote><pre><small
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
961 > &lt;display call="plain('status')"&gt;
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
962 </small></pre></blockquote>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
963
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
964 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
965 functions can accept extra arguments to further specify
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
966 details about the widgets that should be generated. By defining new
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
967 displayer functions, the user interface can be highly customized.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
968
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
969 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
970 <table border=1 cellspacing=0>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
971 <tr><th colspan=2>The displayer functions are</th></tr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
972
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
973 <tr><td valign="top"><strong>plain</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
974 <td>Display a String property directly.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
975 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
976 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
977 to omit the time from the date stamp.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
978 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
979 For a Link or Multilink
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
980 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
981 ids if the linked class has no key property).
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
982 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
983 <em>Options:</em><br>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
984 escape (boolean) - HTML-escape the resulting text.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
985 </td></tr>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
986
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
987 <tr><td valign="top"><strong>field</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
988 <td>Display a property like the
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
989 <strong>plain</strong> displayer above, but in a form field
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
990 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
991 SELECT fields and Multilinks use SELECT MULTIPLE fields.
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>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
994 size (number) - width of TEXT fields.<br>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
995 height (number) - number of nows in SELECT MULTIPLE tags.<br>
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
996 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
997 MULTIPLE fields.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
998 </td></tr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
999
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1000 <tr><td valign="top"><strong>menu</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1001 <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
1002 generated using <strong>field</strong>.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1003 </td></tr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1004
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1005 <tr><td valign="top"><strong>link</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1006 <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
1007 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
1008 <p>
baf901f72977 Updated the documentation for recent html template changes.
Richard Jones <richard@users.sourceforge.net>
parents: 279
diff changeset
1009 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
1010 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1011 <em>Options:</em><br>
602
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
1012 property (property name) - the property to use in the second case.
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1013 </td></tr>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1014
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1015 <tr><td valign="top"><strong>count</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1016 <td>For a Multilink property, display
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1017 a count of the number of links in the list.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1018 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1019 <em>Arguments:</em><br>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1020 property (property name) - the property to use.
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1021
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1022 </td></tr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1023
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1024 <tr><td valign="top"><strong>reldate</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1025 <td>Display a Date property in terms
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1026 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
1027 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1028 <em>Arguments:</em><br>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1029 property (property name) - the property to use.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1030 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1031 <em>Options:</em><br>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1032 pretty (boolean) - display the relative date in an English form.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1033 </td></tr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1034
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1035 <tr><td valign="top"><strong>download</strong></td>
602
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
1036 <td>For a Link or Multilink property, display the names of the linked
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
1037 nodes, hyperlinked to the item views on those nodes.
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
1038 <p>
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
1039 For other properties, link to this node with the property as the text.
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
1040 <p>
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
1041 In all cases, append the name (key property) of the item to the path so it
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
1042 is the name of the file being downloaded.
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1043 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1044 <em>Arguments:</em><br>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1045 property (property name) - the property to use.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1046 </td></tr>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1047
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1048 <tr><td valign="top"><strong>checklist</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1049 <td>For a Link or Multilink property,
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1050 display checkboxes for the available choices to permit filtering.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1051 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1052 <em>Arguments:</em><br>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1053 property (property name) - the property to use.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1054 </td></tr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1055
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1056 <tr><td valign="top"><strong>note</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1057 <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
1058 note to go along with a change.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1059 </td></tr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1060
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1061 <tr><td valign="top"><strong>list</strong></td>
277
20fed9cad7b4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 271
diff changeset
1062 <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
1063 the class.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1064 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1065 <em>Arguments:</em><br>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1066 property (property name) - the property to use.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1067 </td></tr>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1068
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1069 <tr><td valign="top"><strong>history</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1070 <td>List the history of the item.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1071 </td></tr>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1072
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1073 <tr><td valign="top"><strong>submit</strong></td>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1074 <td>Add a submit button for the item.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1075 </td></tr>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1076
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1077 </table>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1078
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1079 <h3>Index Views</h3>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1080
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1081 <p>An index view contains two sections: a filter section
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1082 and an index section.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1083 The filter section provides some widgets for selecting
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1084 which items appear in the index. The index section is
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1085 a table of items.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1086
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1087 <h4>Index View Specifiers</h4>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1088
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1089 <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
1090 has been added for clarity):
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1091
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1092 <blockquote><pre><small
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1093 >/issue?status=unread,in-progress,resolved&amp;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1094 topic=security,ui&amp;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1095 :group=+priority&amp;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1096 :sort=-activity&amp;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1097 :filters=status,topic&amp;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1098 :columns=title,status,fixer
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1099 </small></pre></blockquote>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1100
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1101 <p>The index view is determined by two parts of the
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1102 specifier: the layout part and the filter part.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1103 The layout part consists of the query parameters that
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1104 begin with colons, and it determines the way that the
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1105 properties of selected nodes are displayed.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1106 The filter part consists of all the other query parameters,
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1107 and it determines the criteria by which nodes
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1108 are selected for display.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1109
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1110 <p>The filter part is interactively manipulated with
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1111 the form widgets displayed in the filter section. The
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1112 layout part is interactively manipulated by clicking
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1113 on the column headings in the table.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1114
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1115 <p>The filter part selects the <em>union</em> of the
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1116 sets of items with values matching any specified Link
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1117 properties and the <em>intersection</em> of the sets
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1118 of items with values matching any specified Multilink
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1119 properties.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1120
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1121 <p>The example specifies an index of "issue" nodes.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1122 Only items with a "status" of <em>either</em>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1123 "unread" or "in-progres" or "resolved" are displayed,
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1124 and only items with "topic" values including <em>both</em>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1125 "security" <em>and</em> "ui" are displayed. The items
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1126 are grouped by priority, arranged in ascending order;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1127 and within groups, sorted by activity, arranged in
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1128 descending order. The filter section shows filters
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1129 for the "status" and "topic" properties, and the
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1130 table includes columns for the "title", "status", and
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1131 "fixer" properties.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1132
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1133 <p>Associated with each item class is a default
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1134 layout specifier. The layout specifier in the above
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1135 example is the default layout to be provided with
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1136 the default bug-tracker schema described above in
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1137 section 4.4.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1138
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1139 <h4>Filter Section</h4>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1140
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1141 <p>The template for a filter section provides the
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1142 filtering widgets at the top of the index view.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1143 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
1144 tags are included or omitted depending on whether the
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1145 view specifier requests a filter for a particular property.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1146
602
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
1147 <p>A property must appear in the filter template for it to be available
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
1148 as a filter.
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
1149
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1150 <p>Here's a simple example of a filter template.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1151
602
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
1152 <blockquote><pre><small>&lt;property name=status&gt;
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1153 &lt;display call="checklist('status')"&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1154 &lt;/property&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1155 &lt;br&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1156 &lt;property name=priority&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1157 &lt;display call="checklist('priority')"&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1158 &lt;/property&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1159 &lt;br&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1160 &lt;property name=fixer&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1161 &lt;display call="menu('fixer')"&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1162 &lt;/property&gt;</small></pre></blockquote>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1163
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1164 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1165 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
1166 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
1167 filter template.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1168
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1169 <h4>Index Section</h4>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1170
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1171 <p>The template for an index section describes one row of
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1172 the index table.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1173 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
1174 tags are included or omitted depending on whether the
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1175 view specifier requests a column for a particular property.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1176 The table cells should contain <tt>&lt;display&gt;</tt> tags
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1177 to display the values of the item's properties.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1178
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1179 <p>Here's a simple example of an index template.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1180
602
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
1181 <blockquote><pre><small>&lt;tr&gt;
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1182 &lt;property name=title&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1183 &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
1184 &lt;/property&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1185 &lt;property name=status&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1186 &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
1187 &lt;/property&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1188 &lt;property name=fixer&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1189 &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
1190 &lt;/property&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1191 &lt;/tr&gt;</small></pre></blockquote>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1192
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1193 <h4>Sorting</h4>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1194
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1195 <p>String and Date values are sorted in the natural way.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1196 Link properties are sorted according to the value of the
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1197 "order" property on the linked nodes if it is present; or
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1198 otherwise on the key string of the linked nodes; or
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1199 finally on the node ids. Multilink properties are
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1200 sorted according to how many links are present.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1201
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1202 <h3>Item Views</h3>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1203
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1204 <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
1205 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
1206 items are always displayed.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1207
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1208
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1209
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1210 <h4>Editor Section</h4>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1211
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1212 <p>The editor section is generated from a template
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1213 containing <tt>&lt;display&gt;</tt> tags to insert
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1214 the appropriate widgets for editing properties.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1215
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1216 <p>Here's an example of a basic editor template.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1217
602
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
1218 <blockquote><pre><small>&lt;table&gt;
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1219 &lt;tr&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1220 &lt;td colspan=2&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1221 &lt;display call="field('title', size=60)"&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1222 &lt;/td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1223 &lt;/tr&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1224 &lt;tr&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1225 &lt;td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1226 &lt;display call="field('fixer', size=30)"&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1227 &lt;/td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1228 &lt;td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1229 &lt;display call="menu('status')&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1230 &lt;/td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1231 &lt;/tr&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1232 &lt;tr&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1233 &lt;td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1234 &lt;display call="field('nosy', size=30)"&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1235 &lt;/td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1236 &lt;td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1237 &lt;display call="menu('priority')&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1238 &lt;/td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1239 &lt;/tr&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1240 &lt;tr&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1241 &lt;td colspan=2&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1242 &lt;display call="note()"&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1243 &lt;/td&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1244 &lt;/tr&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1245 &lt;/table&gt;
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1246 </small></pre></blockquote>
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1247
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1248 <p>As shown in the example, the editor template can also
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1249 request the display of a "note" field, which is a
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1250 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
1251
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1252 <p>When a change is submitted, the system automatically
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1253 generates a message describing the changed properties.
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1254
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1255 <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
1256 appended to the description. The message is then added
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1257 to the item's message spool (thus triggering the standard
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1258 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
1259
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1260 <p>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1261 The message also displays all of the property values on the
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1262 item and indicates which ones have changed.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1263 An example of such a message might be this:
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1264
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1265 <blockquote><pre>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1266 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
1267 -----
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1268 title: Polly Parrot is dead
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1269 priority: critical
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1270 status: unread -&gt; in-progress
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1271 fixer: terry
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1272 keywords: parrot,plumage,perch,nailed,dead
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1273 </pre></blockquote>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1274
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1275 <h4>Spool Section</h4>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1276
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1277 <p>The spool section lists messages in the item's "messages"
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1278 property. The index of messages displays the "date", "author",
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1279 and "summary" properties on the message nodes, and selecting a
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1280 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
1281
257
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1282 <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
1283 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
1284 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
1285 property has no entries.
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1286
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1287 <blockquote><pre>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1288 &lt;property name="files"&gt;
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1289 &lt;tr class="strong-header"&gt;
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1290 &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
1291 &lt;/tr&gt;
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1292
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1293 &lt;tr&gt;
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1294 &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
1295 &lt;/tr&gt;
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1296 &lt;/property&gt;
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1297 </pre></blockquote>
2a77a461cc33 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 256
diff changeset
1298
255
d4ef19ef17bd Bug fix for test_init on Windows.
Richard Jones <richard@users.sourceforge.net>
parents: 254
diff changeset
1299 <p><hr>
256
0fb85acfa9e4 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 255
diff changeset
1300 <h1><a name="ack">Acknowledgements</a></h1>
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1301
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1302 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
1303 system on their time.
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1304
254
af6e10660e27 cvs tag
Richard Jones <richard@users.sourceforge.net>
parents: 253
diff changeset
1305 <p>&nbsp;</p>
af6e10660e27 cvs tag
Richard Jones <richard@users.sourceforge.net>
parents: 253
diff changeset
1306 <hr>
602
c242455d9b46 Brought the config branch up to date with HEAD
Richard Jones <richard@users.sourceforge.net>
parents: 469
diff changeset
1307 $Id: index.html,v 1.23.2.1 2002-02-06 04:05:53 richard Exp $
254
af6e10660e27 cvs tag
Richard Jones <richard@users.sourceforge.net>
parents: 253
diff changeset
1308 <p>&nbsp;</p>
af6e10660e27 cvs tag
Richard Jones <richard@users.sourceforge.net>
parents: 253
diff changeset
1309
251
2f4123c715f1 Started working on some _real_ documentation!
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1310 </body></html>
Roundup Issue Tracker: http://roundup-tracker.org/