more doc updates, not so many TODOs any more

Author: Richard Jones

TODO.txt

@@ -2,10 +2,6 @@ This file contains items that need doing before the next release:
 
 Required:
 - implementing logging for roundup-server, including command-line switches
-- fix documentation referring to configuration (config.ini)
-- fix documentation referring to customisation using interfaces.py
-- fix admin_guide referring to structure of trackers
-- add config.ini section descriptions - DONE?
 - Security review:
   - write up security model used in classic tracker
   - ensure classic template actually implements the model detailed

doc/FAQ.txt

@@ -2,7 +2,7 @@
 Roundup FAQ
 ===========
 
-:Version: $Revision: 1.19 $
+:Version: $Revision: 1.20 $
 
 .. contents::
 
@@ -34,9 +34,11 @@ How do I put Roundup behind Apache
 
 We have a project (foo) running on ``tracker.example:8080``.
 We want ``http://tracker.example/issues`` to use the roundup server, so we 
-set that up on port 8080 on ``tracker.example`` with the ``config.py`` line::
+set that up on port 8080 on ``tracker.example`` with the ``config.ini`` line::
 
-  TRACKER_WEB = 'http://tracker.example/issues/'
+  [tracker]
+  ...
+  web = 'http://tracker.example/issues/'
 
 We have a "foo_issues" tracker and we run the server with::
 
@@ -172,8 +174,8 @@ If you're using IE then install Mozilla and try again ;^)
 I keep getting logged out
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Make sure that the TRACKER_WEB setting in your tracker's config.py is set
-to the URL of the tracker.
+Make sure that the ``tracker`` -> ``web`` setting in your tracker's
+config.ini is set to the URL of the tracker.
 
 
 How is sorting performed, and why does it seem to fail sometimes?

doc/admin_guide.txt

@@ -2,7 +2,7 @@
 Administration Guide
 ====================
 
-:Version: $Revision: 1.13 $
+:Version: $Revision: 1.14 $
 
 .. contents::
 
@@ -36,28 +36,28 @@ There's two "installations" that we talk about when using Roundup:
    "inst" (and "init") commands, you're creating a new Roundup tracker. This
    installs configuration files, HTML templates, detector code and a new
    database. You have complete control over where this stuff goes through
-   both choosing your "tracker home" and the DATABASE variable in
-   config.py.
+   both choosing your "tracker home" and the ``main`` -> ``database`` variable
+   in the tracker's config.ini. 
 
 
 Configuring Roundup's Logging of Messages For Sysadmins
 =======================================================
 
-You may configure where Roundup logs messages in your tracker's config.py
-file. Roundup will use the standard Python logging implementation when
-available. If not, then a very basic logging implementation will be used
+You may configure where Roundup logs messages in your tracker's config.ini
+file. Roundup will use the standard Python (2.3+) logging implementation
+when available. If not, then a very basic logging implementation will be used
 (see BasicLogging in the roundup.rlog module for details).
 
-Configuration for "logging" module:
+Configuration for standard "logging" module:
  - tracker configuration file specifies the location of a logging
-   configration file as ``LOGGING_CONFIG``
+   configration file as ``logging`` -> ``config``
  - ``roundup-server`` specifies the location of a logging configuration
    file on the command line
 Configuration for "BasicLogging" implementation:
  - tracker configuration file specifies the location of a log file
-   ``LOGGING_FILENAME``
+   ``logging`` -> ``filename``
  - tracker configuration file specifies the level to log to as
-   ``LOGGING_LEVEL``
+   ``logging`` -> ``level``
  - ``roundup-server`` specifies the location of a log file on the command
    line
  - ``roundup-server`` specifies the level to log to on the command line

doc/customizing.txt

@@ -2,7 +2,7 @@
 Customising Roundup
 ===================
 
-:Version: $Revision: 1.157 $
+:Version: $Revision: 1.158 $
 
 .. This document borrows from the ZopeBook section on ZPT. The original is at:
    http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
@@ -39,13 +39,15 @@ Trackers have the following structure:
 =================== ========================================================
 Tracker File        Description
 =================== ========================================================
-config.py           Holds the basic `tracker configuration`_                 
-dbinit.py           Holds the `tracker schema`_                              
-interfaces.py       Defines the Web and E-Mail interfaces for the tracker    
-select_db.py        Selects the database back-end for the tracker            
+config.ini          Holds the basic `tracker configuration`_                 
+schema.py           Holds the `tracker schema`_                              
+initial_data.py     Holds any data to be entered into the database when the
+                    tracker is initialised.
 db/                 Holds the tracker's database                             
 db/files/           Holds the tracker's upload files and messages            
