clarifications

Author: Richard Jones

doc/customizing.txt

@@ -2,7 +2,7 @@
 Customising Roundup
 ===================
 
-:Version: $Revision: 1.62 $
+:Version: $Revision: 1.63 $
 
 .. This document borrows from the ZopeBook section on ZPT. The original is at:
    http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
@@ -437,9 +437,12 @@ case though, so be careful to use the right one.
     the create() methods.
 
 **Changing content after tracker initialisation**
-    Use the roundup-admin interface's create, set and retire methods to add,
-    alter or remove items from the classes in question.
+    As the "admin" user, click on the "class list" link in the web interface
+    to bring up a list of all database classes. Click on the name of the class
+    you wish to change the content of.
 
+    You may also use the roundup-admin interface's create, set and retire
+    methods to add, alter or remove items from the classes in question.
 
 See "`adding a new field to the classic schema`_" for an example that requires
 database content changes.
@@ -585,6 +588,16 @@ Example Scenarios
  normal "User" Role minus the "Web Access" Permission. This will allow users
  to send in emails to the tracker, but not access the web interface.
 
+**let some users edit the details of all users**
+ Create a new Role called "User Admin" which has the Permission for editing
+ users::
+
+    db.security.addRole(name='User Admin', description='Managing users')
+    p = db.security.getPermission('Edit', 'user')
+    db.security.addPermissionToRole('User Admin', p)
+
+ and assign the Role to the users who need the permission.
+
 
 Web Interface
 =============
@@ -1030,7 +1043,6 @@ The following variables are available to templates.
   `hyperdb class wrapper`_ or a `hyperdb item wrapper`_
 **request**
   Includes information about the current request, including:
-   - the url
    - the current index information (``filterspec``, ``filter`` args,
      ``properties``, etc) parsed out of the form. 
    - methods for easy filterspec link generation
@@ -1193,7 +1205,8 @@ The property wrapper has some useful attributes:
 Attribute       Description
 =============== =============================================================
 _name           the name of the property
-_value          the value of the property if any
+_value          the value of the property if any - this is the actual value
+                retrieved from the hyperdb for this property
 =============== =============================================================
 
 There are several methods available on these wrapper objects:
@@ -1237,7 +1250,6 @@ Variable    Holds
 =========== =================================================================
 form        the CGI form as a cgi.FieldStorage
 env         the CGI environment variables
-url         the current URL path for this request
 base        the base URL for this tracker
 user        a HTMLUser instance for this user
 classname   the current classname (possibly None)

doc/installation.txt

@@ -2,7 +2,7 @@
 Installing Roundup
 ==================
 
-:Version: $Revision: 1.36 $
+:Version: $Revision: 1.37 $
 
 .. contents::
 
@@ -84,7 +84,8 @@ Basic Installation Steps
 ------------------------
 
 1. To install the Roundup support code into your Python tree and
-   Roundup scripts into /usr/local/bin. You need to have write permissions
+   Roundup scripts into /usr/local/bin (substitute that path for whatever is
+   appropriate on your system). You need to have write permissions
    for these locations, eg. being root on unix::
 
        python setup.py install
@@ -319,8 +320,8 @@ 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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+As a regular job using a mailbox source
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Set ``roundup-mailgw`` up to run every 10 minutes or so. For example::
 
@@ -330,16 +331,18 @@ 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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+As a regular job using a POP source
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To retrieve from a POP mailbox, use a similar cron entry to the mailbox one::
+To retrieve from a POP mailbox, use a *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.
 
+On windows, you would set up the command using the windows scheduler.
+
 
 Shared Environment Steps
 ------------------------

doc/user_guide.txt

@@ -2,7 +2,7 @@
 User Guide
 ==========
 
-:Version: $Revision: 1.11 $
+:Version: $Revision: 1.12 $
 
 .. contents::
 
@@ -129,7 +129,21 @@ propname   selects the values the item properties given by propname
 Access Controls
 ---------------
 
-XXX
+User access is controlled through Permissions. These are are grouped into
+Roles, and users have a comma-separated list of Roles assigned to them.
+
+Permissions divide access controls up into answering questions like:
+
+- may the user edit issues ("Edit", "issue")
+- is the user allowed to use the web interface ("Web Access")
+- may the user edit other user's Roles through the web ("Web Roles")
+
+Any number of new Permissions and Roles may be created as described in the
+customisation documentation. Examples of new access controls are:
+
+- only managers may sign off issues as complete
+- don't give users who register through email web access
+- let some users edit the details of all users
 
 
 E-Mail Gateway
@@ -385,4 +399,4 @@ command-line.
 Back to `Table of Contents`_
 
 .. _`Table of Contents`: index.html
-
+.. _`customisation documentation`: customizing.html