![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: 3d454b6)
raw | patch | inline | side by side (parent: 3d454b6)
| author | richard <richard@57a73879-2fb5-44c3-a270-3262357dd7e2> | |
| Wed, 13 Mar 2002 23:00:48 +0000 (23:00 +0000) | ||
| committer | richard <richard@57a73879-2fb5-44c3-a270-3262357dd7e2> | |
| Wed, 13 Mar 2002 23:00:48 +0000 (23:00 +0000) |
- renamed .stx to .txt so they're identifiable as readable files.
- fixed FAQ and announcement formatting
git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@671 57a73879-2fb5-44c3-a270-3262357dd7e2
- fixed FAQ and announcement formatting
git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@671 57a73879-2fb5-44c3-a270-3262357dd7e2
16 files changed:
| README.txt | patch | blob | history | |
| doc/FAQ.stx | [deleted file] | patch | blob | history |
| doc/FAQ.txt | patch | blob | history | |
| doc/acknoledgements.stx | [deleted file] | patch | blob | history |
| doc/acknoledgements.txt | [new file with mode: 0644] | patch | blob |
| doc/announcement.txt | patch | blob | history | |
| doc/customizing.stx | [deleted file] | patch | blob | history |
| doc/customizing.txt | [new file with mode: 0644] | patch | blob |
| doc/getting_started.stx | [deleted file] | patch | blob | history |
| doc/getting_started.txt | [new file with mode: 0644] | patch | blob |
| doc/index.stx | [deleted file] | patch | blob | history |
| doc/index.txt | [new file with mode: 0644] | patch | blob |
| doc/installation.stx | [deleted file] | patch | blob | history |
| doc/installation.txt | [new file with mode: 0644] | patch | blob |
| doc/user_guide.stx | [deleted file] | patch | blob | history |
| doc/user_guide.txt | [new file with mode: 0644] | patch | blob |
diff --git a/README.txt b/README.txt
index 57745d334d7848cf3aa76416c096159954c0e12b..d9a9642a1fa2b8548b11efad9d55898fa8514941 100644 (file)
--- a/README.txt
+++ b/README.txt
- Roundup
- =======
+Installation
+============
+For installation instructions, please see installation.txt /
+installation.html in the "doc" directory.
-1. License
-==========
+
+Usage and Other Information
+===========================
+See the index.txt / index.html file in the "doc" directory.
+
+
+License
+=======
Copyright (c) 2001 Bizar Software Pty Ltd (http://www.bizarsoftware.com.au/)
This module is free software, and you may redistribute it and/or modify
The stylesheet included with this package has been copied from the Zope
management interface and presumably belongs to Digital Creations.
-
-2. Installation
-===============
-For installation notes, please see the file INSTALL.TXT
-
-
-3. Usage
-========
-See the index.html file in the "doc" directory.
-
-
-3. Design
-=========
-See the information in the "doc" directory.
-
-
-
-4. TODO
-=======
-Most of the TODO items are captured in comments in the code. In summary:
-
-in general:
- . more unit tests
- . more back-ends
-hyperdb:
- . more efficient reverse lookups
-roundup-server:
- . check the source file timestamps before reloading
-cgi_client
- . keep form fields in form on bad submission - only clear it if all ok
-
-
-5. Known Bugs
-=============
-
-date:
- . date subtraction doesn't work correctly "if the dates cross leap years,
- phases of the moon, ..."
-
-
-6. Author
-=========
-richard@users.sourceforge.net
-
-
-7. Thanks
-=========
-Well, Ping, of course ;)
-
-Anthony Baxter, for some good first-release feedback. And then continuing
-support through development on sourceforge.
-
diff --git a/doc/FAQ.stx b/doc/FAQ.stx
--- a/doc/FAQ.stx
+++ /dev/null
@@ -1,125 +0,0 @@
-Roundup FAQ
-===========
-
- '$Date: 2002-02-21 06:22:00 $'
-
- NOTE: This is just a grabbag, most of this should go into documentation.
-
-Changing HTML layout
---------------------
-
- Note changes to the files in html take place immediatly without
- restart, even when running roundup-server.
-
-Displaying whole messages not only the summary
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- Modify instance/html/msg.index change::
-
- <td><display call="plain('summary')"></td>
-
- to::
-
- <td><pre><display call="plain('content')"></pre></td>
-
- displays the whole message not only the first line and 'pre'
- prevents the browser from reformatting.
-
-Getting the nosy list picker instead of textfield
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- In classic template there is plenty of space below the text field.
- So one could modify instance/html/issue.item to use it.
-
- At the file top set 'border=1' to see cell boundaries, then
- replace::
-
- <td class="form-text"><display call="field('nosy',size=20)"></td>
-
- by::
-
- <td rowspan=5 class="form-text"><display call="menu('nosy',height=10)"></td>
-
- and remove the last cell in the next four rows, either by deleting a cell
- or by reducing colspan.
-
-Want to see the issue id (the number) on the issue item display
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- The number is really a central information and not an internal one.
-
- In file INSTANCE/html/issue.item displays the creator, so one could add
- the number to it.::
-
- <td class="form-text"><display call="reldate('creation', pretty=1)">
- (<display call="plain('creator')">)</td>
-
- to see::
-
- <td class="form-text"><display call="reldate('creation', pretty=1)">
- (issue<display call="plain('id')"> by <display call="plain('creator')">)</td>
-
-Installation
-------------
-
-Living without a mailserver.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- Remove the nosy reactor, means delete the file 'INSTANCE/detectors/nosyreactor.py'.
-
-Rights issues (MISSING)
-~~~~~~~~~~~~~~~~~~~~~~~
-
- Different jobs run under different users.
-
- * Standalone roundup-server is started by whome ?
-
- * Running cgi under apache.
-
- * roundup-mailgw called via .forward from MTA, or running a cron job
- fetching via pop.
-
- see Troubleshooting.
-
-Troubleshooting
----------------
-
-
-AttributeError: ''_roundup_instance_1'' module has no attribute 'open'
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- Sorry: in html it is not formatted correct.
-
- For example submitting issues via roundup-mailgw breaks similar to this.::
-
- Command died with status 1:
- "/usr/local/bin/python /usr/local/bin/roundup-mailgw /home/roundup".
- Command output: Traceback (most recent call last):
- File "/usr/local/bin/roundup-mailgw", line 178, in ?
- sys.exit(main(sys.argv))
- File "/usr/local/bin/roundup-mailgw", line 153, in main
- db = instance.open('admin')
- AttributeError: '_roundup_instance_1' module has no attribute 'open'
-
- Happens if the user which accesses the instance has no read right
- on 'INSTANCE/dbinit.py' or 'pyc'.
-
- If the user has no rights on the 'INSTANCE/db' the mailgw finishes,
- but is, of course, unable to add the message. A notification to
- the roundup-admin is sent, with a longer trace ending in::
-
- File "/opt/python/lib/python2.2/dbhash.py", line 16, in open
- return bsddb.hashopen(file, flag, mode)
- error: (13, 'Keine Berechtigung')
-
- Replace 'Keine Berechtigung' by 'Not permitted' or ...
-
- An easy way to test whether it's a permissions problem, or some other mail
- server configuration problem is to cat an email-formatted text file
- directly to the roundup-mailgw script as the roundup user.::
-
- cat issue.txt | /usr/local/bin/roundup-mailgw /home/roundup
-
- If that doesn't raise any errors, the problem is the permissions of the
- MTA.
-
diff --git a/doc/FAQ.txt b/doc/FAQ.txt
index 3b5dbecea8d4cef8ab26fb4d7dd30b3c7ab41637..d78da85fc508123806d8cfd23854b7fb54d2954a 100644 (file)
--- a/doc/FAQ.txt
+++ b/doc/FAQ.txt
Roundup FAQ
+===========
- '$Date: 2002-02-14 11:11:36 $'
+:Date: $Date: 2002-03-13 23:00:48 $
- NOTE: This is just a grabbag, most of this should go into documentation.
+NOTE: This is just a grabbag, most of this should go into documentation.
Changing HTML layout
+--------------------
- Note changes to the files in html take place immediatly without
- restart, even when running roundup-server.
+Note changes to the files in html take place immediatly without
+restart, even when running roundup-server.
- Displaying whole messages not only the summary
+Displaying whole messages not only the summary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Modify instance/html/msg.index change::
+Modify instance/html/msg.index change::
- <td><display call="plain('summary')"></td>
+ <td><display call="plain('summary')"></td>
- to::
+to::
- <td><pre><display call="plain('content')"></pre></td>
+ <td><pre><display call="plain('content')"></pre></td>
- displays the whole message not only the first line and 'pre'
- prevents the browser from reformatting.
+displays the whole message not only the first line and 'pre'
+prevents the browser from reformatting.
- Getting the nosy list picker instead of textfield.
+Getting the nosy list picker instead of textfield
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- In classic template there is plenty of space below the text field.
- So one could modify instance/html/issue.item to use it.
+In classic template there is plenty of space below the text field.
+So one could modify instance/html/issue.item to use it.
- At the file top set 'border=1' to see cell boundaries, then
- replace::
+At the file top set 'border=1' to see cell boundaries, then
+replace::
- <td class="form-text"><display call="field('nosy',size=20)"></td>
+ <td class="form-text"><display call="field('nosy',size=20)"></td>
- by::
+by::
- <td rowspan=5 class="form-text"><display call="menu('nosy',height=10)"></td>
+ <td rowspan=5 class="form-text"><display call="menu('nosy',height=10)"></td>
- and remove the last cell in the next four rows, either by deleting a cell
- or by reducing colspan.
+and remove the last cell in the next four rows, either by deleting a cell
+or by reducing colspan.
- Want to see the issue id (the number) on the issue item display
+Want to see the issue id (the number) on the issue item display
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The number is really a central information and not an internal one.
+The number is really a central information and not an internal one.
- In file INSTANCE/html/issue.item displays the creator, so one could add
- the number to it.::
+In file INSTANCE/html/issue.item displays the creator, so one could add
+the number to it.::
- <td class="form-text"><display call="reldate('creation', pretty=1)">
- (<display call="plain('creator')">)</td>
+ <td class="form-text"><display call="reldate('creation', pretty=1)">
+ (<display call="plain('creator')">)</td>
- to see::
+to see::
- <td class="form-text"><display call="reldate('creation', pretty=1)">
- (issue<display call="plain('id')"> by <display call="plain('creator')">)</td>
+ <td class="form-text"><display call="reldate('creation', pretty=1)">
+ (issue<display call="plain('id')"> by <display call="plain('creator')">)</td>
Installation
+------------
- Living without a mailserver.
+Living without a mailserver.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Remove the nosy reactor, means delete the file 'INSTANCE/detectors/nosyreactor.py'.
+Remove the nosy reactor, means delete the file
+'INSTANCE/detectors/nosyreactor.py'.
- Rights issues (MISSING)
- Different jobs run under different users.
+Rights issues (MISSING)
+~~~~~~~~~~~~~~~~~~~~~~~
- * Standalone roundup-server is started by whome ?
+Different jobs run under different users.
- * Running cgi under apache.
+* Standalone roundup-server is started by whome ?
- * roundup-mailgw called via .forward from MTA, or running a cron job
- fetching via pop.
+* Running cgi under apache.
- see Troubleshooting.
+* roundup-mailgw called via .forward from MTA, or running a cron job
+ fetching via pop.
-Troubleshooting
+see Troubleshooting_.
-
- AttributeError: '_roundup_instance_1' module has no attribute 'open'
- Sorry: in html it is not formatted correct.
+Troubleshooting
+---------------
+
+AttributeError: '_roundup_instance_1' module has no attribute 'open'
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- For example submitting issues via roundup-mailgw breaks similar to this.::
+For example submitting issues via roundup-mailgw breaks similar to this::
- Command died with status 1:
- "/usr/local/bin/python /usr/local/bin/roundup-mailgw /home/roundup".
- Command output: Traceback (most recent call last):
- File "/usr/local/bin/roundup-mailgw", line 178, in ?
- sys.exit(main(sys.argv))
- File "/usr/local/bin/roundup-mailgw", line 153, in main
- db = instance.open('admin')
- AttributeError: '_roundup_instance_1' module has no attribute 'open'
+ Command died with status 1:
+ "/usr/local/bin/python /usr/local/bin/roundup-mailgw /home/roundup".
+ Command output: Traceback (most recent call last):
+ File "/usr/local/bin/roundup-mailgw", line 178, in ?
+ sys.exit(main(sys.argv))
+ File "/usr/local/bin/roundup-mailgw", line 153, in main
+ db = instance.open('admin')
+ AttributeError: '_roundup_instance_1' module has no attribute 'open'
- Happens if the user which accesses the instance has no read right
- on 'INSTANCE/dbinit.py' or 'pyc'.
+Happens if the user which accesses the instance has no read right
+on 'INSTANCE/dbinit.py' or 'pyc'.
- If the user has no rights on the 'INSTANCE/db' the mailgw finishes,
- but is, of course, unable to add the message. A notification to
- the roundup-admin is sent, with a longer trace ending in::
+If the user has no rights on the 'INSTANCE/db' the mailgw finishes,
+but is, of course, unable to add the message. A notification to
+the roundup-admin is sent, with a longer trace ending in::
- File "/opt/python/lib/python2.2/dbhash.py", line 16, in open
- return bsddb.hashopen(file, flag, mode)
- error: (13, 'Keine Berechtigung')
+ File "/opt/python/lib/python2.2/dbhash.py", line 16, in open
+ return bsddb.hashopen(file, flag, mode)
+ error: (13, 'Keine Berechtigung')
- Replace 'Keine Berechtigung' by 'Not permitted' or ...
+Replace 'Keine Berechtigung' by 'Not permitted' or ...
- An easy way to test whether it's a permissions problem, or some other mail
- server configuration problem is to cat an email-formatted text file
- directly to the roundup-mailgw script as the roundup user.::
+An easy way to test whether it's a permissions problem, or some other mail
+server configuration problem is to cat an email-formatted text file
+directly to the roundup-mailgw script as the roundup user.::
- cat issue.txt | /usr/local/bin/roundup-mailgw /home/roundup
+ cat issue.txt | /usr/local/bin/roundup-mailgw /home/roundup
- If that doesn't raise any errors, the problem is the permissions of the
- MTA.
+If that doesn't raise any errors, the problem is the permissions of the
+MTA.
diff --git a/doc/acknoledgements.stx b/doc/acknoledgements.stx
--- a/doc/acknoledgements.stx
+++ /dev/null
@@ -1,6 +0,0 @@
-Acknowledgements
-================
-
-Go Ping, you rock! Also, go Bizar Software for letting me implement this system on their time.
-
-
diff --git a/doc/acknoledgements.txt b/doc/acknoledgements.txt
--- /dev/null
+++ b/doc/acknoledgements.txt
@@ -0,0 +1,6 @@
+Acknowledgements
+================
+
+Go Ping, you rock! Also, go Bizar Software for letting me implement this system on their time.
+
+
diff --git a/doc/announcement.txt b/doc/announcement.txt
index d3625fd5a6052bbe1498824d5772317234eddd27..0fd0650bd3623fbbb4e345ba36a4f45371a4efbf 100644 (file)
--- a/doc/announcement.txt
+++ b/doc/announcement.txt
- Roundup 0.4.0 - an issue tracking system
+========================================
+Roundup 0.4.0 - an issue tracking system
+========================================
If you are upgrading please read MIGRATION.txt.
requires python 2.1.2 or 2.2.
Big stuff in this release:
- - Use of transactions to prevent partial data commits
- - Zope Product front-end
- - Nicer, more consistent change message generation
- - Several bug fixes and more unit tests
- - Much, much more: see the CHANGES file for details.
+
+- Use of transactions to prevent partial data commits
+- Zope Product front-end
+- Nicer, more consistent change message generation
+- Several bug fixes and more unit tests
+- Much, much more: see the CHANGES file for details.
Source and documentation is available at the website:
http://roundup.sourceforge.net/
-
Release Info (via download page):
http://sourceforge.net/projects/roundup
-
Mailing lists - the place to ask questions:
http://sourceforge.net/mail/?group_id=31577
is richard@users.sourceforge.net.
Roundup manages a number of issues (with flexible properties such as
-"description", "priority", and so on) and provides the ability to
- (a) submit new issues,
- (b) find and edit existing issues, and
- (c) discuss issues with other participants.
+"description", "priority", and so on) and provides the ability to:
+
+(a) submit new issues,
+(b) find and edit existing issues, and
+(c) discuss issues with other participants.
+
The system will facilitate communication among the participants by managing
discussions and notifying interested parties when issues are edited. One of
the major design goals for Roundup that it be simple to get going. Roundup
diff --git a/doc/customizing.stx b/doc/customizing.stx
--- a/doc/customizing.stx
+++ /dev/null
@@ -1,558 +0,0 @@
-Customising Roundup
-===================
-
-Instances have the following structure:
-
-+-------------------+--------------------------------------------------------+
-|instance_config.py |Holds the basic instance_configuration |
-+-------------------+--------------------------------------------------------+
-|dbinit.py |Holds the instance_schema |
-+-------------------+--------------------------------------------------------+
-|interfaces.py |Defines the Web and E-Mail interfaces for the instance |
-+-------------------+--------------------------------------------------------+
-|select_db.py |Selects the database back-end for the instance |
-+-------------------+--------------------------------------------------------+
-|db/ |Holds the instance's database |
-+-------------------+--------------------------------------------------------+
-|db/files/ |Holds the instance's upload files and messages |
-+-------------------+--------------------------------------------------------+
-|detectors/ |Auditors and reactors for this instance |
-+-------------------+--------------------------------------------------------+
-|html/ |Web interface templates, images and style sheets |
-+-------------------+--------------------------------------------------------+
-
-Instance Configuration
-----------------------
-
-The instance_config.py 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 instance_config.py is given below - as you
-can see, the MAIL_DOMAIN must be edited before any interaction with the
-instance is attempted.::
-
- 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'
-
-
-Instance Schema
----------------
-
-Note: if you modify the schema, you'll most likely need to edit the
- `web interface`_ HTML template files to reflect your changes.
-
-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::
-
- 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')
-
-Classes and Properties - creating a new information store
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In the instance above, we've defined 7 classes of information:
-
- priority
- Defines the possible levels of urgency for issues.
-
- status
- Defines the possible states of processing the issue may be in.
-
- keyword
- Initially empty, will hold keywords useful for searching issues.
-
- user
- Initially holding the "admin" user, will eventually have an entry for all
- users using roundup.
-
- msg
- Initially empty, will all e-mail messages sent to or generated by
- roundup.
-
- file
- Initially empty, will all files attached to issues.
-
- issue
- Initially emtyp, this is where the issue information is stored.
-
-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.
-
-Class and Nodes
-:::::::::::::::
-
-A Class 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.
-The actual data entered into the database, using class.create() are called
-nodes. They have a special immutable property called id. We sometimes refer to
-this as the nodeid.
-
-Properties
-::::::::::
-
-A Class is comprised of one or more properties of the following types:
- * String properties are for storing arbitrary-length strings.
- * Password properties are for storing encoded arbitrary-length strings. The
- default encoding is defined on the roundup.password.Password class.
- * Date properties store date-and-time stamps. Their values are Timestamp
- objects.
- * A Link 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.
- * A Multilink property refers to possibly many nodes in a specified class.
- The value is a list of integers.
-
-FileClass
-:::::::::
-
-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.
-
-IssueClass
-::::::::::
-
-IssueClasses automatically include the "messages", "files", "nosy", and
-"superseder" properties.
-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.
-They also have the dynamically generated "creation", "activity" and "creator"
-properties.
-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.
-
-setkey(property)
-::::::::::::::::
-
-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::
-
- roundup-admin set issue assignedto=2
-
-or::
-
- roundup-admin set issue assignedto=richard
-
-Note, the same thing can be done in the web and e-mail interfaces.
-
-create(information)
-:::::::::::::::::::
-
-Create a node in the database. This is generally used to create nodes in the
-"definitional" classes like "priority" and "status".
-
-Web Interface
--------------
-
-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.
-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.
-
-Repurcussions of changing the instance schema
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you choose to change_the_instance_schema you will need to ensure the web
-interface knows about it:
-
- 1. Index, item and filter pages for the relevant classes may need to have
- properties added or removed,
- 2. 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.
-
-Displaying Properties
-~~~~~~~~~~~~~~~~~~~~~
-
-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.
-
-The display of a property is handled by functions in the htmltemplate module.
-Displayer functions are triggered by <display> tags in templates. The call
-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::
-
- <display call="plain('status')">
-
-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.
-
-+-----------------------------------------------------------------------------+
-|The displayer functions are |
-+---------+-------------------------------------------------------------------+
-|plain |Display a String property directly. |
-| |Display a Date property in a specified time zone with an option to |
-| |omit the time from the date stamp. |
-| |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). |
-| |Options: |
-| |escape (boolean) - HTML-escape the resulting text. |
-+---------+-------------------------------------------------------------------+
-|field |Display a property like the plain 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. |
-| |Options: |
-| |size (number) - width of TEXT fields. |
-| |height (number) - number of nows in SELECT MULTIPLE tags. |
-| |showid (boolean) - true includes the id of linked nodes in the |
-| |SELECT MULTIPLE fields. |
-+---------+-------------------------------------------------------------------+
-|menu |For a Links and Multilinks, display the same field as would be |
-| |generated using field. |
-+---------+-------------------------------------------------------------------+
-|link |For a Link or Multilink property, display the names of the linked |
-| |nodes, hyperlinked to the item views on those nodes. |
-| |For other properties, link to this node with the property as the |
-| |text. |
-| |Options: |
-| |property (property name) - the property to use in the second case. |
-+---------+-------------------------------------------------------------------+
-|count |For a Multilink property, display a count of the number of links in|
-| |the list. |
-| |Arguments: |
-| |property (property name) - the property to use. |
-+---------+-------------------------------------------------------------------+
-|reldate |Display a Date property in terms of an interval relative to the |
-| |current date (e.g. "+ 3w", "- 2d"). |
-| |Arguments: |
-| |property (property name) - the property to use. |
-| |Options: |
-| |pretty (boolean) - display the relative date in an English form. |
-+---------+-------------------------------------------------------------------+
-|download |For a Link or Multilink property, display the names of the linked |
-| |nodes, hyperlinked to the item views on those nodes. |
-| |For other properties, link to this node with the property as the |
-| |text. |
-| |In all cases, append the name (key property) of the item to the |
-| |path so it is the name of the file being downloaded. |
-| |Arguments: |
-| |property (property name) - the property to use. |
-+---------+-------------------------------------------------------------------+
-|checklist|For a Link or Multilink property, display checkboxes for the |
-| |available choices to permit filtering. |
-| |Arguments: |
-| |property (property name) - the property to use. |
-+---------+-------------------------------------------------------------------+
-|note |Display the special notes field, which is a text area for entering |
-| |a note to go along with a change. |
-+---------+-------------------------------------------------------------------+
-|list |List the nodes specified by property using the standard index for |
-| |the class. |
-| |Arguments: |
-| |property (property name) - the property to use. |
-+---------+-------------------------------------------------------------------+
-|history |List the history of the item. |
-+---------+-------------------------------------------------------------------+
-|submit |Add a submit button for the item. |
-+---------+-------------------------------------------------------------------+
-
-
-Index Views
-~~~~~~~~~~~
-
-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.
-
-Index View Specifiers
-:::::::::::::::::::::
-
-An index view specifier (URL fragment) looks like this (whitespace has been
-added for clarity)::
-
- /issue?status=unread,in-progress,resolved&
- topic=security,ui&
- :group=+priority&
- :sort=-activity&
- :filters=status,topic&
- :columns=title,status,fixer
-
-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.
-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.
-
-The filter part selects the union of the sets of items with values matching any
-specified Link properties and the intersection of the sets of items with values
-matching any specified Multilink properties.
-
-The example specifies an index of "issue" nodes. Only items with a "status" of
-either "unread" or "in-progres" or "resolved" are displayed, and only items
-with "topic" values including both "security" and "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.
-
-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.
-
-Filter Section
-::::::::::::::
-
-The template for a filter section provides the filtering widgets at the top of
-the index view. Fragments enclosed in <property>...</property> tags are
-included or omitted depending on whether the view specifier requests a filter
-for a particular property.
-
-A property must appear in the filter template for it to be available as a
-filter.
-
-Here's a simple example of a filter template.::
-
- <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>
-
-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.
-
-Index Section
-:::::::::::::
-
-The template for an index section describes one row of the index table.
-Fragments enclosed in <property>...</property> tags are included or omitted
-depending on whether the view specifier requests a column for a particular
-property. The table cells should contain <display> tags to display the values
-of the item's properties.
-
-Here's a simple example of an index template.::
-
- <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>
-
-Sorting
-:::::::
-
-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.
-
-Item Views
-~~~~~~~~~~
-
-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.
-
-Editor Section
-::::::::::::::
-
-The editor section is generated from a template containing <display> tags to
-insert the appropriate widgets for editing properties.
-
-Here's an example of a basic editor template.::
-
- <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>
-
-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.
-
-When a change is submitted, the system automatically generates a message
-describing the changed properties.
-
-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).
-
-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::
-
- 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
-
-Spool Section
-:::::::::::::
-
-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.
-
-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.::
-
- <property name="files">
- <tr class="strong-header">
- <td><b>Files</b></td>
- </tr>
-
- <tr>
- <td><display call="list('files')"></td>
- </tr>
- </property>
-
-
diff --git a/doc/customizing.txt b/doc/customizing.txt
--- /dev/null
+++ b/doc/customizing.txt
@@ -0,0 +1,558 @@
+Customising Roundup
+===================
+
+Instances have the following structure:
+
++-------------------+--------------------------------------------------------+
+|instance_config.py |Holds the basic instance_configuration |
++-------------------+--------------------------------------------------------+
+|dbinit.py |Holds the instance_schema |
++-------------------+--------------------------------------------------------+
+|interfaces.py |Defines the Web and E-Mail interfaces for the instance |
++-------------------+--------------------------------------------------------+
+|select_db.py |Selects the database back-end for the instance |
++-------------------+--------------------------------------------------------+
+|db/ |Holds the instance's database |
++-------------------+--------------------------------------------------------+
+|db/files/ |Holds the instance's upload files and messages |
++-------------------+--------------------------------------------------------+
+|detectors/ |Auditors and reactors for this instance |
++-------------------+--------------------------------------------------------+
+|html/ |Web interface templates, images and style sheets |
++-------------------+--------------------------------------------------------+
+
+Instance Configuration
+----------------------
+
+The instance_config.py 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 instance_config.py is given below - as you
+can see, the MAIL_DOMAIN must be edited before any interaction with the
+instance is attempted.::
+
+ 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'
+
+
+Instance Schema
+---------------
+
+Note: if you modify the schema, you'll most likely need to edit the
+ `web interface`_ HTML template files to reflect your changes.
+
+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::
+
+ 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')
+
+Classes and Properties - creating a new information store
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the instance above, we've defined 7 classes of information:
+
+ priority
+ Defines the possible levels of urgency for issues.
+
+ status
+ Defines the possible states of processing the issue may be in.
+
+ keyword
+ Initially empty, will hold keywords useful for searching issues.
+
+ user
+ Initially holding the "admin" user, will eventually have an entry for all
+ users using roundup.
+
+ msg
+ Initially empty, will all e-mail messages sent to or generated by
+ roundup.
+
+ file
+ Initially empty, will all files attached to issues.
+
+ issue
+ Initially emtyp, this is where the issue information is stored.
+
+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.
+
+Class and Nodes
+:::::::::::::::
+
+A Class 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.
+The actual data entered into the database, using class.create() are called
+nodes. They have a special immutable property called id. We sometimes refer to
+this as the nodeid.
+
+Properties
+::::::::::
+
+A Class is comprised of one or more properties of the following types:
+ * String properties are for storing arbitrary-length strings.
+ * Password properties are for storing encoded arbitrary-length strings. The
+ default encoding is defined on the roundup.password.Password class.
+ * Date properties store date-and-time stamps. Their values are Timestamp
+ objects.
+ * A Link 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.
+ * A Multilink property refers to possibly many nodes in a specified class.
+ The value is a list of integers.
+
+FileClass
+:::::::::
+
+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.
+
+IssueClass
+::::::::::
+
+IssueClasses automatically include the "messages", "files", "nosy", and
+"superseder" properties.
+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.
+They also have the dynamically generated "creation", "activity" and "creator"
+properties.
+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.
+
+setkey(property)
+::::::::::::::::
+
+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::
+
+ roundup-admin set issue assignedto=2
+
+or::
+
+ roundup-admin set issue assignedto=richard
+
+Note, the same thing can be done in the web and e-mail interfaces.
+
+create(information)
+:::::::::::::::::::
+
+Create a node in the database. This is generally used to create nodes in the
+"definitional" classes like "priority" and "status".
+
+Web Interface
+-------------
+
+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.
+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.
+
+Repurcussions of changing the instance schema
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you choose to change_the_instance_schema you will need to ensure the web
+interface knows about it:
+
+ 1. Index, item and filter pages for the relevant classes may need to have
+ properties added or removed,
+ 2. 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.
+
+Displaying Properties
+~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+The display of a property is handled by functions in the htmltemplate module.
+Displayer functions are triggered by <display> tags in templates. The call
+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::
+
+ <display call="plain('status')">
+
+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.
+
++-----------------------------------------------------------------------------+
+|The displayer functions are |
++---------+-------------------------------------------------------------------+
+|plain |Display a String property directly. |
+| |Display a Date property in a specified time zone with an option to |
+| |omit the time from the date stamp. |
+| |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). |
+| |Options: |
+| |escape (boolean) - HTML-escape the resulting text. |
++---------+-------------------------------------------------------------------+
+|field |Display a property like the plain 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. |
+| |Options: |
+| |size (number) - width of TEXT fields. |
+| |height (number) - number of nows in SELECT MULTIPLE tags. |
+| |showid (boolean) - true includes the id of linked nodes in the |
+| |SELECT MULTIPLE fields. |
++---------+-------------------------------------------------------------------+
+|menu |For a Links and Multilinks, display the same field as would be |
+| |generated using field. |
++---------+-------------------------------------------------------------------+
+|link |For a Link or Multilink property, display the names of the linked |
+| |nodes, hyperlinked to the item views on those nodes. |
+| |For other properties, link to this node with the property as the |
+| |text. |
+| |Options: |
+| |property (property name) - the property to use in the second case. |
++---------+-------------------------------------------------------------------+
+|count |For a Multilink property, display a count of the number of links in|
+| |the list. |
+| |Arguments: |
+| |property (property name) - the property to use. |
++---------+-------------------------------------------------------------------+
+|reldate |Display a Date property in terms of an interval relative to the |
+| |current date (e.g. "+ 3w", "- 2d"). |
+| |Arguments: |
+| |property (property name) - the property to use. |
+| |Options: |
+| |pretty (boolean) - display the relative date in an English form. |
++---------+-------------------------------------------------------------------+
+|download |For a Link or Multilink property, display the names of the linked |
+| |nodes, hyperlinked to the item views on those nodes. |
+| |For other properties, link to this node with the property as the |
+| |text. |
+| |In all cases, append the name (key property) of the item to the |
+| |path so it is the name of the file being downloaded. |
+| |Arguments: |
+| |property (property name) - the property to use. |
++---------+-------------------------------------------------------------------+
+|checklist|For a Link or Multilink property, display checkboxes for the |
+| |available choices to permit filtering. |
+| |Arguments: |
+| |property (property name) - the property to use. |
++---------+-------------------------------------------------------------------+
+|note |Display the special notes field, which is a text area for entering |
+| |a note to go along with a change. |
++---------+-------------------------------------------------------------------+
+|list |List the nodes specified by property using the standard index for |
+| |the class. |
+| |Arguments: |
+| |property (property name) - the property to use. |
++---------+-------------------------------------------------------------------+
+|history |List the history of the item. |
++---------+-------------------------------------------------------------------+
+|submit |Add a submit button for the item. |
++---------+-------------------------------------------------------------------+
+
+
+Index Views
+~~~~~~~~~~~
+
+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.
+
+Index View Specifiers
+:::::::::::::::::::::
+
+An index view specifier (URL fragment) looks like this (whitespace has been
+added for clarity)::
+
+ /issue?status=unread,in-progress,resolved&
+ topic=security,ui&
+ :group=+priority&
+ :sort=-activity&
+ :filters=status,topic&
+ :columns=title,status,fixer
+
+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.
+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.
+
+The filter part selects the union of the sets of items with values matching any
+specified Link properties and the intersection of the sets of items with values
+matching any specified Multilink properties.
+
+The example specifies an index of "issue" nodes. Only items with a "status" of
+either "unread" or "in-progres" or "resolved" are displayed, and only items
+with "topic" values including both "security" and "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.
+
+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.
+
+Filter Section
+::::::::::::::
+
+The template for a filter section provides the filtering widgets at the top of
+the index view. Fragments enclosed in <property>...</property> tags are
+included or omitted depending on whether the view specifier requests a filter
+for a particular property.
+
+A property must appear in the filter template for it to be available as a
+filter.
+
+Here's a simple example of a filter template.::
+
+ <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>
+
+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.
+
+Index Section
+:::::::::::::
+
+The template for an index section describes one row of the index table.
+Fragments enclosed in <property>...</property> tags are included or omitted
+depending on whether the view specifier requests a column for a particular
+property. The table cells should contain <display> tags to display the values
+of the item's properties.
+
+Here's a simple example of an index template.::
+
+ <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>
+
+Sorting
+:::::::
+
+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.
+
+Item Views
+~~~~~~~~~~
+
+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.
+
+Editor Section
+::::::::::::::
+
+The editor section is generated from a template containing <display> tags to
+insert the appropriate widgets for editing properties.
+
+Here's an example of a basic editor template.::
+
+ <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>
+
+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.
+
+When a change is submitted, the system automatically generates a message
+describing the changed properties.
+
+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).
+
+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::
+
+ 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
+
+Spool Section
+:::::::::::::
+
+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.
+
+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.::
+
+ <property name="files">
+ <tr class="strong-header">
+ <td><b>Files</b></td>
+ </tr>
+
+ <tr>
+ <td><display call="list('files')"></td>
+ </tr>
+ </property>
+
+
diff --git a/doc/getting_started.stx b/doc/getting_started.stx
--- a/doc/getting_started.stx
+++ /dev/null
@@ -1,258 +0,0 @@
-Getting Started
-===============
-
-The following instructions assume that you have installed roundup. If you
-haven't, you may still proceed - just run the commands as
-"``PYTHONPATH=. python roundup/scripts/roundup_admin.py``" for
-``roundup-admin`` and
-"``PYTHONPATH=. python roundup/scripts/roundup_server.py``" for
-``roundup-server``.
-
-The Instance
-------------
-
-We'll be referring to the term instance 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:
-
-Hyperdatabase
- This is the lowest component of Roundup and is where all the issues,
- users, file attachments and messages are stored.
-
-Database schema
- 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.
-
-Web Interface
- 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.
-
-Instances are created using the ``roundup-admin`` tool.
-
-Command Line Tool
------------------
-
-To initiliase a new instance, run "``roundup-admin init``". You will be asked a
-series of questions:
-
-1. Instance home directory
-2. Schema to use
-3. Database back-end to use
-4. Administration user "admin" password.
-
-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
-Users_and_Access_Control for information on how to secure your instance from the
-start.
-
-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:
-
-MAILHOST
- The SMTP mail host that roundup will use to send mail
-MAIL_DOMAIN
- The domain name used for email addresses
-ISSUE_TRACKER_WEB
- The web address of the issue tracker's web interface
-
-The email addresses used by the system by default are:
-
-ISSUE_TRACKER_EMAIL: ``issue_tracker@MAIL_DOMAIN``
- submissions of issues
-
-ADMIN_EMAIL: ``roundup-admin@MAIL_DOMAIN``
- roundup's internal use (problems, etc)
-
-E-Mail Interface
-----------------
-
-Setup 1: As a mail alias pipe process
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Set up a mail alias called "issue_tracker" as (include the quote marks):
-"``|/usr/bin/python /usr/local/bin/roundup-mailgw <instance_home>``"
-
-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::
-
- |roundup-mailgw <instance_home>
-
-To test the mail gateway on unix systems, try::
-
- echo test |mail -s '[issue] test' issue_tracker@your.domain
-
-
-Setup 2: As a regular cron job using a mailbox source
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Set ``roundup-mailgw`` up to run every 10 minutes or so. For example::
-
- 10 * * * * /usr/local/bin/roundup-mailgw <instance_home> mailbox <mail_spool_file>
-
-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``".
-
-Setup 3: As a regular cron job using a POP source
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To retrieve from a POP mailbox, use a similar cron entry to the mailbox one::
-
- 10 * * * * /usr/local/bin/roundup-mailgw <instance_home> pop <pop_spec>
-
-where pop_spec is "``username:password@server``" that specifies the roundup
-submission user's POP account name, password and server.
-
-
-Web Interface
--------------
-
-This software will work through apache or stand-alone.
-
-Stand-alone:
- 1. 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.
-
- 2. "``roundup-server [-p port] (name=instance_home)*``" (hostname may be "")
-
- 3. Load up the page "``/<instance name>/index``" where instance name is the name
- you nominated in ``ROUNDUP_INSTANCE_HOMES``.
-
-Apache:
- 1. The CGI script is found in the cgi-bin directory of the roundup
- distribution.
-
- 2. Make sure roundup.cgi is executable. Edit it at the top -
- ``ROUNDUP_INSTANCE_HOMES`` needs to know about your instance.
-
- 3. 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.
-
- 4. Re-start your apache to re-load the config if necessary.
-
- 5. Load up the page "``/roundup/roundup.cgi/index/``" where instance name is the
- name you nominated in ``ROUNDUP_INSTANCE_HOMES``.
-
- 6. To use the CGI script unchanged, which allows much easier updates, add
- these directives to your "httpd.conf"::
-
- SetEnv ROUNDUP_LOG "/var/log/roundup.log"
- SetEnv ROUNDUP_INSTANCE_HOMES "Default=/usr/local/share/roundup/instances/Default"
- SetEnv ROUNDUP_DEBUG "0"
-
- 7. On Windows, write a batch file "roundup.bat" similar to the one below and
- place it into your cgi-bin directory::
-
- @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
-
-
-Users
------
-
-Users and permissions
-~~~~~~~~~~~~~~~~~~~~~
-
-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.
-
-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:
-
-Command-line interface
- 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:
-
- 1. Add a new user and group to your system (e.g. "issue_tracker")
-
- 2. When creating a new instance home, use the following commands
- (substituting instance_home for the directory you want to use)::
-
- mkdir instance_home
- chown issue_tracker:issue_tracker instance_home
- chmod g+rwxs instance_home
- roundup-admin -i instance_home init
-
- 3. 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".)
-
-E-Mail interface
- 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 always
- identified by roundup.
-
-Web interface
- 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.
-
-**anonymous access and the ANONYMOUS_* configurations.**
-
-
-Adding users
-~~~~~~~~~~~~
-
-To add users, use one of the following interfaces:
-
-1. On the web, access the URL .../<instance name>/newuser to bring up a form
- which may be used to add a new user.
-
-2. On the command-line, use::
-
- roundup-admin -i <instance home> create user username=bozo password=bozo
- address=richard@clown.org
-
- Supply the admin username and password. roundup-admin will print the id
- of the new user.
-
-3. 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.
-
-
-Issues
-------
-
-To add issues, use one of the following interfaces:
-
-1. On the web, access the URL .../<instance name>/newissue to bring up a
- form which may be used to add a new issue.
-
-2. On the command-line, use::
-
- roundup-admin -i <instance home> create issue title="test issue"
-
- Supply the admin username and password. roundup-admin will print the id
- of the new issue.
-
-3. 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.
-
-
diff --git a/doc/getting_started.txt b/doc/getting_started.txt
--- /dev/null
+++ b/doc/getting_started.txt
@@ -0,0 +1,258 @@
+Getting Started
+===============
+
+The following instructions assume that you have installed roundup. If you
+haven't, you may still proceed - just run the commands as
+"``PYTHONPATH=. python roundup/scripts/roundup_admin.py``" for
+``roundup-admin`` and
+"``PYTHONPATH=. python roundup/scripts/roundup_server.py``" for
+``roundup-server``.
+
+The Instance
+------------
+
+We'll be referring to the term instance 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:
+
+Hyperdatabase
+ This is the lowest component of Roundup and is where all the issues,
+ users, file attachments and messages are stored.
+
+Database schema
+ 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.
+
+Web Interface
+ 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.
+
+Instances are created using the ``roundup-admin`` tool.
+
+Command Line Tool
+-----------------
+
+To initiliase a new instance, run "``roundup-admin init``". You will be asked a
+series of questions:
+
+1. Instance home directory
+2. Schema to use
+3. Database back-end to use
+4. Administration user "admin" password.
+
+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
+Users_and_Access_Control for information on how to secure your instance from the
+start.
+
+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:
+
+MAILHOST
+ The SMTP mail host that roundup will use to send mail
+MAIL_DOMAIN
+ The domain name used for email addresses
+ISSUE_TRACKER_WEB
+ The web address of the issue tracker's web interface
+
+The email addresses used by the system by default are:
+
+ISSUE_TRACKER_EMAIL: ``issue_tracker@MAIL_DOMAIN``
+ submissions of issues
+
+ADMIN_EMAIL: ``roundup-admin@MAIL_DOMAIN``
+ roundup's internal use (problems, etc)
+
+E-Mail Interface
+----------------
+
+Setup 1: As a mail alias pipe process
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Set up a mail alias called "issue_tracker" as (include the quote marks):
+"``|/usr/bin/python /usr/local/bin/roundup-mailgw <instance_home>``"
+
+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::
+
+ |roundup-mailgw <instance_home>
+
+To test the mail gateway on unix systems, try::
+
+ echo test |mail -s '[issue] test' issue_tracker@your.domain
+
+
+Setup 2: As a regular cron job using a mailbox source
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Set ``roundup-mailgw`` up to run every 10 minutes or so. For example::
+
+ 10 * * * * /usr/local/bin/roundup-mailgw <instance_home> mailbox <mail_spool_file>
+
+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``".
+
+Setup 3: As a regular cron job using a POP source
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To retrieve from a POP mailbox, use a similar cron entry to the mailbox one::
+
+ 10 * * * * /usr/local/bin/roundup-mailgw <instance_home> pop <pop_spec>
+
+where pop_spec is "``username:password@server``" that specifies the roundup
+submission user's POP account name, password and server.
+
+
+Web Interface
+-------------
+
+This software will work through apache or stand-alone.
+
+Stand-alone:
+ 1. 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.
+
+ 2. "``roundup-server [-p port] (name=instance_home)*``" (hostname may be "")
+
+ 3. Load up the page "``/<instance name>/index``" where instance name is the name
+ you nominated in ``ROUNDUP_INSTANCE_HOMES``.
+
+Apache:
+ 1. The CGI script is found in the cgi-bin directory of the roundup
+ distribution.
+
+ 2. Make sure roundup.cgi is executable. Edit it at the top -
+ ``ROUNDUP_INSTANCE_HOMES`` needs to know about your instance.
+
+ 3. 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.
+
+ 4. Re-start your apache to re-load the config if necessary.
+
+ 5. Load up the page "``/roundup/roundup.cgi/index/``" where instance name is the
+ name you nominated in ``ROUNDUP_INSTANCE_HOMES``.
+
+ 6. To use the CGI script unchanged, which allows much easier updates, add
+ these directives to your "httpd.conf"::
+
+ SetEnv ROUNDUP_LOG "/var/log/roundup.log"
+ SetEnv ROUNDUP_INSTANCE_HOMES "Default=/usr/local/share/roundup/instances/Default"
+ SetEnv ROUNDUP_DEBUG "0"
+
+ 7. On Windows, write a batch file "roundup.bat" similar to the one below and
+ place it into your cgi-bin directory::
+
+ @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
+
+
+Users
+-----
+
+Users and permissions
+~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+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:
+
+Command-line interface
+ 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:
+
+ 1. Add a new user and group to your system (e.g. "issue_tracker")
+
+ 2. When creating a new instance home, use the following commands
+ (substituting instance_home for the directory you want to use)::
+
+ mkdir instance_home
+ chown issue_tracker:issue_tracker instance_home
+ chmod g+rwxs instance_home
+ roundup-admin -i instance_home init
+
+ 3. 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".)
+
+E-Mail interface
+ 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 always
+ identified by roundup.
+
+Web interface
+ 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.
+
+**anonymous access and the ANONYMOUS_* configurations.**
+
+
+Adding users
+~~~~~~~~~~~~
+
+To add users, use one of the following interfaces:
+
+1. On the web, access the URL .../<instance name>/newuser to bring up a form
+ which may be used to add a new user.
+
+2. On the command-line, use::
+
+ roundup-admin -i <instance home> create user username=bozo password=bozo
+ address=richard@clown.org
+
+ Supply the admin username and password. roundup-admin will print the id
+ of the new user.
+
+3. 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.
+
+
+Issues
+------
+
+To add issues, use one of the following interfaces:
+
+1. On the web, access the URL .../<instance name>/newissue to bring up a
+ form which may be used to add a new issue.
+
+2. On the command-line, use::
+
+ roundup-admin -i <instance home> create issue title="test issue"
+
+ Supply the admin username and password. roundup-admin will print the id
+ of the new issue.
+
+3. 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.
+
+
diff --git a/doc/index.stx b/doc/index.stx
--- a/doc/index.stx
+++ /dev/null
@@ -1,30 +0,0 @@
-*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/index.txt b/doc/index.txt
--- /dev/null
+++ b/doc/index.txt
@@ -0,0 +1,83 @@
+*Roundup: an Issue-Tracking System for Knowledge Workers*
+
+Contents
+========
+
+- Overview_
+- Installation_
+- `Getting Started`_
+- `User Guide`_
+- `Customising Roundup`_
+- `Roundup's Design Document`_
+- Contact_
+- Acknowledgements_
+- License_
+
+.. _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
+
+
+Contact
+=======
+
+For general support enquiries about usage, a mailing list is available:
+
+ roundup-users@sourceforge.net
+
+If you've got a great idea for roundup, or have found a bug, please
+submit
+an issue to the tracker at:
+
+ http://sourceforge.net/tracker/?group_id=31577
+
+For discussions about developing or enhancing roundup:
+
+ roundup-devel@sourceforge.net
+
+The admin for this project is Richard Jones:
+
+ richard@users.sourceforge.net
+
+but he should only be contacted directly when none of the
+above avenues of contact are suitable.
+
+
+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.
+
+
+License
+=======
+
+Copyright (c) 2001 Bizar Software Pty Ltd (http://www.bizarsoftware.com.au/)
+
+This module is free software, and you may redistribute it and/or modify
+under the same terms as Python, so long as this copyright message and
+disclaimer are retained in their original form.
+
+IN NO EVENT SHALL BIZAR SOFTWARE PTY LTD BE LIABLE TO ANY PARTY FOR
+DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OF THIS CODE, EVEN IF BIZAR SOFTWARE PTY LTD HAS BEEN
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+BIZAR SOFTWARE PTY LTD SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
+BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+FOR A PARTICULAR PURPOSE. THE CODE PROVIDED HEREUNDER IS ON AN "AS IS"
+BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
+SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
+
+
+The stylesheet included with this package has been copied from the Zope
+management interface and presumably belongs to Digital Creations.
+
diff --git a/doc/installation.stx b/doc/installation.stx
--- a/doc/installation.stx
+++ /dev/null
@@ -1,223 +0,0 @@
-Installing Roundup
-==================
-
-`Table of contents`_
-
-- Overview_
-
- - `Classic Template`_
- - `Extended Template`_
-
-- Prerequisites_
-
- - `Testing your Python`_
-
-- `Getting Roundup`_
-- `Installation`_
-- `Further Reading`_
-- `Platform-Specific Notes`_
-
-Overview
-========
-
-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 follows.
-
-Classic Template
-----------------
-
-The classic template is the one defined in the `Roundup Specification`_. It
-holds issues which have priorities and statuses. Each issue may also have a
-set of messages which are disseminated to the issue's list of nosy users.
-
-
-Extended Template
------------------
-
-The extended template adds additional information to issues: product,
-platform, version, targetversion and supportcall.
-There is an additional class for
-handling support calls, which includes a time log, customername, rate and
-source.
-
-The priorty class has different default entries too: "fatal-bug", "bug",
-"usability" and "feature".
-
-Users of this template will want to change the contents of the product
-class as soon as the instance is created.
-
-
-Prerequisites
-=============
-
-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/.
-
-
-Installation
-============
-
-Set aside 15-30 minutes.
-
-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 the Overview_::
-
- 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 `Customising Roundup`_.
-
-
-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.
-
-2. change your alias to ``"|roundup-mailgw <instance_home>"``
-
-
-Linux
------
-
-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
-.. _`roundup specification`: spec.html
-.. _`customising roundup`: customizing.html
-
-$Id: installation.stx,v 1.3 2002-03-09 22:46:52 richard Exp $
diff --git a/doc/installation.txt b/doc/installation.txt
--- /dev/null
+++ b/doc/installation.txt
@@ -0,0 +1,223 @@
+Installing Roundup
+==================
+
+`Table of contents`_
+
+- Overview_
+
+ - `Classic Template`_
+ - `Extended Template`_
+
+- Prerequisites_
+
+ - `Testing your Python`_
+
+- `Getting Roundup`_
+- `Installation`_
+- `Further Reading`_
+- `Platform-Specific Notes`_
+
+Overview
+========
+
+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 follows.
+
+Classic Template
+----------------
+
+The classic template is the one defined in the `Roundup Specification`_. It
+holds issues which have priorities and statuses. Each issue may also have a
+set of messages which are disseminated to the issue's list of nosy users.
+
+
+Extended Template
+-----------------
+
+The extended template adds additional information to issues: product,
+platform, version, targetversion and supportcall.
+There is an additional class for
+handling support calls, which includes a time log, customername, rate and
+source.
+
+The priorty class has different default entries too: "fatal-bug", "bug",
+"usability" and "feature".
+
+Users of this template will want to change the contents of the product
+class as soon as the instance is created.
+
+
+Prerequisites
+=============
+
+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/.
+
+
+Installation
+============
+
+Set aside 15-30 minutes.
+
+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 the Overview_::
+
+ 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 `Customising Roundup`_.
+
+
+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.
+
+2. change your alias to ``"|roundup-mailgw <instance_home>"``
+
+
+Linux
+-----
+
+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
+.. _`roundup specification`: spec.html
+.. _`customising roundup`: customizing.html
+
+$Id: installation.txt,v 1.1 2002-03-13 23:00:48 richard Exp $
diff --git a/doc/user_guide.stx b/doc/user_guide.stx
--- a/doc/user_guide.stx
+++ /dev/null
@@ -1,276 +0,0 @@
-User Guide
-==========
-
-Command Line Tool
------------------
-
-Usage: ``roundup-admin [-i instance home] [-u login] [-c] <command> <arguments>``
-
-Options:
-
--i instance home specify the issue tracker "home directory" to administer
--u the ``user[:password]`` to use for commands
--c when outputting lists of data, comma-separate them
-
-+-----------------------------------------------------------------------------+
-| Command Help |
-+=============+===============================================================+
-|commit |Usage: commit |
-| |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. |
-+-------------+---------------------------------------------------------------+
-|create |Usage: create classname property=value ... |
-| |This creates a new entry of the given class using the property |
-| |name=value arguments provided on the command line after the |
-| |"create" command. |
-+-------------+---------------------------------------------------------------+
-|display |Usage: display designator |
-| |This lists the properties and their associated values for the |
-| |given node. |
-+-------------+---------------------------------------------------------------+
-|export |Usage: export class[,class] destination dir |
-| |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. |
-+-------------+---------------------------------------------------------------+
-|find |Usage: find classname propname=value ... |
-| |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. |
-+-------------+---------------------------------------------------------------+
-|get |Usage: get property designator[,designator]* |
-| |Retrieves the property value of the nodes specified by the |
-| |designators. |
-+-------------+---------------------------------------------------------------+
-|help |Usage: help topic |
-| |commands -- list commands |
-| |x -- help specific to a command |
-| |initopts -- init command options |
-| |all -- all available help |
-+-------------+---------------------------------------------------------------+
-|history |Usage: history designator |
-| |Lists the journal entries for the node identified by the |
-| |designator. |
-+-------------+---------------------------------------------------------------+
-|import |Usage: import class file |
-| |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.) |
-+-------------+---------------------------------------------------------------+
-|initialise |Usage: initialise [template [backend [admin password]]] |
-| |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. |
-+-------------+---------------------------------------------------------------+
-|list |Usage: list classname [property] |
-| |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. |
-+-------------+---------------------------------------------------------------+
-|retire |Usage: retire designator[,designator]* |
-| |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. |
-+-------------+---------------------------------------------------------------+
-|rollback |Usage: rollback |
-| |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. |
-+-------------+---------------------------------------------------------------+
-|set |Usage: set designator[,designator]* propname=value ... |
-| |Sets the property to the value for all designators given. |
-+-------------+---------------------------------------------------------------+
-|specification|Usage: specification classname |
-| |This lists the properties for a given class. |
-+-------------+---------------------------------------------------------------+
-|table |Usage: table classname [property[,property]*] |
-| |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 |
-+-------------+---------------------------------------------------------------+
-
-
-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``".
-
-A designator is a classname and a nodeid concatenated, eg. bug1, user10, ...
-Property values are represented as strings in command arguments and in the printed
-results:
-
-- Strings are, well, strings.
-- Password values will display as their encoded value.
-- 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.::
-
- Input of... Means...
- "2000-04-17.03:45" 2000-04-17.08:45:00
- "2000-04-17" 2000-04-17.00:00:00
- "01-25" yyyy-01-25.00:00:00
- "08-13.22:13" yyyy-08-14.03:13:00
- "11-07.09:32:43" yyyy-11-07.14:32:43
- "14:25" yyyy-mm-dd.19:25:00
- "8:47:11" yyyy-mm-dd.13:47:11
- "." "right now"
-
-- Link values are printed as node designators. When given as an argument,
- node designators and key strings are both accepted.
-- 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.
-
-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. 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).
-
-Where the command changes data, a login name/password is required. The login may
-be specified as either "``name``" or "``name:password``".
-
-- ``ROUNDUP_LOGIN`` environment variable
-- the "``-u``" command-line option
-
-If either the name or password is not supplied, they are obtained from the
-command-line.
-
-
-Web Interface
--------------
-
-Index views may be modified by the following arguments:
-
-+-----------+--------------------------------------------------------------+
-| :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). |
-+-----------+--------------------------------------------------------------+
-
-Not sure what to put in here...
-
-E-Mail Gateway
---------------
-
-Performing Actions
-~~~~~~~~~~~~~~~~~~
-
-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).
-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.
-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.
-
-Setting Properties
-~~~~~~~~~~~~~~~~~~
-
-The e-mail interface also provides a simple way to set properties on items. At
-the end of the subject line, propname=value pairs can be specified in square
-brackets, using the same conventions as for the roundup set shell command.
-explanatory message given in the exception.
-
-Message content
-~~~~~~~~~~~~~~~
-
-Incoming messages are examined for multiple parts:
-
-* 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.
-* In a multipart/alternative message or part, we look for a text/plain
- subpart and ignore the other parts.
-
-Message summary
-:::::::::::::::
-
-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.
-
-Address handling
-~~~~~~~~~~~~~~~~
-
-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.
-
-Triggers
-~~~~~~~~
-
-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
-
-Nosy Lists
-::::::::::
-
-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.
-
-
diff --git a/doc/user_guide.txt b/doc/user_guide.txt
--- /dev/null
+++ b/doc/user_guide.txt
@@ -0,0 +1,276 @@
+User Guide
+==========
+
+Command Line Tool
+-----------------
+
+Usage: ``roundup-admin [-i instance home] [-u login] [-c] <command> <arguments>``
+
+Options:
+
+-i instance home specify the issue tracker "home directory" to administer
+-u the ``user[:password]`` to use for commands
+-c when outputting lists of data, comma-separate them
+
++-----------------------------------------------------------------------------+
+| Command Help |
++=============+===============================================================+
+|commit |Usage: commit |
+| |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. |
++-------------+---------------------------------------------------------------+
+|create |Usage: create classname property=value ... |
+| |This creates a new entry of the given class using the property |
+| |name=value arguments provided on the command line after the |
+| |"create" command. |
++-------------+---------------------------------------------------------------+
+|display |Usage: display designator |
+| |This lists the properties and their associated values for the |
+| |given node. |
++-------------+---------------------------------------------------------------+
+|export |Usage: export class[,class] destination dir |
+| |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. |
++-------------+---------------------------------------------------------------+
+|find |Usage: find classname propname=value ... |
+| |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. |
++-------------+---------------------------------------------------------------+
+|get |Usage: get property designator[,designator]* |
+| |Retrieves the property value of the nodes specified by the |
+| |designators. |
++-------------+---------------------------------------------------------------+
+|help |Usage: help topic |
+| |commands -- list commands |
+| |x -- help specific to a command |
+| |initopts -- init command options |
+| |all -- all available help |
++-------------+---------------------------------------------------------------+
+|history |Usage: history designator |
+| |Lists the journal entries for the node identified by the |
+| |designator. |
++-------------+---------------------------------------------------------------+
+|import |Usage: import class file |
+| |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.) |
++-------------+---------------------------------------------------------------+
+|initialise |Usage: initialise [template [backend [admin password]]] |
+| |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. |
++-------------+---------------------------------------------------------------+
+|list |Usage: list classname [property] |
+| |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. |
++-------------+---------------------------------------------------------------+
+|retire |Usage: retire designator[,designator]* |
+| |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. |
++-------------+---------------------------------------------------------------+
+|rollback |Usage: rollback |
+| |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. |
++-------------+---------------------------------------------------------------+
+|set |Usage: set designator[,designator]* propname=value ... |
+| |Sets the property to the value for all designators given. |
++-------------+---------------------------------------------------------------+
+|specification|Usage: specification classname |
+| |This lists the properties for a given class. |
++-------------+---------------------------------------------------------------+
+|table |Usage: table classname [property[,property]*] |
+| |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 |
++-------------+---------------------------------------------------------------+
+
+
+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``".
+
+A designator is a classname and a nodeid concatenated, eg. bug1, user10, ...
+Property values are represented as strings in command arguments and in the printed
+results:
+
+- Strings are, well, strings.
+- Password values will display as their encoded value.
+- 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.::
+
+ Input of... Means...
+ "2000-04-17.03:45" 2000-04-17.08:45:00
+ "2000-04-17" 2000-04-17.00:00:00
+ "01-25" yyyy-01-25.00:00:00
+ "08-13.22:13" yyyy-08-14.03:13:00
+ "11-07.09:32:43" yyyy-11-07.14:32:43
+ "14:25" yyyy-mm-dd.19:25:00
+ "8:47:11" yyyy-mm-dd.13:47:11
+ "." "right now"
+
+- Link values are printed as node designators. When given as an argument,
+ node designators and key strings are both accepted.
+- 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.
+
+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. 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).
+
+Where the command changes data, a login name/password is required. The login may
+be specified as either "``name``" or "``name:password``".
+
+- ``ROUNDUP_LOGIN`` environment variable
+- the "``-u``" command-line option
+
+If either the name or password is not supplied, they are obtained from the
+command-line.
+
+
+Web Interface
+-------------
+
+Index views may be modified by the following arguments:
+
++-----------+--------------------------------------------------------------+
+| :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). |
++-----------+--------------------------------------------------------------+
+
+Not sure what to put in here...
+
+E-Mail Gateway
+--------------
+
+Performing Actions
+~~~~~~~~~~~~~~~~~~
+
+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).
+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.
+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.
+
+Setting Properties
+~~~~~~~~~~~~~~~~~~
+
+The e-mail interface also provides a simple way to set properties on items. At
+the end of the subject line, propname=value pairs can be specified in square
+brackets, using the same conventions as for the roundup set shell command.
+explanatory message given in the exception.
+
+Message content
+~~~~~~~~~~~~~~~
+
+Incoming messages are examined for multiple parts:
+
+* 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.
+* In a multipart/alternative message or part, we look for a text/plain
+ subpart and ignore the other parts.
+
+Message summary
+:::::::::::::::
+
+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.
+
+Address handling
+~~~~~~~~~~~~~~~~
+
+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.
+
+Triggers
+~~~~~~~~
+
+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
+
+Nosy Lists
+::::::::::
+
+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.
+
+