documentation cleanup from Luke Ross (patch [SF#1594860])

Author: Richard Jones

CHANGES.txt

@@ -1,14 +1,20 @@
 This file contains the changes to the Roundup system over time. The entries
 are given with the most recent entry first.
 
-2006-??-?? 1.3.1
+
+2006-??-?? 1.3.2
+Fixed:
+- documentation cleanup from Luke Ross (sf patch 1594860)
+
+
+2006-11-11 1.3.1
 Fixed:
 - setup.py had broken reference to roundup.cgi (sf bug 1593573)
 - full-text search wasn't coping with multiple multilinks to the same class
 - unicode / sqlite 3 problem (sf bug 1589292)
 
 
-2006-09-11 1.3.0
+2006-11-09 1.3.0
 Feature:
 - WSGI support via roundup.cgi.wsgi_handler
 

doc/FAQ.txt

@@ -2,7 +2,7 @@
 Roundup FAQ
 ===========
 
-:Version: $Revision: 1.22 $
+:Version: $Revision: 1.23 $
 
 .. contents::
 
@@ -13,7 +13,7 @@ Installation
 Living without a mailserver
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Remove the nosy reactor, means delete the tracker file
+Remove the nosy reactor - delete the tracker file
 ``detectors/nosyreactor.py`` from your tracker home.
 
 
@@ -23,10 +23,11 @@ The cgi-bin is very slow!
 Yep, it sure is. It has to start up Python and load all of the support
 libraries for *every* request.
 
-The solution is to use the built in server.
+The solution is to use the built in server (or possibly the mod_python
+or WSGI support).
 
 To make Roundup more seamless with your website, you may place the built
-in server behind apache and link it into your web tree
+in server behind apache and link it into your web tree (see below).
 
 
 How do I put Roundup behind Apache

doc/customizing.txt

@@ -2,7 +2,7 @@
 Customising Roundup
 ===================
 
-:Version: $Revision: 1.211 $
+:Version: $Revision: 1.212 $
 
 .. This document borrows from the ZopeBook section on ZPT. The original is at:
    http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
@@ -397,14 +397,15 @@ specifying (default) labelling and ordering of classes.)::
 
     user = Class(db, "user", username=String(), organisation=String(),
         password=String(), address=String(), realname=String(),
-        phone=String())
+        phone=String(), alternate_addresses=String(),
+        queries=Multilink('query'), roles=String(), timezone=String())
     user.setkey("username")
 
     msg = FileClass(db, "msg", author=Link("user"), summary=String(),
         date=Date(), recipients=Multilink("user"),
-        files=Multilink("file"))
+        files=Multilink("file"), messageid=String(), inreplyto=String())
 
