![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: 6744bff)
raw | patch | inline | side by side (parent: 6744bff)
| author | richard <richard@57a73879-2fb5-44c3-a270-3262357dd7e2> | |
| Fri, 8 Mar 2002 23:41:46 +0000 (23:41 +0000) | ||
| committer | richard <richard@57a73879-2fb5-44c3-a270-3262357dd7e2> | |
| Fri, 8 Mar 2002 23:41:46 +0000 (23:41 +0000) |
Use build_html.py *.stx to build the HTML. We'll move that into the setup
script when someone figures how to :)
git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@665 57a73879-2fb5-44c3-a270-3262357dd7e2
script when someone figures how to :)
git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@665 57a73879-2fb5-44c3-a270-3262357dd7e2
| doc/build_html.py | [new file with mode: 0755] | patch | blob |
| doc/default.css | [new file with mode: 0644] | patch | blob |
| doc/index.html | patch | blob | history | |
| doc/index.stx | [new file with mode: 0644] | patch | blob |
| doc/installation.stx | patch | blob | history |
diff --git a/doc/build_html.py b/doc/build_html.py
--- /dev/null
+++ b/doc/build_html.py
@@ -0,0 +1,31 @@
+#!/usr/bin/env python
+
+"""
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:Revision: $Revision: 1.1 $
+:Date: $Date: 2002-03-08 23:41:46 $
+:Copyright: This module has been placed in the public domain.
+
+A minimal front-end to the Docutils Publisher.
+
+This module takes advantage of the default values defined in `publish()`.
+"""
+
+import sys, os.path
+from dps.core import publish
+from dps import utils
+
+if len(sys.argv) < 2:
+ print >>sys.stderr, 'I need at least one filename'
+ sys.exit(1)
+
+reporter = utils.Reporter(2, 4)
+
+for file in sys.argv[1:]:
+ name, ext = os.path.splitext(file)
+ dest = '%s.html'%name
+ print >>sys.stderr, '%s -> %s'%(file, dest)
+ publish(writername='html', source=file, destination=dest,
+ reporter=reporter)
+
diff --git a/doc/default.css b/doc/default.css
--- /dev/null
+++ b/doc/default.css
@@ -0,0 +1,131 @@
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:date: $Date: 2002-03-08 23:41:46 $
+:version: $Revision: 1.1 $
+:copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+*/
+
+a.footnote-reference {
+ font-size: smaller;
+ vertical-align: super }
+
+col.docinfo-name {
+ font-weight: bold;
+ text-align: right }
+
+col.field-name {
+ font-weight: bold }
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract h6 {
+ font-size: larger;
+ text-align: center }
+
+div.attention, div.caution, div.danger, div.error, div.hint,
+div.important, div.note, div.tip, div.warning {
+ margin: 2em;
+ border: medium outset;
+ padding: 1em }
+
+div.attention h3, div.caution h3, div.danger h3, div.error h3,
+div.warning h3 {
+ color: red;
+ font-weight: bold;
+ font-family: sans-serif }
+
+div.hint h3, div.important h3, div.note h3, div.tip h3 {
+ font-weight: bold;
+ font-family: sans-serif }
+
+div.field-body {
+ margin-bottom: 1em }
+
+div.field-list {
+ margin-bottom: -1em }
+
+div.figure {
+ margin-left: 2em }
+
+div.footnote {
+ border-left: solid thin black;
+ padding-left: 1em }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset;
+ padding: 1em }
+
+div.system-message h3 {
+ color: red }
+
+dt {
+ margin-bottom: -1em }
+
+h1.title {
+ text-align: center }
+
+h2.subtitle {
+ text-align: center }
+
+hr {
+ width: 75% }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.caption {
+ font-style: italic }
+
+p.field-name {
+ margin-bottom: 1em }
+
+pre.literal-block, pre.doctest-block {
+ margin-left: 2em }
+
+span.classifier {
+ font-family: sans-serif;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif;
+ font-weight: bold }
+
+span.field-argument {
+ font-style: italic }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option-argument {
+ font-style: italic }
+
+span.problematic {
+ color: red }
+
+table {
+ margin-top: 1em }
+
+table.docinfo {
+ margin: 2em 4em }
diff --git a/doc/index.html b/doc/index.html
index 3e05a2f01f968ebb0061063f8497978d2ac83ace..0d8a20de93cf4c33b6619cf2389d53f7444d409f 100644 (file)
--- a/doc/index.html
+++ b/doc/index.html
-<html><head>
-<title>Roundup: an Issue-Tracking System for Knowledge Workers</title>
-</head><body>
-
-<h1 align=center>Roundup (0.3.1)</h1>
-<h3 align=center>An Issue-Tracking System for Knowledge Workers</h2>
-
-<h1>Contents</h1>
-
-<ul>
- <li><a href="overview.html">Overview</a> (Initial submission to SC Track)
-<li><a href="#installation">Installation</a>
- <ul>
- <li><a href="#requires">Prerequisites</a>
- <li><a href="#getting">Getting Roundup</a>
- <li><a href="#installing">Installing Roundup</a>
- </ul>
-<li><a href="#starting">Getting Started</a>
- <ul>
- <li><a href="#instance">The Instance</a>
- <li><a href="#startcmd">Command Line Tool</a>
- <li><a href="#startmail">E-Mail Interface</a>
- <li><a href="#startweb">Web Interface</a>
- <li><a href="#users">Users and Access Control</a> (Users and permissions, Adding users)
- <li><a href="#issues">Issues</a>
- </ul>
-<li><a href="#guide">User Guide</a>
- <ul>
- <li><a href="#cmd">Command Line Tool</a>
- <li><a href="#web">Web Interface</a>
- <li><a href="#mail">E-Mail Gateway</a> (Message content summary, Address handling, Performing Actions)
- </ul>
-<li><a href="#custom">Customising Roundup</a>
- <ul>
- <li><a href="#config">Instance Configuration</a>
- <li><a href="#custinst">Instance Schema</a> (Creating a new information store)
- <li><a href="#custweb">Web Interface</a> (Displaying properties, Index views, Item views)
- </ul>
-<li><a href="spec.html">Roundup's Design Document</a> ("Implementation Guide")
-<li><a href="#ack">Acknowledgements</a>
-</ul>
-
-<p><hr>
-<h1><a name="installation">Installation</a></h1>
-
-
-<h2><a name="requires">Prerequisites</a></h2>
-
-<p>
-Python 2.1.1 is required for the correct operation of roundup.
-</p>
-
-<p>
-Download the latest version from
-<a href="http://www.python.org/">http://www.python.org/</a>.
-</p>
-
-
-
-<h2><a name="getting">Getting Roundup</a></h2>
-
-Download the latest version from
-<a href="http://roundup.sf.net/">http://roundup.sf.net/</a>.
-
-
-<h2><a name="installing">Installing Roundup</a></h2>
-
-<ol>
- <li>Run:
- <br><tt>python setup.py install</tt>
- <li>If you would prefer the scripts installed in somewhere other than
- <tt>/usr/local/bin</tt>, add <tt>"--install-scripts=<dir>"</tt>
- to the command:
- <br><tt>python setup.py install --install-scripts=<dir></tt>
- <li>The command:
- <br><tt>python setup.py install --help</tt>
- <br>gives all the options available for installation.
-</ol>
-
-
-<p><hr>
-<h1><a name="starting">Getting Started</a></h1>
-
-The following instructions assume that you have installed roundup. If you
-haven't, you may still proceed - just preface all commands with "./"
-ie. "./roundup-admin init".
-
-
-<h2><a name="instance">The Instance</a></h2>
-
-We'll be referring to the term <em>instance</em> a lot from now on. An
-instance is
-a directory in your filesystem that is where all the information about a
-live issue tracker database is stored. The data that is entered as issues,
-the users who access the database and the definition of the database itself
-all reside there:
-<ol>
- <li><strong>Hyperdatabase</strong>
- <br>This is the lowest component of Roundup and is where all the
- issues, users, file attachments and messages are stored.
- <li><strong>Database schema</strong>
- <br>This describes the content of the hyperdatabase - what fields are
- stored for issues, what user information, etc. Being stored in the
- instance, this allows it to be customised for a particular application.
- It also means that changes in the Roundup core code do not affect a
- running instance.
- <li><strong>Web Interface</strong>
- <br>The web interface templates are defined in the instance too - and
- the actual CGI interface class is defined (mostly using base classes in
- the Roundup core code) so it, like the database, may be customised for
- each instance in use.
-</ol>
-
-Instances are created using the <tt>roundup-admin</tt> tool.
-
-<h2><a name="startcmd">Command Line Tool</a></h2>
-
-To initiliase a new instance, run <tt>roundup-admin init</tt>. You will be
-asked a series of questions:
-
-<ol>
- <li>Instance home directory
- <li>Schema to use
- <li>Database back-end to use
- <li>Administration user "admin" password.
-</ol>
-
-You should also think about whether there is going to be controlled access
-to the instance on the machine the instance is running on. That is, who can
-actually make changes to the database using the roundup-admin tool. See
-the section on <a href="#users">Users and Access Control</a> for
-information on how to secure your instance from the start.
-
-<p>
-
-Roundup is configurable using an instance_config.py file in the instance home.
-It should be edited before roundup is used, and may have the following
-variable declarations:
-
-<ol>
- <li>MAILHOST
- <br>The SMTP mail host that roundup will use to send mail
- <li>MAIL_DOMAIN
- <br>The domain name used for email addresses
- <li>ISSUE_TRACKER_WEB
- <br>The web address of the issue tracker's web interface
-</ol>
-
-<p>
-The email addresses used by the system by default are:
-
-<ol>
- <li>ISSUE_TRACKER_EMAIL - issue_tracker@MAIL_DOMAIN
- <br>submissions of issues
- <li>ADMIN_EMAIL - roundup-admin@MAIL_DOMAIN
- <br>roundup's internal use (problems, etc)
-</ol>
-
-<h2><a name="startmail">E-Mail Interface</a></h2>
-
-<h3>Setup 1: As a mail alias pipe process</h3>
-Set up a mail alias called "issue_tracker" as (include the quote marks):
-<blockquote>
- <tt>"|/usr/bin/python /usr/local/bin/roundup-mailgw <instance_home>"</tt>
-</blockquote>
-
-In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh
-so sendmail will accept the pipe command. In that case, symlink
-/etc/smrsh/roundup-mailgw to /usr/local/bin/roundup-mailgw and change the
-command to:
-<blockquote>
- <tt>|roundup-mailgw <instance_home></tt>
-</blockquote>
-
-To test the mail gateway on unix systems, try:
-
-<blockquote>
- <tt>echo test |mail -s '[issue] test' issue_tracker@your.domain</tt>
-</blockquote>
-
-
-<h3>Setup 2: As a regular cron job using a mailbox source</h3>
-Set the roundup-mailgw up to run every 10 minutes or so. For example:
-<blockquote>
- <tt>10 * * * * /usr/local/bin/roundup-mailgw <instance_home> mailbox <mail_spool_file></tt>
-</blockquote>
-Where the mail_spool_file argument is the location of the roundup
-submission user's mail spool. On most systems, the spool for a user
-"issue_tracker" will be "/var/mail/issue_tracker".
-
-<h3>Setup 3: As a regular cron job using a POP source</h3>
-To retrieve from a POP mailbox, use a similar cron entry to the mailbox
-one:
-<blockquote>
- <tt>10 * * * * /usr/local/bin/roundup-mailgw <instance_home> pop <pop_spec></tt>
-</blockquote>
-where pop_spec is "username:password@server" that specifies the roundup
-submission user's POP account name, password and server.
-
-<h2><a name="startweb">Web Interface</a></h2>
-This software will work through apache or stand-alone.
-<p>
-<strong>Stand-alone:</strong>
-<ol>
- <li>Edit roundup-server at the top - ROUNDUP_INSTANCE_HOMES needs to know
- about your instance. You may also specify the values for
- ROUNDUP_INSTANCE_HOMES on the command-line using "name=home" pairs.
- <li><tt>roundup-server [hostname port]</tt> (hostname may be "")
- <li>Load up the page <tt>/<instance name>/index</tt> where
- instance name is the
- name you nominated in <tt>ROUNDUP_INSTANCE_HOMES</tt>.
-</ol>
-
-<strong>Apache:</strong>
-<ol>
-<li>The CGI script is found in the cgi-bin directory of the roundup
- distribution.
-</li>
-<li>Make sure roundup.cgi is executable. Edit it at the top -
- ROUNDUP_INSTANCE_HOMES needs to know about your instance.
-</li>
-<li>Edit your /etc/httpd/conf/httpd.conf and make sure that the
- /home/httpd/html/roundup/roundup.cgi script will be treated as a CGI
- script.
-</li>
-<li>Re-start your apache to re-load the config if necessary.
-</li>
-<li>Load up the page "/roundup/roundup.cgi/<instance name>/index" where
- instance name is the name you nominated in ROUNDUP_INSTANCE_HOMES.
-</li>
-<li>To use the CGI script unchanged, which allows much easier updates,
- add these directives to your "httpd.conf":
- <pre>
- SetEnv ROUNDUP_LOG "/var/log/roundup.log"
- SetEnv ROUNDUP_INSTANCE_HOMES "Default=/usr/local/share/roundup/instances/Default"
- SetEnv ROUNDUP_DEBUG "0"
-</pre>
-</li>
-<li>On Windows, write a batch file "roundup.bat" similar to the one below
- and place it into your cgi-bin directory:
- <pre>
- @echo off
- set ROUNDUP_LOG=c:\Python21\share\roundup\cgi.log
- set ROUNDUP_INSTANCE_HOMES=Default=c:\Python21\share\roundup\instances\Default;
- set ROUNDUP_DEBUG=0
- c:\Python21\python.exe c:\Python21\share\roundup\cgi-bin\roundup.cgi
-</pre>
-</li>
-</ol>
-
-
-
-
-<h2><a name="users">Users</a></h2>
-
-<h3>Users and permissions</h3>
-By default, roundup automatically creates one user when the instance
-database is initialised (using roundup-admin init). The user is "admin" and
-the password is the one you supply at that time.
-<p>
-If users attempt to use roundup in any manner and are not identified to
-roundup, they will be using the database in a read-only mode. That is, if
-roundup doesn't know who they are, they can't change anything. This has the
-following repurcussions:
-<dl>
-<dt><strong>Command-line interface</strong>
-<dd>The data modification commands (create, init, retire, set) are
-performed as the "admin" user. It is therefore important that the database
-be protected by the filesystem if protection is required. On a Unix system,
-the easiest and most flexible method of doing so is:
-<ol>
-<li>Add a new user and group to your system (e.g. "issue_tracker")
-<li>When creating a new instance home, use the following commands
-(substituting instance_home for the directory you want to use):<br>
-<pre>
-mkdir instance_home
-chown issue_tracker:issue_tracker instance_home
-chmod g+rwxs instance_home
-roundup-admin -i instance_home init
-</pre>
-<li>Now, edit the /etc/group line for the issue_tracker group so it includes
-the unix logins of all the users who are going to administer your roundup
-instance. If you're running the web or mail gateways, then be sure to
-include those users in the group too (on some Linux systems, these
-users are "www" or "apache" and "mail".)
-</ol>
-
-<dt><strong>E-Mail interface</strong>
-<dd>Users are identified by e-mail address - a new user entry will be
-created for any e-mail address that is not recognised, so users are
-<em>always</em> identified by roundup.
-<dt><strong>Web interface</strong>
-<dd>Unidentified users have read-only access. If the users database has an
-entry with the username "anonymous", then unidentified users are
-automatically logged in as that user. This gives them write access.
-</dl>
-<p>
-*** anonymous access and the ANONYMOUS_* configuratins.
-
-<h3>Adding users</h3>
-To add users, use one of the following interfaces:
-
-<ol>
- <li>On the web, access the URL <tt>.../<instance name>/newuser</tt>
- to bring up a form which may be used to add a new user.
- <li>On the command-line, use:
- <br><tt>roundup-admin -i <instance home> create user
- username=bozo password=bozo address=richard@clown.org</tt>
- <br>Supply the admin username and password. roundup-admin will print the
- id of the new user.
- <li>Any e-mail sent to roundup from an address that doesn't match an
- existing user in the database will result in a new user entry being
- created for that user.
-</ol>
-
-
-
-<h2><a name="issues">Issues</a></h2>
-To add issues, use one of the following interfaces:
-
-<ol>
- <li>On the web, access the URL <tt>.../<instance name>/newissue</tt>
- to bring up a form which may be used to add a new issue.
- <li>On the command-line, use:
- <br><tt>roundup-admin -i <instance home> create issue
- title="test issue"</tt>
- <br>Supply the admin username and password. roundup-admin will print the
- id of the new issue.
- <li>Any e-mail sent to roundup with the subject line containing [issue]
- will automatically created a new issue in the database using the
- contents of the e-mail.
-</ol>
-
-<p><hr>
-<h1><a name="guide">User Guide</a></h1>
-<h2><a name="cmd">Command Line Tool</a></h2>
-
-Usage:
-<tt>roundup-admin [-i instance home] [-u login] [-c] <command>
- <arguments></tt>
-
-<p>
-<table><tr><th colspan=2>Options:</th></tr>
- <tr><td>-i instance home </td><td>specify the issue tracker "home directory" to administer
- </td></tr>
- <tr><td>-u </td><td>the user[:password] to use for commands
- </td></tr>
- <tr><td>-c </td><td>when outputting lists of data, just comma-separate them
- </td></tr>
-</table>
-
-<p>
-<table width=100% border=1 cellspacing=0>
-<tr><th colspan=2>Command Help</th></tr>
-
-
-<tr><td valign=top><strong>commit</strong></td>
- <td><tt>Usage: commit</tt><p>
-<pre>
-The changes made during an interactive session are not
-automatically written to the database - they must be committed
-using this command.
-
-One-off commands on the command-line are automatically committed if
-they are successful.
-
-</pre></td></tr>
-
-
-<tr><td valign=top><strong>create</strong></td>
- <td><tt>Usage: create classname property=value ...</tt><p>
-<pre>
-This creates a new entry of the given class using the property
-name=value arguments provided on the command line after the "create"
-command.
-
-</pre></td></tr>
-
-
-<tr><td valign=top><strong>display</strong></td>
- <td><tt>Usage: display designator</tt><p>
-<pre>
-This lists the properties and their associated values for the given
-node.
-
-</pre></td></tr>
-
-
-<tr><td valign=top><strong>export</strong></td>
- <td><tt>Usage: export class[,class] destination_dir</tt><p>
-<pre>
-This action exports the current data from the database into
-tab-separated-value files that are placed in the nominated destination
-directory. The journals are not exported.
-
-</pre></td></tr>
-
-
-<tr><td valign=top><strong>find</strong></td>
- <td><tt>Usage: find classname propname=value ...</tt><p>
-<pre>
-Find the nodes of the given class with a given link property value. The
-value may be either the nodeid of the linked node, or its key value.
-
-</pre></td></tr>
-
-
-<tr><td valign=top><strong>get</strong></td>
- <td><tt>Usage: get property designator[,designator]*</tt><p>
-<pre>
-Retrieves the property value of the nodes specified by the designators.
-
-</pre></td></tr>
-
-
-<tr><td valign=top><strong>help</strong></td>
- <td><tt>Usage: help topic</tt><p>
-<pre>
-commands -- list commands
-<command> -- help specific to a command
-initopts -- init command options
-all -- all available help
-
-</pre></td></tr>
-
-
-<tr><td valign=top><strong>history</strong></td>
- <td><tt>Usage: history designator</tt><p>
-<pre>
-Lists the journal entries for the node identified by the designator.
-
-</pre></td></tr>
-
-
-<tr><td valign=top><strong>import</strong></td>
- <td><tt>Usage: import class file</tt><p>
-<pre>
-The file must define the same properties as the class (including having
-a "header" line with those property names.) The new nodes are added to
-the existing database - if you want to create a new database using the
-imported data, then create a new database (or, tediously, retire all
-the old data.)
-
-</pre></td></tr>
-
-
-<tr><td valign=top><strong>initialise</strong></td>
- <td><tt>Usage: initialise [template [backend [admin password]]]</tt><p>
-<pre>
-The command will prompt for the instance home directory (if not supplied
-through INSTANCE_HOME or the -i option. The template, backend and admin
-password may be specified on the command-line as arguments, in that
-order.
-
-See also initopts help.
-
-</pre></td></tr>
-
-
-<tr><td valign=top><strong>list</strong></td>
- <td><tt>Usage: list classname [property]</tt><p>
-<pre>
-Lists all instances of the given class. If the property is not
-specified, the "label" property is used. The label property is tried
-in order: the key, "name", "title" and then the first property,
-alphabetically.
-
-</pre></td></tr>
-
-
-<tr><td valign=top><strong>retire</strong></td>
- <td><tt>Usage: retire designator[,designator]*</tt><p>
-<pre>
-This action indicates that a particular node is not to be retrieved by
-the list or find commands, and its key value may be re-used.
-
-</pre></td></tr>
-
-
-<tr><td valign=top><strong>rollback</strong></td>
- <td><tt>Usage: rollback</tt><p>
-<pre>
-The changes made during an interactive session are not
-automatically written to the database - they must be committed
-manually. This command undoes all those changes, so a commit
-immediately after would make no changes to the database.
-
-</pre></td></tr>
-
-
-<tr><td valign=top><strong>set</strong></td>
- <td><tt>Usage: set designator[,designator]* propname=value ...</tt><p>
-<pre>
-Sets the property to the value for all designators given.
-
-</pre></td></tr>
-
-
-<tr><td valign=top><strong>specification</strong></td>
- <td><tt>Usage: specification classname</tt><p>
-<pre>
-This lists the properties for a given class.
-
-</pre></td></tr>
-
-
-<tr><td valign=top><strong>table</strong></td>
- <td><tt>Usage: table classname [property[,property]*]</tt><p>
-<pre>
-Lists all instances of the given class. If the properties are not
-specified, all properties are displayed. By default, the column widths
-are the width of the property names. The width may be explicitly defined
-by defining the property as "name:width". For example::
- roundup> table priority id,name:10
- Id Name
- 1 fatal-bug
- 2 bug
- 3 usability
- 4 feature
-
-</pre></td></tr>
-
-</table>
-
-<p>
-All commands (except help) require an instance specifier. This is just the path
-to the roundup instance you're working with. A roundup instance is where
-roundup keeps the database and configuration file that defines an issue
-tracker. It may be thought of as the issue tracker's "home directory". It may
-be specified in the environment variable ROUNDUP_INSTANCE or on the command
-line as "-i instance".
-
-<p>
-A designator is a classname and a nodeid concatenated, eg. bug1, user10, ...
-
-<p>
-Property values are represented as strings in command arguments and in the
-printed results:
-<ul>
- <li>Strings are, well, strings.
- <li>Password values will display as their encoded value.
- <li>Date values are printed in the full date format in the local time zone, and
- accepted in the full format or any of the partial formats explained below.
-<table>
- <tr><th>Input of...</th><th>Means...</th></tr>
- <tr><td>"2000-04-17.03:45"</td><td>2000-04-17.08:45:00</td></tr>
- <tr><td>"2000-04-17"</td><td>2000-04-17.00:00:00</td></tr>
- <tr><td>"01-25"</td><td>yyyy-01-25.00:00:00</td></tr>
- <tr><td>"08-13.22:13"</td><td>yyyy-08-14.03:13:00</td></tr>
- <tr><td>"11-07.09:32:43"</td><td>yyyy-11-07.14:32:43</td></tr>
- <tr><td>"14:25"</td><td>yyyy-mm-dd.19:25:00</td></tr>
- <tr><td>"8:47:11"</td><td>yyyy-mm-dd.13:47:11</td></tr>
- <tr><td>"."</td><td>"right now"</td></tr>
-</table>
- <li>Link values are printed as node designators. When given as an argument,
- node designators and key strings are both accepted.
- <li>Multilink values are printed as lists of node designators joined by commas.
- When given as an argument, node designators and key strings are both
- accepted; an empty string, a single node, or a list of nodes joined by
- commas is accepted.
-</ul>
-When multiple nodes are specified to the roundup get or roundup set
-commands, the specified properties are retrieved or set on all the listed
-nodes.
-<p>
-When multiple results are returned by the roundup get or roundup find
-commands, they are printed one per line (default) or joined by commas (with
-the -c) option.
-<p>
-Where the command changes data, a login name/password is required. The
-login may be specified as either "name" or "name:password".
-<ul>
- <li>ROUNDUP_LOGIN environment variable
- <li>the -u command-line option
-</ul>
-If either the name or password is not supplied, they are obtained from the
-command-line.
-
-<h2><a name="web">Web Interface</a></h2>
-Index views may be modified by the following arguments:
-<pre>
- :sort - sort by prop name, optionally preceeded with '-'
- to give descending or nothing for ascending sorting.
- :group - group by prop name, optionally preceeded with '-' or
- to sort in descending or nothing for ascending order.
- :filter - selects which props should be displayed in the filter
- section. Default is all.
- :columns - selects the columns that should be displayed.
- Default is all.
- propname - selects the values the node properties given by propname
- must have (very basic search/filter).
-</pre>
-
-<strong>Not sure what to put in here...</strong>
-
-<h2><a name="mail">E-Mail Gateway</a></h2>
-
-<h3>Performing Actions</h3>
-The subject line of the incoming message is examined to determine whether
-the message is an attempt to create a new item or to discuss an existing
-item. A designator enclosed in square brackets is sought as the first thing
-on the subject line (after skipping any "Fwd:" or "Re:" prefixes).
-<p>
-If an item designator (class name and id number) is found there, the newly
-created "msg" node is added to the "messages" property for that item, and
-any new "file" nodes are added to the "files" property for the item.
-<p>
-If just an item class name is found there, we attempt to create a new item
-of that class with its "messages" property initialized to contain the new
-"msg" node and its "files" property initialized to contain any new "file"
-nodes.
-
-<h3>Setting Properties</h3>
-The e-mail interface also provides a simple way to set
-properties on items. At the end of the subject line,
-<em>propname</em><tt>=</tt><em>value</em> pairs can be
-specified in square brackets, using the same conventions
-as for the <tt>roundup set</tt> shell command.
-explanatory message given in the exception.
-
-<h3>Message content</h3>
-Incoming messages are examined for multiple parts:
-<ul>
-<li>In a multipart/mixed message or part, each subpart is extracted and
- examined. The text/plain subparts are assembled to form the textual
- body of the message, to be stored in the file associated with a "msg"
- class node. Any parts of other types are each stored in separate files
- and given "file" class nodes that are linked to the "msg" node.
-<li>In a multipart/alternative message or part, we look for a text/plain
- subpart and ignore the other parts.
-</ul>
-
-<h4>Message summary</h4>
-The "summary" property on message nodes is taken from the first non-quoting
-section in the message body. The message body is divided into sections by
-blank lines. Sections where the second and all subsequent lines begin with
-a ">" or "|" character are considered "quoting sections". The first line of
-the first non-quoting section becomes the summary of the message.
-
-<h3>Address handling</h3>
-All of the addresses in the To: and Cc: headers of the incoming message are
-looked up among the user nodes, and the corresponding users are placed in
-the "recipients" property on the new "msg" node. The address in the From:
-header similarly determines the "author" property of the new "msg"
-node. The default handling for addresses that don't have corresponding
-users is to create new users with no passwords and a username equal to the
-address. (The web interface does not permit logins for users with no
-passwords.) If we prefer to reject mail from outside sources, we can simply
-register an auditor on the "user" class that prevents the creation of user
-nodes with no passwords.
-
-<h3>Triggers</h3>
-Both cases may trigger detectors (in the first case we are calling the
-set() method to add the message to the item's spool; in the second case we
-are calling the create() method to create a new node). If an auditor raises
-an exception, the original message is bounced back to the sender with the
-
-<h4>Nosy Lists</h4>
-A standard detector is provided that watches for additions
-to the "messages" property. When a new message is added, the
-detector sends it to all the users on the "nosy" list for the
-item that are not already on the "recipients" list of the
-message. Those users are then appended to the "recipients"
-property on the message, so multiple copies of a message
-are never sent to the same user. The journal recorded by
-the hyperdatabase on the "recipients" property then provides
-a log of when the message was sent to whom.
-
-<p><hr>
-<h1><a name="custom">Customising Roundup</a></h1>
-
-Instances have the following structure:
-<table>
- <tr><td valign=top><strong>instance_config.py</strong></td>
- <td>Holds the basic <a href="#config">instance configuration</a></td></tr>
- <tr><td valign=top><strong>dbinit.py</strong></td>
- <td>Holds the <a href="#custinst">instance schema</a></td></tr>
- <tr><td valign=top><strong>interfaces.py</strong></td>
- <td>Defines the <a href="#custweb">Web</a> and E-Mail interfaces for the instance</td></tr>
- <tr><td valign=top><strong>select_db.py</strong></td>
- <td>Selects the database back-end for the instance</td></tr>
- <tr><td valign=top><strong>db/</strong></td>
- <td>Holds the instance's database</td></tr>
- <tr><td valign=top><strong>db/files/</strong></td>
- <td>Holds the instance's upload files and messages</td></tr>
- <tr><td valign=top><strong>detectors/</strong></td>
- <td>Auditors and reactors for this instance</td></tr>
- <tr><td valign=top><strong>html/</strong></td>
- <td>Web interface <a href="#custweb">templates</a>, images and style sheets</td></tr>
-</table>
-
-<h2><a name="config">Instance Configuration</a></h2>
-The <tt>instance_config.py</tt> located in your instance home contains the
-basic configuration for the web and e-mail components of roundup's
-interfaces. This file is a Python module. The default
-<tt>instance_config.py</tt> is given below - as you can see, the
-MAIL_DOMAIN must be edited before any interaction with the instance is
-attempted.
-
-<p>
-<pre>
-MAIL_DOMAIN=MAILHOST=HTTP_HOST=None
-HTTP_PORT=0
-
-# roundup home is this package's directory
-INSTANCE_HOME=os.path.split(__file__)[0]
-
-# The SMTP mail host that roundup will use to send mail
-if not MAILHOST:
- MAILHOST = 'localhost'
-
-# The domain name used for email addresses.
-if not MAIL_DOMAIN:
- MAIL_DOMAIN = 'fill.me.in.'
-
-# the next two are only used for the standalone HTTP server.
-if not HTTP_HOST:
- HTTP_HOST = ''
-if not HTTP_PORT:
- HTTP_PORT = 9080
-
-# This is the directory that the database is going to be stored in
-DATABASE = os.path.join(INSTANCE_HOME, 'db')
-
-# This is the directory that the HTML templates reside in
-TEMPLATES = os.path.join(INSTANCE_HOME, 'html')
-
-# The email address that mail to roundup should go to
-ISSUE_TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN
-
-# The web address that the instance is viewable at
-ISSUE_TRACKER_WEB = 'http://some.useful.url/'
-
-# The email address that roundup will complain to if it runs into trouble
-ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
-
-# Somewhere for roundup to log stuff internally sent to stdout or stderr
-LOG = os.path.join(INSTANCE_HOME, 'roundup.log')
-
-# Where to place the web filtering HTML on the index page
-FILTER_POSITION = 'bottom' # one of 'top', 'bottom', 'top and bottom'
-
-# Deny or allow anonymous access to the web interface
-ANONYMOUS_ACCESS = 'deny'
-
-# Deny or allow anonymous users to register through the web interface
-ANONYMOUS_REGISTER = 'deny'
-
-# Send nosy messages to the author of the message
-MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no'
-</pre>
-
-<h2><a name="custinst">Instance Schema</a></h2>
-<b>Note:</b> if you modify the schema, you'll most likely need to
-<a href="#schemarepurcussions">
-web interface to reflect your changes</a>.
-<p>
-An instance schema defines what data is stored in the instance's database.
-The two schemas shipped with Roundup turn it into a typical software bug
-tracker (the extended schema allowing for support issues as well as bugs).
-Schemas are defined using Python code. The "classic" schema looks like
-this:
-<p>
-<pre>
- pri = Class(db, "priority", name=String(), order=String())
- pri.setkey("name")
- pri.create(name="critical", order="1")
- pri.create(name="urgent", order="2")
- pri.create(name="bug", order="3")
- pri.create(name="feature", order="4")
- pri.create(name="wish", order="5")
-
- stat = Class(db, "status", name=String(), order=String())
- stat.setkey("name")
- stat.create(name="unread", order="1")
- stat.create(name="deferred", order="2")
- stat.create(name="chatting", order="3")
- stat.create(name="need-eg", order="4")
- stat.create(name="in-progress", order="5")
- stat.create(name="testing", order="6")
- stat.create(name="done-cbb", order="7")
- stat.create(name="resolved", order="8")
-
- keyword = Class(db, "keyword", name=String())
- keyword.setkey("name")
-
- user = Class(db, "user", username=String(), password=String(),
- address=String(), realname=String(), phone=String(), organisation=String())
- user.setkey("username")
- user.create(username="admin", password=adminpw, address=instance_config.ADMIN_EMAIL)
-
- msg = FileClass(db, "msg", author=Link("user"), recipients=Multilink("user"),
- date=Date(), summary=String(), files=Multilink("file"))
-
- file = FileClass(db, "file", name=String(), type=String())
-
- issue = IssueClass(db, "issue", assignedto=Link("user"),
- topic=Multilink("keyword"), priority=Link("priority"), status=Link("status"))
- issue.setkey('title')
-</pre>
-
-<h3>Classes and Properties - creating a new information store</h3>
-In the instance above, we've defined 7 <em>classes</em> of information:
-<dl>
- <dt><strong>priority</strong>
- <dd>Defines the possible levels of urgency for issues.
- <dt><strong>status</strong>
- <dd>Defines the possible states of processing the issue may be in.
- <dt><strong>keyword</strong>
- <dd>Initially empty, will hold keywords useful for searching issues.
- <dt><strong>user</strong>
- <dd>Initially holding the "admin" user, will eventually have an entry
- for all users using roundup.
- <dt><strong>msg</strong>
- <dd>Initially empty, will all e-mail messages sent to or generated by roundup.
- <dt><strong>file</strong>
- <dd>Initially empty, will all files attached to issues.
- <dt><strong>issue</strong>
- <dd>Initially emtyp, this is where the issue information is stored.
-</dl>
-<p>
-We define the "priority" and "status" classes to allow two things: reduction
-in the amount of information stored on the issue and more powerful, accurate
-searching of issues by priority and status. By only requiring a link on
-the issue (which is stored as a single number) we reduce the chance
-that someone mis-types a priority or status - or simply makes a new one
-up.
-
-<h4>Class and Nodes</h4>
-A <em>Class</em> defines a particular class (or type) of data that will be
-stored in the database. A class comprises one or more properties, which
-given the information about the class nodes.
-<p>
-The actual data entered into the database, using <em>class</em>.create()
-are called <em>nodes</em>. They have a special immutable property called
-id. We sometimes refer to this as the <em>nodeid</em>.
-
-
-<h4>Properties</h4>
-A Class is comprised of one or more <em>properties</em> of the following types:
-
-<ul>
-<li><em>String</em> properties are for storing arbitrary-length
-strings.
-
-<li><em>Password</em> properties are for storing encoded arbitrary-length
-strings. The default encoding is defined on the roundup.password.Password
-class.
-
-<li><em>Date</em> properties store date-and-time stamps.
-Their values are Timestamp objects.
-
-<li>A <em>Link</em> property refers to a single other node
-selected from a specified class. The class is part of the property;
-the value is an integer, the id of the chosen node.
-
-<li>A <em>Multilink</em> property refers to possibly many nodes
-in a specified class. The value is a list of integers.
-</ul>
-
-<h4>FileClass</h4>
-FileClasses save their "content" attribute off in a separate file from the
-rest of the database. This reduces the number of large entries in the
-database, which generally makes databases more efficient, and also allows
-us to use command-line tools to operate on the files. They are stored in
-the files sub-directory of the db directory in your instance.
-
-<h4>IssueClass</h4>
-IssueClasses automatically include the "messages", "files", "nosy", and
-"superseder" properties.
-<p>
-The messages and files properties list the links to the messages and files
-related to the issue. The nosy property is a list of links to users who
-wish to be informed of changes to the issue - they get "CC'ed" e-mails when
-messages are sent to or generated by the issue. The nosy reactor (in the
-detectors directory) handles this action. The superceder link indicates an
-issue which has superceded this one.
-<p>
-They also have the dynamically generated
-"creation", "activity" and "creator" properties.
-<p>
-The value of the "creation" property is the date when a node was created,
-and the value of the "activity" property is the date when any property on
-the node was last edited (equivalently, these are the dates on the first
-and last records in the node's journal). The "creator" property holds a
-link to the user that created the issue.
-
-<h4>setkey(property)</h4>
-Select a String property of the class to be the key property. The key
-property muse be unique, and allows references to the nodes in the class by
-the content of the key property. That is, we can refer to users by their
-username, e.g. let's say that there's an issue in roundup, issue 23. There's
-also a user, richard who happens to be user 2. To assign an issue to him,
-we could do either of:
-<p>
-<blockquote><tt>roundup-admin set issue assignedto=2</tt></blockquote>
-<p>
-or
-<p>
-<blockquote><tt>roundup-admin set issue
- assignedto=richard</tt></blockquote>
-<p>
-Note, the same thing can be done in the web and e-mail interfaces.
-
-<h4>create(information)</h4>
-Create a node in the database. This is generally used to create nodes in
-the "definitional" classes like "priority" and "status".
-
-
-<h2><a name="custweb">Web Interface</a></h2>
-
-The web interface works behind the cgi-bin/roundup.cgi or roundup-server
-scripts. In both cases, the scripts determine which instance is being
-accessed (the first part of the URL path inside the scope of the CGI
-handler) and pass control on to the instance interfaces.Client class which
-handles the rest of the access through its main() method. This means that
-you can do pretty much anything you want as a web interface to your
-instance.
-<p>
-Most customisation of the web view can be done by modifying the templates
-in the instance html directory. These are divided into index, item and
-newitem views. The newitem view is optional - the item view will be used if
-the newitem view doesn't exist.
-
-<h3><a name="schemarepurcussions">Repurcussions of changing the instance schema</a></h3>
-
-If you choose to <a href="custinst">change the instance schema</a> you will need to
-ensure the web interface knows about it:
-<ol>
-<li>Index, item and filter pages for the relevant classes may need to have properties
-added or removed,
-<li>The default page header relies on the existence of, and some values of the
-priority, status, assignedto and activity classes. If you change any of these (specifically
-if you remove any of the classes or their default values) you will need to implement your
-own pagehead() method in your instance's interfaces.py module.
-</ol>
-
-
-<h3>Displaying Properties</h3>
-
-<p>
-Properties appear in the user interface in three contexts:
-in indices, in editors, and as filters. For each type of
-property, there are several display possibilities. For example,
-in an index view, a string property may just be printed as
-a plain string, but in an editor view, that property should
-be displayed in an editable field.
-
-<p>
-The display of a property is handled by functions in
-the htmltemplate module.
-
-<p>
-Displayer functions are triggered by <tt><display></tt>
-tags in templates. The <tt>call</tt> attribute of the tag
-provides a Python expression for calling the displayer
-function. The three standard arguments are inserted in
-front of the arguments given. For example, the occurrence of
-
-<blockquote><pre><small
-> <display call="plain('status')">
-</small></pre></blockquote>
-
-in a template triggers a call the "plain" function. The displayer
-functions can accept extra arguments to further specify
-details about the widgets that should be generated. By defining new
-displayer functions, the user interface can be highly customized.
-
-<p>
-<table border=1 cellspacing=0>
-<tr><th colspan=2>The displayer functions are</th></tr>
-
-<tr><td valign="top"><strong>plain</strong></td>
-<td>Display a String property directly.
-<p>
-Display a Date property in a specified time zone with an option
-to omit the time from the date stamp.
-<p>
-For a Link or Multilink
-property, display the key strings of the linked nodes (or the
-ids if the linked class has no key property).
-<p>
-<em>Options:</em><br>
-escape (boolean) - HTML-escape the resulting text.
-</td></tr>
-
-<tr><td valign="top"><strong>field</strong></td>
-<td>Display a property like the
-<strong>plain</strong> displayer above, but in a form field
-to be edited. Strings, Dates and Intervals use TEXT fields, Links use
-SELECT fields and Multilinks use SELECT MULTIPLE fields.
-<p>
-<em>Options:</em><br>
-size (number) - width of TEXT fields.<br>
-height (number) - number of nows in SELECT MULTIPLE tags.<br>
-showid (boolean) - true includes the id of linked nodes in the SELECT
-MULTIPLE fields.
-</td></tr>
-
-<tr><td valign="top"><strong>menu</strong></td>
-<td>For a Links and Multilinks, display the same field as would be
-generated using <strong>field</strong>.
-</td></tr>
-
-<tr><td valign="top"><strong>link</strong></td>
-<td>For a Link or Multilink property, display the names of the linked
-nodes, hyperlinked to the item views on those nodes.
-<p>
-For other properties, link to this node with the property as the text.
-<p>
-<em>Options:</em><br>
-property (property name) - the property to use in the second case.
-</td></tr>
-
-<tr><td valign="top"><strong>count</strong></td>
-<td>For a Multilink property, display
-a count of the number of links in the list.
-<p>
-<em>Arguments:</em><br>
-property (property name) - the property to use.
-
-</td></tr>
-
-<tr><td valign="top"><strong>reldate</strong></td>
-<td>Display a Date property in terms
-of an interval relative to the current date (e.g. "+ 3w", "- 2d").
-<p>
-<em>Arguments:</em><br>
-property (property name) - the property to use.
-<p>
-<em>Options:</em><br>
-pretty (boolean) - display the relative date in an English form.
-</td></tr>
-
-<tr><td valign="top"><strong>download</strong></td>
-<td>For a Link or Multilink property, display the names of the linked
-nodes, hyperlinked to the item views on those nodes.
-<p>
-For other properties, link to this node with the property as the text.
-<p>
-In all cases, append the name (key property) of the item to the path so it
-is the name of the file being downloaded.
-<p>
-<em>Arguments:</em><br>
-property (property name) - the property to use.
-</td></tr>
-
-<tr><td valign="top"><strong>checklist</strong></td>
-<td>For a Link or Multilink property,
-display checkboxes for the available choices to permit filtering.
-<p>
-<em>Arguments:</em><br>
-property (property name) - the property to use.
-</td></tr>
-
-<tr><td valign="top"><strong>note</strong></td>
-<td>Display the special notes field, which is a text area for entering a
-note to go along with a change.
-</td></tr>
-
-<tr><td valign="top"><strong>list</strong></td>
-<td>List the nodes specified by property using the standard index for
-the class.
-<p>
-<em>Arguments:</em><br>
-property (property name) - the property to use.
-</td></tr>
-
-<tr><td valign="top"><strong>history</strong></td>
-<td>List the history of the item.
-</td></tr>
-
-<tr><td valign="top"><strong>submit</strong></td>
-<td>Add a submit button for the item.
-</td></tr>
-
-</table>
-
-<h3>Index Views</h3>
-
-<p>An index view contains two sections: a filter section
-and an index section.
-The filter section provides some widgets for selecting
-which items appear in the index. The index section is
-a table of items.
-
-<h4>Index View Specifiers</h4>
-
-<p>An index view specifier (URL fragment) looks like this (whitespace
-has been added for clarity):
-
-<blockquote><pre><small
->/issue?status=unread,in-progress,resolved&
- topic=security,ui&
- :group=+priority&
- :sort=-activity&
- :filters=status,topic&
- :columns=title,status,fixer
-</small></pre></blockquote>
-
-<p>The index view is determined by two parts of the
-specifier: the layout part and the filter part.
-The layout part consists of the query parameters that
-begin with colons, and it determines the way that the
-properties of selected nodes are displayed.
-The filter part consists of all the other query parameters,
-and it determines the criteria by which nodes
-are selected for display.
-
-<p>The filter part is interactively manipulated with
-the form widgets displayed in the filter section. The
-layout part is interactively manipulated by clicking
-on the column headings in the table.
-
-<p>The filter part selects the <em>union</em> of the
-sets of items with values matching any specified Link
-properties and the <em>intersection</em> of the sets
-of items with values matching any specified Multilink
-properties.
-
-<p>The example specifies an index of "issue" nodes.
-Only items with a "status" of <em>either</em>
-"unread" or "in-progres" or "resolved" are displayed,
-and only items with "topic" values including <em>both</em>
-"security" <em>and</em> "ui" are displayed. The items
-are grouped by priority, arranged in ascending order;
-and within groups, sorted by activity, arranged in
-descending order. The filter section shows filters
-for the "status" and "topic" properties, and the
-table includes columns for the "title", "status", and
-"fixer" properties.
-
-<p>Associated with each item class is a default
-layout specifier. The layout specifier in the above
-example is the default layout to be provided with
-the default bug-tracker schema described above in
-section 4.4.
-
-<h4>Filter Section</h4>
-
-<p>The template for a filter section provides the
-filtering widgets at the top of the index view.
-Fragments enclosed in <tt><property></tt>...<tt></property></tt>
-tags are included or omitted depending on whether the
-view specifier requests a filter for a particular property.
-
-<p>A property must appear in the filter template for it to be available
-as a filter.
-
-<p>Here's a simple example of a filter template.
-
-<blockquote><pre><small><property name=status>
- <display call="checklist('status')">
-</property>
-<br>
-<property name=priority>
- <display call="checklist('priority')">
-</property>
-<br>
-<property name=fixer>
- <display call="menu('fixer')">
-</property></small></pre></blockquote>
-
-<p>
-The standard index generation code appends a section to the index pages
-which allows selection of the filters - from those which are defined in the
-filter template.
-
-<h4>Index Section</h4>
-
-<p>The template for an index section describes one row of
-the index table.
-Fragments enclosed in <tt><property></tt>...<tt></property></tt>
-tags are included or omitted depending on whether the
-view specifier requests a column for a particular property.
-The table cells should contain <tt><display></tt> tags
-to display the values of the item's properties.
-
-<p>Here's a simple example of an index template.
-
-<blockquote><pre><small><tr>
- <property name=title>
- <td><display call="plain('title', max=50)"></td>
- </property>
- <property name=status>
- <td><display call="plain('status')"></td>
- </property>
- <property name=fixer>
- <td><display call="plain('fixer')"></td>
- </property>
-</tr></small></pre></blockquote>
-
-<h4>Sorting</h4>
-
-<p>String and Date values are sorted in the natural way.
-Link properties are sorted according to the value of the
-"order" property on the linked nodes if it is present; or
-otherwise on the key string of the linked nodes; or
-finally on the node ids. Multilink properties are
-sorted according to how many links are present.
-
-<h3>Item Views</h3>
-
-<p>An item view contains an editor section and a spool section.
-At the top of an item view, links to superseding and superseded
-items are always displayed.
-
-
-
-<h4>Editor Section</h4>
-
-<p>The editor section is generated from a template
-containing <tt><display></tt> tags to insert
-the appropriate widgets for editing properties.
-
-<p>Here's an example of a basic editor template.
-
-<blockquote><pre><small><table>
-<tr>
- <td colspan=2>
- <display call="field('title', size=60)">
- </td>
-</tr>
-<tr>
- <td>
- <display call="field('fixer', size=30)">
- </td>
- <td>
- <display call="menu('status')>
- </td>
-</tr>
-<tr>
- <td>
- <display call="field('nosy', size=30)">
- </td>
- <td>
- <display call="menu('priority')>
- </td>
-</tr>
-<tr>
- <td colspan=2>
- <display call="note()">
- </td>
-</tr>
-</table>
-</small></pre></blockquote>
-
-<p>As shown in the example, the editor template can also
-request the display of a "note" field, which is a
-text area for entering a note to go along with a change.
-
-<p>When a change is submitted, the system automatically
-generates a message describing the changed properties.
-
-<p>If a note is given in the "note" field, the note is
-appended to the description. The message is then added
-to the item's message spool (thus triggering the standard
-detector to react by sending out this message to the nosy list).
-
-<p>
-The message also displays all of the property values on the
-item and indicates which ones have changed.
-An example of such a message might be this:
-
-<blockquote><pre>
-Polly's taken a turn for the worse - this is now really important!
------
-title: Polly Parrot is dead
-priority: critical
-status: unread -> in-progress
-fixer: terry
-keywords: parrot,plumage,perch,nailed,dead
-</pre></blockquote>
-
-<h4>Spool Section</h4>
-
-<p>The spool section lists messages in the item's "messages"
-property. The index of messages displays the "date", "author",
-and "summary" properties on the message nodes, and selecting a
-message takes you to its content.
-
-<p>The <property> tag used in the index may also be used here -
-it checks to see if the nominated Multilink property has any entries.
-This can be used to eliminate sections of the spool section if the
-property has no entries.
-
-<blockquote><pre>
-<property name="files">
- <tr class="strong-header">
- <td><b>Files</b></td>
- </tr>
-
- <tr>
- <td><display call="list('files')"></td>
- </tr>
-</property>
-</pre></blockquote>
-
-<p><hr>
-<h1><a name="ack">Acknowledgements</a></h1>
-
-Go Ping, you rock! Also, go Bizar Software for letting me implement this
-system on their time.
-
-<p> </p>
-<hr>
-$Id: index.html,v 1.27 2002-01-23 05:10:27 richard Exp $
-<p> </p>
-
-</body></html>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd">
+<HTML LANG="en">
+<HEAD>
+<LINK REL="StyleSheet" HREF="default.css" TYPE="text/css"></HEAD>
+<BODY>
+<DIV CLASS="document">
+<P><EM>Roundup: an Issue-Tracking System for Knowledge Workers</EM></P>
+<DIV CLASS="section" ID="id1">
+<H1>Contents</H1>
+<UL>
+<LI>
+<P><A CLASS="reference" HREF="overview.html">Overview</A></P>
+</LI>
+<LI>
+<P><A CLASS="reference" HREF="installation.html">Installation</A></P>
+</LI>
+<LI>
+<P><A CLASS="reference" HREF="getting_started.html">Getting Started</A></P>
+</LI>
+<LI>
+<P><A CLASS="reference" HREF="user_guide.html">User Guide</A></P>
+</LI>
+<LI>
+<P><A CLASS="reference" HREF="customizing.html">Customising Roundup</A></P>
+</LI>
+<LI>
+<P><A CLASS="reference" HREF="spec.html">Roundup's Design Document</A></P>
+</LI>
+</UL>
+</A></A></A></A></A></A></DIV>
+<DIV CLASS="section" ID="id8">
+<H1>Acknowledgements</H1>
+<P>Go Ping, you rock! Also, go Bizar Software and ekit.com for letting me
+implement this system on their time.</P>
+<P>Thanks also to the many people on the mailing list and in the sourceforge
+project: Anthony Baxter, Juergen Hermann, Roch'e Compaan, Engelbert Gruber,
+Titus Brown, Jeff Blaine and Patrick Ohly.</P>
+</DIV>
+</DIV>
+</BODY>
+</HTML>
diff --git a/doc/index.stx b/doc/index.stx
--- /dev/null
+++ b/doc/index.stx
@@ -0,0 +1,30 @@
+*Roundup: an Issue-Tracking System for Knowledge Workers*
+
+Contents
+========
+
+- Overview_
+- Installation_
+- `Getting Started`_
+- `User Guide`_
+- `Customising Roundup`_
+- `Roundup's Design Document`_
+
+.. _Overview: overview.html
+.. _Installation: installation.html
+.. _`Getting Started`: getting_started.html
+.. _`User Guide`: user_guide.html
+.. _`Customising Roundup`: customizing.html
+.. _`Roundup's Design Document`: spec.html
+
+
+Acknowledgements
+================
+
+Go Ping, you rock! Also, go Bizar Software and ekit.com for letting me
+implement this system on their time.
+
+Thanks also to the many people on the mailing list and in the sourceforge
+project: Anthony Baxter, Juergen Hermann, Roch'e Compaan, Engelbert Gruber,
+Titus Brown, Jeff Blaine and Patrick Ohly.
+
diff --git a/doc/installation.stx b/doc/installation.stx
index d874b5d50e583da0c12bdc8b7d0c6d5370f620ae..17b4c8ad4845fd3aecd5cef02f786fa10c99f2e7 100644 (file)
--- a/doc/installation.stx
+++ b/doc/installation.stx
`Table of contents`_
-1. Prerequisites_
-2. `Getting Roundup`_
-3. `Installing Roundup`_
+- Overview_
+- Prerequisites_
+ - `Testing your Python`_
+
+- `Getting Roundup`_
+- `Installation`_
+- `Further Reading`_
+- `Platform-Specific Notes`_
+
+Overview
+========
+
+TODO
Prerequisites
--------------
+=============
-Python 2.1.1 is required for the correct operation of roundup.
+Python 2.1.1 or newer with a functioning anydbm or bsddb module.
Download the latest version from http://www.python.org/.
+Testing your Python
+-------------------
+
+Run ``"python -c 'import test;test.go()'"`` and make sure there
+are no errors. If there are errors, please let us know!
+
+
Getting Roundup
----------------
+===============
Download the latest version from http://roundup.sf.net/.
-Installing Roundup
-------------------
-Run:
+Installation
+============
+
+Set aside 15-30 minutes.
+
+Broken out separately, there are several conceptual pieces to a
+Roundup installation:
+
+Roundup support code
+ Installed into your Python install's lib directory
+
+Roundup scripts
+ These include the email gateway, the roundup
+ HTTP server, the roundup administration command-line interface, etc.
+
+Roundup instances
+ Instances consist of core support files, issues
+ (be they bug reports or otherwise), instance configuration file(s),
+ etc. Roundup instances also adhere to a specific "Template" which
+ defines the fields usable/assignable on a per-issue basis. A
+ description of the provided templates can be found under the
+ 'TODO' section.
+
+1. To install the Roundup support code into your Python tree and
+ Roundup scripts into /usr/local/bin::
+
+ python setup.py install
+
+ If you would like to place the Roundup scripts in a directory other
+ than ``/usr/local/bin``, use the ``--install-scripts`` option as follows,
+ replacing ``/opt/roundup/bin`` with the location where you would like
+ the scripts to reside::
+
+ python setup.py install --install-scripts=/opt/roundup/bin
+
+2. To create a Roundup instance (necessary to do before you can
+ use the software in any real fashion):
+
+ a. (Optional) If you intend to keep your roundup instances
+ under one top level directory which does not exist yet,
+ you should create that directory now. Example:
+
+ mkdir /opt/roundup/instances
+
+ b. Either add the Roundup script location to your ``PATH``
+ environment variable or specify the full path to
+ the command in the next step.
+
+ c. ``roundup-admin init``
+
+ You will be asked a series of questions. A description of
+ the Roundup-provided templates can be found under TODO::
+
+ Enter instance home: /opt/roundup/instances/support
+ Templates: classic, extended
+ Select template [classic]: classic
+ Back ends: anydbm, bsddb
+ Select backend [anydbm]: anydbm
+ Admin Password:
+ Confirm:
+
+3. Each instance ideally should have its own UNIX group, so create
+ a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
+ you're using NIS). To continue with my examples so far, I would
+ create the UNIX group 'support', although the name of the UNIX
+ group does not have to be the same as the instance name. To this
+ 'support' group I then add all of the UNIX usernames who will be
+ working with this Roundup instance. In addition to 'real' users,
+ the Roundup email gateway will need to have permissions to this
+ area as well, so add the user your mail service runs as to the
+ group. The UNIX group might then look like::
+
+ support:*:1002:jblaine,samh,geezer,mail
+
+ If you intend to use the web interface (as most people do), you
+ should also add the username your web server runs as to the group.
+ My group now looks like this::
+
+ support:*:1002:jblaine,samh,geezer,mail,apache
+
+4. Configure your new instance by editing the file ``instance_config.py``
+ located in the instance home you specified in step 2c above. This
+ file is Python code and must adhere to Python syntax rules, but
+ don't be daunted if you do not know Python - it should look pretty
+ straightfoward if you carefully read the comments in the file.
+
+5. There are two supported ways to get emailed issues into the
+ Roundup instance. You should pick ONE of the following, both
+ of which will continue my example setup from above:
+
+ a. Set up a mail alias called "support" as::
+
+ "|/opt/roundup/bin/roundup-mailgw /opt/roundup/instances/support"
+
+ If you use Sendmail's ``smrsh`` mechanism, please read the notes
+ under 'Platform-Specific Notes'
+
+ b. OR... Configure roundup-mailgw to run every 10 minutes or
+ so via ``cron``. My cron job would be (these 2 lines all on one
+ line)::
+
+ 10 * * * * /opt/roundup/bin/roundup-mailgw
+ /opt/roundup/instances/support /var/mail/support
+
+6. TODO (mention perms)
+
+7. Test the email gateway. Under most flavors of UNIX, this
+ can be done by::
+
+ echo test | mail -s '[issue] test' support@YOUR_DOMAIN_HERE
+
+TODO (finish)
+
+
+Further Reading
+===============
+
+If you intend to use Roundup with anything other than the defualt
+templates, if you would like to hack on Roundup, or if you would
+like implementation details, you should read 'TODO'
+
+Platform-Specific Notes
+=======================
+
+Sendmail smrsh
+--------------
+
+If you use Sendmail's ``smrsh`` mechanism, you will need to tell
+smrsh that roundup-mailgw is a valid/trusted mail handler
+before it will work.
+
+This is usually done via the following 2 steps:
+
+1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
+ which points to the full path of your actual ``roundup-mailgw``
+ script.
-- "``python setup.py install``"
-- If you would prefer the scripts installed in somewhere other than
- "``/usr/local/bin``", add "``--install-scripts=<dir>``" to the
- command::
+2. change your alias to ``"|roundup-mailgw <instance_home>"``
- python setup.py install --install-scripts=<dir>
-- This command gives all the options available for
- installation::
+Linux
+-----
- python setup.py install --help
+Python 2.1.1 as shipped with SuSE7.3 might be missing module
+``_weakref``.
+-------------------------------------------------------------------------------
Next: `Getting Started`_
.. _`table of contents`: index.html
.. _`getting started`: getting_started.html
-$Id: installation.stx,v 1.1 2002-02-21 06:22:00 richard Exp $
+$Id: installation.stx,v 1.2 2002-03-08 23:41:46 richard Exp $