doc

git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@1261 57a73879-2fb5-44c3-a270-3262357dd7e2

diff --git a/doc/customizing.txt b/doc/customizing.txt
index 76e57dc3404e3dd3bc6abcac7336d157b8623fa4..ce2782e3ce05406658c191fd5bb37812a74ab8ff 100644 (file)
--- a/doc/customizing.txt
+++ b/doc/customizing.txt
@@ -2,7 +2,7 @@
 Customising Roundup
 ===================
 
-:Version: $Revision: 1.46 $
+:Version: $Revision: 1.47 $
 
 .. This document borrows from the ZopeBook section on ZPT. The original is at:
    http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
@@ -185,9 +185,8 @@ Note: if you modify the schema, you'll most likely need to edit the
       your changes.
 
 A tracker schema defines what data is stored in the tracker's database.
-The
-schemas shipped with Roundup turn it into a typical software bug tracker or
-help desk.
+The schemas shipped with Roundup turn it into a typical software bug tracker
+or help desk.
 
 XXX make sure we ship the help desk
 
@@ -1489,8 +1488,8 @@ When adding a new Permission, you will need to:
 Examples
 ========
 
-Adding a new field to a roundup schema
---------------------------------------
+Adding a new field to the classic schema
+----------------------------------------
 
 This example shows how to add a new constrained property (ie. a selection of
 distinct values) to your tracker.