-    file = FileClass(db, "file", name=String(), type=String())
+    file = FileClass(db, "file", name=String())
 
     issue = IssueClass(db, "issue", topic=Multilink("keyword"),
         status=Link("status"), assignedto=Link("user"),
@@ -535,7 +536,8 @@ 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
-tracker.
+tracker. FileClasses also have a "type" attribute to store the MIME
+type of the file.
 
 
 IssueClass
@@ -640,7 +642,8 @@ property, or sorting will result in random ordering.
 Examples of adding to your schema
 ---------------------------------
 
-TODO
+The Roundup wiki has examples of how schemas can be customised to add
+new functionality.
 
 
 Detectors - adding behaviour to your tracker
@@ -799,7 +802,7 @@ Database Content
 ================
 
 .. note::
-   if you modify the content of definitional classes, you'll most
+   If you modify the content of definitional classes, you'll most
    likely need to edit the tracker `detectors`_ to reflect your changes.
 
 Customisation of the special "definitional" classes (eg. status,

doc/features.txt

@@ -35,7 +35,7 @@ from Ka-Ping Yee in the Software Carpentry "Track" design competition.
    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,
-   or may veto the creation or modification of items int he database
+   or may veto the creation or modification of items in the database
  - samples are provided for all manner of configuration changes and
    customisations
 
@@ -62,7 +62,7 @@ from Ka-Ping Yee in the Software Carpentry "Track" design competition.
  - authentication of user registration and user-driven password resetting
    using email and one time keys
  - may be run using WSGI or through CGI as a normal cgi script, as a
-   stand-alone web server, or through Zope
+   stand-alone web server, under mod_python or through Zope
  - searching may be performed using many constraints, including a full-text
    search of messages attached to issues
  - file attachments (added through the web or email) are served up with the

doc/installation.txt

@@ -2,7 +2,7 @@
 Installing Roundup
 ==================
 
-:Version: 1.76
+:Version: $Revision: 1.120 $
 
 .. contents::
    :depth: 2
@@ -312,7 +312,7 @@ privileges to create databases.
 Configure a Web Interface
 -------------------------
 
-There are three web interfaces to choose from:
+There are five web interfaces to choose from:
 
 1. `web server cgi-bin`_
 2. `stand-alone web server`_
@@ -332,7 +332,7 @@ 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.
 
-If your Python isn't install as "python" then you'll need to edit
+If your Python isn't installed as "python" then you'll need to edit
 the ``roundup.cgi`` script to fix the first line.
 
 If you're using IIS on a Windows platform, you'll need to run this command
@@ -368,7 +368,7 @@ part of the configuration is the tracker home directory.
 
 If you're using Apache, you can use an additional trick to hide the
 ``.cgi`` extension of the cgi script. Place the ``roundup.cgi`` script
-wherever you want it to be, renamed it to just ``roundup``, and add a
+wherever you want it to be, rename it to just ``roundup``, and add a
 couple lines to your Apache configuration::
 
  <Location /path/to/roundup>
@@ -379,7 +379,7 @@ couple lines to your Apache configuration::
 Stand-alone Web Server
 ~~~~~~~~~~~~~~~~~~~~~~
 
-This approach will give you the fastest of the three web interfaces. You may
+This approach will give you faster response than cgi-bin. You may
 investigate using ProxyPass or similar configuration in apache to have your
 tracker accessed through the same URL as other systems.
 
@@ -409,7 +409,7 @@ Apache HTTP Server with mod_python
 
 `Mod_python`_ is an `Apache`_ module that embeds the Python interpreter
 within the server.  Running Roundup this way is much faster than all
-above options and, like `web server cgi-bin`_, allows to use HTTPS
+above options and, like `web server cgi-bin`_, allows you to use HTTPS
 protocol.  The drawback is that this setup is more complicated.
 
 The following instructions were tested on apache 2.0 with mod_python 3.1.
@@ -462,7 +462,7 @@ directives:
     timing display is disabled.
 
 In the following example we have two trackers set up in
-``/var/db/roundup/support`` and ``var/db/roundup/devel`` and accessed
+``/var/db/roundup/support`` and ``/var/db/roundup/devel`` and accessed
 as ``https://my.host/roundup/support/`` and ``https://my.host/roundup/devel/``
 respectively.  Having them share same parent directory allows us to
 reduce the number of configuration directives.  Support tracker has
@@ -536,7 +536,7 @@ If you don't want to use the email component of Roundup, then remove the
 
 See `platform-specific notes`_ for steps that may be needed on your system.
 
-There are three supported ways to get emailed issues into the
+There are five 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:
 
@@ -547,10 +547,10 @@ Set up a mail alias called "issue_tracker" as (include the quote marks):
 "``|/usr/bin/python /usr/bin/roundup-mailgw <tracker_home>``"
 (substitute ``/usr/bin`` for wherever roundup-mailgw is installed).
 
-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/bin/roundup-mailgw``" and change
-the command to::
+In some installations (e.g. RedHat Linux and Fedora Core) you'll need to
+set up smrsh so sendmail will accept the pipe command. In that case,
+symlink ``/etc/smrsh/roundup-mailgw`` to "``/usr/bin/roundup-mailgw``"
+and change the command to::
 
     |roundup-mailgw /opt/roundup/trackers/support
 
@@ -622,8 +622,8 @@ This config makes a few assumptions:
   user, in this case, 'roundup'.
 
 * That if the ``schema.py`` file exists, then the tracker is ready for
-  use. Another option is to use the ``config.ini`` file, but this recently
-  changed (in 0.8) from ``config.py``.
+  use. Another option is to use the ``config.ini`` file (this changed
+  in 0.8 from ``config.py``).
 
 Macros for Roundup router/transport. Should be placed in the macros
 section of the Exim4 config::
@@ -746,6 +746,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.
 
+If you're using a Linux system (e.g. Fedora Core) with SELinux enabled,
+you will need to ensure that the db directory has a context that
+permits the web server to modify and create files. If you're using the
+mysql or postgresql backend you may also need to update your policy to
+allow the web server to access the database socket.
+
 
 Additional Language Codecs
 --------------------------

doc/user_guide.txt

@@ -2,7 +2,7 @@
 User Guide
 ==========
 
-:Version: $Revision: 1.34 $
+:Version: $Revision: 1.35 $
 
 .. contents::
 
@@ -21,7 +21,7 @@ issue-ness or user-ness is called the item's *class*. So, for bug
 reports and features, the class is "issue", and for users the class is
 "user".
 
-Each item in the tracker has an id number that identifies it along with
+Each item in the tracker has an ID number that identifies it along with
 its item class. To identify a particular issue or user, we combine the
 class with the number to create a unique label, so that user 1 (who,
 incidentally, is *always* the "admin" user) is referred to as "user1".
@@ -731,8 +731,8 @@ the command-line.
 Using with the shell
 --------------------
 
-With version 0.6.0 or newer of roundup which supports: multiple
-designators to display and the -d, -S and -s flags.
+With version 0.6.0 or newer of roundup (which introduced support for
+multiple designators to display and the -d, -S and -s flags):
 
 To find all messages regarding chatting issues that contain the word
 "spam", for example, you could execute the following command from the