README.txt

   1                                     Roundup
   2                                     =======
   3
   4
   5 1. License
   6 ==========
   7 This software is released under the GNU GPL. The copyright is held by Bizar
   8 Software Pty Ltd (http://www.bizarsoftware.com.au).
   9
  10 The stylesheet included with this package has been copied from the Zope
  11 management interface and presumably belongs to Digital Creations.
  12
  13
  14 2. Installation
  15 ===============
  16 For installation notes, please see the file INSTALL.TXT
  17
  18
  19 3. Usage
  20 ========
  21 The system is designed to accessed through the command-line, e-mail or web
  22 interface.
  23
  24 3.1 Command-line
  25 ----------------
  26 The command-line tool is called "roundup-admin" and is used for most low-level
  27 database manipulations such as:
  28  . creating a database instance
  29  . redefining the list of products ("create" and "retire" commands)
  30  . adding users manually, or setting their passwords ("create" and "set")
  31  . other stuff - run it with no arguments to get a better description of
  32    what it does.
  33
  34
  35 3.2 E-mail
  36 ----------
  37 See the docstring at the start of the roundup/mailgw.py source file.
  38
  39
  40 3.3 Web
  41 -------
  42 Hopefully, this interface is pretty self-explanatory...
  43
  44 Index views may be modified by the following arguments:
  45     :sort    - sort by prop name, optionally preceeded with '-'
  46              to give descending or nothing for ascending sorting.
  47     :group   - group by prop name, optionally preceeded with '-' or
  48              to sort in descending or nothing for ascending order.
  49     :filter  - selects which props should be displayed in the filter
  50              section. Default is all.
  51     :columns - selects the columns that should be displayed.
  52              Default is all.
  53     propname - selects the values the node properties given by propname
  54              must have (very basic search/filter).
  55
  56
  57
  58 3. Design
  59 =========
  60 This software was written according to the specification found at
  61
  62  http://software-carpentry.codesourcery.com/entries/second-round/track/Roundup/
  63
  64 a copy of the spec is distributed with roundup as doc/spec.html.
  65
  66
  67 There have been some modifications. I've marked these in the source with
  68 'XXX' comments when I remember to.
  69
  70 In short:
  71  Class.find() - may match multiple properties, uses keyword args.
  72
  73  Class.filter() - isn't in the spec and it's very useful to have at the Class
  74     level.
  75
  76  CGI interface index view specifier layout part - lose the '+' from the
  77     sorting arguments (it's a reserved URL character ;). Just made no
  78     prefix mean ascending and '-' prefix descending.
  79
  80  ItemClass - renamed to IssueClass to better match it only having one
  81     hypderdb class "issue". Allowing > 1 hyperdb class breaks the
  82     "superseder" multilink (since it can only link to one thing, and we'd
  83     want bugs to link to support and vice-versa).
  84
  85  templates - the call="link()" is handled by special-case mechanisms in my
  86     top-level CGI handler. In a nutshell, the handler looks for a method on
  87     itself called 'index%s' or 'item%s' where %s is a class. Most items
  88     pass on to the templating mechanism, but the file class _always_ does
  89     downloading. It'll probably stay this way too...
  90
  91  template - call="link(property)" may be used to link "the current node"
  92     (from an index) - the link text is the property specified.
  93
  94  template - added functions that I found very useful: List, History and
  95     Submit.
  96
  97  template - items must specify the message lists, history, etc. Having them
  98     by default was sometimes not wanted.
  99
 100  template - index view determines its default columns from the template's
 101     <property> tags.
 102
 103  template - menu() and field() look awfully similar now .... ;)
 104
 105  roundup.py - the command-line tool has a lot more commands at its disposal
 106
 107
 108
 109 4. TODO
 110 =======
 111 Most of the TODO items are captured in comments in the code. In summary:
 112
 113 in general:
 114   . better error handling (nicer messages for users)
 115   . possibly revert the entire damn thing to 1.5.2 ... :(
 116 roundup.py:
 117   . getopt() for command line
 118   . default init db in some way?
 119 hyperdb:
 120   . transaction support
 121 roundupdb:
 122   . split the file storage into multiple files
 123 roundup-mailgw:
 124   . errors as attachments
 125   . snip signatures?
 126 server:
 127   . check the source file timestamps before reloading
 128 date:
 129   . blue Date.__sub__ needs food, badly
 130 config
 131   . default to blank config in distribution and warn appropriately
 132 roundup_cgi
 133   . searching
 134   . keep form fields in form on bad submission - only clear it if all ok
 135   . messages should have the roundup CGI URL in them
 136
 137
 138 5. Known Bugs
 139 =============
 140
 141 date:
 142   . date subtraction doesn't work correctly "if the dates cross leap years,
 143     phases of the moon, ..."
 144
 145 filter:
 146   . incorrectly embeds hidden fields for filters being displayed - and
 147     doesn't use the existing values for filters being displayed either.
 148
 149
 150 6. Author
 151 =========
 152 richard@sourceforge.net
 153
 154
 155 7. Thanks
 156 =========
 157 Well, Ping, of course ;)
 158
 159 Anthony Baxter, for some good first-release feedback. And then continuing
 160 support through development on sourceforge.
 161