diff --git a/doc/default.css b/doc/default.css
index a6c07c55effd98586cfbd2c21b1795302b685a0d..bb21ecc40bb5c46449fe1098e3e9d86910abc012 100644 (file)
--- a/doc/default.css
+++ b/doc/default.css
@@ -1,8 +1,8 @@
 /*
 :Author: David Goodger
 :Contact: goodger@users.sourceforge.net
-:date: $Date: 2002-09-12 03:57:09 $
-:version: $Revision: 1.9 $
+:date: $Date: 2002-09-26 06:41:46 $
+:version: $Revision: 1.10 $
 :copyright: This stylesheet has been placed in the public domain.
 
 Default cascading style sheet for the HTML output of Docutils.
@@ -85,6 +85,7 @@ hr {
   width: 75% }
 
 ol.simple, ul.simple {
+  margin-top: 0;
   margin-bottom: 1em }
 
 ol.arabic {
@@ -212,5 +213,9 @@ h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
 tt {
   background-color: #eeeeee }
 
+tt.literal span.pre {
+  background-color: #eeeeee
+}
+
 ul.auto-toc {
   list-style-type: none }

diff --git a/doc/features.txt b/doc/features.txt
index b7b688adc230b538d2f18b180f68fb805a8d0462..f9c41d5e86df4209e2b48bc9b25192f2e4393e0d 100644 (file)
--- a/doc/features.txt
+++ b/doc/features.txt
@@ -2,27 +2,46 @@
 Roundup Features
 ================
 
-
 Roundup is a simple-to-use and -install issue-tracking system with
 web, e-mail and command-line interfaces. It is based on the winning design
 from Ka-Ping Yee in the Software Carpentry "Track" design competition.
 
+*simple to install*
+ - installation (including web interface) takes about 30 minutes
+ - two templates included in the distribution for you to base your tracker on
+ - doesn't need *any* additional support software - python (2.1+) is enough to
+   get you going
+ - easy to set up higher-performance storage backends like sqlite_ and
+   metakit_
 
 *simple to use*
  - accessible through the web, email, command-line or Python programs
  - may be used to track bugs, features, user feedback, sales opportunities,
-   ...
- - keeps a full history of changes to issues
+   milestones, ...
+ - keeps a full history of changes to issues with configurable verbosity
 
-*simple to install*
- - installation takes about 10 minutes for a basic installation
- - two "template" schemas included in the distribution for you to base your
-   tracker on
- - doesn't need any additional support software - python (2.1+) is enough to
-   get you going
+*highly configurable*
+ - web interface HTML is fully editable
+ - database schema is also fully editable (only the "user" class is required)
+   with a full set of data types (including dates and many-to-many relations)
+   across all storages available
+ - customised automatic auditors and reactors may be written that perform
+   actions before and after changes are made to entries in the database
+ - samples are provided for all types of configuration changes
+
+*fast, scalable*
+ - with the sqlite_ and metakit_ backends, roundup is also fast and scalable,
+   easily handling thousands of issues and users with decent response times
+ - indexed text searching giving fast responses to searches across all
+   messages and indexed string properties
+
+*documented*
+ - documentation exists for installation, upgrading, maintenance, users and
+   customisation
 
 *web interface*
- - fully editable interfaces for indexing and display of items
+ - fully editable interfaces for listing and display of items
+ - extendable to include wizards, parent/meta bug displays, ...
  - differentiates between anonymous, known and admin users
  - may be set up to require login, and may also only allow admin users
    to register new users
@@ -59,10 +78,6 @@ from Ka-Ping Yee in the Software Carpentry "Track" design competition.
  - roundup's API may also be used by other Python programs - a sample is
    provided that runs once a day and emails people their assigned issues
 
-*highly configurable*
- - web interface HTML is fully editable
- - database schema is also fully editable
- - customised automatic auditors and reactors may be written that perform
-   actions before and after changes are made to entries in the database
- - samples are provided for all types of configuration changes
+.. _sqlite: http://www.hwaci.com/sw/sqlite/
+.. _metakit: http://www.equi4.com/metakit/
 

diff --git a/doc/installation.txt b/doc/installation.txt
index c8128383cc451426f7c7433051a74ebc231ed4b8..b35d43c3600a016e050a3af9b27be3626ebd3fde 100644 (file)
--- a/doc/installation.txt
+++ b/doc/installation.txt
@@ -2,7 +2,7 @@
 Installing Roundup
 ==================
 
-:Version: $Revision: 1.27 $
+:Version: $Revision: 1.28 $
 
 .. contents::
 
@@ -62,14 +62,14 @@ Installation
 ============
 
 Set aside 15-30 minutes. Please make sure you're using a supported version of
-Python -- see `testing your python`_. There's three sections to this
-installation guide:
+Python -- see `testing your python`_. There's four steps to follow in your
+installation:
 
 1. `basic installation steps`_ that all installers must follow
-2. `shared environment steps`_ to take if you're installing on a shared
+2. then optionally `configure a web interface`_
+3. and optionally `configure an email interface`_
+4. `shared environment steps`_ to take if you're installing on a shared
     UNIX machine and want to restrict local access to roundup
-3. `internet setup`_ steps to take if your tracker is to be used by the wider
-    internet community
 
 Most users will only need to follow the first step, since the environment will
 be a trusted one.
@@ -95,7 +95,7 @@ Basic Installation Steps
 
    a. (Optional) If you intend to keep your roundup trackers
       under one top level directory which does not exist yet,
-      you should create that directory now.  Example:
+      you should create that directory now.  Example::
 
          mkdir /opt/roundup/trackers
 
@@ -103,13 +103,12 @@ Basic Installation Steps
       environment variable or specify the full path to
       the command in the next step.
 
-   c.  ``roundup-admin install``
-
+   c. Install a new tracker with the command ``roundup-admin install``.
       You will be asked a series of questions.  Descriptions of the provided
       templates can be found in `choosing your template`_ below.  Descriptions
       of the available backends can be found in `choosing your backend`_
       below.  The questions will be something like (you may have more
-      templates or backends available):
+      templates or backends available)::
 
           Enter tracker home: /opt/roundup/trackers/support
           Templates: classic
@@ -123,19 +122,18 @@ Basic Installation Steps
       after you've initialised the tracker - it's just better to have valid
       values for this stuff now.
 
-   d.  ``roundup-admin initialise``
-
-      This step initialises the tracker database. You will need to supply
-      an admin password at this step. You will be prompted::
+   d. Initialise the tracker database with ``roundup-admin initialise``.
+      You will need to supply an admin password at this step. You will be
+      prompted::
 
           Admin Password:
                  Confirm:
 
       Once this is done, the tracker has been created.
 
-3. XXX Set up the CGI interface
-
-4. XXX Set up the mail gateway
+At this point, your tracker is set up, but doesn't have a nice user interface.
+To set that up, we need to `configure a web interface`_ and optionally
+`configure an email interface`_.
 
 
 Choosing Your Template
@@ -175,12 +173,12 @@ There's several to choose from, each with benefits and limitations:
 **bsddb3**
   Again, this effectively the same as anydbm, but uses the bsddb3 backend.
   This allows it to gain some performance and scaling benefits.
-**sqlite**
-  This uses the SQLite embedded RDBMS to provide a fast, scaleable backend.
+**sqlite_**
+  This uses the SQLite_ embedded RDBMS to provide a fast, scaleable backend.
   There are no limitations, and it's much faster and more scaleable than the
   dbm backends.
-**metakit**
-  This backend is implemented over the metakit storage system, using Mk4Py as
+**metakit_**
+  This backend is implemented over the metakit_ storage system, using Mk4Py as
   the interface. It scales much better than the dbm backends.
 **gadfly**
   This is a proof-of-concept relational database backend, not really intended
@@ -194,6 +192,121 @@ to be available) and switch to one of the other backends at any time using the
 instructions in the `maintenance documentation`_.
 
 
+Configure a Web Interface
+-------------------------
+
+There are three web interfaces to choose from:
+
+1. `web server cgi-bin`_
+2. `stand-alone web server`_
+3. `Zope product - ZRoundup`_
+
+You may need to give the web server user permission to access the tracker home
+- see the `shared environment steps`_ for information.
+
+
+Web Server cgi-bin
+~~~~~~~~~~~~~~~~~~
+
+A benefit of using the cgi-bin approach is that it's the easiest way to
+restrict access to your tracker to only use HTTPS. Access will be slower
+than through the `stand-alone web server`_ though.
+
+Copy the ``cgi-bin/roundup.cgi`` file to your web server's ``cgi-bin``
+directory. You will need to configure it to tell it where your tracker home
+is. You can do this either:
+
+through an environment variable
+ set the variable TRACKER_HOMES to be a colon (":") separated list of
+ name=home pairs (if you're using apache, the SetEnv directive can do this)
+directly in the ``roundup.cgi`` file itself
+ add your instance to the TRACKER_HOMES variable as ``'name': 'home'``
+
+The "name" part of the configuration will appear in the URL and identifies the
+tracker (so you may have more than one tracker per cgi-bin script). Make sure
+there are no spaces or other illegal characters in it (to be safe, stick to
+letters and numbers). The "name" forms part of the URL that appears in the
+tracker config TRACKER_WEB variable, so make sure they match. The "home"
+part of the configuration is the tracker home directory.
+
+Stand-alone Web Server
+~~~~~~~~~~~~~~~~~~~~~~
+
+This approach will give you the fastest of the three web interfaces. You may
+investigate using ProxyPass or similar configuration in apache to have your
+tracker accessed through the same URL as other systems.
+
+The stand-alone web server is started with the command ``roundup-server``. It
+has several options - display them with ``roundup-server -h``.
+
+The tracker home configuration is similar to the cgi-bin - you may either edit
+the script to change the TRACKER_HOMES variable or you may supply the
+name=home values on the command-line after all the other options.
+
+To make the server run in the background, use the "-d" option, specifying the
+name of a file to write the server process id (pid) to.
+
+
+Zope Product - ZRoundup
+~~~~~~~~~~~~~~~~~~~~~~~
+
+ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
+your Products directory either in INSTANCE_HOME/Products or the Zope
+code tree lib/python/Products.
+
+When you next (re)start up Zope, you will be able to add a ZRoundup object
+that interfaces to your new tracker.
+
+
+Configure an Email Interface
+----------------------------
+
+If you don't want to use the email component of Roundup, then remove the
+"``nosyreator.py``" module from your tracker "``detectors``" directory.
+
+There are three supported ways to get emailed issues into the
+Roundup tracker.  You should pick ONE of the following, all
+of which will continue my example setup from above:
+
+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 <tracker_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 /opt/roundup/trackers/support
+ 
+To test the mail gateway on unix systems, try::
+
+    echo test |mail -s '[issue] test' support@YOUR_DOMAIN_HERE
+
+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 /opt/roundup/trackers/support 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``".
+
+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 /opt/roundup/trackers/support pop <pop_spec>
+    
+where pop_spec is "``username:password@server``" that specifies the roundup
+submission user's POP account name, password and server.
+
+
 Shared Environment Steps
 ------------------------
 
@@ -229,37 +342,12 @@ responsibility of running roundup. This user:
 4. optionally has no login password so that nobody but the "root" user
    may actually login and play with the roundup setup.
 
-Internet Setup
---------------
-
-1. There are two supported ways to get emailed issues into the
-   Roundup tracker.  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/trackers/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)::
+Maintenance
+===========
 
-       10 * * * * /opt/roundup/bin/roundup-mailgw
-                /opt/roundup/trackers/support /var/mail/support
-
-   If you don't want to use the email component of Roundup, then remove the
-   "``nosyreator.py``" module from your tracker "``detectors``" directory.
-
-2. Test the email gateway.  Under most flavors of UNIX, this
-   can be done by::
-
-     echo test | mail -s '[issue] test' support@YOUR_DOMAIN_HERE
-
-XXX mention HTTPS
-XXX mention Basic vs. cookie auth
+Read the separate `maintenance documentation`_ for information about how to
+perform common maintenance tasks with Roundup.
 
 
 Upgrading
@@ -270,22 +358,6 @@ upgrade existing tracker trackers for each version of Roundup that is
 released.
 
 
-ZRoundup
-========
-
-Install roundup as usual (see installation_).
-
-ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
-your Products directory either in an TRACKER_HOME/Products or the Zope
-code tree lib/python/Products.
-
-You will need to create the tracker using the roundup-admin tool (step 2 in
-installation_).
-
-When you next (re)start up Zope, you will be able to add a ZRoundup object
-that interfaces to your new tracker.
-
-
 Further Reading
 ===============
 
@@ -331,4 +403,6 @@ Next: `Getting Started`_
 .. _`customising roundup`: customizing.html
 .. _`upgrading document`: upgrading.html
 .. _`maintenance documentation`: maintenance.html
+.. _sqlite: http://www.hwaci.com/sw/sqlite/
+.. _metakit: http://www.equi4.com/metakit/
 

diff --git a/doc/user_guide.txt b/doc/user_guide.txt
index b195b54c76748889e2b4fc351b6411621d82c0ec..f6b64e9b4cdbf3b89877f7d0d065db86df444ee3 100644 (file)
--- a/doc/user_guide.txt
+++ b/doc/user_guide.txt
@@ -2,7 +2,7 @@
 User Guide
 ==========
 
-:Version: $Revision: 1.8 $
+:Version: $Revision: 1.9 $
 
 .. contents::
 
@@ -79,11 +79,16 @@ Note that the sidebar menu has changed slightly, so you can now get to your
 
 Note the new information on this page - the history.
 
+
+Display, edit or entry of an item
+---------------------------------
+
 Create a new issue with "create new" under the issue subheading. This will
 take you to:
 
 .. img: images/new_issue.png
 
+The `nosy list`_ is explained below.
 Enter some information and click "submit new entry" and you'll be rewarded
 with:
 
@@ -94,10 +99,11 @@ occurs) you'll get something like:
 
 .. img: images/new_issue_error.png
 
-Searching
----------
 
-TODO: some information about how searching works
+Searching Page
+--------------
+
+XXX: some information about how searching works
 
 
 Under the covers
@@ -123,11 +129,7 @@ propname   selects the values the item properties given by propname
 Access Controls
 ---------------
 
-
-Managing Issues
----------------
-
-TODO: some mention of how the various widgets work
+XXX
 
 
 E-Mail Gateway
@@ -258,7 +260,8 @@ the message may be added to the `nosy list`_ depending on:
 Nosy List
 ~~~~~~~~~
 
-The nosy list watches for additions to the "messages" property of items.
+Roundup watches for additions to the "messages" property of items.
+
 When a new message is added, it is sent 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