+db/backend_name     Names the database back-end for the tracker            
 detectors/          Auditors and reactors for this tracker                   
+extensions/         Additional web actions and templating utilities.
 html/               Web interface templates, images and style sheets         
 =================== ======================================================== 
 
@@ -1222,8 +1224,8 @@ Default templates
 -----------------
 
 The default templates are html4 compliant. If you wish to change them to be
-xhtml compliant, you'll need to change the ``HTML_VERSION`` configuration
-variable in ``config.py`` to ``'xhtml'`` instead of ``'html4'``.
+xhtml compliant, you'll need to change the ``html_version`` configuration
+variable in ``config.ini`` to ``'xhtml'`` instead of ``'html4'``.
 
 Most customisation of the web view can be done by modifying the
 templates in the tracker ``'html'`` directory. There are several types
@@ -1534,7 +1536,7 @@ The following variables are available to templates.
      The current CGI form information as a mapping of form argument name
      to value
 **config**
-  This variable holds all the values defined in the tracker config.py
+  This variable holds all the values defined in the tracker config.ini
   file (eg. TRACKER_NAME, etc.)
 **db**
   The current database, used to access arbitrary database items.
@@ -3834,11 +3836,13 @@ First up, we create the new Role and Permission structure in
     db.security.addPermissionToRole('Provisional User', p)
 
 
-Then in the ``config.py`` we change the Role assigned to newly-registered
+Then in the ``config.ini`` we change the Role assigned to newly-registered
 users, replacing the existing ``'User'`` values::
 
-    NEW_WEB_USER_ROLES = 'Provisional User'
-    NEW_EMAIL_USER_ROLES = 'Provisional User'
+    [main]
+    ...
+    new_web_user_roles = 'Provisional User'
+    new_email_user_roles = 'Provisional User'
 
 Finally we add a new *auditor* to the ``detectors`` directory called
 ``provisional_user_auditor.py``::

doc/developers.txt

@@ -2,7 +2,7 @@
 Developing Roundup
 ==================
 
-:Version: $Revision: 1.13 $
+:Version: $Revision: 1.14 $
 
 .. note::
    The intended audience of this document is the developers of the core
@@ -122,7 +122,7 @@ of ways, depending on what it is you're testing:
    This variable replaces the older HYPERDBDEBUG environment var.
 
 2. If you're testing a particular tracker, then set the logging level in
-   your tracker's ``config.py``.
+   your tracker's ``config.ini``.
 
 
 Internationalization Notes

doc/installation.txt

@@ -298,10 +298,12 @@ mysql      Fast        Many  Needs install/admin (MySQLdb_)
   If you are choosing from these two, please select sqlite.
 **postgresql**
   Backend for popular RDBMS PostgreSQL. You must read doc/postgresql.txt for
-  additional installation steps and requirements.
+  additional installation steps and requirements. You must also configure
+  the ``rdbms`` section of your tracker's ``config.ini``
 **mysql**
   Backend for popular RDBMS MySQL. You must read doc/mysql.txt for additional
-  installation steps and requirements.
+  installation steps and requirements. You must also configure the ``rdbms``
+  section of your tracker's ``config.ini``
 
 You may defer your decision by setting your tracker up with the anydbm
 backend (which is guaranteed to be available) and switching to one of the
@@ -595,7 +597,7 @@ If you're using the mysql or postgresql backend then you'll need to ensure
 that the tracker user has appropriate permissions to create/modify the
 database. If you're using roundup.cgi, the apache user needs permissions
 to modify the database.  Alternatively, explicitly specify a database login
-in ``POSTRGRESQL_DATABASE`` or ``MYSQL_DATABASE`` in ``config.py``.
+in ``rdbms`` -> ``user`` and ``password`` in ``config.ini``.
 
 An alternative to the above is to create a new user who has the sole
 responsibility of running roundup. This user:

doc/mysql.txt

@@ -2,7 +2,7 @@
 MySQL Backend
 =============
 
-:version: $Revision: 1.11 $
+:version: $Revision: 1.12 $
 
 This notes detail the MySQL backend for the Roundup issue tracker.
 
@@ -25,6 +25,7 @@ to install:
 
 __ http://bugs.mysql.com/bug.php?id=1810
 
+
 Running the MySQL tests
 =======================
 
@@ -62,3 +63,4 @@ just::
 
 and all will be better (note that on some systems, ``mysql`` is spelt
 ``mysqld``).
+