Index: openacs-4/packages/acs-core-docs/www/acs-admin.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/acs-admin.adp,v diff -u -N -r1.1.2.4 -r1.1.2.5 --- openacs-4/packages/acs-core-docs/www/acs-admin.adp 9 Jun 2016 13:03:11 -0000 1.1.2.4 +++ openacs-4/packages/acs-core-docs/www/acs-admin.adp 23 Jun 2016 08:32:44 -0000 1.1.2.5 @@ -1,7 +1,7 @@ -{/doc/acs-core-docs {Documentation}} {Part II. Administrator's +{/doc/acs-core-docs {Documentation}} {Part II. Administrator's Guide} -Part II. Administrator's +Part II. Administrator's Guide

-Part II. Administrator's +Part II. Administrator's Guide

Table of Contents

2. Index: openacs-4/packages/acs-core-docs/www/acs-admin.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/acs-admin.html,v diff -u -N -r1.45.2.2 -r1.45.2.3 --- openacs-4/packages/acs-core-docs/www/acs-admin.html 9 Jun 2016 13:03:11 -0000 1.45.2.2 +++ openacs-4/packages/acs-core-docs/www/acs-admin.html 23 Jun 2016 08:32:44 -0000 1.45.2.3 @@ -1,2 +1,2 @@ -Part II. Administrator's Guide
Alex logo
Prev Next

Part II. Administrator's Guide

Table of Contents

2. Installation Overview
Basic Steps
Prerequisite Software
3. Complete Installation
Install a Unix-like system and supporting software
Install Oracle 8.1.7
Install PostgreSQL
Install AOLserver 4
Install OpenACS 5.9.0
OpenACS Installation Guide for Windows
OpenACS Installation Guide for Mac OS X
4. Configuring a new OpenACS Site
Installing OpenACS packages
Mounting OpenACS packages
Configuring an OpenACS package
Setting Permissions on an OpenACS package
How Do I?
5. Upgrading
Overview
Upgrading 4.5 or higher to 4.6.3
Upgrading OpenACS 4.6.3 to 5.0
Upgrading an OpenACS 5.0.0 or greater installation
Upgrading the OpenACS files
Upgrading Platform components
6. Production Environments
Starting and Stopping an OpenACS instance.
AOLserver keepalive with inittab
Running multiple services on one machine
High Availability/High Performance Configurations
Staged Deployment for Production Networks
Installing SSL Support for an OpenACS service
Set up Log Analysis Reports
External uptime validation
Diagnosing Performance Problems
7. Database Management
Running a PostgreSQL database on another server
Deleting a tablespace
Vacuum Postgres nightly
8. Backup and Recovery
Backup Strategy
Manual backup and recovery
Automated Backup
Using CVS for backup-recovery
A. Install Red Hat 8/9
B. Install additional supporting software
Unpack the OpenACS tarball
Initialize CVS (OPTIONAL)
Add PSGML commands to emacs init file (OPTIONAL)
Install Daemontools (OPTIONAL)
Install qmail (OPTIONAL)
Install Analog web file analyzer
Install nspam
Install Full Text Search using Tsearch2
Install Full Text Search using OpenFTS (deprecated see tsearch2)
Install nsopenssl
Install tclwebtest.
Install PHP for use in AOLserver
Install Squirrelmail for use as a webmail system for OpenACS
Install PAM Radius for use as external authentication
Install LDAP for use as external authentication
Install AOLserver 3.3oacs1
C. Credits
Where did this document come from?
Linux Install Guides
Security Information
Resources
Prev Home Next
OpenACS Release Notes Up Chapter 2. Installation Overview
docs@openacs.org
View comments on this page at openacs.org
+Part II. Administrator's Guide
Alex logo
Prev Next

Part II. Administrator's Guide

Table of Contents

2. Installation Overview
Basic Steps
Prerequisite Software
3. Complete Installation
Install a Unix-like system and supporting software
Install Oracle 8.1.7
Install PostgreSQL
Install AOLserver 4
Install OpenACS 5.9.0
OpenACS Installation Guide for Windows
OpenACS Installation Guide for Mac OS X
4. Configuring a new OpenACS Site
Installing OpenACS packages
Mounting OpenACS packages
Configuring an OpenACS package
Setting Permissions on an OpenACS package
How Do I?
5. Upgrading
Overview
Upgrading 4.5 or higher to 4.6.3
Upgrading OpenACS 4.6.3 to 5.0
Upgrading an OpenACS 5.0.0 or greater installation
Upgrading the OpenACS files
Upgrading Platform components
6. Production Environments
Starting and Stopping an OpenACS instance.
AOLserver keepalive with inittab
Running multiple services on one machine
High Availability/High Performance Configurations
Staged Deployment for Production Networks
Installing SSL Support for an OpenACS service
Set up Log Analysis Reports
External uptime validation
Diagnosing Performance Problems
7. Database Management
Running a PostgreSQL database on another server
Deleting a tablespace
Vacuum Postgres nightly
8. Backup and Recovery
Backup Strategy
Manual backup and recovery
Automated Backup
Using CVS for backup-recovery
A. Install Red Hat 8/9
B. Install additional supporting software
Unpack the OpenACS tarball
Initialize CVS (OPTIONAL)
Add PSGML commands to emacs init file (OPTIONAL)
Install Daemontools (OPTIONAL)
Install qmail (OPTIONAL)
Install Analog web file analyzer
Install nspam
Install Full Text Search using Tsearch2
Install Full Text Search using OpenFTS (deprecated see tsearch2)
Install nsopenssl
Install tclwebtest.
Install PHP for use in AOLserver
Install Squirrelmail for use as a webmail system for OpenACS
Install PAM Radius for use as external authentication
Install LDAP for use as external authentication
Install AOLserver 3.3oacs1
C. Credits
Where did this document come from?
Linux Install Guides
Security Information
Resources
Prev Home Next
OpenACS Release Notes Up Chapter 2. Installation Overview
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/acs-package-dev.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/acs-package-dev.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-core-docs/www/acs-package-dev.adp 9 Jun 2016 13:03:11 -0000 1.1.2.2 +++ openacs-4/packages/acs-core-docs/www/acs-package-dev.adp 23 Jun 2016 08:32:44 -0000 1.1.2.3 @@ -79,7 +79,7 @@ Overview
How Internationalization/Localization works in OpenACS
How to Internationalize a Package
Design -Notes
Translator's Guide
+Notes
Translator's Guide
D. Using CVS with an OpenACS Site
Index: openacs-4/packages/acs-core-docs/www/acs-package-dev.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/acs-package-dev.html,v diff -u -N -r1.33.2.2 -r1.33.2.3 --- openacs-4/packages/acs-core-docs/www/acs-package-dev.html 9 Jun 2016 08:44:49 -0000 1.33.2.2 +++ openacs-4/packages/acs-core-docs/www/acs-package-dev.html 23 Jun 2016 08:32:44 -0000 1.33.2.3 @@ -2,4 +2,4 @@ Part III. For OpenACS Package Developers
Alex logo
Prev Next

Part III. For OpenACS Package Developers

Tutorials and reference material for creating new OpenACS packages.

Table of Contents

9. Development Tutorial
Creating an Application Package
Setting Up Database Objects
Creating Web Pages
Debugging and Automated Testing
10. Advanced Topics
Write the Requirements and Design Specs
Add the new package to CVS
OpenACS Edit This Page Templates
Adding Comments
Admin Pages
Categories
Profile your code
Prepare the package for distribution.
Distributing upgrades of your package
Notifications
Hierarchical data
Using .vuh files for pretty urls
Laying out a page with CSS instead of tables
Sending HTML email from your application
Basic Caching
Scheduled Procedures
Enabling WYSIWYG
Adding in parameters for your package
Writing upgrade scripts
Connect to a second database
Future Topics
11. Development Reference
OpenACS Packages
OpenACS Data Models and the Object System
The Request Processor
The OpenACS Database Access API
Using Templates in OpenACS
Groups, Context, Permissions
Writing OpenACS Application Pages
Parties in OpenACS
OpenACS Permissions Tediously Explained
Object Identity
Programming with AOLserver
Using Form Builder: building html forms dynamically
12. Engineering Standards
OpenACS Style Guide
CVS Guidelines -
Release Version Numbering
Constraint naming standard
ACS File Naming and Formatting Standards
PL/SQL Standards
Variables
Automated Testing
13. Documentation Standards
OpenACS Documentation Guide
Using PSGML mode in Emacs
Using nXML mode in Emacs
Detailed Design Documentation Template
System/Application Requirements Template
14. Internationalization
Internationalization and Localization Overview
How Internationalization/Localization works in OpenACS
How to Internationalize a Package
Design Notes
Translator's Guide
D. Using CVS with an OpenACS Site
Prev Home Next
Resources Up Chapter 9. Development Tutorial
docs@openacs.org
View comments on this page at openacs.org
+
Release Version Numbering
Constraint naming standard
ACS File Naming and Formatting Standards
PL/SQL Standards
Variables
Automated Testing
13. Documentation Standards
OpenACS Documentation Guide
Using PSGML mode in Emacs
Using nXML mode in Emacs
Detailed Design Documentation Template
System/Application Requirements Template
14. Internationalization
Internationalization and Localization Overview
How Internationalization/Localization works in OpenACS
How to Internationalize a Package
Design Notes
Translator's Guide
D. Using CVS with an OpenACS Site
Prev Home Next
Resources Up Chapter 9. Development Tutorial
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/analog-setup.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/analog-setup.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/analog-setup.adp 23 Sep 2015 11:54:19 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/analog-setup.adp 23 Jun 2016 08:32:44 -0000 1.1.2.2 @@ -27,12 +27,12 @@ cp -r /usr/share/analog-5.32/images www/log/

Edit /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/analog.cfg and change the variable in HOSTNAME -"[my organisation]" to reflect your website title. If you -don't want the traffic log to be publicly visible, change -OUTFILE +"[my organisation]" to reflect your website title. +If you don't want the traffic log to be publicly visible, +change OUTFILE /var/lib/aolserver/$OPENACS_SERVICE_NAME/www/log/traffic.html -to use a private directory. You'll also need to edit all instances -of service0 to your $OPENACS_SERVICE_NAME.

+to use a private directory. You'll also need to edit all +instances of service0 to your $OPENACS_SERVICE_NAME.

  • Run it.

     [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/share/analog-5.32/analog -G -g/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/analog.cfg
Index: openacs-4/packages/acs-core-docs/www/analog-setup.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/analog-setup.html,v
diff -u -N -r1.15.2.1 -r1.15.2.2
--- openacs-4/packages/acs-core-docs/www/analog-setup.html	9 Jun 2016 08:44:49 -0000	1.15.2.1
+++ openacs-4/packages/acs-core-docs/www/analog-setup.html	23 Jun 2016 08:32:45 -0000	1.15.2.2
@@ -15,9 +15,9 @@
 cp -r /usr/share/analog-5.32/images www/log/

    Edit /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/analog.cfg and change the variable in HOSTNAME "[my organisation]" to reflect your website title. If you -don't want the traffic log to be publicly visible, change +don't want the traffic log to be publicly visible, change OUTFILE /var/lib/aolserver/$OPENACS_SERVICE_NAME/www/log/traffic.html to use a private -directory. You'll also need to edit all instances of service0 to your $OPENACS_SERVICE_NAME.

  • Run it.

    [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/share/analog-5.32/analog -G -g/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/analog.cfg
+directory. You'll also need to edit all instances of service0 to your $OPENACS_SERVICE_NAME.

  • Run it.

    [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/share/analog-5.32/analog -G -g/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/analog.cfg
 /usr/share/analog-5.32/analog: analog version 5.32/Unix
 /usr/share/analog-5.32/analog: Warning F: Failed to open DNS input file
   /home/$OPENACS_SERVICE_NAME/dnscache: ignoring it
Index: openacs-4/packages/acs-core-docs/www/aolserver.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/aolserver.adp,v
diff -u -N -r1.1.2.5 -r1.1.2.6
--- openacs-4/packages/acs-core-docs/www/aolserver.adp	9 Jun 2016 13:03:11 -0000	1.1.2.5
+++ openacs-4/packages/acs-core-docs/www/aolserver.adp	23 Jun 2016 08:32:45 -0000	1.1.2.6
@@ -18,12 +18,12 @@
 instructions are retained as a resource.
    Debian users: we do not recommend installing Debian packages for
 Aolserver or Postgres. Several people have reported problems while
 trying to install using apt-get instead of from source. If you have
-the time to debug these and submit what you did, that's great, but
-if not, you should stick to installing from source.
      
+the time to debug these and submit what you did, that's great,
+but if not, you should stick to installing from source.
        
 
      1. 
 
        
-Unpack the Aolserver tarball. Download the
-aolserver tarball
+Unpack the Aolserver
+tarball. Download the aolserver tarball
 and unpack it.
         [root root]# cd /usr/local/src
 [root src]# wget --passive http://uptime.openacs.org/aolserver-openacs/aolserver3.3oacs1.tar.gz
@@ -48,9 +48,10 @@
 tarball”.
        
 
      2. 
 
        
-Compile AOLserver. Compile and install
-AOLserver. First, prepare the installation directory and the source
-code. The message about BUILD-MODULES can be ignored.
        +Compile AOLserver. Compile and
+install AOLserver. First, prepare the installation directory and
+the source code. The message about BUILD-MODULES can be
+ignored.
         root\@yourserver root]# mkdir -p /usr/local/aolserver
 [root root]# cd /usr/local/src/aolserver
 [root aolserver]# ./conf-clean
@@ -65,7 +66,7 @@
 properly.
        
 conf-inst should contain the
 location where AOLserver is to be installed. Overwrite the
-tarball's default value with our default value, /usr/local/aolserver:
        +tarball's default value with our default value, /usr/local/aolserver:
         [root aolserver]# echo "/usr/local/aolserver" > conf-inst
 [root aolserver]#
 
        
@@ -111,12 +112,12 @@
 build errors.
        
 
      3. 
 
        
-Add a database-specific wrapper script. This
-script sets database environment variables before starting
-AOLserver; this allows the AOLserver instance can communicate with
-the database. There is one script each for Oracle and PostgreSQL.
-They don't conflict, so if you plan to use both databases, install
-both.
          
+Add a database-specific wrapper
+script. This script sets database environment
+variables before starting AOLserver; this allows the AOLserver
+instance can communicate with the database. There is one script
+each for Oracle and PostgreSQL. They don't conflict, so if you
+plan to use both databases, install both.
            
 
          • 
 
            Oracle
             [root aolserver]# cd /usr/local/aolserver/bin
@@ -141,9 +142,10 @@
 
          
 
        • 
 
          
-Install tDOM. Download the tDOM tarball,
-unpack it, adjust the configuration file to match our patched
-distribution of aolserver, and compile it.
          +Install tDOM. Download the
+tDOM
+tarball, unpack it, adjust the configuration file to match our
+patched distribution of aolserver, and compile it.
           [root root]# cd /usr/local/src
 [root src]# wget --passive http://www.tdom.org/tDOM-0.7.8.tar.gz
 --16:40:58--  http://www.tdom.org/tDOM-0.7.8.tar.gz
@@ -206,13 +208,14 @@
 (OPTIONAL)
        • 
 Install nspam (OPTIONAL)
        • 
 
          
-Test AOLserver. In order to test AOLserver,
-we'll run it using the sample-config.tcl file provided in the
-AOLserver distribution, under the nobody user and web group. The sample-config.tcl
-configuration writes to the default log locations, so we need to
-give it permission to do so or it will fail. Grant the web group permission to write to
-/usr/local/aolserver/log and
-/usr/local/aolserver/servers.
          +Test AOLserver. In order to test
+AOLserver, we'll run it using the sample-config.tcl file
+provided in the AOLserver distribution, under the nobody user and
+web group. The
+sample-config.tcl configuration writes to the default log
+locations, so we need to give it permission to do so or it will
+fail. Grant the web group
+permission to write to /usr/local/aolserver/log and /usr/local/aolserver/servers.
           [root root]# cd /usr/local/aolserver
 [root aolserver]# chown -R root.web log servers
 [root aolserver]# chmod -R g+w log servers
@@ -235,8 +238,8 @@
 create one for this test. Type echo
 "Welcome to AOLserver" >
 /usr/local/aolserver40r8/servers/server1/pages/index.html
-
          Now, we'll run a quick test to ensure AOLserver is running
-correctly. We'll use the sample config file provided with
+
          Now, we'll run a quick test to ensure AOLserver is running
+correctly. We'll use the sample config file provided with
 AOLserver. This file will attempt to guess your IP address and
 hostname. It will then start up the server at port 8000 of that IP
 address.
          @@ -247,21 +250,21 @@
 -- user/password is not set.
 [08/Mar/2003:15:07:18][31175.8192][-main-] Notice: config.tcl: finished reading
 config file.
-
          The first warning, about nsssl, can be ignored. We won't be
-using nsssl; we'll be using nsopenssl instead, and we haven't fully
-configured it yet. The nscp warning refers to the fact that,
-without a user and password in the config file, the administrative
-panel of AOLserver won't load. We don't plan to use it and can
-ignore that error as well. Any other warning or error is unexpected
-and probably a problem.
          Test to see if AOLserver is working by starting Mozilla or Lynxon the same
+
          The first warning, about nsssl, can be ignored. We won't be
+using nsssl; we'll be using nsopenssl instead, and we
+haven't fully configured it yet. The nscp warning refers to the
+fact that, without a user and password in the config file, the
+administrative panel of AOLserver won't load. We don't plan
+to use it and can ignore that error as well. Any other warning or
+error is unexpected and probably a problem.
          Test to see if AOLserver is working by starting Mozilla or Lynxon the same
 computer and surfing over to your web page. If you
-browse from another computer and the sample config file didn't
-guess your hostname or ip correctly, you'll get a false negative
-test.
          +browse from another computer and the sample config file didn't
+guess your hostname or ip correctly, you'll get a false
+negative test.
           [root aolserver]# lynx localhost:8000
-
          You should see a "Welcome to AOLserver" page. If this doesn't
-work, try going to http://127.0.0.1:8000/. If this still
-doesn't work, check out the Troubleshooting
+
          You should see a "Welcome to AOLserver" page. If this
+doesn't work, try going to http://127.0.0.1:8000/. If this still
+doesn't work, check out the Troubleshooting
 AOLserver section below. Note that you will not be able to
 browse to the web page from another machine, because AOLserver is
 only listening to the local address.
          Shutdown the test server:
          @@ -274,10 +277,10 @@
 alive section.
          
 
        • 
 
          
-Troubleshooting. If you can't view the
-welcome page, it's likely there's a problem with your server
-configuration. Start by viewing your AOLserver log, which is in
-/usr/local/aolserver/log/server.log. You
+Troubleshooting. If you can't
+view the welcome page, it's likely there's a problem with
+your server configuration. Start by viewing your AOLserver log,
+which is in /usr/local/aolserver/log/server.log. You
 should also try to find lines of the form:
           [01/Jun/2000:12:11:20][5914.4051][-nssock-] Notice: nssock: listening on http://localhost.localdomain:8000 (127.0.0.1:8000)
 [01/Jun/2000:12:11:20][5914.4051][-nssock-] Notice: accepting connections
@@ -289,9 +292,9 @@
 grabs your address and hostname from your OS settings.
           set hostname        [ns_info hostname]
 set address         [ns_info address]
-
          If you get an error that nssock can't get the requested address,
-you can set these manually. If you type 0.0.0.0, AOLserver will try
-to listen on all available addresses. Note: ns_info address doesn't appear to be
+
          If you get an error that nssock can't get the requested
+address, you can set these manually. If you type 0.0.0.0, AOLserver
+will try to listen on all available addresses. Note: ns_info address doesn't appear to be
 supported in current versions of AOLserver.
           set hostname        [ns_info hostname]
 #set address         [ns_info address]
@@ -300,8 +303,8 @@
 
        • 
 Install Analog web file
 analyzer. (OPTIONAL)
          • 
-
      ($‌Id: aolserver.xml,v 1.22 2006/07/17 05:38:37
-torbenb Exp $)
      
+
    ($‌Id: aolserver.html,v 1.52.2.10 2016/06/21
+07:44:35 gustafn Exp $)
    
 
 
    1. Unpack the Aolserver tarball. Download the aolserver tarball and unpack it.
      [root root]# cd /usr/local/src
 [root src]# wget --passive http://uptime.openacs.org/aolserver-openacs/aolserver3.3oacs1.tar.gz
@@ -43,7 +43,7 @@
           the environment variables properly.
         
      conf-inst should contain the
           location where AOLserver is to be installed.  Overwrite the
-          tarball's default value with our default value, /usr/local/aolserver:
      [root aolserver]# echo "/usr/local/aolserver" > conf-inst
+          tarball's default value with our default value, /usr/local/aolserver:
      [root aolserver]# echo "/usr/local/aolserver" > conf-inst
 [root aolserver]#
      conf-make should contain the
           name of the GNU Make command on your system. It defaults to
           gmake.  Debian users: ln -s /usr/bin/make /usr/bin/gmake.
      Set an environment variable that the nspostgres driver
@@ -81,7 +81,7 @@
 	  sets database environment variables before starting
 	  AOLserver; this allows the AOLserver instance can
 	  communicate with the database.  There is one script each for
-	  Oracle and PostgreSQL.  They don't conflict, so if you plan
+	  Oracle and PostgreSQL.  They don't conflict, so if you plan
 	  to use both databases, install both.
      • Oracle
        [root aolserver]# cd /usr/local/aolserver/bin
 [root bin]# cp /var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle
 [root bin]# chmod 750 nsd-oracle
@@ -145,7 +145,7 @@
 cp libtdom0.7.8.so /usr/local/aolserver/bin/
 cd /usr/local/aolserver/bin
 ln -s libtdom0.7.8.so libtdom.so
      • Install nsopenssl
-      (OPTIONAL)
      • Install Full Text Search with OpenFTS (OPTIONAL)
      • Install nspam (OPTIONAL)
      • Test AOLserver. In order to test AOLserver, we'll run it using the
+      (OPTIONAL)
      • Install Full Text Search with OpenFTS (OPTIONAL)
      • Install nspam (OPTIONAL)
      • Test AOLserver. In order to test AOLserver, we'll run it using the
       sample-config.tcl file provided in the AOLserver distribution,
       under the nobody user and web
       group.  The sample-config.tcl configuration writes to the
@@ -172,8 +172,8 @@
 chmod -R g+w log servers
 ls -l
      Note: AOLserver4.x does not include a default start page, so we create one for this test. Type 
         echo "Welcome to AOLserver" > /usr/local/aolserver40r8/servers/server1/pages/index.html
-      
      Now, we'll run a quick test to ensure AOLserver is running
-          correctly. We'll use the sample config file provided with
+      
      Now, we'll run a quick test to ensure AOLserver is running
+          correctly. We'll use the sample config file provided with
           AOLserver. This file will attempt to guess your IP address and
           hostname. It will then start up the server at port 8000 of that
           IP address.
      [root aolserver]# ./bin/nsd -t sample-config.tcl -u nobody -g web
@@ -182,22 +182,22 @@
 [08/Mar/2003:15:07:18][31175.8192][-main-] Warning: config.tcl: nscp not loaded
 -- user/password is not set.
 [08/Mar/2003:15:07:18][31175.8192][-main-] Notice: config.tcl: finished reading
-config file.
      The first warning, about nsssl, can be ignored.  We won't be using nsssl; we'll be using nsopenssl instead, and we haven't fully configured it yet.  The nscp warning refers to the fact that, without a user and password in the config file, the administrative panel of AOLserver won't load.  We don't plan to use it and can ignore that error as well.  Any other warning or error is unexpected and probably a problem.
      
+config file.
      The first warning, about nsssl, can be ignored.  We won't be using nsssl; we'll be using nsopenssl instead, and we haven't fully configured it yet.  The nscp warning refers to the fact that, without a user and password in the config file, the administrative panel of AOLserver won't load.  We don't plan to use it and can ignore that error as well.  Any other warning or error is unexpected and probably a problem.
      
 
           Test to see if AOLserver is working by starting
           Mozilla or
           Lynx on the same
           computer and surfing over to your web page.  If
           you browse from another computer and the sample config file
-          didn't guess your hostname or ip correctly, you'll get a
+          didn't guess your hostname or ip correctly, you'll get a
           false negative test.
 
         
      [root aolserver]# lynx localhost:8000
      
 
           You should see a "Welcome to AOLserver" page. If this
-          doesn't work, try going to
+          doesn't work, try going to
           http://127.0.0.1:8000/. If this
-          still doesn't work, check out the Troubleshooting AOLserver section below.  Note that you will not be able to browse to the web page from another machine, because AOLserver is only listening to the local address.
+          still doesn't work, check out the Troubleshooting AOLserver section below.  Note that you will not be able to browse to the web page from another machine, because AOLserver is only listening to the local address.
 
         
      Shutdown the test server:
      [root aolserver]# killall nsd
 [root aolserver]#
      
@@ -207,7 +207,7 @@
           but clearly this is not a good tool to use for managing your
           services in general. We cover this topic in the Keep AOLserver alive section.
 
-        
    2. Troubleshooting. If you can't view the welcome page, it's likely there's a
+        
    3. Troubleshooting. If you can't view the welcome page, it's likely there's a
       problem with your server configuration. Start by viewing your
       AOLserver log, which is in
       /usr/local/aolserver/log/server.log.
@@ -231,10 +231,10 @@
 set hostname        [ns_info hostname]
 set address         [ns_info address]

    - If you get an error that nssock can't get the requested address, you + If you get an error that nssock can't get the requested address, you can set these manually. If you type 0.0.0.0, AOLserver will try to listen on all available addresses. Note: - ns_info address doesn't appear + ns_info address doesn't appear to be supported in current versions of AOLserver. 

    Index: openacs-4/packages/acs-core-docs/www/aolserver4.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/aolserver4.adp,v
diff -u -N -r1.1.2.4 -r1.1.2.5
--- openacs-4/packages/acs-core-docs/www/aolserver4.adp	9 Jun 2016 13:03:11 -0000	1.1.2.4
+++ openacs-4/packages/acs-core-docs/www/aolserver4.adp	23 Jun 2016 08:32:45 -0000	1.1.2.5
@@ -31,12 +31,12 @@

    If the first command returns anything other than 1, then tcl is not threaded. If tcl is threaded and the version is 8.4 or higher, then installing tcl from source is optional.

    -Retrieve Tcl 8.4 -(or higher). Download and install Tcl 8.4 from -source

    Note for Debian users: you can apt-get install tcl8.4-dev if you +Retrieve +Tcl 8.4 (or higher). Download and install Tcl +8.4 from source

    Note for Debian users: you can apt-get install tcl8.4-dev if you have the right version (stable users will need to add tcl8.4 to their sources.list file as described on the Install Postgres -page). You'll have to use /usr/lib/tcl8.4/ instead of +page). You'll have to use /usr/lib/tcl8.4/ instead of /usr/local/lib when you try to find the tcl libraries, however.

    If you have not installed Tcl already, download the latest Tcl version from Sourceforge

    Debian:apt-get @@ -63,8 +63,8 @@

  • -Retrieve AOLserver. Download the aolserver -from CVS.

    +Retrieve AOLserver. Download the
+aolserver from CVS.
     [root root]# cd /usr/local/src
 [root src]# mkdir aolserver40r10
 [root src]# cd aolserver40r10
@@ -93,9 +93,9 @@

  • Configure, compile and install -AOLserver. Many people need to run more than one -version of AOLserver in parallel. This section accomodates future -upgrades by installing AOLserver 4 in /usr/local/aolserver40r9.

    +AOLserver. Many people need to run more than
+one version of AOLserver in parallel. This section accomodates
+future upgrades by installing AOLserver 4 in /usr/local/aolserver40r9.
     [root aolserver]# cd /usr/local/src/aolserver40r10/aolserver
 [root aolserver]# ./configure --prefix=/usr/local/aolserver40r10 --with-tcl=/usr/local/lib/
 [root aolserver]# make installcd /usr/local/src/aolserver40r10/aolserver
@@ -191,15 +191,15 @@

  • -Add a database-specific wrapper script. This -script sets database environment variables before starting -AOLserver; this allows the AOLserver instance to communicate with -the database. There is one script for Oracle and one for -PostgreSQL. They do not conflict. If you plan to use both -databases, install both. Note that this section requires you to -have OpenACS files available, which you can get through CVS, +Add a database-specific wrapper +script. This script sets database environment +variables before starting AOLserver; this allows the AOLserver +instance to communicate with the database. There is one script for +Oracle and one for PostgreSQL. They do not conflict. If you plan to +use both databases, install both. Note that this section requires +you to have OpenACS files available, which you can get through CVS, through a tarball, or by other means. You can come back to this -section after you acquire the OpenACS code, but don't forget to +section after you acquire the OpenACS code, but don't forget to come back. (Note to maintainers: this should be moved to the next page and integrated into the text there)

    • @@ -226,15 +226,16 @@

    You may need to edit these scripts if you are not using /usr/local/aolserver as the directory of Aolserver4.

  • -Change startup script (optional). If you want -to run AOLserver on a port below 1024 (normally, for a webserver -you will use 80), you will have to change the /var/lib/aolserver/service0/etc/daemontools/run +Change startup script +(optional). If you want to run AOLserver on a +port below 1024 (normally, for a webserver you will use 80), you +will have to change the /var/lib/aolserver/service0/etc/daemontools/run script according to the documentation found there (namely: Add the -b yourip:yourport switch)

  • Test AOLserver.

    • -
    ($‌Id: aolserver4.xml,v 1.31 2014/10/27 16:39:31 -victorg Exp $)
    +
    ($‌Id: aolserver4.html,v 1.27.2.10 2016/06/21 +07:44:35 gustafn Exp $)

    Retrieve Tcl 8.4 (or higher). Download and install Tcl 8.4 from source

    Note for Debian users: you can apt-get install tcl8.4-dev if you have the right version (stable users will need to add tcl8.4 to their sources.list file as described on the - Install Postgres page). You'll + Install Postgres page). You'll have to use /usr/lib/tcl8.4/ instead of /usr/local/lib when you try to find the tcl libraries, however.

    If you have not installed Tcl already, download the latest Tcl version from Sourceforge

    Debian: apt-get install @@ -96,7 +96,7 @@ Note that this section requires you to have OpenACS files available, which you can get through CVS, through a tarball, or by other means. You can come back to this section after you acquire the - OpenACS code, but don't forget to come back. (Note to + OpenACS code, but don't forget to come back. (Note to maintainers: this should be moved to the next page and integrated into the text there)

    • Oracle

      [root aolserver]# cd /usr/local/aolserver/bin
Index: openacs-4/packages/acs-core-docs/www/apm-design.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/apm-design.adp,v
diff -u -N -r1.1.2.2 -r1.1.2.3
--- openacs-4/packages/acs-core-docs/www/apm-design.adp	9 Jun 2016 08:44:49 -0000	1.1.2.2
+++ openacs-4/packages/acs-core-docs/www/apm-design.adp	23 Jun 2016 08:32:45 -0000	1.1.2.3
@@ -52,7 +52,7 @@
 and the OpenACS
 Kernel, which includes APM.

    An installation of the OpenACS includes the OpenACS Kernel, some -services that extend the kernel's functionality, and some +services that extend the kernel's functionality, and some applications intended for end-users. Packages function as individual pieces of subsites. A subsite can contain multiple application and service instances that provide the @@ -61,17 +61,18 @@ For example, Jane User starts a forum focusing on the merits of View Cameras by creating an instance of the Forum application for her personal subsite on an OpenACS Installation. Jack User -discovers Jane's forum and includes a link to it in his subsite. As -interest in Jane's forum grows, she creates a subsite specializing -in providing information about View cameras. This subsite now -includes several package instances beyond Forum; it could -potentially include its own Ecommerce capabilities (ala Yahoo! -Shopping). This could include a knowledge management -application that allows users to spread expertise about view -cameras and a portal application that links to reliable camera +discovers Jane's forum and includes a link to it in his +subsite. As interest in Jane's forum grows, she creates a +subsite specializing in providing information about View cameras. +This subsite now includes several package instances beyond Forum; +it could potentially include its own Ecommerce capabilities (ala +Yahoo! Shopping). This could include a knowledge +management application that allows users to spread expertise about +view cameras and a portal application that links to reliable camera models and resellers. Any subsite enabled package that is added to the OpenACS installation through APM is another potential package -instance that can become part of Jane's View Camera subsite.

    The APM provides an architecture for packaging software, making +instance that can become part of Jane's View Camera +subsite.

    The APM provides an architecture for packaging software, making instances of that software available to subsites, specifying configuration parameters for each instance, and managing the creation and release of new packages.

    @@ -100,15 +101,15 @@ affect dependent packages. Rather, the package interface should provide a level of abstraction above the data model (as well as the rest of the package implementation). Then, users of the package can -take advantage of implementation improvements that don't affect the -interface (e.g., faster performance from intelligent +take advantage of implementation improvements that don't affect +the interface (e.g., faster performance from intelligent denormalization of the data model), without having to worry that code outside the package will now break.

  • A typical ACS-backed site only uses a few of the modules included in the distribution, yet there was no well-understood way to pick only what you needed when installing the ACS, or even to -uninstall what you didn't need, post-installation. Unwanted code -had to be removed manually.

  • Releasing a new version of the ACS was complicated, owing again +uninstall what you didn't need, post-installation. Unwanted +code had to be removed manually.

  • Releasing a new version of the ACS was complicated, owing again to the monolithic nature of the software. Since we released everything in the ACS together, all threads of ACS development had to converge on a single deadline, after which we would undertake a @@ -150,8 +151,8 @@

  • a standard format for APM -packages (also called "OpenACS packages"), -including:

      +packages (also called "OpenACS +packages"), including:

      • version numbering, independent of any other package and the OpenACS as a whole

      • specification of the package interface

      • specification of dependencies on other packages (if any)

      • attribution (who wrote it) and ownership (who maintains it)

      @@ -214,8 +215,8 @@

    Authoring a Package

    Full instructions on how to prepare an OpenACS package are available in Packages. The API here can be invoked -manually by a package's data model creation script, but need not to -be used. This API is part of the APM PL/SQL package.

    +manually by a package's data model creation script, but need
+not to be used. This API is part of the APM PL/SQL package.
     
 -- Informs the APM that this application is available for use.
 procedure register_application (
@@ -333,8 +334,8 @@
 ) return apm_package_versions.version_id%TYPE;
 
 
    Versions can be enabled or disabled. Enabling a version
-instructs APM to source the package's libraries on startup and to
-make the package available to the OpenACS.
    +instructs APM to source the package's libraries on startup and
+to make the package available to the OpenACS.
     
 procedure enable (
     version_id          in apm_package_versions.version_id%TYPE
@@ -489,13 +490,13 @@
 for each Instance
    A parameter is a setting that can be changed on a package
 instance basis. Parameters are registered on each package_key, and the values are associated
 with each instance. Parameters can have default values and can be
-of type 'string' or 'number.' There is support with this API for
-setting a number of minimum and maximum values for each parameter,
-but for most instances, the minimum and maximum should be 1. It is
-useful to allow or require multiple values for packages that need
-to store multiple pieces of information under one parameter.
-Default values are automatically set when instances are created,
-but can be changed for each instance.
    All of the functions below are in the APM PL/SQL package.
    +of type 'string' or 'number.' There is support with
+this API for setting a number of minimum and maximum values for
+each parameter, but for most instances, the minimum and maximum
+should be 1. It is useful to allow or require multiple values for
+packages that need to store multiple pieces of information under
+one parameter. Default values are automatically set when instances
+are created, but can be changed for each instance.
    All of the functions below are in the APM PL/SQL package.
     
 -- Indicate to APM that a parameter is available to the system.
 function register_parameter (
@@ -576,7 +577,7 @@
 OpenACS instance, a corresponding row in this table is inserted
 with information about the type of package, e.g. if the forum package is
 installed on your OpenACS server, a row in apm_package_types will be created, noting
-that it's an application package type.
    The apm_packages table is
+that it's an application package type.
    The apm_packages table is
 used to contain information about the instances of packages currently created
 in the system. The package_key
 column references the apm_package_types table to ensure that no
@@ -614,9 +615,8 @@
 
 
    
 
    
-User Interface
    The APM's
-user interface is part of the OpenACS Administration Service. The
-UI is the primary point of contact with APM by developers and
+User Interface
    The APM's user interface is part of the OpenACS Administration Service.
+The UI is the primary point of contact with APM by developers and
 administrators. It is part of OpenACS Administration, because only
 the site-wide administrator should be able to access it. Thus in
 order to develop a package, the developer must be granted site-wide
Index: openacs-4/packages/acs-core-docs/www/apm-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/apm-design.html,v
diff -u -N -r1.40.2.1 -r1.40.2.2
--- openacs-4/packages/acs-core-docs/www/apm-design.html	9 Jun 2016 08:44:49 -0000	1.40.2.1
+++ openacs-4/packages/acs-core-docs/www/apm-design.html	23 Jun 2016 08:32:45 -0000	1.40.2.2
@@ -26,22 +26,22 @@
 Content Repository, the OpenACS Templating
 System, and the OpenACS Kernel, which includes
 APM.

    • An installation of the OpenACS includes the OpenACS Kernel, some services that -extend the kernel's functionality, and some applications intended for +extend the kernel's functionality, and some applications intended for end-users. Packages function as individual pieces of subsites. A subsite can contain multiple application and service instances that provide the end-user with capabilities and content customized to the particular subsite.

    This architecture supports the growth of collaborative commerce. For example, Jane User starts a forum focusing on the merits of View Cameras by creating an instance of the Forum application for her personal subsite on an -OpenACS Installation. Jack User discovers Jane's forum and includes a link to -it in his subsite. As interest in Jane's forum grows, she creates a +OpenACS Installation. Jack User discovers Jane's forum and includes a link to +it in his subsite. As interest in Jane's forum grows, she creates a subsite specializing in providing information about View cameras. This subsite now includes several package instances beyond Forum; it could potentially include its own Ecommerce capabilities (ala Yahoo! Shopping). This could include a knowledge management application that allows users to spread expertise about view cameras and a portal application that links to reliable camera models and resellers. Any subsite enabled package that is added to the OpenACS installation through APM is another potential package instance that can -become part of Jane's View Camera subsite.

    The APM provides an architecture for packaging software, making instances +become part of Jane's View Camera subsite.

    The APM provides an architecture for packaging software, making instances of that software available to subsites, specifying configuration parameters for each instance, and managing the creation and release of new packages.

    Historical Considerations

    Prior to ACS 3.3, all packages were lumped together into one monolithic @@ -61,12 +61,12 @@ model should not affect dependent packages. Rather, the package interface should provide a level of abstraction above the data model (as well as the rest of the package implementation). Then, users of the package can -take advantage of implementation improvements that don't affect the +take advantage of implementation improvements that don't affect the interface (e.g., faster performance from intelligent denormalization of the data model), without having to worry that code outside the package will now break.

  • A typical ACS-backed site only uses a few of the modules included in the distribution, yet there was no well-understood way to pick only what you -needed when installing the ACS, or even to uninstall what you didn't +needed when installing the ACS, or even to uninstall what you didn't need, post-installation. Unwanted code had to be removed manually. @@ -123,7 +123,7 @@ subsites across the system, and be available for distribution to other OpenACS installations without doing a monolithic upgrade or reinstall.

    • API

    The APM is composed of systems for accomplishing a set of package-related tasks. Each of these tasks comprise a feature area that has an API, data -model, and a UI:

    • Authoring a Package

    • Maintaining Multiple Versions of a Package

    • Creating Instances of the Package

    • Specifying Configuration Parameters for each Instance

    Authoring a Package

    Full instructions on how to prepare an OpenACS package are available in Packages. The API here can be invoked manually by a package's data model +model, and a UI:

    • Authoring a Package

    • Maintaining Multiple Versions of a Package

    • Creating Instances of the Package

    • Specifying Configuration Parameters for each Instance

    Authoring a Package

    Full instructions on how to prepare an OpenACS package are available in Packages. The API here can be invoked manually by a package's data model creation script, but need not to be used. This API is part of the APM PL/SQL package.

     
@@ -232,7 +232,7 @@
 ) return apm_package_versions.version_id%TYPE;

    Versions can be enabled or disabled. Enabling a version instructs APM to -source the package's libraries on startup and to make the package +source the package's libraries on startup and to make the package available to the OpenACS.

     
 procedure enable (
@@ -467,7 +467,7 @@
 table where each package is registered. When a new application or service is
 installed on an OpenACS instance, a corresponding row in this table is inserted
 with information about the type of package, e.g. if the forum package is installed on your OpenACS server, a row
-in apm_package_types will be created, noting that it's an
+in apm_package_types will be created, noting that it's an
 application package type.
    The apm_packages table is used to contain information about
 the instances of packages currently created in the system. The
 package_key column references the apm_package_types
Index: openacs-4/packages/acs-core-docs/www/apm-requirements.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/apm-requirements.adp,v
diff -u -N -r1.1.2.2 -r1.1.2.3
--- openacs-4/packages/acs-core-docs/www/apm-requirements.adp	9 Jun 2016 08:44:49 -0000	1.1.2.2
+++ openacs-4/packages/acs-core-docs/www/apm-requirements.adp	23 Jun 2016 08:32:45 -0000	1.1.2.3
@@ -83,7 +83,8 @@
 configuration:
      
 
    • The ability to change package parameter values on-line through a
 simple web interface.
    • A new ad_parameter which does not require a monolithic site-wide
-parameter's file or server restarts for changes to take effect.
    • The ability to manage multiple package instances at the sub-site
+parameter's file or server restarts for changes to take
+effect.
    • The ability to manage multiple package instances at the sub-site
 level.
      • 
 
    
 
@@ -94,17 +95,18 @@
 may or may not overlap:
      
 
    1. 
 Developers
-(referred to as 'the developer') use the APM to create a software
-package for distribution and use the procedural API for direct
-control of the APM system.
    2. 
+(referred to as 'the developer') use the APM to create a
+software package for distribution and use the procedural API for
+direct control of the APM system.
    3. 
 Site-wide
-administrators (referred to as 'the administrator')
-use the APM to install packages for their OpenACS instance, and
-optionally make them available to sub-sites.
    4. 
+administrators (referred to as 'the
+administrator') use the APM to install packages for their
+OpenACS instance, and optionally make them available to
+sub-sites.
    5. 
 Sub-site
-administrators (referred to as 'the sub-admin') use
-an administration interface to configure and enable packages for
-their sub-site.
      6. 
+administrators (referred to as 'the
+sub-admin') use an administration interface to configure and
+enable packages for their sub-site.
      
 
    Initial Package
 Development
    
 David Developer
@@ -113,29 +115,30 @@
 pages, and his documentation according to the APM specification. He
 splits the documentation and the code into sub-packages, and
 creates a KM installation-chain to install both with the APM
-developer UI. Noting that his software was built with Patricia Programmer's Super Widget
-toolkit, he specifies that as a dependency. Moreover, since this
-package is capable of being used at the sub-site level, David
+developer UI. Noting that his software was built with Patricia Programmer's Super
+Widget toolkit, he specifies that as a dependency. Moreover, since
+this package is capable of being used at the sub-site level, David
 configures this option in the package. When the package development
 is complete, David uses the APM developer UI to construct a
 distribution file. He assigns it a version number, 1.0, and makes
 the package available for download at the OpenACS package
 repository.
    Initial Package
 Installation
    
 Annie Admin learns
-of David's KM system by browsing the OpenACS package repository.
-Annie Admin uses the APM administrator UI on her system. She
-selects to install a package from a URL and types the URL displayed
-on the system. The APM automatically downloads the package. The
-dependency checker notices that Patricia's Super Widget toolkit is
-required, so it warns Annie of this. Annie selects an option to
-find a package that satisfies the dependency at the OpenACS APM
-repository. The APM informs Annie that it can download and install
-Jim's Super Widget toolkit. Annie confirms this option. After
-successfully installing Jim's toolkit, Annie proceeds to install
-David's KM system. The data model is loaded and all of the files
-necessary for the software are installed. Because installation was
-successful, the package is available for use.
    Since the package is available for use, its initialization
+of David's KM system by browsing the OpenACS package
+repository. Annie Admin uses the APM administrator UI on her
+system. She selects to install a package from a URL and types the
+URL displayed on the system. The APM automatically downloads the
+package. The dependency checker notices that Patricia's Super
+Widget toolkit is required, so it warns Annie of this. Annie
+selects an option to find a package that satisfies the dependency
+at the OpenACS APM repository. The APM informs Annie that it can
+download and install Jim's Super Widget toolkit. Annie confirms
+this option. After successfully installing Jim's toolkit, Annie
+proceeds to install David's KM system. The data model is loaded
+and all of the files necessary for the software are installed.
+Because installation was successful, the package is available for
+use.
    Since the package is available for use, its initialization
 routines are set to run automatically on server startup. Annie is
 warned that since there are initialization routines, she must
 restart the server for the package to be ready for use. Annie
@@ -164,7 +167,7 @@
 repository.
    Sally SubAdmin asks Annie Administrator to upgrade the package
 using the APM UI. This upgrade supersedes the old version of KM at
 the site-wide level. Once Annie upgrades the package, the new
-version starts working immediately in Sally's sub-site.
    Procedural API
    
+version starts working immediately in Sally's sub-site.
    Procedural API
    
 Danielle Developer
 wants her software to perform different actions depending on what
 version of another package is installed. She uses the APM
@@ -187,7 +190,8 @@
 the developer using the developer UI.)
    
 4.500.1 A human
 readable package key that is guaranteed to be unique to the local
-OpenACS site must be maintained by the APM. For example, "apm."
    
+OpenACS site must be maintained by the APM. For example,
+"apm."
    
 4.500.5 A package
 id (primary key) that is guaranteed to be unique to the local site
 must be maintained by the APM. For example, "25."
    
@@ -271,11 +275,11 @@
 the running OpenACS.

    -Requirements: The Developer's -Interface

    The intent of the developer's interface is to enable the +Requirements: The +Developer's Interface

    The intent of the developer's interface is to enable the developer to construct and maintain APM packages. It will be -possible to disable the developer's interface for production sites -to help reduce the chance of site failure; much of the +possible to disable the developer's interface for production +sites to help reduce the chance of site failure; much of the functionality here can have cascading effects throughout the OpenACS and should not be used on a production site.

    • @@ -305,15 +309,15 @@ package

      20.1 The developer must be able to add files to the package. This is done by copying -the files into the package directory in the host OS's file system. -Files can be added at any point after package creation.

      +the files into the package directory in the host OS's file +system. Files can be added at any point after package creation.

      20.3 Once a package has been versioned and distributed, no new files should be added to the package without incrementing the version number.

      -20.5 The APM's UI -should facilitate the process of adding new files, by scanning the -file system for new files automatically, and allowing the developer -to confirm adding them.

      +20.5 The APM's +UI should facilitate the process of adding new files, by scanning +the file system for new files automatically, and allowing the +developer to confirm adding them.

      20.10 The developer cannot add files to a given package via the UI that do not exist in the file system already.

      @@ -338,7 +342,7 @@ file from file system.

      30.5.1 The APM UI should take note of the fact that the file is gone and offer the -developer an option to confirm the file's deletion.

      +developer an option to confirm the file's deletion.

  • @@ -355,8 +359,8 @@ detail.

    40.10 Also, although a change in files implies that the package distribution -file is out of date, it is the developer's responsibility to update -it.

    +file is out of date, it is the developer's responsibility to +update it.

  • 4.45.0 Manage Package Dependency @@ -402,9 +406,9 @@ should be able to generate a .APM distribution file for the package with just one click.

    130.5 Generating a -distribution file implies doing an "up-to-date" check on all of the -files. If any of the files have changed since package installation, -then a new version of the package is created.

    +distribution file implies doing an "up-to-date" check on +all of the files. If any of the files have changed since package +installation, then a new version of the package is created.

  • 140.0 Access CVS information

    @@ -436,9 +440,9 @@

    Requirements: The Site-Wide -Administrator's Interface

    The requirement of the administrator's interface is to enable -the administrator to install, enable, upgrade, disable, deinstall, -and delete packages.

      +Administrator's Interface

    The requirement of the administrator's interface is to +enable the administrator to install, enable, upgrade, disable, +deinstall, and delete packages.

    • 80.0 Package Enable/Disable

      @@ -541,8 +545,8 @@ 100.1.5 Replacing any old files with new versions.

    • 100.1.10 Marking -the old version of the package as 'superseded' and disabling -it.

    • +the old version of the package as 'superseded' and +disabling it.

    • 100.1.15 Assuming no errors from above, the new package is enabled.

    @@ -595,12 +599,12 @@

    Requirements: The Sub-Site -Administrator's Interface

    If the developer is in charge of creating packages and the +Administrator's Interface

    If the developer is in charge of creating packages and the administrator for installing them, then the sub-site administrator is responsible for configuring and enabling packages. In order for a package to be available for a sub-site it must be associated with -the sub-site's type specification. This interface is part of the -sub-site /admin interface.

      +the sub-site's type specification. This interface is part of +the sub-site /admin interface.

      • 4.300 Creating a @@ -610,12 +614,12 @@ packages available in the system as well as an option to add a package to the subsite.

        4.300.5 From the -"add" option, the sub-admin can select from a list of packages -registered as available in the sub-site type to which the sub-site -belongs.

        +"add" option, the sub-admin can select from a list of +packages registered as available in the sub-site type to which the +sub-site belongs.

        4.300.19 Once a package instance is added, it is available on the list of the -subsite's available packages.

        +subsite's available packages.

      • 4.305 Configuring a Index: openacs-4/packages/acs-core-docs/www/apm-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/apm-requirements.html,v diff -u -N -r1.36.2.1 -r1.36.2.2 --- openacs-4/packages/acs-core-docs/www/apm-requirements.html 9 Jun 2016 08:44:49 -0000 1.36.2.1 +++ openacs-4/packages/acs-core-docs/www/apm-requirements.html 23 Jun 2016 08:32:45 -0000 1.36.2.2 @@ -37,7 +37,7 @@

      • Web-based tools for package development:

        • Creating new packages locally

        • Releasing new versions of locally-created packages

        • Uploading packages to a global package repository on the web

        • Use of these tools should be safe, i.e. installing or removing a package should never break an OpenACS installation

      • Web-based tools for package configuration:

        • The ability to change package parameter values on-line through a simple web interface.

        • A new ad_parameter which does not require a monolithic site-wide -parameter's file or server restarts for changes to take effect.

        • The ability to manage multiple package instances at the sub-site +parameter's file or server restarts for changes to take effect.

        • The ability to manage multiple package instances at the sub-site level.

    Use-cases and User-scenarios

    The APM is intended for the following classes of users, which may or may not overlap:

    1. Developers (referred to as 'the developer') use @@ -57,16 +57,16 @@ sub-site level, David configures this option in the package. When the package development is complete, David uses the APM developer UI to construct a distribution file. He assigns it a version number, 1.0, and makes the package -available for download at the OpenACS package repository.

      Initial Package Installation

      Annie Admin learns of David's KM system by browsing +available for download at the OpenACS package repository.

      Initial Package Installation

      Annie Admin learns of David's KM system by browsing the OpenACS package repository. Annie Admin uses the APM administrator UI on her system. She selects to install a package from a URL and types the URL displayed on the system. The APM automatically downloads the package. The -dependency checker notices that Patricia's Super Widget toolkit is +dependency checker notices that Patricia's Super Widget toolkit is required, so it warns Annie of this. Annie selects an option to find a package that satisfies the dependency at the OpenACS APM repository. The -APM informs Annie that it can download and install Jim's Super Widget -toolkit. Annie confirms this option. After successfully installing Jim's -toolkit, Annie proceeds to install David's KM system. The data model is +APM informs Annie that it can download and install Jim's Super Widget +toolkit. Annie confirms this option. After successfully installing Jim's +toolkit, Annie proceeds to install David's KM system. The data model is loaded and all of the files necessary for the software are installed. Because installation was successful, the package is available for use.

      Since the package is available for use, its initialization routines are set to run automatically on server startup. Annie is warned that since there @@ -91,7 +91,7 @@ repository.

      Sally SubAdmin asks Annie Administrator to upgrade the package using the APM UI. This upgrade supersedes the old version of KM at the site-wide level. Once Annie upgrades the package, the new version starts working immediately -in Sally's sub-site.

      Procedural API

      Danielle Developer wants her software to perform +in Sally's sub-site.

      Procedural API

      Danielle Developer wants her software to perform different actions depending on what version of another package is installed. She uses the APM procedural API to check if KM version 1.0 is installed or version 1.1. Based on the results of this procedural call, the software @@ -132,9 +132,9 @@

    2. 4.600.5 The APM will provide a facility to validate both the PGP signature and MD5 stamps information before a package install.

    Requirements: The User Interface

    The user interface is a set of HTML pages that are used to drive the underlying API. It is restricted to site-wide administrators because the -actions taken here can dramatically affect the state of the running OpenACS.

    Requirements: The Developer's Interface

    The intent of the developer's interface is to enable the developer to +actions taken here can dramatically affect the state of the running OpenACS.

    Requirements: The Developer's Interface

    The intent of the developer's interface is to enable the developer to construct and maintain APM packages. It will be possible to disable the -developer's interface for production sites to help reduce the chance of +developer's interface for production sites to help reduce the chance of site failure; much of the functionality here can have cascading effects throughout the OpenACS and should not be used on a production site.

    • 10.0 Define a package.

      The developer must be able to create a new package by specifying some identifying information for the package. This includes a package name, a @@ -159,14 +159,14 @@ done in two ways.

      • 30.1 Access the APM UI, browse the file list, and remove files.

        30.1.1If a file is removed from the package list, but not from the file system, an error should be generated at package load time.

      • 30.5 Remove the file from file system.

        30.5.1 The APM UI should take note of the fact that the -file is gone and offer the developer an option to confirm the file's +file is gone and offer the developer an option to confirm the file's deletion.

    • 40.0 Modify files in a package.

      40.1 The developer should be able to modify files in the file system. The APM UI should not interfere with this.

      40.5 However, if the developer modifies files containing procedural definitions, APM UI should allow a means to watch those files and automatically reload them if changed. See requirement 50.0 for more detail.

      40.10 Also, although a change in files implies that the -package distribution file is out of date, it is the developer's +package distribution file is out of date, it is the developer's responsibility to update it.

    • 4.45.0 Manage Package Dependency Information.

      4.45.1 The developer should be able to specify which interfaces the package requires.

      4.45.5 The developer should be able to specify which interfaces the package provides.

      4.45.10 Circular dependencies are not allowed.

    • 50.0 Watch a file

      4.50.1 The developer should be able to assign a watch to @@ -201,7 +201,7 @@ but this is discouraged. In such a case, the sub-package should really be a separate package that is required by the compound package.

      4.400.10 If a sub-package is required for the installation of the compound package, the compound package should have a -registered dependency on the sub-package.

    Requirements: The Site-Wide Administrator's Interface

    The requirement of the administrator's interface is to enable the +registered dependency on the sub-package.

    • Requirements: The Site-Wide Administrator's Interface

    The requirement of the administrator's interface is to enable the administrator to install, enable, upgrade, disable, deinstall, and delete packages.

    • 80.0 Package Enable/Disable

      4.80.1 The administrator should be able mark an installed package as enabled. This means that the package is activated and its @@ -259,18 +259,18 @@ consequences throughout a site and should almost never be done.

    • 150.0 Scan for new or modified packages

      150.1 The administrator should be able to scan the file system for any changes made in any of the installed package files.

      150.5 The administrator should be able to scan the file system for any newly installed packages. -

    Requirements: The Sub-Site Administrator's Interface

    +

    Requirements: The Sub-Site Administrator's Interface

    If the developer is in charge of creating packages and the administrator for installing them, then the sub-site administrator is responsible for configuring and enabling packages. In order for a package to be available for -a sub-site it must be associated with the sub-site's type specification. +a sub-site it must be associated with the sub-site's type specification. This interface is part of the sub-site /admin interface.

    • 4.300 Creating a package instance.

      4.300.1 From the sub-site /admin interface, there should be an option to view all packages available in the system as well as an option to add a package to the subsite.

      4.300.5 From the "add" option, the sub-admin can select from a list of packages registered as available in the sub-site type to which the sub-site belongs.

      4.300.19 Once a package instance is added, it is -available on the list of the subsite's available packages.

    • 4.305 Configuring a package instance.

      4.305.1 An automatic web interface that lists all +available on the list of the subsite's available packages.

    • 4.305 Configuring a package instance.

      4.305.1 An automatic web interface that lists all parameters with current values must be available.

      4.305.5 Changing the values for the parameters is accomplished simply by submitting an HTML form.

    • 4.310 Enabling a package instance.

      4.310.1 The sub-admin should be able to enable a package with a single click. Enabling a package means that the OpenACS will serve its Index: openacs-4/packages/acs-core-docs/www/automated-backup.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/automated-backup.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/automated-backup.adp 23 Sep 2015 11:54:21 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/automated-backup.adp 23 Jun 2016 08:32:45 -0000 1.1.2.2 @@ -23,10 +23,9 @@ chmod +x backup.sh

    • -

      Set this file to run automatically by adding a line to root's -crontab. (Typically, with export -EDITOR=emacs; crontab -e.) This example runs the backup -script at 1:30 am every day.

      +
      Set this file to run automatically by adding a line to
+root's crontab. (Typically, with export EDITOR=emacs; crontab -e.) This
+example runs the backup script at 1:30 am every day.
       30 1 * * *        sh /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/backup.sh
      • Index: openacs-4/packages/acs-core-docs/www/automated-backup.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/automated-backup.html,v diff -u -N -r1.13.2.1 -r1.13.2.2 --- openacs-4/packages/acs-core-docs/www/automated-backup.html 9 Jun 2016 08:44:49 -0000 1.13.2.1 +++ openacs-4/packages/acs-core-docs/www/automated-backup.html 23 Jun 2016 08:32:45 -0000 1.13.2.2 @@ -1,4 +1,4 @@ Automated Backup
      Alex logo
      Prev Chapter 8. Backup and Recovery Next

      Automated Backup

      The recommended backup strategy for a production sit is to use an automated script which first backs up the database to a file in /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup and then backs up all of /var/lib/aolserver/$OPENACS_SERVICE_NAME to a single zip file, and then copies that zip file to another computer.

      1. Make sure that the manual backup process described above works.

      2. Customize the default backup script. Edit /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/backup.sh with your specific parameters.

      3. Make sure the file is executable:

        chmod +x backup.sh

      4. - Set this file to run automatically by adding a line to root's crontab. (Typically, with export EDITOR=emacs; crontab -e.) This example runs the backup script at 1:30 am every day.

        30 1 * * *        sh /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/backup.sh
      Prev Home Next
      Manual backup and recovery Up Using CVS for backup-recovery
      docs@openacs.org
      View comments on this page at openacs.org
      + Set this file to run automatically by adding a line to root's crontab. (Typically, with export EDITOR=emacs; crontab -e.) This example runs the backup script at 1:30 am every day.

      30 1 * * *        sh /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/backup.sh
    Prev Home Next
    Manual backup and recovery Up Using CVS for backup-recovery
    docs@openacs.org
    View comments on this page at openacs.org
    Index: openacs-4/packages/acs-core-docs/www/automated-testing-best-practices.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/automated-testing-best-practices.adp,v diff -u -N -r1.1.2.4 -r1.1.2.5 --- openacs-4/packages/acs-core-docs/www/automated-testing-best-practices.adp 9 Jun 2016 13:03:11 -0000 1.1.2.4 +++ openacs-4/packages/acs-core-docs/www/automated-testing-best-practices.adp 23 Jun 2016 08:32:45 -0000 1.1.2.5 @@ -15,40 +15,44 @@ OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

    Best practices in writing OpenACS automated tests

    • -Special characters in Tcl.  Try strings -starting with a -Bad and -strings containing [BAD], +Special characters in Tcl.  Try +strings starting with a -Bad +and strings containing [BAD], {, \077, and $Bad. For user input, [BAD] should never be evaluated, \077 should not be turned into a ? and $Bad should not be interpolated. The string -Bad [BAD] \077 { $Bad should be valid user input, should pass through the system unaltered, and -if it isn't that's a bug.

    • -Quoting issues. Put some html in plain text -fields and make sure the result is properly quoted anywhere it -shows up (I use "<b>bold</b>" usually). Look out -especially for quoting errors in the context bar and in round trips -via an edit form. For fields that disallow html tags you can use -&amp; to check that the -field is quoted properly. If it is not displayed as &amp; then the quoting for the field is -incorrect. (It's not clear whether this should be considered an -error but given that data for text fields can come from various -sources if it's text it should be properly quoted and we should not -rely on input validation to prevent XSS security holes.)

    • -Whitespace input. Check that whitespace is -not considered valid input for a field if it does not make sense. -For example, the subject of a forum post is used to construct a -link and if it is " " it will have a link of <a href="..."> </a> which would -not be clickable if whitespace was allowed as a valid input.

    • -Doubleclick.  Make sure that if you submit a -form, use the back button, and submit again that the behavior is -reasonable (correct behavior depends on what the form is for, but a -server error is not reasonable).

    • -Duplicate names.  Make sure that if a -duplicate name is entered that there is a reasonable error rather +if it isn't that's a bug.

    • +Quoting issues. Put some html in +plain text fields and make sure the result is properly quoted +anywhere it shows up (I use "<b>bold</b>" +usually). Look out especially for quoting errors in the context bar +and in round trips via an edit form. For fields that disallow html +tags you can use &amp; to +check that the field is quoted properly. If it is not displayed as +&amp; then the quoting for +the field is incorrect. (It's not clear whether this should be +considered an error but given that data for text fields can come +from various sources if it's text it should be properly quoted +and we should not rely on input validation to prevent XSS security +holes.)

    • +Whitespace input. Check that +whitespace is not considered valid input for a field if it does not +make sense. For example, the subject of a forum post is used to +construct a link and if it is " " it will have a link of +<a href="..."> +</a> which would not be clickable if whitespace was +allowed as a valid input.

    • +Doubleclick.  Make sure that if you +submit a form, use the back button, and submit again that the +behavior is reasonable (correct behavior depends on what the form +is for, but a server error is not reasonable).

    • +Duplicate names.  Make sure that if +a duplicate name is entered that there is a reasonable error rather than a server error. Check for insert, move, copy, and rename.

      • -
    ($‌Id: auto-testing.xml,v 1.3 2006/07/17 -05:38:37 torbenb Exp $)
    +
    ($‌Id: automated-testing-best-practices.html,v +1.28.2.10 2016/06/21 07:44:35 gustafn Exp $)

    Best practices in writing OpenACS automated tests

    • Special characters in Tcl.  -Try strings starting with a -Bad and strings containing [BAD], {, \077, and $Bad. For user input, [BAD] should never be evaluated, \077 should not be turned into a ? and $Bad should not be interpolated. The string -Bad [BAD] \077 { $Bad should be valid user input, should pass through the system unaltered, and if it isn't that's a bug. +Try strings starting with a -Bad and strings containing [BAD], {, \077, and $Bad. For user input, [BAD] should never be evaluated, \077 should not be turned into a ? and $Bad should not be interpolated. The string -Bad [BAD] \077 { $Bad should be valid user input, should pass through the system unaltered, and if it isn't that's a bug.

    • Quoting issues. Put some html in plain text fields and make sure the result is properly quoted anywhere it shows up (I use "<b>bold</b>" usually). Look out especially for quoting errors in the context bar and in round trips via an edit form. For fields that disallow html tags you can use &amp; to check that the field is quoted -properly. If it is not displayed as &amp; then the quoting for the field is incorrect. (It's not clear whether this +properly. If it is not displayed as &amp; then the quoting for the field is incorrect. (It's not clear whether this should be considered an error but given that data for text fields can -come from various sources if it's text it should be properly quoted +come from various sources if it's text it should be properly quoted and we should not rely on input validation to prevent XSS security holes.)

    • Whitespace input. Check that whitespace is not considered valid input for a field if it does not make sense. For example, the subject of a forum post is Index: openacs-4/packages/acs-core-docs/www/backup-recovery.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/backup-recovery.adp,v diff -u -N -r1.1.2.11 -r1.1.2.12 --- openacs-4/packages/acs-core-docs/www/backup-recovery.adp 21 Jun 2016 07:44:35 -0000 1.1.2.11 +++ openacs-4/packages/acs-core-docs/www/backup-recovery.adp 23 Jun 2016 08:32:45 -0000 1.1.2.12 @@ -7,7 +7,7 @@

      @@ -21,17 +21,17 @@ for backup-recovery

      -
      ($‌Id: recovery.xml,v 1.17 2010/12/11 23:36:32 -ryang Exp $)

      By Don Baccus with additions by Joel Aufrecht +

      ($‌Id: backup-recovery.html,v 1.43.2.10 +2016/06/21 07:44:35 gustafn Exp $)

      By Don Baccus with additions by Joel Aufrecht

      We will cover some basic backup and recovery strategies. These are intended to be robust but simple enough to set up. For a large scale production site you would probably need to create your own backup strategies (in particular full dumps from oracle, while easy to set up, are far from the best solution).

      There are three basic things which need to be backed up, the database data, the server source tree, and the acs-content-repository (which is in the server source tree).

      -

      Figure 8.1. Backup and -Recovery Strategy

      Backup and Recovery Strategy
      +

      Figure 8.1. Backup +and Recovery Strategy

      Backup and Recovery Strategy


      OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
      Index: openacs-4/packages/acs-core-docs/www/backup-recovery.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/backup-recovery.html,v diff -u -N -r1.43.2.10 -r1.43.2.11 --- openacs-4/packages/acs-core-docs/www/backup-recovery.html 21 Jun 2016 07:44:35 -0000 1.43.2.10 +++ openacs-4/packages/acs-core-docs/www/backup-recovery.html 23 Jun 2016 08:32:45 -0000 1.43.2.11 @@ -1,5 +1,5 @@ -Chapter 8. Backup and Recovery
      Alex logo
      Prev Part II. Administrator's Guide Next

      Chapter 8. Backup and Recovery

      Table of Contents

      Backup Strategy
      Manual backup and recovery
      Automated Backup
      Using CVS for backup-recovery
      ($Id$)

      By Don Baccus with additions +Chapter 8. Backup and Recovery

      Alex logo
      Prev Part II. Administrator's Guide Next

      Chapter 8. Backup and Recovery

      Table of Contents

      Backup Strategy
      Manual backup and recovery
      Automated Backup
      Using CVS for backup-recovery
      ($Id$)

      By Don Baccus with additions by Joel Aufrecht

      We will cover some basic backup and recovery strategies. These are intended to be robust but simple enough to set up. For a large scale production site you would probably need to create your own backup strategies (in particular full dumps from Index: openacs-4/packages/acs-core-docs/www/backups-with-cvs.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/backups-with-cvs.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/backups-with-cvs.adp 23 Sep 2015 11:54:22 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/backups-with-cvs.adp 23 Jun 2016 08:32:45 -0000 1.1.2.2 @@ -11,10 +11,10 @@

      Using CVS for backup-recovery

      CVS-only backup is often appropriate for development sites. If you are already using CVS and your data is not important, you -probably don't need to do anything to back up your files. Just make -sure that your current work is checked into the system. You can -then roll back based on date - note the current system time, down -to the minute. For maximum safety, you can apply a tag to your +probably don't need to do anything to back up your files. Just +make sure that your current work is checked into the system. You +can then roll back based on date - note the current system time, +down to the minute. For maximum safety, you can apply a tag to your current files. You will still need to back up your database.

      Note that, if you did the CVS options in this document, the /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc directory is not included in cvs and you may want to add it.

      Index: openacs-4/packages/acs-core-docs/www/backups-with-cvs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/backups-with-cvs.html,v
diff -u -N -r1.13.2.1 -r1.13.2.2
--- openacs-4/packages/acs-core-docs/www/backups-with-cvs.html	9 Jun 2016 08:44:49 -0000	1.13.2.1
+++ openacs-4/packages/acs-core-docs/www/backups-with-cvs.html	23 Jun 2016 08:32:45 -0000	1.13.2.2
@@ -1,5 +1,5 @@
 
-Using CVS for backup-recovery
      Alex logo
      Prev Chapter 8. Backup and Recovery Next
      Using CVS for backup-recovery
      CVS-only backup is often appropriate for development sites.  If you are already using CVS and your data is not important, you probably don't
+Using CVS for backup-recovery
      Alex logo
      Prev Chapter 8. Backup and Recovery Next
      Using CVS for backup-recovery
      CVS-only backup is often appropriate for development sites.  If you are already using CVS and your data is not important, you probably don't
       need to do anything to back up your files.  Just make
       sure that your current work is checked into the system.
       You can then roll back based on date - note the
Index: openacs-4/packages/acs-core-docs/www/bootstrap-acs.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/bootstrap-acs.adp,v
diff -u -N -r1.1.2.3 -r1.1.2.4
--- openacs-4/packages/acs-core-docs/www/bootstrap-acs.adp	28 Sep 2015 07:54:10 -0000	1.1.2.3
+++ openacs-4/packages/acs-core-docs/www/bootstrap-acs.adp	23 Jun 2016 08:32:45 -0000	1.1.2.4
@@ -43,8 +43,8 @@
 they are running OpenACS.
      Next AOLserver sources, in lexicographical order, each file in
 the /tcl directory. The first
 such file is 0-acs-init.tcl,
-which doesn't do much directly except to determine the OpenACS path
-root (e.g., /var/lib/aolserver/yourservername) by trimming the
+which doesn't do much directly except to determine the OpenACS
+path root (e.g., /var/lib/aolserver/yourservername) by trimming the
 final component from the path to the Tcl library directory
 (/var/lib/aolserver/yourservername/tcl).
 But 0-acs-init.tcl's has an
@@ -53,7 +53,7 @@
 
    • 
 Initialize some NSVs used by the
 core. These NSVs are documented in /packages/acs-core/apm-procs.tcl - no need
-to worry about them unless you're an OpenACS core hacker.
    • 
+to worry about them unless you're an OpenACS core hacker.
    • 
 Verify the deletion of obsolete
 OpenACS files. The /tcl directory has evolved quite a bit over
 the months and years, and a few files have come and gone. The
@@ -70,25 +70,26 @@
 the following steps.
    • 
 Ensure that the database is
 available by grabbing and releasing a handle. If we
-can't obtain a handle, we terminate initialization (since OpenACS
-couldn't possibly start up the server without access to the
-database).
    • 
+can't obtain a handle, we terminate initialization (since
+OpenACS couldn't possibly start up the server without access to
+the database).
    • 
 Register any new packages in the
 /packages
 directory. In each directory inside /packages, we look for a .info file; if we find a package that
-hasn't yet been registered with the package manager (i.e., it's
-been copied there manually), we insert information about it into
-the database. (The first time OpenACS starts up, no packages will have been registered in
-the database yet, so this step will registers every single package
-in the /packages directory.)
-Note that packages discovered here are initially disabled; they
-must be manually enabled in the package manager before they can be
-used.
    • 
+hasn't yet been registered with the package manager (i.e.,
+it's been copied there manually), we insert information about
+it into the database. (The first time OpenACS starts up,
+no packages will have been
+registered in the database yet, so this step will registers every
+single package in the /packages
+directory.) Note that packages discovered here are initially
+disabled; they must be manually enabled in the package manager
+before they can be used.
    • 
 Ensure that the acs-kernel package is
-enabled. If the OpenACS core isn't initialized, the
-server couldn't possibly be operational, so if there's no enabled
-version of the OpenACS core we simply mark the latest installed one
-as enabled.
    • 
+enabled. If the OpenACS core isn't initialized,
+the server couldn't possibly be operational, so if there's
+no enabled version of the OpenACS core we simply mark the latest
+installed one as enabled.
    • 
 Load *-procs.tcl files for enabled
 packages, activating their APIs.
    • 
 Load *-init.tcl files for enabled
@@ -97,13 +98,13 @@
 Verify that the core has been
 properly initialized by checking for the existence
 of an NSV created by the request processor initialization code. If
-it's not present, the server won't be operational, so we log an
-error.
      • 
+it's not present, the server won't be operational, so we
+log an error.

    At this point, bootstrap.tcl is done executing. AOLserver proceeds to source the remaining files in the /tcl directory (i.e., -unpackaged libraries) and begins listening for connections.

    ($‌Id: bootstrap-acs.xml,v 1.7 2006/07/17 -05:38:38 torbenb Exp $)
    +unpackaged libraries) and begins listening for connections.

    ($‌Id: bootstrap-acs.html,v 1.49.2.10 2016/06/21 +07:44:35 gustafn Exp $)

    Next AOLserver sources, in lexicographical order, each file in the /tcl directory. The first such file is -0-acs-init.tcl, which doesn't do much directly except to +0-acs-init.tcl, which doesn't do much directly except to determine the OpenACS path root (e.g., /var/lib/aolserver/yourservername) by trimming the final component from the path to the Tcl library directory (/var/lib/aolserver/yourservername/tcl). But 0-acs-init.tcl's has an important function, namely sourcing /packages/acs-core/bootstrap.tcl, which does the following:

    1. Initialize some NSVs used by the core. These NSVs are documented in /packages/acs-core/apm-procs.tcl - no need to -worry about them unless you're an OpenACS core hacker. +worry about them unless you're an OpenACS core hacker.

    2. Verify the deletion of obsolete OpenACS files. The /tcl directory has evolved quite a bit over the months and @@ -52,14 +52,14 @@ procedure are needed to perform any of the following steps.

    3. Ensure that the database is available by grabbing and -releasing a handle. If we can't obtain a handle, we terminate -initialization (since OpenACS couldn't possibly start up the server without +releasing a handle. If we can't obtain a handle, we terminate +initialization (since OpenACS couldn't possibly start up the server without access to the database).

    4. Register any new packages in the /packages directory. In each directory inside /packages, we look -for a .info file; if we find a package that hasn't yet been -registered with the package manager (i.e., it's been copied there +for a .info file; if we find a package that hasn't yet been +registered with the package manager (i.e., it's been copied there manually), we insert information about it into the database. (The first time OpenACS starts up, no packages will have been registered in the database yet, so this step will registers every single package in the @@ -68,8 +68,8 @@ before they can be used.

    5. Ensure that the acs-kernel package is -enabled. If the OpenACS core isn't initialized, the server -couldn't possibly be operational, so if there's no enabled version of +enabled. If the OpenACS core isn't initialized, the server +couldn't possibly be operational, so if there's no enabled version of the OpenACS core we simply mark the latest installed one as enabled.

    6. Load *-procs.tcl files for enabled @@ -81,7 +81,7 @@

    7. Verify that the core has been properly initialized by checking for the existence of an NSV created by the request processor -initialization code. If it's not present, the server won't be +initialization code. If it's not present, the server won't be operational, so we log an error.

    At this point, bootstrap.tcl is done executing. AOLserver proceeds to source the remaining files in the /tcl directory Index: openacs-4/packages/acs-core-docs/www/complete-install.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/complete-install.adp,v diff -u -N -r1.1.2.3 -r1.1.2.4 --- openacs-4/packages/acs-core-docs/www/complete-install.adp 9 Jun 2016 13:03:11 -0000 1.1.2.3 +++ openacs-4/packages/acs-core-docs/www/complete-install.adp 23 Jun 2016 08:32:45 -0000 1.1.2.4 @@ -7,7 +7,7 @@

    Index: openacs-4/packages/acs-core-docs/www/complete-install.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/complete-install.html,v diff -u -N -r1.25.2.2 -r1.25.2.3 --- openacs-4/packages/acs-core-docs/www/complete-install.html 9 Jun 2016 13:03:11 -0000 1.25.2.2 +++ openacs-4/packages/acs-core-docs/www/complete-install.html 23 Jun 2016 08:32:45 -0000 1.25.2.3 @@ -1,2 +1,2 @@ -Chapter 3. Complete Installation
    Alex logo
    Prev Part II. Administrator's Guide Next

    Chapter 3. Complete Installation

    Table of Contents

    Install a Unix-like system and supporting software
    Install Oracle 8.1.7
    Install PostgreSQL
    Install AOLserver 4
    Install OpenACS 5.9.0
    OpenACS Installation Guide for Windows
    OpenACS Installation Guide for Mac OS X
    Prev Home Next
    Prerequisite Software Up Install a Unix-like system and supporting software
    docs@openacs.org
    View comments on this page at openacs.org
    +Chapter 3. Complete Installation
    Alex logo
    Prev Part II. Administrator's Guide Next

    Chapter 3. Complete Installation

    Table of Contents

    Install a Unix-like system and supporting software
    Install Oracle 8.1.7
    Install PostgreSQL
    Install AOLserver 4
    Install OpenACS 5.9.0
    OpenACS Installation Guide for Windows
    OpenACS Installation Guide for Mac OS X
    Prev Home Next
    Prerequisite Software Up Install a Unix-like system and supporting software
    docs@openacs.org
    View comments on this page at openacs.org
    Index: openacs-4/packages/acs-core-docs/www/configuring-configuring-packages.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-configuring-packages.adp,v diff -u -N -r1.1.2.10 -r1.1.2.11 --- openacs-4/packages/acs-core-docs/www/configuring-configuring-packages.adp 21 Jun 2016 07:44:35 -0000 1.1.2.10 +++ openacs-4/packages/acs-core-docs/www/configuring-configuring-packages.adp 23 Jun 2016 08:32:45 -0000 1.1.2.11 @@ -17,12 +17,12 @@ OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

    -Configuring an OpenACS package

    After you've installed and mounted your package, you can +Configuring an OpenACS package

    After you've installed and mounted your package, you can configure each instance to act as you would like.

    This is done from the Applications page. Log in, go to the Admin or Control Panel, click on the subsite the application is in, and -click on Applications. If you click on the 'Parameters' link, you -will see a list of parameters that you can change for this -application.

    +click on Applications. If you click on the 'Parameters' +link, you will see a list of parameters that you can change for +this application.

    Configuring an OpenACS package
    Alex logo
    Prev Chapter 4. Configuring a new OpenACS Site Next

    Configuring an OpenACS package

    by Jade Rubick

    OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

    Configuring an OpenACS package

    After you've installed and mounted your package, you can +

    Configuring an OpenACS package

    After you've installed and mounted your package, you can configure each instance to act as you would like.

    This is done from the Applications page. Log in, go to the Admin or Control Panel, click on the subsite the application is in, and click on Applications. If you click on the 'Parameters' Index: openacs-4/packages/acs-core-docs/www/configuring-configuring-permissions.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-configuring-permissions.adp,v diff -u -N -r1.1.2.10 -r1.1.2.11 --- openacs-4/packages/acs-core-docs/www/configuring-configuring-permissions.adp 21 Jun 2016 07:44:35 -0000 1.1.2.10 +++ openacs-4/packages/acs-core-docs/www/configuring-configuring-permissions.adp 23 Jun 2016 08:32:45 -0000 1.1.2.11 @@ -18,18 +18,18 @@ OpenACS documentation staff.

    Setting Permission on an OpenACS -package

    After you've installed and mounted your package, you can +package

    After you've installed and mounted your package, you can configure each instance to act as you would like.

    This is done from the Applications page. Log in, go to the Admin or Control Panel, click on the subsite the application is in, and -click on Applications. If you click on the 'Permissions' link, you -will see and be able to set the permissions for that +click on Applications. If you click on the 'Permissions' +link, you will see and be able to set the permissions for that application.

    Each application may have different behavior for what Read Create Write and Admin permissions mean, but generally the permissions are straightforward. If you find the behavior is not what you expect after setting permissions, you can post a bug in -the OpenACS bugtracker.

    'The Public' refers to users to the website who are not logged -in. 'Registered Users' are people who have registered for the -site.

    +the OpenACS bugtracker.

    'The Public' refers to users to the website who are not +logged in. 'Registered Users' are people who have +registered for the site.

    Setting Permissions on an OpenACS package
    Alex logo
    Prev Chapter 4. Configuring a new OpenACS Site Next

    Setting Permissions on an OpenACS package

    by Jade Rubick

    OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

    Setting Permission on an OpenACS package

    After you've installed and mounted your package, you can +

    Setting Permission on an OpenACS package

    After you've installed and mounted your package, you can configure each instance to act as you would like.

    This is done from the Applications page. Log in, go to the Admin or Control Panel, click on the subsite the application is in, and click on Applications. If you click on the 'Permissions' Index: openacs-4/packages/acs-core-docs/www/configuring-install-packages.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-install-packages.adp,v diff -u -N -r1.1.2.11 -r1.1.2.12 --- openacs-4/packages/acs-core-docs/www/configuring-install-packages.adp 21 Jun 2016 07:44:35 -0000 1.1.2.11 +++ openacs-4/packages/acs-core-docs/www/configuring-install-packages.adp 23 Jun 2016 08:32:45 -0000 1.1.2.12 @@ -17,25 +17,25 @@ OpenACS documentation staff.

    Installing OpenACS packages

    An OpenACS package extends your website and lets it do things it -wasn't able to do before. You can have a weblog, a forums, a +wasn't able to do before. You can have a weblog, a forums, a calendar, or even do sophisticated project-management via your -website.

    After you've installed OpenACS, you can congratulate yourself -for a job well done. Then, you'll probably want to install a couple -of packages.

    To install packages, you have to be an administrator on the -OpenACS webserver. Log in, and you'll see a link to Admin or the -Control Panel. Click on that, then click on 'Install software'. -Packages are sometimes also referred to as applications or -software.

    At this point, you'll need to determine whether or not you're -able to install from the repository, or whether you should install -from local files.

    Basically, if you have a local CVS repository, or have custom -code, you need to install from 'Local Files'. Otherwise, you can -install from the OpenACS repository

    If you want to install new packages, click on 'Install from -Repository' or 'Install from Local'. Select the package, and click -'Install checked applications'. The system will check to make sure -you have all necessary packages that the package you want depends -on. If you're installing from Local Files, and you are missing any -packages, you may have to add the packages your desired package -depends on: the section called +website.

    After you've installed OpenACS, you can congratulate +yourself for a job well done. Then, you'll probably want to +install a couple of packages.

    To install packages, you have to be an administrator on the +OpenACS webserver. Log in, and you'll see a link to Admin or +the Control Panel. Click on that, then click on 'Install +software'. Packages are sometimes also referred to as +applications or software.

    At this point, you'll need to determine whether or not +you're able to install from the repository, or whether you +should install from local files.

    Basically, if you have a local CVS repository, or have custom +code, you need to install from 'Local Files'. Otherwise, +you can install from the OpenACS repository

    If you want to install new packages, click on 'Install from +Repository' or 'Install from Local'. Select the +package, and click 'Install checked applications'. The +system will check to make sure you have all necessary packages that +the package you want depends on. If you're installing from +Local Files, and you are missing any packages, you may have to add +the packages your desired package depends on: the section called “Upgrading the OpenACS files”

    If you run into any errors at all, check your Index: openacs-4/packages/acs-core-docs/www/configuring-install-packages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-install-packages.html,v diff -u -N -r1.10.2.10 -r1.10.2.11 --- openacs-4/packages/acs-core-docs/www/configuring-install-packages.html 21 Jun 2016 07:44:35 -0000 1.10.2.10 +++ openacs-4/packages/acs-core-docs/www/configuring-install-packages.html 23 Jun 2016 08:32:45 -0000 1.10.2.11 @@ -3,23 +3,23 @@ OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

    Installing OpenACS packages

    An OpenACS package extends your website and lets it do - things it wasn't able to do before. You can have a weblog, a + things it wasn't able to do before. You can have a weblog, a forums, a calendar, or even do sophisticated project-management - via your website.

    After you've installed OpenACS, you can congratulate - yourself for a job well done. Then, you'll probably want to + via your website.

    After you've installed OpenACS, you can congratulate + yourself for a job well done. Then, you'll probably want to install a couple of packages.

    To install packages, you have to be an administrator on - the OpenACS webserver. Log in, and you'll see a link to Admin or + the OpenACS webserver. Log in, and you'll see a link to Admin or the Control Panel. Click on that, then click on 'Install software'. Packages are sometimes also referred to as - applications or software.

    At this point, you'll need to determine whether or not - you're able to install from the repository, or whether you + applications or software.

    At this point, you'll need to determine whether or not + you're able to install from the repository, or whether you should install from local files.

    Basically, if you have a local CVS repository, or have custom code, you need to install from 'Local Files'. Otherwise, you can install from the OpenACS repository

    If you want to install new packages, click on 'Install from Repository' or 'Install from Local'. Select the package, and click 'Install checked applications'. The system will check to make sure you have all necessary packages that the package - you want depends on. If you're installing from Local Files, and + you want depends on. If you're installing from Local Files, and you are missing any packages, you may have to add the packages your desired package depends on: the section called “Upgrading the OpenACS files” Index: openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.adp,v diff -u -N -r1.1.2.10 -r1.1.2.11 --- openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.adp 21 Jun 2016 07:44:35 -0000 1.1.2.10 +++ openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.adp 23 Jun 2016 08:32:45 -0000 1.1.2.11 @@ -16,17 +16,19 @@ OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

    -Mounting OpenACS packages

    After you've installed your packages, you have to 'mount' them -in order to make them appear on your website.

    Make sure you are logged in, and then click on the 'Admin' or -'Control Panel' link to get to the Site-Wide Administration page -(at /acs-admin). Click on the subsite you'd like the application to -be available at.

    Subsites are a way of dividing your website into logical chunks. +Mounting OpenACS packages

    After you've installed your packages, you have to +'mount' them in order to make them appear on your +website.

    Make sure you are logged in, and then click on the +'Admin' or 'Control Panel' link to get to the +Site-Wide Administration page (at /acs-admin). Click on the subsite +you'd like the application to be available at.

    Subsites are a way of dividing your website into logical chunks. Often they represent different groups of users, or parts of an -organization.

    Now click on 'Applications' (applications are the same thing as -packages). You'll see a list of Applications and the URLs that each -is located at. To mount a new application, you click on 'Add -application', enter the Application, title (application name), and -URL (URL folder name), and you're done.

    Test it out now. The URL is based on a combination of the +organization.

    Now click on 'Applications' (applications are the same +thing as packages). You'll see a list of Applications and the +URLs that each is located at. To mount a new application, you click +on 'Add application', enter the Application, title +(application name), and URL (URL folder name), and you're +done.

    Test it out now. The URL is based on a combination of the subsite URL and the application URL. So if you installed a package in the Main Subsite at the URL calendar, it will be available at http://www.yoursite.com/calendar. If you installed it at a subsite Index: openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.html,v diff -u -N -r1.10.2.10 -r1.10.2.11 --- openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.html 21 Jun 2016 07:44:35 -0000 1.10.2.10 +++ openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.html 23 Jun 2016 08:32:45 -0000 1.10.2.11 @@ -2,17 +2,17 @@ Mounting OpenACS packages

    Alex logo
    Prev Chapter 4. Configuring a new OpenACS Site Next

    Mounting OpenACS packages

    by Jade Rubick

    OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

    Mounting OpenACS packages

    After you've installed your packages, you have to 'mount' +

    Mounting OpenACS packages

    After you've installed your packages, you have to 'mount' them in order to make them appear on your website.

    Make sure you are logged in, and then click on the 'Admin' or 'Control Panel' link to get to the Site-Wide - Administration page (at /acs-admin). Click on the subsite you'd + Administration page (at /acs-admin). Click on the subsite you'd like the application to be available at.

    Subsites are a way of dividing your website into logical chunks. Often they represent different groups of users, or parts of an organization.

    Now click on 'Applications' (applications are the same - thing as packages). You'll see a list of Applications and the + thing as packages). You'll see a list of Applications and the URLs that each is located at. To mount a new application, you click on 'Add application', enter the Application, title - (application name), and URL (URL folder name), and you're + (application name), and URL (URL folder name), and you're done.

    Test it out now. The URL is based on a combination of the subsite URL and the application URL. So if you installed a package in the Main Subsite at the URL calendar, it will be Index: openacs-4/packages/acs-core-docs/www/configuring-new-site.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-new-site.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-core-docs/www/configuring-new-site.adp 9 Jun 2016 13:03:11 -0000 1.1.2.2 +++ openacs-4/packages/acs-core-docs/www/configuring-new-site.adp 23 Jun 2016 08:32:45 -0000 1.1.2.3 @@ -7,7 +7,7 @@

    Index: openacs-4/packages/acs-core-docs/www/configuring-new-site.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-new-site.html,v diff -u -N -r1.15.2.1 -r1.15.2.2 --- openacs-4/packages/acs-core-docs/www/configuring-new-site.html 9 Jun 2016 08:44:49 -0000 1.15.2.1 +++ openacs-4/packages/acs-core-docs/www/configuring-new-site.html 23 Jun 2016 08:32:45 -0000 1.15.2.2 @@ -1,5 +1,5 @@ -Chapter 4. Configuring a new OpenACS Site
    Alex logo
    Prev Part II. Administrator's Guide Next

    Chapter 4. Configuring a new OpenACS Site

    Table of Contents

    Installing OpenACS packages
    Mounting OpenACS packages
    Configuring an OpenACS package
    Setting Permissions on an OpenACS package
    How Do I?

    by Joel Aufrecht

    +Chapter 4. Configuring a new OpenACS Site
    Alex logo
    Prev Part II. Administrator's Guide Next

    Chapter 4. Configuring a new OpenACS Site

    Table of Contents

    Installing OpenACS packages
    Mounting OpenACS packages
    Configuring an OpenACS package
    Setting Permissions on an OpenACS package
    How Do I?

    by Joel Aufrecht

    OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

    In this chapter, Configuring refers to making changes to a new OpenACS site through the web interface. In crude terms, these changes happen in the database, and are upgrade-safe. Customizing refers to changes that touch the file system, and require some planning if easy upgradability is to be maintained.

    Prev Home Next
    OpenACS Installation Guide for Mac OS X Up Installing OpenACS packages
    docs@openacs.org
    View comments on this page at openacs.org
    Index: openacs-4/packages/acs-core-docs/www/credits.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/credits.adp,v diff -u -N -r1.1.2.4 -r1.1.2.5 --- openacs-4/packages/acs-core-docs/www/credits.adp 9 Jun 2016 13:03:11 -0000 1.1.2.4 +++ openacs-4/packages/acs-core-docs/www/credits.adp 23 Jun 2016 08:32:45 -0000 1.1.2.5 @@ -5,7 +5,7 @@

    @@ -25,7 +25,7 @@ this guide from many sources of information.

    Joel Aufrecht updated the document starting in March 2003.

    Acknowledgments for versions of the above documents go (in no particular order) to Bryan Quinn, Adam Farkas, Brian Stein, Doug Hoffman, Ravi Jasuja, Hiro Iwashima, Ryan Lee, Jonathan Goler, @@ -44,8 +44,8 @@ Malte Sussdorff, Stan Kaufman and Pascal Scheffers.

    All questions and comments regarding this guide should be posted on -the OpenACS forums.

    ($‌Id: credits.xml,v 1.12 2006/07/17 05:38:37 -torbenb Exp $)
    +the OpenACS forums.

    ($‌Id: credits.html,v 1.46.2.10 2016/06/21 +07:44:35 gustafn Exp $)

    -Appendix C. Credits
    Alex logo
    Prev Part II. Administrator's Guide Next

    Appendix C. Credits

    Table of Contents

    Where did this document come from?
    Linux Install Guides
    Security Information
    Resources

    By Vinod Kurup

    +Appendix C. Credits
    Alex logo
    Prev Part II. Administrator's Guide Next

    Appendix C. Credits

    Table of Contents

    Where did this document come from?
    Linux Install Guides
    Security Information
    Resources

    By Vinod Kurup

    OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

    Vinod Kurup put @@ -8,7 +8,7 @@ updated the document starting in March 2003.

    • OpenACS 3.x Installation Guide

    • - Gilbert Wong's FreeBSD + Gilbert Wong's FreeBSD installation guide

    • My own Brief OpenACS4 Index: openacs-4/packages/acs-core-docs/www/cvs-guidelines.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/cvs-guidelines.adp,v diff -u -N -r1.1.2.12 -r1.1.2.13 --- openacs-4/packages/acs-core-docs/www/cvs-guidelines.adp 21 Jun 2016 07:44:35 -0000 1.1.2.12 +++ openacs-4/packages/acs-core-docs/www/cvs-guidelines.adp 23 Jun 2016 08:32:45 -0000 1.1.2.13 @@ -10,8 +10,8 @@

      CVS Guidelines

      -
      ($‌Id: cvs.xml,v 1.6 2006/07/17 05:38:37 torbenb -Exp $)

      By Joel Aufrecht with input from Jeff Davis, Branimir Dolicki, +

      ($‌Id: cvs-guidelines.html,v 1.10.2.10 +2016/06/21 07:44:35 gustafn Exp $)

      By Joel Aufrecht with input from Jeff Davis, Branimir Dolicki, and Jade Rubick.

      OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
      @@ -28,8 +28,8 @@ This will create a local checkout directory that uses cvs.openacs.org but does not specify the user. By default, it will use your local account name as the user, so if you are logged in as -"foobar" it will try to check out and commit as if you had -specified :ext:foobar\@cvs.openacs.org:/cvsroot. The +"foobar" it will try to check out and commit as if you +had specified :ext:foobar\@cvs.openacs.org:/cvsroot. The advantage of not specifying a user in the checkout command is that other users can work in the directory using their own accounts.

      OpenACS.org supports non-anonymous cvs access only over ssh, so you must have CVS_RSH=ssh in @@ -54,7 +54,7 @@

      Administrator Note: These are the steps to grant CVS commit rights to a user:

      1. -

        Create the user's account. On cvs.openacs.org:

        sudo bash
+
        Create the user's account. On cvs.openacs.org:
        sudo bash
 /usr/sbin/useradd -c "Real Name" -G cvs -p passwdusername
 /usr/sbin/usermod -G cvs,usernameusername
 
        
@@ -193,7 +193,8 @@
 applies only to the calendar package. All non-core, non-dotlrn
 packages should have a tag of this style, based on the package
 name. Many packages have not been re-released since the new naming
-convention was adopted and so don't have a tag of this type.
      2. +convention was adopted and so don't have a tag of this +type.

      3. openacs-x-y-compat tags point to the most recent released version of OpenACS @@ -346,15 +347,17 @@ script. E.g., the last planned upgrade script for a package previously in dev 1 would be upgrade-2.0.0d1-2.0.0b1.sql, not upgrade-2.0.0d1-2.0.0.sql. Note that using rc1 instead of b1 would -be nice, because that's the convention with release codes in cvs, -but the package manager doesn't support rc tags.

        +be nice, because that's the convention with release codes in +cvs, but the package manager doesn't support rc +tags.

      4. Database upgrade scripts should never go to the release version, e.g., should always have a letter suffix such as d1 or b1.

      5. CVS commit messages should be intelligible in the context of Changelogs. They should not refer to the files or versions.

      6. CVS commit messages and code comments should refer to bug, tip, -or patch number if appropriate, in the format "resolves bug 11", -"resolves bugs 11, resolves bug 22". "implements tip 42", -"implements tip 42, implements tip 50", "applies patch 456 by User -Name", "applies patch 456 by User Name, applies patch 523 by +or patch number if appropriate, in the format "resolves bug +11", "resolves bugs 11, resolves bug 22". +"implements tip 42", "implements tip 42, implements +tip 50", "applies patch 456 by User Name", +"applies patch 456 by User Name, applies patch 523 by ...".

    • @@ -381,10 +384,10 @@

      Tags

      1. When a package is released in final form, the developer shall -tag it "packagename-x-y-z-final" and "openacs-x-y-compat". x-y -should correspond to the current branch. If the package is -compatible with several different core versions, several compat -tags should be applied.

        Reason 1: The packagename tag is a +tag it "packagename-x-y-z-final" and +"openacs-x-y-compat". x-y should correspond to the +current branch. If the package is compatible with several different +core versions, several compat tags should be applied.

        Reason 1: The packagename tag is a permanent, static tag that allows for future comparison. The compat tag is a floating tag which is used by the repository generator to determine the most recent released version of each package for each @@ -404,10 +407,11 @@ the fork and the OpenACS code so that patches can be generated.

        2. -

      For example, adding a new API function wouldn't require a TIP. -Changing an existing API function by adding an optional new flag -which defaults to no-effect wouldn't require a TIP. Added a new -mandatory flag to an existing function would require a TIP.

      +

    For example, adding a new API function wouldn't require a +TIP. Changing an existing API function by adding an optional new +flag which defaults to no-effect wouldn't require a TIP. Added +a new mandatory flag to an existing function would require a +TIP.

    @@ -429,15 +433,16 @@ making it invoke the new one.

  • Never rush to commit something. Before committing double check with cvs diff what exactly you are committing.

  • Always accompany a commit with a brief but informative comment. If your commit is related to bug number N and/or patch number P, -indicate this in the commit comment by including "bug N" and/or -"patch P". This allows us to link bugs and patches in the Bug -Tracker with changes to the source code. For example suppose you -are committing a patch that closes a missing HTML tag, then an -appropriate comment could be "Fixing bug 321 by applying patch 134. -Added missing h3 HTML close tag".

  • Commit one cohesive bug fix or feature change at a time. Don't -put a bunch of unrelated changes into one commit.

  • Before you throw out or change a piece of code that you don't -fully understand, use cvs annotate and cvs log on the file to see -who wrote the code and why. Consider contacting the author.

  • Test your change before committing. Use the OpenACS package +indicate this in the commit comment by including "bug N" +and/or "patch P". This allows us to link bugs and patches +in the Bug Tracker with changes to the source code. For example +suppose you are committing a patch that closes a missing HTML tag, +then an appropriate comment could be "Fixing bug 321 by +applying patch 134. Added missing h3 HTML close tag".

  • Commit one cohesive bug fix or feature change at a time. +Don't put a bunch of unrelated changes into one commit.

  • Before you throw out or change a piece of code that you +don't fully understand, use cvs annotate and cvs log on the +file to see who wrote the code and why. Consider contacting the +author.

  • Test your change before committing. Use the OpenACS package acs-automated-testing to test Tcl procedures and the tool Tclwebtest to test pages

  • Keep code simple, adhere to conventions, and use comments liberally.

  • In general, treat the code with respect, at the same time, never stop questioning what you see. The code can always be improved, @@ -448,12 +453,12 @@

    • Additional Resources for CVS

    Index: openacs-4/packages/acs-core-docs/www/cvs-guidelines.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/cvs-guidelines.html,v diff -u -N -r1.10.2.10 -r1.10.2.11 --- openacs-4/packages/acs-core-docs/www/cvs-guidelines.html 21 Jun 2016 07:44:35 -0000 1.10.2.10 +++ openacs-4/packages/acs-core-docs/www/cvs-guidelines.html 23 Jun 2016 08:32:45 -0000 1.10.2.11 @@ -44,7 +44,7 @@ ~/.cvsrc with the contents: 

    cvs -z6
 cvs -q

    -z6 speeds up cvs access over the network quite a bit by enabling compressed - connection by default. -q suppresses some verbose output from commands. For example, it makes the output of cvs up much easier to read.

    Administrator Note: These are the steps to grant CVS commit rights to a user:

    1. Create the user's account. On cvs.openacs.org:

      sudo bash
+        connection by default.  -q suppresses some verbose output from commands.  For example, it makes the output of cvs up much easier to read.
      Administrator Note: These are the steps to grant CVS commit rights to a user:
      1. Create the user's account.  On cvs.openacs.org:
        sudo bash
 /usr/sbin/useradd -c "Real Name" -G cvs -p passwd username
 /usr/sbin/usermod -G cvs,username username
           
      2. Grant cvs access to the user account.  On any machine, in a temporary directory:
        cvs -d :ext:cvs.openacs.org:/cvsroot co CVSROOT
@@ -131,7 +131,7 @@
                   calendar package. All non-core, non-dotlrn packages should have a
                   tag of this style, based on the package name. Many packages have
                   not been re-released since the new naming convention was adopted
-                  and so don't have a tag of this type.
+                  and so don't have a tag of this type.
                 
      3. openacs-x-y-compat tags point to the most recent released version of OpenACS X.Y.
             It is similar to openacs-x-y-z-compat, except that it will
             always get the most recent dot-release of Core and the
@@ -229,9 +229,9 @@
         be addressed with another upgrade script. E.g., the last planned
         upgrade script for a package previously in dev 1 would be
         upgrade-2.0.0d1-2.0.0b1.sql, not upgrade-2.0.0d1-2.0.0.sql. Note
-        that using rc1 instead of b1 would be nice, because that's the
+        that using rc1 instead of b1 would be nice, because that's the
         convention with release codes in cvs, but the package manager
-        doesn't support rc tags.
+        doesn't support rc tags.
       
      4. 
               Database upgrade scripts should never go to the release
               version, e.g., should always have a letter suffix such as d1 or
@@ -310,9 +310,9 @@
         OpenACS code so that patches can be generated.
         
       
      
-          For example, adding a new API function wouldn't require a
+          For example, adding a new API function wouldn't require a
           TIP. Changing an existing API function by adding an optional new
-          flag which defaults to no-effect wouldn't require a TIP. Added a
+          flag which defaults to no-effect wouldn't require a TIP. Added a
           new mandatory flag to an existing function would require a
           TIP.

    @@ -366,10 +366,10 @@ Added missing h3 HTML close tag".

  • Commit one cohesive bug fix or feature change at a time. - Don't put a bunch of unrelated changes into one commit. + Don't put a bunch of unrelated changes into one commit.

  • Before you throw out or change a piece of code that you - don't fully understand, use cvs annotate and cvs log on the file to + don't fully understand, use cvs annotate and cvs log on the file to see who wrote the code and why. Consider contacting the author.

  • @@ -395,7 +395,7 @@ OpenACS cvs web and - Jeff's cvs + Jeff's cvs browser are useful tools in understanding what is @@ -416,7 +416,7 @@

  • file locking etc. with cvs

  • - Piskorski's cvs refs + Piskorski's cvs refs

  • backup with cvs

  • Index: openacs-4/packages/acs-core-docs/www/cvs-tips.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/cvs-tips.adp,v diff -u -N -r1.1.2.10 -r1.1.2.11 --- openacs-4/packages/acs-core-docs/www/cvs-tips.adp 21 Jun 2016 07:44:35 -0000 1.1.2.10 +++ openacs-4/packages/acs-core-docs/www/cvs-tips.adp 23 Jun 2016 08:32:45 -0000 1.1.2.11 @@ -18,9 +18,9 @@

    OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

    • -Add -the Service to CVS - OPTIONAL. These steps -take an existing OpenACS directory and add it to a CVS +Add the Service to CVS - +OPTIONAL. These steps take +an existing OpenACS directory and add it to a CVS repository.

    1. Create and set permissions on a subdirectory in the local cvs @@ -56,10 +56,10 @@ command, $OPENACS_SERVICE_NAME refers to the cvs repository to use; it uses the CVSROOT plus this string, i.e. /cvsroot/$OPENACS_SERVICE_NAME -. "OpenACS" -is the vendor tag, and "oacs-5-9-0-final" is the release tag. These -tags will be useful in upgrading and branching. -m sets the version -comment.

      +.
+"OpenACS" is the vendor tag, and
+"oacs-5-9-0-final" is the release tag. These tags will be
+useful in upgrading and branching. -m sets the version comment.
       [root root]# su - $OPENACS_SERVICE_NAME
 
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME
@@ -113,7 +113,7 @@
    -Appendix D. Using CVS with an OpenACS Site
    Alex logo
    Prev Part III. For OpenACS Package Developers Next

    Appendix D. Using CVS with an OpenACS Site

    By Joel Aufrecht

    +Appendix D. Using CVS with an OpenACS Site
    Alex logo
    Prev Part III. For OpenACS Package Developers Next

    Appendix D. Using CVS with an OpenACS Site

    By Joel Aufrecht

    OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

    Add the Service to CVS - OPTIONAL. These steps take an existing OpenACS directory and add @@ -60,4 +60,4 @@ su - $OPENACS_SERVICE_NAME cd /var/lib/aolserver cvs checkout $OPENACS_SERVICE_NAME -exit

  • If the service starts correctly, come back and remove the temporary copy of the uploaded files.

    • Prev Home Next
    Translator's Guide Up Part IV. For OpenACS Platform Developers
    docs@openacs.org
    View comments on this page at openacs.org
    +exit

  • If the service starts correctly, come back and remove the temporary copy of the uploaded files.

    • Prev Home Next
    Translator's Guide Up Part IV. For OpenACS Platform Developers
    docs@openacs.org
    View comments on this page at openacs.org
    Index: openacs-4/packages/acs-core-docs/www/database-management.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/database-management.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-core-docs/www/database-management.adp 9 Jun 2016 13:03:11 -0000 1.1.2.2 +++ openacs-4/packages/acs-core-docs/www/database-management.adp 23 Jun 2016 08:32:45 -0000 1.1.2.3 @@ -7,7 +7,7 @@

    Index: openacs-4/packages/acs-core-docs/www/database-management.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/database-management.html,v diff -u -N -r1.31.2.1 -r1.31.2.2 --- openacs-4/packages/acs-core-docs/www/database-management.html 9 Jun 2016 08:44:49 -0000 1.31.2.1 +++ openacs-4/packages/acs-core-docs/www/database-management.html 23 Jun 2016 08:32:45 -0000 1.31.2.2 @@ -1,5 +1,5 @@ -Chapter 7. Database Management
    Alex logo
    Prev Part II. Administrator's Guide Next

    Chapter 7. Database Management

    Table of Contents

    Running a PostgreSQL database on another server
    Deleting a tablespace
    Vacuum Postgres nightly

    By Joel Aufrecht

    +Chapter 7. Database Management
    Alex logo
    Prev Part II. Administrator's Guide Next

    Chapter 7. Database Management

    Table of Contents

    Running a PostgreSQL database on another server
    Deleting a tablespace
    Vacuum Postgres nightly

    By Joel Aufrecht

    OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
    Prev Home Next
    Diagnosing Performance Problems Up Running a PostgreSQL database on another server
    docs@openacs.org
    View comments on this page at openacs.org
    Index: openacs-4/packages/acs-core-docs/www/db-api-detailed.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/db-api-detailed.adp,v diff -u -N -r1.1.2.5 -r1.1.2.6 --- openacs-4/packages/acs-core-docs/www/db-api-detailed.adp 9 Jun 2016 08:44:49 -0000 1.1.2.5 +++ openacs-4/packages/acs-core-docs/www/db-api-detailed.adp 23 Jun 2016 08:32:45 -0000 1.1.2.6 @@ -17,27 +17,27 @@

  • Tcl procedures: /packages/acs-kernel/10-database-procs.tcl

  • Tcl initialization: /packages/acs-kernel/database-init.tcl

    • -The Big Picture

    One of OpenACS's great strengths is that code written for it is -very close to the database. It is very easy to interact with the +The Big Picture

    One of OpenACS's great strengths is that code written for it +is very close to the database. It is very easy to interact with the database from anywhere within OpenACS. Our goal is to develop a coherent API for database access which makes this even easier.

    There were four significant problems with the way OpenACS previously used the database (i.e., directly through the ns_db interface):

    1. Handle management. We required code to pass database handles around, and for routines -which needed to perform database access but didn't receive a +which needed to perform database access but didn't receive a database handle as input, it was difficult to know from which of -the three "magic pools" (main, subquery, and log) to allocate a new -handle.

    2. +the three "magic pools" (main, subquery, and log) to +allocate a new handle.

    3. Nested transactions. In our Oracle driver, begin transaction really means "turn auto-commit mode off" and end -transaction means "commit the current transaction and turn -auto-commit mode on." Thus if transactional code needed to call a -routine which needed to operate transactionally, the semantics were -non-obvious. Consider:

      +transaction means "commit the current transaction and
+turn auto-commit mode on." Thus if transactional code needed
+to call a routine which needed to operate transactionally, the
+semantics were non-obvious. Consider:
       
 proc foo { db args } {
     db_transaction {
@@ -56,16 +56,16 @@
 end transaction in foo would actually cause a commit, and
 greeble #50 would later be inserted in auto-commit mode. This could
 cause subtle bugs: e.g., in the case that the insert for greeble
-#50 failed, part of the "transaction" would have already have been
-committed!. This is not a good thing.
      
+#50 failed, part of the "transaction" would have already
+have been committed!. This is not a good thing.

    4. Unorthodox use of variables. The standard mechanism for mapping column values into variables involved the use of the set_variables_after_query routine, which relies on an uplevel variable named selection (likewise for set_variables_after_subquery and subselection).

    5. Hard-coded reliance on -Oracle. It's difficult to write code supporting +Oracle. It's difficult to write code supporting various different databases (dynamically using the appropriate dialect based on the type of database being used, e.g., using DECODE on Oracle and @@ -80,17 +80,17 @@ the OpenACS Core, this API will translate logical statement names into actual SQL, based on the type of database in use. (To smooth the learning curve, we provide a facility for writing SQL inline -for a "default SQL dialect", which we assume to be Oracle for -now.)

      To be clear, SQL abstraction is not fully implemented in OpenACS 3.3.1. +for a "default SQL dialect", which we assume to be Oracle +for now.)

      To be clear, SQL abstraction is not fully implemented in OpenACS 3.3.1. The statement names supplied to each call are not used by the API -at all. The API's design for SQL abstraction is in fact incomplete; -unresolved issues include:

        +at all. The API's design for SQL abstraction is in fact +incomplete; unresolved issues include:

        • how to add WHERE clause criteria dynamically

        • how to build a dynamic ORDER -BY clause (Ben Adida has a proposed solution for this)

        • how to define a statement's formal interface (i.e., what bind -variables it expects, what columns its SELECT clause must contain if it's a query) -without actually implementing the statement in a specific SQL -dialect

          • +BY clause (Ben Adida has a proposed solution for this)

        • how to define a statement's formal interface (i.e., what +bind variables it expects, what columns its SELECT clause must contain if it's a +query) without actually implementing the statement in a specific +SQL dialect

        So why is the incremental change of adding statement naming to the API worth the effort? It is worth the effort because we know that giving each SQL statement a logical name will be required by @@ -104,22 +104,22 @@ set_variables_after_query

    set_variables_after_query is -gone! (Well, it's still there, but you'll never need to use it.) -The new API routines set local variables automatically. For +gone! (Well, it's still there, but you'll never need to use +it.) The new API routines set local variables automatically. For instance:

     
 db_1row select_names "select first_names, last_name from users where user_id = [ad_conn user_id]"
 doc_body_append "Hello, $first_names $last_name!"

    Like ns_db 1row, this will -bomb if the query doesn't return any rows (no such user exists). If -this isn't what you want, you can write:

    +bomb if the query doesn't return any rows (no such user
+exists). If this isn't what you want, you can write:
     
 if { [db_0or1row select_names "select first_names, last_name from users where user_id = [ad_conn user_id]"] } {
     doc_body_append "Hello, $first_names $last_name!"
 } else {
     # Executed if the query returns no rows.
-    doc_body_append "There's no such user!"
+    doc_body_append "There's no such user!"
 }
 
 
    Selecting a bunch of rows is a lot prettier now:
    @@ -128,16 +128,16 @@
      doc_body_append "Say hi to $first_names $last_name for me!<br>"
 }
 
-
    That's right, db_foreach is
-now like ns_db select plus a
+

    That's right, db_foreach +is now like ns_db select plus a while loop plus set_variables_after_query plus an if statement (containing code to be executed if no rows are returned).

     
 db_foreach select_names "select first_names, last_name from users where last_name like 'S%'" {
      doc_body_append "Say hi to $first_names $last_name for me!<br>"
 } if_no_rows {
-     doc_body_append "There aren't any users with last names beginnings with S!"
+     doc_body_append "There aren't any users with last names beginnings with S!"
 }
    @@ -153,7 +153,7 @@ doc_body_append "<li>User $first_names $last_name\n<ul>" db_foreach select_groups "select group_id from user_group_map where user_id = $user_id" { - # There's a selection in progress, so we allocated a database handle + # There's a selection in progress, so we allocated a database handle # from the subquery pool for this selection. doc_body_append "<li>Member of group #$group_id.\n" } if_no_rows { @@ -164,11 +164,11 @@ doc_body_append "</ul>" db_release_unused_handles -

    A new handle isn't actually allocated and released for every +

    A new handle isn't actually allocated and released for every selection, of course - as a performance optimization, the API keeps old handles around until db_release_unused_handles is invoked (or the script terminates).

    Note that there is no analogue to ns_db gethandle - the handle is always -automatically allocated the first time it's needed.

    +automatically allocated the first time it's needed.

    Bind Variables

    Introduction

    Most SQL statements require that the code invoking the statement @@ -179,19 +179,19 @@ delete from wp_presentations where presentation_id = some_presentation_id

    where some_presentation_id is a number which is a valid presentation ID of the presentation I want -to delete. It's easy to write code handling situations like this -since SQL statements can include bind -variables, which represent placeholders for actual -data. A bind variable is specified as a colon followed by an -identifier, so the statement above can be coded as:

    +to delete. It's easy to write code handling situations like
+this since SQL statements can include bind variables, which represent
+placeholders for actual data. A bind variable is specified as a
+colon followed by an identifier, so the statement above can be
+coded as:
     
 db_dml presentation_delete {
     delete from wp_presentations where presentation_id = :some_presentation_id
 }
 
 
    When this SQL statement is invoked, the value for the bind
 variable :some_presentation_id
-is pulled from the Tcl variable $some_presentation_id (in the caller's
+is pulled from the Tcl variable $some_presentation_id (in the caller's
 environment). Note that bind variables are not limited to one per
 statement; you can use an arbitrary number, and each will pull from
 the correspondingly named Tcl variable. (Alternatively, you can
@@ -201,7 +201,7 @@
 value for a bind variable, or to use db_quote to escape single-quotes contained
 in the value. The following works fine, despite the apostrophe:
     
-set exclamation "That's all, folks!"
+set exclamation "That's all, folks!"
 db_dml exclamation_insert { insert into exclamations(exclamation) values(:exclamation) }
 
 
    Note that you can use a bind variable in a SQL statement only
@@ -225,20 +225,22 @@
 to $some_presentation_id to be
 interpolated in.) This will work, but consider the case where some
 devious user causes some_presentation_id to be set to something
-like '3 or 1 = 1', which would
-result in the following statement being executed:
    +like '3 or 1 = 1',
+which would result in the following statement being executed:
     
 delete from wp_presentations where presentation_id = 3 or 1 = 1
 
 
    This deletes every presentation in the database! Using bind
 variables eliminates this gaping security hole: since bind variable
 values are taken literally. Oracle will attempt to delete
-presentations whose presentation ID is literally '3 or 1 = 1' (i.e., no presentations, since
-'3 or 1 = 1' can't possibly be
-a valid integer primary key for wp_presentations. In general, since Oracle
-always considers the values of bind variables to be literals, it
-becomes more difficult for users to perform URL surgery to trick
-scripts into running dangerous queries and DML.
    Usage
    Every db_* command accepting
+presentations whose presentation ID is literally '3 or 1 = 1' (i.e., no
+presentations, since '3 or 1 =
+1' can't possibly be a valid integer primary key for
+wp_presentations. In general,
+since Oracle always considers the values of bind variables to be
+literals, it becomes more difficult for users to perform URL
+surgery to trick scripts into running dangerous queries and
+DML.
    Usage
    Every db_* command accepting
 a SQL command as an argument supports bind variables. You can
 either
      
 
    • specify the -bind switch to
@@ -304,11 +306,13 @@
 into null. (This coercion does
 not occur in the
 WHERE clause of a query, i.e.
-col = '' and col is null are not equivalent.)
      As a result, when using bind variables, the only way to make
+col = '' and
+col is null are not
+equivalent.)
      As a result, when using bind variables, the only way to make
 Oracle set a column value to null is to set the corresponding bind
 variable to the empty string, since a bind variable whose value is
-the string "null" will be interpreted as the literal string
-"null".
      These Oracle quirks complicate the process of writing clear and
+the string "null" will be interpreted as the literal
+string "null".
      These Oracle quirks complicate the process of writing clear and
 abstract DML difficult. Here is an example that illustrates
 why:
       
@@ -387,8 +391,8 @@
 
    
 
    
 API
    Note that you never have to use ns_db anymore (including ns_db gethandle)! Just start doing stuff,
-and (if you want) call db_release_unused_handles when you're done
-as a hint to release the database handle.
    
+and (if you want) call db_release_unused_handles when you're
+done as a hint to release the database handle.
    
 
    
 db_null
    
 
    db_null
    Returns a value which can be used in a bind variable to
@@ -426,7 +430,7 @@
 1 row.
    Example:
     
 db_1row select_foo "select foo, bar from greeble where greeble_id = $greeble_id"
-# Bombs if there's no such greeble!
+# Bombs if there's no such greeble!
 # Now $foo and $bar are set.
 
 
    
@@ -443,7 +447,7 @@
 
     db_stringstatement-namesql [ -default default ] [ -bind bind_set_id | -bind bind_value_list ]
 
    Returns the first column of the result of SQL query sql.
-If sql doesn't return a row,
+If sql doesn't return a row,
 returns default (or throws an error if
 default is unspecified).
 Analogous to database_to_tcl_string and database_to_tcl_string_or_null.
    
@@ -461,16 +465,16 @@
 db_liststatement-namesql [ -bind bind_set_id | -bind bind_value_list ]
 
    Returns a Tcl list of the values in the first column of the
 result of SQL query sql. If sql
-doesn't return any rows, returns an empty list. Analogous to
+doesn't return any rows, returns an empty list. Analogous to
 database_to_tcl_list.
    
 
    
 db_list_of_lists
    
 
     db_list_of_listsstatement-namesql [ -bind bind_set_id | -bind bind_value_list ]
 
    Returns a Tcl list, each element of which is a list of all
 column values in a row of the result of SQL query sql.
-If sql doesn't return any rows,
-returns an empty list. (Analogous to database_to_tcl_list_list.)
    
+If sql doesn't return any
+rows, returns an empty list. (Analogous to database_to_tcl_list_list.)
    
 
    
 db_list_of_ns_sets
    
 
    @@ -529,8 +533,8 @@
 db_transactioncode_block [ on_error { code_block } ]
 
    Executes code_block transactionally.
 Nested transactions are supported (end
-transaction is transparently ns_db dml'ed when the outermost transaction
-completes). The db_abort_transaction command can be used to
+transaction is transparently ns_db dml'ed when the outermost
+transaction completes). The db_abort_transaction command can be used to
 abort all levels of transactions. It is possible to specify an
 optional on_error code block
 that will be executed if some code in code_block throws an exception. The
@@ -570,8 +574,8 @@
 db_abort_transaction
    
 
    db_abort_transaction
    Aborts all levels of a transaction. That is if this is called
 within several nested transactions, all of them are terminated. Use
-this instead of db_dml "abort" "abort
-transaction".
    
+this instead of db_dml
+"abort" "abort transaction".
    
 
    
 db_multirow
    
 
    @@ -589,10 +593,10 @@
 var_name:columns to a list of
 column names.
    Each row also has a column, rownum, automatically added and set
 to the row number, starting with 1. Note that this will override
-any column in the SQL statement named 'rownum', also if you're
-using the Oracle rownum pseudo-column.
    If the -local is passed, the
+any column in the SQL statement named 'rownum', also if
+you're using the Oracle rownum pseudo-column.
    If the -local is passed, the
 variables defined by db_multirow will be set locally (useful if
-you're compiling dynamic templates in a function or similar
+you're compiling dynamic templates in a function or similar
 situations).
    You may supply a code block, which will be executed for each row
 in the loop. This is very useful if you need to make computations
 that are better done in Tcl than in SQL, for example using
@@ -602,13 +606,13 @@
 copied back into the multirow.
    You may also add additional, computed columns to the multirow,
 using the -extend { col_1col_2 ... } switch. This is
 useful for things like constructing a URL for the object retrieved
-by the query.
    If you're constructing your multirow through multiple queries
-with the same set of columns, but with different rows, you can use
-the -append switch. This causes
-the rows returned by this query to be appended to the rows already
-in the multirow, instead of starting a clean multirow, as is the
-normal behavior. The columns must match the columns in the original
-multirow, or an error will be thrown.
    Your code block may call continue in order to skip a row and not
+by the query.
    If you're constructing your multirow through multiple
+queries with the same set of columns, but with different rows, you
+can use the -append switch.
+This causes the rows returned by this query to be appended to the
+rows already in the multirow, instead of starting a clean multirow,
+as is the normal behavior. The columns must match the columns in
+the original multirow, or an error will be thrown.
    Your code block may call continue in order to skip a row and not
 include it in the multirow. Or you can call break to skip this row and quit
 looping.
    Notice the nonstandard numbering (everything else in Tcl starts
 at 0); the reason is that the graphics designer, a non programmer,
@@ -630,7 +634,7 @@
 db_with_handlevarcode_block
 
    Places a database handle into the variable var
 and executes code_block. This is useful when
-you don't want to have to use the new API (db_foreach, db_1row, etc.), but need to use database
+you don't want to have to use the new API (db_foreach, db_1row, etc.), but need to use database
 handles explicitly.
    Example:
     
 proc lookup_the_foo { foo } {
@@ -640,7 +644,7 @@
 }
 
 db_with_handle db {
-    # Now there's a database handle in $db.
+    # Now there's a database handle in $db.
     set selection [ns_db select $db "select foo from bar"]
     while { [ns_db getrow $db $selection] } {
         set_variables_after_query
@@ -671,9 +675,9 @@
 db_package_supports_rdbms_p db_type_list
                 
 
    Returns 1 if db_type_list contains the current RDMBS type. A
-package intended to run with a given RDBMS must note this in it's
-package info file regardless of whether or not it actually uses the
-database.
    
+package intended to run with a given RDBMS must note this in
+it's package info file regardless of whether or not it actually
+uses the database.
    
 
    
 db_legacy_package_p
    
 
    @@ -694,13 +698,13 @@
 
    db_known_database_types
    Returns a list of three-element lists describing the database
 engines known to OpenACS. Each sublist contains the internal
 database name (used in file paths, etc), the driver name, and a
-"pretty name" to be used in selection forms displayed to the
-user.
    The nsv containing the list is initialized by the bootstrap
+"pretty name" to be used in selection forms displayed to
+the user.
    The nsv containing the list is initialized by the bootstrap
 script and should never be referenced directly by user code.
 Returns the current rdbms type and version.
    
 
    
-
    ($‌Id: db-api.xml,v 1.11.2.1 2016/01/02 21:55:21 -gustafn Exp $)
    +
    ($‌Id: db-api-detailed.html,v 1.48.2.11 +2016/06/21 07:44:35 gustafn Exp $)

    There were four significant problems with the way OpenACS previously used the database (i.e., directly through the ns_db interface):

    1. Handle management. We required code to pass database handles around, and for routines which needed to perform database access but -didn't receive a database handle as input, it was difficult to know from +didn't receive a database handle as input, it was difficult to know from which of the three "magic pools" (main, subquery, and log) to allocate a new handle. @@ -50,7 +50,7 @@ set_variables_after_subquery and subselection). -

    2. Hard-coded reliance on Oracle. It's difficult to +

    3. Hard-coded reliance on Oracle. It's difficult to write code supporting various different databases (dynamically using the appropriate dialect based on the type of database being used, e.g., using DECODE on Oracle and CASE ... WHEN on @@ -68,9 +68,9 @@ 3.3.1. The statement names supplied to each call are not used by the API at all. The API's design for SQL abstraction is in fact incomplete; unresolved issues include:

      • how to add WHERE clause criteria dynamically

      • how to build a dynamic ORDER BY clause (Ben Adida has a -proposed solution for this)

      • how to define a statement's formal interface (i.e., what bind +proposed solution for this)

      • how to define a statement's formal interface (i.e., what bind variables it expects, what columns its SELECT clause must -contain if it's a query) without actually implementing the statement in a +contain if it's a query) without actually implementing the statement in a specific SQL dialect

      So why is the incremental change of adding statement naming to the API worth the effort? It is worth the effort because we know that giving each SQL @@ -79,25 +79,25 @@ advantage of the new support for bind variables will already require code that uses 3.3.0 version of the API to be updated.

    The Bell Tolls for set_variables_after_query

    -set_variables_after_query is gone! (Well, it's still there, -but you'll never need to use it.) The new API routines set local +set_variables_after_query is gone! (Well, it's still there, +but you'll never need to use it.) The new API routines set local variables automatically. For instance: 

     
 db_1row select_names "select first_names, last_name from users where user_id = [ad_conn user_id]"
 doc_body_append "Hello, $first_names $last_name!"

    -Like ns_db 1row, this will bomb if the query doesn't return -any rows (no such user exists). If this isn't what you want, you can +Like ns_db 1row, this will bomb if the query doesn't return +any rows (no such user exists). If this isn't what you want, you can write: 

     
 if { [db_0or1row select_names "select first_names, last_name from users where user_id = [ad_conn user_id]"] } {
     doc_body_append "Hello, $first_names $last_name!"
 } else {
     # Executed if the query returns no rows.
-    doc_body_append "There's no such user!"
+    doc_body_append "There's no such user!"
 }

    @@ -110,7 +110,7 @@ }

    -That's right, db_foreach is now like ns_db +That's right, db_foreach is now like ns_db select plus a while loop plus set_variables_after_query plus an if statement (containing code to be executed if no rows are returned). @@ -120,7 +120,7 @@ db_foreach select_names "select first_names, last_name from users where last_name like 'S%'" { doc_body_append "Say hi to $first_names $last_name for me!<br>" } if_no_rows { - doc_body_append "There aren't any users with last names beginnings with S!" + doc_body_append "There aren't any users with last names beginnings with S!" }

    Handle Management

    @@ -135,7 +135,7 @@ doc_body_append "<li>User $first_names $last_name\n<ul>" db_foreach select_groups "select group_id from user_group_map where user_id = $user_id" { - # There's a selection in progress, so we allocated a database handle + # There's a selection in progress, so we allocated a database handle # from the subquery pool for this selection. doc_body_append "<li>Member of group #$group_id.\n" } if_no_rows { @@ -147,12 +147,12 @@ db_release_unused_handles

    -A new handle isn't actually allocated and released for every selection, +A new handle isn't actually allocated and released for every selection, of course - as a performance optimization, the API keeps old handles around until db_release_unused_handles is invoked (or the script terminates).

    Note that there is no analogue to ns_db gethandle - the -handle is always automatically allocated the first time it's needed.

    Bind Variables

    Introduction

    +handle is always automatically allocated the first time it's needed.

    Bind Variables

    Introduction

    Most SQL statements require that the code invoking the statement pass along data associated with that statement, usually obtained from the user. For instance, in order to delete a WimpyPoint presentation, a Tcl script might @@ -163,7 +163,7 @@

    where some_presentation_id is a number which is a valid -presentation ID of the presentation I want to delete. It's easy to write +presentation ID of the presentation I want to delete. It's easy to write code handling situations like this since SQL statements can include bind variables, which represent placeholders for actual data. A bind variable is specified as a colon followed by an identifier, so @@ -177,7 +177,7 @@

    When this SQL statement is invoked, the value for the bind variable :some_presentation_id is pulled from the Tcl variable -$some_presentation_id (in the caller's environment). Note +$some_presentation_id (in the caller's environment). Note that bind variables are not limited to one per statement; you can use an arbitrary number, and each will pull from the correspondingly named Tcl variable. (Alternatively, you can also specify an list or ns_set @@ -187,7 +187,7 @@ variable, or to use db_quote to escape single-quotes contained in the value. The following works fine, despite the apostrophe:

     
-set exclamation "That's all, folks!"
+set exclamation "That's all, folks!"
 db_dml exclamation_insert { insert into exclamations(exclamation) values(:exclamation) }

    Note that you can use a bind variable in a SQL statement only where you @@ -223,7 +223,7 @@ eliminates this gaping security hole: since bind variable values are taken literally. Oracle will attempt to delete presentations whose presentation ID is literally '3 or 1 = 1' (i.e., no presentations, since -'3 or 1 = 1' can't possibly be a valid integer +'3 or 1 = 1' can't possibly be a valid integer primary key for wp_presentations. In general, since Oracle always considers the values of bind variables to be literals, it becomes more difficult for users to perform URL surgery to trick scripts into running @@ -377,7 +377,7 @@

    • first_names is Jon. last_name is Salz.

    • first_names is Lars. last_name is Pind.

    • first_names is Michael. last_name is Yoon.

    API

    Note that you never have to use ns_db anymore (including ns_db gethandle)! Just start doing stuff, and (if you want) call -db_release_unused_handles when you're done as a hint to +db_release_unused_handles when you're done as a hint to release the database handle.

    db_null @@ -413,7 +413,7 @@ column values. Raises an error if the query does not return exactly 1 row.

    Example:

     
 db_1row select_foo "select foo, bar from greeble where greeble_id = $greeble_id"
-# Bombs if there's no such greeble!
+# Bombs if there's no such greeble!
 # Now $foo and $bar are set.
    db_0or1row 
    @@ -424,7 +424,7 @@
 returns 0. If more than one row is returned, throws an error.
    db_string 
     db_string statement-name sql [ -default default ] [ -bind bind_set_id | -bind bind_value_list ]

    Returns the first column of the result of SQL query -sql. If sql doesn't return a +sql. If sql doesn't return a row, returns default (or throws an error if default is unspecified). Analogous to database_to_tcl_string and @@ -440,15 +440,15 @@

    db_list
     db_list statement-name sql [ -bind bind_set_id | -bind bind_value_list ]

    Returns a Tcl list of the values in the first column of the result of SQL -query sql. If sql doesn't +query sql. If sql doesn't return any rows, returns an empty list. Analogous to database_to_tcl_list.

    db_list_of_lists
     db_list_of_lists statement-name sql [ -bind bind_set_id | -bind bind_value_list ]

    Returns a Tcl list, each element of which is a list of all column values in a row of the result of SQL query sql. If -sql doesn't return any rows, returns an empty list. +sql doesn't return any rows, returns an empty list. (Analogous to database_to_tcl_list_list.)

    db_list_of_ns_sets
    @@ -560,11 +560,11 @@
     
    
     Each row also has a column, rownum, automatically
     added and set to the row number, starting with 1. Note that this will
-    override any column in the SQL statement named 'rownum', also if you're
+    override any column in the SQL statement named 'rownum', also if you're
     using the Oracle rownum pseudo-column.
     
    
     If the -local is passed, the variables defined
-    by db_multirow will be set locally (useful if you're compiling dynamic templates
+    by db_multirow will be set locally (useful if you're compiling dynamic templates
     in a function or similar situations).
     
                                                                                                                                            
     You may supply a code block, which will be executed for each row in
@@ -580,7 +580,7 @@
     useful for things like constructing a URL for the object retrieved by
     the query.
     
    
-    If you're constructing your multirow through multiple queries with the
+    If you're constructing your multirow through multiple queries with the
     same set of columns, but with different rows, you can use the
     -append switch. This causes the rows returned by this query
     to be appended to the rows already in the multirow, instead of starting
@@ -612,7 +612,7 @@
    db_with_handle
     db_with_handle var code_block

    Places a database handle into the variable var and -executes code_block. This is useful when you don't +executes code_block. This is useful when you don't want to have to use the new API (db_foreach, db_1row, etc.), but need to use database handles explicitly.

    Example:

     
@@ -623,7 +623,7 @@
 }
 
 db_with_handle db {
-    # Now there's a database handle in $db.
+    # Now there's a database handle in $db.
     set selection [ns_db select $db "select foo from bar"]
     while { [ns_db getrow $db $selection] } {
         set_variables_after_query
@@ -677,7 +677,7 @@
 			db_package_supports_rdbms_p db_type_list

    Returns 1 if db_type_list contains the current RDMBS type. A package - intended to run with a given RDBMS must note this in it's package info + intended to run with a given RDBMS must note this in it's package info file regardless of whether or not it actually uses the database.

    Index: openacs-4/packages/acs-core-docs/www/db-api.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/db-api.adp,v diff -u -N -r1.1.2.5 -r1.1.2.6 --- openacs-4/packages/acs-core-docs/www/db-api.adp 9 Jun 2016 08:44:49 -0000 1.1.2.5 +++ openacs-4/packages/acs-core-docs/www/db-api.adp 23 Jun 2016 08:32:45 -0000 1.1.2.6 @@ -11,17 +11,17 @@

    The OpenACS Database Access API

    By Pete Su and Jon Salz. Modified by Roberto Mello.

    -Overview

    One of OpenACS's great strengths is that code written for it is -very close to the database. It is very easy to interact with the +Overview

    One of OpenACS's great strengths is that code written for it +is very close to the database. It is very easy to interact with the database from anywhere within OpenACS, and we have a coherent API for database access which makes this even easier.

    More detailed information about the DB api is available at Database Access API.

    DB API Examples

    The OpenACS database API is meant to save developers from making common mistakes and to provide a more structured syntax for -specifying database operations, including transactions. Here's an -example of the API.

    +specifying database operations, including transactions. Here's
+an example of the API.
     set count 0
 set tcl_var "foo"
 set sql {
@@ -116,9 +116,9 @@
 
 db_foreach my_query { select :table from some_table where :condition }
     
-
    SQL will not allow a literal to occur where we've put the bind
-variables, so the query is syntactically incorrect. You have to
-remember that while the bind variable syntax looks similar to
+

    SQL will not allow a literal to occur where we've put the +bind variables, so the query is syntactically incorrect. You have +to remember that while the bind variable syntax looks similar to variable interpolation in Tcl, It is not the same thing at all.

    Finally, the DB API has several different styles for passing bind variable values to queries. In general, use the style @@ -194,11 +194,13 @@ into null. (This coercion does not occur in the WHERE clause of a query, i.e. -col = '' and col is null are not equivalent.)

    As a result, when using bind variables, the only way to make +col = '' and +col is null are not +equivalent.)

    As a result, when using bind variables, the only way to make Oracle set a column value to null is to set the corresponding bind variable to the empty string, since a bind variable whose value is -the string "null" will be interpreted as the literal string -"null".

    These Oracle quirks complicate the process of writing clear and +the string "null" will be interpreted as the literal +string "null".

    These Oracle quirks complicate the process of writing clear and abstract DML difficult. Here is an example that illustrates why:

     
@@ -268,17 +270,17 @@
 
    
 Basic API
    The Database API has several functions that wrap familiar parts
 of the AOLserver database API.
    Note that you never have to use ns_db anymore (including ns_db gethandle)! Just start doing stuff,
-and (if you want) call db_release_unused_handles when you're done
-as a hint to release the database handle.
    
+and (if you want) call db_release_unused_handles when you're
+done as a hint to release the database handle.
    
 
    
 db_abort_transaction
    
 
     db_abort_transaction
           
 
    Aborts all levels of a transaction. That is if this is called
 within several nested transactions, all of them are terminated. Use
-this instead of db_dml "abort" "abort
-transaction".
    
+this instead of db_dml
+"abort" "abort transaction".
    
 
    
 db_multirow
    
 
    @@ -296,10 +298,10 @@
 var_name:columns to a list of
 column names.
    Each row also has a column, rownum, automatically added and set
 to the row number, starting with 1. Note that this will override
-any column in the SQL statement named 'rownum', also if you're
-using the Oracle rownum pseudo-column.
    If the -local is passed, the
+any column in the SQL statement named 'rownum', also if
+you're using the Oracle rownum pseudo-column.
    If the -local is passed, the
 variables defined by db_multirow will be set locally (useful if
-you're compiling dynamic templates in a function or similar
+you're compiling dynamic templates in a function or similar
 situations).
    You may supply a code block, which will be executed for each row
 in the loop. This is very useful if you need to make computations
 that are better done in Tcl than in SQL, for example using
@@ -309,13 +311,13 @@
 copied back into the multirow.
    You may also add additional, computed columns to the multirow,
 using the -extend { col_1col_2 ... } switch. This is
 useful for things like constructing a URL for the object retrieved
-by the query.
    If you're constructing your multirow through multiple queries
-with the same set of columns, but with different rows, you can use
-the -append switch. This causes
-the rows returned by this query to be appended to the rows already
-in the multirow, instead of starting a clean multirow, as is the
-normal behavior. The columns must match the columns in the original
-multirow, or an error will be thrown.
    Your code block may call continue in order to skip a row and not
+by the query.
    If you're constructing your multirow through multiple
+queries with the same set of columns, but with different rows, you
+can use the -append switch.
+This causes the rows returned by this query to be appended to the
+rows already in the multirow, instead of starting a clean multirow,
+as is the normal behavior. The columns must match the columns in
+the original multirow, or an error will be thrown.
    Your code block may call continue in order to skip a row and not
 include it in the multirow. Or you can call break to skip this row and quit
 looping.
    Notice the nonstandard numbering (everything else in Tcl starts
 at 0); the reason is that the graphics designer, a non programmer,
@@ -340,8 +342,8 @@
   lappend asset_id_l $asset_id
 }
           
-
    Technically it's equivalent to using a code block on the end of
-your db_multirow.
    
+

    Technically it's equivalent to using a code block on the end +of your db_multirow.

    db_null
    db_null

    Returns a value which can be used in a bind variable to @@ -381,7 +383,7 @@ 1 row.

    Example:

     
 db_1row select_foo "select foo, bar from greeble where greeble_id = $greeble_id"
-# Bombs if there's no such greeble!
+# Bombs if there's no such greeble!
 # Now $foo and $bar are set.
 
           
@@ -417,7 +419,7 @@
 db_string statement-namesql [ -default default ] [ -bind bind_set_id | -bind bind_value_list ]

    Returns the first column of the result of SQL query sql. -If sql doesn't return a row, +If sql doesn't return a row, returns default (or throws an error if default is unspecified). Analogous to database_to_tcl_string and database_to_tcl_string_or_null.

    @@ -428,7 +430,7 @@

    Returns a Tcl list of the values in the first column of the result of SQL query sql. If sql -doesn't return any rows, returns an empty list. Analogous to +doesn't return any rows, returns an empty list. Analogous to database_to_tcl_list.

    db_list_of_lists
    @@ -437,8 +439,8 @@

    Returns a Tcl list, each element of which is a list of all column values in a row of the result of SQL query sql. -If sql doesn't return any rows, -returns an empty list. (Analogous to database_to_tcl_list_list.)

    +If sql doesn't return any +rows, returns an empty list. (Analogous to database_to_tcl_list_list.)

    db_dml
    @@ -497,8 +499,8 @@

    Executes code_block transactionally. Nested transactions are supported (end -transaction is transparently ns_db dml'ed when the outermost transaction -completes). The db_abort_transaction command can be used to +transaction is transparently ns_db dml'ed when the outermost +transaction completes). The db_abort_transaction command can be used to abort all levels of transactions. It is possible to specify an optional on_error code block that will be executed if some code in code_block throws an exception. The @@ -548,7 +550,7 @@ db_with_handle varcode_block

    Places a database handle into the variable var and executes code_block. This is useful when -you don't want to have to use the new API (db_foreach, db_1row, etc.), but need to use database +you don't want to have to use the new API (db_foreach, db_1row, etc.), but need to use database handles explicitly.

    Example:

     
 proc lookup_the_foo { foo } {
@@ -558,7 +560,7 @@
 }
 
 db_with_handle db {
-    # Now there's a database handle in $db.
+    # Now there's a database handle in $db.
     set selection [ns_db select $db "select foo from bar"]
     while { [ns_db getrow $db $selection] } {
         set_variables_after_query
@@ -588,7 +590,7 @@
 set n_rows [db_string unused "select count(*) from foo where baz is null"]
 #
 # $n_rows is 1; in effect, the "baz is null" criterion is matching
-# the empty string we just inserted (because of Oracle's coercion
+# the empty string we just inserted (because of Oracle's coercion
 # quirk)
 
           
@@ -600,22 +602,23 @@
    -
    ($‌Id: db-api.xml,v 1.13.8.1 2016/01/02 21:55:21 -gustafn Exp $)
    +
    ($‌Id: db-api.html,v 1.50.2.11 2016/06/21 +07:44:35 gustafn Exp $)

    Caching Database API Results

    The database API allows for direct caching of query results. Repeated calls will return the cached value until it is either explicitly flushed using db_flush_cache, times out (configured the ns_cache is called to create the cache), or another cached query fills the cache, causing older entries to be flushed.

    Values returned by a query are cached if you pass the -"-cache_key" switch to the database procedure. The switch value -will be used as the key in the ns_cache eval call used to execute -the query and processing code. The db_flush proc should be called -to flush the cache when appropriate. The "-cache_pool" parameter -can be used to specify the cache pool to be used, and defaults to -db_cache_pool. The size of the default cache is governed by the -kernel parameter "DBCacheSize" in the "caching" section.

    Currently db_string, db_list, db_list_of_lists, db_1row, +"-cache_key" switch to the database procedure. The switch +value will be used as the key in the ns_cache eval call used to +execute the query and processing code. The db_flush proc should be +called to flush the cache when appropriate. The +"-cache_pool" parameter can be used to specify the cache +pool to be used, and defaults to db_cache_pool. The size of the +default cache is governed by the kernel parameter +"DBCacheSize" in the "caching" section.

    Currently db_string, db_list, db_list_of_lists, db_1row, db_0or1row, and db_multirow support caching.

    For caching to be effective, one must carefully design a cache_pool and cache_key strategy that uniquely identifies a query within the system, including the relevant objects being referenced Index: openacs-4/packages/acs-core-docs/www/db-api.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/db-api.html,v diff -u -N -r1.50.2.11 -r1.50.2.12 --- openacs-4/packages/acs-core-docs/www/db-api.html 21 Jun 2016 07:44:35 -0000 1.50.2.11 +++ openacs-4/packages/acs-core-docs/www/db-api.html 23 Jun 2016 08:32:45 -0000 1.50.2.12 @@ -12,7 +12,7 @@

    DB API Examples

    The OpenACS database API is meant to save developers from making common mistakes and to provide a more structured syntax for - specifying database operations, including transactions. Here's + specifying database operations, including transactions. Here's an example of the API. 

     set count 0
@@ -134,7 +134,7 @@
 
 db_foreach my_query { select :table from some_table where :condition }

    - SQL will not allow a literal to occur where we've put the bind + SQL will not allow a literal to occur where we've put the bind variables, so the query is syntactically incorrect. You have to remember that while the bind variable syntax looks similar to variable interpolation in Tcl, It is not the same thing at all. @@ -290,7 +290,7 @@

    Note that you never have to use ns_db anymore (including ns_db gethandle)! Just start doing stuff, and (if you want) call - db_release_unused_handles when you're done as a hint to + db_release_unused_handles when you're done as a hint to release the database handle.

    @@ -318,11 +318,11 @@

    Each row also has a column, rownum, automatically added and set to the row number, starting with 1. Note that this will - override any column in the SQL statement named 'rownum', also if you're + override any column in the SQL statement named 'rownum', also if you're using the Oracle rownum pseudo-column.

    If the -local is passed, the variables defined - by db_multirow will be set locally (useful if you're compiling dynamic templates + by db_multirow will be set locally (useful if you're compiling dynamic templates in a function or similar situations).

    You may supply a code block, which will be executed for each row in @@ -338,7 +338,7 @@ useful for things like constructing a URL for the object retrieved by the query.

    - If you're constructing your multirow through multiple queries with the + If you're constructing your multirow through multiple queries with the same set of columns, but with different rows, you can use the -append switch. This causes the rows returned by this query to be appended to the rows already in the multirow, instead of starting @@ -377,7 +377,7 @@ multirow foreach assets { lappend asset_id_l $asset_id } -

    Technically it's equivalent to using a code block on +

    Technically it's equivalent to using a code block on the end of your db_multirow.

    @@ -444,7 +444,7 @@

    Example:

     
 db_1row select_foo "select foo, bar from greeble where greeble_id = $greeble_id"
-# Bombs if there's no such greeble!
+# Bombs if there's no such greeble!
 # Now $foo and $bar are set.
    @@ -487,7 +487,7 @@ db_string statement-name sql [ -default default ] [ -bind bind_set_id | -bind bind_value_list ]

    Returns the first column of the result of SQL query sql. - If sql doesn't return a + If sql doesn't return a row, returns default (or throws an error if @@ -500,15 +500,15 @@

    Returns a Tcl list of the values in the first column of the result of SQL query sql. - If sql doesn't + If sql doesn't return any rows, returns an empty list. Analogous to database_to_tcl_list.

    db_list_of_lists
     db_list_of_lists statement-name sql [ -bind bind_set_id | -bind bind_value_list ]

    Returns a Tcl list, each element of which is a list of all column values in a row of the result of SQL query sql. If - sql doesn't return any rows, returns an empty list. + sql doesn't return any rows, returns an empty list. (Analogous to database_to_tcl_list_list.)

    db_dml
    @@ -601,7 +601,7 @@
    db_with_handle
     db_with_handle var code_block

    Places a database handle into the variable var and - executes code_block. This is useful when you don't + executes code_block. This is useful when you don't want to have to use the new API (db_foreach, db_1row, etc.), but need to use database handles explicitly.

    Example:

     
@@ -612,7 +612,7 @@
 }
 
 db_with_handle db {
-    # Now there's a database handle in $db.
+    # Now there's a database handle in $db.
     set selection [ns_db select $db "select foo from bar"]
     while { [ns_db getrow $db $selection] } {
         set_variables_after_query
@@ -644,7 +644,7 @@
 set n_rows [db_string unused "select count(*) from foo where baz is null"]
 #
 # $n_rows is 1; in effect, the "baz is null" criterion is matching
-# the empty string we just inserted (because of Oracle's coercion
+# the empty string we just inserted (because of Oracle's coercion
 # quirk)

    Index: openacs-4/packages/acs-core-docs/www/docbook-primer.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/docbook-primer.adp,v diff -u -N -r1.1.2.11 -r1.1.2.12 --- openacs-4/packages/acs-core-docs/www/docbook-primer.adp 21 Jun 2016 07:44:35 -0000 1.1.2.11 +++ openacs-4/packages/acs-core-docs/www/docbook-primer.adp 23 Jun 2016 08:32:45 -0000 1.1.2.12 @@ -19,11 +19,11 @@ curve that is only attenuated by good documentation. Our goal is to write superb documentation, so that users, developers and administrators of OpenACS installations can enjoy the system.

    The history of OpenACS documentation: ..began by building on a -good documentation base from ArsDigita's ACS in the late 1990's. -Some sections of the documentation, however, lacked details and -examples; others simply did not exist. The OpenACS community began -meeting the challenge by identifying needs and writing -documentation on an as needed basis.

    By having documentation dependent on volunteers and code +good documentation base from ArsDigita's ACS in the late +1990's. Some sections of the documentation, however, lacked +details and examples; others simply did not exist. The OpenACS +community began meeting the challenge by identifying needs and +writing documentation on an as needed basis.

    By having documentation dependent on volunteers and code developers, documentation updates lagged behind the evolving system software. As significant development changes were made to the system, existing documentation became dated, and its value @@ -39,7 +39,7 @@ significant work completed by others. New developers had to learn the system through experience with working with it and discussion in the forums. Informal sharing of experiential and tacit knowledge -has become the OpenACS community's main method of sharing +has become the OpenACS community's main method of sharing knowledge.

    This document attempts to shape ongoing documentation efforts by using principles of continual improvement to re-engineer documentation production.

    @@ -110,13 +110,14 @@ that bookmarks etc. indicate location in a manner similar to pages in books (in print publishing world).

  • Organize document according to the needs of the reader (which may be different than the wishes of the writers).

  • Do not make informal exclamations about difficulty/ease for -users to complete tasks or understand... for example, "Simply...". -Readers come from many different backgrounds --remember that the -greater audience is likely as varied as the readers on the -internet--- If important, state pre-conditions or knowledge -requirements etc. if different than the rest of the context of the -document. For example, "requires basic competency with a text-based -editor such as vi or emacs via telnet"

    • +users to complete tasks or understand... for example, +"Simply...". Readers come from many different backgrounds +--remember that the greater audience is likely as varied as the +readers on the internet--- If important, state pre-conditions or +knowledge requirements etc. if different than the rest of the +context of the document. For example, "requires basic +competency with a text-based editor such as vi or emacs via +telnet"

  • Show where to find current information instead of writing about @@ -138,7 +139,7 @@ (books). Each book contains chapters and sections much like how DocBook examples are shown, where each chapter is a web page. This designation could help create an OpenACs book in print, and help -new readers visualize how the documentation is organized.

  • The use licenses between OpenACS and Arsdigita's ACS are not +new readers visualize how the documentation is organized.

  • The use licenses between OpenACS and Arsdigita's ACS are not compatible, thereby creating strict limits on how much OpenACS developers should have access to Arsdigita code and resources. The OpenACS documentation has a new legal requirement: to eliminate any @@ -184,32 +185,33 @@ possibilities this system brings (think customer solution, customer cost, convenience, value). A comprehensive community communications system; How this system is valuable to users; Reasons others use -OpenACS (with quotes in their own words) "...the most important -thing that the ACS does is manage users, i.e. provide a way to -group, view and manipulate members of the web community. -- Talli -Somekh, September 19, 2001" using it to communicate, cooperate, -collaborate... OpenACS offers directed content functionality with -the OpenACS templating system. ... OpenACS is more than a data -collection and presentation tool. OpenACS has management facilities -that are absent in other portals. ...The beauty of OpenACS is the -simplicity (and scalability) of the platform on which it is built -and the library of tried and tested community building tools that -are waiting to be added. It seems that most portals just add -another layer of complexity to the cake. See Slides on OACS features...a set of slides on OACS +OpenACS (with quotes in their own words) "...the most +important thing that the ACS does is manage users, i.e. provide a +way to group, view and manipulate members of the web community. -- +Talli Somekh, September 19, 2001" using it to communicate, +cooperate, collaborate... OpenACS offers directed content +functionality with the OpenACS templating system. ... OpenACS is +more than a data collection and presentation tool. OpenACS has +management facilities that are absent in other portals. ...The +beauty of OpenACS is the simplicity (and scalability) of the +platform on which it is built and the library of tried and tested +community building tools that are waiting to be added. It seems +that most portals just add another layer of complexity to the cake. +See Slides on OACS features...a set of slides on OACS features that can be used for beginners who want to know OACS is about and what they can do with it. Screen captures that highlight features. Example shows BBoard, calendar, news, file storage, wimpy point, ticket tracking. An OpenACS tour; an abbreviated, interactive set of demo pages.

  • From a marketing perspective,

      -

    • differentiate "product" by highlighting features, performance -quality, conformance to standards, durability (handling of -technological obsolescence), reliability, repairability, style of -use, design (strategy in design, specifications, integrated, -well-matched systems etc).

    • differentiate "service" by highlighting software availability -(licensing and completeness from mature to early adopters or -development versions), community incident support, project -collaborative opportunities, and contractor support +

    • differentiate "product" by highlighting features, +performance quality, conformance to standards, durability (handling +of technological obsolescence), reliability, repairability, style +of use, design (strategy in design, specifications, integrated, +well-matched systems etc).

    • differentiate "service" by highlighting software +availability (licensing and completeness from mature to early +adopters or development versions), community incident support, +project collaborative opportunities, and contractor support availability

    • differentiate price (economic considerations of opensource and features)

    • Discussion and details should rely on meeting criteria of design, completeness of implementation, and related system @@ -248,10 +250,10 @@ from the real world edited into a longer description to quickly learn if a package is appropriate for specific projects.

    • Create a long bulleted list of features. Feature list should go deeper than high-level feature lists and look at the quality of the -implementations (from the user's perspective, not the -programmer's). Example issues an end-user may have questions about: -Ticket Tracker and Ticket Tracker Lite, why would I want one of -them vs the other? And, before I specify to download and install +implementations (from the user's perspective, not the +programmer's). Example issues an end-user may have questions +about: Ticket Tracker and Ticket Tracker Lite, why would I want one +of them vs the other? And, before I specify to download and install it, what credit card gateways are supported by the current e-commerce module? There are some packages where the name is clear enough, but what are the limitations of the standard package?

    • End-user docs should not be duplicative. The package description @@ -265,26 +267,28 @@ OpenACS Documentation Requirements for Site and Administrators

    • By the OpenACS Community. This section is a collection of documentation requirements that have been expressed in the OpenACS -forums to 4th July 2003.

    OpenACS administrators' documentation should meet the following -requirements. No significance has been given to the order +forums to 4th July 2003.

    OpenACS administrators' documentation should meet the +following requirements. No significance has been given to the order presented, topic breadth or depth here.

    • For each requirement below, include links to developer tutorials and other documentation for more detail.

    • Describe a structural overview of a working system and how the -components work together. "The Layered Cake view" a general network -view of system; a table showing system levels versus roles to help -with understanding how the subsystems are interconnected.

    • Provide a comprehensive description of typical administrative +components work together. "The Layered Cake view" a +general network view of system; a table showing system levels +versus roles to help with understanding how the subsystems are +interconnected.

    • Provide a comprehensive description of typical administrative processes for operating an OpenACS system responsibly, including reading logs and command line views that describe status of various active processes.

    • Create a list of administrative tools that are useful to administrating OpenACS, including developer support, schema-browser -and api browser. Link to AOLserver's config file documentation.

    • Resources on high level subjects such as web services, security +and api browser. Link to AOLserver's config file +documentation.

    • Resources on high level subjects such as web services, security guidelines

    • Describe typical skill sets (and perhaps mapped to standardized job titles) for administrating an OpenACS system (human-resources style). For a subsite admin/moderator attributes might include trustworthy, sociable, familiarity with the applications and subsystems, work/group communication skills et cetera

    • Describe how to set up typical site moderation and -administration including parameters, permissions, "Hello World" -page

    • Show directory structure of a typical package, explanation of +administration including parameters, permissions, "Hello +World" page

    • Show directory structure of a typical package, explanation of the various file types in a package (tcl,adp,xql) and how those relate to the previously described subsystems, when they get refreshed etc.

    • Ways to build a "Hello World" page

    • Show examples of how the OpenACS templating system is used, @@ -297,9 +301,9 @@ statements and interpreting them --for OpenACS and the underlying processes.

    • FAQs: Administration tasks commonly discussed on boards: admin page flow, how to change the looks of a subsite with a new -master.adp, options on "user pages" , a quick introduction to the -functions and processes. info about the user variables, file -locations

      • +master.adp, options on "user pages" , a quick +introduction to the functions and processes. info about the user +variables, file locations

    @@ -309,15 +313,17 @@ forums to 4th July 2003.

    OpenACS installation documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here.

      -

    • state installation prerequisites. For example: "You should read -through the installation process to familiarize yourself with the -installation process, before beginning an installation."

    • list critical decisions (perhaps as questions) that need to be +

    • state installation prerequisites. For example: "You should +read through the installation process to familiarize yourself with +the installation process, before beginning an +installation."

    • list critical decisions (perhaps as questions) that need to be made before starting: which OS, which DB, which aolserver version, system name, dependencies et cetera. Maybe summarize options as -tables or decision-trees. For example, "As you proceed throughout -the installation, you will be acting on decisions that have an -impact on how the remaining part of the system is installed. Here -is a list of questions you should answer before beginning."

    • list pre-installation assumptions

    • Show chronological overview of the process of installing a +tables or decision-trees. For example, "As you proceed +throughout the installation, you will be acting on decisions that +have an impact on how the remaining part of the system is +installed. Here is a list of questions you should answer before +beginning."

    • list pre-installation assumptions

    • Show chronological overview of the process of installing a system to full working status: Install operating system with supporting software, configure with preparations for OpenACS, RDBMS(s) install and configure, Webserver install and configure, @@ -344,9 +350,9 @@ protocols, how to use the page contract, how to get the accessing user_id etc

    • Show how to construct basic SQL queries using the db API,

    • The life of an http request to a dynamic, templated page

    • General rules to follow for stability, scalability

    • Show the step by step customizing of an existing package that meets current recommended coding styles of OpenACS package -development, by referring to developer resources.

    • Use the ArsDigita problem sets and "what Lars produced for ACS -Java" as inspiration for a PostgreSQL equivalent tutorial about -developing a new OpenACS package including discussion of the +development, by referring to developer resources.

    • Use the ArsDigita problem sets and "what Lars produced for +ACS Java" as inspiration for a PostgreSQL equivalent tutorial +about developing a new OpenACS package including discussion of the significance of the package documentation templates

    • Include a summary of important links used by developers

    • Note any deprecated tools and methods by linking to prior versions instead of describing them in current docs

    @@ -368,12 +374,12 @@ development and reference areas.

  • Show current engineering standards and indicate where changes to the standards are in the works.

  • Sections should be dedicated to DotLRN standards as well, if they are not available elsewhere.

  • Add overview diagrams showing the core parts of the datamodel -including an updated summary of Greenspun's Chapter 4: Data Models -and the Object System

  • package design guidelines and development process templates +including an updated summary of Greenspun's Chapter 4: Data +Models and the Object System

  • package design guidelines and development process templates including planning, core functions, testing, usability, and creating case studies

  • -

    Standard package conventions, where to see "model" code, and -guidelines (or where to find them) for:

      +

      Standard package conventions, where to see "model" +code, and guidelines (or where to find them) for:

      • programming tcl/sql

      • using the acs-api

      • ad_form

      • coding permissions

      • OpenACS objects

      • scheduled protocols

      • call backs

      • directory structure

      • user interface

      • widgets

      • package_name and type_extension_table

      • adding optional services, including search, general comments, attachments, notifications, workflow, CR and the new CR Tcl API

      @@ -432,16 +438,14 @@ to usability on the web. That meant DocBook did not entirely meet OpenACS publishing requirements at that time.

      In 2004, Docbook released version 4.4, which complies with all the OpenACS publishing requirements. Producing a web friendly book -hierarchy arguably remains DocBooks' weakest point. For example, a -dynamically built document should be able to extract details of a -specific reference from a bibliographic (table) and present a -footnote at the point where referenced. DocBook 4.4 allows for this -with bibliocoverage, -bibliorelation, and -bibliosource. DocBook: The Definitive Guide is a good start for +hierarchy arguably remains DocBooks' weakest point. For +example, a dynamically built document should be able to extract +details of a specific reference from a bibliographic (table) and +present a footnote at the point where referenced. DocBook 4.4 +allows for this with bibliocoverage, bibliorelation, and bibliosource. DocBook: The Definitive Guide is a good start for learning how to represent paper-based books online.

      The following DocBook primer walks you through the basics, and should cover the needs for 95 percent of the documentation we -produce. You are welcome to explore DocBook's list +produce. You are welcome to explore DocBook's list of elements and use more exotic features in your documents. The list is made up of SGML-elements but basically the same elements are valid in the XML DTD as long as @@ -462,7 +466,7 @@ zip file from the site linked from here.

    • XSL Stylesheets (docbook-xsl) - The stylesheets to convert to HTML. We have been using a stylesheet based upon -NWalsh's chunk.xsl.

    • +NWalsh's chunk.xsl.

    • xsltproc - The processor that will take an XML document and, given a xsl stylesheet, convert it to HTML. It needs libxml2 and libxslt (available in RPM and DEB @@ -485,8 +489,9 @@ Template.

    -Document Structure

    The documentation for each package will make up a little "book" -that is structured like this - examples are emphasized: +Document Structure

    • The documentation for each package will make up a little +"book" that is structured like this - examples are +emphasized: 

         book                        : Docs for one package - templating
      |
@@ -498,7 +503,7 @@
              |
              +--sect2           : Sections - functional requirements
                  |
-                 +--sect3       : Subsections - Programmer's API
+                 +--sect3       : Subsections - Programmer's API
                      |
                     ...         : ...

    The actual content is split up into documents that start at a @@ -522,12 +527,12 @@ links in the section called “Links”). The value of id has to be unique throughout -the book you're making since the id's in your sect1's will turn into filenames when the -book is parsed into HTML.

    +the book you're making since the id's in your sect1's will turn into filenames when +the book is parsed into HTML.

    The other attribute is xreflabel. The value of this is the text that will appear as the link when referring to this sect1.

    Right after the opening tag you put the title of the document - this is usually the same as xreflabel-attribute. E.g. the top level of -the document you're reading right now looks like this:

    +the document you're reading right now looks like this:
     <sect1 id="docbook-primer" xreflabel="DocBook Primer">
   <title>DocBook Primer</title>
 
@@ -539,9 +544,9 @@
 be split up into <sect2>'s,
 each with the same requirements - id and xreflabel attributes, and a <title>-tag inside. Actually, the
 xreflabel is never required in
-sections, but it makes linking to that section a lot easier.
    When it comes to naming your sect2's and below, prefix them with some
-abbreviation of the id in the
-sect1 such as requirements-overview.
    
+sections, but it makes linking to that section a lot easier.
    When it comes to naming your sect2's and below, prefix them with
+some abbreviation of the id in
+the sect1 such as requirements-overview.

    Code

    @@ -560,37 +565,38 @@

    Links

    Linking falls into two different -categories: inside the book you're making and outside:

    +categories: inside the book you're making and outside:

    1. Inside linking, cross-referencing other parts of your book
    -

    By having unique id's you -can cross-reference any part of your book with a simple tag, +

    By having unique id's +you can cross-reference any part of your book with a simple tag, regardless of where that part is.

    Check out how I link to a subsection of -the Developer's Guide:

    Put this in your XML:

    +the Developer's Guide:
    Put this in your XML:
     - Find information about creating a package in
 <xref linkend="packages-making-a-package"></xref>.
 
    And the output is:
     - Find information about creating a package in 
 Making a Package.
 
    Note that even though this is an empty tag, you have to
 either:
      
-
    1. Provide the end-tag, </xref>, or
    2. Put a slash before the ending-bracket: <xref linkend="blahblah"/>
+
    3. Provide the end-tag, </xref>, or
    4. Put a slash before the ending-bracket: <xref
+linkend="blahblah"/>
 
      5. 
-
    If the section you link to hasn't a specified xreflabel-attribute, the link is going to
+

    If the section you link to hasn't a specified xreflabel-attribute, the link is going to look like this:

    Put this in your XML:

     -Find information about what a package looks like in 
 <xref linkend="packages-looks"></xref>.

    And the output is:

     - Find information about what a package looks like in 
 the section called “What a Package Looks Like”.
-

    Note that since I haven't provided an xreflabel for the subsection, packages-looks, the parser will try its +

    Note that since I haven't provided an xreflabel for the subsection, packages-looks, the parser will try its best to explain where the link takes you.

    2. Linking outside the documentation

    - If you're hyper-linking out of the + If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just a little different (<ulink>):

     <ulink url="http://www.oracle.com/">Oracle Corporation</ulink>
@@ -629,12 +635,12 @@
     <phrase>This is an image of the flow in the Request Processor</phrase>
   </textobject>
 </mediaobject>
-

    Put your graphics in a separate directory ("images") and link to -them only with relative paths.

    +

    Put your graphics in a separate directory ("images") +and link to them only with relative paths.

    Lists

    - Here's how you make the DocBook + Here's how you make the DocBook equivalent of the three usual HTML-lists:

    1. How to make an <ul>
    @@ -665,8 +671,8 @@
    3. How to make a <dl>
    -

    This kind of list is called a variablelist and these are the tags you'll -need to make it happen: <variablelist>, <varlistentry>, <term> and +

    This kind of list is called a variablelist and these are the tags +you'll need to make it happen: <variablelist>, <varlistentry>, <term> and <listitem>:

     <variablelist>
 
@@ -735,8 +741,8 @@
 Emphasis

    Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - <emphasis>.

    The <emphasis> tag -defaults to italics when parsed. If you're looking for emphasizing -with bold type, use <emphasis +defaults to italics when parsed. If you're looking for +emphasizing with bold type, use <emphasis role="strong">.

    @@ -758,7 +764,7 @@ the command:

     bash$ xsltproc -o outputfilename.xml /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/html.xsl filename.xml
    -

    Note

    This example uses Daniel Veillard's xsltproc command available as part +

    Note

    This example uses Daniel Veillard's xsltproc command available as part of libxslt from http://www.xmlsoft.org/XSLT/. If you are using other XML processors such as Xalan or Saxon, you will need to change the command line appropriately.

    @@ -773,11 +779,11 @@ Further Reading

    • Using Xinclude

    • The LDP Author Guide has a lot of good information, a table of docbook -elements and their "look" in HTML and lots of good links for -tools.

    • James Clark wrote nXML Mode, an alternative to PSGML +elements and their "look" in HTML and lots of good links +for tools.

    • James Clark wrote nXML Mode, an alternative to PSGML Mode. nXML Mode can validate a file as it is edited.

    • David Lutterkort wrote an intro to the PSGML Mode in Emacs -

    • James Clark's free Java parser XP. +

    • James Clark's free Java parser XP. Note that this does not validate XML, only parses it.

    • DocBook Tool for Linux: Converts docbook documents to a number of formats. NOTE: @@ -787,8 +793,8 @@

    • AptConvert from PIXware is a Java editor that will produce DocBook documents and let you transform them into HTML and PDF for a local preview before you submit.

    • In the process of transforming your HTML into XML, HTML -tidy can be a handy tool to make your HTML "regexp'able". -Brandoch Calef has made a Perl script with directions (now via archive.org) +tidy can be a handy tool to make your HTML +"regexp'able". Brandoch Calef has made a Perl script with directions (now via archive.org) that gets you most of the way.

    Index: openacs-4/packages/acs-core-docs/www/docbook-primer.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/docbook-primer.html,v diff -u -N -r1.52.2.10 -r1.52.2.11 --- openacs-4/packages/acs-core-docs/www/docbook-primer.html 21 Jun 2016 07:44:35 -0000 1.52.2.10 +++ openacs-4/packages/acs-core-docs/www/docbook-primer.html 23 Jun 2016 08:32:45 -0000 1.52.2.11 @@ -10,7 +10,7 @@ of OpenACS installations can enjoy the system.

    The history of OpenACS documentation: ..began by - building on a good documentation base from ArsDigita's ACS in the + building on a good documentation base from ArsDigita's ACS in the late 1990's. Some sections of the documentation, however, lacked details and examples; others simply did not exist. The OpenACS community began meeting the challenge by identifying needs and @@ -36,7 +36,7 @@ developers had to learn the system through experience with working with it and discussion in the forums. Informal sharing of experiential and tacit knowledge has become the OpenACS - community's main method of sharing knowledge. + community's main method of sharing knowledge.

    This document attempts to shape ongoing documentation efforts by using principles of continual improvement to re-engineer @@ -166,7 +166,7 @@ book in print, and help new readers visualize how the documentation is organized.

  • - The use licenses between OpenACS and Arsdigita's ACS are not + The use licenses between OpenACS and Arsdigita's ACS are not compatible, thereby creating strict limits on how much OpenACS developers should have access to Arsdigita code and resources. The OpenACS documentation has a new legal @@ -323,8 +323,8 @@

  • Create a long bulleted list of features. Feature list should go deeper than high-level feature lists and look at the - quality of the implementations (from the user's perspective, - not the programmer's). Example issues an end-user may have + quality of the implementations (from the user's perspective, + not the programmer's). Example issues an end-user may have questions about: Ticket Tracker and Ticket Tracker Lite, why would I want one of them vs the other? And, before I specify to download and install it, what credit card gateways are @@ -363,7 +363,7 @@

  • Create a list of administrative tools that are useful to administrating OpenACS, including developer support, - schema-browser and api browser. Link to AOLserver's config + schema-browser and api browser. Link to AOLserver's config file documentation.

  • Resources on high level subjects such as web services, @@ -514,7 +514,7 @@ they are not available elsewhere.

  • Add overview diagrams showing the core parts of the - datamodel including an updated summary of Greenspun's + datamodel including an updated summary of Greenspun's Chapter 4: Data Models and the Object System

  • package design guidelines and development process templates @@ -636,7 +636,7 @@ to represent paper-based books online.

    The following DocBook primer walks you through the basics, and should cover the - needs for 95 percent of the documentation we produce. You are welcome to explore DocBook's + needs for 95 percent of the documentation we produce. You are welcome to explore DocBook's list of elements and use more exotic features in your documents. The list is made up of SGML-elements but basically @@ -661,7 +661,7 @@ XSL Stylesheets (docbook-xsl) - The stylesheets to convert to HTML. We have been using a stylesheet based upon - NWalsh's chunk.xsl. + NWalsh's chunk.xsl.

  • xsltproc - The processor that will take an XML document and, given a xsl stylesheet, convert @@ -703,7 +703,7 @@ | +--sect2 : Sections - functional requirements | - +--sect3 : Subsections - Programmer's API + +--sect3 : Subsections - Programmer's API | ... : ...

    @@ -724,15 +724,15 @@ id, is standard and can be used with all elements. It comes in very handy when interlinking between documents (more about this when talking about links in the section called “Links”). The value of id has to be unique - throughout the book you're making since the id's in your + throughout the book you're making since the id's in your sect1's will turn into filenames when the book is parsed into HTML.

    The other attribute is xreflabel. The value of this is the text that will appear as the link when referring to this sect1.

    Right after the opening tag you put the title of the document - this is usually the same as - xreflabel-attribute. E.g. the top level of the document you're + xreflabel-attribute. E.g. the top level of the document you're reading right now looks like this: 

     <sect1 id="docbook-primer" xreflabel="DocBook Primer">
@@ -770,11 +770,11 @@
       and <userinput>
 
    Links
    
       
-      Linking falls into two different categories: inside the book you're making and outside:
+      Linking falls into two different categories: inside the book you're making and outside:
     
    1. Inside linking, cross-referencing other parts of your book
    
         By having unique id's you can cross-reference any part of your book
         with a simple tag, regardless of where that part is.
-      
    Check out how I link to a subsection of the Developer's Guide:
    Put this in your XML:
    +      
    Check out how I link to a subsection of the Developer's Guide:
    Put this in your XML:
     - Find information about creating a package in
 <xref linkend="packages-making-a-package"></xref>.
 
    And the output is:
    @@ -786,20 +786,20 @@
         Provide the end-tag, </xref>, or

  • Put a slash before the ending-bracket: <xref linkend="blahblah"/> -

    • If the section you link to hasn't a specified xreflabel-attribute, +

    If the section you link to hasn't a specified xreflabel-attribute, the link is going to look like this:

    Put this in your XML:

     -Find information about what a package looks like in 
 <xref linkend="packages-looks"></xref>.

    And the output is:

     - Find information about what a package looks like in 
 the section called “What a Package Looks Like”.

    - Note that since I haven't provided an xreflabel for the subsection, + Note that since I haven't provided an xreflabel for the subsection, packages-looks, the parser will try its best to explain where the link takes you.

    2. Linking outside the documentation

    - If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just + If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just a little different (<ulink>): @@ -846,7 +846,7 @@ only with relative paths.

    Lists

    - Here's how you make the DocBook equivalent of the three usual HTML-lists: + Here's how you make the DocBook equivalent of the three usual HTML-lists:

    1. How to make an <ul>

    Making an unordered list is pretty much like doing the same thing in HTML - if you close your <li>, that is. The only differences are that each list item has to be wrapped in something more, such as <para>, and that the tags are called @@ -870,7 +870,7 @@ </orderedlist>

    3. How to make a <dl>

    - This kind of list is called a variablelist and these are the tags you'll need to + This kind of list is called a variablelist and these are the tags you'll need to make it happen: <variablelist>, <varlistentry>, @@ -931,7 +931,7 @@ Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - <emphasis>.

    - The <emphasis> tag defaults to italics when parsed. If you're looking for + The <emphasis> tag defaults to italics when parsed. If you're looking for emphasizing with bold type, use <emphasis role="strong">.

    Indexing Your DocBook Documents

    Words that are marked as index-words are referenced in an index @@ -957,7 +957,7 @@ 

     bash$ xsltproc -o outputfilename.xml /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/html.xsl filename.xml

    Note

    - This example uses Daniel Veillard's xsltproc command available + This example uses Daniel Veillard's xsltproc command available as part of libxslt from http://www.xmlsoft.org/XSLT/. If you are using other XML processors such as Xalan or Saxon, you will need to change the command line appropriately. @@ -983,7 +983,7 @@ David Lutterkort wrote an intro to the PSGML Mode in Emacs

  • - James Clark's free Java parser + James Clark's free Java parser XP. Note that this does not validate XML, only parses it.

  • @@ -997,7 +997,7 @@

  • In the process of transforming your HTML into XML, HTML tidy - can be a handy tool to make your HTML "regexp'able". + can be a handy tool to make your HTML "regexp'able". Brandoch Calef has made a Perl script with directions (now via archive.org) Index: openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.adp,v diff -u -N -r1.1.2.5 -r1.1.2.6 --- openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.adp 21 Jun 2016 07:44:36 -0000 1.1.2.5 +++ openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.adp 23 Jun 2016 08:32:45 -0000 1.1.2.6 @@ -57,11 +57,11 @@

    Format of constraint name

    <table name>_<column_name>_<constraint -abbreviation>

    In reality, this won't be possible because of the character +abbreviation>

    In reality, this won't be possible because of the character limitation on names inside oracle. When the name is too long, we will follow these two steps in order:

      -

    1. Abbreviate the table name with the table's initials (e.g. users --> u and users_contact -> uc).

    2. Truncate the column name until it fits.

      3. +

    3. Abbreviate the table name with the table's initials (e.g. +users -> u and users_contact -> uc).

    4. Truncate the column name until it fits.

    If the constraint name is still too long, you should consider rewriting your entire data model :)

    Notes:

    • If you have to abbreviate the table name for one of the @@ -97,9 +97,9 @@

    -Why it's good to name +Why it's good to name primary keys

    Naming primary keys might not have any obvious advantages. -However, here's an example where naming the primary key really +However, here's an example where naming the primary key really helps (and this is by no means a rare case!

     SQL> set autotrace traceonly explain;
 
@@ -114,19 +114,21 @@
    2    1     TABLE ACCESS (FULL) OF 'CONSTRAINT_NAMING_EXAMPLE'
    3    1     INDEX (UNIQUE SCAN) OF 'EXAMPLE_TOPICS_TOPIC_ID_PK' (UNI
           QUE)
-

    Isn't it nice to see "EXAMPLE_TOPICS_TOPIC_ID_PK" in the trace -and know exactly which table oracle is using at each step?

    +

    Isn't it nice to see "EXAMPLE_TOPICS_TOPIC_ID_PK" +in the trace and know exactly which table oracle is using at each +step?

    Naming not null constraints is optional...

    People disagree on whether or not we should be naming not null constraints. So, if you want to name them, please do so and follow the above naming standard. But, naming not null constraints is not -a requirement.

    About Naming the not null constraints

    Though naming "not null" constraints doesn't help immeditately -in error debugging (e.g. the error will say something like "Cannot -insert null value into column"), we recommend naming not null -constraints to be consistent in our naming of all constraints.

    ($‌Id: constraint-naming.xml,v 1.6 2006/07/17 -05:38:37 torbenb Exp $)
    +a requirement.

    About Naming the not null constraints

    Though naming "not null" constraints doesn't help +immeditately in error debugging (e.g. the error will say something +like "Cannot insert null value into column"), we +recommend naming not null constraints to be consistent in our +naming of all constraints.

    ($‌Id: eng-standards-constraint-naming.html,v +1.48.2.10 2016/06/21 07:44:36 gustafn Exp $)
    • Constraint typeAbbreviation
    references (foreign key)fk
    uniqueun
    primary keypk
    checkck
    not nullnn
    indexidx

    Format of constraint name

    <table name>_<column_name>_<constraint abbreviation>

    -In reality, this won't be possible because of the character limitation on +In reality, this won't be possible because of the character limitation on names inside oracle. When the name is too long, we will follow these two steps in order: -

    1. Abbreviate the table name with the table's initials (e.g. users -> u and users_contact -> uc). +

      1. Abbreviate the table name with the table's initials (e.g. users -> u and users_contact -> uc).

      2. Truncate the column name until it fits.

      If the constraint name is still too long, you should consider rewriting your entire data model :) @@ -52,8 +52,8 @@ constraint cne_example_id_one_line_unq unique(example_id, one_line_description) ); -

    Why it's good to name primary keys

    -Naming primary keys might not have any obvious advantages. However, here's an +

    Why it's good to name primary keys

    +Naming primary keys might not have any obvious advantages. However, here's an example where naming the primary key really helps (and this is by no means a rare case! 

    @@ -71,7 +71,7 @@
    3	1     INDEX (UNIQUE SCAN) OF 'EXAMPLE_TOPICS_TOPIC_ID_PK' (UNI
 	  QUE)

    -Isn't it nice to see "EXAMPLE_TOPICS_TOPIC_ID_PK" in the trace +Isn't it nice to see "EXAMPLE_TOPICS_TOPIC_ID_PK" in the trace and know exactly which table oracle is using at each step?

    Naming not null constraints is optional...

    People disagree on whether or not we should be naming not null @@ -81,7 +81,7 @@

    About Naming the not null constraints

    -Though naming "not null" constraints doesn't help immeditately in error +Though naming "not null" constraints doesn't help immeditately in error debugging (e.g. the error will say something like "Cannot insert null value into column"), we recommend naming not null constraints to be consistent in our naming of all constraints. Index: openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.adp,v diff -u -N -r1.1.2.4 -r1.1.2.5 --- openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.adp 28 Sep 2015 07:54:14 -0000 1.1.2.4 +++ openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.adp 23 Jun 2016 08:32:45 -0000 1.1.2.5 @@ -28,17 +28,17 @@ Style package):

    • For naming files that enable a specific action on an object, use -this format:

      object-verb.extension

      For example, the page to erase a user's portrait from the +this format:

      object-verb.extension

      For example, the page to erase a user's portrait from the database is /admin/users/portrait-erase.tcl.

    • However, modules typically deal with only one primary type of object - e.g., the Bookmarks module deals mainly with bookmarks - -and so action-type files in modules don't need to be specified by -the object they act on. Example: the user pages for the Bookmarks -module live in the /bookmarks/ -directory, and so there is no need to name the bookmark editing -page with a redundant url: /bookmarks/bookmark-edit.tcl. Instead, we -omit the object type, and use this convention:

      verb.extension

      Thus, the page to edit a bookmark is /bookmarks/edit.tcl.

      +and so action-type files in modules don't need to be specified +by the object they act on. Example: the user pages for the +Bookmarks module live in the /bookmarks/ directory, and so there is no +need to name the bookmark editing page with a redundant url: +/bookmarks/bookmark-edit.tcl. +Instead, we omit the object type, and use this convention:

      verb.extension

      Thus, the page to edit a bookmark is /bookmarks/edit.tcl.

    • For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module - use this @@ -89,8 +89,8 @@ explicitly name the index file (index.tcl, index.adp, index.html, etc.). Instead, use just the directory name, for both relative links (subdir/) and absolute links (/top-level-dir/). If linking to the directory in which the page is located, use the empty string -(""), which browsers will -resolve correctly.

      +(""), which browsers +will resolve correctly.

    File Headers and Page @@ -115,9 +115,9 @@ # www/register/user-login-2.tcl ad_page_contract { - Verify the user's password and issue the cookie. + Verify the user's password and issue the cookie. - \@param user_id The user's id in users table. + \@param user_id The user's id in users table. \@param password_from_from The password the user entered. \@param return_url What url to return to after successful login. \@param persistent_cookie_p Specifies whether a cookie should be set to keep the user logged in forever. @@ -140,10 +140,11 @@ particular, multiple and array are the flags that correspond to the old ad_page_variables flags.

  • There are new flags: trim, -notnull and optional. They do what you'd expect; values -will not be trimmed, unless you mark them for it; empty strings are -valid input, unless you specify notnull; and a specified variable -will be considered required, unless you declare it optional.

  • +notnull and optional. They do what you'd expect; +values will not be trimmed, unless you mark them for it; empty +strings are valid input, unless you specify notnull; and a +specified variable will be considered required, unless you declare +it optional.

  • ad_page_contract can do validation for you: the flags integer and sql_identifier will make sure that the values supplied are integers/sql_identifiers. The integer flag will also trim leading zeros. @@ -155,7 +156,7 @@

    • Using ad_library

    For shared Tcl library files, use ad_library after the file path comment. Its only argument is a doc_string in the standard (javadoc-style) format, like ad_page_contract. -Don't forget to put the \@cvs-id in there. Here is an example of +Don't forget to put the \@cvs-id in there. Here is an example of using ad_library:

     # tcl/wp-defs.tcl
 
@@ -169,15 +170,14 @@
 header structure is recommended:
     -- path relative to the ACS root directory
 --
--- brief description of the file's purpose
+-- brief description of the file's purpose
 --
 -- author
 -- created
 --
--- $‌Id$
-
    Of course, replace "--" with
-the comment delimiter appropriate for the language in which you are
-programming.
    
+-- $‌Id: eng-standards-filenaming.html,v 1.48.2.10 2016/06/21 07:44:36 gustafn Exp $
+

    Of course, replace "--" with the comment delimiter +appropriate for the language in which you are programming.

    Page Construction

    Construct the page as one Tcl variable (name it page_content), and then send it back to the @@ -210,17 +210,17 @@ valuable resource (namely, a database handle) for an unpredictable amount of time while sending packets back to the browser, and so it should be avoided in most cases. (On the other hand, for a page -that requires an expensive database query, it's better to call +that requires an expensive database query, it's better to call ad_return_top_of_page first, so that the user is not left to stare at an empty page while the query is running.)

    Local procedures (i.e., procedures defined and used only within -one page) should be prefixed with "module_" and should be used -rarely, only when they are exceedingly useful.

    +one page) should be prefixed with "module_" and should be +used rarely, only when they are exceedingly useful.

    Tcl Library Files

    Further standards for Tcl library files are under discussion; we -plan to include naming conventions for procs.

    ($‌Id: filenaming.xml,v 1.7 2014/10/27 16:39:31 -victorg Exp $)
    +plan to include naming conventions for procs.

    ($‌Id: eng-standards-filenaming.html,v 1.48.2.10 +2016/06/21 07:44:36 gustafn Exp $)

    • For naming files that enable a specific action on an object, use this format:

      object-verb.extension

      -For example, the page to erase a user's portrait from the database is +For example, the page to erase a user's portrait from the database is /admin/users/portrait-erase.tcl.

    • However, modules typically deal with only one primary type of object - e.g., -the Bookmarks module deals mainly with bookmarks - and so action-type files in modules don't need to be specified by the object they act on. Example: the user pages +the Bookmarks module deals mainly with bookmarks - and so action-type files in modules don't need to be specified by the object they act on. Example: the user pages for the Bookmarks module live in the /bookmarks/ directory, and so there is no need to name the bookmark editing page with a redundant url: /bookmarks/bookmark-edit.tcl. Instead, we omit the object type, and use this convention:

      @@ -104,9 +104,9 @@ # www/register/user-login-2.tcl ad_page_contract { - Verify the user's password and issue the cookie. + Verify the user's password and issue the cookie. - @param user_id The user's id in users table. + @param user_id The user's id in users table. @param password_from_from The password the user entered. @param return_url What url to return to after successful login. @param persistent_cookie_p Specifies whether a cookie should be set to keep the user logged in forever. @@ -128,7 +128,7 @@ e.g. foo:integer,multiple,trim. In particular, multiple and array are the flags that correspond to the old ad_page_variables flags.

    • There are new flags: trim, notnull and -optional. They do what you'd expect; values will not be +optional. They do what you'd expect; values will not be trimmed, unless you mark them for it; empty strings are valid input, unless you specify notnull; and a specified variable will be considered required, unless you declare it optional.

    • ad_page_contract can do validation for you: the flags integer @@ -144,7 +144,7 @@ For shared Tcl library files, use ad_library after the file path comment. Its only argument is a doc_string in the standard (javadoc-style) format, like -ad_page_contract. Don't forget to put the @cvs-id in +ad_page_contract. Don't forget to put the @cvs-id in there. Here is an example of using ad_library: 

       # tcl/wp-defs.tcl
@@ -160,7 +160,7 @@
 
       -- path relative to the ACS root directory
 --
--- brief description of the file's purpose
+-- brief description of the file's purpose
 --
 -- author
 -- created
@@ -206,7 +206,7 @@
 resource (namely, a database handle) for an unpredictable amount of
 time while sending packets back to the browser, and so it should be
 avoided in most cases. (On the other hand, for a page that requires an
-expensive database query, it's better to call
+expensive database query, it's better to call
 
 ad_return_top_of_page
 
Index: openacs-4/packages/acs-core-docs/www/eng-standards-plsql.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-plsql.adp,v
diff -u -N -r1.1.2.3 -r1.1.2.4
--- openacs-4/packages/acs-core-docs/www/eng-standards-plsql.adp	28 Sep 2015 07:54:14 -0000	1.1.2.3
+++ openacs-4/packages/acs-core-docs/www/eng-standards-plsql.adp	23 Jun 2016 08:32:45 -0000	1.1.2.4
@@ -25,8 +25,8 @@
 is maintainable by others, this is especially true in our case
 because we are building an open source toolkit than anyone can
 download and browse the source code. So document like you are
-trying to impress your "Introduction to Programming" professor or
-TA.

    • It is important to be consistent throughout an application as +trying to impress your "Introduction to Programming" +professor or TA.

    • It is important to be consistent throughout an application as much as is possible given the nature of team development. This means carrying style and other conventions suchs as naming within an application, not just within one file.

      • @@ -69,12 +69,13 @@ statements, i.e., the end statement for a package should be end <package_name>;, not just end;; same goes for procedures, functions, -package bodies, and triggers.

    • Always use the "show errors" SQL*Plus command after each PL/SQL -block. It will help you debug when there are compilation errors in -your PL/SQL code.

    • +package bodies, and triggers.

    • Always use the "show errors" SQL*Plus command after +each PL/SQL block. It will help you debug when there are +compilation errors in your PL/SQL code.

    • Name parameters as simply as possible, i.e., use the column name -if the parameter corresponds to a table column. We're deprecating -the v_* and *_in syntax in favor of named parameters notation:

      +if the parameter corresponds to a table column. We're
+deprecating the v_* and *_in syntax in favor of named parameters
+notation:
       
         acs_user.create(first_names => 'Jane', last_name => 'Doe', etc.)
       
@@ -107,11 +108,12 @@
         show errors
      
 
      
-

    • Explicitly designate each parameter as "in," "out," or -"inout."

    • Each parameter should be on its own line, with a tab after the +

    • Explicitly designate each parameter as "in," +"out," or "inout."

    • Each parameter should be on its own line, with a tab after the parameter name, then in/out/inout, then a space, and finally the -datatype.

    • Use %TYPE and %ROWTYPE whenever possible.

    • Use 't' and 'f' for booleans, not the PL/SQL "boolean" datatype -because it can't be used in SQL queries.

    • +datatype.

    • Use %TYPE and %ROWTYPE whenever possible.

    • Use 't' and 'f' for booleans, not the PL/SQL +"boolean" datatype because it can't be used in SQL +queries.

    • All new functions (e.g., acs_object.new, party.new, etc.) should optionally accept an ID:

      
@@ -140,8 +142,8 @@
 browsers. This means that we should try to make it as consistent as
 possible to all source code readers.

    • Lowercase everything, with the exception of %TYPE and %ROWTYPE.

      • -
    ($‌Id: plsql.xml,v 1.6 2006/07/17 05:38:37 -torbenb Exp $)
    +
    ($‌Id: eng-standards-plsql.html,v 1.49.2.10 +2016/06/21 07:44:36 gustafn Exp $)

  • Name parameters as simply as possible, i.e., use the column name - if the parameter corresponds to a table column. We're deprecating + if the parameter corresponds to a table column. We're deprecating the v_* and *_in syntax in favor of named parameters notation: 

     
@@ -117,7 +117,7 @@
     Use %TYPE and %ROWTYPE whenever possible.

  • Use 't' and 'f' for booleans, not the PL/SQL "boolean" datatype - because it can't be used in SQL queries. + because it can't be used in SQL queries.

  • All new functions (e.g., acs_object.new, party.new, etc.) should optionally accept an ID: Index: openacs-4/packages/acs-core-docs/www/eng-standards-versioning.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-versioning.adp,v diff -u -N -r1.1.2.3 -r1.1.2.4 --- openacs-4/packages/acs-core-docs/www/eng-standards-versioning.adp 28 Sep 2015 07:54:14 -0000 1.1.2.3 +++ openacs-4/packages/acs-core-docs/www/eng-standards-versioning.adp 23 Jun 2016 08:32:45 -0000 1.1.2.4 @@ -10,12 +10,13 @@

    Release Version Numbering

    -
    ($‌Id: eng-standards-versioning.xml,v 1.10 -2006/07/17 05:38:37 torbenb Exp $)

    By Ron Henderson, Revised by Joel Aufrecht

    +
    ($‌Id: eng-standards-versioning.html,v 1.51.2.10 +2016/06/21 07:44:36 gustafn Exp $)

    By Ron Henderson, Revised by Joel Aufrecht

    OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

    OpenACS version numbers help identify at a high-level what is in a particular release and what has changed since the last -release.

    A "version number" is really just a string of the form:

    +release.

    A "version number" is really just a string of the +form:

    major.minor.dot[ milestone ]

    • A major number change indicates a fundamental change in the architecture of the system, @@ -58,9 +59,9 @@

      Version numbers are also recorded in the CVS repository so that the code tree can be restored to the exact state it was in for a particular release. To translate between a distribution tar file -(acs-3.2.2.tar.gz) and a CVS tag, just swap '.' for '-'.The entire -release history of the toolkit is recorded in the tags for the -top-level readme.txt file:

      +(acs-3.2.2.tar.gz) and a CVS tag, just swap '.' for
+'-'.The entire release history of the toolkit is recorded
+in the tags for the top-level readme.txt file:
       > cvs log readme.txt
 RCS file: /usr/local/cvsroot/acs/readme.txt,v
 Working file: readme.txt
@@ -158,10 +159,10 @@
 incrementing the overall package version.

    • Use only the d, a, and b letters in OLDVERSION and NEWVERSION. rc is not supported by OpenACS APM.

    • The distance from OLDVERSION to NEWVERSION should never span a release. For example if we had a bug fix in acs-kernel on 5.1.0 you -wouldn't want a file upgrade-5.0.4-5.1.0d1.sql since if you +wouldn't want a file upgrade-5.0.4-5.1.0d1.sql since if you subsequently need to provide a 5.0.4-5.0.5 upgrade you will have to -rename the 5.0.4-5.1.0 upgrade since you can't have upgrades which -overlap like that. Instead, use upgrade-5.1.0d1-5.1.0d2.sql +rename the 5.0.4-5.1.0 upgrade since you can't have upgrades +which overlap like that. Instead, use upgrade-5.1.0d1-5.1.0d2.sql

    Index: openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html,v diff -u -N -r1.51.2.10 -r1.51.2.11 --- openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 21 Jun 2016 07:44:36 -0000 1.51.2.10 +++ openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 23 Jun 2016 08:32:45 -0000 1.51.2.11 @@ -88,7 +88,7 @@

    • Naming Database Upgrade Scripts

    Database upgrade scripts must be named very precisely in order for the Package Manager to run the correct script at the correct time.

    1. Upgrade scripts should be named /packages/myfirstpackage/sql/postgresql/upgrade/upgrade-OLDVERSION-NEWVERSION.sql

    2. If the version you are working on is a later version than the current released version, OLDVERSION should be the current version. The current version is package version in the APM and in /packages/myfirstpackage/myfirstpackage.info. So if forums is at 2.0.1, OLDVERSION should be 2.0.1d1. Note that this means that new version development that includes an upgrade must start at d2, not d1.

    3. If you are working on a pre-release version of a package, use the current package version as OLDVERSION. Increment the package version as appropriate (see above) and use the new version as NEWVERSION. For example, if you are working on 2.0.1d3, make it 2.0.1d4 and use upgrade-2.0.1d3-2.0.1d4.sql.

    4. Database upgrades should be confined to development releases, not alpha or beta releases.

    5. Never use a final release number as a NEWVERSION. If you do, then it is impossible to add any more database upgrades without incrementing the overall package version.

    6. Use only the d, a, and b letters in OLDVERSION and NEWVERSION. rc is not supported by OpenACS APM.

    7. The distance from OLDVERSION to NEWVERSION should never span a release. For example if we had a bug fix in -acs-kernel on 5.1.0 you wouldn't want a file upgrade-5.0.4-5.1.0d1.sql since if you subsequently need to provide a 5.0.4-5.0.5 upgrade you will have to rename the 5.0.4-5.1.0 upgrade since you can't have upgrades which overlap like that. Instead, use upgrade-5.1.0d1-5.1.0d2.sql +acs-kernel on 5.1.0 you wouldn't want a file upgrade-5.0.4-5.1.0d1.sql since if you subsequently need to provide a 5.0.4-5.0.5 upgrade you will have to rename the 5.0.4-5.1.0 upgrade since you can't have upgrades which overlap like that. Instead, use upgrade-5.1.0d1-5.1.0d2.sql

    Prev Home Next
    CVS Guidelines Up Constraint naming standard
    docs@openacs.org
    View comments on this page at openacs.org
    Index: openacs-4/packages/acs-core-docs/www/ext-auth-requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ext-auth-requirements.adp,v diff -u -N -r1.1.2.10 -r1.1.2.11 --- openacs-4/packages/acs-core-docs/www/ext-auth-requirements.adp 21 Jun 2016 07:44:36 -0000 1.1.2.10 +++ openacs-4/packages/acs-core-docs/www/ext-auth-requirements.adp 23 Jun 2016 08:32:45 -0000 1.1.2.11 @@ -12,41 +12,42 @@ External Authentication Requirements

    -Vision

    People have plenty of usernames and passwords already, we don't -want them to have yet another. We want people to be able to log in -to OpenACS with the same password they use to log in to any other -system.

    Besides, administrators have better things to do than create +Vision

    People have plenty of usernames and passwords already, we +don't want them to have yet another. We want people to be able +to log in to OpenACS with the same password they use to log in to +any other system.

    Besides, administrators have better things to do than create accounts for people. So we want them to be able to create just one account on a central server (e.g. LDAP or RADIUS), and when they log on to OpenACS, an account will automatically be created for them here.

    Finally, security is increased with fewer passwords, since users -generally can't remember all those passwords, so they tend to keep -them all the same and never change them.

    +generally can't remember all those passwords, so they tend to +keep them all the same and never change them.

    Design Goals

      -

    • Transparent: Users don't have to do anything special to get an -account on the local OpenACS system, if they already have an -account on the external authentication server.

    • Fall-back: Users who don't have an account on the external +

    • Transparent: Users don't have to do anything special to get +an account on the local OpenACS system, if they already have an +account on the external authentication server.

    • Fall-back: Users who don't have an account on the external authentication server are still allowed to create a local account on OpenACS. This could be for external students who should have -access to .LRN, but not to the rest of the university's +access to .LRN, but not to the rest of the university's resources.

    • Authentication Client Only: We want OpenACS to be able to -authenticate by asking some remote authority to verify the user's -username/password combination. The goal is explicitly not (at this point) to have OpenACS act -as an authentication server for other systems, although this could -be easily added later. The goal is also not to devise an infrastructure for +authenticate by asking some remote authority to verify the +user's username/password combination. The goal is explicitly +not (at this point) to have +OpenACS act as an authentication server for other systems, although +this could be easily added later. The goal is also not to devise an infrastructure for letting OpenACS access resources in various other systems on the -user's behalf, such as IMAP, iCalendar, SMB file servers, etc., +user's behalf, such as IMAP, iCalendar, SMB file servers, etc., although this is definitely an interesting use-case.

    • Easy configuration: We would like people to be able to configure this without having to write code. In particular, we want to build drivers that know how to talk with LDAP, RADIUS, PAM, etc., and -which won't have to be locally modified. Only configuration and +which won't have to be locally modified. Only configuration and policies should change, code should not.

    • Usability: The solution must be easy to use for end users and -administrators alike. There's frequently a positive feedback effect -between usability and security, because when authentication schemes -have poor usability, users will think up ways to circumvent +administrators alike. There's frequently a positive feedback +effect between usability and security, because when authentication +schemes have poor usability, users will think up ways to circumvent them.

    • Open and modular: The design should be on the one hand open to add other authentification mechanisms when needed and on the other hand very modular to enable a start with minimal requirements @@ -60,9 +61,9 @@ users.

    • Authentication Driver: An implementation of the authentication service contract, which talks to an authentication of a certain type, e.g. PAM, RADIUS, LDAP, or Active Directory.

    • Authentication API: The API through which login pages and -applications talk to the authentication service. There's one and -only one implementation of the authentication API, namly the one -included in OpenACS Core.

    • Authentication Driver API: The service contract which +applications talk to the authentication service. There's one +and only one implementation of the authentication API, namly the +one included in OpenACS Core.

    • Authentication Driver API: The service contract which authentication drivers implement.

    @@ -110,18 +111,18 @@

    Users will log in using a username, a authority, and a password. The authority is the source for user/password verification. OpenACS can be an authority itself.

    Each user in OpenACS will belong to exactly one authority, which -can either be the "local" OpenACS users table, in which case the -password column is used, or it can be some external authority, -which will be communicated with using some protocol, as implemented -by an authentication driver.

    Username will be separate from email address. It can be an email +can either be the "local" OpenACS users table, in which +case the password column is used, or it can be some external +authority, which will be communicated with using some protocol, as +implemented by an authentication driver.

    Username will be separate from email address. It can be an email address, it can look like an email address but not be the name of -an actual email mailbox, or it can be something else entirely.

    We're assuming that user information (name, email, etc.) will -either already be in the users table through a batch +an actual email mailbox, or it can be something else entirely.

    We're assuming that user information (name, email, etc.) +will either already be in the users table through a batch synchronization job, or that the relevant authentication implementation supports real-time synchronization of user data. -Specifically, if you want remote users who haven't yet logged in to -OpenACS to show up in user searches, you'll have to do the batch -synchronization.

    All in all, the login box will be an includeable template and +Specifically, if you want remote users who haven't yet logged +in to OpenACS to show up in user searches, you'll have to do +the batch synchronization.

    All in all, the login box will be an includeable template and look like this:

     Username:  ________
 Password:  ________
@@ -131,8 +132,8 @@
 
 [Forgot my password]
 [New user registration]
-

    If there's only one active authority, we don't display the -authority drop-down element at all.

    +

    If there's only one active authority, we don't display +the authority drop-down element at all.

    Configuration

    @@ -146,11 +147,11 @@

  • Authorities - ordered list of authorities defined

  • Account Registration Allowed: Yes/No. Account registration can be disabled altogether.

  • Registration authority - the authority in which accounts should be created, using the relevant driver, if account registration is -allowed.

  • Username is email? - instead of asking for username, we'll ask -for email. And we'll store the value in both columns, username and -email. This is a setting that spans all authorities, and is -primarily meant for backwards compatibility with the old OpenACS -login process.

    • +allowed.

  • Username is email? - instead of asking for username, we'll +ask for email. And we'll store the value in both columns, +username and email. This is a setting that spans all authorities, +and is primarily meant for backwards compatibility with the old +OpenACS login process.

    • The local authority driver is an encapsulation of current functionality within an driver matching a service contract. The other drivers call external functions. The possible functions for @@ -175,20 +176,22 @@

    EXT-AUTH-18AAuthority configuration data model

    Each authority is defined like this:

      -

    • Authority pretty-name, e.g. "URZ"

    • Authentication Driver, e.g. "RADIUS". In practice, this would be -a reference to a service contract implementation.

    • Authentication Driver configuration settings, e.g. host name, +

    • Authority pretty-name, e.g. "URZ"

    • Authentication Driver, e.g. "RADIUS". In practice, +this would be a reference to a service contract implementation.

    • Authentication Driver configuration settings, e.g. host name, port, etc., as required by the particular driver. Note that this is per authority, not per driver, i.e., you can have multiple authorities with the same driver but different configuration options.

    • AuthenticationAllowed - true/false, so you can disable login through some authority without having to delete the authority, and hence also all the users who belong to that authority.

    • ForgottenPasswordUrl - a URL to redirect to instead of trying to -use the authentication driver's password management features.

    • ChangePasswordUrl - a URL to redirect to instead of trying to -use the authentication driver's password management features.

    • Account Creation Driver, e.g. "RADIUS". In practice, this would -be a reference to a service contract implementation. The reason we -have separate drivers for authentication and account creation is -that organizations are likely to have a home-grown account -registration process.

    • Account Creation Driver configuration settings, e.g. host name, +use the authentication driver's password management +features.

    • ChangePasswordUrl - a URL to redirect to instead of trying to +use the authentication driver's password management +features.

    • Account Creation Driver, e.g. "RADIUS". In practice, +this would be a reference to a service contract implementation. The +reason we have separate drivers for authentication and account +creation is that organizations are likely to have a home-grown +account registration process.

    • Account Creation Driver configuration settings, e.g. host name, port, etc., as required by the particular driver. Note that this is per authority, not per driver, i.e., you can have multiple authorities with the same driver but different configuration @@ -202,9 +205,9 @@ find a mechanism for the driver to tell us which configuration options are available, a way to set these, and a way for the driver to access these settings.

      OpenACS will come pre-configured with one authority, which is -the "local" authority, meaning we'll authenticate as normal using -the local users table. This will, just like any other authority, be -implemetned using a service contract.

      +the "local" authority, meaning we'll authenticate as +normal using the local users table. This will, just like any other +authority, be implemetned using a service contract.

    Synchronizing and Linking @@ -230,55 +233,58 @@ Enterprise 1.1 specification.

    Batch job means that we do a synchronization (import new users, modify changed, purge deleted) on a regular interval, e.g. every night. You can also decide to have a monthly full synchronization, -plus daily incremental ones. That's up to you. The advantage is +plus daily incremental ones. That's up to you. The advantage is that you have all users in OpenACS, so when you search for a user, -you'll see all the organization's users, not just those who happen -to have used the OpenACS-based system. The down-side is that it -takes some time for user information to propagate. This can be +you'll see all the organization's users, not just those who +happen to have used the OpenACS-based system. The down-side is that +it takes some time for user information to propagate. This can be remedied by using the real-time solution. The batch job will also require error logging and an admin interface to view logs.

    If an email already belongs to some other user, we log it as an error.

    A user will always belong to exactly one authority, which can be -either the "local" authority or some other. Thus, the OpenACS -user's table will have to be augmented with the following -columns:

      +either the "local" authority or some other. Thus, the +OpenACS user's table will have to be augmented with the +following columns:

      • Authority. Reference to the site-wide authorities list. The authority which can authenticate this user.

      • Authority-specific username.

      Real-time means that the first time the user logs into OpenACS, -we'll query the authority that authenticated him for information -about this user. That authentication authority will then give us at -least first names, last name and email. The pros and cons are the -opposite of batch jobs. Using both in combination is ideal.

      Note: One solution to the "two users from different authorities -have the same email" problem above would be to allow users to -belong to multiple authorities. Then we would notice that the email -already exists, ask the user if he thinks he's the same person, and -if so, ask him to prove so by authenticating using the other -authority. Thus he'll have just authenticated in two different -authorities, and we can record that this is the same person. We'd -still have a problem if there was an email conflict between two -accounts on the same authority. Hm. I don't think it's worth -spending too much time trying to solve this problem through -software.

      +we'll query the authority that authenticated him for +information about this user. That authentication authority will +then give us at least first names, last name and email. The pros +and cons are the opposite of batch jobs. Using both in combination +is ideal.

      Note: One solution to the "two users from different +authorities have the same email" problem above would be to +allow users to belong to multiple authorities. Then we would notice +that the email already exists, ask the user if he thinks he's +the same person, and if so, ask him to prove so by authenticating +using the other authority. Thus he'll have just authenticated +in two different authorities, and we can record that this is the +same person. We'd still have a problem if there was an email +conflict between two accounts on the same authority. Hm. I +don't think it's worth spending too much time trying to +solve this problem through software.

      FeatureStatusDescription
      EXT-AUTH-31
      EXT-AUTH-31AUpgrade user data model for ext-auth

      After having authenticated using the relevant authority driver, -we'll look for the username/authority pair in the users table.

      If we don't find any, that means that we're either not doing -batch synchronizing, or that the user has been added since the last -sync. In that case, we'll try to do a real-time synchronization, if -the driver supports it. If it does, it'll return email, -first_names, last_name, and other relevant information, and we'll -create a row in the local users table using that information.

      If that doesn't work, we'll tell the user that their account -isn't yet available, and the driver will supply a message for us, -which could say "The account should be available tomorrow. If not, -contact X."

      +we'll look for the username/authority pair in the users +table.

      If we don't find any, that means that we're either not +doing batch synchronizing, or that the user has been added since +the last sync. In that case, we'll try to do a real-time +synchronization, if the driver supports it. If it does, it'll +return email, first_names, last_name, and other relevant +information, and we'll create a row in the local users table +using that information.

      If that doesn't work, we'll tell the user that their +account isn't yet available, and the driver will supply a +message for us, which could say "The account should be +available tomorrow. If not, contact X."

    -Account Registration

    If a user doesn't have an account, the site-wide configuration -can allow the user to register for one, as defined in the -configuration discussed above. This section is about normal account -registration through a authority driver.

    The account creation service contract implementation will need +Account Registration

    If a user doesn't have an account, the site-wide +configuration can allow the user to register for one, as defined in +the configuration discussed above. This section is about normal +account registration through a authority driver.

    The account creation service contract implementation will need to tell us which information to ask the user for:

    • Required Fields: A list of fields which are required.

    • Optional Fields: A list of fields which are optional.

    The fields to choose from are these:

      @@ -287,8 +293,8 @@

    • Creation status (OK, Try-Again, Fail)

    • Creation message: What went wrong, or a welcome message.

    • Account status: Is the account ready for use?

    • User information: first_names, last_name, email, url, password, password_hash, secret_question, secret_answer. The driver only needs to return the columns which were changed or added through the -registration process. Typically, only the "local" driver will -return password and secret question/answer.

      • +registration process. Typically, only the "local" driver +will return password and secret question/answer.

    After creating the remote account, a local account is created with the information gathered through the form/returned by the driver.

    By default, a local account creation implementation is provided, @@ -298,9 +304,9 @@

    Password Management

    Password management is about changing password, retrieving -password, and resetting password.

    It's up to the authority driver implementation to decide whether -to support any or all of these features, and to say so using the -CanXXX methods (see driver API below).

    Additionally, the authority can be configured with a URL to +password, and resetting password.

    It's up to the authority driver implementation to decide +whether to support any or all of these features, and to say so +using the CanXXX methods (see driver API below).

    Additionally, the authority can be configured with a URL to redirect to in the case of forgotten passwords, or when the user desires to change password.

    @@ -312,30 +318,30 @@ EXT-AUTH-20ALogin over HTTPS

    Login pages must be able to be sent over a secure connection -(https), so your password won't get sent over the wire in +(https), so your password won't get sent over the wire in cleartext, while leaving the rest of the site non-secure (http). I believe that this requires some (minor) changes to the current session handling code.

    Email Verification

    Email verification needs to be handled both at registration and -at login.

    In both cases, it'll be handled by the driver sending +at login.

    In both cases, it'll be handled by the driver sending automatically sending the email containing a link for the user to verify his account. Then the driver will return an account status -of "closed,temporary", and a message that says "Check your inbox -and click the link in the email".

    OpenACS will have a page which receives the email verification, +of "closed,temporary", and a message that says +"Check your inbox and click the link in the email".

    OpenACS will have a page which receives the email verification, for use by local accounts. Other authorities will have to implement -their own page, most likely on the authority's own server.

    +their own page, most likely on the authority's own server.

    Other Items

    There are a number of items which touch on external -authentication and session management. And even though they're not -directly linked to external authentication, I would recommend that -we handle a number of them, either because they're important for -security, or because it makes sense to fix them while we're messing -with this part of the codebase anyway.

    +authentication and session management. And even though they're +not directly linked to external authentication, I would recommend +that we handle a number of them, either because they're +important for security, or because it makes sense to fix them while +we're messing with this part of the codebase anyway.

    Recommended: Untrusted Logins and Login Levels

    @@ -345,27 +351,27 @@
    EXT-AUTH-33AUntrusted Logins

    I like the idea of having multiple login levels:

      -

    1. Not logged in

    2. Untrusted login: We'll show you un-sensitive personal content, -but won't let you modify anything or see personal data. A normal -login becomes untrusted after a certain amount of time, and the -user will have to re-enter his/her password in order to gain access -to personal data. Untrusted login never expires, unless explicitly -done so through either changing password or clicking a special -"expire all logins" link.

    3. Normal login: The user is logged, and has type his password +

    4. Not logged in

    5. Untrusted login: We'll show you un-sensitive personal +content, but won't let you modify anything or see personal +data. A normal login becomes untrusted after a certain amount of +time, and the user will have to re-enter his/her password in order +to gain access to personal data. Untrusted login never expires, +unless explicitly done so through either changing password or +clicking a special "expire all logins" link.

    6. Normal login: The user is logged, and has type his password sufficiently recently that we trust the login. All normal operations are allowed. Will degrade to untrusted login after a specified amount of time.

    7. Secure login: The user is logged in over a secure connection (HTTPS), potentially even using a special secure password. This would be for sensitive actions, such as credit card transactions.

      8. -

    There are two advantages to this. First, when people's login +

    There are two advantages to this. First, when people's login expires, we can ask them to re-enter only their password, and not -both username and password, since we'll still remember who they +both username and password, since we'll still remember who they were the last time their login was valid. This is a much faster operation (the password input field will be focused by default, so you just type your password and hit Return) that typing both username and password, which will make it practical to have your -site configured to expire people's login after e.g. 2, 4, or 8 +site configured to expire people's login after e.g. 2, 4, or 8 hours.

    The other advantage is that we can still offer certain functionality to you, even when your login is not trusted. For example, we could let you browse publically available forums, and @@ -374,9 +380,10 @@ setting.

    By default, auth::require_login would bounce to the login page if the user is only logged in at the untrusted level. Only if you explicitly say auth::require_login -untrusted will we give you -the user_id of a user who's only logged in in untrusted mode.

    Similarly, ad_conn user_id will +the user_id of a user who's only logged in in untrusted +mode.

    Similarly, ad_conn user_id will continue to return 0 (not logged in) when the user is only logged -in untrusted, and we'll supply another variable, ad_conn untrusted_user_id, which wlll be set to +in untrusted, and we'll supply another variable, ad_conn untrusted_user_id, which wlll be set to the user_id for all login levels.

    This should ensure that we get full access to the new feature, while leaving all current code just as secure as it was before.

    @@ -390,15 +397,15 @@

    Currently, OpenACS is unusable in practice without persistent login. The login will expire after just a few minutes of -inactivity, and you'll get bounced to the login page where you have -to enter both email and password again. Unacceptable in -practice.

    We should change the default, so a non-persistent login doesn't -expire until you either close your browser, or a few hours have -elapsed. Even if you are constantly active, the login should still -expire after at most x number of hours. We can still make the login -expire after a period of inactivity, but the amount of time should -be configurable and default to something reasonable like an hour or -so.

    This will require looking into and changing the design of the +inactivity, and you'll get bounced to the login page where you +have to enter both email and password again. Unacceptable in +practice.

    We should change the default, so a non-persistent login +doesn't expire until you either close your browser, or a few +hours have elapsed. Even if you are constantly active, the login +should still expire after at most x number of hours. We can still +make the login expire after a period of inactivity, but the amount +of time should be configurable and default to something reasonable +like an hour or so.

    This will require looking into and changing the design of the current session handling code.

    @@ -413,8 +420,8 @@ to a page that logs the user in. This should be very easy to implement.

    Alternatively, if you want to combine this with fallback to OpenACS accounts, we would instead present the normal login screen, -but put a button which says "Login using X", where X is the -redirection-based external authority.

    +but put a button which says "Login using X", where X is +the redirection-based external authority.

    Recommended: Expire All @@ -424,22 +431,22 @@ EXT-AUTH-22 EXT-AUTH-22Brewrite cookie handling -

    Currently, if you've ever left a permanent login cookie on +

    Currently, if you've ever left a permanent login cookie on someone elses machine, that person will be forever logged in until he/she explicitly logs out. You can change your password, you can do anything you want, but unless a logout is requested from that particular browser, that browser will be logged in forever.

    I want to change our session handling code so that old login cookies can be expired. This would be done automatically whenever you change your password, and we could also offer a link which does -this without changing passwords. It's an important security +this without changing passwords. It's an important security measure.

    The implementation is simply to autogenerate some secret token which is stored in the users table, and is also stored in the -cookie somehow. Then, whenever we want to expire all logins, we'll -just regenerate a new secret token, and the other cookies will be -void. Of course, we don't want to incur a DB hit on every request, -so we'll need to cache the secret token, or only check it when -refreshing the session cookie, which, I believe, normally happens -every 10 minutes or so.

    +cookie somehow. Then, whenever we want to expire all logins, +we'll just regenerate a new secret token, and the other cookies +will be void. Of course, we don't want to incur a DB hit on +every request, so we'll need to cache the secret token, or only +check it when refreshing the session cookie, which, I believe, +normally happens every 10 minutes or so.

    Recommended: @@ -449,9 +456,9 @@ EXT-AUTH-24 EXT-AUTH-24AEmail on password change -

    As an additional security measure, we should email the account's -email address whenever the password is changed, so that he/she is -at least alerted to the fact.

    +

    As an additional security measure, we should email the +account's email address whenever the password is changed, so +that he/she is at least alerted to the fact.

    Optional: Password policy

    @@ -476,28 +483,30 @@ -
    EXT-AUTH-26
    EXT-AUTH-26BLogin without explicit domain

    In order to make it easier for people, we've been toying with -the idea of a functionality like this:

      -

    • If the user enters "foobar\@ix.urz.uni-heidelberg.de", it is -translated to mean username = "foobar", authority = -"ix.urz.uni-heidelberg.de".

    • If the user enters "foobar", it's recognized to not include any -authority, and the default authority of "ix.urz.uni-heidelberg.de" -is used.

    • If the user enters "foo\@bar.com", it's recognized as not -belonging to any known authority, and as such, it's translated to -mean username = "foo\@bar.com", authority = "local".

      • +

    In order to make it easier for people, we've been toying +with the idea of a functionality like this:

      +

    • If the user enters "foobar\@ix.urz.uni-heidelberg.de", +it is translated to mean username = "foobar", authority = +"ix.urz.uni-heidelberg.de".

    • If the user enters "foobar", it's recognized to +not include any authority, and the default authority of +"ix.urz.uni-heidelberg.de" is used.

    • If the user enters "foo\@bar.com", it's recognized +as not belonging to any known authority, and as such, it's +translated to mean username = "foo\@bar.com", authority = +"local".

    If this is deemed desirable, a way to implement this would be through these settings:

      -

    • Split: A regexp which will split the user's entry into username -and authority parts. For example "^([^\@]+)(\@[^\@]+)?$". An easier to -use but less flexible method would be that you simply specify a -certain character to split by, such as "\@" or "\". If the regexp -doesn't match, or in the latter case, if there's more than one -occurrence of the specified character sequence, the split will -fail, signaling that the user's entry was not valid.

    • Default authority: The default authority will be the first one +

    • Split: A regexp which will split the user's entry into +username and authority parts. For example +"^([^\@]+)(\@[^\@]+)?$". An easier to use but less flexible +method would be that you simply specify a certain character to +split by, such as "\@" or "\". If the regexp +doesn't match, or in the latter case, if there's more than +one occurrence of the specified character sequence, the split will +fail, signaling that the user's entry was not valid.

    • Default authority: The default authority will be the first one in the sort order.

    The relevant code in user-login.tcl would look like this:

     if { ![auth::split_username -username_var username -authority_var authority] } {
-    # bounce back to the form with a message saying that the login wasn't valid.
+    # bounce back to the form with a message saying that the login wasn't valid.
     ad_script_abort
 }
 
@@ -506,24 +515,27 @@

    -Optional: Who's Online

    +Optional: Who's Online
    - + -
    FeatureStatusDescription
    EXT-AUTH-27
    EXT-AUTH-27BWho's online listEXT-AUTH-27BWho's online list

    While we're touching the session handling code, anyway, it would -be nice to add a feature to show who's currently online, a nice -real-time collaboration feature frequently requested by members of -the community. This is particularly interesting when integrated -with a chat or instant messaging service like Jabber.

    What I'm concretely suggesting is that we keep a record of which -authenticated users have requested pags on the site in the last x -minutes (typically about 5), and thus are considered to be -currently online. There's nothing more to it. This lets us display -a list of "active users" somewhere on the site, and make their name -a link to a real-time chat service like Jabber.

    We've already made the changes necessary to security-procs.tcl -to do this on an earlier project, but haven't quite finished the -work and put it back into the tree.

    +

    While we're touching the session handling code, anyway, it +would be nice to add a feature to show who's currently online, +a nice real-time collaboration feature frequently requested by +members of the community. This is particularly interesting when +integrated with a chat or instant messaging service like +Jabber.

    What I'm concretely suggesting is that we keep a record of +which authenticated users have requested pags on the site in the +last x minutes (typically about 5), and thus are considered to be +currently online. There's nothing more to it. This lets us +display a list of "active users" somewhere on the site, +and make their name a link to a real-time chat service like +Jabber.

    We've already made the changes necessary to +security-procs.tcl to do this on an earlier project, but +haven't quite finished the work and put it back into the +tree.

    Optional: @@ -537,7 +549,7 @@ login process for that particular subsite. This would probably only entail letting the subsite admin leave out certain authorities defined site-wide, and change the sort order.

    I think we should leave this out until we have a use case for -it, someone who'd need it.

    +it, someone who'd need it.

    Future: Making @@ -552,8 +564,8 @@

    For completely free-form authentication logic and mechanisms, -something like Andrew Grumet's Pluggable Authentication for OACS Draft is -interesting. He's proposing a scheme where the entire user +something like Andrew Grumet's Pluggable Authentication for OACS Draft is +interesting. He's proposing a scheme where the entire user interaction is encapsulated in, and left entirely to, a service contract. This certainly opens up more advanced possibilities, such as perhaps smart cards, personal certificates, etc.

    I have chosen not to go this route, because I think that most @@ -574,17 +586,17 @@

    Both OKI and OpenACS supports a form of stacking, where you can be logged into multiple authorities at the same time. This is useful if, for example, you need to get login tokens such as -Kerberos tickets for access to shared resources.

    I can see the value in this, but for simplicity's sake, I'm in -favor of keeping this use-case out of the loop until we have -someone with a real requirement who could help us guide +Kerberos tickets for access to shared resources.

    I can see the value in this, but for simplicity's sake, +I'm in favor of keeping this use-case out of the loop until we +have someone with a real requirement who could help us guide development.

    For now, OpenACS is still more of an integrated suite, it -doesn't access many outside applications. I think it would be +doesn't access many outside applications. I think it would be excellent for OpenACS to do so, e.g. by using an IMAP server to store emails, an iCal server to store calendar appointments, LDAP for user/group data and access control lists, SMB for file storage, -etc. But at the moment, we don't have any users of such things that -are ready. We have some who are on the steps, but let's wait till -they're there.

    +etc. But at the moment, we don't have any users of such things +that are ready. We have some who are on the steps, but let's +wait till they're there.

    Implement Specific Drivers

    @@ -608,27 +620,29 @@ -
    EXT-AUTH-14ACreate Auth. driver for LDAP

    We'll need drivers for:

      +

    We'll need drivers for:

    • Operating system (Linux/Solaris) PAM: Delegate to the operating system, which can then talk to RADIUS, LDAP, whatever. This is -convenient because there'll be plenty of drivers for the OS PAM -level, so we don't have to write them all ourselves. The downside -is that we can't do things like account creation, password -management, real-time account synchronization, etc., not supported -by PAM (I'm not entirely sure what is and is not supported).

    • RADIUS

    • LDAP

      • +convenient because there'll be plenty of drivers for the OS PAM +level, so we don't have to write them all ourselves. The +downside is that we can't do things like account creation, +password management, real-time account synchronization, etc., not +supported by PAM (I'm not entirely sure what is and is not +supported).

    • RADIUS

    • LDAP

    RADIUS

    RADIUS is a simple username/password-type authentication server.

    It also supports sending a challenge to which the user must -respond with the proper answer (e.g. mother's maiden name, or could -be additional password), but we will not support this feature.

    A RADIUS client implementation in Python can be found in the +respond with the proper answer (e.g. mother's maiden name, or +could be additional password), but we will not support this +feature.

    A RADIUS client implementation in Python can be found in the exUserFolder module for Zope (documentation).

    -Feedback

    We'd really appreciate feedback on this proposal. Please follow -up at this openacs.org forums thread.

    +Feedback

    We'd really appreciate feedback on this proposal. Please +follow up at this openacs.org forums thread.

    References

      Index: openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html,v diff -u -N -r1.40.2.10 -r1.40.2.11 --- openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 21 Jun 2016 07:44:36 -0000 1.40.2.10 +++ openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 23 Jun 2016 08:32:45 -0000 1.40.2.11 @@ -1,34 +1,34 @@ External Authentication Requirements
      Alex logo
      Prev Chapter 15. Kernel Documentation Next

      External Authentication Requirements

      Vision

      People have plenty of usernames and passwords already, we -don't want them to have yet another. We want people to be able to +don't want them to have yet another. We want people to be able to log in to OpenACS with the same password they use to log in to any other system.

      Besides, administrators have better things to do than create accounts for people. So we want them to be able to create just one account on a central server (e.g. LDAP or RADIUS), and when they log on to OpenACS, an account will automatically be created for them here.

      Finally, security is increased with fewer passwords, since -users generally can't remember all those passwords, so they tend to -keep them all the same and never change them.

      Design Goals

      • Transparent: Users don't have to do anything special to +users generally can't remember all those passwords, so they tend to +keep them all the same and never change them.

      Design Goals

      • Transparent: Users don't have to do anything special to get an account on the local OpenACS system, if they already have an - account on the external authentication server.

      • Fall-back: Users who don't have an account on the + account on the external authentication server.

      • Fall-back: Users who don't have an account on the external authentication server are still allowed to create a local account on OpenACS. This could be for external students who should - have access to .LRN, but not to the rest of the university's + have access to .LRN, but not to the rest of the university's resources.

      • Authentication Client Only: We want OpenACS to be able to - authenticate by asking some remote authority to verify the user's + authenticate by asking some remote authority to verify the user's username/password combination. The goal is explicitly not (at this point) to have OpenACS act as an authentication server for other systems, although this could be easily added later. The goal is also not to devise an infrastructure for letting OpenACS access - resources in various other systems on the user's behalf, such as + resources in various other systems on the user's behalf, such as IMAP, iCalendar, SMB file servers, etc., although this is definitely an interesting use-case.

      • Easy configuration: We would like people to be able to configure this without having to write code. In particular, we want to build drivers that know how to talk with LDAP, RADIUS, PAM, - etc., and which won't have to be locally modified. Only + etc., and which won't have to be locally modified. Only configuration and policies should change, code should not.

      • Usability: The solution must be easy to use for end users - and administrators alike. There's frequently a positive feedback + and administrators alike. There's frequently a positive feedback effect between usability and security, because when authentication schemes have poor usability, users will think up ways to circumvent them.

      • Open and modular: The design should be on the one hand @@ -41,7 +41,7 @@ authentication service contract, which talks to an authentication of a certain type, e.g. PAM, RADIUS, LDAP, or Active Directory.

      • Authentication API: The API through which login pages and - applications talk to the authentication service. There's one and + applications talk to the authentication service. There's one and only one implementation of the authentication API, namly the one included in OpenACS Core.

      • Authentication Driver API: The service contract which authentication drivers implement.

      Conceptual Pictures

      Authentication:

      @@ -54,12 +54,12 @@ by an authentication driver.

      Username will be separate from email address. It can be an email address, it can look like an email address but not be the name of an actual email mailbox, or it can be something else -entirely.

      We're assuming that user information (name, email, etc.) will +entirely.

      We're assuming that user information (name, email, etc.) will either already be in the users table through a batch synchronization job, or that the relevant authentication implementation supports real-time synchronization of user data. -Specifically, if you want remote users who haven't yet logged in to -OpenACS to show up in user searches, you'll have to do the batch +Specifically, if you want remote users who haven't yet logged in to +OpenACS to show up in user searches, you'll have to do the batch synchronization.

      All in all, the login box will be an includeable template and look like this:

       Username:  ________
@@ -70,13 +70,13 @@
 
 [Forgot my password]
 [New user registration]
-

      If there's only one active authority, we don't display the +

      If there's only one active authority, we don't display the authority drop-down element at all.

      Configuration

      FeatureStatusDescription
      Configuration
      EXT-AUTH-07AAdmin pages to control Ext-Auth parameters

      The site-wide systems administrator can configure the authentication process from a page linked under /acs-admin.

      • Authorities - ordered list of authorities defined

      • Account Registration Allowed: Yes/No. Account registration can be disabled altogether.

      • Registration authority - the authority in which accounts should be created, using the relevant driver, if account registration is allowed.

      • Username is email? - instead of asking for username, - we'll ask for email. And we'll store the value in both columns, + we'll ask for email. And we'll store the value in both columns, username and email. This is a setting that spans all authorities, and is primarily meant for backwards compatibility with the old OpenACS login process.

      The local authority driver is an encapsulation of current @@ -93,9 +93,9 @@ options.

    • AuthenticationAllowed - true/false, so you can disable login through some authority without having to delete the authority, and hence also all the users who belong to that authority.

    • ForgottenPasswordUrl - a URL to redirect to instead of - trying to use the authentication driver's password management + trying to use the authentication driver's password management features.

    • ChangePasswordUrl - a URL to redirect to instead of - trying to use the authentication driver's password management + trying to use the authentication driver's password management features.

    • Account Creation Driver, e.g. "RADIUS". In practice, this would be a reference to a service contract implementation. The reason we have separate drivers for authentication and account @@ -114,50 +114,50 @@ find a mechanism for the driver to tell us which configuration options are available, a way to set these, and a way for the driver to access these settings.

      OpenACS will come pre-configured with one authority, which is -the "local" authority, meaning we'll authenticate as normal using the +the "local" authority, meaning we'll authenticate as normal using the local users table. This will, just like any other authority, be implemetned using a service contract.

      • Synchronizing and Linking Users

      FeatureStatusDescription
      Synchronizing and linking users
      EXT-AUTH-28ACreate service contract for Batch Sync.
      EXT-AUTH-38ABatch User Synchronization API
      EXT-AUTH-38AIMS Synchronization driver
      EXT-AUTH-08AAutomation of batch Synchronization
      EXT-AUTH-15BOn-demand syncronization

      Regardless of the login method, the user needs to have a row in the OpenACS users table. This can happen through a batch job, in real-time, or both in combination. We use the IMS Enterprise 1.1 specification.

      Batch job means that we do a synchronization (import new users, modify changed, purge deleted) on a regular interval, e.g. every night. You can also decide to have a monthly full -synchronization, plus daily incremental ones. That's up to you. The +synchronization, plus daily incremental ones. That's up to you. The advantage is that you have all users in OpenACS, so when you search -for a user, you'll see all the organization's users, not just those +for a user, you'll see all the organization's users, not just those who happen to have used the OpenACS-based system. The down-side is that it takes some time for user information to propagate. This can be remedied by using the real-time solution. The batch job will also require error logging and an admin interface to view logs.

      If an email already belongs to some other user, we log it as an error.

      A user will always belong to exactly one authority, which can be -either the "local" authority or some other. Thus, the OpenACS user's +either the "local" authority or some other. Thus, the OpenACS user's table will have to be augmented with the following columns:

      • Authority. Reference to the site-wide authorities list. The authority which can authenticate this user.

      • Authority-specific username.

      Real-time means that the first time the user logs into -OpenACS, we'll query the authority that authenticated him +OpenACS, we'll query the authority that authenticated him for information about this user. That authentication authority will then give us at least first names, last name and email. The pros and cons are the opposite of batch jobs. Using both in combination is ideal.

      Note: One solution to the "two users from different authorities have the same email" problem above would be to allow users to belong to multiple authorities. Then we would notice that the email -already exists, ask the user if he thinks he's the same person, and +already exists, ask the user if he thinks he's the same person, and if so, ask him to prove so by authenticating using the other -authority. Thus he'll have just authenticated in two different -authorities, and we can record that this is the same person. We'd still +authority. Thus he'll have just authenticated in two different +authorities, and we can record that this is the same person. We'd still have a problem if there was an email conflict between two accounts -on the same authority. Hm. I don't think it's worth spending too much +on the same authority. Hm. I don't think it's worth spending too much time trying to solve this problem through software.

      FeatureStatusDescription
      EXT-AUTH-31
      EXT-AUTH-31AUpgrade user data model for ext-auth

      After having authenticated using the relevant authority driver, -we'll look for the username/authority pair in the users table.

      If we don't find any, that means that we're either not doing +we'll look for the username/authority pair in the users table.

      If we don't find any, that means that we're either not doing batch synchronizing, or that the user has been added since the last -sync. In that case, we'll try to do a real-time synchronization, if -the driver supports it. If it does, it'll return email, -first_names, last_name, and other relevant information, and we'll +sync. In that case, we'll try to do a real-time synchronization, if +the driver supports it. If it does, it'll return email, +first_names, last_name, and other relevant information, and we'll create a row in the local users table using that -information.

      If that doesn't work, we'll tell the user that their account -isn't yet available, and the driver will supply a message for us, +information.

      If that doesn't work, we'll tell the user that their account +isn't yet available, and the driver will supply a message for us, which could say "The account should be available tomorrow. If not, contact X."

      Account -Registration

      If a user doesn't have an account, the site-wide +Registration

      If a user doesn't have an account, the site-wide configuration can allow the user to register for one, as defined in the configuration discussed above. This section is about normal account registration through a authority driver.

      The account creation service contract implementation will @@ -175,32 +175,32 @@ the default local account creation above, also store the password in hashed form.

    Password Management

    Password management is about changing password, retrieving -password, and resetting password.

    It's up to the authority driver implementation to decide whether +password, and resetting password.

    It's up to the authority driver implementation to decide whether to support any or all of these features, and to say so using the CanXXX methods (see driver API below).

    Additionally, the authority can be configured with a URL to redirect to in the case of forgotten passwords, or when the user desires to change password.

    Login Pages Over HTTPS

    FeatureStatusDescription
    EXT-AUTH-20
    EXT-AUTH-20ALogin over HTTPS

    Login pages must be able to be sent over a secure connection -(https), so your password won't get sent over the wire in +(https), so your password won't get sent over the wire in cleartext, while leaving the rest of the site non-secure (http). I believe that this requires some (minor) changes to the current session handling code.

    Email Verification

    Email verification needs to be handled both at registration -and at login.

    In both cases, it'll be handled by the driver sending +and at login.

    In both cases, it'll be handled by the driver sending automatically sending the email containing a link for the user to verify his account. Then the driver will return an account status of "closed,temporary", and a message that says "Check your inbox and click the link in the email".

    OpenACS will have a page which receives the email verification, for use by local accounts. Other authorities will -have to implement their own page, most likely on the authority's +have to implement their own page, most likely on the authority's own server.

    Other Items

    There are a number of items which touch on external -authentication and session management. And even though they're not +authentication and session management. And even though they're not directly linked to external authentication, I would recommend that -we handle a number of them, either because they're important for -security, or because it makes sense to fix them while we're messing +we handle a number of them, either because they're important for +security, or because it makes sense to fix them while we're messing with this part of the codebase anyway.

    Recommended: -Untrusted Logins and Login Levels

    FeatureStatusDescription
    EXT-AUTH-33
    EXT-AUTH-33AUntrusted Logins

    I like the idea of having multiple login levels:

    1. Not logged in

    2. Untrusted login: We'll show you un-sensitive personal - content, but won't let you modify anything or see personal data. A +Untrusted Logins and Login Levels

    FeatureStatusDescription
    EXT-AUTH-33
    EXT-AUTH-33AUntrusted Logins

    I like the idea of having multiple login levels:

    1. Not logged in

    2. Untrusted login: We'll show you un-sensitive personal + content, but won't let you modify anything or see personal data. A normal login becomes untrusted after a certain amount of time, and the user will have to re-enter his/her password in order to gain access to personal data. Untrusted login never expires, unless @@ -211,14 +211,14 @@ specified amount of time.

    3. Secure login: The user is logged in over a secure connection (HTTPS), potentially even using a special secure password. This would be for sensitive actions, such as credit card - transactions.

    There are two advantages to this. First, when people's login + transactions.

    There are two advantages to this. First, when people's login expires, we can ask them to re-enter only their password, and not -both username and password, since we'll still remember who they +both username and password, since we'll still remember who they were the last time their login was valid. This is a much faster operation (the password input field will be focused by default, so you just type your password and hit Return) that typing both username and password, which will make it practical to have your -site configured to expire people's login after e.g. 2, 4, or 8 +site configured to expire people's login after e.g. 2, 4, or 8 hours.

    The other advantage is that we can still offer certain functionality to you, even when your login is not trusted. For example, we could let you browse publically available forums, and @@ -228,20 +228,20 @@ bounce to the login page if the user is only logged in at the untrusted level. Only if you explicitly say auth::require_login -untrusted will we give you -the user_id of a user who's only logged in in untrusted +the user_id of a user who's only logged in in untrusted mode.

    Similarly, ad_conn user_id will continue to return 0 (not logged in) when the user is only logged in -untrusted, and we'll supply another variable, ad_conn +untrusted, and we'll supply another variable, ad_conn untrusted_user_id, which wlll be set to the user_id for all login levels.

    This should ensure that we get full access to the new feature, while leaving all current code just as secure as it was before.

    Recommended: Make Non-Persistent Login Work

    FeatureStatusDescription
    EXT-AUTH-34
    EXT-AUTH-34AExpire Logins

    Currently, OpenACS is unusable in practice without persistent login. The login will expire after just a few minutes of -inactivity, and you'll get bounced to the login page where you have +inactivity, and you'll get bounced to the login page where you have to enter both email and password again. Unacceptable in practice.

    We should change the default, so a non-persistent login -doesn't expire until you either close your browser, or a few hours +doesn't expire until you either close your browser, or a few hours have elapsed. Even if you are constantly active, the login should still expire after at most x number of hours. We can still make the login expire after a period of inactivity, but the amount of time @@ -255,24 +255,24 @@ OpenACS accounts, we would instead present the normal login screen, but put a button which says "Login using X", where X is the redirection-based external authority.

    Recommended: -Expire All Logins

    FeatureStatusDescription
    EXT-AUTH-22
    EXT-AUTH-22Brewrite cookie handling

    Currently, if you've ever left a permanent login cookie on +Expire All Logins

    FeatureStatusDescription
    EXT-AUTH-22
    EXT-AUTH-22Brewrite cookie handling

    Currently, if you've ever left a permanent login cookie on someone elses machine, that person will be forever logged in until he/she explicitly logs out. You can change your password, you can do anything you want, but unless a logout is requested from that particular browser, that browser will be logged in forever.

    I want to change our session handling code so that old login cookies can be expired. This would be done automatically whenever you change your password, and we could also offer a link which does -this without changing passwords. It's an important security +this without changing passwords. It's an important security measure.

    The implementation is simply to autogenerate some secret token which is stored in the users table, and is also stored in the -cookie somehow. Then, whenever we want to expire all logins, we'll +cookie somehow. Then, whenever we want to expire all logins, we'll just regenerate a new secret token, and the other cookies will be -void. Of course, we don't want to incur a DB hit on every request, -so we'll need to cache the secret token, or only check it when +void. Of course, we don't want to incur a DB hit on every request, +so we'll need to cache the secret token, or only check it when refreshing the session cookie, which, I believe, normally happens every 10 minutes or so.

    Recommended: Email account owner on password change

    FeatureStatusDescription
    EXT-AUTH-24
    EXT-AUTH-24AEmail on password change

    As an additional security measure, we should email the -account's email address whenever the password is changed, so that +account's email address whenever the password is changed, so that he/she is at least alerted to the fact.

    Optional: Password policy

    FeatureStatusDescription
    EXT-AUTH-25
    EXT-AUTH-25AImplement password policy

    Again, to increase security, we should add password policies, such as passwords needing to be changed after a certain number of @@ -281,52 +281,52 @@ complexity rules, i.e. both upper and lowercase characters, numbers, special chars, etc.

    It would good to extend the current maximum password length from 10 to at least 32 characters.

    Optional: -Login Without Explicit Authority

    FeatureStatusDescription
    EXT-AUTH-26
    EXT-AUTH-26BLogin without explicit domain

    In order to make it easier for people, we've been toying with +Login Without Explicit Authority

    FeatureStatusDescription
    EXT-AUTH-26
    EXT-AUTH-26BLogin without explicit domain

    In order to make it easier for people, we've been toying with the idea of a functionality like this:

    • If the user enters "foobar@ix.urz.uni-heidelberg.de", it is translated to mean username = "foobar", authority = - "ix.urz.uni-heidelberg.de".

    • If the user enters "foobar", it's recognized to not + "ix.urz.uni-heidelberg.de".

    • If the user enters "foobar", it's recognized to not include any authority, and the default authority of - "ix.urz.uni-heidelberg.de" is used.

    • If the user enters "foo@bar.com", it's recognized as not - belonging to any known authority, and as such, it's translated to mean + "ix.urz.uni-heidelberg.de" is used.

    • If the user enters "foo@bar.com", it's recognized as not + belonging to any known authority, and as such, it's translated to mean username = "foo@bar.com", authority = "local".

    If this is deemed desirable, a way to implement this would be -through these settings:

    • Split: A regexp which will split the user's entry into +through these settings:

      • Split: A regexp which will split the user's entry into username and authority parts. For example "^([^@]+)(@[^@]+)?$". An easier to use but less flexible method would be that you simply specify a certain character to split by, such as "@" or "\". If the - regexp doesn't match, or in the latter case, if there's more than + regexp doesn't match, or in the latter case, if there's more than one occurrence of the specified character sequence, the split will - fail, signaling that the user's entry was not valid.

      • Default authority: The default authority will be the first one + fail, signaling that the user's entry was not valid.

      • Default authority: The default authority will be the first one in the sort order.

      The relevant code in user-login.tcl would look like this:

       if { ![auth::split_username -username_var username -authority_var authority] } {
-    # bounce back to the form with a message saying that the login wasn't valid.
+    # bounce back to the form with a message saying that the login wasn't valid.
     ad_script_abort
 }
 
 # username will now contain username
 # authority will now contain authority
-

    Optional: Who's Online

    FeatureStatusDescription
    EXT-AUTH-27
    EXT-AUTH-27BWho's online list

    While we're touching the session handling code, anyway, it -would be nice to add a feature to show who's currently online, a +

    Optional: Who's Online

    FeatureStatusDescription
    EXT-AUTH-27
    EXT-AUTH-27BWho's online list

    While we're touching the session handling code, anyway, it +would be nice to add a feature to show who's currently online, a nice real-time collaboration feature frequently requested by members of the community. This is particularly interesting when integrated with a chat or instant messaging service like Jabber.

    What I'm concretely suggesting is that we keep a record of which authenticated users have requested pags on the site in the last x minutes (typically about 5), and thus are considered to be -currently online. There's nothing more to it. This lets us display +currently online. There's nothing more to it. This lets us display a list of "active users" somewhere on the site, and make their name -a link to a real-time chat service like Jabber.

    We've already made the changes necessary to -security-procs.tcl to do this on an earlier project, but haven't +a link to a real-time chat service like Jabber.

    We've already made the changes necessary to +security-procs.tcl to do this on an earlier project, but haven't quite finished the work and put it back into the tree.

    Optional: Subsite-level configuration

    FeatureStatusDescription
    EXT-AUTH-28
    EXT-AUTH-28implement subsite-level config

    If we want to, we could let subsite administrators configure the login process for that particular subsite. This would probably only entail letting the subsite admin leave out certain authorities defined site-wide, and change the sort order.

    I think we should leave this out until we have a use case for -it, someone who'd need it.

    Future: +it, someone who'd need it.

    Future: Making the Authentication API itself a service contract

    FeatureStatusDescription
    EXT-AUTH-32
    EXT-AUTH-32AParameters for Service Contract Implementation
    EXT-AUTH-35AMake the Authentication API a service contract

    For completely free-form authentication logic and mechanisms, -something like Andrew Grumet's +something like Andrew Grumet's Pluggable -Authentication for OACS Draft is interesting. He's +Authentication for OACS Draft is interesting. He's proposing a scheme where the entire user interaction is encapsulated in, and left entirely to, a service contract. This certainly opens up more advanced possibilities, such as perhaps @@ -340,35 +340,35 @@ Authenticating against multiple servers simultaneously

    FeatureStatusDescription
    EXT-AUTH-36
    EXT-AUTH-36AAuthenticate against multiple servers

    Both OKI and OpenACS supports a form of stacking, where you can be logged into multiple authorities at the same time. This is useful if, for example, you need to get login tokens such as -Kerberos tickets for access to shared resources.

    I can see the value in this, but for simplicity's sake, I'm +Kerberos tickets for access to shared resources.

    I can see the value in this, but for simplicity's sake, I'm in favor of keeping this use-case out of the loop until we have someone with a real requirement who could help us guide development.

    For now, OpenACS is still more of an integrated suite, it -doesn't access many outside applications. I think it would be +doesn't access many outside applications. I think it would be excellent for OpenACS to do so, e.g. by using an IMAP server to store emails, an iCal server to store calendar appointments, LDAP for user/group data and access control lists, SMB for file storage, -etc. But at the moment, we don't have any users of such things that -are ready. We have some who are on the steps, but let's wait till -they're there.

    Implement +etc. But at the moment, we don't have any users of such things that +are ready. We have some who are on the steps, but let's wait till +they're there.

    Implement Specific Drivers

    FeatureStatusDescription
    Implement specific drivers
    EXT-AUTH-09ACreate Auth. drivers for Local Authority
    EXT-AUTH-10ACreate Acct. Creation driver for Local Authority
    EXT-AUTH-11ACreate Auth. driver for PAM
    EXT-AUTH-12XCreate Acct. Creation driver for PAM - this - functionality is explicitly excluded from PAM
    EXT-AUTH-13ACreate Acct. Creation driver for LDAP
    EXT-AUTH-14ACreate Auth. driver for LDAP

    We'll need drivers for:

    • Operating system (Linux/Solaris) PAM: Delegate to the + functionality is explicitly excluded from PAMEXT-AUTH-13ACreate Acct. Creation driver for LDAPEXT-AUTH-14ACreate Auth. driver for LDAP

    We'll need drivers for:

    • Operating system (Linux/Solaris) PAM: Delegate to the operating system, which can then talk to RADIUS, LDAP, whatever. - This is convenient because there'll be plenty of drivers for the OS - PAM level, so we don't have to write them all ourselves. The - downside is that we can't do things like account creation, password + This is convenient because there'll be plenty of drivers for the OS + PAM level, so we don't have to write them all ourselves. The + downside is that we can't do things like account creation, password management, real-time account synchronization, etc., not supported by PAM (I'm not entirely sure what is and is not supported).

    • RADIUS

    • LDAP

    RADIUS

    RADIUS is a simple username/password-type authentication server.

    It also supports sending a challenge to which the user must -respond with the proper answer (e.g. mother's maiden name, or could +respond with the proper answer (e.g. mother's maiden name, or could be additional password), but we will not support this feature.

    A RADIUS client implementation in Python can be found in the exUserFolder module for Zope -(documentation).

    Feedback

    We'd really appreciate feedback on this proposal. Please follow up at +(documentation).

    Feedback

    We'd really appreciate feedback on this proposal. Please follow up at this openacs.org forums thread.

    References

    Also worthy of treatment in this section:

    Note: it's entirely possible that a discussion of what a package -is not intended to do differs from a discussion of future +to address the same requirements.

    Note: it's entirely possible that a discussion of what a +package is not intended to do differs from a discussion of future improvements for the package.

    @@ -72,7 +72,7 @@ team needs to be ready for inquiries regarding features our software lacks.

    Note that such a discussion may differ from a discussion of a -package's potential future improvements.

    +package's potential future improvements.

    Design Tradeoffs

    No single design solution can optimize every desirable software @@ -90,11 +90,11 @@

    -API

    Here's where you discuss the abstractions used by your package, -such as the procedures encapsulating the legal transactions on the -data model. Explain the organization of procedures and their -particulars (detail above and beyond what is documented in the -code), including:

      +API

    Here's where you discuss the abstractions used by your +package, such as the procedures encapsulating the legal +transactions on the data model. Explain the organization of +procedures and their particulars (detail above and beyond what is +documented in the code), including:

    • Problem-domain components: key algorithms, e.g. a specialized statistics package would implement specific mathematical procedures.

    • User-interface components: e.g. HTML widgets that the package @@ -104,8 +104,8 @@

    Remember that the correctness, completeness, and stability of the API and interface are what experienced members of our audience are looking for. This is a cultural shift for us at aD (as of -mid-year 2000), in that we've previously always looked at the data -models as key, and seldom spent much effort on the API (e.g. +mid-year 2000), in that we've previously always looked at the +data models as key, and seldom spent much effort on the API (e.g. putting raw SQL in pages to handle transactions, instead of encapsulating them via procedures). Experience has taught us that we need to focus on the API for maintainability of our systems in @@ -114,11 +114,12 @@

    Data Model Discussion

    The data model discussion should do more than merely display the SQL code, since this information is already be available via a link -in the "essentials" section above. Instead, there should be a -high-level discussion of how your data model meets your solution -requirements: why the database entities were defined as they are, -and what transactions you expect to occur. (There may be some -overlap with the API section.) Here are some starting points:

      +in the "essentials" section above. Instead, there should +be a high-level discussion of how your data model meets your +solution requirements: why the database entities were defined as +they are, and what transactions you expect to occur. (There may be +some overlap with the API section.) Here are some starting +points:

      • The data model discussion should address the intended usage of each entity (table, trigger, view, procedure, etc.) when this information is not obvious from an inspection of the data model @@ -140,15 +141,16 @@

      • Developers

      • OpenACS administrators (previously known as site-wide administrators)

      • Subsite administrators

      • End users

      You may want to include page mockups, site-maps, or other visual -aids. Ideally this section is informed by some prototyping you've -done, to establish the package's usability with the client and -other interested parties.

      Note: In order that developer +aids. Ideally this section is informed by some prototyping +you've done, to establish the package's usability with the +client and other interested parties.

      Note: In order that developer documentation be uniform across different system documents, these -users should herein be designated as "the developer," "the -OpenACS-admin," "the sub-admin," and "the user," -respectively.

      Finally, note that as our templating system becomes more -entrenched within the OpenACS, this section's details are likely to -shift from UI specifics to template interface specifics.

      +users should herein be designated as "the developer," +"the OpenACS-admin," "the sub-admin," and +"the user," respectively.

      Finally, note that as our templating system becomes more +entrenched within the OpenACS, this section's details are +likely to shift from UI specifics to template interface +specifics.

    Configuration/Parameters

    Under OpenACS 5.9.0, parameters are set at two levels: at the @@ -161,17 +163,17 @@ Change

    If the system presently lacks useful/desirable features, note details here. You could also comment on non-functional improvements to the package, such as usability.

    Note that a careful treatment of the earlier "competitive -analysis" section can greatly facilitate the documenting of this -section.

    +analysis" section can greatly facilitate the documenting of +this section.

    -Authors

    Although a system's data model file often contains this -information, this isn't always the case. Furthermore, data model -files often undergo substantial revision, making it difficult to -track down the system creator. An additional complication: package -documentation may be authored by people not directly involved in -coding. Thus to avoid unnecessary confusion, include email links to -the following roles as they may apply:

      +Authors

    Although a system's data model file often contains this +information, this isn't always the case. Furthermore, data +model files often undergo substantial revision, making it difficult +to track down the system creator. An additional complication: +package documentation may be authored by people not directly +involved in coding. Thus to avoid unnecessary confusion, include +email links to the following roles as they may apply:

    • System creator

    • System owner

    • Documentation author

    @@ -192,8 +194,8 @@ 0.1Creation8/21/2000Josh Finkler, Audrey McLoghlin -
    ($‌Id: design-template.xml,v 1.8 2006/07/17 -05:38:37 torbenb Exp $)
    +
    ($‌Id: filename.html,v 1.48.2.10 2016/06/21 +07:44:36 gustafn Exp $)

    • When applicable, a careful demarcation between the functionality of this package and others which - at least superficially - appear to address the same requirements.

    - Note: it's entirely possible that a discussion of what a package + Note: it's entirely possible that a discussion of what a package is not intended to do differs from a discussion of future improvements for the package.

    Historical Considerations

    @@ -51,7 +51,7 @@ team needs to be ready for inquiries regarding features our software lacks.

    Note that such a discussion may differ from a discussion of a - package's potential future improvements. + package's potential future improvements.

    Design Tradeoffs

    No single design solution can optimize every desirable software attribute. For example, an increase in the security of a system will @@ -63,7 +63,7 @@ chosen, and the reasons for your choices. Some areas of importance to keep in mind are:

    Areas of interest to users:

    • Performance: availability and efficiency

    • Flexibility

    • Interoperability

    • Reliability and robustness

    • Usability

    Areas of interest to developers:

    • Maintainability

    • Portability

    • Reusability

    • Testability

    API

    - Here's where you discuss the abstractions used by your package, such + Here's where you discuss the abstractions used by your package, such as the procedures encapsulating the legal transactions on the data model. Explain the organization of procedures and their particulars (detail above and beyond what is documented in the @@ -75,7 +75,7 @@ Remember that the correctness, completeness, and stability of the API and interface are what experienced members of our audience are looking for. This is a cultural shift for us at aD (as of mid-year 2000), in - that we've previously always looked at the data models as key, and + that we've previously always looked at the data models as key, and seldom spent much effort on the API (e.g. putting raw SQL in pages to handle transactions, instead of encapsulating them via procedures). Experience has taught us that we need to focus on the API for @@ -102,8 +102,8 @@ you can organize by the expected classes of users. These may include:

    • Developers

    • OpenACS administrators (previously known as site-wide administrators)

    • Subsite administrators

    • End users

    You may want to include page mockups, site-maps, or other visual aids. - Ideally this section is informed by some prototyping you've done, to - establish the package's usability with the client and other interested + Ideally this section is informed by some prototyping you've done, to + establish the package's usability with the client and other interested parties.

    Note: In order that developer documentation be uniform across @@ -112,7 +112,7 @@ respectively.

    Finally, note that as our templating system becomes more entrenched - within the OpenACS, this section's details are likely to shift from UI + within the OpenACS, this section's details are likely to shift from UI specifics to template interface specifics.

    Configuration/Parameters

    Under OpenACS 5.9.0, parameters are set at two levels: at the global level by @@ -126,8 +126,8 @@ Note that a careful treatment of the earlier "competitive analysis" section can greatly facilitate the documenting of this section.

    Authors

    - Although a system's data model file often contains this information, - this isn't always the case. Furthermore, data model files often + Although a system's data model file often contains this information, + this isn't always the case. Furthermore, data model files often undergo substantial revision, making it difficult to track down the system creator. An additional complication: package documentation may be authored by people not directly involved in coding. Thus to avoid Index: openacs-4/packages/acs-core-docs/www/form-builder.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/form-builder.adp,v diff -u -N -r1.1.2.11 -r1.1.2.12 --- openacs-4/packages/acs-core-docs/www/form-builder.adp 21 Jun 2016 07:44:36 -0000 1.1.2.11 +++ openacs-4/packages/acs-core-docs/www/form-builder.adp 23 Jun 2016 08:32:45 -0000 1.1.2.12 @@ -13,8 +13,8 @@ dynamically

    Overview

    -
    ($‌Id: form-builder.xml,v 1.9.2.1 2015/09/23 -11:55:07 gustafn Exp $)
    +
    ($‌Id: form-builder.html,v 1.30.2.10 2016/06/21 +07:44:36 gustafn Exp $)
    OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

    OpenACS has a form manager called ad_form. Ad_form has an adaptable UI. Error handling includes inline error reporting, and @@ -27,8 +27,8 @@

    SELECT elements

    1. -Creating the form element. Populate a list of -lists with values for the option list.

      +Creating the form element. Populate
+a list of lists with values for the option list.
       set foo_options [db_list_of_lists foo_option_list "
     select foo,
            foo_id
@@ -66,26 +66,26 @@
     
 
      What this will do is set the value for pm_task_id and all the
 other form elements, and resubmit the form. If you then include a
-block that extends the form, you'll have the opportunity to add in
-subcategories:
      +block that extends the form, you'll have the opportunity to add
+in subcategories:
           if {[info exists pm_task_id] && $pm_task_id ne ""} {
     db_1row get_task_values { }
     ad_form -extend -name form_name -form { ... }
     
 
      Note that you will get strange results when you try to set the
-values for the form. You'll need to set them explicitly in an
--on_refresh section of your ad_form. In that section, you'll get
-the values from the database, and set the values as so:
      +values for the form. You'll need to set them explicitly in an
+-on_refresh section of your ad_form. In that section, you'll
+get the values from the database, and set the values as so:
           db_1row get_task_values { }
     template::element set_value form_name estimated_hours_work $estimated_hours_work

    -Troubleshooting

    A good way to troubleshoot when you're using ad_form is to add -the following code at the top of the .tcl page (thanks Jerry +Troubleshooting

    A good way to troubleshoot when you're using ad_form is to +add the following code at the top of the .tcl page (thanks Jerry Asher):

    -ns_log notice it's my page!
+ns_log notice it's my page!
 set mypage [ns_getform]
 if {$mypage eq ""} {
     ns_log notice no form was submitted on my page
Index: openacs-4/packages/acs-core-docs/www/form-builder.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/form-builder.html,v
diff -u -N -r1.30.2.10 -r1.30.2.11
--- openacs-4/packages/acs-core-docs/www/form-builder.html	21 Jun 2016 07:44:36 -0000	1.30.2.10
+++ openacs-4/packages/acs-core-docs/www/form-builder.html	23 Jun 2016 08:32:45 -0000	1.30.2.11
@@ -29,20 +29,20 @@
     }

    What this will do is set the value for pm_task_id and all the other form elements, and resubmit the form. If you then include a - block that extends the form, you'll have the opportunity to add in + block that extends the form, you'll have the opportunity to add in subcategories: 

        if {[info exists pm_task_id] && $pm_task_id ne ""} {
     db_1row get_task_values { }
     ad_form -extend -name form_name -form { ... }

    Note that you will get strange results when you try to set - the values for the form. You'll need to set them explicitly in an - -on_refresh section of your ad_form. In that section, you'll get + the values for the form. You'll need to set them explicitly in an + -on_refresh section of your ad_form. In that section, you'll get the values from the database, and set the values as so:

        db_1row get_task_values { }
     template::element set_value form_name estimated_hours_work $estimated_hours_work
-

    Troubleshooting

    A good way to troubleshoot when you're using ad_form is to +

    Troubleshooting

    A good way to troubleshoot when you're using ad_form is to add the following code at the top of the .tcl page (thanks Jerry Asher):

    -ns_log notice it's my page!
+ns_log notice it's my page!
 set mypage [ns_getform]
 if {$mypage eq ""} {
     ns_log notice no form was submitted on my page
Index: openacs-4/packages/acs-core-docs/www/groups-design.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-design.adp,v
diff -u -N -r1.1.2.2 -r1.1.2.3
--- openacs-4/packages/acs-core-docs/www/groups-design.adp	9 Jun 2016 08:44:49 -0000	1.1.2.2
+++ openacs-4/packages/acs-core-docs/www/groups-design.adp	23 Jun 2016 08:32:45 -0000	1.1.2.3
@@ -34,19 +34,19 @@
 
    
 Historical
 Considerations
    The primary limitation of the OpenACS 3.x user group system is
-that it restricts the application developer to representing a "flat
-group" that contains only users: The user_groups table may contain the
+that it restricts the application developer to representing a
+"flat group" that contains only users: The user_groups table may contain the
 group_id of a parent group, but
 parent-child relationship support is limited because it only allows
 one kind of relationship between groups to be represented.
-Moreover, the Oracle database's limited support for tree-like
+Moreover, the Oracle database's limited support for tree-like
 structures makes the queries over these relationships
 expensive.
    In addition, the Module Scoping design in OpenACS 3.0 introduced
 a party abstraction - a
 thing that is a person or a group of people - though not in the
 form of an explicit table. Rather, the triple of scope, user_id, and group_id columns was used to identify the
 party. One disadvantage of this design convention is that it
-increases a data model's complexity by requiring the programmer
+increases a data model's complexity by requiring the programmer
 to:
      
 
    • add these three columns to each "scoped" table
    • define a multi-column check constraint to protect against data
 corruption (e.g., a row with a scope value of "group" but a null
@@ -60,16 +60,16 @@
 
    
 
    
 Design Tradeoffs
    The core of the Group Systems data model is quite simple, but it
-was designed in the hopes of modeling "real world" organizations
-which can be complex graph structures. The Groups System only
-considers groups that can be modeled using directed acyclic graphs,
-but queries over these structures are still complex enough to slow
-the system down. Since almost every page will have at least one
-membership check, a number of triggers, views, and auxiliary tables
-have been created in the hopes of increasing performance. To keep
-the triggers simple and the number of triggers small, the data
-model disallows updates on the membership and composition tables,
-only inserts and deletes are permitted.
    The data model has tried to balance the need to model actual
+was designed in the hopes of modeling "real world"
+organizations which can be complex graph structures. The Groups
+System only considers groups that can be modeled using directed
+acyclic graphs, but queries over these structures are still complex
+enough to slow the system down. Since almost every page will have
+at least one membership check, a number of triggers, views, and
+auxiliary tables have been created in the hopes of increasing
+performance. To keep the triggers simple and the number of triggers
+small, the data model disallows updates on the membership and
+composition tables, only inserts and deletes are permitted.
    The data model has tried to balance the need to model actual
 organizations without making the system too complex or too slow.
 The added triggers, views, and tables and will increase storage
 requirements and the insert and delete times in an effort to speed
@@ -82,8 +82,9 @@
 
    parties
    The set of all defined parties: any person, user, or group must have a corresponding row in
 this table.
    persons
    The set of all defined persons. To allow easy sorting of
 persons, the name requirement 30.10 is
-met by splitting the person's name into two columns: first_names and last_name.
    users
    The set of all registered users; this table includes information
-about the user's email address and the user's visits to the
+met by splitting the person's name into two columns:
+first_names and last_name.
    users
    The set of all registered users; this table includes information
+about the user's email address and the user's visits to the
 site.
    user_preferences
    Preferences for the user.
    groups
    The set of all defined groups.
    group_types
    When a new type of group is created, this table holds additional
 knowledge level attributes for the group and its subtypes.
    membership_rels
    The set of direct membership relationships between a group and a
 party.
    group_member_index
    A mapping of a party P to the groups {Gi
@@ -104,10 +105,10 @@
 application developer. Membership constraints can be specified at
 creation time by passing a parent group to the constructor.
    The membership_rels and
 composition_rels tables
-indicate a group's direct members and direct components; these
+indicate a group's direct members and direct components; these
 tables do not provide a record of the members or components that
 are in the group by virtue of being a member or component of one of
-the group's component groups. Site pages will query group
+the group's component groups. Site pages will query group
 membership often, but the network of component groups can become a
 very complex directed acyclic graph and traversing this graph for
 every query will quickly degrade performance. To make membership
@@ -130,10 +131,8 @@
 appropriaterel_id from the
 membership_rels table.
    group_approved_member_map
    A mapping of a party to the groups the party is an approved
 member of (member_state is
-'approved'); this mapping includes the type of relationship by
-including the appropriaterel_id
-from the membership_rels
-table.
    group_distinct_member_map
    A person may appear in the group member map multiple times, for
+'approved'); this mapping includes the type of relationship
+by including the appropriaterel_id from the membership_rels table.
    group_distinct_member_map
    A person may appear in the group member map multiple times, for
 example, by being a member of two different groups that are both
 components of a third group. This view is strictly a mapping of
 approved members to
@@ -201,8 +200,8 @@

    User

    acs_user.new creates a new user and returns the user_id. -The function must be given the user's email address and the full -name of the user in two pieces: first_names and last_name. All other fields are optional. +The function must be given the user's email address and the +full name of the user in two pieces: first_names and last_name. All other fields are optional. The interface for this function is:

     function acs_user.new (
   user_id            users.user_id%TYPE,
@@ -230,13 +229,13 @@
 );

    acs_user.receives_alerts_p -returns 't' if the user should receive email alerts and 'f' -otherwise. The interface for this function is:

    +returns 't' if the user should receive email alerts and
+'f' otherwise. The interface for this function is:
     function acs_user.receives_alerts_p (
   user_id       users.user_id%TYPE
 ) return varchar;
 
    Use the procedures acs_user.approve_email and acs_user.unapprove_email to specify whether
-the user's email address is valid. The interface for these
+the user's email address is valid. The interface for these
 procedures are:
     procedure acs_user.approve_email (
   user_id       users.user_id%TYPE
@@ -248,10 +247,11 @@
 
    Group
    
 acs_group.new creates a new
 group and returns the group_id.
-All fields are optional and default to null except for object_type which defaults to 'group',
-creation_date which defaults to
-sysdate, and group_name which is required. The interface
-for this function is:
    +All fields are optional and default to null except for object_type which defaults to
+'group', creation_date
+which defaults to sysdate, and
+group_name which is required.
+The interface for this function is:
     function acs_group.new (
   group_id           groups.group_id%TYPE,
   object_type        acs_objects.object_type%TYPE,
@@ -271,8 +271,9 @@
 ) return varchar;
 
    
 acs_group.member_p returns
-'t' if the specified party is a member of the specified group.
-Returns 'f' otherwise. The interface for this function is:
    +'t' if the specified party is a member of the specified
+group. Returns 'f' otherwise. The interface for this
+function is:
     function acs_group.member_p (
   group_id      groups.group_id%TYPE,
   party_id      parties.party_id%TYPE,
@@ -281,9 +282,10 @@
 Relationship
    
 membership_rel.new creates a
 new membership relationship type between two parties and returns
-the relationship type's rel_id.
-All fields are optional and default to null except for rel_type which defaults to membership_rel.
-The interface for this function is:
    +the relationship type's rel_id. All fields are optional and default
+to null except for rel_type
+which defaults to membership_rel. The interface for this function
+is:
     function membership_rel.new (
   rel_id             membership_rels.rel_id%TYPE,
   rel_type           acs_rels.rel_type%TYPE,
@@ -304,8 +306,8 @@
 
    
 membership_rel.approve sets
 the member_state of the given
-rel_id to 'approved'. The
-interface for this procedure is:
    +rel_id to 'approved'.
+The interface for this procedure is:
     procedure membership_rel.approve (
   rel_id           membership_rels.rel_id%TYPE
 );
@@ -328,8 +330,8 @@
 
    
 membership_rel.deleted sets
 the member_state of the given
-rel_id to 'deleted'. The
-interface for this procedure is:
    +rel_id to 'deleted'.
+The interface for this procedure is:
     procedure membership_rel.deleted (
   rel_id           membership_rels.rel_id%TYPE
 );
@@ -343,9 +345,9 @@
 
    Composition
 Relationship
    
 composition_rel.new creates
-a new composition relationship type and returns the relationship's
-rel_id. All fields are optional
-and default to null except for rel_type which defaults to composition_rel.
+a new composition relationship type and returns the
+relationship's rel_id. All
+fields are optional and default to null except for rel_type which defaults to composition_rel.
 The interface for this function is:
     function membership_rel.new (
   rel_id             composition_rels.rel_id%TYPE,
Index: openacs-4/packages/acs-core-docs/www/groups-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-design.html,v
diff -u -N -r1.34.2.1 -r1.34.2.2
--- openacs-4/packages/acs-core-docs/www/groups-design.html	9 Jun 2016 08:44:49 -0000	1.34.2.1
+++ openacs-4/packages/acs-core-docs/www/groups-design.html	23 Jun 2016 08:32:45 -0000	1.34.2.2
@@ -13,14 +13,14 @@
 that contains only users: The user_groups table may contain the
 group_id of a parent group, but parent-child relationship
 support is limited because it only allows one kind of relationship between
-groups to be represented. Moreover, the Oracle database's limited support
+groups to be represented. Moreover, the Oracle database's limited support
 for tree-like structures makes the queries over these relationships
 expensive.
    In addition, the Module Scoping design in OpenACS 3.0 introduced a
 party abstraction - a thing that is a person or a group of people -
 though not in the form of an explicit table. Rather, the triple of
 scope, user_id, and group_id columns
 was used to identify the party. One disadvantage of this design convention is
-that it increases a data model's complexity by requiring the programmer
+that it increases a data model's complexity by requiring the programmer
 to:
    • add these three columns to each "scoped" table
    • define a multi-column check constraint to protect against data corruption
 (e.g., a row with a scope value of "group" but a null
 group_id)
    • perform extra checks in Tcl and PL/SQL
@@ -45,11 +45,11 @@
 
 
      The set of all defined persons. To allow easy sorting of persons, the
 name requirement 30.10 is met by
-splitting the person's name into two columns: first_names and
+splitting the person's name into two columns: first_names and
 last_name.
      users
 
 
      The set of all registered users; this table includes information about
-the user's email address and the user's visits to the site.
      user_preferences
+the user's email address and the user's visits to the site.
    user_preferences

    Preferences for the user.

    groups @@ -76,9 +76,9 @@ When a specialized type of group is required, the group type can be extended by an application developer. Membership constraints can be specified at creation time by passing a parent group to the constructor.

    The membership_rels and composition_rels tables indicate -a group's direct members and direct components; these tables do not +a group's direct members and direct components; these tables do not provide a record of the members or components that are in the group by virtue -of being a member or component of one of the group's component groups. +of being a member or component of one of the group's component groups. Site pages will query group membership often, but the network of component groups can become a very complex directed acyclic graph and traversing this graph for every query will quickly degrade performance. To make membership @@ -162,7 +162,7 @@ person_id persons.person_id%TYPE ) return varchar;

    User

    acs_user.new creates a new user and returns the user_id. -The function must be given the user's email address and the full name of +The function must be given the user's email address and the full name of the user in two pieces: first_names and last_name. All other fields are optional. The interface for this function is:

     function acs_user.new (
@@ -194,7 +194,7 @@
   user_id       users.user_id%TYPE
 ) return varchar;

    Use the procedures acs_user.approve_email and -acs_user.unapprove_email to specify whether the user's email +acs_user.unapprove_email to specify whether the user's email address is valid. The interface for these procedures are:

     procedure acs_user.approve_email (
   user_id       users.user_id%TYPE
@@ -232,7 +232,7 @@
   party_id      parties.party_id%TYPE,
 ) return char;

    Membership Relationship

    membership_rel.new creates a new membership relationship type -between two parties and returns the relationship type's rel_id. +between two parties and returns the relationship type's rel_id. All fields are optional and default to null except for rel_type which defaults to membership_rel. The interface for this function is:

     function membership_rel.new (
@@ -278,7 +278,7 @@
   rel_id           membership_rels.rel_id%TYPE
 );

    Composition Relationship

    composition_rel.new creates a new composition relationship type -and returns the relationship's rel_id. All fields are optional +and returns the relationship's rel_id. All fields are optional and default to null except for rel_type which defaults to composition_rel. The interface for this function is:

     function membership_rel.new (
Index: openacs-4/packages/acs-core-docs/www/groups-requirements.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-requirements.adp,v
diff -u -N -r1.1.2.2 -r1.1.2.3
--- openacs-4/packages/acs-core-docs/www/groups-requirements.adp	9 Jun 2016 08:44:49 -0000	1.1.2.2
+++ openacs-4/packages/acs-core-docs/www/groups-requirements.adp	23 Jun 2016 08:32:45 -0000	1.1.2.3
@@ -24,30 +24,30 @@
 
    
 
    
 Vision Statement
    A powerful web service that can meet the needs of large
-enterprises must be able to model the the real world's very rich
-organizational structures and many ways of decomposing the same
-organization. For example, a corporation can be broken into
+enterprises must be able to model the the real world's very
+rich organizational structures and many ways of decomposing the
+same organization. For example, a corporation can be broken into
 structures (the corporation, its divisions, and their departments)
 or regions (the Boston office, the LA office); a person who is
 employed by (is a member of) a specific department is also a member
 of the division and the corporation, and works at (is a member of,
-but in a different sense) a particular office. OpenACS's Parties
-and Groups system will support such complex relations
+but in a different sense) a particular office. OpenACS's
+Parties and Groups system will support such complex relations
 faithfully.
    Historical
 Motivations
    The primary limitation of the OpenACS 3.x user group system is
-that it restricts the application developer to representing a "flat
-group" that contains only users: The user_groups table may contain the
+that it restricts the application developer to representing a
+"flat group" that contains only users: The user_groups table may contain the
 group_id of a parent group, but
 parent-child relationship support is limited because it only allows
 one kind of relationship between groups to be represented.
-Moreover, the Oracle database's limited support for tree-like
+Moreover, the Oracle database's limited support for tree-like
 structures makes the queries over these relationships
 expensive.
    In addition, the Module Scoping design in OpenACS 3.0 introduced
 a party abstraction - a
 thing that is a person or a group of people - though not in the
 form of an explicit table. Rather, the triple of scope, user_id, and group_id columns was used to identify the
 party. One disadvantage of this design convention is that it
-increases a data model's complexity by requiring the programmer
+increases a data model's complexity by requiring the programmer
 to:
      
 
    • add these three columns to each "scoped" table
    • define a multi-column check constraint to protect against data
 corruption (e.g., a row with a scope value of "group" but a null
@@ -116,7 +116,7 @@
 There would be a composition relationship between each Sierra Club
 chapter and the Sierra Club. Membership relationships would exist
 between Eddie and the Massachusetts Chapter, between Eddie and the
-Sierra Club (due to Eddie's membership in the Massachusetts
+Sierra Club (due to Eddie's membership in the Massachusetts
 chapter), and between the Sierra Club and Greenpeace.
      Membership requirements can vary from group to group. The
 parties and groups system must provide a base type that specifies
 the bare minimum necessary to join a group.
      The parties and groups system must support constraints between a
@@ -297,14 +297,13 @@
 as a component of a second group. This API is subject to the
 constraints laid out in the data model.
      120.0 Remove a
 party as a member of a group
      The parties and groups system provides an API for deleting a
-party's membership in a group. This API is subject to the
+party's membership in a group. This API is subject to the
 constraints laid out in the data model.
      125.0 Remove a
 group as a component of a second group
      The parties and groups system provides an API for deleting a
-group's composition in a second group. This API is subject to the
-constraints laid out in the data model.
      130.0
+group's composition in a second group. This API is subject to
+the constraints laid out in the data model.
      130.0
 Membership check
      The parties and groups system provides an API for answering the
-question: "Is party P
-a member of group G?"
      135.0
+question: "Is party P a member of group G?"
      135.0
 Composition check
      The parties and groups system provides an API for answering the
 question: "Is group GC
  a component of group
@@ -319,8 +318,8 @@
 Component-of-groups query

    The parties and groups system provides an API for answering the question: "Of which groups is group G a component?"

    160.0 Allowed membership check

    The parties and groups system provides an API for answering the -question: "Is party P -allowed to become a member of group G?"

    165.0 Allowed +question: "Is party P allowed to become a member of +group G?"

    165.0 Allowed composition check

    The parties and groups system provides an API for answering the question: "Is group GC allowed to become a Index: openacs-4/packages/acs-core-docs/www/groups-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-requirements.html,v diff -u -N -r1.34.2.1 -r1.34.2.2 --- openacs-4/packages/acs-core-docs/www/groups-requirements.html 9 Jun 2016 08:44:49 -0000 1.34.2.1 +++ openacs-4/packages/acs-core-docs/www/groups-requirements.html 23 Jun 2016 08:32:45 -0000 1.34.2.2 @@ -8,7 +8,7 @@ particularly to support powerful subsite services; that is, where one OpenACS installation can support what appears to the user as distinct web services for different user communities.

    Vision Statement

    A powerful web service that can meet the needs of large enterprises must - be able to model the the real world's very rich organizational structures + be able to model the the real world's very rich organizational structures and many ways of decomposing the same organization. For example, a corporation can be broken into structures (the corporation, its divisions, and their departments) or regions (the Boston office, the LA office); a @@ -20,14 +20,14 @@ that contains only users: The user_groups table may contain the group_id of a parent group, but parent-child relationship support is limited because it only allows one kind of relationship between - groups to be represented. Moreover, the Oracle database's limited support + groups to be represented. Moreover, the Oracle database's limited support for tree-like structures makes the queries over these relationships expensive.

    In addition, the Module Scoping design in OpenACS 3.0 introduced a party abstraction - a thing that is a person or a group of people - though not in the form of an explicit table. Rather, the triple of scope, user_id, and group_id columns was used to identify the party. One disadvantage of this design convention is - that it increases a data model's complexity by requiring the programmer + that it increases a data model's complexity by requiring the programmer to:

    • add these three columns to each "scoped" table

    • define a multi-column check constraint to protect against data corruption (e.g., a row with a scope value of "group" but a null group_id)

    • perform extra checks in Tcl and PL/SQL @@ -63,7 +63,7 @@ modeled as groups, and Eddie would be a user. There would be a composition relationship between each Sierra Club chapter and the Sierra Club. Membership relationships would exist between Eddie and the Massachusetts Chapter, - between Eddie and the Sierra Club (due to Eddie's membership in the + between Eddie and the Sierra Club (due to Eddie's membership in the Massachusetts chapter), and between the Sierra Club and Greenpeace.

      Membership requirements can vary from group to group. The parties and groups system must provide a base type that specifies the bare minimum necessary to join a group.

      The parties and groups system must support constraints between a composite @@ -165,12 +165,12 @@ component of a second group. This API is subject to the constraints laid out in the data model.

    120.0 Remove a party as a member of a group -

    The parties and groups system provides an API for deleting a party's +

    The parties and groups system provides an API for deleting a party's membership in a group. This API is subject to the constraints laid out in the data model.

    125.0 Remove a group as a component of a second group -

    The parties and groups system provides an API for deleting a group's +

    The parties and groups system provides an API for deleting a group's composition in a second group. This API is subject to the constraints laid out in the data model.

    130.0 Membership check Index: openacs-4/packages/acs-core-docs/www/high-avail.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/high-avail.adp,v diff -u -N -r1.1.2.11 -r1.1.2.12 --- openacs-4/packages/acs-core-docs/www/high-avail.adp 21 Jun 2016 07:44:36 -0000 1.1.2.11 +++ openacs-4/packages/acs-core-docs/www/high-avail.adp 23 Jun 2016 08:32:45 -0000 1.1.2.12 @@ -13,7 +13,7 @@ Configurations

    See also the section called “Running a PostgreSQL database on another server”.

    -

    Figure 6.1. Multiple-server +

    Figure 6.1. Multiple-server configuration

    Multiple-server configuration

    Index: openacs-4/packages/acs-core-docs/www/high-avail.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/high-avail.html,v diff -u -N -r1.24.2.10 -r1.24.2.11 --- openacs-4/packages/acs-core-docs/www/high-avail.html 21 Jun 2016 07:44:36 -0000 1.24.2.10 +++ openacs-4/packages/acs-core-docs/www/high-avail.html 23 Jun 2016 08:32:45 -0000 1.24.2.11 @@ -1,2 +1,2 @@ -High Availability/High Performance Configurations
    Alex logo
    Prev Chapter 6. Production Environments Next

    High Availability/High Performance Configurations

    See also the section called “Running a PostgreSQL database on another server”.

    Figure 6.1. Multiple-server configuration

    Multiple-server configuration

    Prev Home Next
    Running multiple services on one machine Up Staged Deployment for Production Networks
    docs@openacs.org
    View comments on this page at openacs.org
    +High Availability/High Performance Configurations
    Alex logo
    Prev Chapter 6. Production Environments Next

    High Availability/High Performance Configurations

    See also the section called “Running a PostgreSQL database on another server”.

    Figure 6.1. Multiple-server configuration

    Multiple-server configuration

    Prev Home Next
    Running multiple services on one machine Up Staged Deployment for Production Networks
    docs@openacs.org
    View comments on this page at openacs.org
    Index: openacs-4/packages/acs-core-docs/www/how-do-I.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/how-do-I.adp,v diff -u -N -r1.1.2.10 -r1.1.2.11 --- openacs-4/packages/acs-core-docs/www/how-do-I.adp 21 Jun 2016 07:44:36 -0000 1.1.2.10 +++ openacs-4/packages/acs-core-docs/www/how-do-I.adp 23 Jun 2016 08:32:45 -0000 1.1.2.11 @@ -45,13 +45,13 @@ edit it:

    1. cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-subsite/www/index*/var/lib/aolserver/$OPENACS_SERVICE_NAME/www

    2. Edit the new index.adp to -change the text; you shouldn't need to edit index.tcl unless you are adding new +change the text; you shouldn't need to edit index.tcl unless you are adding new functionality.

    How do I change the site-wide style?

    Almost all pages on an OpenACS site use ACS Templating, and so -their appearance is driven by a layer of different files. Let's +their appearance is driven by a layer of different files. Let's examine how this works:

    • A templated page uses an ADP/Tcl pair. The first line in the ADP @@ -71,8 +71,8 @@ and .tcl).

    • Blank-master does HTML housekeeping and provides a framework for special sitewide -navigation "meta" elements such as Translator widgets and Admin -widgets.

      • +navigation "meta" elements such as Translator widgets and +Admin widgets.

    Figure 4.1. Site Templates

    Site Templates
    @@ -83,43 +83,44 @@ problem?

  • Replace human-readable text in Tcl files with temporary -tags. Examine all of the tcl files in the packages -for human-readable text and replace it with temporary tags. The -temporary tags in Tcl are slightly different from those in ADP. If -the first character in the temporary tag is an underscore -(_), then the message keys will -be auto-generated from the original message text. Here is an -unmodified tcl file:

    +tags. Examine all of the tcl files in the
+packages for human-readable text and replace it with temporary
+tags. The temporary tags in Tcl are slightly different from those
+in ADP. If the first character in the temporary tag is an
+underscore (_), then the
+message keys will be auto-generated from the original message text.
+Here is an unmodified tcl file:
     set title "Messages for $a(name) in $b(label)"
 set context [list [list . "SimPlay"] \
                   [list [export_vars -base case-admin { case_id }] \ 
@@ -66,22 +67,23 @@

  • Replace the temporary message tags in Tcl -files. Repeat step 2 for tcl files. Here is the -example Tcl file after conversion:

    +files. Repeat step 2 for tcl files. Here is
+the example Tcl file after conversion:
     set title [_ simulation.admin_title]
 set context [list [list . [_ simulation.SimPlay]] \
                   [list [export_vars -base case-admin { case_id }] \
                     [_ simulation.lt_Administer_name_gt]] \
                   [_ simulation.lt_Messages_for_role_pre]]

  • -Internationalize SQL Code. If there is any -user-visible Tcl code in the .sql or .xql files, internationalize -that the same way as for the Tcl files.

  • -Internationalize Package Parameters.  See -Multilingual APM Parameters +Internationalize SQL Code. If there +is any user-visible Tcl code in the .sql or .xql files, +internationalize that the same way as for the Tcl files.

  • +Internationalize Package +Parameters.  See Multilingual APM Parameters

  • -

    Internationalize Date and Time queries. 

      +

      Internationalize Date and Time +queries. 

      1. Find datetime in .xql files. Use command line tools to find suspect SQL code:

        @@ -100,27 +102,27 @@

      2. In Tcl files where the date fields are used, convert the -datetime from local server timezone, which is how it's stored in -the database, to the user's timezone for display. Do this with the -localizing function lc_time_system_to_conn:

        +datetime from local server timezone, which is how it's stored
+in the database, to the user's timezone for display. Do this
+with the localizing function lc_time_system_to_conn:
         set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]
 
        When a datetime will be written to the database, first convert
-it from the user's local time to the server's timezone with
+it from the user's local time to the server's timezone with
 lc_time_conn_to_system.

      3. When a datetime field will be displayed, format it using the localizing function lc_time_fmt. lc_time_fmt takes two parameters, datetime and format code. Several format codes are usable for localization; they are placeholders that format dates with the -appropriate codes for the user's locale. These codes are: +appropriate codes for the user's locale. These codes are: %x, %X, %q, %Q, and %c. 

         set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]

        Use the _pretty version in your ADP page.

        • %c: Long date and time (Mon November 18, 2002 12:00 AM)

        • %x: Short date (11/18/02)

        • %X: Time (12:00 AM)

        • %q: Long date without weekday (November 18, 2002)

        • %Q: Long date with weekday (Monday November 18, 2002)

          • -

        The "q" format strings are OpenACS additions; the rest follow -unix standards (see man +

      The "q" format strings are OpenACS additions; the rest +follow unix standards (see man strftime).

    @@ -129,22 +131,24 @@ internationalize numbers, use lc_numeric $value, which formats the number using the appropriate decimal point and thousand separator for the locale.

  • -Internationalizing Forms. When coding forms, -remember to use message keys for each piece of text that is -user-visible, including form option labels and button labels.

  • +Internationalizing Forms. When +coding forms, remember to use message keys for each piece of text +that is user-visible, including form option labels and button +labels.

  • Checking the Consistency of -Catalog Files.  This section describes how to check -that the set of keys used in message lookups in tcl, adp, and info -files and the set of keys in the catalog file are identical. The -scripts below assume that message lookups in adp and info files are -on the format \#package_key.message_key\#, and that message lookups -in tcl files are always is done with one of the valid lookups -described above. The script further assumes that you have perl -installed and in your path. Run the script like this: acs-lang/bin/check-catalog.sh +Catalog Files.  This section describes how to +check that the set of keys used in message lookups in tcl, adp, and +info files and the set of keys in the catalog file are identical. +The scripts below assume that message lookups in adp and info files +are on the format \#package_key.message_key\#, and that message +lookups in tcl files are always is done with one of the valid +lookups described above. The script further assumes that you have +perl installed and in your path. Run the script like this: +acs-lang/bin/check-catalog.sh package_key

    where package_key is the key of the package that you want to -test. If you don't provide the package_key argument then all +test. If you don't provide the package_key argument then all packages with catalog files will be checked. The script will run its checks primarily on en_US xml catalog files.

    • @@ -154,15 +158,15 @@

  • Replace complicated keys with longer, simpler -keys. When writing in one language, it is possible -to create clever code to make correct text. In English, for -example, you can put an if -command at the end of a word which adds "s" if a count is anything -but 1. This pluralizes nouns correctly based on the data. However, -it is confusing to read and, when internationalized, may result in -message keys that are both confusing and impossible to set -correctly in some languages. While internationalizing, watch out -that the automate converter does not create such keys. Also, +keys. When writing in one language, it is +possible to create clever code to make correct text. In English, +for example, you can put an if +command at the end of a word which adds "s" if a count is +anything but 1. This pluralizes nouns correctly based on the data. +However, it is confusing to read and, when internationalized, may +result in message keys that are both confusing and impossible to +set correctly in some languages. While internationalizing, watch +out that the automate converter does not create such keys. Also, refactor compound text as you encounter it.

    The automated system can easily get confused by tags within message texts, so that it tries to create two or three message keys for one long string with a tag in the middle. In these cases, @@ -171,8 +175,8 @@ <p class="form-help-text"><b>Invitations</b> are sent, when this wizard is completed and casting begins.</p>

    has a bold tag which confuses the converter into thinking there -are two message keys for the text beginning "Invitations ..." where -there should be one:

    Instead, we cancel those keys, edit the file manually, and put +are two message keys for the text beginning "Invitations +..." where there should be one:

    Instead, we cancel those keys, edit the file manually, and put in a single temporary message tag:

       <p class="form-help-text"> <#Invitations_are_sent <b>Invitations</b> are sent, 
 when this wizard is completed and casting begins.#>
@@ -242,32 +246,32 @@

  • -Don't combine keys in display +Don't combine keys in display text. Converting a phrase from one language to another is usually more complicated than simply replacing each word with an equivalent. When several keys are concatenated, the resulting word order will not be correct for every language. -Different languages may use expressions or idioms that don't match -the phrase key-for-key. Create complete, distinct keys instead of -building text from several keys. For example:

    Original code:

    +Different languages may use expressions or idioms that don't
+match the phrase key-for-key. Create complete, distinct keys
+instead of building text from several keys. For example:
    Original code:
     multirow append links "New [bug_tracker::conn Bug]" 
 
    Problematic conversion:
     multirow append links "[_ bug-tracker.New] [bug_tracker::conn Bug]"
 
    Better conversion:
     set bug_label [bug_tracker::conn Bug]
 multirow append links "[_ bug-tracker.New_Bug]" "${url_prefix}bug-add"
-
    ... and include the variable in the key: "New %bug_label%". This gives translators
-more control over the phrase.
    In this example of bad i18n, full name is created by
+

    ... and include the variable in the key: "New %bug_label%". This gives +translators more control over the phrase.

    In this example of bad i18n, full name is created by concatenating first and last name (admittedly this is pervasive in the toolkit):

     <a href="\@past_version.maintainer_url\@" title="#­bug-tracker.Email# \@past_version.maintainer_email\@">
 \@past_version.maintainer_first_names\@ \@past_version.maintainer_last_name\@</a>

  • -Avoid unnecessary duplicate keys. When -phrases are exactly the same in several places, use a single -key.

    For common words such as Yes and No, you can use a library of +Avoid unnecessary duplicate +keys. When phrases are exactly the same in +several places, use a single key.

    For common words such as Yes and No, you can use a library of keys at acs-kernel. For example, instead of using myfirstpackage.Yes, you can use acs-kernel.Yes. You can also @@ -278,11 +282,12 @@ "Administer"), Translation server upgraded, and Localization questions.

  • -Don't internationalize internal code -words. Many packages use code words or key words, -such as "open" and "closed", which will never be shown to the user. -They may match key values in the database, or be used in a switch -or if statement. Don't change these.

    For example, the original code is

    +Don't internationalize internal code
+words. Many packages use code words or key
+words, such as "open" and "closed", which will
+never be shown to the user. They may match key values in the
+database, or be used in a switch or if statement. Don't change
+these.
    For example, the original code is
     workflow::case::add_log_data \            
        -entry_id $entry_id \        
        -key "resolution" \          
@@ -294,74 +299,77 @@
        -value [db_string select_resolution_code {}]
 
    But resolution is a keyword
 in a table and in the code, so this breaks the code. It should not
-have been internationalized at all. Here's another example of text
-that should not have been internationalized:
    +have been internationalized at all. Here's another example of
+text that should not have been internationalized:
     {show_patch_status "open"}
 
    It is broken if changed to
     {show_patch_status "[_ bug-tracker.open]"}

  • -Fix automatic truncated message keys. The -automatic converter may create unique but crytic message keys. -Watch out for these and replace them with more descriptive keys. -For example:

    +Fix automatic truncated message
+keys. The automatic converter may create
+unique but crytic message keys. Watch out for these and replace
+them with more descriptive keys. For example:
     <msg key="You">You can filter by this %component_name% by viisting %filter_url_string%</msg>
 <msg key="You_1">You do not have permission to map this patch to a bug. Only the submitter of the patch 
 and users with write permission on this Bug Tracker project (package instance) may do so.</msg>
 <msg key="You_2">You do not have permission to edit this patch. Only the submitter of the patch 
 and users with write permission on the Bug Tracker project (package instance) may do so.</msg>
-
    These would be more useful if they were, "you_can_filter",
+

    These would be more useful if they were, +"you_can_filter", "you_do_not_have_permission_to_map_this_patch", and -"you_do_not_have_permission_to_edit_this_patch". Don't worry about -exactly matching the english text, because that might change; -instead try to capture the meaning of the phrase. Ask yourself, if -I was a translator and didn't know how this application worked, -would this key and text make translation easy for me?

    Sometimes the automatic converter creates keys that don't +"you_do_not_have_permission_to_edit_this_patch". +Don't worry about exactly matching the english text, because +that might change; instead try to capture the meaning of the +phrase. Ask yourself, if I was a translator and didn't know how +this application worked, would this key and text make translation +easy for me?

    Sometimes the automatic converter creates keys that don't semantically match their text. Fix these:

     <msg key="Fix">for version</msg>
 <msg key="Fix_1">for</msg>
 <msg key="Fix_2">for Bugs</msg>

    Another example: Bug-tracker -component maintainer" was converted to "[_ bug-tracker.Bug-tracker]". Instead, it -should be bug_tracker_component_maintainer.

    +component maintainer"     was converted to "[_ bug-tracker.Bug-tracker]". +Instead, it should be bug_tracker_component_maintainer.

  • Translations in Avoid "clever" message -reuse. Translations may need to differ depending on -the context in which the message appears.

  • -Avoid plurals. Different languages create -plurals differently. Try to avoid keys which will change based on -the value of a number. OpenACS does not currently support +reuse. Translations may need to differ +depending on the context in which the message appears.

  • +Avoid plurals. Different languages +create plurals differently. Try to avoid keys which will change +based on the value of a number. OpenACS does not currently support internationalization of plurals. If you use two different keys, a plural and a singular form, your application will not localize properly for locales which use different rules or have more than two forms of plurals.

  • -Quoting in the message catalog for tcl. Watch -out for quoting and escaping when editing text that is also code. -For example, the original string

    +Quoting in the message catalog for
+tcl. Watch out for quoting and escaping when
+editing text that is also code. For example, the original
+string
     set title "Patch \"$patch_summary\" is nice."
 
    breaks if the message text retains all of the escaping that was
 in the tcl command:
     <msg>Patch \"$patch_summary\" is nice.</msg>
 
    When it becomes a key, it should be:
     <msg>Patch "$patch_summary" is nice.</msg>
 
    Also, some keys had %var;noquote%, which is not needed since
-those variables are not quoted (and in fact the variable won't even
-be recognized so you get the literal %var;noquote% in the
+those variables are not quoted (and in fact the variable won't
+even be recognized so you get the literal %var;noquote% in the
 output).

  • -Be careful with curly brackets. Code within -curly brackets isn't evaluated. Tcl uses curly brackets as an -alternative way to build lists. But Tcl also uses curly brackets as -an alternative to quotation marks for quoting text. So this -original code

    +Be careful with curly
+brackets. Code within curly brackets isn't
+evaluated. Tcl uses curly brackets as an alternative way to build
+lists. But Tcl also uses curly brackets as an alternative to
+quotation marks for quoting text. So this original code
     array set names { key "Pretty" ...} 
 
    ... if converted to
     array set names { key "[_bug-tracker.Pretty]" ...} 
-
    ... won't work since the _ func will not be called. Instead, it
-should be
    +
    ... won't work since the _ func will not be called. Instead,
+it should be
     array set names [list key [_bug-tracker.Pretty] ...]
    • Index: openacs-4/packages/acs-core-docs/www/i18n-convert.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-convert.html,v diff -u -N -r1.26.2.12 -r1.26.2.13 --- openacs-4/packages/acs-core-docs/www/i18n-convert.html 21 Jun 2016 07:44:36 -0000 1.26.2.12 +++ openacs-4/packages/acs-core-docs/www/i18n-convert.html 23 Jun 2016 08:32:45 -0000 1.26.2.13 @@ -36,9 +36,9 @@ See Multilingual APM Parameters

  • Internationalize Date and Time queries. 

    1. Find datetime in .xql files. Use command line tools to find suspect SQL code:

      grep -r "to_char.*H" *
 grep -r "to_date.*H" *
-

    2. In SQL statements, replace the format string with the ANSI standard format, YYYY-MM-DD HH24:MI:SS and change the field name to *_ansi so that it cannot be confused with previous, improperly formatting fields. For example,

      to_char(timestamp,'MM/DD/YYYY HH:MI:SS') as foo_date_pretty

      becomes

      to_char(timestamp,'YYYY-MM-DD HH24:MI:SS') as foo_date_ansi

    3. In Tcl files where the date fields are used, convert the datetime from local server timezone, which is how it's stored in the database, to the user's timezone for display. Do this with the localizing function lc_time_system_to_conn:

      -set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]

      When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with lc_time_conn_to_system. -

    4. When a datetime field will be displayed, format it using the localizing function lc_time_fmt. lc_time_fmt takes two parameters, datetime and format code. Several format codes are usable for localization; they are placeholders that format dates with the appropriate codes for the user's locale. These codes are: %x, %X, %q, %Q, and %c.

      set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]

      +

    5. In SQL statements, replace the format string with the ANSI standard format, YYYY-MM-DD HH24:MI:SS and change the field name to *_ansi so that it cannot be confused with previous, improperly formatting fields. For example,

      to_char(timestamp,'MM/DD/YYYY HH:MI:SS') as foo_date_pretty

      becomes

      to_char(timestamp,'YYYY-MM-DD HH24:MI:SS') as foo_date_ansi

    6. In Tcl files where the date fields are used, convert the datetime from local server timezone, which is how it's stored in the database, to the user's timezone for display. Do this with the localizing function lc_time_system_to_conn:

      +set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]

      When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with lc_time_conn_to_system. +

    7. When a datetime field will be displayed, format it using the localizing function lc_time_fmt. lc_time_fmt takes two parameters, datetime and format code. Several format codes are usable for localization; they are placeholders that format dates with the appropriate codes for the user's locale. These codes are: %x, %X, %q, %Q, and %c.

      set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]

      Use the _pretty version in your ADP page.

      • %c: Long date and time (Mon November 18, 2002 12:00 AM) @@ -69,7 +69,7 @@

        where package_key is the key of the package that you want to - test. If you don't provide the package_key argument then all + test. If you don't provide the package_key argument then all packages with catalog files will be checked. The script will run its checks primarily on en_US xml catalog files.

    Avoiding common i18n mistakes

    • Replace complicated keys with longer, simpler keys. When writing in one language, it is possible to create clever code to make correct text. In English, for example, you can put an if command at the end of a word which adds "s" if a count is anything but 1. This pluralizes nouns correctly based on the data. However, it is confusing to read and, when internationalized, may result in message keys that are both confusing and impossible to set correctly in some languages. While internationalizing, watch out that the automate converter does not create such keys. Also, refactor compound text as you encounter it.

      The automated system can easily get confused by tags within message texts, so that it tries to create two or three message keys for one long string with a tag in the middle. In these cases, uncheck those keys during the conversion and then edit the files directly. For example, this code:

        <p class="form-help-text"><b>Invitations</b> are sent,
@@ -128,7 +128,7 @@
   </if><else>
     <a href="@components.view_bugs_url@" title="#­bug-tracker.View_the_bug_fo_component#">#­bug-tracker.N_bugs#</a>
   </else>
-</if>

    • Don't combine keys in display text. Converting a phrase from one language to another is usually more complicated than simply replacing each word with an equivalent. When several keys are concatenated, the resulting word order will not be correct for every language. Different languages may use expressions or idioms that don't match the phrase key-for-key. Create complete, distinct keys instead of building text from several keys. For example:

      Original code:

      multirow append links "New [bug_tracker::conn Bug]"

      Problematic conversion:

      multirow append links "[_ bug-tracker.New] [bug_tracker::conn Bug]"

      Better conversion:

      set bug_label [bug_tracker::conn Bug]
+</if>

    • Don't combine keys in display text. Converting a phrase from one language to another is usually more complicated than simply replacing each word with an equivalent. When several keys are concatenated, the resulting word order will not be correct for every language. Different languages may use expressions or idioms that don't match the phrase key-for-key. Create complete, distinct keys instead of building text from several keys. For example:

      Original code:

      multirow append links "New [bug_tracker::conn Bug]"

      Problematic conversion:

      multirow append links "[_ bug-tracker.New] [bug_tracker::conn Bug]"

      Better conversion:

      set bug_label [bug_tracker::conn Bug]
 multirow append links "[_ bug-tracker.New_Bug]" "${url_prefix}bug-add"

      ... and include the variable in the key: "New %bug_label%". This gives translators more control over the phrase.

      In this example of bad i18n, full name is created by concatenating first and last name (admittedly this is pervasive in the toolkit):

      <a href="@past_version.maintainer_url@" title="#­bug-tracker.Email# @past_version.maintainer_email@">
 @past_version.maintainer_first_names@ @past_version.maintainer_last_name@</a>

    • Avoid unnecessary duplicate keys. When phrases are exactly the same in several places, use a single key.

      For common words such as Yes and No, you can use a library of keys at acs-kernel. @@ -141,22 +141,22 @@ across different locales.

      Additional discussion: Re: Bug 961 ("Control Panel" displayed instead of "Administer"), Translation - server upgraded, and Localization questions.

    • Don't internationalize internal code words. Many packages use code words or key words, such as "open" and "closed", which will never be shown to the user. They may match key values in the database, or be used in a switch or if statement. Don't change these.

      For example, the original code is 

      workflow::case::add_log_data \ 	    
+            server upgraded, and Localization questions.

    • Don't internationalize internal code words. Many packages use code words or key words, such as "open" and "closed", which will never be shown to the user. They may match key values in the database, or be used in a switch or if statement. Don't change these.

      For example, the original code is 

      workflow::case::add_log_data \ 	    
        -entry_id $entry_id \ 	    
        -key "resolution" \ 	    
        -value [db_string select_resolution_code {}]

      This is incorrectly internationalized to 

        workflow::case::add_log_data \ 	    
        -entry_id $entry_id \
        -key "[_ bug-tracker.resolution]" \
-       -value [db_string select_resolution_code {}]

      But resolution is a keyword in a table and in the code, so this breaks the code. It should not have been internationalized at all. Here's another example of text that should not have been internationalized:

      {show_patch_status "open"}

      It is broken if changed to

      {show_patch_status "[_ bug-tracker.open]"}

    • Fix automatic truncated message keys. The automatic converter may create unique but crytic message keys. Watch out for these and replace them with more descriptive keys. For example:

      +       -value [db_string select_resolution_code {}]

      But resolution is a keyword in a table and in the code, so this breaks the code. It should not have been internationalized at all. Here's another example of text that should not have been internationalized:

      {show_patch_status "open"}

      It is broken if changed to

      {show_patch_status "[_ bug-tracker.open]"}

    • Fix automatic truncated message keys. The automatic converter may create unique but crytic message keys. Watch out for these and replace them with more descriptive keys. For example:

       <msg key="You">You can filter by this %component_name% by viisting %filter_url_string%</msg>
 <msg key="You_1">You do not have permission to map this patch to a bug. Only the submitter of the patch 
 and users with write permission on this Bug Tracker project (package instance) may do so.</msg>
 <msg key="You_2">You do not have permission to edit this patch. Only the submitter of the patch 
-and users with write permission on the Bug Tracker project (package instance) may do so.</msg>

      These would be more useful if they were, "you_can_filter", "you_do_not_have_permission_to_map_this_patch", and "you_do_not_have_permission_to_edit_this_patch". Don't worry about exactly matching the english text, because that might change; instead try to capture the meaning of the phrase. Ask yourself, if I was a translator and didn't know how this application worked, would this key and text make translation easy for me? -

      Sometimes the automatic converter creates keys that don't semantically match their text. Fix these:

      <msg key="Fix">for version</msg>
+and users with write permission on the Bug Tracker project (package instance) may do so.</msg>

      These would be more useful if they were, "you_can_filter", "you_do_not_have_permission_to_map_this_patch", and "you_do_not_have_permission_to_edit_this_patch". Don't worry about exactly matching the english text, because that might change; instead try to capture the meaning of the phrase. Ask yourself, if I was a translator and didn't know how this application worked, would this key and text make translation easy for me? +

      Sometimes the automatic converter creates keys that don't semantically match their text. Fix these:

      <msg key="Fix">for version</msg>
 <msg key="Fix_1">for</msg>
 <msg key="Fix_2">for Bugs</msg>

      Another example: Bug-tracker component maintainer" was converted to "[_ bug-tracker.Bug-tracker]". Instead, it should be bug_tracker_component_maintainer.

    • Translations in Avoid "clever" message reuse. Translations may need to differ depending on the context in which the message appears.

    • Avoid plurals. Different languages create plurals differently. Try to avoid keys which will change based on the value of a number. OpenACS does not currently support internationalization of plurals. If you use two different keys, a plural and a singular form, your application will not localize properly for locales which use different rules or have more than two forms of plurals.

    • Quoting in the message catalog for tcl. Watch out for quoting and escaping when editing text that is also code. For example, the original string 

      set title "Patch \"$patch_summary\" is nice."

      breaks if the message text retains all of the escaping that was in the tcl command:

      <msg>Patch \"$patch_summary\" is nice.</msg>

      When it becomes a key, it should be:

      <msg>Patch "$patch_summary" is nice.</msg>

      Also, some keys had %var;noquote%, which is not needed since those - variables are not quoted (and in fact the variable won't even be - recognized so you get the literal %var;noquote% in the output).

    • Be careful with curly brackets. Code within curly brackets isn't evaluated. Tcl uses curly brackets as an alternative way to build lists. But Tcl also uses curly brackets as an alternative to quotation marks for quoting text. So this original code

      array set names { key "Pretty" ...}

      ... if converted to 

      array set names { key "[_bug-tracker.Pretty]" ...}

      ... won't work since the _ func will not be called. Instead, it should be 

      array set names [list key [_bug-tracker.Pretty] ...]
    Prev Home Next
    How Internationalization/Localization works in OpenACS Up Design Notes
    docs@openacs.org
    View comments on this page at openacs.org
    + variables are not quoted (and in fact the variable won't even be + recognized so you get the literal %var;noquote% in the output).

  • Be careful with curly brackets. Code within curly brackets isn't evaluated. Tcl uses curly brackets as an alternative way to build lists. But Tcl also uses curly brackets as an alternative to quotation marks for quoting text. So this original code

    array set names { key "Pretty" ...}

    ... if converted to 

    array set names { key "[_bug-tracker.Pretty]" ...}

    ... won't work since the _ func will not be called. Instead, it should be 

    array set names [list key [_bug-tracker.Pretty] ...]
    • Prev Home Next
    How Internationalization/Localization works in OpenACS Up Design Notes
    docs@openacs.org
    View comments on this page at openacs.org
    Index: openacs-4/packages/acs-core-docs/www/i18n-design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-design.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/i18n-design.adp 23 Sep 2015 11:54:33 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/i18n-design.adp 23 Jun 2016 08:32:45 -0000 1.1.2.2 @@ -14,17 +14,18 @@ following in order of precedence:

    1. Use user preference for this package (stored in ad_locale_user_prefs)

    2. Use system preference for the package (stored in -apm_packages)

    3. Use user's general preference (stored in user_preferences)

    4. Use Browser header (Accept-Language HTTP header)

    5. Use system locale (an APM parameter for acs_lang)

    6. default to en_US

      7. +apm_packages)

    7. Use user's general preference (stored in +user_preferences)

    8. Use Browser header (Accept-Language HTTP header)

    9. Use system locale (an APM parameter for acs_lang)

    10. default to en_US

    For ADP pages, message key lookup occurs in the templating engine. For Tcl pages, message key lookup happens with the _ function. In both cases, if the requested locale is not found but a locale which is the default -for the language which matches your locale's language is found, +for the language which matches your locale's language is found, then that locale is offered instead.

    \ No newline at end of file Index: openacs-4/packages/acs-core-docs/www/i18n-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-design.html,v diff -u -N -r1.16.2.1 -r1.16.2.2 --- openacs-4/packages/acs-core-docs/www/i18n-design.html 9 Jun 2016 08:44:49 -0000 1.16.2.1 +++ openacs-4/packages/acs-core-docs/www/i18n-design.html 23 Jun 2016 08:32:45 -0000 1.16.2.2 @@ -1,3 +1,3 @@ -Design Notes
    Alex logo
    Prev Chapter 14. Internationalization Next

    Design Notes

    User locale is a property of ad_conn, ad_conn locale. The request processor sets this by calling lang::conn::locale, which looks for the following in order of precedence:

    1. Use user preference for this package (stored in ad_locale_user_prefs)

    2. Use system preference for the package (stored in apm_packages)

    3. Use user's general preference (stored in user_preferences)

    4. Use Browser header (Accept-Language HTTP header)

    5. Use system locale (an APM parameter for acs_lang)

    6. default to en_US

    For ADP pages, message key lookup occurs in the templating engine. For Tcl pages, message key lookup happens with the _ function. In both cases, if the requested locale is not found but a locale which is the default for the language which matches your locale's language is -found, then that locale is offered instead.

    Prev Home Next
    How to Internationalize a Package Up Translator's Guide
    docs@openacs.org
    View comments on this page at openacs.org
    +Design Notes
    Alex logo
    Prev Chapter 14. Internationalization Next

    Design Notes

    User locale is a property of ad_conn, ad_conn locale. The request processor sets this by calling lang::conn::locale, which looks for the following in order of precedence:

    1. Use user preference for this package (stored in ad_locale_user_prefs)

    2. Use system preference for the package (stored in apm_packages)

    3. Use user's general preference (stored in user_preferences)

    4. Use Browser header (Accept-Language HTTP header)

    5. Use system locale (an APM parameter for acs_lang)

    6. default to en_US

    For ADP pages, message key lookup occurs in the templating engine. For Tcl pages, message key lookup happens with the _ function. In both cases, if the requested locale is not found but a locale which is the default for the language which matches your locale's language is +found, then that locale is offered instead.

    Prev Home Next
    How to Internationalize a Package Up Translator's Guide
    docs@openacs.org
    View comments on this page at openacs.org
    Index: openacs-4/packages/acs-core-docs/www/i18n-introduction.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-introduction.adp,v diff -u -N -r1.1.2.6 -r1.1.2.7 --- openacs-4/packages/acs-core-docs/www/i18n-introduction.adp 9 Jun 2016 08:44:49 -0000 1.1.2.6 +++ openacs-4/packages/acs-core-docs/www/i18n-introduction.adp 23 Jun 2016 08:32:45 -0000 1.1.2.7 @@ -15,20 +15,20 @@ works in OpenACS

    This document describes how to develop internationalized OpenACS packages, including writing new packages with internationalization and converting old packages. Text that users might see is -"localizable text"; replacing monolingual text and single-locale -date/time/money functions with generic functions is -"internationalization"; translating first generation text into a -specific language is "localization." At a minimum, all packages -should be internationalized. If you do not also localize your -package for different locales, volunteers may use a public -"localization server" to submit suggested text. Otherwise, your -package will not be usable for all locales.

    The main difference between monolingual and internationalized +"localizable text"; replacing monolingual text and +single-locale date/time/money functions with generic functions is +"internationalization"; translating first generation text +into a specific language is "localization." At a minimum, +all packages should be internationalized. If you do not also +localize your package for different locales, volunteers may use a +public "localization server" to submit suggested text. +Otherwise, your package will not be usable for all locales.

    The main difference between monolingual and internationalized packages is that all user-visible text in the code of an -internationalized package are coded as "message keys." The message -keys correspond to a message catalog, which contains versions of -the text for each available language. Script files (.adp and .tcl -and .vuh), database files (.sql), and APM parameters are -affected.

    Other differences include: all dates read or written to the +internationalized package are coded as "message keys." +The message keys correspond to a message catalog, which contains +versions of the text for each available language. Script files +(.adp and .tcl and .vuh), database files (.sql), and APM parameters +are affected.

    Other differences include: all dates read or written to the database must use internationalized functions. All displayed dates must use internationalized functions. All displayed numbers must use internationalized functions.

    Localizable text must be handled in ADP files, in Tcl files, and @@ -49,7 +49,7 @@

    Separate Templates for each Locale

    If the request processor finds a file named filename.locale.adp, where locale matches -the user's locale, it will process that file instead of +the user's locale, it will process that file instead of filename.adp. For example, for a user with locale tl_PH, the file index.tl_PH.adp, if found, @@ -67,18 +67,19 @@ then be dynamically replaced with real human language in the desired locale. Message keys themselves should be in ASCII English, as should all code. Three different syntaxes are possible for -message keys.

    "Short" syntax is the recommended syntax and should be used for -new development. When internationalizing an existing package, you -can use the "temporary" syntax, which the APM can use to -auto-generate missing keys and automatically translate to the short -syntax. The "verbose" syntax is useful while developing, because it -allows default text so that the page is usable before you have done -localization.

      +message keys.

      "Short" syntax is the recommended syntax and should be +used for new development. When internationalizing an existing +package, you can use the "temporary" syntax, which the +APM can use to auto-generate missing keys and automatically +translate to the short syntax. The "verbose" syntax is +useful while developing, because it allows default text so that the +page is usable before you have done localization.

      • The short: #package_key.message_key# -

        The advantage of the short syntax is that it's short. It's as -simple as inserting the value of a variable. Example: +

        The advantage of the short syntax is that it's short. +It's as simple as inserting the value of a variable. Example: + <span>#</span>forum.title#

      • @@ -89,9 +90,10 @@

        The verbose syntax allows you to specify a default text in a certain language. This syntax is not recommended anymore, but it can be convenient for development, because it still works even if -you haven't created the message in the message catalog yet, because -what it'll do is create the message key with the default text from -the tag as the localized message. Example: <trn key="forum.title" +you haven't created the message in the message catalog yet, +because what it'll do is create the message key with the +default text from the tag as the localized message. Example: +<trn key="forum.title" locale="en_US">Title</trn>

      • @@ -100,8 +102,8 @@ text#>

        This syntax has been designed to make it easy to internationalize existing pages. This is not a syntax that stays in -the page. As you'll see later, it'll be replaced with the short -syntax by a special feature of the APM. You may leave out the +the page. As you'll see later, it'll be replaced with the +short syntax by a special feature of the APM. You may leave out the message_key by writing an underscore (_) character instead, in which case a message key will be auto-generated by the APM. Example: <_ Title> @@ -116,11 +118,11 @@ formats:

        • Typical static key lookup: [_ package_key.message_key] - The message key and package key -used here must be string literals, they can't result from variable -evaluation.

        • Static key lookup with non-default locale: [lang::message::lookup $locale +used here must be string literals, they can't result from +variable evaluation.

        • Static key lookup with non-default locale: [lang::message::lookup $locale package_key.message_key] - The message key and package key -used here must be string literals, they can't result from variable -evaluation.

        • Dynamic key lookup: [lang::util::localize +used here must be string literals, they can't result from +variable evaluation.

        • Dynamic key lookup: [lang::util::localize $var_with_embedded_message_keys] - In this case the message keys in the variable var_with_embedded_message_keys must appear as string literals \#package_key.message_key\# somewhere in @@ -161,14 +163,14 @@ text_with_percentage_vars#>) and run the action replace tags with keys in the APM.

        The variable values in the message are usually fetched with -upvar, here is an example from dotlrn: ad_return_complaint 1 "Error: A [parameter::get --parameter classes_pretty_name] must have +upvar, here is an example from dotlrn: ad_return_complaint 1 "Error: A +[parameter::get -parameter classes_pretty_name] must have <em>no</em>[parameter::get -parameter -class_instances_pretty_plural] to be deleted" was replaced -by: set subject [parameter::get --localize -parameter classes_pretty_name] set class_instances -[parameter::get -localize -parameter class_instances_pretty_plural] -ad_return_complaint 1 [_ +class_instances_pretty_plural] to be deleted" was +replaced by: set subject +[parameter::get -localize -parameter classes_pretty_name] set +class_instances [parameter::get -localize -parameter +class_instances_pretty_plural] ad_return_complaint 1 [_ dotlrn.class_may_not_be_deleted]

        This kind of interpolation also works in adp files where adp variable values will be inserted into the message.

        Alternatively, you may pass in an array list of the variable @@ -183,25 +185,25 @@ # in curly braces (should return nothing, or possibly a few lines for inspection) find -iname '*.tcl'|xargs egrep -i '\{.*<#' -# Check if you've forgotten space between default key and text in message tags (should return nothing) +# Check if you've forgotten space between default key and text in message tags (should return nothing) find -iname '*.tcl'|xargs egrep -i '<#_[^ ]' # Review the list of tcl files with no message lookups for tcl_file in $(find -iname '*.tcl'); do egrep -L '(<#|\[_)' $tcl_file; done

        When you feel ready you may vist your package in the package manager and -run the action "Replace tags with keys and insert into catalog" on -the Tcl files that you've edited to replace the temporary tags with -calls to the message lookup procedure.

        +run the action "Replace tags with keys and insert into +catalog" on the Tcl files that you've edited to replace +the temporary tags with calls to the message lookup procedure.

        Dates, Times, and Numbers in Tcl files

        Most date, time, and number variables are calculated in Tcl files. Dates and times must be converted when stored in the database, when retrieved from the database, and when displayed. All -dates are stored in the database in the server's timezone, which is -an APM Parameter set at /acs-lang/admin/set-system-timezone and +dates are stored in the database in the server's timezone, +which is an APM Parameter set at /acs-lang/admin/set-system-timezone and readable at lang::system::timezone.. When retrieved from the database and displayed, dates and times must be localized -to the user's locale.

        +to the user's locale.

        @@ -227,7 +229,7 @@ <span>#</span>departments_pretty_name# -

        Then, depending on how we retrieve the value, here's what we +

        Then, depending on how we retrieve the value, here's what we get:

        Index: openacs-4/packages/acs-core-docs/www/i18n-introduction.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-introduction.html,v diff -u -N -r1.18.2.5 -r1.18.2.6 --- openacs-4/packages/acs-core-docs/www/i18n-introduction.html 9 Jun 2016 08:44:50 -0000 1.18.2.5 +++ openacs-4/packages/acs-core-docs/www/i18n-introduction.html 23 Jun 2016 08:32:45 -0000 1.18.2.6 @@ -33,7 +33,7 @@ which are static and mostly text, it may be easier to create a new ADP page for each language. In this case, the pages are distinguished by a file naming convention. -

        User Content

        OpenACS does not have a general system for supporting multiple, localized versions of user-input content. This document currently refers only to internationalizing the text in the package user interface.

        Separate Templates for each Locale

        If the request processor finds a file named filename.locale.adp, where locale matches the user's locale, it will process that file instead of filename.adp. For example, for a user with locale tl_PH, the file index.tl_PH.adp, if found, will be used instead of index.adp. The locale-specific file should thus contain text in the language appropriate for that locale. The code in the page, however, should still be in English. Message keys are processed normally.

        Message Catalogs

        Message Keys in Template Files (ADP Files)

        +

        User Content

        OpenACS does not have a general system for supporting multiple, localized versions of user-input content. This document currently refers only to internationalizing the text in the package user interface.

        Separate Templates for each Locale

        If the request processor finds a file named filename.locale.adp, where locale matches the user's locale, it will process that file instead of filename.adp. For example, for a user with locale tl_PH, the file index.tl_PH.adp, if found, will be used instead of index.adp. The locale-specific file should thus contain text in the language appropriate for that locale. The code in the page, however, should still be in English. Message keys are processed normally.

        Message Catalogs

        Message Keys in Template Files (ADP Files)

        Internationalizing templates is about replacing human readable text in a certain language with internal message keys, which can then be dynamically replaced with real human language in @@ -52,7 +52,7 @@ The short: #package_key.message_key#

        - The advantage of the short syntax is that it's short. It's + The advantage of the short syntax is that it's short. It's as simple as inserting the value of a variable. Example: <span>#</span>forum.title#

      • @@ -64,8 +64,8 @@ The verbose syntax allows you to specify a default text in a certain language. This syntax is not recommended anymore, but it can be convenient for development, because - it still works even if you haven't created the message - in the message catalog yet, because what it'll do is + it still works even if you haven't created the message + in the message catalog yet, because what it'll do is create the message key with the default text from the tag as the localized message. Example: <trn key="forum.title" locale="en_US">Title</trn> @@ -76,7 +76,7 @@

        This syntax has been designed to make it easy to internationalize existing pages. This is not a syntax that - stays in the page. As you'll see later, it'll be replaced + stays in the page. As you'll see later, it'll be replaced with the short syntax by a special feature of the APM. You may leave out the message_key by writing an underscore (_) character instead, in which case a message key will be @@ -88,8 +88,8 @@ \#package_key.message_key\#. In Tcl files all message lookups *must* be on either of the following formats:

        -

        • Typical static key lookup: [_ package_key.message_key] - The message key and package key used here must be string literals, they can't result from variable evaluation.

        • - Static key lookup with non-default locale: [lang::message::lookup $locale package_key.message_key] - The message key and package key used here must be string literals, they can't result from variable evaluation.

        • +

          • Typical static key lookup: [_ package_key.message_key] - The message key and package key used here must be string literals, they can't result from variable evaluation.

          • + Static key lookup with non-default locale: [lang::message::lookup $locale package_key.message_key] - The message key and package key used here must be string literals, they can't result from variable evaluation.

          • Dynamic key lookup: [lang::util::localize $var_with_embedded_message_keys] - In this case the message keys in the variable var_with_embedded_message_keys must appear as string literals \#package_key.message_key\# somewhere in the code. Here is an example of a dynamic lookup: set message_key_array { dynamic_key_1 \#package_key.message_key1\# @@ -162,7 +162,7 @@ # in curly braces (should return nothing, or possibly a few lines for inspection) find -iname '*.tcl'|xargs egrep -i '\{.*<#' -# Check if you've forgotten space between default key and text in message tags (should return nothing) +# Check if you've forgotten space between default key and text in message tags (should return nothing) find -iname '*.tcl'|xargs egrep -i '<#_[^ ]' # Review the list of tcl files with no message lookups @@ -171,19 +171,19 @@ When you feel ready you may vist your package in the package manager and run the action "Replace tags with keys - and insert into catalog" on the Tcl files that you've edited to + and insert into catalog" on the Tcl files that you've edited to replace the temporary tags with calls to the message lookup procedure.

            Dates, Times, and Numbers in Tcl files

            Most date, time, and number variables are calculated in Tcl files. Dates and times must be converted when stored in the database, when retrieved from the database, and when displayed. All dates - are stored in the database in the server's timezone, which is an + are stored in the database in the server's timezone, which is an APM Parameter set at /acs-lang/admin/set-system-timezone and readable at lang::system::timezone.. When retrieved from the database and displayed, dates and times must - be localized to the user's locale. + be localized to the user's locale.

          APM Parameters

          Some parameters contain text that need to be localized. In this case, instead of storing the real text in the parameter, @@ -198,7 +198,7 @@ Here are a couple of examples. Say we have the following two parameters, taken directly from the dotlrn package.

        • Parameter NameParameter Value
        class_instance_pages_csv<span>#</span>dotlrn.class_page_home_title#,Simple 2-Column;<span>#</span>dotlrn.class_page_calendar_title#,Simple 1-Column;<span>#</span>dotlrn.class_page_file_storage_title#,Simple 1-Column
        departments_pretty_name<span>#</span>departments_pretty_name#

        - Then, depending on how we retrieve the value, here's what we get: + Then, depending on how we retrieve the value, here's what we get:

        Command used to retrieve ValueRetrieved Value
        parameter::get -localize -parameter class_instances_pages_csvKurs Startseite,Simple 2-Column;Kalender,Simple 1-Column;Dateien,Simple 1-Column
        parameter::get -localize -parameter departments_pretty_nameAbteilung
        parameter::get -parameter departments_pretty_name<span>#</span>departments_pretty_name#

        The value in the rightmost column in the table above is the value returned by an invocation of parameter::get. Note that Index: openacs-4/packages/acs-core-docs/www/i18n-overview.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-overview.adp,v diff -u -N -r1.1.2.3 -r1.1.2.4 --- openacs-4/packages/acs-core-docs/www/i18n-overview.adp 9 Jun 2016 13:03:11 -0000 1.1.2.3 +++ openacs-4/packages/acs-core-docs/www/i18n-overview.adp 23 Jun 2016 08:32:45 -0000 1.1.2.4 @@ -11,8 +11,8 @@

        Internationalization and Localization Overview

        -

        Table 14.1. Internationalization and -Localization Overview

        +

        Table 14.1. Internationalization +and Localization Overview

        @@ -29,7 +29,7 @@ +each message key. (More information)
        The translation server is updated with the new package.Translation server maintainers
        LocalizationTranslators work in their respective locales to write text for -each message key. (More information)TranslatorsTranslators
        Release ManagementThe translated text in the database of the translation server is compared to the current translations in the OpenACS code base, Index: openacs-4/packages/acs-core-docs/www/i18n-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-overview.html,v diff -u -N -r1.16.2.1 -r1.16.2.2 --- openacs-4/packages/acs-core-docs/www/i18n-overview.html 9 Jun 2016 08:44:50 -0000 1.16.2.1 +++ openacs-4/packages/acs-core-docs/www/i18n-overview.html 23 Jun 2016 08:32:45 -0000 1.16.2.2 @@ -1,2 +1,2 @@ -Internationalization and Localization Overview
        Alex logo
        Prev Chapter 14. Internationalization Next

        Internationalization and Localization Overview

        Table 14.1. Internationalization and Localization Overview

        StageTaskWho
        InternationalizationPackage Developer uses the acs-lang tools to replace all visible text in a package with message keys. (More information)Package Developer
        Release ManagementThe newly internationalized package is released.Package Developer
        The translation server is updated with the new package.Translation server maintainers
        LocalizationTranslators work in their respective locales to write text for each message key. (More information)Translators
        Release ManagementThe translated text in the database of the translation server is compared to the current translations in the OpenACS code base, conflicts are resolved, and the new text is written to catalog files on the translation server.Translation server maintainers
        The catalog files are committed to the OpenACS code base.Translation server maintainers
        A new version of OpenACS core and/or affected packages is released and published in the OpenACS.org repository.Release Manager
        UpgradingSite Administrators upgrade their OpenACS sites, either via the automatic upgrade from the Repository or via tarball or CVS Site Administrators
        Site Administrators import the new translations. Existing local translations, if they exist, are not overwritten.Site Administrators

        Prev Home Next
        Chapter 14. Internationalization Up How Internationalization/Localization works in OpenACS
        docs@openacs.org
        View comments on this page at openacs.org
        +Internationalization and Localization Overview
        Alex logo
        Prev Chapter 14. Internationalization Next

        Internationalization and Localization Overview

        Table 14.1. Internationalization and Localization Overview

        StageTaskWho
        InternationalizationPackage Developer uses the acs-lang tools to replace all visible text in a package with message keys. (More information)Package Developer
        Release ManagementThe newly internationalized package is released.Package Developer
        The translation server is updated with the new package.Translation server maintainers
        LocalizationTranslators work in their respective locales to write text for each message key. (More information)Translators
        Release ManagementThe translated text in the database of the translation server is compared to the current translations in the OpenACS code base, conflicts are resolved, and the new text is written to catalog files on the translation server.Translation server maintainers
        The catalog files are committed to the OpenACS code base.Translation server maintainers
        A new version of OpenACS core and/or affected packages is released and published in the OpenACS.org repository.Release Manager
        UpgradingSite Administrators upgrade their OpenACS sites, either via the automatic upgrade from the Repository or via tarball or CVS Site Administrators
        Site Administrators import the new translations. Existing local translations, if they exist, are not overwritten.Site Administrators

        Prev Home Next
        Chapter 14. Internationalization Up How Internationalization/Localization works in OpenACS
        docs@openacs.org
        View comments on this page at openacs.org
        Index: openacs-4/packages/acs-core-docs/www/i18n-requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-requirements.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-core-docs/www/i18n-requirements.adp 9 Jun 2016 08:44:50 -0000 1.1.2.2 +++ openacs-4/packages/acs-core-docs/www/i18n-requirements.adp 23 Jun 2016 08:32:45 -0000 1.1.2.3 @@ -27,7 +27,7 @@ Definitions
        internationalization (i18n)

        The provision within a computer program of the capability of making itself adaptable to the requirements of different native -languages, local customs and coded character sets.

        locale

        The definition of the subset of a user's environment that +languages, local customs and coded character sets.

        locale

        The definition of the subset of a user's environment that depends on language and cultural conventions.

        localization (L10n)

        The process of establishing information within a computer system specific to the operation of particular native languages, local customs and coded character sets.

        globalization

        A product development approach which ensures that software @@ -103,9 +103,9 @@ content and navigation in multiple languages.

        The site would have an end-user visible UI to support these languages, and the content management system must allow articles to be posted in these languages. In some cases it may be necessary to -make the modules' admin UI's operate in more than one supported -language, while in other cases the backend admin interface can -operate in a single language.

        +make the modules' admin UI's operate in more than one +supported language, while in other cases the backend admin +interface can operate in a single language.

      • A developer is writing a new module, and wants to make it easy for someone to localize it. There should be a clear path to author the module so that future developers can easily add support for @@ -121,11 +121,11 @@

        • Related Links

        Tcl Source File Character @@ -300,8 +300,8 @@ be able to override the default system choice of character set when parsing and validating user form data. INCOMPLETE - form widgets in acs-templating/tcl/date-procs.tcl are not internationalized. Also, -acs-templating's UI needs to be internationalized by replacing all -user-visible strings with message keys. +acs-templating's UI needs to be internationalized by replacing +all user-visible strings with message keys.

        50.30.10In Japan and some other Asian languages where there are multiple character set @@ -364,7 +364,8 @@ system can format the output for the current locale. The datatype is defined by a standard OpenACS datatype plus a format token or format string, for example: a date column might be specified as -'current_date:date LONG,' or 'current_date:date "YYYY-Mon-DD"'

        +'current_date:date LONG,' or 'current_date:date +"YYYY-Mon-DD"'

        Forms

        @@ -390,10 +391,10 @@ locale-dependent way.

        80.20 For the Tcl API, we will say that locale-dependent sorting will use Oracle SQL -operations (i.e., we won't provide a Tcl API for this). We require -a Tcl API function to return the correct incantation of NLS_SORT to -use for a given locale with ORDER BY -clauses in queries.

        +operations (i.e., we won't provide a Tcl API for this). We +require a Tcl API function to return the correct incantation of +NLS_SORT to use for a given locale with ORDER +BY clauses in queries.

        80.40 The system must handle full-text search in any supported language.

        @@ -417,8 +418,8 @@ session or else UTC should be used to display every date and time.

        90.60 The default if we -can't determine a time zone is to display all dates and times in -some universal time zone such as GMT.

        +can't determine a time zone is to display all dates and times +in some universal time zone such as GMT.

        Index: openacs-4/packages/acs-core-docs/www/i18n-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-requirements.html,v diff -u -N -r1.26.2.1 -r1.26.2.2 --- openacs-4/packages/acs-core-docs/www/i18n-requirements.html 9 Jun 2016 08:44:50 -0000 1.26.2.1 +++ openacs-4/packages/acs-core-docs/www/i18n-requirements.html 23 Jun 2016 08:32:45 -0000 1.26.2.2 @@ -18,7 +18,7 @@ capability of making itself adaptable to the requirements of different native languages, local customs and coded character sets.

        locale

        - The definition of the subset of a user's environment that depends on + The definition of the subset of a user's environment that depends on language and cultural conventions.

        localization (L10n)

        The process of establishing information within a computer system @@ -94,7 +94,7 @@ Analysis

        Other application servers: ATG Dyanmo, Broadvision, Vignette, ... ? Anyone know how they deal with i18n ?

        Related Links

        Tcl Source File Character Set

        There are two classes of Tcl files loaded by the system; library files loaded at server startup, and page script files, which are run on each page request.

        Should we require all Tcl files be stored as UTF8? That seems too much of a burden on developers.

        50.10 Tcl library files can be authored @@ -198,7 +198,7 @@ override the default system choice of character set when parsing and validating user form data. INCOMPLETE - form widgets in acs-templating/tcl/date-procs.tcl are not - internationalized. Also, acs-templating's UI needs to be + internationalized. Also, acs-templating's UI needs to be internationalized by replacing all user-visible strings with message keys.

        50.30.10In Japan and some other Asian languages where there are multiple character set @@ -243,7 +243,7 @@ data to the content repository as well

        Sorting and Searching

        80.10 Support API for correct collation (sorting order) on lists of strings in locale-dependent way.

        80.20 For the Tcl API, we will say that locale-dependent sorting will use Oracle SQL operations (i.e., we -won't provide a Tcl API for this). We require a Tcl API +won't provide a Tcl API for this). We require a Tcl API function to return the correct incantation of NLS_SORT to use for a given locale with ORDER BY clauses in queries.

        80.40 The system must handle full-text @@ -256,7 +256,7 @@ universal time zone, UTC.

        90.40 For a registered users, a time zone preference should be stored.

        90.50 For a non-registered user a time zone preference should be attached via a session or else UTC should -be used to display every date and time.

        90.60 The default if we can't +be used to display every date and time.

        90.60 The default if we can't determine a time zone is to display all dates and times in some universal time zone such as GMT.

        Database

        100.10 Since UTF8 strings can use up to three (UCS2) or six (UCS4) bytes per character, make sure that Index: openacs-4/packages/acs-core-docs/www/i18n-translators.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-translators.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-core-docs/www/i18n-translators.adp 9 Jun 2016 13:03:11 -0000 1.1.2.2 +++ openacs-4/packages/acs-core-docs/www/i18n-translators.adp 23 Jun 2016 08:32:45 -0000 1.1.2.3 @@ -1,6 +1,6 @@ -{/doc/acs-core-docs {Documentation}} {Translator's Guide} -Translator's Guide +{/doc/acs-core-docs {Documentation}} {Translator's Guide} +Translator's Guide

        -Translator's Guide

        Most translators use the OpenACS Public +Translator's Guide

        Most translators use the OpenACS Public Translation Server, because the process of getting new message keys onto the server and getting new translations back into the distribution are handled by the maintainers of that machine. You @@ -23,8 +23,9 @@ Administration of Localization and create the locale.

      • -Translating with Translator Mode. To -translate messages in the pages they appear, Toggle Translator Mode and then browse to the +Translating with Translator +Mode. To translate messages in the pages they +appear, Toggle Translator Mode and then browse to the page you want to translate. Untranslated messages will have a yellow background and a red star that you click to translate the message. Translated messages have a green star next to them that is @@ -34,13 +35,15 @@ the bottom of each page.

      • -Batch translation. To translate many messages -at once, go to Administration of Localization, click on the locale to -translate, then click on a package, and then click Batch edit these messages.

        +Batch translation. To translate +many messages at once, go to Administration of Localization, +click on the locale to translate, then click on a package, and then +click Batch edit these +messages.

        • When creating a new locale based on an existing one, such as creating the Guatamalan version of Spanish, you can copy the -existing locale's catalog files using the script /packages/acs-core-docs/www/files/create-new-catalog.sh.

        +existing locale's catalog files using the script /packages/acs-core-docs/www/files/create-new-catalog.sh.

        -Translator's Guide
        Alex logo
        Prev Chapter 14. Internationalization Next

        Translator's Guide

        Most translators use the OpenACS Public Translation Server, because the process of getting new message keys onto the server and getting new translations back into the distribution are handled by the maintainers of that machine. You can also do translation work on your own OpenACS site; this makes your own translations more readily available to you but also means that your work will not be shared with other users unless you take extra steps (contacting an OpenACS core developer or submitting a patch) to get your work back to the OpenACS core.

        The basic steps for translators:

        • Go to the Localization page and choose the locale that you are translating to. If the locale is not present you need to visit Administration of Localization and create the locale.

        • Translating with Translator Mode. To translate messages in the pages they appear, Toggle Translator Mode and then browse to the page you want to translate. Untranslated messages will have a yellow background and a red star that you click to translate the message. Translated messages have a green star next to them that is a hyperlink to editing your translation. There is a history mechanism that allows you to see previous translations in case you would want to revert a translation.

          While in Translator mode, a list of all message keys appears at the bottom of each page.

        • Batch translation. To translate many messages at once, go to Administration of Localization, click on the locale to translate, then click on a package, and then click Batch edit these messages.

        When creating a new locale based on an existing one, such as creating the Guatamalan version of Spanish, you can copy the existing locale's catalog files using the script /packages/acs-core-docs/www/files/create-new-catalog.sh.

        Prev Home Next
        Design Notes Up Appendix D. Using CVS with an OpenACS Site
        docs@openacs.org
        View comments on this page at openacs.org
        +Translator's Guide
        Alex logo
        Prev Chapter 14. Internationalization Next

        Translator's Guide

        Most translators use the OpenACS Public Translation Server, because the process of getting new message keys onto the server and getting new translations back into the distribution are handled by the maintainers of that machine. You can also do translation work on your own OpenACS site; this makes your own translations more readily available to you but also means that your work will not be shared with other users unless you take extra steps (contacting an OpenACS core developer or submitting a patch) to get your work back to the OpenACS core.

        The basic steps for translators:

        • Go to the Localization page and choose the locale that you are translating to. If the locale is not present you need to visit Administration of Localization and create the locale.

        • Translating with Translator Mode. To translate messages in the pages they appear, Toggle Translator Mode and then browse to the page you want to translate. Untranslated messages will have a yellow background and a red star that you click to translate the message. Translated messages have a green star next to them that is a hyperlink to editing your translation. There is a history mechanism that allows you to see previous translations in case you would want to revert a translation.

          While in Translator mode, a list of all message keys appears at the bottom of each page.

        • Batch translation. To translate many messages at once, go to Administration of Localization, click on the locale to translate, then click on a package, and then click Batch edit these messages.

        When creating a new locale based on an existing one, such as creating the Guatamalan version of Spanish, you can copy the existing locale's catalog files using the script /packages/acs-core-docs/www/files/create-new-catalog.sh.

        Prev Home Next
        Design Notes Up Appendix D. Using CVS with an OpenACS Site
        docs@openacs.org
        View comments on this page at openacs.org
        Index: openacs-4/packages/acs-core-docs/www/i18n.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-core-docs/www/i18n.adp 9 Jun 2016 13:03:11 -0000 1.1.2.2 +++ openacs-4/packages/acs-core-docs/www/i18n.adp 23 Jun 2016 08:32:45 -0000 1.1.2.3 @@ -18,7 +18,7 @@ Overview
        How Internationalization/Localization works in OpenACS
        How to Internationalize a Package
        Design -Notes
        Translator's Guide
        +Notes
        Translator's Guide

        By Peter Marklund and Lars Pind Index: openacs-4/packages/acs-core-docs/www/i18n.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n.html,v diff -u -N -r1.34.2.1 -r1.34.2.2 --- openacs-4/packages/acs-core-docs/www/i18n.html 9 Jun 2016 08:44:50 -0000 1.34.2.1 +++ openacs-4/packages/acs-core-docs/www/i18n.html 23 Jun 2016 08:32:45 -0000 1.34.2.2 @@ -1,5 +1,5 @@ -Chapter 14. Internationalization

        Alex logo
        Prev Part III. For OpenACS Package Developers Next

        Chapter 14. Internationalization

        Table of Contents

        Internationalization and Localization Overview
        How Internationalization/Localization works in OpenACS
        How to Internationalize a Package
        Design Notes
        Translator's Guide

        +Chapter 14. Internationalization

        Alex logo
        Prev Part III. For OpenACS Package Developers Next

        Chapter 14. Internationalization

        Table of Contents

        Internationalization and Localization Overview
        How Internationalization/Localization works in OpenACS
        How to Internationalize a Package
        Design Notes
        Translator's Guide

        By Peter Marklund and Lars Pind

        Index: openacs-4/packages/acs-core-docs/www/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/index.adp,v diff -u -N -r1.26.2.12 -r1.26.2.13 --- openacs-4/packages/acs-core-docs/www/index.adp 21 Jun 2016 07:44:36 -0000 1.26.2.12 +++ openacs-4/packages/acs-core-docs/www/index.adp 23 Jun 2016 08:32:45 -0000 1.26.2.13 @@ -19,8 +19,8 @@
        Overview
        OpenACS Release Notes
        -
        II. Administrator's -Guide
        +
        II. +Administrator's Guide
        2. Installation Overview
        Basic @@ -170,7 +170,7 @@ Overview
        How Internationalization/Localization works in OpenACS
        How to Internationalize a Package
        Design -Notes
        Translator's Guide
        +Notes
        Translator's Guide
        D. Using CVS with an OpenACS Site
        IV. For OpenACS Index: openacs-4/packages/acs-core-docs/www/index.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/index.html,v diff -u -N -r1.53.2.10 -r1.53.2.11 --- openacs-4/packages/acs-core-docs/www/index.html 21 Jun 2016 07:44:36 -0000 1.53.2.10 +++ openacs-4/packages/acs-core-docs/www/index.html 23 Jun 2016 08:32:45 -0000 1.53.2.11 @@ -1,4 +1,4 @@ -OpenACS Core Documentation
        Alex logo
        Next

        OpenACS Core Documentation

        Table of Contents

        I. OpenACS For Everyone
        1. High level information: What is OpenACS?
        Overview
        OpenACS Release Notes
        II. Administrator's Guide
        2. Installation Overview
        Basic Steps
        Prerequisite Software
        3. Complete Installation
        Install a Unix-like system and supporting software
        Install Oracle 8.1.7
        Install PostgreSQL
        Install AOLserver 4
        Install OpenACS 5.9.0
        OpenACS Installation Guide for Windows
        OpenACS Installation Guide for Mac OS X
        4. Configuring a new OpenACS Site
        Installing OpenACS packages
        Mounting OpenACS packages
        Configuring an OpenACS package
        Setting Permissions on an OpenACS package
        How Do I?
        5. Upgrading
        Overview
        Upgrading 4.5 or higher to 4.6.3
        Upgrading OpenACS 4.6.3 to 5.0
        Upgrading an OpenACS 5.0.0 or greater installation
        Upgrading the OpenACS files
        Upgrading Platform components
        6. Production Environments
        Starting and Stopping an OpenACS instance.
        AOLserver keepalive with inittab
        Running multiple services on one machine
        High Availability/High Performance Configurations
        Staged Deployment for Production Networks
        Installing SSL Support for an OpenACS service
        Set up Log Analysis Reports
        External uptime validation
        Diagnosing Performance Problems
        7. Database Management
        Running a PostgreSQL database on another server
        Deleting a tablespace
        Vacuum Postgres nightly
        8. Backup and Recovery
        Backup Strategy
        Manual backup and recovery
        Automated Backup
        Using CVS for backup-recovery
        A. Install Red Hat 8/9
        B. Install additional supporting software
        Unpack the OpenACS tarball
        Initialize CVS (OPTIONAL)
        Add PSGML commands to emacs init file (OPTIONAL)
        Install Daemontools (OPTIONAL)
        Install qmail (OPTIONAL)
        Install Analog web file analyzer
        Install nspam
        Install Full Text Search using Tsearch2
        Install Full Text Search using OpenFTS (deprecated see tsearch2)
        Install nsopenssl
        Install tclwebtest.
        Install PHP for use in AOLserver
        Install Squirrelmail for use as a webmail system for OpenACS
        Install PAM Radius for use as external authentication
        Install LDAP for use as external authentication
        Install AOLserver 3.3oacs1
        C. Credits
        Where did this document come from?
        Linux Install Guides
        Security Information
        Resources
        III. For OpenACS Package Developers
        9. Development Tutorial
        Creating an Application Package
        Setting Up Database Objects
        Creating Web Pages
        Debugging and Automated Testing
        10. Advanced Topics
        Write the Requirements and Design Specs
        Add the new package to CVS
        OpenACS Edit This Page Templates
        Adding Comments
        Admin Pages
        Categories
        Profile your code
        Prepare the package for distribution.
        Distributing upgrades of your package
        Notifications
        Hierarchical data
        Using .vuh files for pretty urls
        Laying out a page with CSS instead of tables
        Sending HTML email from your application
        Basic Caching
        Scheduled Procedures
        Enabling WYSIWYG
        Adding in parameters for your package
        Writing upgrade scripts
        Connect to a second database
        Future Topics
        11. Development Reference
        OpenACS Packages
        OpenACS Data Models and the Object System
        The Request Processor
        The OpenACS Database Access API
        Using Templates in OpenACS
        Groups, Context, Permissions
        Writing OpenACS Application Pages
        Parties in OpenACS
        OpenACS Permissions Tediously Explained
        Object Identity
        Programming with AOLserver
        Using Form Builder: building html forms dynamically
        12. Engineering Standards
        OpenACS Style Guide
        +OpenACS Core Documentation
        Alex logo
        Next

        OpenACS Core Documentation

        Table of Contents

        I. OpenACS For Everyone
        1. High level information: What is OpenACS?
        Overview
        OpenACS Release Notes
        II. Administrator's Guide
        2. Installation Overview
        Basic Steps
        Prerequisite Software
        3. Complete Installation
        Install a Unix-like system and supporting software
        Install Oracle 8.1.7
        Install PostgreSQL
        Install AOLserver 4
        Install OpenACS 5.9.0
        OpenACS Installation Guide for Windows
        OpenACS Installation Guide for Mac OS X
        4. Configuring a new OpenACS Site
        Installing OpenACS packages
        Mounting OpenACS packages
        Configuring an OpenACS package
        Setting Permissions on an OpenACS package
        How Do I?
        5. Upgrading
        Overview
        Upgrading 4.5 or higher to 4.6.3
        Upgrading OpenACS 4.6.3 to 5.0
        Upgrading an OpenACS 5.0.0 or greater installation
        Upgrading the OpenACS files
        Upgrading Platform components
        6. Production Environments
        Starting and Stopping an OpenACS instance.
        AOLserver keepalive with inittab
        Running multiple services on one machine
        High Availability/High Performance Configurations
        Staged Deployment for Production Networks
        Installing SSL Support for an OpenACS service
        Set up Log Analysis Reports
        External uptime validation
        Diagnosing Performance Problems
        7. Database Management
        Running a PostgreSQL database on another server
        Deleting a tablespace
        Vacuum Postgres nightly
        8. Backup and Recovery
        Backup Strategy
        Manual backup and recovery
        Automated Backup
        Using CVS for backup-recovery
        A. Install Red Hat 8/9
        B. Install additional supporting software
        Unpack the OpenACS tarball
        Initialize CVS (OPTIONAL)
        Add PSGML commands to emacs init file (OPTIONAL)
        Install Daemontools (OPTIONAL)
        Install qmail (OPTIONAL)
        Install Analog web file analyzer
        Install nspam
        Install Full Text Search using Tsearch2
        Install Full Text Search using OpenFTS (deprecated see tsearch2)
        Install nsopenssl
        Install tclwebtest.
        Install PHP for use in AOLserver
        Install Squirrelmail for use as a webmail system for OpenACS
        Install PAM Radius for use as external authentication
        Install LDAP for use as external authentication
        Install AOLserver 3.3oacs1
        C. Credits
        Where did this document come from?
        Linux Install Guides
        Security Information
        Resources
        III. For OpenACS Package Developers
        9. Development Tutorial
        Creating an Application Package
        Setting Up Database Objects
        Creating Web Pages
        Debugging and Automated Testing
        10. Advanced Topics
        Write the Requirements and Design Specs
        Add the new package to CVS
        OpenACS Edit This Page Templates
        Adding Comments
        Admin Pages
        Categories
        Profile your code
        Prepare the package for distribution.
        Distributing upgrades of your package
        Notifications
        Hierarchical data
        Using .vuh files for pretty urls
        Laying out a page with CSS instead of tables
        Sending HTML email from your application
        Basic Caching
        Scheduled Procedures
        Enabling WYSIWYG
        Adding in parameters for your package
        Writing upgrade scripts
        Connect to a second database
        Future Topics
        11. Development Reference
        OpenACS Packages
        OpenACS Data Models and the Object System
        The Request Processor
        The OpenACS Database Access API
        Using Templates in OpenACS
        Groups, Context, Permissions
        Writing OpenACS Application Pages
        Parties in OpenACS
        OpenACS Permissions Tediously Explained
        Object Identity
        Programming with AOLserver
        Using Form Builder: building html forms dynamically
        12. Engineering Standards
        OpenACS Style Guide
        CVS Guidelines -
        Release Version Numbering
        Constraint naming standard
        ACS File Naming and Formatting Standards
        PL/SQL Standards
        Variables
        Automated Testing
        13. Documentation Standards
        OpenACS Documentation Guide
        Using PSGML mode in Emacs
        Using nXML mode in Emacs
        Detailed Design Documentation Template
        System/Application Requirements Template
        14. Internationalization
        Internationalization and Localization Overview
        How Internationalization/Localization works in OpenACS
        How to Internationalize a Package
        Design Notes
        Translator's Guide
        D. Using CVS with an OpenACS Site
        IV. For OpenACS Platform Developers
        15. Kernel Documentation
        Overview
        Object Model Requirements
        Object Model Design
        Permissions Requirements
        Permissions Design
        Groups Requirements
        Groups Design
        Subsites Requirements
        Subsites Design Document
        Package Manager Requirements
        Package Manager Design
        Database Access API
        OpenACS Internationalization Requirements
        Security Requirements
        Security Design
        Security Notes
        Request Processor Requirements
        Request Processor Design
        Documenting Tcl Files: Page Contracts and Libraries
        Bootstrapping OpenACS
        External Authentication Requirements
        16. Releasing OpenACS
        OpenACS Core and .LRN
        How to Update the OpenACS.org repository
        How to package and release an OpenACS Package
        How to Update the translations
        Index

        List of Figures

        4.1. Site Templates
        4.2. Granting Permissions
        4.3. Granting Permissions in 5.0
        5.1. Upgrading with the APM
        5.2. Upgrading a local CVS repository
        6.1. Multiple-server configuration
        6.2. Simple A/B Deployment - Step 1
        6.3. Simple A/B Deployment - Step 2
        6.4. Simple A/B Deployment - Step 3
        6.5. Complex A/B Deployment - Step 1
        6.6. Complex A/B Deployment - Step 2
        6.7. Complex A/B Deployment - Step 3
        6.8. Query Analysis example
        8.1. Backup and Recovery Strategy
        9.1. Assumptions in this section
        9.2. Tutorial Data Model
        9.3. The Database Creation Script
        9.4. Database Deletion Script
        9.5. Page Map
        10.1. Upgrading a local CVS repository
        11.1. Server file layout diagram
        11.2. Package file layout diagram

        List of Tables

        2.1. Default directories for a standard install
        2.2. Version Compatibility Matrix
        5.1. Assumptions in this section
        6.1. How it Works
        10.1. table showing ETP layout
        11.1. Package files
        11.2. Context Hierarchy Example
        11.3. acs_objects example data
        14.1. Internationalization and Localization Overview

        List of Examples

        12.1. Getting datetime from the database ANSI-style
        Next
        Part I. OpenACS For Everyone
        docs@openacs.org
        View comments on this page at openacs.org
        +
        Release Version Numbering
        Constraint naming standard
        ACS File Naming and Formatting Standards
        PL/SQL Standards
        Variables
        Automated Testing
        13. Documentation Standards
        OpenACS Documentation Guide
        Using PSGML mode in Emacs
        Using nXML mode in Emacs
        Detailed Design Documentation Template
        System/Application Requirements Template
        14. Internationalization
        Internationalization and Localization Overview
        How Internationalization/Localization works in OpenACS
        How to Internationalize a Package
        Design Notes
        Translator's Guide
        D. Using CVS with an OpenACS Site
        IV. For OpenACS Platform Developers
        15. Kernel Documentation
        Overview
        Object Model Requirements
        Object Model Design
        Permissions Requirements
        Permissions Design
        Groups Requirements
        Groups Design
        Subsites Requirements
        Subsites Design Document
        Package Manager Requirements
        Package Manager Design
        Database Access API
        OpenACS Internationalization Requirements
        Security Requirements
        Security Design
        Security Notes
        Request Processor Requirements
        Request Processor Design
        Documenting Tcl Files: Page Contracts and Libraries
        Bootstrapping OpenACS
        External Authentication Requirements
        16. Releasing OpenACS
        OpenACS Core and .LRN
        How to Update the OpenACS.org repository
        How to package and release an OpenACS Package
        How to Update the translations
        Index

        List of Figures

        4.1. Site Templates
        4.2. Granting Permissions
        4.3. Granting Permissions in 5.0
        5.1. Upgrading with the APM
        5.2. Upgrading a local CVS repository
        6.1. Multiple-server configuration
        6.2. Simple A/B Deployment - Step 1
        6.3. Simple A/B Deployment - Step 2
        6.4. Simple A/B Deployment - Step 3
        6.5. Complex A/B Deployment - Step 1
        6.6. Complex A/B Deployment - Step 2
        6.7. Complex A/B Deployment - Step 3
        6.8. Query Analysis example
        8.1. Backup and Recovery Strategy
        9.1. Assumptions in this section
        9.2. Tutorial Data Model
        9.3. The Database Creation Script
        9.4. Database Deletion Script
        9.5. Page Map
        10.1. Upgrading a local CVS repository
        11.1. Server file layout diagram
        11.2. Package file layout diagram

        List of Tables

        2.1. Default directories for a standard install
        2.2. Version Compatibility Matrix
        5.1. Assumptions in this section
        6.1. How it Works
        10.1. table showing ETP layout
        11.1. Package files
        11.2. Context Hierarchy Example
        11.3. acs_objects example data
        14.1. Internationalization and Localization Overview

        List of Examples

        12.1. Getting datetime from the database ANSI-style
        Next
        Part I. OpenACS For Everyone
        docs@openacs.org
        View comments on this page at openacs.org
        Index: openacs-4/packages/acs-core-docs/www/individual-programs.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/individual-programs.adp,v diff -u -N -r1.1.2.6 -r1.1.2.7 --- openacs-4/packages/acs-core-docs/www/individual-programs.adp 9 Jun 2016 13:03:11 -0000 1.1.2.6 +++ openacs-4/packages/acs-core-docs/www/individual-programs.adp 23 Jun 2016 08:32:45 -0000 1.1.2.7 @@ -79,25 +79,28 @@ Server, a Database, a Process Controller, and Source Control software. The following external links are for reference only.

        • -

          The OpenACS tarball +

          + +OpenACS 5.9.0. The OpenACS tarball comprises the core packages and many useful additional packages. This includes a full set of documentation. The tarball works with both PostgreSQL and Oracle. Some scripts require bash shell.

        • -Operating System. OpenACS is designed for a -Unix-like system. It is developed primarily in Linux. It can be run -on Mac OS X, and in Windows within VMWare.

            +Operating System. OpenACS is +designed for a Unix-like system. It is developed primarily in +Linux. It can be run on Mac OS X, and in Windows within VMWare.

            • -GNU/Linux. The installation assumes a linux -kernel of 2.2.22 or newer, or 2.4.14 or newer.

            • +GNU/Linux. The installation assumes +a linux kernel of 2.2.22 or newer, or 2.4.14 or newer.

            • FreeBSD. FreeBSD guide. The OpenACS Reference Platform uses shell scripts written for bash, which is the standard Linux shell. If you are -using a different shell, you will need to substitute your shell's -conventions for setting environment variables when appropriate, and -install bash to work with the scripts. Substitute fetch when the instructions -suggest you use wget to download software.

            • +using a different shell, you will need to substitute your +shell's conventions for setting environment variables when +appropriate, and install bash to work with the scripts. Substitute +fetch when the +instructions suggest you use wget to download software.

            • Mac OS X. the section called “OpenACS Installation Guide for Mac OS X” @@ -110,61 +113,80 @@

          • -Build Environment. The Reference Platform -installation compiles most programs from source code.

              -

            • You need -recent versions of these libraries for Oracle to work properly. For -Unicode support, you need glibc 2.2 or newer. This should be -included in your operating system distribution.

            • PostgreSQL and AOLserver require gmake to -compile. Note that on most linux distributions, GNU Make is simply -named make and there is no -gmake, whereas on BSD -distributions, make and -gmake are different --use -gmake.

              • +Build Environment. The Reference +Platform installation compiles most programs from source code.

                +

              • + +glibc 2.2 or newer, REQUIRED. You +need recent versions of these libraries for Oracle to work +properly. For Unicode support, you need glibc 2.2 or newer. This +should be included in your operating system distribution.

              • + +GNU Make +3.76.1 or newer, REQUIRED. PostgreSQL and +AOLserver require gmake to compile. Note that on most linux +distributions, GNU Make is simply named make and there is no gmake, whereas on BSD distributions, +make and gmake are different --use gmake.

            • -

                -

              • OpenACS is written -in Tcl, an interpreted language. A threaded version of the Tcl -interpreter must be installed for OpenACS to work. The Tcl +

                +Tcl 8.5.x. 

                  +

                • + +Tcl 8.5.x, REQUIRED. OpenACS is +written in Tcl, an interpreted language. A threaded version of the +Tcl interpreter must be installed for OpenACS to work. The Tcl interpreter that is included in most standard distributions may not -be thread safe.

                • The site-wide-search service, OpenFTS, -requires these to compile. (Debian users: apt-get install tcl8.5-dev). You need this +be thread safe.

                • + +Tcl 8.5.x development headers and libraries, +OPTIONAL.  The site-wide-search service, +OpenFTS, requires these to compile. (Debian users: apt-get install tcl8.5-dev). You need this to install OpenFTS.

              • -

                OpenACS 5.9.0 -uses those Tcl extensions to send e-mail out, among others.

                +

                + +Tcllib, REQUIRED.  OpenACS +5.9.0 uses those Tcl extensions to send e-mail out, among +others.

              • -

                OpenACS 5.9.0 stores -queries in XML files, so we use an AOLserver module called tDOM to -parse these files. (This replaces libxml2, which was used prior to -4.6.4.)

                +

                + +tDOM, REQUIRED. OpenACS 5.9.0 +stores queries in XML files, so we use an AOLserver module called +tDOM to parse these files. (This replaces libxml2, which was used +prior to 4.6.4.)

              • -

                tclwebtest -is a tool for testing web interfaces via Tcl scripts.

                +

                + +tclwebtest, +OPTIONAL. tclwebtest is a tool for testing web +interfaces via Tcl scripts.

              • -Web Server. The web server handles incoming -HTTP requests, provides a runtime environment for OpenACS's Tcl -code, connects to the database, sends out HTTP responses, and logs -requests and errors. OpenACS uses AOLserver; some people have had success running Apache with +Web Server. The web server handles +incoming HTTP requests, provides a runtime environment for +OpenACS's Tcl code, connects to the database, sends out HTTP +responses, and logs requests and errors. OpenACS uses AOLserver; +some people have had success running Apache with mod_nsd.

                • -

                  Provides the -base HTTP server

                  +

                  + +AOLserver 4.x, REQUIRED. Provides +the base HTTP server

                Mat Kovach is graciously maintaining an AOLserver distribution that includes all the patches and modules needed to run OpenACS 5.9.0. These instructions will describe how to install using his source distribution. He also has binaries for SuSE 7.3 and OpenBSD -2.8 (and perhaps more to come), currently located at uptime.openacs.org.

                It's also possible to download all the pieces and patches +2.8 (and perhaps more to come), currently located at uptime.openacs.org.

                It's also possible to download all the pieces and patches yourself:

                • AOLserver is available at aolserver.com

                • The OpenACS PostgreSQL driver (nspostgres.so) is available from SourceForge. If you do decide to use nspostgres.so, you have to remember to change the AOLserver config file to point to nspostgres.so instead of postgres.so. This guide -uses Mat Kovach's distro (i.e. postgres.so)

                • The patch that makes exec +uses Mat Kovach's distro (i.e. postgres.so)

                • The patch that makes exec work on BSD is available at sourceforge.net

                • The patch for aolserver 3.x that makes ns_uuencode work for binary files is available at sourceforge.net @@ -179,94 +201,123 @@ webserver. aolserver3.x requires nsopenssl 2.1a. aolserver4.x requires nsopenssl3; see aolserver.com for latest release. (home page)

                • -

                  Provides -PAM capabilities for AOLserver. You need this if you want OpenACS -users to authenticate through a PAM module (such as RADIUS).

                  +

                  + +ns_pam 0.1 or newer, +OPTIONAL. Provides PAM capabilities for +AOLserver. You need this if you want OpenACS users to authenticate +through a PAM module (such as RADIUS).

                • -

                  Provides -RADIUS capabilities for PAM. You need this if you want to use -RADIUS authentication via PAM in OpenACS.

                  +

                  + +pam_radius 1.3.16, +OPTIONAL. Provides RADIUS capabilities for +PAM. You need this if you want to use RADIUS authentication via PAM +in OpenACS.

                • -

                  Provides -LDAP capabilities for AOLserver. You need this if you want to use -LDAP authentication in OpenACS.

                  +

                  + +ns_ldap 0.r8, +OPTIONAL. Provides LDAP capabilities for +AOLserver. You need this if you want to use LDAP authentication in +OpenACS.

                • -

                  Adds -full-text-search to PostgreSQL and includes a driver for AOLserver. -You need this if you want users to be able to search for any text -on your site. For postgres 7.4.x and higher, full text search is -also available via tsearch2.

                  +

                  + +OpenFTS Tcl 0.3.2, +OPTIONAL. Adds full-text-search to PostgreSQL +and includes a driver for AOLserver. You need this if you want +users to be able to search for any text on your site. For postgres +7.4.x and higher, full text search is also available via +tsearch2.

                • -This program examines web -server request logs, looks up DNS values, and produces a report. -You need this if you want to see how much traffic your site is -getting.

                • -"Balance is a simple but powerful generic -tcp proxy with round robin load balancing and failover mechanisms." -You need this or something equivalent if you are running a -high-availability production site and do not have an external load -balancing system.

                • + +Analog 5.32 or newer, +OPTIONAL. This program examines web server +request logs, looks up DNS values, and produces a report. You need +this if you want to see how much traffic your site is getting.

                • + +Balance 3.11 or newer, +OPTIONAL. "Balance is a simple but +powerful generic tcp proxy with round robin load balancing and +failover mechanisms." You need this or something equivalent if +you are running a high-availability production site and do not have +an external load balancing system.

                • -Database. The data on your site (for example, -user names and passwords, calender entries, and notes) is stored in -the database. OpenACS separates the database with an abstraction -layer, which means that several different databases all function -identically. While you can run the core OpenACS on any supported -database, not all contributed packages support all databases.

                    +Database. The data on your site +(for example, user names and passwords, calender entries, and +notes) is stored in the database. OpenACS separates the database +with an abstraction layer, which means that several different +databases all function identically. While you can run the core +OpenACS on any supported database, not all contributed packages +support all databases.

                  • -Process Controller. This is software that -initiates other software, and restarts that software if it fails. -On Linux, we recommend using Daemontools to control AOLserver and -qmail.

                    • -

                      You need -this if you want AOLserver and qmail to run "supervised," meaning -that they are monitored and automatically restarted if they fail. -An alternative would be to run the services from inittab.

                      +Process Controller. This is +software that initiates other software, and restarts that software +if it fails. On Linux, we recommend using Daemontools to control +AOLserver and qmail.

                      • +

                        + +Daemontools 0.76, OPTIONAL. You +need this if you want AOLserver and qmail to run +"supervised," meaning that they are monitored and +automatically restarted if they fail. An alternative would be to +run the services from inittab.

                    • -Mail Transport Agent. A Mail Transport Agent -is a program that handles all incoming and outgoing mail. The -Reference Platform uses Qmail; any MTA that provides a sendmail -wrapper (that is, that can be invoked by calling the sendmail -program with the same variables that sendmail expects) can be -used.

                        +Mail Transport Agent. A Mail +Transport Agent is a program that handles all incoming and outgoing +mail. The Reference Platform uses Qmail; any MTA that provides a +sendmail wrapper (that is, that can be invoked by calling the +sendmail program with the same variables that sendmail expects) can +be used.

                        • -You need this -(or a different Mail Transport Agent) if you want your webserver to -send and receive email.

                        • -This + +Netqmail 1.04, +OPTIONAL. You need this (or a different Mail +Transport Agent) if you want your webserver to send and receive +email.

                        • + +ucspi-tcp 0.88, OPTIONAL. This program listens for incoming TCP connections and hands them to a program. We use it instead of inetd, which is insecure. You need this if you are running qmail.

                        -

                      • (docbook-xml v4.4, -docbook-xsl v1.56, libxslt 1.0.21, xsltproc 1.0.21). You need this -to write or edit documentation.

                      • +

                      • + +DocBook, OPTIONAL. (docbook-xml +v4.4, docbook-xsl v1.56, libxslt 1.0.21, xsltproc 1.0.21). You need +this to write or edit documentation.

                      • -Source Control. A Source Control system keeps -track of all of the old versions of your files. It lets you recover -old files, compare versions of file, and identify specific versions -of files. You can use any source control system; the Reference -Platform and the OpenACS.org repository (where you can get patched -and development code in between releases) use cvs.

                        • cvs is included -in most unix distributions. You need this if you want to track old -versions of your files, do controlled deployment of code from -development to production, or get or contribute development code -from openacs.org.

                        +Source Control. A Source Control +system keeps track of all of the old versions of your files. It +lets you recover old files, compare versions of file, and identify +specific versions of files. You can use any source control system; +the Reference Platform and the OpenACS.org repository (where you +can get patched and development code in between releases) use +cvs.

                        • + +cvs 1.11.18, OPTIONAL. cvs is +included in most unix distributions. You need this if you want to +track old versions of your files, do controlled deployment of code +from development to production, or get or contribute development +code from openacs.org.

                        • -
                      ($‌Id: software.xml,v 1.26 2014/10/27 16:39:31 -victorg Exp $)
                      +
                    ($‌Id: individual-programs.html,v 1.33.2.10 +2016/06/21 07:44:36 gustafn Exp $)

                  • GNU/Linux. The installation assumes a linux kernel of 2.2.22 or newer, or 2.4.14 or newer.

                  • FreeBSD. FreeBSD guide. The OpenACS Reference Platform uses shell scripts written for bash, which is the standard Linux shell. If you are using a different - shell, you will need to substitute your shell's + shell, you will need to substitute your shell's conventions for setting environment variables when appropriate, and install bash to work with the scripts. Substitute fetch when the instructions suggest you use wget to download software.

                  • Mac OS X. the section called “OpenACS Installation Guide for Mac OS X”

                  • Windows/VMWare. the section called “OpenACS Installation Guide for Windows” The only @@ -58,15 +58,15 @@ distribution. He also has binaries for SuSE 7.3 and OpenBSD 2.8 (and perhaps more to come), currently located at uptime.openacs.org.

                    - It's also possible to download all the pieces and patches yourself: + It's also possible to download all the pieces and patches yourself:

                    • AOLserver is available at aolserver.com

                    • The OpenACS PostgreSQL driver (nspostgres.so) is available from SourceForge. If you do decide to use nspostgres.so, you have to remember to change the AOLserver config file to point to nspostgres.so - instead of postgres.so. This guide uses Mat Kovach's distro + instead of postgres.so. This guide uses Mat Kovach's distro (i.e. postgres.so)

                    • Index: openacs-4/packages/acs-core-docs/www/install-cvs.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-cvs.adp,v diff -u -N -r1.1.2.10 -r1.1.2.11 --- openacs-4/packages/acs-core-docs/www/install-cvs.adp 21 Jun 2016 07:44:36 -0000 1.1.2.10 +++ openacs-4/packages/acs-core-docs/www/install-cvs.adp 23 Jun 2016 08:32:45 -0000 1.1.2.11 @@ -10,7 +10,7 @@ rightLink="psgml-for-emacs" rightLabel="Next">

                      -Initialize CVS (OPTIONAL)

                      CVS is a source control system. Create and initialize a +Initialize CVS (OPTIONAL)

                  CVS is a source control system. Create and initialize a directory for a local cvs repository.

                   [root tmp]# mkdir /cvsroot
 [root tmp]# cvs -d /cvsroot init
Index: openacs-4/packages/acs-core-docs/www/install-cvs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-cvs.html,v
diff -u -N -r1.40.2.10 -r1.40.2.11
--- openacs-4/packages/acs-core-docs/www/install-cvs.html	21 Jun 2016 07:44:36 -0000	1.40.2.10
+++ openacs-4/packages/acs-core-docs/www/install-cvs.html	23 Jun 2016 08:32:45 -0000	1.40.2.11
@@ -1,5 +1,5 @@
 
-Initialize CVS (OPTIONAL)
                  Alex logo
                  Prev Appendix B. Install additional supporting software Next
                  Initialize CVS (OPTIONAL)
                  CVS is a source control system.  Create and initialize a
+Initialize CVS (OPTIONAL)
                  Alex logo
                  Prev Appendix B. Install additional supporting software Next
                  Initialize CVS (OPTIONAL)
                  CVS is a source control system.  Create and initialize a
       directory for a local cvs repository.
                  [root tmp]# mkdir /cvsroot
 [root tmp]# cvs -d /cvsroot init
 [root tmp]#
Index: openacs-4/packages/acs-core-docs/www/install-daemontools.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-daemontools.adp,v
diff -u -N -r1.1.2.10 -r1.1.2.11
--- openacs-4/packages/acs-core-docs/www/install-daemontools.adp	21 Jun 2016 07:44:36 -0000	1.1.2.10
+++ openacs-4/packages/acs-core-docs/www/install-daemontools.adp	23 Jun 2016 08:32:45 -0000	1.1.2.11
@@ -16,7 +16,7 @@
 svgroup. svgroup is a script for granting permissions, to allow
 users other than root to use daemontools for specific services.
                    
 
                  1. 
-
                    Install Daemontools
                    
+
                    Install Daemontools
                    
 download
 daemontools and install it.
                      
 
                    • 
Index: openacs-4/packages/acs-core-docs/www/install-daemontools.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-daemontools.html,v
diff -u -N -r1.41.2.10 -r1.41.2.11
--- openacs-4/packages/acs-core-docs/www/install-daemontools.html	21 Jun 2016 07:44:36 -0000	1.41.2.10
+++ openacs-4/packages/acs-core-docs/www/install-daemontools.html	23 Jun 2016 08:32:45 -0000	1.41.2.11
@@ -4,7 +4,7 @@
       installed in /package.  These commands install daemontools and
       svgroup.  svgroup is a script for granting permissions, to allow
       users other than root to use daemontools for specific
-      services.
                      1. Install Daemontools
                        download daemontools and install it.
                        • Red Hat 8
                          [root root]# mkdir -p /package
+      services.
                          1. Install Daemontools
                            download daemontools and install it.
                            • Red Hat 8
                              [root root]# mkdir -p /package
 [root root]# chmod 1755 /package/
 [root root]# cd /package/
 [root package]# tar xzf /tmp/daemontools-0.76.tar.gz
Index: openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.adp,v
diff -u -N -r1.1.2.10 -r1.1.2.11
--- openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.adp	21 Jun 2016 07:44:36 -0000	1.1.2.10
+++ openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.adp	23 Jun 2016 08:32:45 -0000	1.1.2.11
@@ -36,7 +36,7 @@
 [postgres pgsql]$ cd /usr/local/src/postgresql-7.3.4/contrib/tsearch/
 [postgres tsearch]$ make
 sed 's,MODULE_PATHNAME,$libdir/tsearch,g' tsearch.sql.in >tsearch.sql
-/usr/bin/flex  -8 -Ptsearch_yy -o'parser.c' parser.l(many lines omitted)
+/usr/bin/flex  -8 -Ptsearch_yy -o'parser.c' parser.l(many lines omitted)
 rm -f libtsearch.so
 ln -s libtsearch.so.0.0 libtsearch.so
 [postgres tsearch]$ make install
@@ -137,10 +137,11 @@
 /usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts/openfts.sql
 
                              
 
                              Note
                              If you get the error ERROR: could
-not access file "$libdir/tsearch": no such file or directory
-It is probably because PostgreSQL's libdir configuration variable
-points to a diffent directory than where tsearch is. You can find
-out where PostgreSQL expects to find tsearch via
                              pg_config --pkglibdir
                              
+not access file "$libdir/tsearch": no such file or
+directory It is probably because PostgreSQL's libdir
+configuration variable points to a diffent directory than where
+tsearch is. You can find out where PostgreSQL expects to find
+tsearch via
                              pg_config --pkglibdir
                              
 
                              
 
                            
 
                            
@@ -167,13 +168,13 @@
 
                          
 
                        • Wait a minute, then browse back to the home page.
                        • Click on Admin on the
 top of the screen.
                        • Click on Main Site
-Administration in the "Subsite Administration"
-section.
                        • Click on Site Map in
+Administration in the "Subsite
+Administration" section.
                        • Click on Site Map in
 the "Advanced Features" section.
                        • 
 
                          Mount the OpenFTS Full Text Search Engine in the site map.
                            
 
                          1. Click the new sub
-folder link on the "/" line, the first line
-under Main Site:/.
                          2. Type openfts and
+folder link on the "/" line, the
+first line under Main Site:/.
                          3. Type openfts and
 click New.
                          4. On the new openfts
 line, click the mount
 link.
                          5. Click OpenFTS
Index: openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.html,v
diff -u -N -r1.11.2.10 -r1.11.2.11
--- openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.html	21 Jun 2016 07:44:36 -0000	1.11.2.10
+++ openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.html	23 Jun 2016 08:32:45 -0000	1.11.2.11
@@ -13,7 +13,7 @@
 [postgres pgsql]$ cd /usr/local/src/postgresql-7.3.4/contrib/tsearch/
 [postgres tsearch]$ make
 sed 's,MODULE_PATHNAME,$libdir/tsearch,g' tsearch.sql.in >tsearch.sql
-/usr/bin/flex  -8 -Ptsearch_yy -o'parser.c' parser.l(many lines omitted)
+/usr/bin/flex  -8 -Ptsearch_yy -o'parser.c' parser.l(many lines omitted)
 rm -f libtsearch.so
 ln -s libtsearch.so.0.0 libtsearch.so
 [postgres tsearch]$ make install
Index: openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.adp,v
diff -u -N -r1.1.2.10 -r1.1.2.11
--- openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.adp	21 Jun 2016 07:44:36 -0000	1.1.2.10
+++ openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.adp	23 Jun 2016 08:32:45 -0000	1.1.2.11
@@ -18,7 +18,7 @@
 OpenACS docs are written by the named authors, and may be edited by
 OpenACS documentation staff.
                          
 
                          
-Install Tsearch2 module
                          If you want full text search, and you are running PostgreSQL,
+Install Tsearch2 module
                      If you want full text search, and you are running PostgreSQL,
 install this module to support FTS. Do this step after you have
 installed both PostgreSQL and AOLserver. You will need the tseach2
 module form PostgreSQL contrib. This is included with the
@@ -98,8 +98,8 @@

                • Wait a minute, then browse back to the home page.

                • Click on Admin on the top of the screen.

                • Click on Main Site -Administration in the "Subsite Administration" -section.

                • Click on Site Map in +Administration in the "Subsite +Administration" section.

                • Click on Site Map in the "Advanced Features" section.

                • Mount the Search interface in the site map.

                  1. Click the new sub Index: openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html,v diff -u -N -r1.11.2.10 -r1.11.2.11 --- openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html 21 Jun 2016 07:44:36 -0000 1.11.2.10 +++ openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html 23 Jun 2016 08:32:45 -0000 1.11.2.11 @@ -6,7 +6,7 @@ V2 Introduction by Andrew J. Kopciuch

                    OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

                  Install Tsearch2 module

                  If you want full text search, and you are running PostgreSQL, install this module to support FTS. Do this step after you have installed both PostgreSQL and +

                  Install Tsearch2 module

                  If you want full text search, and you are running PostgreSQL, install this module to support FTS. Do this step after you have installed both PostgreSQL and AOLserver. You will need the tseach2 module form PostgreSQL contrib. This is included with the PostgreSQL full source distribution. It is also available with the PostgreSQL contrib Index: openacs-4/packages/acs-core-docs/www/install-ldap-radius.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-ldap-radius.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-core-docs/www/install-ldap-radius.adp 9 Jun 2016 13:03:11 -0000 1.1.2.2 +++ openacs-4/packages/acs-core-docs/www/install-ldap-radius.adp 23 Jun 2016 08:32:45 -0000 1.1.2.3 @@ -21,8 +21,8 @@ these section

                  1. -Install openldap. Download and install -ns_ldap

                    +Install openldap. Download and
+install ns_ldap
                     [root aolserver]# cd /usr/local/src/
           [root src]# wget ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-2.2.17.tgz
           [root src]# tar xvfz openldap-2.2.17.tgz
@@ -40,8 +40,8 @@

                  2. -Install ns_ldap. Download and install -ns_ldap

                    +Install ns_ldap. Download and
+install ns_ldap
                     [root aolserver]# cd /usr/local/src/aolserver/
           [root aolserver]# wget http://www.sussdorff.de/ressources/nsldap.tgz
           [root aolserver]# tar xfz nsldap.tgz
@@ -58,33 +58,34 @@

                  3. Configure ns_ldap for traditional -use. Traditionally OpenACS has supported ns_ldap -for authentification by storing the OpenACS password in an -encrypted field within the LDAP server called "userPassword". -Furthermore a CN field was used for searching for the username, -usually userID or something similar. This field is identical to the -usernamestored in OpenACS. -Therefore the login will only work if you change login method to -make use of the username instead.

                    • Change config.tcl. Remove +use. Traditionally OpenACS has supported +ns_ldap for authentification by storing the OpenACS password in an +encrypted field within the LDAP server called +"userPassword". Furthermore a CN field was used for +searching for the username, usually userID or something similar. +This field is identical to the usernamestored in OpenACS. Therefore the +login will only work if you change login method to make use of the +username instead.

                      • Change config.tcl. Remove the # in front of ns_param nsldap ${bindir}/nsldap.so to enable the loading of the ns_ldap module.

                    • Configure ns_ldap for use with LDAP -bind. LDAP authentication usually is done by trying -to bind (aka. login) a user with the LDAP server. The password of -the user is not stored in any field of the LDAP server, but kept -internally. The latest version of ns_ldap supports this method with -the ns_ldap bind command. -All you have to do to enable this is to configure auth_ldap to make -use of the BIND authentification instead. Alternatively you can -write a small script on how to calculate the username out of the -given input (e.g. if the OpenACS username is malte.fb03.tu, the -LDAP request can be translated into "ou=malte,ou=fb03,o=tu" (this -example is encoded in auth_ldap and you just have to comment it out -to make use of it).

                      +bind. LDAP authentication usually is done by +trying to bind (aka. login) a user with the LDAP server. The +password of the user is not stored in any field of the LDAP server, +but kept internally. The latest version of ns_ldap supports this +method with the ns_ldap bind +command. All you have to do to enable this is to configure +auth_ldap to make use of the BIND authentification instead. +Alternatively you can write a small script on how to calculate the +username out of the given input (e.g. if the OpenACS username is +malte.fb03.tu, the LDAP request can be translated into +"ou=malte,ou=fb03,o=tu" (this example is encoded in +auth_ldap and you just have to comment it out to make use of +it).

                  Index: openacs-4/packages/acs-core-docs/www/install-more-software.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-more-software.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-core-docs/www/install-more-software.adp 9 Jun 2016 13:03:11 -0000 1.1.2.2 +++ openacs-4/packages/acs-core-docs/www/install-more-software.adp 23 Jun 2016 08:32:45 -0000 1.1.2.3 @@ -7,7 +7,7 @@

                  @@ -40,7 +40,7 @@ OpenACS documentation staff.

                  This section assumes that the source tarballs for supporting software are in /tmp. It assumes that you begin each continuous block of commands as root, -and you should end each block as root. It doesn't care which +and you should end each block as root. It doesn't care which directory you start in. Text instructions always precede the commands they refer to.

                  Index: openacs-4/packages/acs-core-docs/www/install-more-software.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-more-software.html,v diff -u -N -r1.22.2.1 -r1.22.2.2 --- openacs-4/packages/acs-core-docs/www/install-more-software.html 9 Jun 2016 08:44:50 -0000 1.22.2.1 +++ openacs-4/packages/acs-core-docs/www/install-more-software.html 23 Jun 2016 08:32:45 -0000 1.22.2.2 @@ -1,10 +1,10 @@ -Appendix B. Install additional supporting software
                  Alex logo
                  Prev Part II. Administrator's Guide Next

                  Appendix B. Install additional supporting software

                  Table of Contents

                  Unpack the OpenACS tarball
                  Initialize CVS (OPTIONAL)
                  Add PSGML commands to emacs init file (OPTIONAL)
                  Install Daemontools (OPTIONAL)
                  Install qmail (OPTIONAL)
                  Install Analog web file analyzer
                  Install nspam
                  Install Full Text Search using Tsearch2
                  Install Full Text Search using OpenFTS (deprecated see tsearch2)
                  Install nsopenssl
                  Install tclwebtest.
                  Install PHP for use in AOLserver
                  Install Squirrelmail for use as a webmail system for OpenACS
                  Install PAM Radius for use as external authentication
                  Install LDAP for use as external authentication
                  Install AOLserver 3.3oacs1

                  By Joel Aufrecht

                  +Appendix B. Install additional supporting software
                  Alex logo
                  Prev Part II. Administrator's Guide Next

                  Appendix B. Install additional supporting software

                  Table of Contents

                  Unpack the OpenACS tarball
                  Initialize CVS (OPTIONAL)
                  Add PSGML commands to emacs init file (OPTIONAL)
                  Install Daemontools (OPTIONAL)
                  Install qmail (OPTIONAL)
                  Install Analog web file analyzer
                  Install nspam
                  Install Full Text Search using Tsearch2
                  Install Full Text Search using OpenFTS (deprecated see tsearch2)
                  Install nsopenssl
                  Install tclwebtest.
                  Install PHP for use in AOLserver
                  Install Squirrelmail for use as a webmail system for OpenACS
                  Install PAM Radius for use as external authentication
                  Install LDAP for use as external authentication
                  Install AOLserver 3.3oacs1

                  By Joel Aufrecht

                  OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

                  This section assumes that the source tarballs for supporting software are in /tmp. It assumes that you begin each continuous block of commands as root, and you - should end each block as root. It doesn't care which directory + should end each block as root. It doesn't care which directory you start in. Text instructions always precede the commands they refer to.

                  Prev Home Next
                  Appendix A. Install Red Hat 8/9 Up Unpack the OpenACS tarball
                  docs@openacs.org
                  View comments on this page at openacs.org
                  Index: openacs-4/packages/acs-core-docs/www/install-next-add-server.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-next-add-server.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-core-docs/www/install-next-add-server.adp 9 Jun 2016 13:03:11 -0000 1.1.2.2 +++ openacs-4/packages/acs-core-docs/www/install-next-add-server.adp 23 Jun 2016 08:32:45 -0000 1.1.2.3 @@ -11,24 +11,26 @@

                  Running multiple services on one machine

                  -Services on different ports. To run a -different service on another port but the same ip, simply repeat +Services on different ports. To run +a different service on another port but the same ip, simply repeat Install OpenACS 5.9.0 replacing $OPENACS_SERVICE_NAME, and change the

                   set httpport              8000
 set httpsport             8443

                  to different values.

                  -Services on different host names. For -example, suppose you want to support http://service0.com and http://bar.com on the same machine. The -easiest way is to assign each one a different ip address. Then you -can install two services as above, but with different values -for

                  +Services on different host
+names. For example, suppose you want to
+support http://service0.com and
+http://bar.com on the same
+machine. The easiest way is to assign each one a different ip
+address. Then you can install two services as above, but with
+different values for
                   set hostname               [ns_info hostname]
 set address                127.0.0.1 
 
                  If you want to install two services with different host names
-sharing the same ip, you'll need nsvhr to redirect requests based
-on the contents of the tcp headers. See AOLserver Virtual Hosting with TCP by markd.
                  
+sharing the same ip, you'll need nsvhr to redirect requests
+based on the contents of the tcp headers. See AOLserver Virtual Hosting with TCP by markd.
                  
 
                  set hostname               [ns_info hostname]
 set address                127.0.0.1

                  If you want to install two services with different host - names sharing the same ip, you'll need nsvhr to redirect requests + names sharing the same ip, you'll need nsvhr to redirect requests based on the contents of the tcp headers. See AOLserver Virtual Hosting with TCP by markd.

                  Prev Home Next
                  AOLserver keepalive with inittab Up High Availability/High Performance Configurations
                  docs@openacs.org
                  View comments on this page at openacs.org
                  Index: openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.adp,v diff -u -N -r1.1.2.3 -r1.1.2.4 --- openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.adp 28 Sep 2015 07:54:19 -0000 1.1.2.3 +++ openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.adp 23 Jun 2016 08:32:45 -0000 1.1.2.4 @@ -9,25 +9,26 @@ rightLink="backup-recovery" rightLabel="Next">

                  -Vacuum Postgres nightly

                  The "vacuum" command must be run periodically to reclaim space -in versions of PostgreSQL before 7.4. The "vacuum analyze" form -additionally collects statistics on the disbursion of columns in -the database, which the optimizer uses when it calculates just how -to execute queries. The availability of this data can make a -tremendous difference in the execution speed of queries. This -command can also be run from cron, but it probably makes more sense -to run this command as part of your nightly backup procedure - if -"vacuum" is going to screw up the database, you'd prefer it to -happen immediately after (not before!) you've made a backup! The -"vacuum" command is very reliable, but conservatism is the key to -good system management. So, if you're using the export procedure -described above, you don't need to do this extra step.

                  Edit your crontab:

                  +Vacuum Postgres nightly

                  The "vacuum" command must be run periodically to +reclaim space in versions of PostgreSQL before 7.4. The +"vacuum analyze" form additionally collects statistics on +the disbursion of columns in the database, which the optimizer uses +when it calculates just how to execute queries. The availability of +this data can make a tremendous difference in the execution speed +of queries. This command can also be run from cron, but it probably +makes more sense to run this command as part of your nightly backup +procedure - if "vacuum" is going to screw up the +database, you'd prefer it to happen immediately after (not +before!) you've made a backup! The "vacuum" command +is very reliable, but conservatism is the key to good system +management. So, if you're using the export procedure described +above, you don't need to do this extra step.

                  Edit your crontab:

                   [joeuser ~]$ crontab -e
-

                  We'll set vacuum up to run nightly at 1 AM. Add the following -line:

                  +

                  We'll set vacuum up to run nightly at 1 AM. Add the +following line:

                   0 1 * * * /usr/local/pgsql/bin/vacuumdb $OPENACS_SERVICE_NAME
-
                  ($‌Id: database-maintenance.xml,v 1.8 2006/07/17 -05:38:37 torbenb Exp $)
                  +
                  ($‌Id: install-next-nightly-vacuum.html,v +1.23.2.10 2016/06/21 07:44:36 gustafn Exp $)

                Edit your crontab:

                [joeuser ~]$ crontab -e

                We'll set vacuum up to run nightly at 1 AM. Add the following +

                Edit your crontab:

                [joeuser ~]$ crontab -e

                We'll set vacuum up to run nightly at 1 AM. Add the following line:

                 0 1 * * * /usr/local/pgsql/bin/vacuumdb $OPENACS_SERVICE_NAME
                ($Id$)
              Prev Home Next
              Deleting a tablespace Up Chapter 8. Backup and Recovery
              docs@openacs.org
              View comments on this page at openacs.org
              Index: openacs-4/packages/acs-core-docs/www/install-nsopenssl.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-nsopenssl.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/install-nsopenssl.adp 23 Sep 2015 11:54:36 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/install-nsopenssl.adp 23 Jun 2016 08:32:45 -0000 1.1.2.2 @@ -18,7 +18,7 @@ to your site via https. These commands compile nsopenssl and install it, along with a tcl helper script to handle https connections. You will also need ssl certificates. Because those -should be different for each server service, you won't need +should be different for each server service, you won't need those instructions until later.

              @@ -96,9 +96,9 @@ to the nsd call. If you are using daemontools, this can be changed in your etc/daemontools/run file).

              To enable SSL support in your server, make sure your -etc/config.tcl file has a section on "OpenSSL 3 with AOLserver4". -If that section is not present, try looking at the README file in -/usr/local/src/aolserver/nsopenssl.

              +etc/config.tcl file has a section on "OpenSSL 3 with +AOLserver4". If that section is not present, try looking at +the README file in /usr/local/src/aolserver/nsopenssl.

              those instructions until + be different for each server service, you won't need those instructions until later.

              Install on AOLserver3

              You will need the unpacked Aolserver tarball in /usr/local/src/aolserver and the nsopenssl tarball in Index: openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.adp 23 Sep 2015 11:54:37 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.adp 23 Jun 2016 08:32:45 -0000 1.1.2.2 @@ -18,9 +18,9 @@ command in SVRMGRL with the cascade option. This command will drop the user and every database object the user owns.

               SVRMGR> drop user $OPENACS_SERVICE_NAME cascade;
-

              If this does not work because svrmgrl "cannot drop a user that -is currently connected", make sure to kill the AOLserver using this -user. If it still does not work, do:

              +

              If this does not work because svrmgrl "cannot drop a user +that is currently connected", make sure to kill the AOLserver +using this user. If it still does not work, do:

               SVRMGR> select username, sid, serial# from v$session where lower(username)='$OPENACS_SERVICE_NAME';

              and then

               SVRMGR> alter system kill session 'sid, serial#';
@@ -36,12 +36,11 @@
 Deleting a
 PostgreSQL tablespace

              Dropping a PostgreSQL tablespace is easy. You have to stop any AOLserver instances that are using the database that you wish to -drop. If you're using daemontools, this is simple, just use the -'down' flag (-d). If you're using inittab, you have to comment out -your server in /etc/inittab, -reread the inittab with /sbin/init -q, and then restart-aolserver -$OPENACS_SERVICE_NAME +drop. If you're using daemontools, this is simple, just use the +'down' flag (-d). If you're using inittab, you have to +comment out your server in /etc/inittab, reread the inittab with +/sbin/init q, and then +restart-aolserver $OPENACS_SERVICE_NAME .

              Then, to drop the db, just do:

               [$OPENACS_SERVICE_NAME ~]$ dropdb $OPENACS_SERVICE_NAME
 
Index: openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html,v
diff -u -N -r1.13.2.1 -r1.13.2.2
--- openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html	9 Jun 2016 08:44:50 -0000	1.13.2.1
+++ openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html	23 Jun 2016 08:32:45 -0000	1.13.2.2
@@ -15,8 +15,8 @@
         related to the service, you can also issue the following:
              SVRMGR> drop tablespace $OPENACS_SERVICE_NAME including contents cascade constraints;

            Deleting a PostgreSQL tablespace

            Dropping a PostgreSQL tablespace is easy. You have to stop any AOLserver instances that are using the database that you wish to - drop. If you're using daemontools, this is simple, just use the - 'down' flag (-d). If you're using inittab, you have to comment out + drop. If you're using daemontools, this is simple, just use the + 'down' flag (-d). If you're using inittab, you have to comment out your server in /etc/inittab, reread the inittab with /sbin/init q, and then restart-aolserver Index: openacs-4/packages/acs-core-docs/www/install-openacs-inittab.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-inittab.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/install-openacs-inittab.adp 23 Sep 2015 11:54:37 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/install-openacs-inittab.adp 23 Jun 2016 08:32:45 -0000 1.1.2.2 @@ -15,9 +15,9 @@ service on your machine, so proceed with caution.

            • There are 2 general steps to getting this working.

                -

              1. Install a script called restart-aolserver. This script doesn't -actually restart AOLserver - it just kills it.

              2. Ask the OS to restart our service whenever it's not running. We -do this by adding a line to /etc/inittab.

                3. +

              3. Install a script called restart-aolserver. This script doesn't +actually restart AOLserver - it just kills it.

              4. Ask the OS to restart our service whenever it's not running. +We do this by adding a line to /etc/inittab.

              Calling restart-aolserver kills our service. The OS notices that our service is not running, so it automatically restarts it. Thus, calling restart-aolserver effectively restarts our @@ -40,8 +40,8 @@

            • Test the restart-aolserver -script. We'll first kill all running servers to clean the slate. -Then, we'll start one server and use restart-aolserver to kill it. If it works, +script. We'll first kill all running servers to clean the +slate. Then, we'll start one server and use restart-aolserver to kill it. If it works, then there should be no more servers running. You should see the following lines.

               [joeuser ~]$ killall nsd
Index: openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html,v
diff -u -N -r1.13.2.1 -r1.13.2.2
--- openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html	9 Jun 2016 08:44:50 -0000	1.13.2.1
+++ openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html	23 Jun 2016 08:32:45 -0000	1.13.2.2
@@ -9,10 +9,10 @@
 		  
              1.  
 				Install a script called
 				restart-aolserver. This
-				script doesn't actually restart AOLserver - it just kills
+				script doesn't actually restart AOLserver - it just kills
 				it.  
 			  
              2. 
-				Ask the OS to restart our service whenever it's not
+				Ask the OS to restart our service whenever it's not
 				running. We do this by adding a line to
 				/etc/inittab.
 			  
              
@@ -43,8 +43,8 @@
 [root ~]# ln -s /usr/bin/perl /usr/local/bin/perl
 [root ~]# exit

            • Test the restart-aolserver - script. We'll first kill all running servers to clean the - slate. Then, we'll start one server and use + script. We'll first kill all running servers to clean the + slate. Then, we'll start one server and use restart-aolserver to kill it. If it works, then there should be no more servers running. You should see the following lines. 

              Index: openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.adp,v
diff -u -N -r1.1.2.10 -r1.1.2.11
--- openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.adp	21 Jun 2016 07:44:36 -0000	1.1.2.10
+++ openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.adp	23 Jun 2016 08:32:45 -0000	1.1.2.11
@@ -13,10 +13,10 @@
 instance.

          The simplest way to start and stop and OpenACS site is to run the startup shell script provided, /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run. This runs as a regular task, and logs to the logfile. To stop the -site, kill the script.

          A more stable way to run OpenACS is with a "keepalive" mechanism -of some sort, so that whenever the server halts or is stopped for a -reset, it restarts automatically. This is recommended for -development and production servers.

          The Reference Platform uses Daemontools to control AOLserver. A +site, kill the script.

          A more stable way to run OpenACS is with a "keepalive" +mechanism of some sort, so that whenever the server halts or is +stopped for a reset, it restarts automatically. This is recommended +for development and production servers.

          The Reference Platform uses Daemontools to control AOLserver. A simpler method, using init, is here.

          1. Daemontools must already be installed. If not, install it.

          2. @@ -109,7 +109,7 @@

          3. Verify that the controls work. You may want to tail -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log in another window, so you can see what happens when you type these -commands.

            Most of this information comes from Tom Jackson's AOLserver+Daemontools Mini-HOWTO.

            +commands.

            Most of this information comes from Tom Jackson's AOLserver+Daemontools Mini-HOWTO.

          Table 6.1. How it Index: openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html,v diff -u -N -r1.24.2.10 -r1.24.2.11 --- openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html 21 Jun 2016 07:44:36 -0000 1.24.2.10 +++ openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html 23 Jun 2016 08:32:45 -0000 1.24.2.11 @@ -62,7 +62,7 @@ [root root]#

        • Verify that the controls work. You may want to tail -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log in another window, so you can see what happens when you type these commands.

          - Most of this information comes from Tom Jackson's AOLserver+Daemontools + Most of this information comes from Tom Jackson's AOLserver+Daemontools Mini-HOWTO.

        Table 6.1. How it Works

        ProgramInvoked by this program ...... using this fileWhere to find errorsLog goes toUse these commands to control it
        svscanboot init/etc/inittabps -auxw | grep readproctitlen/a 
        aolserversupervise Index: openacs-4/packages/acs-core-docs/www/install-origins.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-origins.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/install-origins.adp 23 Sep 2015 11:54:37 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/install-origins.adp 23 Jun 2016 08:32:45 -0000 1.1.2.2 @@ -9,12 +9,13 @@ rightLink="os-install" rightLabel="Next">

        -Where did this document come from?

        This document was created by Vinod Kurup, but it's -really just plagiarism from a number of documents that came before -it. If I've used something that you've written without proper -credit, let me know and I'll fix it right away.

        Versions 4.6.2 to present were edited by Joel Aufrecht.

        These are a few of my sources:

        This document was created by Vinod Kurup, but +it's really just plagiarism from a number of documents that +came before it. If I've used something that you've written +without proper credit, let me know and I'll fix it right +away.

        Versions 4.6.2 to present were edited by Joel Aufrecht.

        These are a few of my sources:

        Please also see the Credits section for more acknowledgements.

        Index: openacs-4/packages/acs-core-docs/www/install-origins.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-origins.html,v diff -u -N -r1.16.2.1 -r1.16.2.2 --- openacs-4/packages/acs-core-docs/www/install-origins.html 9 Jun 2016 08:44:50 -0000 1.16.2.1 +++ openacs-4/packages/acs-core-docs/www/install-origins.html 23 Jun 2016 08:32:45 -0000 1.16.2.2 @@ -1,23 +1,23 @@ Where did this document come from?
        Alex logo
        Prev Appendix C. Credits Next

        Where did this document come from?

        - This document was created by Vinod Kurup, but it's really + This document was created by Vinod Kurup, but it's really just plagiarism from a number of documents that came before it. If - I've used something that you've written without proper credit, let me + I've used something that you've written without proper credit, let me know and I'll fix it right away.

        Versions 4.6.2 to present were edited by Joel Aufrecht.

        These are a few of my sources:

        Please also see the Credits section for more acknowledgements.

        Prev Home Next
        Appendix C. Credits Up Linux Install Guides
        docs@openacs.org
        View comments on this page at openacs.org
        Index: openacs-4/packages/acs-core-docs/www/install-overview.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-overview.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-core-docs/www/install-overview.adp 9 Jun 2016 13:03:11 -0000 1.1.2.2 +++ openacs-4/packages/acs-core-docs/www/install-overview.adp 23 Jun 2016 08:32:45 -0000 1.1.2.3 @@ -7,7 +7,7 @@

        @@ -25,7 +25,7 @@

        Index: openacs-4/packages/acs-core-docs/www/install-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-overview.html,v diff -u -N -r1.33.2.1 -r1.33.2.2 --- openacs-4/packages/acs-core-docs/www/install-overview.html 9 Jun 2016 08:44:50 -0000 1.33.2.1 +++ openacs-4/packages/acs-core-docs/www/install-overview.html 23 Jun 2016 08:32:45 -0000 1.33.2.2 @@ -1,5 +1,5 @@ -Chapter 2. Installation Overview
        Alex logo
        Prev Part II. Administrator's Guide Next

        Chapter 2. Installation Overview

        Table of Contents

        Basic Steps
        Prerequisite Software

        by Vinod Kurup

        +Chapter 2. Installation Overview
        Alex logo
        Prev Part II. Administrator's Guide Next

        Chapter 2. Installation Overview

        Table of Contents

        Basic Steps
        Prerequisite Software

        by Vinod Kurup

        OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
        Prev Home Next
        Part II. Administrator's Guide Up Basic Steps
        docs@openacs.org
        View comments on this page at openacs.org
        +
        Prev Home Next
        Part II. Administrator's Guide Up Basic Steps
        docs@openacs.org
        View comments on this page at openacs.org
        Index: openacs-4/packages/acs-core-docs/www/install-pam-radius.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-pam-radius.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-core-docs/www/install-pam-radius.adp 9 Jun 2016 13:03:11 -0000 1.1.2.2 +++ openacs-4/packages/acs-core-docs/www/install-pam-radius.adp 23 Jun 2016 08:32:45 -0000 1.1.2.3 @@ -26,8 +26,8 @@ end of the file.

        1. -Install ns_pam. Download and install -ns_pam

          +Install ns_pam. Download and
+install ns_pam
           [root aolserver]# cd /usr/local/src/aolserver/
           [root aolserver]# wget http://braindamage.alal.com/software/ns_pam-0.1.tar.gz
           [root aolserver]# tar xvfz ns_pam-0.1.tar.gz
@@ -43,8 +43,8 @@

        2. -Configure ns_pam. Configure AOLserver for -ns_pam

          To enable ns_pam in AOLServer you will first have to edit your +Configure ns_pam. Configure +AOLserver for ns_pam

          To enable ns_pam in AOLServer you will first have to edit your config.tcl file and enable the loading of the ns_pam module and configure the aolservers pam configuration file.

          • Change config.tcl. Remove @@ -63,8 +63,8 @@

        3. -Configure PAM Radius. Configure and install -PAM Radius

          You have to make sure that pam_radius v.1.3.16 or higher is +Configure PAM Radius. Configure and +install PAM Radius

          You have to make sure that pam_radius v.1.3.16 or higher is installed, otherwise you will have to install it.

           [root ns_pam]# cd /usr/local/src/
           [root src]# wget ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar
Index: openacs-4/packages/acs-core-docs/www/install-qmail.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-qmail.adp,v
diff -u -N -r1.1.2.10 -r1.1.2.11
--- openacs-4/packages/acs-core-docs/www/install-qmail.adp	21 Jun 2016 07:44:36 -0000	1.1.2.10
+++ openacs-4/packages/acs-core-docs/www/install-qmail.adp	23 Jun 2016 08:32:45 -0000	1.1.2.11
@@ -12,12 +12,12 @@
 
          
 Install qmail (OPTIONAL)
          Qmail is a Mail Transfer Agent. It handles incoming and outgoing
 mail. Install qmail if you want your OpenACS server to send and
-receive mail, and you don't want to use an alternate MTA.
          Red Hat 9: all djb tools (qmail, daemontools, ucspi) will fail
+receive mail, and you don't want to use an alternate MTA.
          Red Hat 9: all djb tools (qmail, daemontools, ucspi) will fail
 to compile in Red Hat 9 because of changes to glibc (patches)
            
 
          1. 
 
            
-Install ucspi. This program handles incoming
-tcp connections. Download ucspi and install it.
            +Install ucspi. This program handles
+incoming tcp connections. Download ucspi and install it.
             [root root]# cd /usr/local/src
 [root src]# wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz
 [root src]# tar xzf ucspi-tcp-0.88.tar.gzcd /usr/local/src 
@@ -48,20 +48,20 @@
 ] [ -b backlog ] [ -l localname ] [ -t timeout ] host port program
 [root ucspi-tcp-0.88]#
 
            
- (I'm not sure if this next step is 100%
-necessary, but when I skip it I get problems. If you get the error
-553 sorry, that domain isn't in my
-list of allowed rcpthosts (#5.7.1) then you need to do
+ (I'm not sure if this next step is
+100% necessary, but when I skip it I get problems. If you get the
+error 553 sorry, that domain isn't
+in my list of allowed rcpthosts (#5.7.1) then you need to do
 this.) AOLserver sends outgoing mail via the ns_sendmail command,
 which pipes a command to the sendmail executable. Or, in our case,
 the qmail replacement wrapper for the sendmail executable. In some
 cases, though, the outgoing mail requset is apparently sent through
 tcp/ip, so that it comes to qmail from 127.0.0.1 (a special IP
-address that means the local machine - the "loopback" interface).
-Unless this mail is addressed to the same machine, qmail thinks
-that it's an attempt to relay mail, and rejects it. So these two
-commands set up an exception so that any mail sent from 127.0.0.1
-is allowed to send outgoing mail.
            +address that means the local machine - the "loopback"
+interface). Unless this mail is addressed to the same machine,
+qmail thinks that it's an attempt to relay mail, and rejects
+it. So these two commands set up an exception so that any mail sent
+from 127.0.0.1 is allowed to send outgoing mail.
             [root ucspi-tcp-0.88]# cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp
 [root ucspi-tcp-0.88]# tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtpcp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp 
 tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp 
@@ -131,18 +131,18 @@
 ./collate.sh
 cd netqmail-1.04
 make setup check
-
            Replace sendmail with qmail's wrapper.
            +
            Replace sendmail with qmail's wrapper.
             [root qmail-1.03]# rm -f /usr/bin/sendmail /usr/sbin/sendmail
 [root qmail-1.03]# ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail
 [root qmail-1.03]#
 rm -f /usr/bin/sendmail /usr/sbin/sendmail
 ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail
 
            Configure qmail - specifically, run the config script to set up
 files in /var/qmail/control
-specifying the computer's identity and which addresses it should
-accept mail for. This command will automatically set up qmail
-correctly if you have correctly set a valid host nome. If not,
-you'll want to read /var/qmail/doc/INSTALL.ctl to find out how
+specifying the computer's identity and which addresses it
+should accept mail for. This command will automatically set up
+qmail correctly if you have correctly set a valid host nome. If
+not, you'll want to read /var/qmail/doc/INSTALL.ctl to find out how
 to configure qmail.
             [root qmail-1.03]# ./config-fast yourserver.test
 
@@ -157,10 +157,10 @@
 [root qmail-1.03]#
 ./config-fast yourserver.test
 
-
            All incoming mail that isn't for a specific user is handled by
-the alias user. This includes
-all root mail. These commands prepare the alias user to receive
-mail.
            +
            All incoming mail that isn't for a specific user is handled
+by the alias user. This
+includes all root mail. These commands prepare the alias user to
+receive mail.
             [root qmail-1.03]# cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root
 [root alias]# chmod 644 ~alias/.qmail*
 [root alias]# /var/qmail/bin/maildirmake ~alias/Maildir/
@@ -228,9 +228,9 @@
 ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service
 
 
            Wait ten seconds or so, and then verify that that the four qmail
-processes are running. If uptimes don't rise above 1 second, this
-may indicate broken scripts that are continuously restarting. In
-that case, start debugging by checking permissions.
            +processes are running. If uptimes don't rise above 1 second,
+this may indicate broken scripts that are continuously restarting.
+In that case, start debugging by checking permissions.
             [root root]# qmailctl stat
 /service/qmail-send: up (pid 32700) 430 seconds
 /service/qmail-send/log: up (pid 32701) 430 seconds
Index: openacs-4/packages/acs-core-docs/www/install-qmail.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-qmail.html,v
diff -u -N -r1.41.2.10 -r1.41.2.11
--- openacs-4/packages/acs-core-docs/www/install-qmail.html	21 Jun 2016 07:44:36 -0000	1.41.2.10
+++ openacs-4/packages/acs-core-docs/www/install-qmail.html	23 Jun 2016 08:32:45 -0000	1.41.2.11
@@ -1,7 +1,7 @@
 
 Install qmail (OPTIONAL)
            Alex logo
            Prev Appendix B. Install additional supporting software Next
            Install qmail (OPTIONAL)
            Qmail is a Mail Transfer Agent.  It handles incoming and
       outgoing mail.  Install qmail if you want your OpenACS server to
-      send and receive mail, and you don't want to use an alternate
+      send and receive mail, and you don't want to use an alternate
       MTA.
            Red Hat 9: all djb tools (qmail, daemontools, ucspi) will
       fail to compile in Red Hat 9 because of changes to glibc (patches)
            1. Install ucspi. This program handles incoming tcp connections.
             Download ucspi and install it.
              [root root]# cd /usr/local/src
@@ -32,14 +32,14 @@
 [root ucspi-tcp-0.88]#
 
              
 (I'm not sure if this next step is 100% necessary, but when I skip it
-I get problems.  If you get the error 553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1) then you need to do this.)  AOLserver sends outgoing mail via the ns_sendmail
+I get problems.  If you get the error 553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1) then you need to do this.)  AOLserver sends outgoing mail via the ns_sendmail
 command, which pipes a command to the sendmail executable.  Or, in our
 case, the qmail replacement wrapper for the sendmail executable.  In
 some cases, though, the outgoing mail requset is apparently sent
 through tcp/ip, so that it comes to qmail from 127.0.0.1 (a special IP
 address that means the local machine - the "loopback" interface).
 Unless this mail is addressed to the same machine, qmail thinks that
-it's an attempt to relay mail, and rejects it.  So these two commands
+it's an attempt to relay mail, and rejects it.  So these two commands
 set up an exception so that any mail sent from 127.0.0.1 is allowed to
 send outgoing mail.
              [root ucspi-tcp-0.88]# cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp
 [root ucspi-tcp-0.88]# tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp
@@ -103,11 +103,11 @@
 cd netqmail-1.04
 ./collate.sh
 cd netqmail-1.04
-make setup check
              Replace sendmail with qmail's wrapper.
              [root qmail-1.03]# rm -f /usr/bin/sendmail /usr/sbin/sendmail
+make setup check
              Replace sendmail with qmail's wrapper.
              [root qmail-1.03]# rm -f /usr/bin/sendmail /usr/sbin/sendmail
 [root qmail-1.03]# ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail
 [root qmail-1.03]#
 rm -f /usr/bin/sendmail /usr/sbin/sendmail
-ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail
              Configure qmail - specifically, run the config script to set up files in /var/qmail/control specifying the computer's identity and which addresses it should accept mail for.  This command will automatically set up qmail correctly if you have correctly set a valid host nome.  If not, you'll want to read /var/qmail/doc/INSTALL.ctl to find out how to configure qmail.
              [root qmail-1.03]# ./config-fast yourserver.test
+ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail
              Configure qmail - specifically, run the config script to set up files in /var/qmail/control specifying the computer's identity and which addresses it should accept mail for.  This command will automatically set up qmail correctly if you have correctly set a valid host nome.  If not, you'll want to read /var/qmail/doc/INSTALL.ctl to find out how to configure qmail.
              [root qmail-1.03]# ./config-fast yourserver.test
 Your fully qualified host name is yourserver.test.
 Putting yourserver.test into control/me...
 Putting yourserver.test into control/defaultdomain...
@@ -117,7 +117,7 @@
 Now qmail will refuse to accept SMTP messages except to yourserver.test.
 Make sure to change rcpthosts if you add hosts to locals or virtualdomains!
 [root qmail-1.03]#
-./config-fast yourserver.test
              All incoming mail that isn't for a specific user is handled by the alias user.  This includes all root mail.  These commands prepare the alias user to receive mail.
              [root qmail-1.03]# cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root
+./config-fast yourserver.test
              All incoming mail that isn't for a specific user is handled by the alias user.  This includes all root mail.  These commands prepare the alias user to receive mail.
              [root qmail-1.03]# cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root
 [root alias]# chmod 644 ~alias/.qmail*
 [root alias]# /var/qmail/bin/maildirmake ~alias/Maildir/
 [root alias]# chown -R alias.nofiles /var/qmail/alias/Maildir
@@ -172,7 +172,7 @@
 chmod 755 /var/qmail/supervise/qmail-smtpd/run
 chmod 755 /var/qmail/supervise/qmail-smtpd/log/run
 ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service
-
              Wait ten seconds or so, and then verify that that the four qmail processes are running.  If uptimes don't rise above 1 second, this may indicate broken scripts that are continuously restarting.  In that case, start debugging by checking permissions.
              [root root]# qmailctl stat
+
              Wait ten seconds or so, and then verify that that the four qmail processes are running.  If uptimes don't rise above 1 second, this may indicate broken scripts that are continuously restarting.  In that case, start debugging by checking permissions.
              [root root]# qmailctl stat
 /service/qmail-send: up (pid 32700) 430 seconds
 /service/qmail-send/log: up (pid 32701) 430 seconds
 /service/qmail-smtpd: up (pid 32704) 430 seconds
Index: openacs-4/packages/acs-core-docs/www/install-redhat.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-redhat.adp,v
diff -u -N -r1.1.2.10 -r1.1.2.11
--- openacs-4/packages/acs-core-docs/www/install-redhat.adp	21 Jun 2016 07:44:36 -0000	1.1.2.10
+++ openacs-4/packages/acs-core-docs/www/install-redhat.adp	23 Jun 2016 08:32:45 -0000	1.1.2.11
@@ -7,7 +7,7 @@
 
 		
              
 
              
@@ -20,9 +20,9 @@
 software. You should do this section as-is if you have a machine
 you can reformat and you want to be sure that your installation
 works and is secure; it should take about an hour. (In my
-experience, it's almost always a net time savings of several hours
-to install a new machine from scratch compared to installing each
-of these packages installed independently.)
              The installation guide assumes you have:
                
+experience, it's almost always a net time savings of several
+hours to install a new machine from scratch compared to installing
+each of these packages installed independently.)
                The installation guide assumes you have:
                  
 
                • A PC with hard drive you can reinstall
                • Red Hat 8.0 or 9.0 install discs
                • A CD with the current Security
 Patches for your version of Red Hat.
                  • 
 
                The installation guide assumes that you can do the following on
@@ -36,15 +36,16 @@
 correct the problem. Some useful UNIX resources.
                  
 
                1. 
 Unplug
-the network cable from your computer. We don't want to connect to
-the network until we're sure the computer is secure. 
-(Wherever you see the word secure, you should always read it as,
-"secure enough for our purposes, given the amount of work we're
-willing to exert and the estimated risk and consequences.")
                2. Insert Red Hat 8.0 or 9.0 Disk 1 into the CD-ROM and reboot the
+the network cable from your computer. We don't want to connect
+to the network until we're sure the computer is secure.
+ (Wherever you see the word secure, you
+should always read it as, "secure enough for our purposes,
+given the amount of work we're willing to exert and the
+estimated risk and consequences.")
                3. Insert Red Hat 8.0 or 9.0 Disk 1 into the CD-ROM and reboot the
 computer
                4. At the boot:
 prompt, press Enter for a graphical install. The text install is
 fairly different, so if you need to do that instead proceed with
-caution, because the guide won't match the steps.
                5. Checking the media is probably a waste of time, so when it asks
+caution, because the guide won't match the steps.
                6. Checking the media is probably a waste of time, so when it asks
 press Tab and then Enter to skip it.
                7. After the graphical introduction page loads, click 
 Next
 
                8. Choose the language you want to use and then click 
@@ -53,72 +54,72 @@
 Next
 
                9. Choose your mouse type and Click 
 Next
-
                10. Red Hat has several templates for new computers. We'll start
-with the "Server" template and then fine-tune it during the rest of
-the install. Choose Server and
-click 
+
                11. Red Hat has several templates for new computers. We'll start
+with the "Server" template and then fine-tune it during
+the rest of the install. Choose Server and click 
 Next.
                12. 
-
                  Reformat the hard drive. If you know what you're doing, do this
-step on your own. Otherwise: we're going to let the installer wipe
-out the everything on the main hard drive and then arrange things
-to its liking.
                    
+
                    Reformat the hard drive. If you know what you're doing, do
+this step on your own. Otherwise: we're going to let the
+installer wipe out the everything on the main hard drive and then
+arrange things to its liking.
                      
 
                    1. Choose Automatically
 Partition and click 
 Next
 
                    2. Uncheck Review (and modify if needed) the partitions
 created and click 
 Next
-
                    3. On the pop-up window asking "Are you sure you want to do this?"
-click 
+
                    4. On the pop-up window asking "Are you sure you want to do
+this?" click 
 Yes IF YOU ARE WIPING YOUR
 HARD DRIVE.
                    5. Click 
 Next on the boot loader
 screen
                      6. 
 
                    
 
                  1. 
 
                    Configure Networking.  Again, if you
-know what you're doing, do this step yourself, being sure to note
-the firewall holes. Otherwise, follow the instructions in this step
-to set up a computer directly connected to the internet with a
+know what you're doing, do this step yourself, being sure to
+note the firewall holes. Otherwise, follow the instructions in this
+step to set up a computer directly connected to the internet with a
 dedicated IP address.
                      
 
                    1. DHCP is a system by which a computer that joins a network (such
 as on boot) can request a temporary IP address and other network
 information. Assuming the machine has a dedicated IP address (if it
-doesn't, it will be tricky to access the OpenACS service from the
-outside world), we're going to set up that address. If you don't
-know your netmask, 255.255.255.0 is usually a pretty safe guess.
-Click Edit,
+doesn't, it will be tricky to access the OpenACS service from
+the outside world), we're going to set up that address. If you
+don't know your netmask, 255.255.255.0 is usually a pretty safe
+guess. Click Edit,
 uncheck Configure using DHCP and type in your IP
 and netmask. Click 
 Ok.
                    2. Type in your host name, gateway, and DNS server(s). Then click
 
-Next.
                    3. We're going to use the firewall template for high security,
-meaning that we'll block almost all incoming traffic. Then we'll
-add a few holes to the firewall for services which we need and know
-are secure. Choose High security level. Check
+Next.
                    4. We're going to use the firewall template for high security,
+meaning that we'll block almost all incoming traffic. Then
+we'll add a few holes to the firewall for services which we
+need and know are secure. Choose High security level. Check
 WWW, SSH, and Mail
 (SMTP). In the Other ports box, enter
 443, 8000, 8443.
 Click 
 Next. Port 443 is for https
 (http over ssl), and 8000 and 8443 are http and https access to the
-development server we'll be setting up.
                      5. 
+development server we'll be setting up.
                      
 
                    
 
                  2. 
 Select any additional languages you want
 the computer to support and then click 
 Next
 
                  3. Choose your time zone and click 
 Next.
                  4. Type in a root password, twice.
                  5. 
-
                    On the Package selection page, we're going to uncheck a lot of
-packages that install software we don't need, and add packages that
-have stuff we do need. You should install everything we're
-installing here or the guide may not work for you; you can install
-extra stuff, or ignore the instructions here to not install stuff,
-with relative impunity - at worst, you'll introduce a security risk
-that's still screened by the firewall, or a resource hog. Just
-don't install a database or web server, because that would conflict
-with the database and web server we'll install later.
                    
+
                    On the Package selection page, we're going to uncheck a lot
+of packages that install software we don't need, and add
+packages that have stuff we do need. You should install everything
+we're installing here or the guide may not work for you; you
+can install extra stuff, or ignore the instructions here to not
+install stuff, with relative impunity - at worst, you'll
+introduce a security risk that's still screened by the
+firewall, or a resource hog. Just don't install a database or
+web server, because that would conflict with the database and web
+server we'll install later.
                    
 
                    check Editors
 (this installs emacs),
                    click Details next
 to Text-based Internet, check
@@ -142,8 +143,8 @@
 
                  6. 
 
                    We need to fine-tune the exact list of packages. The same rules
 apply as in the last step - you can add more stuff, but you
-shouldn't remove anything the guide adds. We're going to go through
-all the packages in one big list, so select 
+shouldn't remove anything the guide adds. We're going to go
+through all the packages in one big list, so select 
 Flat
 View and wait. In a minute, a list of packages
 will appear.
                    
@@ -153,28 +154,29 @@
 (unless you are using isdn, this installs a useless daemon),
                    check mutt (a mail
 program that reads Maildir),
                    uncheck nfs-utils
 (nfs is a major security risk),
                    uncheck pam-devel (I
-don't remember why, but we don't want this),
                    uncheck portmap,
                    uncheck postfix
-(this is an MTA, but we're going to install qmail later),
                    check postgresql-devel,
                    uncheck rsh (rsh is
+don't remember why, but we don't want this),
                    uncheck portmap,
                    uncheck postfix
+(this is an MTA, but we're going to install qmail later),
                    check postgresql-devel,
                    uncheck rsh (rsh is
 a security hole),
                    uncheck sendmail
-(sendmail is an insecure MTA; we're going to install qmail instead
-later),
                    check tcl (we need
+(sendmail is an insecure MTA; we're going to install qmail
+instead later),
                    check tcl (we need
 tcl), and
                    uncheck xinetd
-(xinetd handles incoming tcp connections. We'll install a
+(xinetd handles incoming tcp connections. We'll install a
 different, more secure program, ucspi-tcp).
                    Click 
 Next
 
                    
 
                    
-
                  7. Red Hat isn't completely happy with the combination of packages
-we've selected, and wants to satisfy some dependencies. Don't let
-it. On the next screen, choose Ignore Package
+
                  8. Red Hat isn't completely happy with the combination of
+packages we've selected, and wants to satisfy some
+dependencies. Don't let it. On the next screen, choose
+Ignore Package
 Dependencies and click 
 Next.
                  9. Click 
 Next to start the copying
 of files.
                  10. Wait. Insert Disk 2 when asked.
                  11. Wait. Insert Disk 3 when asked.
                  12. If you know how to use it, create a boot disk. Since you can
 also boot into recovery mode with the Install CDs, this is less
-useful than it used to be, and we won't bother. Select No,I
-do not want to create a boot
-disk and click 
+useful than it used to be, and we won't bother. Select
+No,I do not want to
+create a boot disk and click 
 Next.
                  13. Click 
 Exit, remove the CD, and
 watch the computer reboot.
                  14. 
@@ -201,7 +203,7 @@
 security precaution, we are now going to tell ssh not to allow
 anyone to connect directly to this computer as root. Type this into
 the shell:
                    emacs /etc/ssh/sshd_config
                    
-
                  15. Search for the word "root" by typing C-s (that's emacs-speak for
+
                  16. Search for the word "root" by typing C-s (that's emacs-speak for
 control-s) and then root.
                  17. 
 
                    Make the following changes:
                    
 
                    
@@ -212,8 +214,8 @@
 PermitRootLogin no (this
 prevents the root user from logging in remotely via ssh. If you do
 this, be sure to create a remote access account, such as
-"remadmin", which you can use to get ssh before using "su" to
-become root)
                    
+"remadmin", which you can use to get ssh before using
+"su" to become root)
                    
 #PermitEmptyPasswords no to
 PermitEmptyPasswords no (this
 blocks passwordless accounts) and save and exit by typing
@@ -226,18 +228,18 @@
 
 
 
                  18. 
-
                    Red Hat still installed a few services we don't need, and which
-can be security holes. Use the service command to turn them off,
-and then use chkconfig to automatically edit the System V init
+
                    Red Hat still installed a few services we don't need, and
+which can be security holes. Use the service command to turn them
+off, and then use chkconfig to automatically edit the System V init
 directories to permanently (The System V init directories are the
 ones in /etc/rc.d. They consist of a bunch of scripts for starting
 and stopping programs, and directories of symlinks for each system
 level indicating which services should be up and down at any given
-service level. We'll use this system for PostgreSQL, but we'll use
-daemontools to perform a similar function for AOLserver. (The
-reason for this discrepencies is that, while daemontools is better,
-it's a pain in the ass to deal with and nobody's had any trouble
-leaving PostgreSQL the way it is.)
                    +service level. We'll use this system for PostgreSQL, but
+we'll use daemontools to perform a similar function for
+AOLserver. (The reason for this discrepencies is that, while
+daemontools is better, it's a pain in the ass to deal with and
+nobody's had any trouble leaving PostgreSQL the way it is.)
                     [root root]# service pcmcia stop
 [root root]# service netfs stop
 [root root]# chkconfig --del pcmcia
@@ -250,11 +252,11 @@
 
                    If you installed PostgreSQL, do also service postgresql start and chkconfig --add postgresql.
                    
 
                  19. Plug in the network cable.
                  20. 
 
                    Verify that you have connectivity by going to another computer
-and ssh'ing to yourserver, logging in as remadmin, and
+and ssh'ing to yourserver, logging in as remadmin, and
 promoting yourself to root:
                     [joeuser\@someotherserver]$  ssh remadmin\@yourserver.test
 
-The authenticity of host 'yourserver.test (1.2.3.4)' can't be established.
+The authenticity of host 'yourserver.test (1.2.3.4)' can't be established.
 DSA key fingerprint is 10:b9:b6:10:79:46:14:c8:2d:65:ae:c1:61:4b:a5:a5.
 Are you sure you want to continue connecting (yes/no)? yes
 Warning: Permanently added 'yourserver.test (1.2.3.4)' (DSA) to the list of known hosts.
@@ -265,9 +267,10 @@
 [root root]#
 
                    
 
                  21. 
-
                    If you didn't burn a CD of patches and use it, can still
-download and install the necessary patches. Here's how to do it for
-the kernel; you should also check for other critical packages.
                    Upgrade the kernel to fix a security hole. The default Red Hat
+
                    If you didn't burn a CD of patches and use it, can still
+download and install the necessary patches. Here's how to do it
+for the kernel; you should also check for other critical
+packages.
                    Upgrade the kernel to fix a security hole. The default Red Hat
 8.0 system kernel (2.4.18-14, which you can check with
 uname -a) has
 several security problems. Download the new kernel, install it,
Index: openacs-4/packages/acs-core-docs/www/install-redhat.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-redhat.html,v
diff -u -N -r1.41.2.10 -r1.41.2.11
--- openacs-4/packages/acs-core-docs/www/install-redhat.html	21 Jun 2016 07:44:36 -0000	1.41.2.10
+++ openacs-4/packages/acs-core-docs/www/install-redhat.html	23 Jun 2016 08:32:45 -0000	1.41.2.11
@@ -1,12 +1,12 @@
 
-Appendix A. Install Red Hat 8/9
                    Alex logo
                    Prev Part II. Administrator's Guide Next
                    Appendix A. Install Red Hat 8/9
                    by Joel Aufrecht
                    
+Appendix A. Install Red Hat 8/9
                    Alex logo
                    Prev Part II. Administrator's Guide Next
                    Appendix A. Install Red Hat 8/9
                    by Joel Aufrecht
                    
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
                    This section takes a blank PC and sets up some supporting
     software.  You should do this section as-is if you have a machine
     you can reformat and you want to be sure that your installation
     works and is secure; it should take about an hour.  (In my
-    experience, it's almost always a net time savings of several hours
+    experience, it's almost always a net time savings of several hours
     to install a new machine from scratch compared to installing each
     of these packages installed independently.)
                    The installation guide assumes you have:
                    • A PC with hard drive you can reinstall
                    • Red Hat 8.0 or 9.0 install discs
                    • A CD with the current Security
       Patches for your version of Red Hat.
                    The installation guide assumes that you can do the following on
@@ -25,78 +25,78 @@
 	  but if anything goes wrong it may take extra time to
 	  understand and correct the problem.  Some useful UNIX resources.
 	
                    1. Unplug the network cable from your
-          computer.  We don't want to connect to the network
-          until we're sure the computer is secure.  
+          computer.  We don't want to connect to the network
+          until we're sure the computer is secure.  
            
   (Wherever you see
           the word secure, you should always read it as, "secure
-          enough for our purposes, given the amount of work we're
+          enough for our purposes, given the amount of work we're
           willing to exert and the estimated risk and
           consequences.")
                    2. Insert Red Hat 8.0 or 9.0 Disk 1 into the  
 	  CD-ROM and reboot the computer
                    3. At the
           boot:
           prompt, press Enter for a
           graphical install.  The text install is fairly different, so
           if you need to do that instead proceed with caution, because
-          the guide won't match the steps.
                    4. Checking the media is probably a waste of
+          the guide won't match the steps.
                    5. Checking the media is probably a waste of
           time, so when it asks press Tab and
           then Enter to skip it.
                    6. After the graphical introduction page loads, click Next
                    7. Choose the language you want to use and then click
 Next
 
                    8. Select the keyboard layout you will use and Click Next
                    9. Choose your mouse type and Click Next
                    10. Red Hat has several templates for new
-          computers.  We'll start with the "Server" template and then
+          computers.  We'll start with the "Server" template and then
           fine-tune it during the rest of the install.  Choose
 	Server
 	and click
-	Next.
                    11. Reformat the hard drive.  If you know what you're doing,
-	do this step on your own.  Otherwise:  we're going to let the
+	Next.
                    12. Reformat the hard drive.  If you know what you're doing,
+	do this step on your own.  Otherwise:  we're going to let the
 	installer wipe out the everything on the main hard drive and then arrange things to
 	its liking.
                      1. Choose Automatically Partition
 	  and click Next
                      2. Uncheck
 Review (and modify if needed) the partitions created and click Next
                      3. On the pop-up window asking "Are you sure
 	  you want to do this?" click
 	  Yes
 	  IF YOU ARE WIPING YOUR HARD DRIVE.
                      4. Click Next on the boot loader screen
                    13. Configure Networking.  
-Again, if you know what you're doing, do this step
+Again, if you know what you're doing, do this step
           yourself, being sure to note the firewall holes. Otherwise,
           follow the instructions in this step to set up a computer directly connected to the internet with a dedicated IP address.
                      1. DHCP is a system by which a computer that
 joins a network (such as on boot) can request a temporary IP address
 and other network information.  Assuming the machine has a dedicated
-IP address (if it doesn't, it will be tricky to access the OpenACS
-service from the outside world), we're going to set up that address.
-If you don't know your netmask, 255.255.255.0 is usually a pretty safe
+IP address (if it doesn't, it will be tricky to access the OpenACS
+service from the outside world), we're going to set up that address.
+If you don't know your netmask, 255.255.255.0 is usually a pretty safe
 guess.  Click Edit, uncheck Configure using DHCP
 and type in your IP and netmask.  Click Ok.
                      2.  Type in your host
-name, gateway, and DNS server(s).  Then click Next.
                      3. We're going to use the firewall template for high
-security, meaning that we'll block almost all incoming traffic.  Then
-we'll add a few holes to the firewall for services which we need and
+name, gateway, and DNS server(s).  Then click Next.
                      4. We're going to use the firewall template for high
+security, meaning that we'll block almost all incoming traffic.  Then
+we'll add a few holes to the firewall for services which we need and
 know are secure.  Choose High
 security level. Check
 WWW,
 SSH, and
 Mail (SMTP).  In the Other ports
 box, enter 443, 8000, 8443.  Click
 Next.
-Port 443 is for https (http over ssl), and 8000 and 8443 are http and https access to the development server we'll be setting up.
                    14. Select any additional languages you want the
+Port 443 is for https (http over ssl), and 8000 and 8443 are http and https access to the development server we'll be setting up.
                  22. Select any additional languages you want the
 	  computer to support and then click
 	  Next
                  23. Choose your time zone and click Next.
                  24. Type in a root
-password, twice.
                  25. On the Package selection page, we're going to
-uncheck a lot of packages that install software we don't need, and add
+password, twice.
                  26. On the Package selection page, we're going to
+uncheck a lot of packages that install software we don't need, and add
 packages that have stuff we do need.  You should install everything
-we're installing here or the guide may not work for you; you can
+we're installing here or the guide may not work for you; you can
 install extra stuff, or ignore the instructions here to not install
-stuff, with relative impunity - at worst, you'll introduce a security
-risk that's still screened by the firewall, or a resource hog.  Just
-don't install a database or web server, because that would conflict
-with the database and web server we'll install later.
+stuff, with relative impunity - at worst, you'll introduce a security
+risk that's still screened by the firewall, or a resource hog.  Just
+don't install a database or web server, because that would conflict
+with the database and web server we'll install later.
 
                    check Editors (this installs emacs),
                    click Details next to Text-based Internet, check lynx, and click OK;
                    check Authoring and Publishing (this installs docbook),
                    uncheck Server Configuration Tools,
                    uncheck Web Server,
                    uncheck Windows File Server,
                    check SQL Database Server (this installs PostgreSQL),
                    check Development Tools (this installs gmake and other build tools),
                    uncheck Administration Tools, and
                    uncheck Printing Support.
                    At the bottom, check Select Individual Packages and click Next
                  27. We need to fine-tune the exact list of packages.
 The same rules apply as in the last step - you can add more stuff, but
-you shouldn't remove anything the guide adds.  We're going to go
+you shouldn't remove anything the guide adds.  We're going to go
 through all the packages in one big list, so select
 Flat
 View and wait. In a minute, a
-list of packages will appear.
                    uncheck apmd (monitors power, not very useful for servers), 
                    check ImageMagick (required for the photo-album packages, 
                    uncheckisdn4k-utils (unless you are using isdn, this installs a useless daemon), 
                    check mutt (a mail program that reads Maildir),
                    uncheck nfs-utils (nfs is a major security risk), 
                    uncheck pam-devel (I don't remember why, but we don't want this), 
                    uncheck portmap, 
                    uncheck postfix (this is an MTA, but we're going to install qmail later), 
                    check  postgresql-devel,
                    uncheck rsh (rsh is a security hole), 
                    uncheck sendmail (sendmail is an insecure MTA; we're going to install qmail instead later),
                    check tcl (we need tcl), and 
                    uncheck xinetd (xinetd handles incoming tcp connections.  We'll install a different, more secure program, ucspi-tcp).
                    Click Next
                  28. Red Hat isn't completely happy with the combination
-of packages we've selected, and wants to satisfy some dependencies.
-Don't let it.  On the next screen, choose
+list of packages will appear.
                    uncheck apmd (monitors power, not very useful for servers), 
                    check ImageMagick (required for the photo-album packages, 
                    uncheckisdn4k-utils (unless you are using isdn, this installs a useless daemon), 
                    check mutt (a mail program that reads Maildir),
                    uncheck nfs-utils (nfs is a major security risk), 
                    uncheck pam-devel (I don't remember why, but we don't want this), 
                    uncheck portmap, 
                    uncheck postfix (this is an MTA, but we're going to install qmail later), 
                    check  postgresql-devel,
                    uncheck rsh (rsh is a security hole), 
                    uncheck sendmail (sendmail is an insecure MTA; we're going to install qmail instead later),
                    check tcl (we need tcl), and 
                    uncheck xinetd (xinetd handles incoming tcp connections.  We'll install a different, more secure program, ucspi-tcp).
                    Click Next
                  29. Red Hat isn't completely happy with the combination
+of packages we've selected, and wants to satisfy some dependencies.
+Don't let it.  On the next screen, choose
 Ignore Package
 Dependencies and click
 Next.
@@ -106,7 +106,7 @@
 asked.
                  30. Wait. Insert Disk 3 when asked.
                  31. If you know how to use it, create a boot
         disk.  Since you can also boot into recovery mode with the
         Install CDs, this is less useful than it used to be, and we
-        won't bother.  Select No,I do not want to create a boot disk and click Next.
                  32. Click Exit, remove the CD, and watch the
+        won't bother.  Select No,I do not want to create a boot disk and click Next.
                  33. Click Exit, remove the CD, and watch the
 computer reboot.
 
                  34. After it finishes rebooting and shows the login
 	  prompt, log in:
                    yourserver login: root
@@ -127,7 +127,7 @@
               ssh connections.  As a security precaution, we are now going
               to tell ssh not to allow anyone to connect directly to this
               computer as root.  Type this into the shell:
-            
                    emacs /etc/ssh/sshd_config
                  35. Search for the word "root" by typing C-s (that's emacs-speak for control-s) and then root.
                  36. Make the following changes:
                    #Protocol 2,1 to
+            
                    emacs /etc/ssh/sshd_config
                  37. Search for the word "root" by typing C-s (that's emacs-speak for control-s) and then root.
                  38. Make the following changes:
                    #Protocol 2,1 to
                 Protocol 2 
                 (this prevents any connections via SSH 1, which is insecure)
                    #PermitRootLogin yes to
                 PermitRootLogin no 
@@ -136,18 +136,18 @@
                 account, such as "remadmin", which you can use to get ssh
                 before using "su" to become root)
                    #PermitEmptyPasswords no to PermitEmptyPasswords no
                 (this blocks passwordless accounts) and save and exit by typing C-x C-s C-x C-c
                  39. Restart sshd so that the change takes effect.
                    service sshd restart
                  40. 
-         Red Hat still installed a few services we don't need, and
+         Red Hat still installed a few services we don't need, and
          which can be security holes.  Use the service command to turn
          them off, and then use chkconfig to automatically edit the
          System V init directories to permanently (The System V init
          directories are the ones in /etc/rc.d.  They consist of a
          bunch of scripts for starting and stopping programs, and
          directories of symlinks for each system level indicating
          which services should be up and down at any given service
-         level.  We'll use this system for PostgreSQL, but we'll use
+         level.  We'll use this system for PostgreSQL, but we'll use
          daemontools to perform a similar function for AOLserver.
          (The reason for this discrepencies is that, while daemontools
-         is better, it's a pain in the ass to deal with and nobody's
+         is better, it's a pain in the ass to deal with and nobody's
          had any trouble leaving PostgreSQL the way it is.)
        
                    [root root]# service pcmcia stop
 [root root]# service netfs stop
@@ -159,19 +159,19 @@
 chkconfig --del pcmcia
 chkconfig --del netfs
                    If you installed PostgreSQL, do also
 service postgresql start and chkconfig --add postgresql.
                  41. Plug in the network cable.
                  42. Verify that you have connectivity by going to another
-          computer and ssh'ing to
+          computer and ssh'ing to
           yourserver, logging in as
           remadmin, and promoting yourself to root:
                    [joeuser@someotherserver]$  ssh remadmin@yourserver.test
-The authenticity of host 'yourserver.test (1.2.3.4)' can't be established.
+The authenticity of host 'yourserver.test (1.2.3.4)' can't be established.
 DSA key fingerprint is 10:b9:b6:10:79:46:14:c8:2d:65:ae:c1:61:4b:a5:a5.
 Are you sure you want to continue connecting (yes/no)? yes
 Warning: Permanently added 'yourserver.test (1.2.3.4)' (DSA) to the list of known hosts.
 Password:
 Last login: Mon Mar  3 21:15:27 2003 from host-12-01.dsl-sea.seanet.com
 [remadmin remadmin]$ su -
 Password: 
-[root root]#
                  43. If you didn't burn a CD of patches and use it, can still
-          download and install the necessary patches.  Here's how to
+[root root]#
                  44. If you didn't burn a CD of patches and use it, can still
+          download and install the necessary patches.  Here's how to
           do it for the kernel; you should also check for other
           critical packages.
                    Upgrade the kernel to fix a security hole.  The default
           Red Hat 8.0 system kernel (2.4.18-14, which you can check
Index: openacs-4/packages/acs-core-docs/www/install-resources.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-resources.adp,v
diff -u -N -r1.1.2.1 -r1.1.2.2
--- openacs-4/packages/acs-core-docs/www/install-resources.adp	23 Sep 2015 11:54:38 -0000	1.1.2.1
+++ openacs-4/packages/acs-core-docs/www/install-resources.adp	23 Jun 2016 08:32:45 -0000	1.1.2.2
@@ -14,14 +14,14 @@
 
                    
 Books
                    
 
                    
 Web Sites
                      
Index: openacs-4/packages/acs-core-docs/www/install-resources.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-resources.html,v
diff -u -N -r1.16.2.1 -r1.16.2.2
--- openacs-4/packages/acs-core-docs/www/install-resources.html	9 Jun 2016 08:44:50 -0000	1.16.2.1
+++ openacs-4/packages/acs-core-docs/www/install-resources.html	23 Jun 2016 08:32:45 -0000	1.16.2.2
@@ -4,7 +4,7 @@
     
                      Books
                      • 
 
             Philip
-            and Alex's Guide to Web Publishing - A very readable
+            and Alex's Guide to Web Publishing - A very readable
             guide to database-backed community websites.
 
           
                      • 
@@ -22,7 +22,7 @@
           
                      •  
 
             UNIX
-            System Administrator's Bible -  (LePage and Iarerra 1998;
+            System Administrator's Bible -  (LePage and Iarerra 1998;
             IDG) 
 
           
                      •  
Index: openacs-4/packages/acs-core-docs/www/install-ssl.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-ssl.adp,v
diff -u -N -r1.1.2.1 -r1.1.2.2
--- openacs-4/packages/acs-core-docs/www/install-ssl.adp	23 Sep 2015 11:54:39 -0000	1.1.2.1
+++ openacs-4/packages/acs-core-docs/www/install-ssl.adp	23 Jun 2016 08:32:45 -0000	1.1.2.2
@@ -38,8 +38,8 @@
 approved CA will work smoothly. Any other certificate will cause
 browsers to produce some messages or block the site. Unfortunately,
 getting a site certificate signed by a CA costs money. In this
-section, we'll generate an unsigned certificate which will work in
-most browsers, albeit with pop-up messages.
                        Use an OpenSSL perl script to generate a certificate and
+section, we'll generate an unsigned certificate which will work
+in most browsers, albeit with pop-up messages.
                        Use an OpenSSL perl script to generate a certificate and
 key.
                        Debian users: use /usr/lib/ssl/misc/CA.pl instead of
 /usr/share/ssl/CA
                        Mac OS X users: use perl /System/Library/OpenSSL/misc/CA.pl
 -newcert instead of /usr/share/ssl/CA
                        @@ -58,13 +58,12 @@
 
                        
 newreq.pem contains our
 certificate and private key. The key is protected by a passphrase,
-which means that we'll have to enter the pass phrase each time the
-server starts. This is impractical and unnecessary, so we create an
-unprotected version of the key. Security
-implication: if anyone gets access to the file
-keyfile.pem, they effectively own the key as much as you do.
-Mitigation: don't use this key/cert combo for anything besides
-providing ssl for the web site.
                        +which means that we'll have to enter the pass phrase each time
+the server starts. This is impractical and unnecessary, so we
+create an unprotected version of the key. Security implication: if anyone gets
+access to the file keyfile.pem, they effectively own the key as
+much as you do. Mitigation: don't use this key/cert combo for
+anything besides providing ssl for the web site.
                         [root misc]# openssl rsa -in newreq.pem -out keyfile.pem
 read RSA key
 Enter PEM pass phrase:
Index: openacs-4/packages/acs-core-docs/www/install-ssl.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-ssl.html,v
diff -u -N -r1.15.2.1 -r1.15.2.2
--- openacs-4/packages/acs-core-docs/www/install-ssl.html	9 Jun 2016 08:44:50 -0000	1.15.2.1
+++ openacs-4/packages/acs-core-docs/www/install-ssl.html	23 Jun 2016 08:32:45 -0000	1.15.2.2
@@ -4,7 +4,7 @@
 [$OPENACS_SERVICE_NAME etc]$ chmod 700 /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs
 [$OPENACS_SERVICE_NAME etc]$ 
 mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs
-chmod 700 /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs
                      • It takes two files to support an SSL connection.  The certificate is the public half of the key pair - the server sends the certificate to browser requesting ssl.  The key is the private half of the key pair.  In addition, the certificate must be signed by Certificate Authority or browsers will protest.  Each web browser ships with a built-in list of acceptable Certificate Authorities (CAs) and their keys.  Only a site certificate signed by a known and approved CA will work smoothly.  Any other certificate will cause browsers to produce some messages or block the site.  Unfortunately, getting a site certificate signed by a CA costs money.  In this section, we'll generate an unsigned certificate which will work in most browsers, albeit with pop-up messages.
                        Use an OpenSSL perl script to generate a certificate and key.
                        
+chmod 700 /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs
                      • It takes two files to support an SSL connection.  The certificate is the public half of the key pair - the server sends the certificate to browser requesting ssl.  The key is the private half of the key pair.  In addition, the certificate must be signed by Certificate Authority or browsers will protest.  Each web browser ships with a built-in list of acceptable Certificate Authorities (CAs) and their keys.  Only a site certificate signed by a known and approved CA will work smoothly.  Any other certificate will cause browsers to produce some messages or block the site.  Unfortunately, getting a site certificate signed by a CA costs money.  In this section, we'll generate an unsigned certificate which will work in most browsers, albeit with pop-up messages.
                        Use an OpenSSL perl script to generate a certificate and key.
                        
           Debian users: use /usr/lib/ssl/misc/CA.pl instead of /usr/share/ssl/CA
         
                        
           Mac OS X users: use perl /System/Library/OpenSSL/misc/CA.pl -newcert instead of /usr/share/ssl/CA
@@ -16,7 +16,7 @@
 .......++++++
 writing new private key to 'newreq.pem'
 Enter PEM pass phrase:
                        Enter a pass phrase for the CA certificate.  Then, answer the rest of the questions.  At the end you should see this:
                        Certificate (and private key) is in newreq.pem
-[$OPENACS_SERVICE_NAME certs]$
                        newreq.pem contains our certificate and private key.  The key is protected by a passphrase, which means that we'll have to enter the pass phrase each time the server starts.  This is impractical and unnecessary, so we create an unprotected version of the key.  Security implication: if anyone gets access to the file keyfile.pem, they effectively own the key as much as you do.  Mitigation: don't use this key/cert combo for anything besides providing ssl for the web site.
                        [root misc]# openssl rsa -in newreq.pem -out keyfile.pem
+[$OPENACS_SERVICE_NAME certs]$
                        newreq.pem contains our certificate and private key.  The key is protected by a passphrase, which means that we'll have to enter the pass phrase each time the server starts.  This is impractical and unnecessary, so we create an unprotected version of the key.  Security implication: if anyone gets access to the file keyfile.pem, they effectively own the key as much as you do.  Mitigation: don't use this key/cert combo for anything besides providing ssl for the web site.
                        [root misc]# openssl rsa -in newreq.pem -out keyfile.pem
 read RSA key
 Enter PEM pass phrase:
 writing RSA key
Index: openacs-4/packages/acs-core-docs/www/install-steps.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-steps.adp,v
diff -u -N -r1.1.2.12 -r1.1.2.13
--- openacs-4/packages/acs-core-docs/www/install-steps.adp	21 Jun 2016 07:44:36 -0000	1.1.2.12
+++ openacs-4/packages/acs-core-docs/www/install-steps.adp	23 Jun 2016 08:32:45 -0000	1.1.2.13
@@ -14,7 +14,8 @@
 
                      • Install an OS and supporting software (see Install a
 Unix-like OS or Appendix A,
 Install Red Hat 8/9
- for more details). See the Table 2.2,
+ for more details). See the
+Table 2.2,
 “Version Compatibility
 Matrix”.
                      • Install a database (see the section called
 “Install Oracle 8.1.7” or
@@ -92,14 +93,13 @@
 createdb $OPENACS_SERVICE_NAME
 
 
                        • 
-Setting a global shell variable for
-cut and paste. In order to cut and paste the
-instructions into your shell, you must set the environment variable
-$OPENACS_SERVICE_NAME. In order to set it globally so that it works
-for any new users or special service users you may create, edit the
-file /etc/profile (
-/etc/share/skel/dot.profile for
-FreeBSD) and add this line:
                        +Setting a global shell
+variable for cut and paste. In order to cut
+and paste the instructions into your shell, you must set the
+environment variable $OPENACS_SERVICE_NAME. In order to set it
+globally so that it works for any new users or special service
+users you may create, edit the file /etc/profile ( /etc/share/skel/dot.profile for FreeBSD)
+and add this line:
                         export OPENACS_SERVICE_NAME=service0
 
                        
 
                        • 
@@ -146,9 +146,9 @@
 
                    45. 
                     
 
                    
-
                    None of these locations are set in stone - they're simply the
-values that we've chosen. The values that you'll probably want to
-change, such as service name, are marked like
+
                    None of these locations are set in stone - they're simply
+the values that we've chosen. The values that you'll
+probably want to change, such as service name, are marked like
 this. The other values we recommend you leave
 unchanged unless you have a reason to change them.
                    
 
                    Note
                    Some of the paths and user accounts have been changed from those
@@ -157,31 +157,34 @@
 
                    
 
                    
 
                    
-Getting Help during installation
                    We'll do our best to assure that following our instructions will
-get you to the promised land. If something goes wrong, don't panic.
-There are plenty of ways to get help. Here are some tips:
                      
+Getting Help during installation
                    We'll do our best to assure that following our instructions
+will get you to the promised land. If something goes wrong,
+don't panic. There are plenty of ways to get help. Here are
+some tips:
                      
 
                    • Keep track of the commands you are run and record their output.
 I like to do my installations in a shell inside of emacs
 (M-x shell) so that I can save
 the output if needed. An alternative would be to use the
-script command.
                    • We'll point out where the error logs for the various pieces of
-software are. Output from those logs will help us help you. Don't
-worry if you feel overwhelmed by all the information in the error
-logs. Over time, you'll find that they make more and more sense.
-Soon, you'll actually look forward to errors so that you can run to
-the log and diagnose the problem.
                    • Search the forums at openacs.org - you'll often find many
-people who have struggled through the same spot that you're in.
                    • The bottom of each page has a link to OpenACS.org, where you can
+script command.
                    • We'll point out where the error logs for the various pieces
+of software are. Output from those logs will help us help you.
+Don't worry if you feel overwhelmed by all the information in
+the error logs. Over time, you'll find that they make more and
+more sense. Soon, you'll actually look forward to errors so
+that you can run to the log and diagnose the problem.
                    • Search the forums at openacs.org - you'll often find
+many people who have struggled through the same spot that
+you're in.
                    • The bottom of each page has a link to OpenACS.org, where you can
 post comments and read other users comments about the contents of
 the page.
                    • Ask questions at the irc channel on freenode.net (#openacs).
-They're knowledgeable and quite friendly if you can keep them on
-topic.
                    • Post a question on the forums. Make sure
-you've done a search first. When you do post, be sure to include
-your setup information (OS, etc) as well as the exact commands that
-are failing with the accompanying error. If there's a SQL error in
-the Tcl error or in the log, post that too.
                    • If you find errors in this document or if you have ideas about
+They're knowledgeable and quite friendly if you can keep them
+on topic.
                    • Post a question on the forums. Make sure
+you've done a search first. When you do post, be sure to
+include your setup information (OS, etc) as well as the exact
+commands that are failing with the accompanying error. If
+there's a SQL error in the Tcl error or in the log, post that
+too.
                    • If you find errors in this document or if you have ideas about
 making it better, please post them in our BugTracker.
                      • 
-
                    ($‌Id: overview.xml,v 1.29.2.1 2015/09/28
-07:54:30 gustafn Exp $)
                    
+
                    ($‌Id: install-steps.html,v 1.35.2.10 2016/06/21
+07:44:36 gustafn Exp $)
                    
 
 
 $OPENACS_SERVICE_NAME (set to service0 in default install)
                    45. OpenACS service account$OPENACS_SERVICE_NAME
                    OpenACS database name$OPENACS_SERVICE_NAME
                    Root of OpenACS service file tree (SERVERROOT)/var/lib/aolserver/$OPENACS_SERVICE_NAME
                    Location of source code tarballs for new software/var/tmp
                    The OpenACS tarball contains some files which
                 are useful while setting up other software.  Those
                 files are located at:/var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files
                    Database backup directory/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup
                    Service config files/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc
                    Service log files/var/lib/aolserver/$OPENACS_SERVICE_NAME/log
                    Compile directory/usr/local/src
                    PostgreSQL directory/usr/local/pgsql
                    AOLserver directory/usr/local/aolserver

                    
-      None of these locations are set in stone - they're simply
-      the values that we've chosen.  The values that you'll
+      None of these locations are set in stone - they're simply
+      the values that we've chosen.  The values that you'll
       probably want to change, such as service name, are
       marked like this.  The other
       values we recommend you leave unchanged unless you have a
@@ -58,8 +58,8 @@
         those recommended in previous versions of this document to
         improve security and maintainability.  See this
 	  thread for discussion.
                    Getting Help during installation
                    
-      We'll do our best to assure that following our instructions will get
-      you to the promised land. If something goes wrong, don't
+      We'll do our best to assure that following our instructions will get
+      you to the promised land. If something goes wrong, don't
       panic. There are plenty of ways to get help. Here are some tips:
     
                    • 
           Keep track of the commands you are run and record their output. I
@@ -68,30 +68,30 @@
           the output if needed. An alternative would be to use the
           script command.
         
                    • 
-          We'll point out where the error logs for the various pieces of
-          software are. Output from those logs will help us help you. Don't
+          We'll point out where the error logs for the various pieces of
+          software are. Output from those logs will help us help you. Don't
           worry if you feel overwhelmed by all the information in the error
-          logs. Over time, you'll find that they make more and more
-          sense. Soon, you'll actually look forward to errors so that you
+          logs. Over time, you'll find that they make more and more
+          sense. Soon, you'll actually look forward to errors so that you
           can run to the log and diagnose the problem. 
         
                    • 
           Search the forums at
-            openacs.org - you'll often find many people who have
-          struggled through the same spot that you're in.
+            openacs.org - you'll often find many people who have
+          struggled through the same spot that you're in.
         
                    • 
           The bottom of each page has a link to OpenACS.org, where you can post
           comments and read other users comments about the
           contents of the page.
         
                    • 
           Ask questions at the irc channel on freenode.net
-          (#openacs). They're knowledgeable and quite friendly
+          (#openacs). They're knowledgeable and quite friendly
           if you can keep them on topic.
         
                    • 
           Post a question on the forums. Make sure
-          you've done a search first. When you do post, be sure to include
+          you've done a search first. When you do post, be sure to include
           your setup information (OS, etc) as well as the exact commands
           that are failing with the accompanying error.  If
-          there's a SQL error in the Tcl error or in the log,
+          there's a SQL error in the Tcl error or in the log,
           post that too.
         
                    • 
           If you find errors in this document or if you have ideas about
Index: openacs-4/packages/acs-core-docs/www/ix01.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ix01.adp,v
diff -u -N -r1.1.2.11 -r1.1.2.12
--- openacs-4/packages/acs-core-docs/www/ix01.adp	21 Jun 2016 07:44:36 -0000	1.1.2.11
+++ openacs-4/packages/acs-core-docs/www/ix01.adp	23 Jun 2016 08:32:45 -0000	1.1.2.12
@@ -8,23 +8,23 @@
 		    rightLink="" rightLabel="">
 		
                      
 
                      
-Index
                      
+Index
                    
 
                    
-
                    Symbols
                    $OPENACS_SERVICE_NAME, Paths and
+
                    Symbols
                    $OPENACS_SERVICE_NAME, Paths and
 Users
 
                    
 
                    
 
                    A
                    
-
                    AOLserver
                    configuration, Installation Option 2: Install
+
                    AOLserver
                    configuration, Installation Option 2: Install
 from tarball
-
                    Automated tests, Write
+
                    Automated tests, Write
 automated tests
 
                    
 
                    
 
                    
 
                    C
                    
-
                    computeroutput
                    code, Code
-
                    cvs
                    
+
                    computeroutput
                    code, Code
+
                    cvs
                    
 
                    initializing, Initialize CVS (OPTIONAL)
 
                    setup, Using CVS with
 an OpenACS Site
@@ -33,62 +33,62 @@
 
                    
 
                    
 
                    D
                    
-
                    daemontools
                    installation, Install Daemontools (OPTIONAL)
-
                    docbook
                    installation, Install Red Hat 8/9
-
                    DocBook
                    
+
                    daemontools
                    installation, Install Daemontools (OPTIONAL)
+
                    docbook
                    installation, Install Red Hat 8/9
+
                    DocBook
                    
 
                    DTD, OpenACS Documentation Strategy:
 Why DocBook?
 
                    emacs configuration for, Add PSGML commands to emacs init file
 (OPTIONAL)
 
                    
-
                    Document structure, Document
+
                    Document structure, Document
 Structure
 
                    
 
                    
 
                    
 
                    E
                    
-
                    emacs
                    installation, Install Red Hat 8/9
-
                    emphasis
                    bold, italics, Emphasis
+
                    emacs
                    installation, Install Red Hat 8/9
+
                    emphasis
                    bold, italics, Emphasis
 
                    
 
                    
 
                    
 
                    F
                    
-
                    full text search
                    installation, Install
+
                    full text search
                    installation, Install
 Tsearch2 module, Install
 OpenFTS module, Install
 OpenFTS prerequisites in PostgreSQL instance
 
                    
 
                    
 
                    
 
                    G
                    
-
                    Graphics
                    Images, Graphics
+
                    Graphics
                    Images, Graphics
 
                    
 
                    
 
                    
 
                    I
                    
-
                    informaltable
                    table, Tables
+
                    informaltable
                    table, Tables
 
                    
 
                    
 
                    
 
                    L
                    
-
                    language
                    installation, Install Red Hat 8/9
-
                    Linking, Links
-
                    lists, Lists
+
                    language
                    installation, Install Red Hat 8/9
+
                    Linking, Links
+
                    lists, Lists
 
                    
 
                    
 
                    
-
                    O
                    OpenACS Package, What a Package
+
                    O
                    OpenACS Package, What a Package
 Looks Like
 
                    
 
                    
 
                    P
                    
-
                    photo-album
                    installation (see ImageMagick)
                    Postgres
                    Vacuuming, Installation Option 2: Install
+
                    photo-album
                    installation (see ImageMagick)
                    Postgres
                    Vacuuming, Installation Option 2: Install
 from tarball
 
                    
 
                    
 
                    
 
                    Q
                    
-
                    qmail
                    
+
                    qmail
                    
 
                    installation, Install qmail (OPTIONAL)
 
                    Maildir, Install
 qmail (OPTIONAL)
@@ -98,39 +98,39 @@
 
                    
 
                    
 
                    S
                    
-
                    sect1, Headlines,
+
                    sect1, Headlines,
 Sections
-
                    sect2, Headlines,
+
                    sect2, Headlines,
 Sections
-
                    Sections
                    Headlines, Headlines,
+
                    Sections
                    Headlines, Headlines,
 Sections
-
                    security
                    
+
                    security
                    
 
                    definition, Install Red Hat 8/9
 
                    firewall, Install Red Hat 8/9
 
                    
-
                    sendmail
                    removing, Install qmail (OPTIONAL)
-
                    ssh, Install Red Hat 8/9
+
                    sendmail
                    removing, Install qmail (OPTIONAL)
+
                    ssh, Install Red Hat 8/9
 
                    
 
                    
 
                    
-
                    T
                    The publish point for new
+
                    T
                    The publish point for new
 packages should be fixed., Prepare the package for
 distribution.
 
                    
 
                    
 
                    U
                    
-
                    ulink, Links
-
                    upgrade
                    
+
                    ulink, Links
+
                    upgrade
                    
 
                    OpenACS 4.5 to 4.6.x
                    Linux/Unix, Upgrading 4.5 or higher to 4.6.3
 
                    
 
                    
 
                    
 
                    
 
                    X
                    
-
                    XML guidelines, OpenACS
+
                    XML guidelines, OpenACS
 Documentation Strategy: Why DocBook?
-
                    xref
                    linkend, Links
-
                    xreflabel, Headlines,
+
                    xref
                    linkend, Links
+
                    xreflabel, Headlines,
 Sections
 
                    
 
                    
Index: openacs-4/packages/acs-core-docs/www/ix01.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ix01.html,v
diff -u -N -r1.29.2.10 -r1.29.2.11
--- openacs-4/packages/acs-core-docs/www/ix01.html	21 Jun 2016 07:44:36 -0000	1.29.2.10
+++ openacs-4/packages/acs-core-docs/www/ix01.html	23 Jun 2016 08:32:45 -0000	1.29.2.11
@@ -1,3 +1,3 @@
 
-Index
                    Alex logo
                    Prev  
                    Index
                    Symbols
                    $OPENACS_SERVICE_NAME, Paths and Users
                    A
                    AOLserver
                    configuration, Installation Option 2: Install from tarball
                    Automated tests, Write automated tests
                    C
                    computeroutput
                    code, Code
                    cvs
                    initializing, Initialize CVS (OPTIONAL)
                    setup, Using CVS with an OpenACS Site
                    D
                    daemontools
                    installation, Install Daemontools (OPTIONAL)
                    docbook
                    installation, Install Red Hat 8/9
                    DocBook
                    DTD, OpenACS Documentation Strategy: Why DocBook?
                    emacs configuration for, Add PSGML commands to emacs init file (OPTIONAL)
                    Document structure, Document Structure
                    E
                    emacs
                    installation, Install Red Hat 8/9
                    emphasis
                    bold, italics, Emphasis
                    F
                    full text search
                    installation, Install Tsearch2 module, Install OpenFTS module, Install OpenFTS prerequisites in PostgreSQL instance
                    G
                    Graphics
                    Images, Graphics
                    I
                    informaltable
                    table, Tables
                    L
                    language
                    installation, Install Red Hat 8/9
                    Linking, Links
                    lists, Lists
                    O
                    OpenACS Package, What a Package Looks Like
                    P
                    photo-album
                    installation (see ImageMagick)
                    Postgres
                    Vacuuming, Installation Option 2: Install from tarball
                    Q
                    qmail
                    installation, Install qmail (OPTIONAL)
                    Maildir, Install qmail (OPTIONAL)
                    rcpthosts error message, Install qmail (OPTIONAL)
                    S
                    sect1, Headlines, Sections
                    sect2, Headlines, Sections
                    Sections
                    Headlines, Headlines, Sections
                    security
                    definition, Install Red Hat 8/9
                    firewall, Install Red Hat 8/9
                    sendmail
                    removing, Install qmail (OPTIONAL)
                    ssh, Install Red Hat 8/9
                    T
                    The publish point for new packages should be
-        fixed., Prepare the package for distribution.
                    U
                    ulink, Links
                    upgrade
                    OpenACS 4.5 to 4.6.x
                    Linux/Unix, Upgrading 4.5 or higher to 4.6.3
                    X
                    XML guidelines, OpenACS Documentation Strategy: Why DocBook?
                    xref
                    linkend, Links
                    xreflabel, Headlines, Sections
                    Prev Home 
                    How to Update the translations Up 
                    docs@openacs.org
                    View comments on this page at openacs.org
                    
+Index
                    Alex logo
                    Prev  
                    Index
                    Symbols
                    $OPENACS_SERVICE_NAME, Paths and Users
                    A
                    AOLserver
                    configuration, Installation Option 2: Install from tarball
                    Automated tests, Write automated tests
                    C
                    computeroutput
                    code, Code
                    cvs
                    initializing, Initialize CVS (OPTIONAL)
                    setup, Using CVS with an OpenACS Site
                    D
                    daemontools
                    installation, Install Daemontools (OPTIONAL)
                    docbook
                    installation, Install Red Hat 8/9
                    DocBook
                    DTD, OpenACS Documentation Strategy: Why DocBook?
                    emacs configuration for, Add PSGML commands to emacs init file (OPTIONAL)
                    Document structure, Document Structure
                    E
                    emacs
                    installation, Install Red Hat 8/9
                    emphasis
                    bold, italics, Emphasis
                    F
                    full text search
                    installation, Install Tsearch2 module, Install OpenFTS module, Install OpenFTS prerequisites in PostgreSQL instance
                    G
                    Graphics
                    Images, Graphics
                    I
                    informaltable
                    table, Tables
                    L
                    language
                    installation, Install Red Hat 8/9
                    Linking, Links
                    lists, Lists
                    O
                    OpenACS Package, What a Package Looks Like
                    P
                    photo-album
                    installation (see ImageMagick)
                    Postgres
                    Vacuuming, Installation Option 2: Install from tarball
                    Q
                    qmail
                    installation, Install qmail (OPTIONAL)
                    Maildir, Install qmail (OPTIONAL)
                    rcpthosts error message, Install qmail (OPTIONAL)
                    S
                    sect1, Headlines, Sections
                    sect2, Headlines, Sections
                    Sections
                    Headlines, Headlines, Sections
                    security
                    definition, Install Red Hat 8/9
                    firewall, Install Red Hat 8/9
                    sendmail
                    removing, Install qmail (OPTIONAL)
                    ssh, Install Red Hat 8/9
                    T
                    The publish point for new packages should be
+        fixed., Prepare the package for distribution.
                    U
                    ulink, Links
                    upgrade
                    OpenACS 4.5 to 4.6.x
                    Linux/Unix, Upgrading 4.5 or higher to 4.6.3
                    X
                    XML guidelines, OpenACS Documentation Strategy: Why DocBook?
                    xref
                    linkend, Links
                    xreflabel, Headlines, Sections
                    Prev Home 
                    How to Update the translations Up 
                    docs@openacs.org
                    View comments on this page at openacs.org
                    
Index: openacs-4/packages/acs-core-docs/www/maint-performance.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maint-performance.adp,v
diff -u -N -r1.1.2.11 -r1.1.2.12
--- openacs-4/packages/acs-core-docs/www/maint-performance.adp	21 Jun 2016 07:44:36 -0000	1.1.2.11
+++ openacs-4/packages/acs-core-docs/www/maint-performance.adp	23 Jun 2016 08:32:45 -0000	1.1.2.12
@@ -19,15 +19,16 @@
 degrade in performance. For PostGreSQL, see the section called
 “Vacuum Postgres nightly”. For
 Oracle, use exec
-dbms_stats.gather_schema_stats('SCHEMA_NAME') (Andrew Piskorski's Oracle notes).
                  45. 
+dbms_stats.gather_schema_stats('SCHEMA_NAME')
+(Andrew Piskorski's Oracle notes).
                  46. 
 
                    You can track the exact amount of time each database query on a
 page takes:
                      
 
                    1. Go to Main Site : Site-Wide Administration : Install
 Software
-
                    2. Click on "Install New Application" in "Install from OpenACS
-Repository"
                    3. Choose "ACS Developer Support">
                    4. After install is complete, restart the server.
                    5. Browse to Developer Support, which is automatically mounted at
-/ds.
                    6. Turn on Database statistics
                    7. Browse directly to a slow page and click "Request Information"
-at the bottom of the page.
                    8. 
+
                    9. Click on "Install New Application" in "Install
+from OpenACS Repository"
                    10. Choose "ACS Developer Support">
                    11. After install is complete, restart the server.
                    12. Browse to Developer Support, which is automatically mounted at
+/ds.
                    13. Turn on Database statistics
                    14. Browse directly to a slow page and click "Request
+Information" at the bottom of the page.
                    15. 
 
                      This should return a list of database queries on the page,
 including the exact query (so it can be cut-paste into psql or
 oracle) and the time each query took.
                      
@@ -72,7 +73,7 @@
 
                      To kill a troubled process:
                       alter system kill session 'SID,SERIAL#';  --substitute values for SID and SERIAL#
 
                      (See Andrew
-Piskorski's Oracle notes)
                      
+Piskorski's Oracle notes)
                      
 
                    16. 
 
                      Identify a runaway Postgres query. First, logging must be
 enabled in the database. This imposes a performance penalty and
@@ -112,23 +113,23 @@
 Statspack, a package to monitor and save the state of the v$
 performance views. These reports help finding severe problems by
 exposing summary data about the Oracle wait interface, executed
-queries. You'll find the installation instructions in
+queries. You'll find the installation instructions in
 $ORACLE_HOME/rdbms/admin/spdoc.txt. Follow the instructions
-carefully and take periodic snapshots, this way you'll be able to
-look at historical performance data.
                      Also turn on the timed_statistics in your init.ora file, so that
+carefully and take periodic snapshots, this way you'll be able
+to look at historical performance data.
                      Also turn on the timed_statistics in your init.ora file, so that
 Statspack reports (and all other Oracle reports) are timed, which
 makes them a lot more meaningful. The overhead of timing data is
 about 1% per Oracle Support information.
                      To be able to get a overview of how Oracle executes a particular
-query, install "autotrace". I usually follow the instructions here
-http://asktom.oracle.com/~tkyte/article1/autotrace.html.
                      
+query, install "autotrace". I usually follow the
+instructions here http://asktom.oracle.com/~tkyte/article1/autotrace.html.
                      
 
                      
 Make sure, that the Oracle CBO works with
 adequate statistics
                      The Oracle Cost Based optimizer is a piece of software that
-tries to find the "optimal" execution plan for a given SQL
-statement. For that it estimates the costs of running a SQL query
-in a particular way (by default up to 80.000 permutations are being
-tested in a Oracle 8i). To get an adequate cost estimate, the CBO
-needs to have adequate statistics. For that Oracle supplies the
+tries to find the "optimal" execution plan for a given
+SQL statement. For that it estimates the costs of running a SQL
+query in a particular way (by default up to 80.000 permutations are
+being tested in a Oracle 8i). To get an adequate cost estimate, the
+CBO needs to have adequate statistics. For that Oracle supplies the
 dbms_stats package.
                      
 
                      
 
                      
Index: openacs-4/packages/acs-core-docs/www/maint-performance.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maint-performance.html,v
diff -u -N -r1.29.2.10 -r1.29.2.11
--- openacs-4/packages/acs-core-docs/www/maint-performance.html	21 Jun 2016 07:44:36 -0000	1.29.2.10
+++ openacs-4/packages/acs-core-docs/www/maint-performance.html	23 Jun 2016 08:32:45 -0000	1.29.2.11
@@ -1,7 +1,7 @@
 
 Diagnosing Performance Problems
                      Alex logo
                      Prev Chapter 6. Production Environments Next
                      Diagnosing Performance Problems
                      • Did performance problems happen overnight, or did they sneak up on
     you? Any clue what caused the performance problems (e.g. loading 20K
-    users into .LRN)
                      • Is the file system out of space?  Is the machine swapping to disk constantly?
                      • Isolating and solving database problems.
                        • Without daily internal maintenance, most databases slowly degrade in performance.  For PostGreSQL, see the section called “Vacuum Postgres nightly”.  For Oracle, use exec dbms_stats.gather_schema_stats('SCHEMA_NAME') (Andrew Piskorski's Oracle notes).
                        • You can track the exact amount of time each database query on a page takes:
                          1. Go to Main Site : Site-Wide Administration : Install Software
                          2. Click on "Install New Application" in "Install from OpenACS Repository"
                          3. Choose "ACS Developer Support">
                          4. After install is complete, restart the server.
                          5. Browse to Developer Support, which is automatically mounted at /ds.
+    users into .LRN)
                          6. Is the file system out of space?  Is the machine swapping to disk constantly?
                          7. Isolating and solving database problems.
                            • Without daily internal maintenance, most databases slowly degrade in performance.  For PostGreSQL, see the section called “Vacuum Postgres nightly”.  For Oracle, use exec dbms_stats.gather_schema_stats('SCHEMA_NAME') (Andrew Piskorski's Oracle notes).
                            • You can track the exact amount of time each database query on a page takes:
                              1. Go to Main Site : Site-Wide Administration : Install Software
                              2. Click on "Install New Application" in "Install from OpenACS Repository"
                              3. Choose "ACS Developer Support">
                              4. After install is complete, restart the server.
                              5. Browse to Developer Support, which is automatically mounted at /ds.
               
                              6. Turn on Database statistics
                              7. Browse directly to a slow page and click "Request Information" at the bottom of the page.
                              8. This should return a list of database queries on the page, including the exact query (so it can be cut-paste into psql or oracle) and the time each query took.
                                Figure 6.8. Query Analysis example
                                Query Analysis example

                            • Identify a runaway Oracle query: first, use ps aux or top to get the UNIX process ID of a runaway Oracle process.
                              Log in to SQL*Plus as the admin:
                              [$OPENACS_SERVICE_NAME ~]$ svrmgrl
 
 Oracle Server Manager Release 3.1.7.0.0 - Production
@@ -27,7 +27,7 @@
  where sql.address    = s.sql_address
    and sql.hash_value = s.sql_hash_value
  --and upper(s.username) like 'USERNAME%'
- order by s.username ,s.sid ,s.serial# ,sql.piece ;
                              To kill a troubled process:
                              alter system kill session 'SID,SERIAL#';  --substitute values for SID and SERIAL#
                              (See Andrew Piskorski's Oracle notes)
                            • Identify a runaway Postgres query.  First, logging must be enabled in the database.  This imposes a performance penalty and should not be done in normal operation.
                              Edit the file postgresql.conf - its location depends on the PostGreSQL installation - and change
                              #stats_command_string = false
                              to
                              stats_command_string = true
                              Next, connect to postgres (psql service0) and select * from pg_stat_activity;.  Typical output should look like:
                              + order by s.username ,s.sid ,s.serial# ,sql.piece ;
                              To kill a troubled process:
                              alter system kill session 'SID,SERIAL#';  --substitute values for SID and SERIAL#
                              (See Andrew Piskorski's Oracle notes)
                            • Identify a runaway Postgres query.  First, logging must be enabled in the database.  This imposes a performance penalty and should not be done in normal operation.
                              Edit the file postgresql.conf - its location depends on the PostGreSQL installation - and change
                              #stats_command_string = false
                              to
                              stats_command_string = true
                              Next, connect to postgres (psql service0) and select * from pg_stat_activity;.  Typical output should look like:
                                 datid   |   datname   | procpid | usesysid | usename |  current_query
 ----------+-------------+---------+----------+---------+-----------------
  64344418 | openacs.org |   14122 |      101 | nsadmin | <IDLE>
@@ -47,9 +47,9 @@
       what is going on inside Oracle. Oracle provides Statspack, a package to
       monitor and save the state of the v$ performance views. These reports
       help finding severe problems by exposing summary data about the Oracle
-      wait interface, executed queries. You'll find the installation
+      wait interface, executed queries. You'll find the installation
       instructions in $ORACLE_HOME/rdbms/admin/spdoc.txt. Follow the
-      instructions carefully and take periodic snapshots, this way you'll be
+      instructions carefully and take periodic snapshots, this way you'll be
       able to look at historical performance data.
     
                              
       Also turn on the timed_statistics in your init.ora file, so that
Index: openacs-4/packages/acs-core-docs/www/maintenance-deploy.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maintenance-deploy.adp,v
diff -u -N -r1.1.2.11 -r1.1.2.12
--- openacs-4/packages/acs-core-docs/www/maintenance-deploy.adp	21 Jun 2016 07:44:36 -0000	1.1.2.11
+++ openacs-4/packages/acs-core-docs/www/maintenance-deploy.adp	23 Jun 2016 08:32:45 -0000	1.1.2.12
@@ -11,8 +11,8 @@
 
                              
 Staged Deployment for Production
 Networks
                              
-
                              ($‌Id: maintenance.xml,v 1.30 2010/12/11
-23:36:32 ryang Exp $)
                              By Joel Aufrecht
+
                              ($‌Id: maintenance-deploy.html,v 1.24.2.10
+2016/06/21 07:44:36 gustafn Exp $)
                              By Joel Aufrecht
 
                              
 OpenACS docs are written by the named authors, and may be edited by
 OpenACS documentation staff.
                              This section describes two minimal-risk methods for deploying
@@ -31,29 +31,30 @@
 only way files should move between the server instances is via
 cvs.
                              To set up a developmental installation, first set up either your
 developmental installation or your production installation, and
-follow the instructions for committing your files to CVS. We'll
+follow the instructions for committing your files to CVS. We'll
 assume in this example that you set up the production server
 (service0). To set up the developmental instance, you then follow
 the intall guide again, this time creating a new user
-(service0-dev) that you'll use for the new installation. To get the
-files for service0-dev, you check them out from cvs (check out
+(service0-dev) that you'll use for the new installation. To get
+the files for service0-dev, you check them out from cvs (check out
 service0).
                               su - service0-dev
 co -d /cvsroot service0
 mv service0 /var/lib/aolserver/service0-dev
 ln -s /home/service0-dev/web /var/lib/aolserver/service0-dev
 emacs web/etc/config.tcl
 emacs web/etc/daemontools/run
-
                              In the config.tcl file, you'll probably want to pay attention
-the rollout support section. That will ensure that email on your
-developmental server will not be sent out to the general world.
                              Also, instead of going through the OpenACS online installer,
-you'll actually load live data into your production server.
                              You can even automate the process of getting live data from your
+
                              In the config.tcl file, you'll probably want to pay
+attention the rollout support section. That will ensure that email
+on your developmental server will not be sent out to the general
+world.
                              Also, instead of going through the OpenACS online installer,
+you'll actually load live data into your production server.
                              You can even automate the process of getting live data from your
 production server. Copy something like this to
-/home/service0-dev/bin and put it in service0-dev's crontab to run
-once a night. You'll need to make sure the database backups are set
-up in service0's crontab, and that if the servers are on different
-physical machines, that the database backup is copied to the
-developmental machine once per night.
                              +/home/service0-dev/bin and put it in service0-dev's crontab to
+run once a night. You'll need to make sure the database backups
+are set up in service0's crontab, and that if the servers are
+on different physical machines, that the database backup is copied
+to the developmental machine once per night.
                               /usr/local/bin/svc -d /service/service0-dev
 /bin/sleep 60
 # this deletes the dev database!
@@ -75,7 +76,7 @@
 if the file is /var/lib/aolserver/service0-dev/www/index.adp, do: 
 
 cd /var/lib/aolserver/service0-dev/www
-cvs diff index.adp (this is optional; it's just a
+cvs diff index.adp (this is optional; it's just a
 reality check)
 the lines starting > will be added and the lines
 starting < will be removed, when you commit
@@ -88,18 +89,18 @@
 cvs up -Pd index.adp
 
                              If you make changes that require changes to the database, test
 them out first on service0-dev, using either -create.sql or upgrade
-scripts. Once you've tested them, you then update and run the
+scripts. Once you've tested them, you then update and run the
 upgrade scripts from the package manager.
                              The production site can run "HEAD" from cvs.
                              The drawback to using HEAD as the live code is that you cannot
 commit new work on the development server without erasing the
-definition of 'working production code.' So a better method is to
-use a tag. This guarantees that, at any time in the future, you can
-retrieve exactly the same set of code. This is useful for both of
-the characteristics of safe change deployment. For control, you can
-use tags to define a body of code, test that code, and then know
-that what you are deploying is exactly that code. For rollback, you
-can use return to the last working tag if the new tag (or new,
-untagged changes) cause problems. .... example of using tags to
-follow ...
                              
+definition of 'working production code.' So a better method
+is to use a tag. This guarantees that, at any time in the future,
+you can retrieve exactly the same set of code. This is useful for
+both of the characteristics of safe change deployment. For control,
+you can use tags to define a body of code, test that code, and then
+know that what you are deploying is exactly that code. For
+rollback, you can use return to the last working tag if the new tag
+(or new, untagged changes) cause problems. .... example of using
+tags to follow ...
                              
 
                            
 
                            
 Method 2: A/B Deployment
                            The approach taken in this section is to always create a new
@@ -120,27 +121,27 @@
 
                            
 Simple A/B Deployment: Database is not
 changed
                            
-
                            Figure 6.2. Simple A/B
-Deployment - Step 1
                            Simple A/B Deployment - Step 1
                            
+
                            Figure 6.2. Simple
+A/B Deployment - Step 1
                            Simple A/B Deployment - Step 1
                            
 

                            
-
                            Figure 6.3. Simple A/B
-Deployment - Step 2
                            Simple A/B Deployment - Step 2
                            
+
                            Figure 6.3. Simple
+A/B Deployment - Step 2
                            Simple A/B Deployment - Step 2
                            
 

                            
-
                            Figure 6.4. Simple A/B
-Deployment - Step 3
                            Simple A/B Deployment - Step 3
                            
+
                            Figure 6.4. Simple
+A/B Deployment - Step 3
                            Simple A/B Deployment - Step 3
                            
 

                            
 
                            
 
                            
 Complex A/B Deployment: Database is
 changed
                            
-
                            Figure 6.5. Complex A/B
-Deployment - Step 1
                            Complex A/B Deployment - Step 1
                            
+
                            Figure 6.5. Complex A/B Deployment
+- Step 1
                            Complex A/B Deployment - Step 1
                            
 

                            
-
                            Figure 6.6. Complex A/B
-Deployment - Step 2
                            Complex A/B Deployment - Step 2
                            
+
                            Figure 6.6. Complex A/B Deployment
+- Step 2
                            Complex A/B Deployment - Step 2
                            
 

                            
-
                            Figure 6.7. Complex A/B
-Deployment - Step 3
                            Complex A/B Deployment - Step 3
                            
+
                            Figure 6.7. Complex A/B Deployment
+- Step 3
                            Complex A/B Deployment - Step 3
                            
 

                            
 
                            
 
                          
Index: openacs-4/packages/acs-core-docs/www/maintenance-deploy.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maintenance-deploy.html,v
diff -u -N -r1.24.2.10 -r1.24.2.11
--- openacs-4/packages/acs-core-docs/www/maintenance-deploy.html	21 Jun 2016 07:44:36 -0000	1.24.2.10
+++ openacs-4/packages/acs-core-docs/www/maintenance-deploy.html	23 Jun 2016 08:32:45 -0000	1.24.2.11
@@ -10,10 +10,10 @@
       instances is via cvs.
                          To set up a developmental installation, first set up
       either your developmental installation or your production
       installation, and follow the instructions for committing your
-      files to CVS. We'll assume in this example that you set up the
+      files to CVS. We'll assume in this example that you set up the
       production server (service0). To set up the developmental instance,
       you then follow the intall guide again, this time creating a new
-      user (service0-dev) that you'll use for the new installation. To get
+      user (service0-dev) that you'll use for the new installation. To get
       the files for service0-dev, you check them out from cvs (check out
       service0). 
                           su - service0-dev
@@ -22,14 +22,14 @@
 ln -s /home/service0-dev/web /var/lib/aolserver/service0-dev
 emacs web/etc/config.tcl
 emacs web/etc/daemontools/run
-
                          In the config.tcl file, you'll probably want to pay attention
+
                          In the config.tcl file, you'll probably want to pay attention
       the rollout support section. That will ensure that email on your
       developmental server will not be sent out to the general world.
                          Also, instead of going through the OpenACS online
-      installer, you'll actually load live data into your production
+      installer, you'll actually load live data into your production
       server. 
                          You can even automate the process of getting live data
       from your production server. Copy something like this to
-      /home/service0-dev/bin and put it in service0-dev's crontab to
-      run once a night. You'll need to make sure the database backups
+      /home/service0-dev/bin and put it in service0-dev's crontab to
+      run once a night. You'll need to make sure the database backups
       are set up in service0's crontab, and that if the servers are on
       different physical machines, that the database backup is copied
       to the developmental machine once per night.
                          @@ -54,7 +54,7 @@
 if the file is /var/lib/aolserver/service0-dev/www/index.adp, do: 
 
 cd /var/lib/aolserver/service0-dev/www
-cvs diff index.adp (this is optional; it's just a
+cvs diff index.adp (this is optional; it's just a
 reality check)
 the lines starting > will be added and the lines
 starting < will be removed, when you commit
@@ -66,5 +66,5 @@
 cd /var/lib/aolserver/service0/www
 cvs up -Pd index.adp
                          If you make changes that require changes to the database,
       test them out first on service0-dev, using either -create.sql or
-      upgrade scripts. Once you've tested them, you then update and
+      upgrade scripts. Once you've tested them, you then update and
       run the upgrade scripts from the package manager. 
                          The production site can run "HEAD" from cvs.
                          The drawback to using HEAD as the live code is that you cannot commit new work on the development server without erasing the definition of 'working production code.'  So a better method is to use a tag.  This guarantees that, at any time in the future, you can retrieve exactly the same set of code.  This is useful for both of the characteristics of safe change deployment.  For control, you can use tags to define a body of code, test that code, and then know that what you are deploying is exactly that code.  For rollback, you can use return to the last working tag if the new tag (or new, untagged changes) cause problems.  .... example of using tags to follow ...
                        Method 2: A/B Deployment
                        The approach taken in this section is to always create a new service with the desired changes, running in parallel with the existing site.  This guarantees control, at least at the final step of the process: you know what changes you are about to make because you can see them directly.  It does not, by itself, guarantee the entire control chain.  You need additional measures to make sure that the change you are making is exactly and completely the change you intended to make and tested previously, and nothing more.  Those additional measures typically take the form of source control tags and system version numbers.  The parallel-server approach also guarantees rollback because the original working service is not touched; it is merely set aside.
                        This approach can has limitations.  If the database or file system regularly receiving new data, you must interrupt this function or risk losing data in the shuffle.  It also requires extra steps if the database will be affected.
                        Simple A/B Deployment: Database is not changed
                        Figure 6.2. Simple A/B Deployment - Step 1
                        Simple A/B Deployment - Step 1

                        Figure 6.3. Simple A/B Deployment - Step 2
                        Simple A/B Deployment - Step 2

                        Figure 6.4. Simple A/B Deployment - Step 3
                        Simple A/B Deployment - Step 3

                        Complex A/B Deployment: Database is changed
                        Figure 6.5. Complex A/B Deployment - Step 1
                        Complex A/B Deployment - Step 1

                        Figure 6.6. Complex A/B Deployment - Step 2
                        Complex A/B Deployment - Step 2

                        Figure 6.7. Complex A/B Deployment - Step 3
                        Complex A/B Deployment - Step 3

                      Prev Home Next
                      High Availability/High Performance Configurations Up Installing SSL Support for an OpenACS service
                      docs@openacs.org
                      View comments on this page at openacs.org
                      
Index: openacs-4/packages/acs-core-docs/www/maintenance-web.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maintenance-web.adp,v
diff -u -N -r1.1.2.2 -r1.1.2.3
--- openacs-4/packages/acs-core-docs/www/maintenance-web.adp	9 Jun 2016 13:03:11 -0000	1.1.2.2
+++ openacs-4/packages/acs-core-docs/www/maintenance-web.adp	23 Jun 2016 08:32:45 -0000	1.1.2.3
@@ -7,7 +7,7 @@
 
 		
                      
 
                      
Index: openacs-4/packages/acs-core-docs/www/maintenance-web.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maintenance-web.html,v
diff -u -N -r1.40.2.1 -r1.40.2.2
--- openacs-4/packages/acs-core-docs/www/maintenance-web.html	9 Jun 2016 08:44:50 -0000	1.40.2.1
+++ openacs-4/packages/acs-core-docs/www/maintenance-web.html	23 Jun 2016 08:32:45 -0000	1.40.2.2
@@ -1,5 +1,5 @@
 
-Chapter 6. Production Environments
                      Alex logo
                      Prev Part II. Administrator's Guide Next
                      Chapter 6. Production Environments
                      Table of Contents
                      Starting and Stopping an OpenACS instance.
                      AOLserver keepalive with inittab
                      Running multiple services on one machine
                      High Availability/High Performance Configurations
                      Staged Deployment for Production Networks
                      Installing SSL Support for an OpenACS service
                      Set up Log Analysis Reports
                      External uptime validation
                      Diagnosing Performance Problems
                      by Joel Aufrecht
                      
+Chapter 6. Production Environments
                      Alex logo
                      Prev Part II. Administrator's Guide Next
                      Chapter 6. Production Environments
                      Table of Contents
                      Starting and Stopping an OpenACS instance.
                      AOLserver keepalive with inittab
                      Running multiple services on one machine
                      High Availability/High Performance Configurations
                      Staged Deployment for Production Networks
                      Installing SSL Support for an OpenACS service
                      Set up Log Analysis Reports
                      External uptime validation
                      Diagnosing Performance Problems
                      by Joel Aufrecht
                      
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
                      Prev Home Next
                      Upgrading Platform components Up Starting and Stopping an OpenACS instance.
                      docs@openacs.org
                      View comments on this page at openacs.org
                      
Index: openacs-4/packages/acs-core-docs/www/object-identity.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-identity.adp,v
diff -u -N -r1.1.2.4 -r1.1.2.5
--- openacs-4/packages/acs-core-docs/www/object-identity.adp	9 Jun 2016 13:03:11 -0000	1.1.2.4
+++ openacs-4/packages/acs-core-docs/www/object-identity.adp	23 Jun 2016 08:32:45 -0000	1.1.2.5
@@ -15,43 +15,43 @@
 OpenACS docs are written by the named authors, and may be edited by
 OpenACS documentation staff.
                      One of the major design features of OpenACS 5.9.0 is the
 explicit representation of object
-identity. The reason I say "explicit representation" is
-because the concept of object identity has been around forever. It
-is inherent to our problem domain. Consider the example of 3.x
-style scoping. The 3.x data models use the triple (user_id,
-group_id, scope) to identify
-an object. In the 5.9.0 data
-model this object is explicitly
+identity. The reason I say "explicit
+representation" is because the concept of object identity has
+been around forever. It is inherent to our problem domain. Consider
+the example of 3.x style scoping. The 3.x data models use the
+triple (user_id, group_id, scope) to identify an object. In the 5.9.0 data model this
+object is explicitly
 represented by a single party_id.
                      Another good example of this is can be found in the user groups
 data model. The 3.x user groups data model contains another example
 of an implied identity.
 Every mapping between a user and a group could have an arbitrary
 number of attached values (user_group_member_fields, etc.). In this
 case it is the pair (group_id, user_id) that implicitly refers to
-an object (the person's membership in a group). In the 5.9.0 data
-model this object identity is made explicit by adding an integer
-primary key to the table that maps users to groups.
                      Coming from a purely relational world, this might seem slightly
+an object (the person's membership in a group). In the 5.9.0
+data model this object identity is made explicit by adding an
+integer primary key to the table that maps users to groups.
                      Coming from a purely relational world, this might seem slightly
 weird at first. The pair (group_id, user_id) is sufficient to
 uniquely identify the object in question, so why have the redundant
-integer primary key? If you take a closer look, it actually isn't
-quite so redundant. If you want to be able to use the object
-model's permissioning features, and generic attribute features on a
-table, you need an integer primary key for that table. This is
-because you can't really write a data model in oracle that uses
-more than one way to represent identity.
                      So, this apparently redundant primary key has saved us the
+integer primary key? If you take a closer look, it actually
+isn't quite so redundant. If you want to be able to use the
+object model's permissioning features, and generic attribute
+features on a table, you need an integer primary key for that
+table. This is because you can't really write a data model in
+oracle that uses more than one way to represent identity.
                      So, this apparently redundant primary key has saved us the
 trouble of duplicating the entire generic storage system for the
 special case of the user_group_map, and has saved us from
 implementing ad-hoc security instead of just using acs-permissions.
 This design choice is further validated by the fact that services
-like journals that weren't previously thought to be generic can in
-fact be generically applied to membership objects, thereby allowing
-us to eliminated membership state auditing columns that weren't
-even capable of fully tracking the history of membership state.
                      The design choice of explicitly representing object identity
+like journals that weren't previously thought to be generic can
+in fact be generically applied to membership objects, thereby
+allowing us to eliminated membership state auditing columns that
+weren't even capable of fully tracking the history of
+membership state.
                      The design choice of explicitly representing object identity
 with an integer primary key that is derived from a globally unique
 sequence is the key to eliminating redundant code and replacing it
 with generic object level
-services.
                      ($‌Id: object-identity.xml,v 1.7 2006/07/17
-05:38:37 torbenb Exp $)
                      
+services.
                      ($‌Id: object-identity.html,v 1.49.2.10
+2016/06/21 07:44:36 gustafn Exp $)
                      
 
                      
 implied identity. Every mapping between a user and a group could
 have an arbitrary number of attached values (user_group_member_fields, etc.).
 In this case it is the pair (group_id, user_id) that implicitly refers to an
-object (the person's membership in a group). In the 5.9.0 data model this
+object (the person's membership in a group). In the 5.9.0 data model this
 object identity is made explicit by adding an integer primary key to the
 table that maps users to groups.
                      Coming from a purely relational world, this might seem slightly weird at
 first. The pair (group_id, user_id) is sufficient to uniquely identify the
 object in question, so why have the redundant integer primary key? If you
-take a closer look, it actually isn't quite so redundant. If you want to
-be able to use the object model's permissioning features, and generic
+take a closer look, it actually isn't quite so redundant. If you want to
+be able to use the object model's permissioning features, and generic
 attribute features on a table, you need an integer primary key for that
-table. This is because you can't really write a data model in oracle that
+table. This is because you can't really write a data model in oracle that
 uses more than one way to represent identity.
                      So, this apparently redundant primary key has saved us the trouble of
 duplicating the entire generic storage system for the special case of the
 user_group_map, and has saved us from implementing ad-hoc security instead of
 just using acs-permissions. This design choice is further validated by the
-fact that services like journals that weren't previously thought to be
+fact that services like journals that weren't previously thought to be
 generic can in fact be generically applied to membership objects, thereby
-allowing us to eliminated membership state auditing columns that weren't
+allowing us to eliminated membership state auditing columns that weren't
 even capable of fully tracking the history of membership state.
                      The design choice of explicitly representing object identity with an
 integer primary key that is derived from a globally unique sequence is the
 key to eliminating redundant code and replacing it with generic object
Index: openacs-4/packages/acs-core-docs/www/object-system-design.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-design.adp,v
diff -u -N -r1.1.2.2 -r1.1.2.3
--- openacs-4/packages/acs-core-docs/www/object-system-design.adp	9 Jun 2016 08:44:50 -0000	1.1.2.2
+++ openacs-4/packages/acs-core-docs/www/object-system-design.adp	23 Jun 2016 08:32:45 -0000	1.1.2.3
@@ -44,15 +44,16 @@
 of application objects include:
                        
 
                      • forum messages
                      • A user home page
                      • A ticket in the ticket tracker
                        • 
 
                      In the past, developers had to use ad-hoc and inconsistent
-schemes to interface to various "general" services. OpenACS 4
-defines a central data model that keeps track of the application
-objects that we wish to manage, and serves as a primary store of
-metadata. By metadata, we mean data stored on behalf
-of an application outside of
-the application's data model in order to enable certain central
-services. The OpenACS 4 Object Model (or object system) manages
-several different kinds of data and metadata to allow us to provide
-general services to applications:
                        
+schemes to interface to various "general" services.
+OpenACS 4 defines a central data model that keeps track of the
+application objects that we wish to manage, and serves as a primary
+store of metadata. By
+metadata, we mean data
+stored on behalf of an application outside of the application's data
+model in order to enable certain central services. The OpenACS 4
+Object Model (or object system) manages several different kinds of
+data and metadata to allow us to provide general services to
+applications:
                          
 
                        • 
 
                          Object Identification
                          Every application object is given a unique identifier in the
 system. This identifier can be used to find all data related to a
@@ -103,15 +104,15 @@
 relation.
                          Also, in OpenACS 3.x many utility modules exist that do nothing
 more than attach some extra attributes to existing application
 data. For example, general comments maintains a table that maps
-application "page" data (static or dynamic pages on the website) to
-one or more user comments on that page. It does so by constructing
-a unique identifier for each page, usually a combination of the
-table in which the data is stored, and the value of the primary key
-value for the particular page. This idiom is referred to as the
-"(on_which_table + on_what_id)" method for identifying application
-data. In particular, general comments stores its map from pages to
-comments using a "(on_which_table + on_what_id)" key plus the ID of
-the comment itself.
                          All of these composite key constructions are implicit object
+application "page" data (static or dynamic pages on the
+website) to one or more user comments on that page. It does so by
+constructing a unique identifier for each page, usually a
+combination of the table in which the data is stored, and the value
+of the primary key value for the particular page. This idiom is
+referred to as the "(on_which_table + on_what_id)" method
+for identifying application data. In particular, general comments
+stores its map from pages to comments using a "(on_which_table
++ on_what_id)" key plus the ID of the comment itself.
                          All of these composite key constructions are implicit object
 identifiers - they build a unique ID out of other pieces of the
 data model. The problem is that their definition and use is ad-hoc
 and inconsistent, making the construction of generic
@@ -128,8 +129,8 @@
 new API to make sure every object the system is to manage is
 associated with a row in acs_objects. More importantly, if they do
 this, new services like general comments can be created without
-requiring existing applications to "hook into" them via new
-metadata.
                          
+requiring existing applications to "hook into" them via
+new metadata.
                          
 Note: Object
 identifiers are a good example of metadata in the new system. Each
 row in acs_objects stores
@@ -142,9 +143,9 @@
 Object Context and Access
 Control
                      Until the implementation of the general permissions system,
 every OpenACS application had to manage access control to its data
-separately. Later on, a notion of "scoping" was introduced into the
-core data model.
                      "Scope" is a term best explained by example. Consider some
-hypothetical rows in the address_book table:
                      
+separately. Later on, a notion of "scoping" was
+introduced into the core data model.
                      "Scope" is a term best explained by example. Consider
+some hypothetical rows in the address_book table:
                      
@@ -158,10 +159,10 @@
 
-
                      
 
 
 
                      ...public...
 
                      
 
                      The first row represents an entry in User 123's personal address
-book, the second row represents an entry in User Group 456's shared
-address book, and the third row represents an entry in the site's
-public address book.
                      In this way, the scoping columns identify the security context
+
                  The first row represents an entry in User 123's personal
+address book, the second row represents an entry in User Group
+456's shared address book, and the third row represents an
+entry in the site's public address book.
                  In this way, the scoping columns identify the security context
 in which a given object belongs, where each context is either a person or a group of people or the general public (itself a group of
 people).
                  In OpenACS 4, rather than breaking the world into a limited set
 of scopes, every object lives in a single context. A context is just an abstract
@@ -172,12 +173,12 @@
 forum topic as its context, and a forum topic might list a subsite
 as its context. Thus, contexts make it easier to break the site up
 into security domains according to its natural structure. An
-object's context is stored in the context_id column of the acs_objects table.
                  We use an object's context to provide a default answer to
+object's context is stored in the context_id column of the acs_objects table.
                  We use an object's context to provide a default answer to
 questions regarding access control. Whenever we ask a question of
-the form "can user X perform action Y on object Z", the OpenACS
-security model will defer to an object's context if there is no
-information about user X's permission to perform action Y on object
-Z.
                  The context system forms the basis for the rest of the OpenACS
+the form "can user X perform action Y on object Z", the
+OpenACS security model will defer to an object's context if
+there is no information about user X's permission to perform
+action Y on object Z.
                  The context system forms the basis for the rest of the OpenACS
 access control system, which is described in in two separate
 documents: one for the permissions
 system and another for the party groups system.
@@ -192,9 +193,9 @@
 3.x
                  The user/group system allowed developers to define group types along with attributes to be
 stored with each instance of a group type. Each group type could
 define a helper table that stored attributes on each instance of
-the group type. This table was called the "_info" table because the name was generated
-by appending _info to the name
-of the group type.
                  The user/groups data model also provided the user_group_type_member_fields and
+the group type. This table was called the "_info" table because the name was
+generated by appending _info to
+the name of the group type.
                  The user/groups data model also provided the user_group_type_member_fields and
 user_group_member_fields tables
 to define attributes for members of groups of a specific type and
 for members of a specific group, respectively. The user_group_member_field_map table stored
@@ -218,16 +219,16 @@
 be more extensible. In OpenACS 3.x, many applications extended the
 core data models by directly adding more columns, in order to
 provide convenient access to new information. This resulted in core
-data tables that were too "fat", containing a hodge podge of
-unrelated information that should have been normalized away. The
+data tables that were too "fat", containing a hodge podge
+of unrelated information that should have been normalized away. The
 canonical example of this is the explosion of the users table in OpenACS 3.x. In addition to
 being sloppy technically, these fat tables have a couple of other
 problems:
                    
 
                  • They degrade performance.
                  • Denormalization can make it hard to maintain consistency
 constraints on the data.
                    • 
 
                  Object subtypes provide a way to factor the data model while
 still keeping track of the fact that each member of a subtype (i.e.
-for each row in the subtype's table), is also a member of the
+for each row in the subtype's table), is also a member of the
 parent type (i.e. there is a corresponding row in the parent type
 table). Therefore, applications an use this mechanism without
 worrying about this bookkeeping themselves, and we avoid having
@@ -247,18 +248,20 @@
 attributes for catalog products, and the ec_custom_product_field_values table stores
 values for those attributes.
                13. In the Photo DB data model, the ph_custom_photo_fields table defines
 attributes for the photographs owned by a specific user, and tables
-named according to the convention "ph_user_<user_id>_custom_info" are
-used to store values for those attributes.
                  14. 
+named according to the convention "ph_user_<user_id>_custom_info"
+are used to store values for those attributes.
                  
 
              In addition, there are some instances where we are not using
 this model but should, e.g.
 the users_preferences table,
 which stores preferences for registered users in columns such as
 prefer_text_only_p and
-dont_spam_me_p. The "standard"
-way for an OpenACS 3.x-based application to add to the list of user
-preferences is to add a column to the users_preferences table (exactly the kind
-of data model change that has historically complicated the process
-of upgrading to a more recent OpenACS version).
              The Objet Model generalizes the scheme used in the old OpenACS
+dont_spam_me_p. The
+"standard" way for an OpenACS 3.x-based application to
+add to the list of user preferences is to add a column to the
+users_preferences table
+(exactly the kind of data model change that has historically
+complicated the process of upgrading to a more recent OpenACS
+version).
              The Objet Model generalizes the scheme used in the old OpenACS
 3.x user/groups system. It defines a table called acs_attributes that record what attributes
 belong to which object types, and how the attributes are stored. As
 before, attributes can either be stored in helper tables, or in a
@@ -294,25 +297,25 @@
 with extra attributes that store constraints on the relation, and
 the types of objects the relation actually maps. In turn, each
 instance of a relation type is an object that represents a single
-fact of the form "the object t of type T is related to the object r
-of type R." That is, each instance of a relation type is
-essentially just a pair of objects.
              Relation types generalize mapping tables. For example, the 3.x
+fact of the form "the object t of type T is related to the
+object r of type R." That is, each instance of a relation type
+is essentially just a pair of objects.
              Relation types generalize mapping tables. For example, the 3.x
 user/groups data model can be largely duplicated using a single
-relation type describing the "group membership" relation. Group
-types would then be subtypes of this membership relation type.
-Group type attributes would be attached to the relation type
+relation type describing the "group membership" relation.
+Group types would then be subtypes of this membership relation
+type. Group type attributes would be attached to the relation type
 itself. Group member attributes would be attached to instances of
 the membership relation. Finally, the mapping table would be
 replaced by a central skinny table that the relation type system
 defines.
              Relation types should be used when you want to be able to attach
-data to the "fact" that object X and object Y are related to each
-other. On the face of it, they seem like a redundant mechanism
-however, since one could easily create a mapping table to do the
-same thing. The advantage of registering this table as a relation
-type is that in principle the OpenACS 4 object system could use the
-meta data in the types table to do useful things in a generic way
-on all relation types. But this mechanism doesn't really exist
-yet.
              Relation types are a somewhat abstract idea. To get a better
+data to the "fact" that object X and object Y are related
+to each other. On the face of it, they seem like a redundant
+mechanism however, since one could easily create a mapping table to
+do the same thing. The advantage of registering this table as a
+relation type is that in principle the OpenACS 4 object system
+could use the meta data in the types table to do useful things in a
+generic way on all relation types. But this mechanism doesn't
+really exist yet.
              Relation types are a somewhat abstract idea. To get a better
 feel for them, you should just skip to the data
 model.
              
 
              
@@ -325,19 +328,20 @@
 metadata:
              
 
              
 Why not Object Databases?
              The presence of a framework for subtyping and inheritance always
-brings up the question of why we don't just use an object database.
-The main reason is that all of the major object database vendors
-ship products that are effectively tied to some set of object
-oriented programming languages. Their idea is to provide tight
-language-level integration to lower the "impedance mismatch"
-between the database and the language. Therefore, database objects
-and types are generally directly modeled on language level objects
-and types. Of course, this makes it nearly impossible to interact
-with the database from a language that does not have this tight
-coupling, and it limits the data models that we can write to ideas
-that are expressible in the host language. In particular, we lose
-many of the best features of the relational database model. This is
-a disaster from an ease of use standpoint.
              The "Object relational" systems provide an interesting
+brings up the question of why we don't just use an object
+database. The main reason is that all of the major object database
+vendors ship products that are effectively tied to some set of
+object oriented programming languages. Their idea is to provide
+tight language-level integration to lower the "impedance
+mismatch" between the database and the language. Therefore,
+database objects and types are generally directly modeled on
+language level objects and types. Of course, this makes it nearly
+impossible to interact with the database from a language that does
+not have this tight coupling, and it limits the data models that we
+can write to ideas that are expressible in the host language. In
+particular, we lose many of the best features of the relational
+database model. This is a disaster from an ease of use
+standpoint.
              The "Object relational" systems provide an interesting
 alternative. Here, some notion of subtyping is embedded into an
 existing SQL or SQL-like database engine. Examples of systems like
 this include the new Informix, PostgreSQL 7, and Oracle has
@@ -358,7 +362,7 @@
 object oriented features we need most.
              In the context of OpenACS 4, this means using the object model
 to make our data models more flexible, so that new modules can
 easily gain access to generic features. However, while the API
-itself doesn't enforce the idea that applications only use the
+itself doesn't enforce the idea that applications only use the
 object model for metadata, it is also the case that the data model
 is not designed to scale to large type hierarchies. In the more
 limited domain of the metadata model, this is acceptable since the
@@ -404,21 +408,21 @@
 The key things to note about this table are:
                
 
              • For every type, we store metadata for how to display this type
 in certain contexts (pretty_name and pretty_plural).
              • If the type is a subtype, then its parent type is stored in the
-column supertype.
              • We support a notion of "abstract" types that contain no
-instances (as of 9/2000 this is not actually used). These types
+column supertype.
              • We support a notion of "abstract" types that contain
+no instances (as of 9/2000 this is not actually used). These types
 exist only to be subtyped. An example might be a type representing
-"shapes" that contains common characteristics of all shapes, but
-which is only used to create subtypes that represent real, concrete
-shapes like circles, squares, and so on.
              • Every type defines a table in which one can find one row for
+"shapes" that contains common characteristics of all
+shapes, but which is only used to create subtypes that represent
+real, concrete shapes like circles, squares, and so on.
              • Every type defines a table in which one can find one row for
 every instance of this type (table_name, id_column).
              • 
 type_extension_table is for
 naming a table that stores extra generic attributes.
                • 
 
              The second table we use to describe types is acs_attributes. Each row in this table
 represents a single attribute on a specific object type (e.g. the
-"password" attribute of the "user" type). Again, here is an
-abbreviated version of what this table looks like. The actual table
-used in the implementation is somewhat different and is discussed
-in a separate document.
              create table acs_attributes (
+"password" attribute of the "user" type).
+Again, here is an abbreviated version of what this table looks
+like. The actual table used in the implementation is somewhat
+different and is discussed in a separate document.
              create table acs_attributes (
         attribute_id    integer not null primary key
         object_type     not null references acs_object_types (object_type),
         attribute_name  varchar(100) not null,
@@ -439,16 +443,17 @@
 (pretty_name, sort_order).
            2. The data_type column stores
 type information on this attribute. This is not the SQL type of the
 attribute; it is just a human readable name for the type of data we
-think the attribute holds (e.g. "String", or "Money"). This might
-be used later to generate a user interface.
            3. The sort_order column stores
-information about how to sort the attribute values.
            4. Attributes can either be stored explicitly in a table ("type
-specific storage") or in a skinny table ("generic storage"). In
-most cases, an attribute maps directly to a column in the table
-identified by the table_name of
-the corresponding object type, although, as mentioned above, we
-sometimes store attribute values as key-value pairs in a "skinny"
-table. However, when you ask the question "What are the attributes
-of this type of object?", you don't really care about how the
+think the attribute holds (e.g. "String", or
+"Money"). This might be used later to generate a user
+interface.
            5. The sort_order column stores
+information about how to sort the attribute values.
            6. Attributes can either be stored explicitly in a table
+("type specific storage") or in a skinny table
+("generic storage"). In most cases, an attribute maps
+directly to a column in the table identified by the table_name of the corresponding object
+type, although, as mentioned above, we sometimes store attribute
+values as key-value pairs in a "skinny" table. However,
+when you ask the question "What are the attributes of this
+type of object?", you don't really care about how the
 values for each attribute are stored (in a column or as key-value
 pairs); you expect to receive the complete list of all
 attributes.
            7. The max_n_values and
@@ -463,8 +468,8 @@
 used to generalize the 3.x notion of group member fields. These were fields
 that a developer could store on each member of a group, but which
 were contextualized to the membership relation. That is, they were
-really "attached" to the fact that a user was a member of a
-particular group, and not really attached to the user. This is a
+really "attached" to the fact that a user was a member of
+a particular group, and not really attached to the user. This is a
 subtle but important distinction, because it allowed the 3.x system
 to store multiple sets of attributes on a given user, one set for
 each group membership relation in which they participated.
              In OpenACS 4, this sort of data can be stored as a relationship
@@ -490,8 +495,8 @@
 each instance of this relation type will be a pair of objects of
 the appropriate types.
            8. The role columns store human
 readable names for the roles played by each object in the relation
-(e.g. "employee" and "employer"). Each role must appear in the
-acs_rel_roles.
            9. The min_n_rels_one column,
+(e.g. "employee" and "employer"). Each role
+must appear in the acs_rel_roles.
            10. The min_n_rels_one column,
 and its three friends allow the programmer to specify constraints
 on how many objects any given object can be related to on either
 side of the relation.
              11. 
@@ -509,10 +514,10 @@
 
            
 
            
 Operational-level Data Model
            The operational level data model centers around the acs_objects table. This table contains a
-single row for every instance of the type acs_object. The table contains the object's
-unique identifier, a reference to its type, security information,
-and generic auditing information. Here is what the table looks
-like:
            create table acs_objects (
+single row for every instance of the type acs_object. The table contains the
+object's unique identifier, a reference to its type, security
+information, and generic auditing information. Here is what the
+table looks like:
            create table acs_objects (
         object_id               integer not null,
         object_type             not null
                                 references acs_object_types (object_type),
@@ -532,9 +537,10 @@
 stores the context hierarchy.
            Other tables in the core data model store additional information
 related to objects. The table acs_attribute_values and acs_static_attr_values are used to store
 attribute values that are not stored in a helper table associated
-with the object's type. The former is used for instance attributes
-while the latter is used for class-wide "static" values. These
-tables have the same basic form, so we'll only show the first:
            create table acs_attribute_values (
+with the object's type. The former is used for instance
+attributes while the latter is used for class-wide
+"static" values. These tables have the same basic form,
+so we'll only show the first:
            create table acs_attribute_values (
         object_id       not null
                         references acs_objects (object_id) on delete cascade,
         attribute_id    not null
@@ -565,11 +571,11 @@
 relation type to which this object belongs.
          2. The next two object IDs are the IDs of the objects being
 mapped.
            3. 
 
          All this table does is store one row for every pair of objects
-that we'd like to attach with a relation. Any additional attributes
-that we'd like to attach to this pair of objects is specified in
-the attributes of the relation type, and could be stored in any
-number of places. As in the 3.x user/groups system, these places
-include helper tables or generic skinny tables.
          This table, along with acs_attributes and acs_attribute_values generalize the old
+that we'd like to attach with a relation. Any additional
+attributes that we'd like to attach to this pair of objects is
+specified in the attributes of the relation type, and could be
+stored in any number of places. As in the 3.x user/groups system,
+these places include helper tables or generic skinny tables.
          This table, along with acs_attributes and acs_attribute_values generalize the old
 user/group tables user_group_map, user_group_member_fields_map and
 user_group_member_fields.
        @@ -581,16 +587,16 @@ system. Services can use this table along with the metadata in stored in the knowledge level data model to create, manage, query and manipulate objects in a uniform manner. The acs_rels table has an analogous role in -storing information on relations.

        These are all the tables that we'll discuss in this document. -The rest of the Kernel data model is described in the documents for -subsites, the permissions system and for the groups +storing information on relations.

        These are all the tables that we'll discuss in this +document. The rest of the Kernel data model is described in the +documents for subsites, the permissions system and for the groups system.

        Some examples of how these tables are used in the system can be found in the discussion of the API, which comes next.

        -API

        Now we'll examine each piece of the API in detail. Bear in mind -that the Object Model API is defined primarily through PL/SQL +API

        Now we'll examine each piece of the API in detail. Bear in +mind that the Object Model API is defined primarily through PL/SQL packages.

        Object Types and Attributes

        The object system provides an API for creating new object types @@ -713,8 +719,8 @@ familiar with the data model at a lower level.

        The function acs_object.new() makes a new object for you. The function acs_object.del() deletes an object. As before, this is an abbreviated interface with all the long type -specs removed. See the data model or developer's guide for the full -interface.

         function new (
+specs removed. See the data model or developer's guide for the
+full interface.
         function new (
   object_id     in acs_objects.object_id%TYPE default null,
   object_type   in acs_objects.object_type%TYPE
                            default 'acs_object',
@@ -731,10 +737,10 @@
  );
 
        Next, we define some generic functions to manipulate attributes.
 Again, these interfaces are useful to an extent, but for large
-scale queries, it's likely that developers would have to query the
-data model directly, and then encapsulate their queries in
+scale queries, it's likely that developers would have to query
+the data model directly, and then encapsulate their queries in
 procedures.
        For names, the default_name
-function is used if you don't want to define your own name
+function is used if you don't want to define your own name
 function.
         function name (
   object_id     in acs_objects.object_id%TYPE
  ) return varchar;
@@ -789,7 +795,7 @@
     return v_ticket_id;
   end new_ticket;
 
        This function will typically be defined in the context of a
-PL/SQL package, but we've left it stand-alone here for
+PL/SQL package, but we've left it stand-alone here for
 simplicity.
        To summarize: in order to take advantage of OpenACS 4 services,
 a new application need only do three things:
          
 
        • Define a data model to describe application objects. This can
@@ -814,9 +820,9 @@
 relation types, and acs_rel for
 relating objects.
          These two procedures just insert and remove roles from the
 acs_rel_roles table. This table
-stores the legal relationship "roles" that can be used when
-creating relation types. Examples of roles are, say, "member", or
-"employer".
           procedure create_role (
+stores the legal relationship "roles" that can be used
+when creating relation types. Examples of roles are, say,
+"member", or "employer".
           procedure create_role (
     role        in acs_rel_roles.role%TYPE
   );
 
@@ -888,9 +894,9 @@
    type_extension_table => 'group_types',
    name_method => 'acs_group.name'
  );
-
          In this example, we've made groups a subtype of acs_object to make the code simpler. The
-actual data model is somewhat different. Also, we've assumed that
-there is a helper table called groups to store information on groups, and
+
          In this example, we've made groups a subtype of acs_object to make the code simpler. The
+actual data model is somewhat different. Also, we've assumed
+that there is a helper table called groups to store information on groups, and
 that there is a helper table called group_types that has been defined to store
 extra attributes on groups.
          Now, assuming we have another object type called person to represent objects that can be
 group members, we define the following relationship type for group
@@ -953,12 +959,12 @@

        -Summary and Discussion

        The Object Model's API and data model provides a small set of -simple procedures that allow applications to create object types, -object instances, and object relations. Most of the data model is -straightforward; the relation type mechanism is a bit more complex, -but in return it provides functionality on par with the old -user/groups system in a more general way.

        +Summary and Discussion

        The Object Model's API and data model provides a small set +of simple procedures that allow applications to create object +types, object instances, and object relations. Most of the data +model is straightforward; the relation type mechanism is a bit more +complex, but in return it provides functionality on par with the +old user/groups system in a more general way.

        Index: openacs-4/packages/acs-core-docs/www/object-system-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-design.html,v diff -u -N -r1.34.2.1 -r1.34.2.2 --- openacs-4/packages/acs-core-docs/www/object-system-design.html 9 Jun 2016 08:44:50 -0000 1.34.2.1 +++ openacs-4/packages/acs-core-docs/www/object-system-design.html 23 Jun 2016 08:32:45 -0000 1.34.2.2 @@ -20,7 +20,7 @@ data model that keeps track of the application objects that we wish to manage, and serves as a primary store of metadata. By metadata, we mean data stored on behalf of an application -outside of the application's data model in order to enable +outside of the application's data model in order to enable certain central services. The OpenACS 4 Object Model (or object system) manages several different kinds of data and metadata to allow us to provide general services to applications:

        • Object Identification

          Every application object is given a unique identifier in the system. This @@ -82,7 +82,7 @@ notion of "scoping" was introduced into the core data model.

          "Scope" is a term best explained by example. Consider some hypothetical rows in the address_book table:

          ...scopeuser_idgroup_id...
          ...user123 ...
          ...group 456...
          ...public ...

          The first row represents an entry in User 123's personal address book, the second row represents an entry in User Group 456's shared address -book, and the third row represents an entry in the site's public address +book, and the third row represents an entry in the site's public address book.

          In this way, the scoping columns identify the security context in which a given object belongs, where each context is either a person or a group of people or the general public (itself a group @@ -94,11 +94,11 @@ forum message would probably list a forum topic as its context, and a forum topic might list a subsite as its context. Thus, contexts make it easier to break the site up into security domains according to its natural -structure. An object's context is stored in the context_id -column of the acs_objects table.

          We use an object's context to provide a default answer to questions +structure. An object's context is stored in the context_id +column of the acs_objects table.

          We use an object's context to provide a default answer to questions regarding access control. Whenever we ask a question of the form "can user X perform action Y on object Z", the OpenACS security model will defer -to an object's context if there is no information about user X's +to an object's context if there is no information about user X's permission to perform action Y on object Z.

          The context system forms the basis for the rest of the OpenACS access control system, which is described in in two separate documents: one for the permissions system and another for the party groups system. The context system @@ -138,7 +138,7 @@ these fat tables have a couple of other problems:

          • They degrade performance.

          • Denormalization can make it hard to maintain consistency constraints on the data.

          Object subtypes provide a way to factor the data model while still keeping track of the fact that each member of a subtype (i.e. for each row in the -subtype's table), is also a member of the parent type (i.e. there is a +subtype's table), is also a member of the parent type (i.e. there is a corresponding row in the parent type table). Therefore, applications an use this mechanism without worrying about this bookkeeping themselves, and we avoid having applications pollute the core data model with their specific @@ -202,12 +202,12 @@ easily create a mapping table to do the same thing. The advantage of registering this table as a relation type is that in principle the OpenACS 4 object system could use the meta data in the types table to do useful things -in a generic way on all relation types. But this mechanism doesn't really +in a generic way on all relation types. But this mechanism doesn't really exist yet.

          Relation types are a somewhat abstract idea. To get a better feel for them, you should just skip to the data model.

        Summary and Design Considerations

        The OpenACS 4 Object Model is designed to generalize and unify the following mechanisms that are repeatedly implemented in OpenACS-based systems to manage generic and application specific metadata:

        Why not Object Databases?

        The presence of a framework for subtyping and inheritance always brings up -the question of why we don't just use an object database. The main reason +the question of why we don't just use an object database. The main reason is that all of the major object database vendors ship products that are effectively tied to some set of object oriented programming languages. Their idea is to provide tight language-level integration to lower the @@ -235,7 +235,7 @@ the relational data model while gaining the object oriented features we need most.

        In the context of OpenACS 4, this means using the object model to make our data models more flexible, so that new modules can easily gain access to -generic features. However, while the API itself doesn't enforce the idea +generic features. However, while the API itself doesn't enforce the idea that applications only use the object model for metadata, it is also the case that the data model is not designed to scale to large type hierarchies. In the more limited domain of the metadata model, this is acceptable since the @@ -319,7 +319,7 @@ by the table_name of the corresponding object type, although, as mentioned above, we sometimes store attribute values as key-value pairs in a "skinny" table. However, when you ask the question "What are -the attributes of this type of object?", you don't really care about +the attributes of this type of object?", you don't really care about how the values for each attribute are stored (in a column or as key-value pairs); you expect to receive the complete list of all attributes.

      • The max_n_values and min_n_values columns encode information about the number of values an attribute may hold. @@ -370,7 +370,7 @@ model, which is discussed next.

        • Operational-level Data Model

        The operational level data model centers around the acs_objects table. This table contains a single row for every instance of the type acs_object. The table contains the -object's unique identifier, a reference to its type, security +object's unique identifier, a reference to its type, security information, and generic auditing information. Here is what the table looks like:

         
@@ -395,10 +395,10 @@
 acs_object_context_index that stores the context hierarchy.
        Other tables in the core data model store additional information related
 to objects. The table acs_attribute_values and
 acs_static_attr_values are used to store attribute values that
-are not stored in a helper table associated with the object's type. The
+are not stored in a helper table associated with the object's type. The
 former is used for instance attributes while the latter is used for
 class-wide "static" values. These tables have the same basic form,
-so we'll only show the first:
        +so we'll only show the first:
         
 create table acs_attribute_values (
         object_id       not null
@@ -431,8 +431,8 @@
 type. We do this so we can store all the mapping tables in this one
 table.
      • rel_type is the ID of the relation type to which this object
 belongs.
      • The next two object IDs are the IDs of the objects being mapped.

        • All this table does is store one row for every pair of objects that -we'd like to attach with a relation. Any additional attributes that -we'd like to attach to this pair of objects is specified in the +we'd like to attach with a relation. Any additional attributes that +we'd like to attach to this pair of objects is specified in the attributes of the relation type, and could be stored in any number of places. As in the 3.x user/groups system, these places include helper tables or generic skinny tables.

        This table, along with acs_attributes and @@ -444,9 +444,9 @@ the system. Services can use this table along with the metadata in stored in the knowledge level data model to create, manage, query and manipulate objects in a uniform manner. The acs_rels table has an analogous -role in storing information on relations.

        These are all the tables that we'll discuss in this document. The rest +role in storing information on relations.

        These are all the tables that we'll discuss in this document. The rest of the Kernel data model is described in the documents for subsites, the permissions system and for the groups system.

        Some examples of how these tables are used in the system can be found in -the discussion of the API, which comes next.

        API

        Now we'll examine each piece of the API in detail. Bear in mind that +the discussion of the API, which comes next.

        API

        Now we'll examine each piece of the API in detail. Bear in mind that the Object Model API is defined primarily through PL/SQL packages.

        Object Types and Attributes

        The object system provides an API for creating new object types and then attaching attributes to them. The procedures create_type and drop_type are used to create and delete type definitions.

        The two calls show up in the package acs_object_type.

        @@ -578,7 +578,7 @@
 with the data model at a lower level.
        The function acs_object.new() makes a new object for you. The
 function acs_object.del() deletes an object. As before, this
 is an abbreviated interface with all the long type specs removed. See the
-data model or developer's guide for the full interface.
        +data model or developer's guide for the full interface.
         
  function new (
   object_id     in acs_objects.object_id%TYPE default null,
@@ -599,8 +599,8 @@
 
 
        Next, we define some generic functions to manipulate attributes. Again,
 these interfaces are useful to an extent, but for large scale queries,
-it's likely that developers would have to query the data model directly,
-and then encapsulate their queries in procedures.
        For names, the default_name function is used if you don't
+it's likely that developers would have to query the data model directly,
+and then encapsulate their queries in procedures.
        For names, the default_name function is used if you don't
 want to define your own name function.
         
  function name (
@@ -667,7 +667,7 @@
 
 
 
        This function will typically be defined in the context of a PL/SQL
-package, but we've left it stand-alone here for simplicity.
        To summarize: in order to take advantage of OpenACS 4 services, a new
+package, but we've left it stand-alone here for simplicity.
        To summarize: in order to take advantage of OpenACS 4 services, a new
 application need only do three things:
        • Define a data model to describe application objects. This can just be a
 normal SQL table.
        • Create an object type, using code like in the example from the previous
 section.
        • Make sure application objects are created using
@@ -776,9 +776,9 @@
  );
 
 
-
        In this example, we've made groups a subtype of
+

        In this example, we've made groups a subtype of acs_object to make the code simpler. The actual data model is -somewhat different. Also, we've assumed that there is a helper table +somewhat different. Also, we've assumed that there is a helper table called groups to store information on groups, and that there is a helper table called group_types that has been defined to store extra attributes on groups.

        Now, assuming we have another object type called person to @@ -851,7 +851,7 @@ end; -

        Summary and Discussion

        The Object Model's API and data model provides a small set of simple +

        Summary and Discussion

        The Object Model's API and data model provides a small set of simple procedures that allow applications to create object types, object instances, and object relations. Most of the data model is straightforward; the relation type mechanism is a bit more complex, but in return it provides functionality Index: openacs-4/packages/acs-core-docs/www/object-system-requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-requirements.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-core-docs/www/object-system-requirements.adp 9 Jun 2016 08:44:50 -0000 1.1.2.2 +++ openacs-4/packages/acs-core-docs/www/object-system-requirements.adp 23 Jun 2016 08:32:45 -0000 1.1.2.3 @@ -25,23 +25,23 @@ include:

        • Bboard messages

        • A user home page

        • A ticket in the Ticket Tracker

        • A photograph in the PhotoDB

        In the past, developers had to use ad-hoc and inconsistent -schemes to interface to the various "general" services mentioned -above. Since each service used its own scheme for storing its -metadata and mapping this data to application objects, we could not -implement any kind of centralized management system or consistent -administrative pages for all the services. Consequently, a large -amount of duplicate code appeared throughout the system for dealing -with these services.

        Unifying and "normalizing" these interfaces, to minimize the -amount of code repetition in applications, is a primary goal of -OpenACS 4. Thus the Object Model (OM, also referred to later as the -object system) is concerned primarily with the storage and -management of metadata, on -any object within a given instance of OpenACS 4. The term -"metadata" refers to any extra data the OM stores on behalf of the -application - outside of the application's data model - in order to -enable certain generic services. The term "object" refers to any -entity being represented within the OpenACS, and typically -corresponds to a single row within the relational database.

        +schemes to interface to the various "general" services +mentioned above. Since each service used its own scheme for storing +its metadata and mapping this data to application objects, we could +not implement any kind of centralized management system or +consistent administrative pages for all the services. Consequently, +a large amount of duplicate code appeared throughout the system for +dealing with these services.

        Unifying and "normalizing" these interfaces, to +minimize the amount of code repetition in applications, is a +primary goal of OpenACS 4. Thus the Object Model (OM, also referred +to later as the object system) is concerned primarily with the +storage and management of metadata, on any object within a given +instance of OpenACS 4. The term "metadata" refers to any +extra data the OM stores on behalf of the application - outside of +the application's data model - in order to enable certain +generic services. The term "object" refers to any entity +being represented within the OpenACS, and typically corresponds to +a single row within the relational database.

        Vision Statement

        The OpenACS 4 Object Model must address five high-level @@ -57,15 +57,15 @@ to identify data associated with a single membership relation.

        Also in OpenACS 3.x, many utility modules exist that do nothing more than attach some extra attributes to existing application data. For example, general comments maintains a mapping table that -maps application "page" data (static or dynamic) to one or more -user comments on the page, by constructing a unique identifier for -each page. This identifier is usually a combination of the table in -which the data is stored, and the value of the primary key value -for the particular page. This idiom is referred to as the -"(on_which_table + on_what_id)" method for identifying application -data. General comments stores its map from pages to comments using -a "(on_which_table + on_what_id)" key, plus the id of the comment -itself.

        All of these composite key constructions are implicit object +maps application "page" data (static or dynamic) to one +or more user comments on the page, by constructing a unique +identifier for each page. This identifier is usually a combination +of the table in which the data is stored, and the value of the +primary key value for the particular page. This idiom is referred +to as the "(on_which_table + on_what_id)" method for +identifying application data. General comments stores its map from +pages to comments using a "(on_which_table + on_what_id)" +key, plus the id of the comment itself.

        All of these composite key constructions are implicit object identifiers: they build a unique ID out of other pieces of the data model. The problem is that their definition and use is ad-hoc and inconsistent. This makes the construction of generic @@ -75,9 +75,9 @@ Control

        Access control should be as transparent as possible to the application developer. Until the implementation of the general permissions system, every OpenACS application had to manage access -control to its data separately. Later on, a notion of "scoping" was -introduced into the core data model.

        "Scope" is a term best explained by example. Consider some -hypothetical rows in the address_book table:

        +control to its data separately. Later on, a notion of +"scoping" was introduced into the core data model.

        "Scope" is a term best explained by example. Consider +some hypothetical rows in the address_book table:

        @@ -91,10 +91,10 @@ -
        ...public...

        The first row represents an entry in User 123's personal address -book, the second row represents an entry in User Group 456's shared -address book, and the third row represents an entry in the site's -public address book.

        In this way, the scoping columns identify the security context +

        The first row represents an entry in User 123's personal +address book, the second row represents an entry in User Group +456's shared address book, and the third row represents an +entry in the site's public address book.

        In this way, the scoping columns identify the security context in which a given object belongs, where each context is either a person or a group of people or the general public (itself a group of people).

        The problem with this scheme is that we are limited to using only users and groups as scopes for access control, limiting @@ -111,9 +111,9 @@ extended to support an increasing number of modules. The users table is the best case in point: it became full of columns that exist for various special -applications (e.g. user portraits), but that aren't really related -to each other in any way except that they store information on -users, i.e. the table became grossly denormalized. Normalizing +applications (e.g. user portraits), but that aren't really +related to each other in any way except that they store information +on users, i.e. the table became grossly denormalized. Normalizing (breaking-down) this table into several pieces, each of which is specific to a particular application, would improve maintainability greatly. Furthermore, the ability to allow applications or users to @@ -128,26 +128,26 @@ providing a generic API for object creation that automatically keeps track of the location and relationships between data.

        Design Note: While -this doesn't really belong in a requirements document, the fact +this doesn't really belong in a requirements document, the fact that we are constrained to using relational databases means that certain constraints on the overall design of the object data model exist, which you can read about in Summary and Design Considerations.

        Modifiable Data Models

        Another recurring applications problem is how to store a modifiable data model, or how to store information that may change extensively between releases or in different client installations. -Furthermore, we want to avoid changes to an application's database -queries in the face of any custom extensions, since such changes -are difficult or dangerous to make at runtime, and can make +Furthermore, we want to avoid changes to an application's +database queries in the face of any custom extensions, since such +changes are difficult or dangerous to make at runtime, and can make updating the system difficult. Some example applications in OpenACS 3.x with modifiable data models include:

        • User/groups: developers and users can attach custom data to group types, groups, and members of groups.

        • In the Ecommerce data model, the ec_custom_product_fields table defines attributes for catalog products, and the ec_custom_product_field_values table stores values for those attributes.

        • In the PhotoDB data model, the ph_custom_photo_fields table defines attributes for the photographs owned by a specific user, and tables -named according to the convention "ph_user_<user_id>_custom_info" are -used to store values for those attributes.

          • +named according to the convention "ph_user_<user_id>_custom_info" +are used to store values for those attributes.

        Thus the Object Model must provide a general mechanism for applications and developers to modify or extend data models, without requiring changes to the SQL schema of the system. This @@ -236,7 +236,7 @@ Uniqueness

        The object ID should be unique among all the IDs in the entire OpenACS system in which the object lives.

        10.20 Useful as a Reference

        Applications should be able to use the unique object ID as a -reference, with which they can fetch any or all of the object's +reference, with which they can fetch any or all of the object's attributes.

        10.30 Storable

        Object IDs should be storable in tables. e.g. you should be able to use them to implement mapping tables between objects, to represent relationships.

        10.40 Moveable

        Objects should be mobile between databases. That is, information @@ -318,11 +318,11 @@ maintaining application specific integrity rules.

        50.0 Object Contexts
        -

        In OpenACS 3.x, there was a notion of "scope" for application -objects. An object could be belong to one of three scopes: public, -group or user. This provided a crude way to associate objects with -particular scopes in the system, but it was awkward to use and -limited in flexibility.

        The OpenACS 4 Object Model provides a generalized notion of +

        In OpenACS 3.x, there was a notion of "scope" for +application objects. An object could be belong to one of three +scopes: public, group or user. This provided a crude way to +associate objects with particular scopes in the system, but it was +awkward to use and limited in flexibility.

        The OpenACS 4 Object Model provides a generalized notion of scope that allows developers to represent a hierarchy of object contexts. These contexts are used as the basis for the permissions system. In general, if an @@ -332,21 +332,21 @@ separate documents.

        The context data model should provide the following facilities:

        50.10 Unique ID

        Every context should have a unique ID in the system.

        50.20 Tree Structure

        The data model should support a tree structured organization of -contexts. That is, contexts can be logically "contained" within -other contexts (i.e. contexts have parents) and contexts can +contexts. That is, contexts can be logically "contained" +within other contexts (i.e. contexts have parents) and contexts can contain other contexts (i.e. contexts can have children).

        50.30 Data Model Constraints

        All objects must have a context ID. This ID must refer to an existing context or be NULL. The meaning of a NULL context is determined by the implementation.

        Note:

        The current system interprets the NULL context as meaning the -default "site-wide" context in some sense. I wanted to note this -fact for others, but there is no need to make this a requirement of -the system. I think it would be reasonable to have a NULL context -be an error (psu 8/24/2000).

        +default "site-wide" context in some sense. I wanted to +note this fact for others, but there is no need to make this a +requirement of the system. I think it would be reasonable to have a +NULL context be an error (psu 8/24/2000).

        55.0 Object Relations

        The data model should include a notion of pair-wise relations between objects. Relations should be able to record simple facts of -the form "object X is related to object Y by relationship R," and -also be able to attach attributes to these facts.

        +the form "object X is related to object Y by relationship +R," and also be able to attach attributes to these facts.

        @@ -381,8 +381,8 @@ This API is subject to the constraints laid out in the data model.

        80.10.10

        However, the programmer should also be able to specify that all the subtypes and instances of those subtypes be destroyed before -destroying the object type. This is similar to a "delete cascade" -constraint in SQL.

        +destroying the object type. This is similar to a "delete +cascade" constraint in SQL.

        90.0 Object Instance Creation and Destruction

        The system must provide API calls to manage the creation and @@ -396,8 +396,8 @@ Instance

        The OM should provide an API call for object deletion. Objects can be deleted only when no other objects in the system refer to them. Since it might not be practical to provide a mechanism like -"delete cascade" here in a reliable way, providing such a facility -in the system is optional.

        +"delete cascade" here in a reliable way, providing such a +facility in the system is optional.

        94.0 Object Relation Creation and Destruction

        The system must provide API calls to manage the creation and destruction of object relations.

        94.10 Create an @@ -425,9 +425,10 @@ in one way or another. Since it is important that the largest audience of developers possible adopts and uses the OM, it must be easy to incorporate into applications, and it must not impose undue -requirements on an application's data model. In other words, it -should be easy to "hook into" the object model, and that ability -should not have a major impact on the application data model.

        +requirements on an application's data model. In other words, it +should be easy to "hook into" the object model, and that +ability should not have a major impact on the application data +model.

        Note: Is the API the only way to obtain values? How does this integrate with application level SQL queries?

        Index: openacs-4/packages/acs-core-docs/www/object-system-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-requirements.html,v diff -u -N -r1.34.2.1 -r1.34.2.2 --- openacs-4/packages/acs-core-docs/www/object-system-requirements.html 9 Jun 2016 08:44:50 -0000 1.34.2.1 +++ openacs-4/packages/acs-core-docs/www/object-system-requirements.html 23 Jun 2016 08:32:45 -0000 1.34.2.2 @@ -18,7 +18,7 @@ concerned primarily with the storage and management of metadata, on any object within a given instance of OpenACS 4. The term "metadata" refers to any extra data the OM stores on behalf of the application - outside -of the application's data model - in order to enable certain generic +of the application's data model - in order to enable certain generic services. The term "object" refers to any entity being represented within the OpenACS, and typically corresponds to a single row within the relational database.

        Vision Statement

        The OpenACS 4 Object Model must address five high-level requirements that @@ -52,7 +52,7 @@ model.

        "Scope" is a term best explained by example. Consider some hypothetical rows in the address_book table:

        ...scopeuser_idgroup_id...
        ...user123 ...
        ...group 456...
        ...public ...

        The first row represents an entry in User 123's personal address book, the second row represents an entry in User Group 456's shared address -book, and the third row represents an entry in the site's public address +book, and the third row represents an entry in the site's public address book.

        In this way, the scoping columns identify the security context in which a given object belongs, where each context is either a person or a group of people or the general public (itself a group @@ -68,7 +68,7 @@ tables in the system became bloated as they were extended to support an increasing number of modules. The users table is the best case in point: it became full of columns that exist for various special -applications (e.g. user portraits), but that aren't really related to +applications (e.g. user portraits), but that aren't really related to each other in any way except that they store information on users, i.e. the table became grossly denormalized. Normalizing (breaking-down) this table into several pieces, each of which is specific to a particular application, @@ -82,13 +82,13 @@ custom extensions to the existing data models, and the OM does the bookkeeping necessary to make this easier, providing a generic API for object creation that automatically keeps track of the location and relationships -between data.

        Design Note: While this doesn't really belong in a +between data.

        Design Note: While this doesn't really belong in a requirements document, the fact that we are constrained to using relational databases means that certain constraints on the overall design of the object data model exist, which you can read about in Summary and Design Considerations.

        Modifiable Data Models

        Another recurring applications problem is how to store a modifiable data model, or how to store information that may change extensively between releases or in different client installations. Furthermore, we want to avoid -changes to an application's database queries in the face of any custom +changes to an application's database queries in the face of any custom extensions, since such changes are difficult or dangerous to make at runtime, and can make updating the system difficult. Some example applications in OpenACS 3.x with modifiable data models include:

        • User/groups: developers and users can attach custom data to group types, @@ -150,7 +150,7 @@ system.

          The object identifiers should be subject to the following requirements:

          10.10 Uniqueness

          The object ID should be unique among all the IDs in the entire OpenACS system in which the object lives.

          10.20 Useful as a Reference

          Applications should be able to use the unique object ID as a reference, -with which they can fetch any or all of the object's attributes.

          10.30 Storable

          Object IDs should be storable in tables. e.g. you should be able to use +with which they can fetch any or all of the object's attributes.

          10.30 Storable

          Object IDs should be storable in tables. e.g. you should be able to use them to implement mapping tables between objects, to represent relationships.

          10.40 Moveable

          Objects should be mobile between databases. That is, information will often need to be moved between multiple servers (development, staging, and @@ -258,7 +258,7 @@ another. Since it is important that the largest audience of developers possible adopts and uses the OM, it must be easy to incorporate into applications, and it must not impose undue requirements on an -application's data model. In other words, it should be easy to "hook +application's data model. In other words, it should be easy to "hook into" the object model, and that ability should not have a major impact on the application data model.

          Note: Is the API the only way to obtain values? How does this integrate with application level SQL queries?

        Revision History

        -
        Document Revision #Action Taken, NotesWhen?By Whom?
        0.1Creation08/10/2000Bryan Quinn
        0.2Major re-write08/11/2000Pete Su
        0.3Draft completed after initial reviews08/22/2000Pete Su
        0.4Edited, updated to conform to requirements template, pending freeze08/23/2000Kai Wu
        Final edits before freeze08/24/2000Pete Su
        0.5Edited for consistency08/27/2000Kai Wu
        0.6Put Object ID stuff first, because it makes more sense08/28/2000Pete Su
        0.7Added requirement that knowledge-level objects must be moveable between Index: openacs-4/packages/acs-core-docs/www/objects.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/objects.adp,v diff -u -N -r1.1.2.11 -r1.1.2.12 --- openacs-4/packages/acs-core-docs/www/objects.adp 21 Jun 2016 07:44:36 -0000 1.1.2.11 +++ openacs-4/packages/acs-core-docs/www/objects.adp 23 Jun 2016 08:32:45 -0000 1.1.2.12 @@ -31,19 +31,20 @@ title varchar(255) not null, body varchar(1024) ) -

        We've omitted constraint names for the purpose of clarity.

        Thinking further ahead, we can imagine doing any of the +

        We've omitted constraint names for the purpose of +clarity.

        Thinking further ahead, we can imagine doing any of the following things with Notes as well:

        • Define access control policies on notes.

        • Attach user comments on notes.

        • Allow users to define custom fields to store on their notes.

        • Automatically generate input forms or output displays for -notes.

        • Allow other applications to use notes in ways we don't know of -yet.

          • +notes.

        • Allow other applications to use notes in ways we don't know +of yet.

        In OpenACS, the key to enabling these types of services on your application data is to take advantage of the Object System. The -first question, then, is "Just what are objects, and what do you -use them for anyway?". The short answer: objects are anything -represented in the application's data model that will need to be -managed by any central service in OpenACS, or that may be reusable -in the context of future applications. Every object in the system -is represented using a row in the acs_objects table. This table defines all +first question, then, is "Just what are objects, and what do +you use them for anyway?". The short answer: objects are +anything represented in the application's data model that will +need to be managed by any central service in OpenACS, or that may +be reusable in the context of future applications. Every object in +the system is represented using a row in the acs_objects table. This table defines all the standard attributes that are stored on every object, including its system-wide unique ID, object type, and some generic auditing columns.

        To make use of the object system, you as the application @@ -61,8 +62,9 @@

        -How to Use Objects

        Using ACS objects is straightforward: all that's required are a -few extra steps in the design of your application data model.

        In order to hook our Notes application into the object system, +How to Use Objects

        Using ACS objects is straightforward: all that's required +are a few extra steps in the design of your application data +model.

        In order to hook our Notes application into the object system, we make some calls to use our notes table as the basis for a new object type. Object types are analogous to classes in programming languages such as C++ and @@ -77,8 +79,9 @@ object types can inherit attributes from a parent type, so the type system forms a hierarchy. Unlike Java, Oracle does not support this inheritance transparently, so we have to make sure we add our own -bookkeeping code to keep everything consistent. Below you'll find -the code needed to describe a new object type called notes in your system.

        Fire up your text editor and open the ROOT/packages/notes/sql/oracle/notes-create.sql +bookkeeping code to keep everything consistent. Below you'll +find the code needed to describe a new object type called +notes in your system.

        Fire up your text editor and open the ROOT/packages/notes/sql/oracle/notes-create.sql (ROOT/packages/notes/sql/postgresql/notes-create.sql for the PG version) file created when we created the package. Then, do the following:

        @@ -104,13 +107,13 @@ This type is a subtype of the acs_object type, which means that we want to inherit all of the basic attributes of all ACS objects. As mentioned, it will take some work on our part to make this happen, -since Oracle can't do it automatically. In general, most basic +since Oracle can't do it automatically. In general, most basic applications will define types that are simple subtypes of acs_object.

        Add entries to the acs_attributes table to describe the data attributes of the new type. This data can eventually be used to do things like automatically generate user interfaces to manipulate the notes table, though that -functionality isn't yet available.

        +functionality isn't yet available.
         declare 
  attr_id acs_attributes.attribute_id%TYPE; 
 begin
@@ -190,9 +193,9 @@
 / 
 show errors 
 
        You might be wondering what all the extra parameters are to
-these calls, since we haven't mentioned them before. These
+these calls, since we haven't mentioned them before. These
 parameters are needed to fill out information that will be stored
-about the object that's not stored directly in the table you
+about the object that's not stored directly in the table you
 defined. The OpenACS Object System defines these attributes on the
 type acs_object since all
 objects should have these attributes. Internally, there are tables
@@ -205,9 +208,9 @@
 if no permissions are explicitly attached to the object, then the
 object inherits its permissions from the context. For example, if I
 had told you how to use the permissions system to
-specify that an object OBJ was "read only", then any other object
-that used OBJ as its context would also be "read only" by default.
-We'll talk about this more later.
        
+specify that an object OBJ was "read only", then any
+other object that used OBJ as its context would also be "read
+only" by default. We'll talk about this more later.

        Define a package body for type specific @@ -268,11 +271,12 @@ end note; / show errors; -

        That's pretty much it! As long as you use the note.new function to create notes, and the +

        That's pretty much it! As long as you use the note.new function to create notes, and the note.delete function to delete -them, you'll be assured that the relationship each note has with its corresponding +them, you'll be assured that the relationship each note has with its corresponding acs_object is preserved.

        The last thing to do is to make a file ROOT/packages/notes/sql/notes-drop.sql so -it's easy to drop the data model when, say, you're testing:

        +it's easy to drop the data model when, say, you're
+testing:
         begin 
   acs_object_type.drop_type ('note'); 
 end; 
@@ -296,7 +300,7 @@
 system.
        For example, for most applications, you will want to use objects
 to represent the data in your application that is user visible and
 thus requires access control. But other internal tables, views,
-mapping tables and so on probably don't need to be objects. As
+mapping tables and so on probably don't need to be objects. As
 before, this kind of design decision is mostly made on an
 application-by-application basis, but this is a good baseline from
 which to start.
        
@@ -315,14 +319,14 @@
 to the context_id attribute of
 an object. This field is used for a very specific purpose by the
 permissions system, and using this field in any other way whatsoever is guaranteed
-to make your application act strangely.
        As we'll see later, the Notes example will point each note
-object's context_id to the
+to make your application act strangely.
        As we'll see later, the Notes example will point each note
+object's context_id to the
 package instance in which the note was created. The idea will be
 that in a real site, the administrator would create one package
 instance for every separate set of Notes (say, one per user). The
-instance would "own" all of the notes that it created, and the
-administrator would be able to use the package instance as the
-basis for access control, which is convenient.
        
+instance would "own" all of the notes that it created,
+and the administrator would be able to use the package instance as
+the basis for access control, which is convenient.

        The reason behind these two rules is pretty straightforward: First, the OpenACS Object system itself is meant to be a generic @@ -340,10 +344,10 @@ we are careful to define our own attribute for owner_id rather than overloading creation_user from the objects table. But, since we will probably use creation_date and so on for their intended -purposes, we don't bother to define our own attributes to store -that data again. This will entail joins with acs_objects but that's OK because it makes -the overall data model cleaner. The real lesson is that deciding -exactly how and when to use inherited attributes is fairly +purposes, we don't bother to define our own attributes to store +that data again. This will entail joins with acs_objects but that's OK because it +makes the overall data model cleaner. The real lesson is that +deciding exactly how and when to use inherited attributes is fairly straightforward, but requires a good amount of thought at design time even for simple applications.

        @@ -361,8 +365,8 @@ acs_objects. This means you should never use the fields in acs_objects for application-specific purposes. This is especially true for the context_id field.

        -
        ($‌Id: objects.xml,v 1.9 2006/07/17 05:38:37 -torbenb Exp $)
        +
        ($‌Id: objects.html,v 1.52.2.10 2016/06/21 +07:44:36 gustafn Exp $)

        -We've omitted constraint names for the purpose of clarity. +We've omitted constraint names for the purpose of clarity.

        Thinking further ahead, we can imagine doing any of the following things with Notes as well: -

        • Define access control policies on notes.

        • Attach user comments on notes.

        • Allow users to define custom fields to store on their notes.

        • Automatically generate input forms or output displays for notes.

        • Allow other applications to use notes in ways we don't know of yet.

        +

        • Define access control policies on notes.

        • Attach user comments on notes.

        • Allow users to define custom fields to store on their notes.

        • Automatically generate input forms or output displays for notes.

        • Allow other applications to use notes in ways we don't know of yet.

        In OpenACS, the key to enabling these types of services on your application data is to take advantage of the Object System. The first question, then, is "Just what are objects, and what do you use them for anyway?". The short answer: objects are anything -represented in the application's data model that will need to be +represented in the application's data model that will need to be managed by any central service in OpenACS, or that may be reusable in the context of future applications. Every object in the system is represented using a row in the acs_objects table. This @@ -53,7 +53,7 @@ a general-comments replacement to personalized ranking - will become available to your application "for free."

        How to Use Objects

        -Using ACS objects is straightforward: all that's required are a few +Using ACS objects is straightforward: all that's required are a few extra steps in the design of your application data model.

        In order to hook our Notes application into the object system, we @@ -72,7 +72,7 @@ inherit attributes from a parent type, so the type system forms a hierarchy. Unlike Java, Oracle does not support this inheritance transparently, so we have to make sure we add our own bookkeeping code to -keep everything consistent. Below you'll find the code needed to describe a +keep everything consistent. Below you'll find the code needed to describe a new object type called notes in your system.

        @@ -100,14 +100,14 @@ note. This type is a subtype of the acs_object type, which means that we want to inherit all of the basic attributes of all ACS objects. As mentioned, it will take -some work on our part to make this happen, since Oracle can't do it +some work on our part to make this happen, since Oracle can't do it automatically. In general, most basic applications will define types that are simple subtypes of acs_object.

        Add entries to the acs_attributes table to describe the data attributes of the new type. This data can eventually be used to do things like automatically generate user interfaces to manipulate -the notes table, though that functionality isn't yet +the notes table, though that functionality isn't yet available. 

         declare 
@@ -193,9 +193,9 @@
 show errors

        You might be wondering what all the extra parameters are to these -calls, since we haven't mentioned them before. These parameters are +calls, since we haven't mentioned them before. These parameters are needed to fill out information that will be stored about the object -that's not stored directly in the table you defined. The OpenACS Object +that's not stored directly in the table you defined. The OpenACS Object System defines these attributes on the type acs_object since all objects should have these attributes. Internally, there are tables that store this information for you. Most of the data is pretty @@ -210,7 +210,7 @@ then the object inherits its permissions from the context. For example, if I had told you how to use the permissions system to specify that an object OBJ was "read only", then any other object that used OBJ as its -context would also be "read only" by default. We'll talk about this more +context would also be "read only" by default. We'll talk about this more later.

        Define a package body for type specific procedures

        The PL/SQL package body contains the implementations of the procedures @@ -272,15 +272,15 @@ / show errors;

        -That's pretty much it! As long as you use the note.new +That's pretty much it! As long as you use the note.new function to create notes, and the note.delete function to -delete them, you'll be assured that the relationship each +delete them, you'll be assured that the relationship each note has with its corresponding acs_object is preserved.

        The last thing to do is to make a file -ROOT/packages/notes/sql/notes-drop.sql so it's easy to -drop the data model when, say, you're testing: +ROOT/packages/notes/sql/notes-drop.sql so it's easy to +drop the data model when, say, you're testing: 

         begin 
   acs_object_type.drop_type ('note'); 
@@ -306,7 +306,7 @@
 For example, for most applications, you will want to use objects to
 represent the data in your application that is user visible and thus
 requires access control. But other internal tables, views, mapping
-tables and so on probably don't need to be objects. As before, this
+tables and so on probably don't need to be objects. As before, this
 kind of design decision is mostly made on an
 application-by-application basis, but this is a good baseline from
 which to start.
@@ -333,7 +333,7 @@
 field in any other way whatsoever is guaranteed to make your
 application act strangely.
 
        
-As we'll see later, the Notes example will point each note object's
+As we'll see later, the Notes example will point each note object's
 context_id to the package instance in which the note was
 created. The idea will be that in a real site, the administrator would
 create one package instance for every separate set of Notes (say, one
@@ -362,9 +362,9 @@
 are careful to define our own attribute for owner_id
 rather than overloading creation_user from the objects
 table. But, since we will probably use creation_date and
-so on for their intended purposes, we don't bother to define our own
+so on for their intended purposes, we don't bother to define our own
 attributes to store that data again. This will entail joins with
-acs_objects but that's OK because it makes the overall
+acs_objects but that's OK because it makes the overall
 data model cleaner. The real lesson is that deciding exactly how and
 when to use inherited attributes is fairly straightforward, but
 requires a good amount of thought at design time even for simple
Index: openacs-4/packages/acs-core-docs/www/openacs-overview.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-overview.adp,v
diff -u -N -r1.1.2.1 -r1.1.2.2
--- openacs-4/packages/acs-core-docs/www/openacs-overview.adp	23 Sep 2015 11:54:43 -0000	1.1.2.1
+++ openacs-4/packages/acs-core-docs/www/openacs-overview.adp	23 Jun 2016 08:32:45 -0000	1.1.2.2
@@ -12,9 +12,9 @@
 
        
 Overview
        OpenACS (Open Architecture Community System) is an advanced
 toolkit for building scalable, community-oriented web applications.
-If you're thinking of building an enterprise-level web application,
-OpenACS is a solid, scalable framework for building dynamic content
-driven sites.
        OpenACS is a collection of pre-built applications and services
+If you're thinking of building an enterprise-level web
+application, OpenACS is a solid, scalable framework for building
+dynamic content driven sites.
        OpenACS is a collection of pre-built applications and services
 that you can use to build your web site/application. Through a
 modular architecture, OpenACS has packages for user/groups
 management, content management, e-commerce, news, FAQs, calendar,
@@ -39,7 +39,7 @@
 custom development. Many of the production users are actively
 funding and contributing work back to the project. Formal,
 consensus driven governance has been established (with semi-annual
-elections) which ensures the project serves the needs of it's
+elections) which ensures the project serves the needs of it's
 constituents.
        The OpenACS community would like to hear your comments and can
 help you in your endeavors with the system. Visit our web site and
 feel free to ask questions or provide feedback.
        
Index: openacs-4/packages/acs-core-docs/www/openacs-overview.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-overview.html,v
diff -u -N -r1.29.2.1 -r1.29.2.2
--- openacs-4/packages/acs-core-docs/www/openacs-overview.html	9 Jun 2016 08:44:50 -0000	1.29.2.1
+++ openacs-4/packages/acs-core-docs/www/openacs-overview.html	23 Jun 2016 08:32:45 -0000	1.29.2.2
@@ -2,7 +2,7 @@
 Overview
        Alex logo
        Prev Chapter 1. High level information: What is OpenACS? Next
        Overview
        
         OpenACS (Open Architecture Community System) is an
         advanced toolkit for building scalable, community-oriented
-        web applications.  If you're thinking of building an
+        web applications.  If you're thinking of building an
         enterprise-level web application, OpenACS is a solid,
         scalable framework for building dynamic content driven
         sites.
@@ -43,7 +43,7 @@
         users are actively funding and contributing work back to the
         project.  Formal, consensus driven governance has been
         established (with semi-annual elections) which ensures the
-        project serves the needs of it's constituents.
+        project serves the needs of it's constituents.
       
        
         The OpenACS community would like to hear your comments and
         can help you in your endeavors with the system. Visit our
Index: openacs-4/packages/acs-core-docs/www/openacs.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs.adp,v
diff -u -N -r1.1.2.12 -r1.1.2.13
--- openacs-4/packages/acs-core-docs/www/openacs.adp	21 Jun 2016 07:44:36 -0000	1.1.2.12
+++ openacs-4/packages/acs-core-docs/www/openacs.adp	23 Jun 2016 08:32:45 -0000	1.1.2.13
@@ -19,25 +19,25 @@
 each site.

        AOLserver needs to be started as the root user if you want to use port 80. Once it starts, though, it will drop the root privileges and run as another user, which you must specify on the -command line. It's important that this user has as few privileges -as possible. Why? Because if an intruder somehow breaks in through -AOLserver, you don't want her to have any ability to do damage to -the rest of your server.

        At the same time, AOLserver needs to have write access to some +command line. It's important that this user has as few +privileges as possible. Why? Because if an intruder somehow breaks +in through AOLserver, you don't want her to have any ability to +do damage to the rest of your server.

        At the same time, AOLserver needs to have write access to some files on your system in order for OpenACS to function properly. So, -we'll run AOLserver with a different user account for each +we'll run AOLserver with a different user account for each different service. A service name should be a single word, letters and numbers only. If the name of your site is one word, that would be a good choice. For -example "$OPENACS_SERVICE_NAME" might be the -service name for the +example "$OPENACS_SERVICE_NAME" might be +the service name for the $OPENACS_SERVICE_NAME.net -community.

        We'll leave the password blank, which prevents login by +community.

        We'll leave the password blank, which prevents login by password, for increased security. The only way to log in will be with ssh certificates. The only people who should log in are developers for that specific instance. Add this user, and put it in the $OPENACS_SERVICE_NAME group so that it can use database and server commands associated with that -group. (If you don't know how to do this, type man usermod. You can type +group. (If you don't know how to do this, type man usermod. You can type groups to find out which groups a user is a part of)

         [root root]# useradd $OPENACS_SERVICE_NAME
@@ -84,9 +84,9 @@
 to a manual
 installation.
        Get the install script from CVS. It is located within the main
 cvs tree, at /etc/install. Use anonymous CVS checkout to get that
-directory in the home directory of the service's dedicated user. We
-put it there so that it is not overwritten when we do the main CVS
-checkout to the target location.
        +directory in the home directory of the service's dedicated
+user. We put it there so that it is not overwritten when we do the
+main CVS checkout to the target location.
         [root root]# su - $OPENACS_SERVICE_NAME
 
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs -d :pserver:anonymous\@cvs.openacs.org:/cvsroot co -d install openacs-4/etc/install
@@ -99,11 +99,11 @@
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd install
 [$OPENACS_SERVICE_NAME install]$ emacs install.tcl
 
        Edit the installation configuration file, /home/$OPENACS_SERVICE_NAME/install/install.tcl
-and update the site-specific values, such as the new service's IP
-address and name, which will be written into the new service's
-config.tcl file. If your system
-is different from the one described in the previous sections, check
-the file paths as well. Set do_checkout=yes to create a new OpenACS
+and update the site-specific values, such as the new service's
+IP address and name, which will be written into the new
+service's config.tcl file.
+If your system is different from the one described in the previous
+sections, check the file paths as well. Set do_checkout=yes to create a new OpenACS
 site directly from a CVS checkout, or =no if you have a fully configured site and
 just want to rebuild it (drop and recreate the database and repeat
 the installation). If you have followed a stock installation, the
@@ -176,8 +176,8 @@
 
      • 
 
        
 Prepare Oracle for
-OpenACS. If you won't be using Oracle, skip to
-Prepare PostgreSQL for
+OpenACS. If you won't be using Oracle,
+skip to Prepare PostgreSQL for
 an OpenACS Service
 
        You should be sure that your user account (e.g. $OPENACS_SERVICE_NAME) is in the
 dba group.
          
@@ -215,15 +215,15 @@
 /ora8/m01/app/oracle/oradata/ora8/drsys01.dbf
 
        • 
 
      • Using the above output, you should determine where to store your
-tablespace. As a general rule, you'll want to store your tablespace
-on a mount point under the /ora8 directory that is separate from the
+tablespace. As a general rule, you'll want to store your
+tablespace on a mount point under the /ora8 directory that is separate from the
 Oracle system data files. By default, the Oracle system is on
 m01, so we will use
 m02. This enables your Oracle
 system and database files to be on separate disks for optimized
 performance. For more information on such a configuration, see
-Chapter 12 of Philip's
-book. For this example, we'll use /ora8/m02/oradata/ora8/.
      • 
+Chapter 12 of Philip's
+book. For this example, we'll use /ora8/m02/oradata/ora8/.
      • 
 
        Create the directory for the datafile; to do this, exit from
 svrmgrl and login as
 root for this step:
        @@ -239,11 +239,11 @@
 
      • 
 
        Create a tablespace for the service. It is important that the
 tablespace can autoextend. This
-allows the tablespace's storage capacity to grow as the size of the
-data grows. We set the pctincrease to be a very low value so that
-our extents won't grow geometrically. We do not set it to 0 at the
-tablespace level because this would affect Oracle's ability to
-automatically coalesce free space in the tablespace.
        +allows the tablespace's storage capacity to grow as the size of
+the data grows. We set the pctincrease to be a very low value so
+that our extents won't grow geometrically. We do not set it to
+0 at the tablespace level because this would affect Oracle's
+ability to automatically coalesce free space in the tablespace.
         [$OPENACS_SERVICE_NAME ~]$ svrmgrl
 SVRMGR> connect internal;
 SVRMGR> create tablespace $OPENACS_SERVICE_NAME
@@ -257,7 +257,7 @@
 
        
 
      • 
 
        Create a database user for this service. Give the user access to
-the tablespace and rights to connect. We'll use $OPENACS_SERVICE_NAMEpassword as
+the tablespace and rights to connect. We'll use $OPENACS_SERVICE_NAMEpassword as
 our password.
        Write down what you specify as service_name (i.e. $OPENACS_SERVICE_NAME) and
 database_password (i.e.
 $OPENACS_SERVICE_NAMEpassword).
@@ -283,26 +283,27 @@
 ----------
 2001-12-20
 SQL> exit;
-

        • You should see today's date in a format 'YYYY-MM-DD.' If you -can't login, try redoing step 1 again. If the date is in the wrong -format, make sure you followed the steps outlined in the section called +

        You should see today's date in a format +'YYYY-MM-DD.' If you can't login, try redoing step 1 +again. If the date is in the wrong format, make sure you followed +the steps outlined in the section called “Troubleshooting Oracle Dates”

      • -Prepare PostgreSQL for an -OpenACS Service.  +Prepare PostgreSQL +for an OpenACS Service. 

        • PostgreSQL:

          Create a user in the database matching the service name. With default PostgreSQL authentication, a system user connecting locally automatically authenticates as the postgres user of the same name, -if one exists. We currently use postgres "super-users" for -everything, which means that anyone with access to any of the +if one exists. We currently use postgres "super-users" +for everything, which means that anyone with access to any of the openacs system accounts on a machine has full access to all postgresql databases on that machine.

           [root root]# su - postgres
@@ -348,9 +349,9 @@
 0 1-23 * * * /usr/local/pgsql/bin/vacuumdb --analyze $OPENACS_SERVICE_NAME
 0 0 * * * /usr/local/pgsql/bin/vacuumdb --full --analyze $OPENACS_SERVICE_NAME

          Depending on your distribution, you may receive email when the -crontab items are executed. If you don't want to receive email for -those crontab items, you can add > -/dev/null 2>&1 to the end of each crontab line

          +crontab items are executed. If you don't want to receive email +for those crontab items, you can add > /dev/null 2>&1 to the end of +each crontab line

        • Add Full Text Search Support (OPTIONAL)

        • @@ -376,15 +377,16 @@ [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc [$OPENACS_SERVICE_NAME etc]$ emacs config.tcl

          You can continue without changing any values in the file. -However, if you don't change address to match the computer's ip address, -you won't be able to browse to your server from other machines.

            +However, if you don't change address to match the computer's ip +address, you won't be able to browse to your server from other +machines.

            • httpport - If you want your server on a different port, enter it here. The Reference Platform port is 8000, which is suitable for development use. Port -80 is the standard http port - it's the port used by your browser -when you enter http://yourserver.test. So you should use port 80 -for your production site.

            • +80 is the standard http port - it's the port used by your +browser when you enter http://yourserver.test. So you should use +port 80 for your production site.

            • httpsport - This is the port for https requests. The Reference Platform https port is 8443. If http port is set to 80, httpsport should be 443 to match the @@ -442,7 +444,7 @@ also send a -b flag. Do this by editing the run file as indicated in the comments.

              If you are root then killall will affect all OpenACS services on -the machine, so if there's more than one you'll have to do +the machine, so if there's more than one you'll have to do ps -auxw | grep nsd and selectively kill by job number.

               [$OPENACS_SERVICE_NAME etc]$ killall nsd
@@ -459,23 +461,24 @@
 
              You should see a page that looks like this. If you imported your files into
 cvs, now that you know it worked you can erase the temp
 directory with rm -rf
-/var/lib/aolserver/$OPENACS_SERVICE_NAME.orig.
              If you don't see the login page, view your error log
+/var/lib/aolserver/$OPENACS_SERVICE_NAME.orig.
              If you don't see the login page, view your error log
 (/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log)
 to make sure the service is starting without any problems. The most
 common errors here are trying to start a port 80 server while not
 root, failing to connect because of a firewall, and aolserver
 failing to start due to permissions errors or missing files. If you
-need to make changes, don't forget to kill any running servers with
-killall nsd.
              
+need to make changes, don't forget to kill any running servers
+with killall
+nsd.

            • Automate AOLserver keepalive (OPTIONAL)

          • Configure a Service with the OpenACS -Installer.  Now that you've got AOLserver up and -running, let's install OpenACS 5.9.0.

              +Installer.  Now that you've got AOLserver +up and running, let's install OpenACS 5.9.0.

              • You should see a page from the webserver titled OpenACS Installation: Welcome. You will be warned if your version of the database driver is out of date, if AOLserver cannot connect to the database, if any modules are @@ -486,28 +489,29 @@

                The next page shows the results of loading the OpenACS Kernel data model - be prepared to wait a few minutes as it works. You should see a string of output messages from the database as the -datamodel is created. You'll see the line:

                +datamodel is created. You'll see the line:
                 Loading package .info files ... this will take a few minutes
 
                This will really take a few minutes. Have faith! Finally,
 another Next button will appear
 at the bottom - click it.

              • The following page shows the results of loading the core package data models. You should see positive results for each of the previously selected packages, but watch out for any errors. -Eventually, the page will display "Generating secret tokens" and -then "Done"- click Next.

              • You should see a page, "OpenACS Installation: Create +Eventually, the page will display "Generating secret +tokens" and then "Done"- click Next.

              • You should see a page, "OpenACS Installation: Create Administrator" with form fields to define the OpenACS site administrator. Fill out the fields as appropriate, and click Create User.

              • You should see a page, "OpenACS Installation: Set System -Information" allowing you to name your service. Fill out the fields -as appropriate, and click Set System -Information +Information" allowing you to name your service. Fill out the +fields as appropriate, and click Set +System Information

              • -

                You'll see the final Installer page, "OpenACS Installation: -Complete." It will tell you that the server is being restarted; -note that unless you already set up a way for AOLserver to restart -itself (ie. inittab or -daemontools), you'll need to manually restart your service.

                +
                You'll see the final Installer page, "OpenACS
+Installation: Complete." It will tell you that the server is
+being restarted; note that unless you already set up a way for
+AOLserver to restart itself (ie. inittab or
+daemontools), you'll need to manually restart your
+service.
                 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/$OPENACS_SERVICE_NAME/config.tcl

              • Give the server a few minutes to start up. Then reload the final @@ -546,7 +550,7 @@

                Set up database environment variables for the site user. Depending on how you installed Oracle or PostGreSQL, these settings may be necessary for working with the database while logged in as -the service user. They do not directly affect the service's +the service user. They do not directly affect the service's run-time connection with the database, because those environmental variables are set by the wrapper scripts nsd-postgres and nsd-oracle.

                @@ -563,9 +567,9 @@

              • Oracle. These environment variables are specific for a local Oracle installation communicating via IPC. If you are connecting to -a remote Oracle installation, you'll need to adjust these -appropriately. Also, make sure that the '8.1.7' matches your Oracle -version.

                +a remote Oracle installation, you'll need to adjust these
+appropriately. Also, make sure that the '8.1.7' matches
+your Oracle version.
                 export ORACLE_BASE=/ora8/m01/app/oracle
 export ORACLE_HOME=$ORACLE_BASE/product/8.1.7
 export PATH=$PATH:$ORACLE_HOME/bin
@@ -606,8 +610,8 @@
 recovery procedure.

              • Set up the section called “External uptime validation”.

                • -
              ($‌Id: openacs.xml,v 1.31 2006/07/17 05:38:37 -torbenb Exp $)
              +
            ($‌Id: openacs.html,v 1.51.2.10 2016/06/21 +07:44:36 gustafn Exp $)

        Set up a user account for each site.

        AOLserver needs to be started as the root user if you want to use port 80. Once it starts, though, it will drop the root privileges and - run as another user, which you must specify on the command line. It's + run as another user, which you must specify on the command line. It's important that this user has as few privileges as possible. Why? - Because if an intruder somehow breaks in through AOLserver, you don't + Because if an intruder somehow breaks in through AOLserver, you don't want her to have any ability to do damage to the rest of your server.

        At the same time, AOLserver needs to have write access to some files on your system in order for OpenACS to function - properly. So, we'll run AOLserver with a different user account + properly. So, we'll run AOLserver with a different user account for each different service. A service name should be a single word, letters and numbers only. If the name of your site is one word, that would be a good choice. For example "$OPENACS_SERVICE_NAME" might be the service name for the $OPENACS_SERVICE_NAME.net - community.

        We'll leave the password blank, which prevents login by + community.

        We'll leave the password blank, which prevents login by password, for increased security. The only way to log in will be with ssh certificates. The only people who should log in are developers for that specific instance. Add this user, and put it in the $OPENACS_SERVICE_NAME group so that it can use database and server commands associated with that group. - (If you don't know how to do this, type + (If you don't know how to do this, type man usermod. You can type groups to find out which groups a user is a part of) @@ -55,7 +55,7 @@ chmod 770 /var/lib/aolserver

        Installation Option 1: Use automated script

        A bash script is available to automate all of the steps for the rest of this section. It requires tclwebtest. The automated script can greatly accelerate the install process, but is very sensitive to the install environment. We recommend that you run the automated install and, if it does not work the first time, consider switching to a manual installation.

        Get the install script from CVS. It is located within the main cvs tree, at /etc/install. Use anonymous CVS checkout to get that directory in the home directory of the - service's dedicated user. We put it there so that it is not + service's dedicated user. We put it there so that it is not overwritten when we do the main CVS checkout to the target location.

        [root root]# su - $OPENACS_SERVICE_NAME
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot co -d install openacs-4/etc/install
@@ -67,7 +67,7 @@
 U install/tcl/user-procs.tcl
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd install
 [$OPENACS_SERVICE_NAME install]$ emacs install.tcl
-

        Edit the installation configuration file, /home/$OPENACS_SERVICE_NAME/install/install.tcl and update the site-specific values, such as the new service's IP address and name, which will be written into the new service's config.tcl file. If your system is different from the one described in the previous sections, check the file paths as well. Set do_checkout=yes to create a new OpenACS site directly from a CVS checkout, or =no if you have a fully configured site and just want to rebuild it (drop and recreate the database and repeat the installation). If you have followed a stock installation, the default configuration will work without changes and will install an OpenACS site at 127.0.0.1:8000.

        Run the install script install.sh as root:

        [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit 
+

        Edit the installation configuration file, /home/$OPENACS_SERVICE_NAME/install/install.tcl and update the site-specific values, such as the new service's IP address and name, which will be written into the new service's config.tcl file. If your system is different from the one described in the previous sections, check the file paths as well. Set do_checkout=yes to create a new OpenACS site directly from a CVS checkout, or =no if you have a fully configured site and just want to rebuild it (drop and recreate the database and repeat the installation). If you have followed a stock installation, the default configuration will work without changes and will install an OpenACS site at 127.0.0.1:8000.

        Run the install script install.sh as root:

        [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit 
 [root root]# sh /home/$OPENACS_SERVICE_NAME/install/install.sh
 /home/$OPENACS_SERVICE_NAME/install/install.sh: Starting installation with config_file 
 /home/$OPENACS_SERVICE_NAME/install/install.tcl. Using serverroot=/var/lib/aolserver/
@@ -105,7 +105,7 @@
 mv openacs-5.9.0 $OPENACS_SERVICE_NAME
 chmod -R 755 $OPENACS_SERVICE_NAME
 chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME
-exit

      • Add the Service to CVS (OPTIONAL)

      • Prepare the database

        • Prepare Oracle for OpenACS. If you won't be using Oracle, skip to Prepare PostgreSQL for an OpenACS Service

          +exit

        • Add the Service to CVS (OPTIONAL)

        • Prepare the database

          • Prepare Oracle for OpenACS. If you won't be using Oracle, skip to Prepare PostgreSQL for an OpenACS Service

            You should be sure that your user account (e.g. $OPENACS_SERVICE_NAME) is in the dba group. @@ -152,7 +152,7 @@ /ora8/m01/app/oracle/oradata/ora8/drsys01.dbf

          • Using the above output, you should determine where - to store your tablespace. As a general rule, you'll want to + to store your tablespace. As a general rule, you'll want to store your tablespace on a mount point under the /ora8 directory that is separate from the Oracle system data files. By default, the Oracle system @@ -161,8 +161,8 @@ system and database files to be on separate disks for optimized performance. For more information on such a configuration, see Chapter - 12 of Philip's - book. For this example, we'll use + 12 of Philip's + book. For this example, we'll use /ora8/m02/oradata/ora8/.

          • Create the directory for the datafile; to do this, @@ -179,11 +179,11 @@ Create a tablespace for the service. It is important that the tablespace can autoextend. This - allows the tablespace's storage capacity to grow as the size + allows the tablespace's storage capacity to grow as the size of the data grows. We set the pctincrease to be a very low value - so that our extents won't grow geometrically. We do not set + so that our extents won't grow geometrically. We do not set it to 0 at the tablespace level because this would affect - Oracle's ability to automatically coalesce free space in the + Oracle's ability to automatically coalesce free space in the tablespace. 

            [$OPENACS_SERVICE_NAME ~]$ svrmgrl
@@ -197,7 +197,7 @@
       extent management local
       uniform size 32K;

          • Create a database user for this service. Give the - user access to the tablespace and rights to connect. We'll use + user access to the tablespace and rights to connect. We'll use $OPENACS_SERVICE_NAMEpassword as our password.

            Write down what you specify as service_name @@ -223,8 +223,8 @@ ---------- 2001-12-20 SQL> exit;

            - You should see today's date in a format 'YYYY-MM-DD.' - If you can't login, try redoing step 1 again. If the date is + You should see today's date in a format 'YYYY-MM-DD.' + If you can't login, try redoing step 1 again. If the date is in the wrong format, make sure you followed the steps outlined in the section called “Troubleshooting Oracle Dates”

        • Prepare PostgreSQL for an OpenACS Service. 

          • PostgreSQL:

            Create a user in the database matching the service @@ -241,7 +241,7 @@ /usr/local/pgsql/bin/createdb -E UNICODE $OPENACS_SERVICE_NAME

          • Automate daily database Vacuuming. This is a process which cleans out discarded data from the database. A quick way to automate vacuuming is to edit the cron file for the database user. Recommended: VACUUM ANALYZE every hour and VACUUM FULL ANALYZE every day.

            [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ export EDITOR=emacs;crontab -e

            Add these lines to the file. The vacuum command cleans up temporary structures within a PostGreSQL database, and can improve performance. We vacuum gently every hour and completely every day. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day, and every (*) day of month, month, and day of week. Type man 5 crontab for more information.

            0 1-23 * * * /usr/local/pgsql/bin/vacuumdb --analyze $OPENACS_SERVICE_NAME
 0 0 * * * /usr/local/pgsql/bin/vacuumdb --full --analyze $OPENACS_SERVICE_NAME

            Depending on your distribution, you may receive email when the crontab items are executed. If you - don't want to receive email for those crontab items, + don't want to receive email for those crontab items, you can add > /dev/null 2>&1 to the end of each crontab line

          • Add Full Text Search Support (OPTIONAL)

          • At this point the database should be ready for installing OpenACS.

      • Configure an AOLserver Service for OpenACS. 

        1. @@ -255,9 +255,9 @@ [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc [$OPENACS_SERVICE_NAME etc]$ emacs config.tcl

          - You can continue without changing any values in the file. However, if you don't change address to match the computer's ip address, you won't be able to browse to your server from other machines. + You can continue without changing any values in the file. However, if you don't change address to match the computer's ip address, you won't be able to browse to your server from other machines.

          • httpport - If you want your - server on a different port, enter it here. The Reference Platform port is 8000, which is suitable for development use. Port 80 is the standard http port - it's the port used by your browser when you enter http://yourserver.test. So you should use port 80 for your production site.

          • httpsport - This is the + server on a different port, enter it here. The Reference Platform port is 8000, which is suitable for development use. Port 80 is the standard http port - it's the port used by your browser when you enter http://yourserver.test. So you should use port 80 for your production site.

          • httpsport - This is the port for https requests. The Reference Platform https port is 8443. If http port is set to 80, httpsport should be 443 to match the standard.

          • @@ -287,7 +287,7 @@ /etc/passwd and then put those numbers into the command line via -u 501 -g - 502. In AOLserver 4, you must also send a -b flag. Do this by editing the run file as indicated in the comments.

            If you are root then killall will affect all OpenACS services on the machine, so if there's more than one you'll have to do ps -auxw | grep + 502. In AOLserver 4, you must also send a -b flag. Do this by editing the run file as indicated in the comments.

            If you are root then killall will affect all OpenACS services on the machine, so if there's more than one you'll have to do ps -auxw | grep nsd and selectively kill by job number.

            [$OPENACS_SERVICE_NAME etc]$ killall nsd
 nsd: no process killed
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl
@@ -299,19 +299,19 @@
         directory with rm -rf /var/lib/aolserver/$OPENACS_SERVICE_NAME.orig.
 	
            
 
-	  If you don't see the login page, view your error log
+	  If you don't see the login page, view your error log
 	  (/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log)
 	  to make sure the service is starting without any
 	  problems. The most common errors here are trying to start a
 	  port 80 server while not root, failing to connect because of
 	  a firewall, and aolserver failing to start due to
 	  permissions errors or missing files.  If you need to make
-	  changes, don't forget to kill any running servers with
+	  changes, don't forget to kill any running servers with
 	  killall nsd.

          • Automate AOLserver keepalive (OPTIONAL)

      • Configure a Service with the OpenACS Installer.  - Now that you've got AOLserver up and running, let's install OpenACS + Now that you've got AOLserver up and running, let's install OpenACS 5.9.0.

        • You should see a page from the webserver titled @@ -328,7 +328,7 @@ The next page shows the results of loading the OpenACS Kernel data model - be prepared to wait a few minutes as it works. You should see a string of output messages from the database as the - datamodel is created. You'll see the line: + datamodel is created. You'll see the line: 

           Loading package .info files ... this will take a few minutes

          @@ -359,11 +359,11 @@ fields as appropriate, and click Set System Information

        • - You'll see the final Installer page, "OpenACS + You'll see the final Installer page, "OpenACS Installation: Complete." It will tell you that the server is being restarted; note that unless you already set up a way for AOLserver to restart itself (ie. inittab or daemontools), - you'll need to manually restart your service. + you'll need to manually restart your service. 

          [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/$OPENACS_SERVICE_NAME/config.tcl

        • Give the server a few minutes to start up. Then reload the final page above. You should see the front page, with @@ -378,13 +378,13 @@ packages. (more information)

        • Proceed to the tutorial to learn how to develop your own packages.

        • Set up database environment variables for the site user. Depending on how you installed Oracle or PostGreSQL, these settings may be necessary for working with the database while logged in as the service user. They do not - directly affect the service's run-time connection with the + directly affect the service's run-time connection with the database, because those environmental variables are set by the wrapper scripts nsd-postgres and nsd-oracle.

          [root root]# su - $OPENACS_SERVICE_NAME
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ emacs .bashrc

          Put in the appropriate lines for the database you are running. If you will use both databases, put in both sets of lines.

          • PostgreSQL:

            export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib
 export PATH=$PATH:/usr/local/pgsql/bin

          • Oracle. These environment variables are specific for a local Oracle installation communicating via IPC. If you are connecting to a remote - Oracle installation, you'll need to adjust these appropriately. Also, + Oracle installation, you'll need to adjust these appropriately. Also, make sure that the '8.1.7' matches your Oracle version. 

            export ORACLE_BASE=/ora8/m01/app/oracle
 export ORACLE_HOME=$ORACLE_BASE/product/8.1.7
Index: openacs-4/packages/acs-core-docs/www/oracle.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/oracle.adp,v
diff -u -N -r1.1.2.6 -r1.1.2.7
--- openacs-4/packages/acs-core-docs/www/oracle.adp	9 Jun 2016 13:03:11 -0000	1.1.2.6
+++ openacs-4/packages/acs-core-docs/www/oracle.adp	23 Jun 2016 08:32:45 -0000	1.1.2.7
@@ -16,32 +16,32 @@
 OpenACS documentation staff.

          If you are installing PostGreSQL instead of Oracle, skip this section.

          OpenACS 5.9.0 will install with Oracle 9i but has not been extensively tested so may still have bugs or tuning issues. See -Andrew Piskorski's Oracle 9i notes for +Andrew Piskorski's Oracle 9i notes for guidance.

          This installation guide attempts to present all of the information necessary to complete an OpenACS installation. We try hard to make all of the steps possible in one pass, rather than having a step which amounts to "go away and develop a profound understanding of software X and then come back and, in 99% of all -cases, type these two lines." The exception to our rule is Oracle -production systems. This page describes a set of steps to get a -working Oracle development server, but it is unsuitable for production systems. +cases, type these two lines." The exception to our rule is +Oracle production systems. This page describes a set of steps to +get a working Oracle development server, but it is unsuitable for production systems. If you will be using OpenACS on Oracle in a production environment, you will experience many problems unless you develop a basic understanding of Oracle which is outside the scope of this -document. T

          This document assumes that you'll be installing Oracle on the -same box as AOLserver. For more details on a remote Oracle -installation, see Daryl Biberdorf's document.

          Useful links to find help on how to set up Oracle under Linux +document. T

          This document assumes that you'll be installing Oracle on +the same box as AOLserver. For more details on a remote Oracle +installation, see Daryl Biberdorf's document.

          Useful links to find help on how to set up Oracle under Linux are:

          Acquire Oracle

          Production Oracle systems should run on certified platforms. Follow the metalink note 223718.1to find certified -platforms. If you don't have metalink access, take a look at the -Oracle on Linux FAQ: Which Linux Distributions Are Directly Supported By +platforms. If you don't have metalink access, take a look at +the Oracle on Linux FAQ: Which Linux Distributions Are Directly Supported By Oracle?. In summary, free and inexpensive Linux distributions -are not certified.

          If you don't have an account at OTN get one: you can +are not certified.

          If you don't have an account at OTN get one: you can download the Oracle software from the Oracle Downloads page. It is also get the CDs shipped to you for a nominal fee from the Oracle Store.

          Each Oracle release comes with extensive and usually quite well-written documentation. Your first step should be to thoroughly @@ -52,18 +52,18 @@ its latest patchset. At the time of writing these were 8.1.7.4 and 9.2.0.5, both of which are considered to be very stable.

          To be able to download a patchset, you need a (to-pay-for) account on Metalink. You may find the appropriate patchset by -following Andrew's suggestion.

          +following Andrew's suggestion.

          Things to Keep in Mind

          Oracle is very well-documented software, the online documentation comes with printable PDFs and full-text search. Altogether there is more than 20.000 pages of documentation, so do not expect to understand Oracle within in a few hours. The best -starting pointing into Oracle is the Concepts book. Here's the +starting pointing into Oracle is the Concepts book. Here's the 8i version and the 9.2 version.

          To give you an idea of how configurable Oracle is and how much thought you may need to put into buying the proper hardware and -creating a sane setup, you should thoroughly read Cary Millsap's -Configuring Oracle Server for VLDB and the +creating a sane setup, you should thoroughly read Cary +Millsap's Configuring Oracle Server for VLDB and the Optimal Flexible Architecture standard.

          Throughout these instructions, we will refer to a number of configurable settings and advise certain defaults. With the exception of passwords, we advise you to follow these defaults @@ -87,7 +87,7 @@ 

           nls_date_format = "YYYY-MM-DD"

          For additional resources/documentation, please see this -thread and Andrew Piskorski's mini-guide.

          +thread and Andrew Piskorski's mini-guide.

          Pre-Installation Tasks

          Though Oracle 8.1.7 has an automated installer, we still need to @@ -131,7 +131,7 @@ root:/ora8# exit

        • -

          Set up the oracle user's +

          Set up the oracle user's environment

          • Log in as the user oracle by @@ -241,13 +241,13 @@

          Check to make sure the file is there.

           oracle:/where/oracle/Disk1$ ls
 doc  index.htm  install  runInstaller  stage  starterdb
-

          If you don't see runInstaller, you are in the wrong +

          If you don't see runInstaller, you are in the wrong directory.

        • Run the installer

           oracle:/where/oracle/Disk1$ ./runInstaller
-

          A window will open that welcomes you to the 'Oracle Universal -Installer' (OUI). Click on "Next"

          +

          A window will open that welcomes you to the 'Oracle +Universal Installer' (OUI). Click on "Next"

          Note

          Some people have had trouble with this step on RedHat 7.3 and 8.0. If so, try the following steps before calling ./runInstaller:

          1. Execute the following command: /usr/i386-glibc21-linux/bin/i386-glibc21-linux-env.sh @@ -258,20 +258,20 @@

        • The "File Locations" screen in the OUI:

            -

          • "Source" path should have been prefilled with "(wherever you -mounted the CDROM)/stage/products.jar"

          • +

          • "Source" path should have been prefilled with +"(wherever you mounted the CDROM)/stage/products.jar"

          • "destination" path says "/ora8/m01/app/oracle/product/8.1.7"

            If the destination is not correct it is because your environment variables are not set properly. Make sure you logged on as oracle using su - oracle. If so, edit the ~/.bash_profile as you did in the section called “Pre-Installation Tasks”

            -

          • Click "Next" (a pop up window will display Loading Product -information).

            • +

          • Click "Next" (a pop up window will display Loading +Product information).

        • The "Unix Group Name" screen in the OUI:

            -

          • The Unix Group name needs to be set to 'oinstall' ( we made this Unix group earlier -).

          • Click "Next"

          • A popup window appears instantly, requesting you to run a script +

          • The Unix Group name needs to be set to 'oinstall' ( we made this Unix group +earlier ).

          • Click "Next"

          • A popup window appears instantly, requesting you to run a script as root:

            • Debian users need to link /bin/awk to /usr/bin/awk before running the script below

              @@ -303,17 +303,20 @@

            • The "Available Product Components" screen

              • In addition to the defaults, make sure that "Oracle SQLJ -8.1.7.0," "Oracle Protocol Support 8.1.7.0.0," and "Linux -Documentation 8.1.7.0.0" are also checked.

              • Click "Next"

              • A progress bar will appear for about 1 minute.

                • +8.1.7.0," "Oracle Protocol Support 8.1.7.0.0," and +"Linux Documentation 8.1.7.0.0" are also checked.

              • Click "Next"

              • A progress bar will appear for about 1 minute.

            • The "Component Locations" screen in the OUI

                -

              • Click on the "Java Runtime Environment 1.1.8" It should have the -path "/ora8/m01/app/oracle/jre/1.1.8"

              • Click "Next"

              • A progress bar will appear for about 1 minute.

                • +

              • Click on the "Java Runtime Environment 1.1.8" It +should have the path "/ora8/m01/app/oracle/jre/1.1.8"

              • Click "Next"

              • A progress bar will appear for about 1 minute.

            • -

              The "Privileged Operation System Groups" screen in the OUI

                -

              • Enter "dba" for "Database Administrator (OSDBA) Group"

              • Enter "dba" for the "Database Operator (OSOPER) Group"

              • Click "Next"

              • A progress bar will appear for about 1 minute.

                • +

                The "Privileged Operation System Groups" screen in the +OUI

                  +

                • Enter "dba" for "Database Administrator (OSDBA) +Group"

                • Enter "dba" for the "Database Operator (OSOPER) +Group"

                • Click "Next"

                • A progress bar will appear for about 1 minute.

              • The "Authentication Methods" screen

                • Click "Next"

                @@ -324,24 +327,25 @@

            • The "Create a Database" screen in the OUI

                -

              • Select "No" as we will do this later, after some important -configuration changes.

              • Click "Next"

                • +

              • Select "No" as we will do this later, after some +important configuration changes.

              • Click "Next"

            • The next screen is "Oracle Product Support"

                -

              • TCP should be checked with "Status" listed as Required

              • Click "Next"

                • +

              • TCP should be checked with "Status" listed as +Required

              • Click "Next"

            • The "Summary" screen in the OUI

                -

              • Check the "Space Requirements" section to verify you have enough -disk space for the install.

              • Check that "(144 products)" is in the "New Installations" -section title.

              • Click "Install"

              • A progress bar will appear for about 20 - 30 minutes. Now is a -good time to take a break.

              • A "Setup Privileges" window will popup towards the end of the -installation asking you to run a script as root +

              • Check the "Space Requirements" section to verify you +have enough disk space for the install.

              • Check that "(144 products)" is in the "New +Installations" section title.

              • Click "Install"

              • A progress bar will appear for about 20 - 30 minutes. Now is a +good time to take a break.

              • A "Setup Privileges" window will popup towards the end +of the installation asking you to run a script as root

              • Run the script. Switch to the oracle user first to set the environment appropriately and then do su to get root privileges, while -keeping the oracle user's enviroment.

                +keeping the oracle user's enviroment.
                 [joeuser ~]$ su - oracle
 Password: *********
 [oracle ~]$ su
@@ -384,40 +388,44 @@
 
                The "Configuration Tools" screen in the OUI
                • This window displays the config tools that will automatically be
 launched.
              • -

                The "Welcome" screen in the "net 8 Configuration Assistant"

                  -

                • Make sure the "Perform Typical installation" is not selected.

                • Click "Next"

                • The "Directory Service Access" screen in the "Net 8 -Configuration Assistant"

                • Select "No"

                • Click "Next"

                  • +

                  The "Welcome" screen in the "net 8 Configuration +Assistant"

                    +

                  • Make sure the "Perform Typical installation" is +not selected.

                  • Click "Next"

                  • The "Directory Service Access" screen in the "Net +8 Configuration Assistant"

                  • Select "No"

                  • Click "Next"

                • -

                  The "Listener Configuration, Listener Name" screen in the "Net 8 -Configuration Assistant"

                    +

                    The "Listener Configuration, Listener Name" screen in +the "Net 8 Configuration Assistant"

                    • Accept the default listener name of "LISTENER"

                    • Click "Next"

                  • -

                    The "Listener Configuration, Select Protocols" screen in the -"Net 8 Configuration Assistant"

                      -

                    • The only choice in "Select protocols:" should be "TCP/IP"

                    • Click "Next"

                      • +

                      The "Listener Configuration, Select Protocols" screen +in the "Net 8 Configuration Assistant"

                        +

                      • The only choice in "Select protocols:" should be +"TCP/IP"

                      • Click "Next"

                    • -

                      The "Listener Configuration TCP/IP Protocol" screen in the "Net -8 Configuration Assistant"

                        +

                        The "Listener Configuration TCP/IP Protocol" screen in +the "Net 8 Configuration Assistant"

                        • Default Port should be 1521 and selected.

                        • Click "Next"

                      • -

                        The "Listener Configuration, More Listeners" screen in the "Net -8 Configuration Assistant"

                          +

                          The "Listener Configuration, More Listeners" screen in +the "Net 8 Configuration Assistant"

                          • Select "No"

                          • Click "Next"

                        • -

                          The "Listener Configuration Done" screen in the "Net 8 -Configuration Assistant"

                          • Click "Next"

                          +

                          The "Listener Configuration Done" screen in the +"Net 8 Configuration Assistant"

                          • Click "Next"

                        • -

                          The "Naming Methods Configuration" screen in the "Net 8 -Configuration Assistant"

                            +

                            The "Naming Methods Configuration" screen in the +"Net 8 Configuration Assistant"

                            • Select "No"

                            • Click "Next"

                          • -

                            The "Done" screen in the "Net 8 Configuration Assistant"

                            • Click "Finish"

                            +

                            The "Done" screen in the "Net 8 Configuration +Assistant"

                            • Click "Finish"

                          • The "End of Installation" screen in the OUI

                            • Click "Exit"

                            • Click "Yes" on the confirmation pop up window.

                            • The Oracle Universal Installer window should have @@ -426,7 +434,7 @@

                            Congratulations, you have just installed Oracle 8.1.7 Server! However, you still need to create a database which can take about -an hour of non-interactive time, so don't quit yet.

                            +an hour of non-interactive time, so don't quit yet.

                          Creating the First Database

                          This step will take you through the steps of creating a @@ -445,8 +453,8 @@ [oracle ~]$ dbassist

                        • -

                          The "Welcome" screen in the Oracle Database Configuration Agent -(ODCA)

                            +

                            The "Welcome" screen in the Oracle Database +Configuration Agent (ODCA)

                            • Select "Create a database"

                            • Click "Next"

                          • @@ -464,20 +472,21 @@

                          • Select "Dedicated Server Mode", click "Next"

                          • Accept all of the options, and click Next Oracle Visual Information Retrieval may be grayed out. If so, you can ignore it; just make sure that -everything else is checked.

                          • For "Global Database Name", enter "ora8"; for "SID", also enter "ora8" (it should do this automatically). -Click "Change Character Set and -select UTF8. Click -"Next".

                          • Accept the defaults for the next screen (control file location). -Click "Next"

                          • Go to the "temporary" and "rollback" tabs, and change the Size -(upper-right text box) to 150MB. Click "Next"

                          • Increase the redo log sizes to 10000K each. Click "Next"

                          • Use the default checkpoint interval & timeout. Click -"Next"

                          • Increase "Processes" to -100; "Block Size" to 4096 (better for small Linux boxes; use +everything else is checked.

                          • For "Global Database Name", enter "ora8"; for "SID", also enter +"ora8" (it should do +this automatically). Click "Change Character Set and select +UTF8. Click "Next".

                          • Accept the defaults for the next screen (control file location). +Click "Next"

                          • Go to the "temporary" and "rollback" tabs, +and change the Size (upper-right text box) to 150MB. Click "Next"

                          • Increase the redo log sizes to 10000K each. Click "Next"

                          • Use the default checkpoint interval & timeout. Click +"Next"

                          • Increase "Processes" to 100; "Block Size" to 4096 (better for small Linux boxes; use 8192 for a big Solaris machine).

                          • Accept the defaults for the Trace File Directory. Click -"Next"

                          • Finally, select "Save information -to a shell script" and click "Finish" (We're going to examine the -contents of this file before creating our database.)

                          • Click the "Save" button. -Oracle will automatically save it to the correct directory and with -the correct file name. This will likely be /ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib/sqlora8.sh +"Next"

                          • Finally, select "Save +information to a shell script" and click +"Finish" (We're +going to examine the contents of this file before creating our +database.)

                          • Click the "Save" +button. Oracle will automatically save it to the correct directory +and with the correct file name. This will likely be /ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib/sqlora8.sh

                          • It will alert you that the script has been saved successfully.

                          • Now we need to customize the database configuration a bit. While @@ -496,7 +505,7 @@

                          • Now find the open_cursors -line in the file. If you're using emacs scroll up to the top of the buffer +line in the file. If you're using emacs scroll up to the top of the buffer and do CTRL-S and type open_cursors to find the line. The default is 100. Change it @@ -519,26 +528,26 @@ succeed.

                          • Your database will now be built. It will take > 1 hour - no -fooling. You will see lots of errors scroll by (like: "ORA-01432: -public synonym to be dropped does not exist") Fear not, this is -normal.

                            Eventually, you'll be returned to your shell prompt. In the -meantime, relax, you've earned it.

                            +fooling. You will see lots of errors scroll by (like: +"ORA-01432: public synonym to be dropped does not exist") +Fear not, this is normal.

                            Eventually, you'll be returned to your shell prompt. In the +meantime, relax, you've earned it.

                        Acceptance Test

                        For this step, open up a terminal and su to oracle as usual. You should be running X and Netscape (or other web browser) for this phase.

                          -

                        • You need to download the "Oracle Acceptance Test" file. It's -available here and at http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt. +

                        • You need to download the "Oracle Acceptance Test" +file. It's available here and at http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt. Save the file to /var/tmp

                        • In the oracle shell, copy the file.

                           [oracle ~]$ cp /var/tmp/acceptance-sql.txt /var/tmp/acceptance.sql
                        • -

                          Once you've got the acceptance test file all set, stay in your -term and type the following:

                          +
                          Once you've got the acceptance test file all set, stay in
+your term and type the following:
                           [oracle ~]$ sqlplus system/manager
 
                          SQL*Plus should startup. If you get an ORA-01034: Oracle not Available error, it
 is because your Oracle instance is not running. You can manually
@@ -549,25 +558,25 @@
 SVRMGR> startup
                        • -

                          Now that you're into SQL*Plus, change the default passwords for -system, sys, and ctxsys to "alexisahunk" (or to something you'll -remember):

                          +
                          Now that you're into SQL*Plus, change the default passwords
+for system, sys, and ctxsys to "alexisahunk" (or to
+something you'll remember):
                           SQL> alter user system identified by alexisahunk;
 SQL> alter user sys identified by alexisahunk;
 SQL> alter user ctxsys identified by alexisahunk;

                        • Verify that your date settings are correct.

                           SQL> select sysdate from dual;
-

                          If you don't see a date that fits the format YYYY-MM-DD, please read the section called +

                          If you don't see a date that fits the format YYYY-MM-DD, please read the section called “Troubleshooting Oracle Dates”.

                        • At this point we are going to hammer your database with an intense acceptance test. This usually takes around 30 minutes.

                           SQL> \@ /var/tmp/acceptance.sql
 
-; A bunch of lines will scroll by.  You'll know if the test worked if
+; A bunch of lines will scroll by.  You'll know if the test worked if
 ; you see this at the end:
 
 SYSDATE
@@ -586,16 +595,16 @@
 “Creating the First Database”
 above. You can set the parameter using the dbassist program or by setting the
 DB_BLOCK_SIZE parameter in your
-database's creation script.
                          If there were no errors, then consider yourself fortunate. Your
+database's creation script.
                          If there were no errors, then consider yourself fortunate. Your
 Oracle installation is working.

                        Automating Startup & Shutdown

                        You will want to automate the database startup and shutdown -process. It's probably best to have Oracle spring to life when you -boot up your machine.

                          +process. It's probably best to have Oracle spring to life when +you boot up your machine.

                          • Oracle includes a script called dbstart that can be used to automatically start the database. Unfortunately, the script shipped in the Linux @@ -605,7 +614,7 @@ [oracle ~]$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/dbstart

                          • -

                            While you're logged in as oracle, you should configure the +

                            While you're logged in as oracle, you should configure the oratab file to load your database at start. Edit the file /etc/oratab:

                            • @@ -615,9 +624,9 @@ databases, the format of this file is:

                              service_name:$ORACLE_HOME:Y || N (for autoload)

                            • -

                              Change the last letter from "N" to "Y". This tells Oracle that -you want the database to start when the machine boots. It should -look like this.

                              +
                              Change the last letter from "N" to "Y". This
+tells Oracle that you want the database to start when the machine
+boots. It should look like this.
                               ora8:/ora8/m01/app/oracle/product/8.1.7:Y

                            • Save the file & quit the terminal.

                              • @@ -870,8 +879,8 @@ on the number of seconds elapsed since some date. However, for the purposes of inputing dates into Oracle and getting them back out, Oracle needs to be told to use a specific date format. By default, -it uses an Oracle-specific format which isn't copacetic. You want -Oracle to use the ANSI-compliant date format which is of form +it uses an Oracle-specific format which isn't copacetic. You +want Oracle to use the ANSI-compliant date format which is of form 'YYYY-MM-DD'.

                              To fix this, you should include the following line in $ORACLE_HOME/dbs/initSID.ora or for the default case, $ORACLE_HOME/dbs/initora8.ora 

                              @@ -887,8 +896,8 @@
 SQL> select sysdate from dual;

                              If the date does not conform to this format, double-check that you included the necessary line in the init scripts. If it still -isn't working, make sure that you have restarted the database since -adding the line:

                              +isn't working, make sure that you have restarted the database
+since adding the line:
                               [joeuser ~]$ svrmgrl
 SVRMGR> connect internal
 Connected.
@@ -898,16 +907,16 @@
 ORACLE instance shut down.
 SVRMGR> startup
 ORACLE instance started.
-
                              If you're sure that you have restarted the database since adding
-the line, check your initialization scripts. Make sure that the
-following line is not included:
                              +
                              If you're sure that you have restarted the database since
+adding the line, check your initialization scripts. Make sure that
+the following line is not included:
                               export nls_lang = american
 
                              Setting this environment variable will override the date
 setting. Either delete this line and login again or add the
 following entry to your login scripts after the nls_lang line:
                               export nls_date_format = 'YYYY-MM-DD'
-
                              Log back in again. If adding the nls_date_format line doesn't help, you can
-ask for advice in our OpenACS
+

                              Log back in again. If adding the nls_date_format line doesn't help, you +can ask for advice in our OpenACS forums.

                            @@ -961,8 +970,8 @@ access to the Oracle system.

        		•
        ($‌Id: oracle.xml,v 1.21 2006/07/17 05:38:37 -torbenb Exp $)
        +
        ($‌Id: oracle.html,v 1.49.2.10 2016/06/21 +07:44:36 gustafn Exp $)

        If you are installing PostGreSQL instead of Oracle, skip this section.

        - OpenACS 5.9.0 will install with Oracle 9i but has not been extensively tested so may still have bugs or tuning issues. See Andrew Piskorski's Oracle 9i notes for guidance. + OpenACS 5.9.0 will install with Oracle 9i but has not been extensively tested so may still have bugs or tuning issues. See Andrew Piskorski's Oracle 9i notes for guidance.

        This installation guide attempts to present all of the information necessary to complete an OpenACS installation. We try hard to make all of the steps possible in one pass, rather than having a step which amounts to "go away and develop a profound understanding of software X and then come back and, in 99% of all cases, type these two lines." The exception to our rule is Oracle production systems. This page describes a set of steps to get a working Oracle development server, but it is unsuitable for production systems. If you will be using OpenACS on Oracle in a production environment, you will experience many problems unless you develop a basic understanding of Oracle which is outside the scope of this document. T

        - This document assumes that you'll be installing Oracle on the same + This document assumes that you'll be installing Oracle on the same box as AOLserver. For more details on a remote Oracle installation, - see Daryl Biberdorf's document. + see Daryl Biberdorf's document.

        Useful links to find help on how to set up Oracle under Linux are:

        Acquire Oracle

        + Roger's company - on Oracle on Linux

      • Werner Puschitz - Oracle on Red Hat Linux

      • SuSE/Oracle Support matrix

      Acquire Oracle

      Production Oracle systems should run on certified platforms. Follow the metalink - note 223718.1to find certified platforms. If you don't have + note 223718.1to find certified platforms. If you don't have metalink access, take a look at the Oracle on Linux FAQ: Which Linux Distributions Are Directly Supported By Oracle?. In summary, free and inexpensive Linux distributions are not certified.

      - If you don't have an account at OTN + If you don't have an account at OTN get one: you can download the Oracle software from the Oracle Downloads page. It is also get the CDs shipped to you for a nominal fee from the Oracle @@ -45,20 +45,20 @@ both of which are considered to be very stable.

      To be able to download a patchset, you need a (to-pay-for) account on Metalink. You may find the appropriate - patchset by following Andrew's + patchset by following Andrew's suggestion.

      Things to Keep in Mind

      Oracle is very well-documented software, the online documentation comes with printable PDFs and full-text search. Altogether there is more than 20.000 pages of documentation, so do not expect to understand Oracle within in a few hours. The best starting pointing into Oracle is the - Concepts book. Here's the 8i + Concepts book. Here's the 8i version and the 9.2 version.

      To give you an idea of how configurable Oracle is and how much thought you may need to put into buying the proper hardware and creating a sane - setup, you should thoroughly read Cary Millsap's Configuring + setup, you should thoroughly read Cary Millsap's Configuring Oracle Server for VLDB and the Optimal Flexible Architecture standard.

      @@ -87,7 +87,7 @@ For additional resources/documentation, please see this thread and Andrew - Piskorski's mini-guide. + Piskorski's mini-guide.

      Pre-Installation Tasks

      @@ -156,7 +156,7 @@ root:/ora8# chown -R oracle.dba /ora8 root:/ora8# exit

    • - Set up the oracle user's + Set up the oracle user's environment

      • @@ -326,7 +326,7 @@ oracle:/where/oracle/Disk1$ ls doc index.htm install runInstaller stage starterdb

        - If you don't see + If you don't see runInstaller, you are in the wrong directory. @@ -532,7 +532,7 @@ Run the script. Switch to the oracle user first to set the environment appropriately and then do su to get root privileges, while keeping - the oracle user's enviroment. + the oracle user's enviroment. 

         [joeuser ~]$ su - oracle
 Password: *********
@@ -649,7 +649,7 @@

    Congratulations, you have just installed Oracle 8.1.7 Server! However, you still need to create a database which can take about an - hour of non-interactive time, so don't quit yet. + hour of non-interactive time, so don't quit yet.

    Creating the First Database

    This step will take you through the steps of creating a customized database. Be warned that this process takes about an hour on a @@ -744,7 +744,7 @@

  • Finally, select "Save information to a shell script" and click - "Finish" (We're + "Finish" (We're going to examine the contents of this file before creating our database.)

  • @@ -775,7 +775,7 @@ 

     nls_date_format = "YYYY-MM-DD"

  • Now find the open_cursors line - in the file. If you're using + in the file. If you're using emacs scroll up to the top of the buffer and do CTRL-S and type open_cursors to find the @@ -813,22 +813,22 @@ "ORA-01432: public synonym to be dropped does not exist") Fear not, this is normal.

    - Eventually, you'll be returned to your shell prompt. In the - meantime, relax, you've earned it. + Eventually, you'll be returned to your shell prompt. In the + meantime, relax, you've earned it.

    • Acceptance Test

    For this step, open up a terminal and su to oracle as usual. You should be running X and Netscape (or other web browser) for this phase.

    • You need to download the "Oracle Acceptance Test" file. - It's available here and at http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt. + It's available here and at http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt. Save the file to /var/tmp

    • In the oracle shell, copy the file. 

       [oracle ~]$ cp /var/tmp/acceptance-sql.txt /var/tmp/acceptance.sql

    • - Once you've got the acceptance test file all set, stay in + Once you've got the acceptance test file all set, stay in your term and type the following: 

       [oracle ~]$ sqlplus system/manager

      @@ -839,25 +839,25 @@ [oracle ~]$ svrmgrl SVRMGR> connect internal SVRMGR> startup

    • - Now that you're into SQL*Plus, change the default passwords + Now that you're into SQL*Plus, change the default passwords for system, sys, and ctxsys to "alexisahunk" (or to - something you'll remember): + something you'll remember): 

       SQL> alter user system identified by alexisahunk;
 SQL> alter user sys identified by alexisahunk;
 SQL> alter user ctxsys identified by alexisahunk;

    • Verify that your date settings are correct. 

       SQL> select sysdate from dual;

      - If you don't see a date that fits the format + If you don't see a date that fits the format YYYY-MM-DD, please read the section called “Troubleshooting Oracle Dates”.

    • At this point we are going to hammer your database with an intense acceptance test. This usually takes around 30 minutes. 

       SQL> @ /var/tmp/acceptance.sql
 
-; A bunch of lines will scroll by.  You'll know if the test worked if
+; A bunch of lines will scroll by.  You'll know if the test worked if
 ; you see this at the end:
 
 SYSDATE
@@ -879,13 +879,13 @@
           can set the parameter using the
           dbassist program or by setting
           the DB_BLOCK_SIZE parameter in
-          your database's creation script.
+          your database's creation script.
         
      
           If there were no errors, then consider yourself fortunate. Your
           Oracle installation is working.

    Automating Startup & Shutdown

    You will want to automate the database startup and shutdown process. - It's probably best to have Oracle spring to life when you boot up + It's probably best to have Oracle spring to life when you boot up your machine.

    • Oracle includes a script called @@ -900,7 +900,7 @@ [oracle ~]$ cp /var/tmp/dbstart.txt /ora8/m01/app/oracle/product/8.1.7/bin/dbstart [oracle ~]$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/dbstart

    • - While you're logged in as + While you're logged in as oracle, you should configure the oratab file to load your database at start. Edit the file @@ -1165,7 +1165,7 @@ the number of seconds elapsed since some date. However, for the purposes of inputing dates into Oracle and getting them back out, Oracle needs to be told to use a specific date format. By default, it - uses an Oracle-specific format which isn't copacetic. You want + uses an Oracle-specific format which isn't copacetic. You want Oracle to use the ANSI-compliant date format which is of form 'YYYY-MM-DD'.

      @@ -1190,7 +1190,7 @@ SQL> select sysdate from dual;

      If the date does not conform to this format, double-check that you included the necessary line in the init scripts. If it still - isn't working, make sure that you have restarted the database + isn't working, make sure that you have restarted the database since adding the line: 

       [joeuser ~]$ svrmgrl
@@ -1202,7 +1202,7 @@
 ORACLE instance shut down.
 SVRMGR> startup
 ORACLE instance started.

      - If you're sure that you have restarted the database since adding + If you're sure that you have restarted the database since adding the line, check your initialization scripts. Make sure that the following line is not included: 

      @@ -1214,7 +1214,7 @@
     
       export nls_date_format = 'YYYY-MM-DD'
      
       Log back in again. If adding the
-      nls_date_format line doesn't
+      nls_date_format line doesn't
       help, you can ask for advice in our OpenACS forums.

    Useful Procedures

    • Dropping a tablespace Index: openacs-4/packages/acs-core-docs/www/os-install.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/os-install.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/os-install.adp 23 Sep 2015 11:54:45 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/os-install.adp 23 Jun 2016 08:32:45 -0000 1.1.2.2 @@ -9,7 +9,8 @@ rightLink="os-security" rightLabel="Next">

      -Linux Install Guides

      Here's a list of some helpful documentation for various OS's

        +Linux Install Guides

    Here's a list of some helpful documentation for various +OS's

    • Painless Debian GNU/Linux by Stephen van Egmond

    • Official Debian Guide

    • RedHat

    • Mandrake

    • SuSE

      • Index: openacs-4/packages/acs-core-docs/www/os-install.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/os-install.html,v diff -u -N -r1.16.2.1 -r1.16.2.2 --- openacs-4/packages/acs-core-docs/www/os-install.html 9 Jun 2016 08:44:50 -0000 1.16.2.1 +++ openacs-4/packages/acs-core-docs/www/os-install.html 23 Jun 2016 08:32:45 -0000 1.16.2.2 @@ -1,6 +1,6 @@ Linux Install Guides
      Alex logo
      Prev Appendix C. Credits Next

      Linux Install Guides

      - Here's a list of some helpful documentation for various OS's + Here's a list of some helpful documentation for various OS's

      • Painless Debian GNU/Linux by Stephen van Egmond Index: openacs-4/packages/acs-core-docs/www/os-security.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/os-security.adp,v diff -u -N -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/os-security.adp 23 Sep 2015 11:54:45 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/os-security.adp 23 Jun 2016 08:32:45 -0000 1.1.2.2 @@ -9,18 +9,18 @@ rightLink="install-resources" rightLabel="Next">

        -Security Information

        Once you get your OS installed, it's imperative that you secure -your installation. As Jon Griffin repeatedly warns us, "No -distribution is secure out of the box." The Reference Platform -implements some basic precautions, but security is a process, not a -condition. If you are responsible for a computer hooked to the -internet, you are responsible for learning some rudiments of -security, such as monitoring the state of a computer, maintaining -patch levels, and keeping backups. We recommend these +Security Information

      Once you get your OS installed, it's imperative that you +secure your installation. As Jon Griffin repeatedly warns us, +"No distribution is secure out of the box." The Reference +Platform implements some basic precautions, but security is a +process, not a condition. If you are responsible for a computer +hooked to the internet, you are responsible for learning some +rudiments of security, such as monitoring the state of a computer, +maintaining patch levels, and keeping backups. We recommend these resources:

    Security Information
    Alex logo
    Prev Appendix C. Credits Next

    Security Information

    - Once you get your OS installed, it's imperative that you secure your + Once you get your OS installed, it's imperative that you secure your installation. As Jon Griffin repeatedly warns us, "No distribution is secure out of the box." The Reference Platform implements some basic precautions, but security is a process, not a @@ -13,7 +13,7 @@ Securing and Optimizing Linux - version 2.0

  • Jon - Griffin's notes + Griffin's notes

  • Linux Administrators Security Guide @@ -22,5 +22,5 @@ of a Secure Webserver

  • Bruce - Schneier's Crypto-Gram, especially The + Schneier's Crypto-Gram, especially The security patch treadmill and Monitoring First.

    • Prev Home Next
    Linux Install Guides Up Resources
    docs@openacs.org
    View comments on this page at openacs.org
    Index: openacs-4/packages/acs-core-docs/www/packages.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/packages.adp,v diff -u -N -r1.1.2.11 -r1.1.2.12 --- openacs-4/packages/acs-core-docs/www/packages.adp 21 Jun 2016 07:44:36 -0000 1.1.2.11 +++ openacs-4/packages/acs-core-docs/www/packages.adp 23 Jun 2016 08:32:45 -0000 1.1.2.12 @@ -25,8 +25,8 @@

    Server file layout

    Here is how an OpenACS 5 server is laid out starting from the Server root (ROOT):

    -

    Figure 11.1. Server -file layout diagram

    +
    Figure 11.1. Server file layout
+diagram
     ROOT/
     bin/
         Various executables and scripts for server maintanence.
@@ -59,14 +59,14 @@
 the packages that have been installed in the server, where those
 packages have been installed, and a standard way to map URLs that a
 client sends to our server to the right page in the appropriate
-package. While we're at it, this tool should also automate package
-installation, dependency checking, upgrades, and package removal.
-In OpenACS 5, this tool is called the APM.
    
+package. While we're at it, this tool should also automate
+package installation, dependency checking, upgrades, and package
+removal. In OpenACS 5, this tool is called the APM.
    
  To illustrate
-the general structure of a package, let's see what the package for
-the "notes" application should look like.
    
-
    Figure 11.2. Package
-file layout diagram
    +the general structure of a package, let's see what the package
+for the "notes" application should look like.
    
+
    Figure 11.2. Package file layout
+diagram
     ROOT/
   +-- packages/    APM Root
         |
@@ -262,9 +262,9 @@
 each instance maintains its own set of application parameters and
 options.
    The following sections will show you how to make a package for
 the Notes application. In addition, they will discuss some site
-management features in OpenACS 5 that take advantage of the APM's
-package instance model. The two most important of these are
-subsites, and the
+management features in OpenACS 5 that take advantage of the
+APM's package instance model. The two most important of these
+are subsites, and the
 site map tool, which can be
 used to map applications to one or more arbitrary URLs in a running
 site.
    We will also discuss how to organize your files and queries so
@@ -274,8 +274,8 @@
 Making a Package
    Here is how you make a package.
      
 
    1. Login as a site-wide administrator on your web service.
    2. Go to the package manager on your server. The URL is /acs-admin/apm.
    3. Click on the link /acs-admin/apm/package-add.
    4. 
 
      Fill out the form for adding a new package. The form explains
-what everything means, but we'll repeat the important bits here for
-easy reference:
      
+what everything means, but we'll repeat the important bits here
+for easy reference:
      
 
      Package Key
      This is a short text string that should uniquely name your
 package to distinguish it from all the others. It is used as a
 database key to keep track of the package and as the name of the
@@ -285,9 +285,9 @@
 application, we will use the package key notes.
      Package Name
      This is a short human readable name for your package. For our
 example, we will use the name "Notes".
      Package Plural
      If your package name is a nice singular noun, this should be the
 plural form of it. I assume the plural form is used when multiple
-instances of the package are used by a single service. We'll talk
-more about package instances later. Our example apllication doesn't
-really have a good plural name. So just make it also be
+instances of the package are used by a single service. We'll
+talk more about package instances later. Our example apllication
+doesn't really have a good plural name. So just make it also be
 "Notes".
      Package Type
      Generally we think of packages as either being applications, meaning that the package
 is meant primarily for use by end-users, or services meaning that the package is
 meant to be a reusable library of code, to be used by other
@@ -302,27 +302,27 @@
 
      The directory that APM created will be empty except for the
 notes.info file. Create a file
 called ROOT/packages/notes/sql/oracle/notes-create.sql.
-We'll fill this file with our data model
-very soon. Create a file called ROOT/packages/notes/sql/oracle/notes-drop.sql.
+We'll fill this file with our data model very
+soon. Create a file called ROOT/packages/notes/sql/oracle/notes-drop.sql.
 This will contain the instructions to drop the data model. To be
 complete, you would also create the PostgreSQL versions of these
 files as well in ROOT/packages/notes/sql/postgresql/notes-create.sql
 and ROOT/packages/notes/sql/postgresql/notes-drop.sql.
      After you do this, go back to the main APM page. From there,
-click the link called "notes" to go to the management page for the
-new package. Now click the link called "Manage file information",
-then the "Scan the packages/notes directory for additional
-files in this package" link on that page to scan the file system
-for new files. This will bring you do a page that lists all the
-files you just added and lets you add them to the notes package.
      Note that while the .sql
+click the link called "notes" to go to the management
+page for the new package. Now click the link called "Manage
+file information", then the "Scan the packages/notes directory for additional
+files in this package" link on that page to scan the file
+system for new files. This will bring you do a page that lists all
+the files you just added and lets you add them to the notes package.
      Note that while the .sql
 files have been added to the packge, they have not been loaded into the database.
 For the purposes of development, you have to load the data model by
 hand, because while OpenACS has automatic mechanisms for loading
 and reloading .tcl files for
 code, it does not do the same thing for data model files.
      
 
    5. Now go back to the main management page for the notes If your package has parameters,
-create them using the "Manage Parameter Information" link. Define
-package callbacks via the "Tcl Callbacks (install, instantiate,
-mount)" link.
    6. 
+create them using the "Manage Parameter Information"
+link. Define package callbacks via the "Tcl Callbacks
+(install, instantiate, mount)" link.
    7. 
 
      The new package has been created and installed in the server. At
 this point, you should add your package files to your CVS
 repository. I'll assume that you have set up your development
@@ -346,11 +346,11 @@
 
    
 
    
 The Site Map and Package Instances
    At this point, you are probably excited to see your new package
-in action. But, we haven't added any user visible pages yet. By
+in action. But, we haven't added any user visible pages yet. By
 convention, user visible pages go in the ROOT/packages/notes/www directory. So go
 there and add a file called hello.html with some text in it. Now we
-have to make the user pages visible in the site. Since we didn't
-put the pages underneath ROOT/www they will not appear on their own.
+have to make the user pages visible in the site. Since we
+didn't put the pages underneath ROOT/www they will not appear on their own.
 What we have to do is mount
 the application into the site map. That is, we have to define the
 URL from which the application will serve its pages.
    In OpenACS 5, administrators can define an arbitrary mapping
@@ -375,16 +375,17 @@
 to mount it in the site map. You do this by going to the Site Map page,
 which is by default available at /acs-admin/site-map. Use the interface here
 to add a new sub-folder called notes to the root of the site, then click
-"new application" to mount a new instance of the notes application to the site. Name the new
-instance notes-1.
    Then type this URL into your browser: http://yourserver/notes/hello.html
+"new application" to mount a new instance of the
+notes application to the site.
+Name the new instance notes-1.
    Then type this URL into your browser: http://yourserver/notes/hello.html
 
    Now you should see the contents of the page that you added. What
 has happened is that all URLs that start with /notes have been mapped in such a way as to
 serve content from the directory ROOT/packages/notes/www. At this point, you
 can experiment with the site map by mounting multiple instances of
 the not yet written Notes application at various places in the
-site. In a later document, we'll see how to write your application
-so that the code can detect from what URL it was invoked. This is
-the key to supporting subsites.
    
+site. In a later document, we'll see how to write your
+application so that the code can detect from what URL it was
+invoked. This is the key to supporting subsites.
    
 
    
 
    
 Summary
    The APM performs the following tasks in an OpenACS site:
      
@@ -393,15 +394,15 @@
 packages.
    • Manages package upgrades.
    • Manages information on all package instances in a site. For correctly
 written application packages, this allows the site administrator to
 map multiple instances of a package to URLs within a site.
    • Writes out package distribution files for other people to
-download and install. We'll cover this later.
      • 
+download and install. We'll cover this later.
      
 
    
 
    
 
    
 Additional Reading
    ($‌Id: packages.xml,v 1.9 2006/07/17 05:38:37
-torbenb Exp $)
    
+
    ($‌Id: packages.html,v 1.51.2.10 2016/06/21
+07:44:36 gustafn Exp $)
    
 
    
 
    
 APM.
     
    
       
-      To illustrate the general structure of a package, let's see what the
+      To illustrate the general structure of a package, let's see what the
       package for the "notes" application should look like.
     
    Figure 11.2. Package file layout diagram
     ROOT/
@@ -259,7 +259,7 @@
     
  • Go to the package manager on your server.  The URL is /acs-admin/apm.
     
  • Click on the link /acs-admin/apm/package-add.
     
  • Fill out the form for adding a new package. The form explains what
-      everything means, but we'll repeat the important bits here for easy
+      everything means, but we'll repeat the important bits here for easy
       reference:
 
       
    Package Key
@@ -279,8 +279,8 @@
           
    
           If your package name is a nice singular noun, this should be the
           plural form of it. I assume the plural form is used when multiple
-          instances of the package are used by a single service. We'll talk more
-          about package instances later. Our example apllication doesn't really
+          instances of the package are used by a single service. We'll talk more
+          about package instances later. Our example apllication doesn't really
           have a good plural name. So just make it also be "Notes".
         
    Package Type
           
    
@@ -314,7 +314,7 @@
           The directory that APM created will be empty except for the
           notes.info file. Create a file
           called
-          ROOT/packages/notes/sql/oracle/notes-create.sql. We'll
+          ROOT/packages/notes/sql/oracle/notes-create.sql. We'll
           fill this file with our data model
           very soon. Create a file called
           ROOT/packages/notes/sql/oracle/notes-drop.sql. This
@@ -364,11 +364,11 @@
       you should also consider the tasks outlined in the package development tutorial.
     
    • The Site Map and Package Instances
    
       At this point, you are probably excited to see your new package in
-      action. But, we haven't added any user visible pages yet. By
+      action. But, we haven't added any user visible pages yet. By
       convention, user visible pages go in the
       ROOT/packages/notes/www directory. So go there and add a
       file called hello.html with some text in it. Now we have
-      to make the user pages visible in the site. Since we didn't put the
+      to make the user pages visible in the site. Since we didn't put the
       pages underneath ROOT/www they will not appear on their
       own.  What we have to do is mount the application into the site
       map. That is, we have to define the URL from which the application
@@ -409,7 +409,7 @@
       ROOT/packages/notes/www. At this point, you can
       experiment with the site map by mounting multiple instances of the not
       yet written Notes application at various places in the site. In a
-      later document, we'll see how to write your application so that the
+      later document, we'll see how to write your application so that the
       code can detect from what URL it was invoked. This is the key
       to supporting subsites.
     
    Summary
    
@@ -426,5 +426,5 @@
       site.
     
  • 
       Writes out package distribution files for other people to download and
-      install. We'll cover this later.
+      install. We'll cover this later.

    • Additional Reading

    ($Id$)
    Prev Home Next
    Chapter 11. Development Reference Up OpenACS Data Models and the Object System
    docs@openacs.org
    View comments on this page at openacs.org
    Index: openacs-4/packages/acs-core-docs/www/parties.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/parties.adp,v diff -u -N -r1.1.2.3 -r1.1.2.4 --- openacs-4/packages/acs-core-docs/www/parties.adp 28 Sep 2015 07:54:21 -0000 1.1.2.3 +++ openacs-4/packages/acs-core-docs/www/parties.adp 23 Jun 2016 08:32:45 -0000 1.1.2.4 @@ -22,10 +22,11 @@ and groups are treated identically. Modelling individuals and groups as specializations of one supertype is a practical way to manage both. This concept is so mundane that there is no need to -invent special terminology. This supertype is called a "party".

    A classic example of the "party" supertype is evident in address -books. A typical address book might contain the address of a -doctor, grocery store, and friend. The first field in an entry in -the address book is not labeled a person or company, but a +invent special terminology. This supertype is called a +"party".

    A classic example of the "party" supertype is evident +in address books. A typical address book might contain the address +of a doctor, grocery store, and friend. The first field in an entry +in the address book is not labeled a person or company, but a "party".

    @@ -123,10 +124,10 @@ membership relations and composite relations. The full range of sophisticated group structures that exist in the real world can be modelled in OpenACS by these two relationship types.

    Membership relations represent direct membership relation -between parties and groups. A party may be a "member" of a group. -Direct membership relations are common in administrative practices, -and do not follow basic set theory rules. If A is a member of B, -and B is a member of C, A is not a member of C. Membership +between parties and groups. A party may be a "member" of +a group. Direct membership relations are common in administrative +practices, and do not follow basic set theory rules. If A is a +member of B, and B is a member of C, A is not a member of C. Membership relations are not transitive.

    Composition relation represents composite relation between two groups. Composite relation is transitive. That is, it works like memberships in set @@ -228,13 +229,14 @@ Views

    The parties data model does a reasonable job of representing many of the situations one is likely to encounter when modeling organizational structures. We still need to be able to efficiently -answer questions like "what members are in this group and all of -its components?", and "of what groups is this party a member either -directly or indirectly?". Composition relations allow you to -describe an arbitrary Directed Acyclic Graph (DAG) between a group -and its components. For these reasons the party system provides a -bunch of views that take advantage of the internal representation -of group relations to answer questions like these very quickly.

    The group_component_map view +answer questions like "what members are in this group and all +of its components?", and "of what groups is this party a +member either directly or indirectly?". Composition relations +allow you to describe an arbitrary Directed Acyclic Graph (DAG) +between a group and its components. For these reasons the party +system provides a bunch of views that take advantage of the +internal representation of group relations to answer questions like +these very quickly.

    The group_component_map view returns all the subcomponents of a group including components of sub components and so forth. The container_id column is the group_id of the group in which component_id is directly contained. This allows you to easily distinguish whether a component is a direct Index: openacs-4/packages/acs-core-docs/www/permissions-design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-design.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-core-docs/www/permissions-design.adp 9 Jun 2016 08:44:50 -0000 1.1.2.2 +++ openacs-4/packages/acs-core-docs/www/permissions-design.adp 23 Jun 2016 08:32:45 -0000 1.1.2.3 @@ -30,11 +30,11 @@ is an operation a site administrator is able to assign to a particular user. Or perhaps an application developer might decide that viewing a certain set of pages within the application is an -operation to be individually granted or revoked from a user. It's -expected that the Permissions system will be seeing a lot of use - -almost every page will make at least one permissions API call, and -some will make several.

    For programmers, the Permissions API provides a means to work -with access control in a consistent manner. If a programmer's +operation to be individually granted or revoked from a user. +It's expected that the Permissions system will be seeing a lot +of use - almost every page will make at least one permissions API +call, and some will make several.

    For programmers, the Permissions API provides a means to work +with access control in a consistent manner. If a programmer's OpenACS package defines new methods for itself, the Permissions API must provide simple calls to determine whether the current user is authorized to perform the given method. In addition, using the @@ -52,9 +52,9 @@ registered user to access its pages read-only, but only allow members of a certain group to make changes. The way this group was determined also varied greatly between modules. Some modules used -"roles", while others did not. Other modules did all access control -based simply on coded rules regarding who can act on a given -database row based on the information in that row.

    Problems resulting from this piecemeal approach to permissions +"roles", while others did not. Other modules did all +access control based simply on coded rules regarding who can act on +a given database row based on the information in that row.

    Problems resulting from this piecemeal approach to permissions and access control were many, the two major ones being inconsistency, and repeated/redundant code. Thus the drive in OpenACS 4 to provide a unified, consistent permissions system that @@ -90,10 +90,10 @@

    There are also a number of views to make it easier to ask specific questions about permissions. For example, a number of the -above tables describe "direct" or explicit permissions. Inheritance -and default values can, however, introduce permissions which are -not directly specified. (For example, read access on a forum allows -read access on all the messages in the forum.)

    The following views provide flattened versions of inherited +above tables describe "direct" or explicit permissions. +Inheritance and default values can, however, introduce permissions +which are not directly specified. (For example, read access on a +forum allows read access on all the messages in the forum.)

    The following views provide flattened versions of inherited information:

    acs_privilege_method_map

    Map of privileges to the methods they contain either directly or because of another privilege which is included (at any depth).

    acs_object_grantee_priv_map

    Relation on (object, @@ -124,8 +124,8 @@ indirectly a member of

  • privileges get associated with the methods of any other privileges they have taken methods from (at any level) (see acs_privilege_hierarchy)

  • objects get access control from direct grants, or inherit -permissions from their context (unless the "don't inherit" flag is -set)

    • +permissions from their context (unless the "don't +inherit" flag is set)

    @@ -134,37 +134,39 @@

  • Modification of methods and privileges

  • Modification of permissions

  • Queries on permissions

    • "Modification of methods and -privileges." This refers to actions that happen -mainly at package installation time - a package will create a -number of methods for its own use, then associate them with the -system's standard privileges, or new privileges which the package -has created. The association step might also happen later, if the -site-wide administrator chooses to change permissions policy.

    These steps involve directly manipulating the acs_methods, acs_privileges, and acs_privilege_method_rules tables. A web +privileges." This refers to actions that +happen mainly at package installation time - a package will create +a number of methods for its own use, then associate them with the +system's standard privileges, or new privileges which the +package has created. The association step might also happen later, +if the site-wide administrator chooses to change permissions +policy.

    These steps involve directly manipulating the acs_methods, acs_privileges, and acs_privilege_method_rules tables. A web page for manipulating these features should be limited to site-wide administrators.

    "Modification of -permissions" - involves fairly common operations. -Users are typically able to administer permissions for objects they -themselves create. The two basic operations here are "grant" and -"revoke". Granting permissions is done via acs_permissions.grant_permission, and +permissions" - involves fairly common +operations. Users are typically able to administer permissions for +objects they themselves create. The two basic operations here are +"grant" and "revoke". Granting permissions is +done via acs_permissions.grant_permission, and revocation via acs_permissions.revoke_permission. These directly manipulate the acs_permissions table.

    Web pages for making these changes are available to all users, so they should not be in an admin area. In order to grant and revoke permissions on an object, the user must have the administer_privileges method permission on that object.

    "Queries on -permissions" - by far the most common operation is -querying the permissions database. Several kinds of questions are -commonly asked: First, and most commonly, "Can this party perform -this method on this object?" Two Tcl functions are provided to -answer this - one which returns a boolean, the other of which -results in an error page. These tcl functions directly access the -acs_object_party_method_map.

    The second most commonly asked question occurs when a list of +permissions" - by far the most common +operation is querying the permissions database. Several kinds of +questions are commonly asked: First, and most commonly, "Can +this party perform this method on this object?" Two Tcl +functions are provided to answer this - one which returns a +boolean, the other of which results in an error page. These tcl +functions directly access the acs_object_party_method_map.

    The second most commonly asked question occurs when a list of objects is being displayed, often in order to provide appropriate -UI functionality: "For this party, what methods are available on -these objects?" Here, the SQL query needs to filter based on -whether the party/user can perform some operation on the object. +UI functionality: "For this party, what methods are available +on these objects?" Here, the SQL query needs to filter based +on whether the party/user can perform some operation on the object. This is done via a join or sub-select against acs_object_party_method_map, or by calling the Tcl functions for appropriate methods.

    Finally, when administering the permissions for an object, a web page needs to know all permissions directly granted on that object. @@ -204,9 +206,9 @@ privilege acs_permissions.privilege%TYPE );

    These procedures are defined in permissions-create.sql -

    Tcl Procedures

    Two tcl procedures provide a simple call for the query, "Can -this user perform this method on this object?" One returns true or -false, the other presents an error page.

    To receive a true or false value, Tcl code should call:

    +
    Tcl Procedures
    Two tcl procedures provide a simple call for the query,
+"Can this user perform this method on this object?" One
+returns true or false, the other presents an error page.
    To receive a true or false value, Tcl code should call:
     permission::permission_p -object_id $object_id -party_id $user_id -privilege $method
 
    If the user_id argument is
 left out, then the currently logged in user is checked. To create
@@ -226,10 +228,10 @@
 providing a list of all possible permissions and a list of all
 parties in the system. (For large sites, some future search
 mechanism will be necessary.) After choosing privileges to grant,
-the user is returned to the "edit privileges for one object"
-screen.
    If it makes sense, the system will also display a checkbox which
+the user is returned to the "edit privileges for one
+object" screen.
    If it makes sense, the system will also display a checkbox which
 the user may select to toggle whether permissions are inherited
-from the object's context.
    There are a number of potential future enhancements for the
+from the object's context.
    There are a number of potential future enhancements for the
 permissions UI, outlined below.

    @@ -242,9 +244,9 @@ likely to be in the UI:

    • There should be a page displaying a list of all objects for which the current user is allowed to administer privileges.

    • Users should be able to view the permissions on any object, or -perhaps on objects which they have the "read_permissions" method. -This would allow them to see what grants are affecting their -objects through inheritance.

      • +perhaps on objects which they have the "read_permissions" +method. This would allow them to see what grants are affecting +their objects through inheritance.

    Index: openacs-4/packages/acs-core-docs/www/permissions-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-design.html,v diff -u -N -r1.34.2.1 -r1.34.2.2 --- openacs-4/packages/acs-core-docs/www/permissions-design.html 9 Jun 2016 08:44:50 -0000 1.34.2.1 +++ openacs-4/packages/acs-core-docs/www/permissions-design.html 23 Jun 2016 08:32:45 -0000 1.34.2.2 @@ -12,10 +12,10 @@ bans a user from a sub-site is an operation a site administrator is able to assign to a particular user. Or perhaps an application developer might decide that viewing a certain set of pages within the application is an operation to -be individually granted or revoked from a user. It's expected that the +be individually granted or revoked from a user. It's expected that the Permissions system will be seeing a lot of use - almost every page will make at least one permissions API call, and some will make several.

    For programmers, the Permissions API provides a means to work with access -control in a consistent manner. If a programmer's OpenACS package defines new +control in a consistent manner. If a programmer's OpenACS package defines new methods for itself, the Permissions API must provide simple calls to determine whether the current user is authorized to perform the given method. In addition, using the Permissions API, queries should easily select only @@ -92,12 +92,12 @@ a member of

  • privileges get associated with the methods of any other privileges they have taken methods from (at any level) (see acs_privilege_hierarchy)

  • objects get access control from direct grants, or inherit permissions -from their context (unless the "don't inherit" flag is +from their context (unless the "don't inherit" flag is set)

    • Legal Transactions

    There are three essential areas in which all transactions in the permissions system fall:

    • Modification of methods and privileges

    • Modification of permissions

    • Queries on permissions

    "Modification of methods and privileges." This refers to actions that happen mainly at package installation time - a package will create a number of methods for its own use, then associate them with the -system's standard privileges, or new privileges which the package has +system's standard privileges, or new privileges which the package has created. The association step might also happen later, if the site-wide administrator chooses to change permissions policy.

    These steps involve directly manipulating the acs_methods, acs_privileges, and acs_privilege_method_rules tables. A @@ -170,7 +170,7 @@ large sites, some future search mechanism will be necessary.) After choosing privileges to grant, the user is returned to the "edit privileges for one object" screen.

    If it makes sense, the system will also display a checkbox which the user -may select to toggle whether permissions are inherited from the object's +may select to toggle whether permissions are inherited from the object's context.

    There are a number of potential future enhancements for the permissions UI, outlined below.

    Configuration/Parameters

    There are no configuration options for the permissions system.

    Future Improvements/Areas of Likely Change

    The most important future changes to the Permissions system are likely to be in the UI:

    • There should be a page displaying a list of all objects for which the Index: openacs-4/packages/acs-core-docs/www/permissions-requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-requirements.adp,v diff -u -N -r1.1.2.2 -r1.1.2.3 --- openacs-4/packages/acs-core-docs/www/permissions-requirements.adp 9 Jun 2016 08:44:50 -0000 1.1.2.2 +++ openacs-4/packages/acs-core-docs/www/permissions-requirements.adp 23 Jun 2016 08:32:45 -0000 1.1.2.3 @@ -21,26 +21,27 @@

    Vision Statement

    Any multi-user software system must address the general problem -of permissions, or "who can do what, on what." On web services, -which typically involve large numbers of users belonging to -different groups, permissions handling is a critical need: access -to content, services, and information generally must be controlled. -The OpenACS 4 Permissions system is meant to serve as a consistent, -unified interface for higher-level OpenACS applications to handle -permissions. Consolidating access control in such a manner reduces -both cost and risk: cost, in that less code has to be written and -maintained for dealing with recurring permissions situations; risk, -in that we need not rely on any single programmer's diligence to -ensure access control is implemented and enforced correctly.

    Historical +of permissions, or "who can do what, on what." On web +services, which typically involve large numbers of users belonging +to different groups, permissions handling is a critical need: +access to content, services, and information generally must be +controlled. The OpenACS 4 Permissions system is meant to serve as a +consistent, unified interface for higher-level OpenACS applications +to handle permissions. Consolidating access control in such a +manner reduces both cost and risk: cost, in that less code has to +be written and maintained for dealing with recurring permissions +situations; risk, in that we need not rely on any single +programmer's diligence to ensure access control is implemented +and enforced correctly.

    Historical Motivations

    In earlier versions of the OpenACS, permissions and access control was handled on a module-by-module basis, often even on a page-by-page basis. For example, a typical module might allow any registered user to access its pages read-only, but only allow members of a certain group to make changes. The way this group was determined also varied greatly between modules. Some modules used -"roles", while others did not. Other modules did all access control -based simply on coded rules regarding who can act on a given -database row based on the information in that row.

    Problems resulting from this piecemeal approach to permissions +"roles", while others did not. Other modules did all +access control based simply on coded rules regarding who can act on +a given database row based on the information in that row.

    Problems resulting from this piecemeal approach to permissions and access control were many, the two major ones being inconsistency, and repeated/redundant code. Thus the drive in OpenACS 4 to provide a unified, consistent permissions system that @@ -63,19 +64,20 @@ three-way relation, like that between the parts of most simple sentences. A simple sentence generally has three parts, a subject, an object, and a verb - in the context of OpenACS Permissions, our -simple sentence is, "Can this party perform this operation on this -target?" Definitions:

    The subject of the sentence is "party" - a distinguishable actor -whose access may be controlled, this special word is used because -one person may be represented by several parties, and one party may -represent many users (or no users at all).

    The object of the sentence is "target" - this is an entity, or -object, that the party wishes to perform some action on. An +simple sentence is, "Can this party perform this operation on +this target?" Definitions:

    The subject of the sentence is "party" - a distinguishable +actor whose access may be controlled, this special word is used +because one person may be represented by several parties, and one +party may represent many users (or no users at all).

    The object of the sentence is "target" - this is an entity, +or object, that the party wishes to perform some action on. An entity/object here is anything that can be put under access -control.

    The verb of the sentence is "operation" - a behavior on the -OpenACS system subject to control, this word is used to represent -the fact that a single operation may be part of many larger actions -the system wants to perform. If "foo" is an operation, than we -sometimes refer to the foo "privilege" to mean that a user has the -privilege to perform that operation.

    Examples of the essential question addressed by the Permissions +control.

    The verb of the sentence is "operation" - a behavior +on the OpenACS system subject to control, this word is used to +represent the fact that a single operation may be part of many +larger actions the system wants to perform. If "foo" is +an operation, than we sometimes refer to the foo +"privilege" to mean that a user has the privilege to +perform that operation.

    Examples of the essential question addressed by the Permissions system: Can jane\@attacker.com delete the web security forum? Can the Boston office (a party) within the VirtuaCorp intranet/website create its own news instance?

    @@ -91,12 +93,12 @@ OpenACS Objects data model).

    20.0 Operations

    The system itself must be able to answer the essential permissions question as well as several derived questions.

    20.10 Basic Access -Check

    The system must be able to answer the question, "May party P -perform operation O on target T?"

    +Check

    The system must be able to answer the question, "May party +P perform operation O on target T?"

    20.20 Allowed Parties -Check

    The system must be able to answer the question, "Which parties -may perform operation O on target T?"

    +Check

    The system must be able to answer the question, "Which +parties may perform operation O on target T?"

    20.30 Allowed Operations Check

    The system must be able to answer the question, "Which @@ -112,21 +114,23 @@ Requirements

    40.0 Scale of Privileges

    Privileges must be designed with appropriate scope for a given OpenACS package. Some privileges are of general utility (e.g. -"read" and "write"). Others are of more limited use (e.g. -"moderate" - applies mainly to a package like forum, where many -users are contributing content simultaneously). A package defining -its own privileges should do so with moderation, being careful not -to overload a privilege like "read" to mean too many things.

    50.0 Aggregation of Operations +"read" and "write"). Others are of more limited +use (e.g. "moderate" - applies mainly to a package like +forum, where many users are contributing content simultaneously). A +package defining its own privileges should do so with moderation, +being careful not to overload a privilege like "read" to +mean too many things.

    50.0 Aggregation of Operations (Privileges)

    For user interface purposes, it can be appropriate to group certain privileges under others. For example, anyone with the -"admin" privilege may also automatically receive "read", "write", -"delete", etc. privileges.

    60.0 Aggregation of Parties +"admin" privilege may also automatically receive +"read", "write", "delete", etc. +privileges.

    60.0 Aggregation of Parties (Groups)

    The system must allow aggregation of parties. The exact method used for aggregation will probably be addressed by the OpenACS 4 -"Groups" system. Regardless of the exact behavior of aggregate -parties, if an aggregate party exists, then access which is granted -to the aggregate party should be available to all members of that -aggregate.

    70.0 Scope of Access +"Groups" system. Regardless of the exact behavior of +aggregate parties, if an aggregate party exists, then access which +is granted to the aggregate party should be available to all +members of that aggregate.

    70.0 Scope of Access Control

    70.10 Context

    There must be a method for objects to receive default access control from some context. For example, if you do not have read Index: openacs-4/packages/acs-core-docs/www/permissions-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-requirements.html,v diff -u -N -r1.34.2.1 -r1.34.2.2 --- openacs-4/packages/acs-core-docs/www/permissions-requirements.html 9 Jun 2016 08:44:50 -0000 1.34.2.1 +++ openacs-4/packages/acs-core-docs/www/permissions-requirements.html 23 Jun 2016 08:32:45 -0000 1.34.2.2 @@ -13,7 +13,7 @@ applications to handle permissions. Consolidating access control in such a manner reduces both cost and risk: cost, in that less code has to be written and maintained for dealing with recurring permissions situations; risk, in -that we need not rely on any single programmer's diligence to ensure +that we need not rely on any single programmer's diligence to ensure access control is implemented and enforced correctly.

    Historical Motivations

    In earlier versions of the OpenACS, permissions and access control was handled on a module-by-module basis, often even on a page-by-page basis. For example, a typical module might allow any registered user to access its pages Index: openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.adp,v diff -u -N -r1.1.2.10 -r1.1.2.11 --- openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.adp 21 Jun 2016 07:44:36 -0000 1.1.2.10 +++ openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.adp 23 Jun 2016 08:32:46 -0000 1.1.2.11 @@ -130,8 +130,8 @@ Context Hierarchy

    Suppose objects A, B, ..., and F form the following hierarchy.

    -

    Table 11.2. Context -Hierarchy Example

    +

    Table 11.2. Context Hierarchy +Example

    @@ -156,8 +156,8 @@

    This can be represented in the acs_objects table by the following entries:

    -

    Table 11.3. acs_objects -example data

    +

    Table 11.3. acs_objects example +data

    @@ -195,8 +195,8 @@

    The fact that Joe can also read B, C, ..., and F can be derived by ascertaining that these objects are children of A by traversing the context hierarchy. As it turns out, hierarchical queries are expensive. As Rafael -Schloming put it so aptly, Oracle can't -deal with hierarchies for shit. +Schloming put it so aptly, Oracle +can't deal with hierarchies for shit.

    One way to solve this problem is to cache a flattened view of the context tree like so:

    @@ -295,9 +295,9 @@ end if; end;

    One final note about acs_objects. -By setting an object's security_inherit_p column to 'f', you can -stop permissions from cascading down the context tree. In the -following example, Joe does not have the read permissions on +By setting an object's security_inherit_p column to 'f', +you can stop permissions from cascading down the context tree. In +the following example, Joe does not have the read permissions on C and F.

    @@ -663,7 +663,7 @@ as exists_p char(1); begin - -- XXX This must be fixed: -1 shouldn't be hardcoded (it is the public) + -- XXX This must be fixed: -1 shouldn't be hardcoded (it is the public) select decode(count(*),0,'f','t') into exists_p from acs_object_party_privilege_map where object_id = permission_p.object_id Index: openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html,v diff -u -N -r1.46.2.10 -r1.46.2.11 --- openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 21 Jun 2016 07:44:36 -0000 1.46.2.10 +++ openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 23 Jun 2016 08:32:46 -0000 1.46.2.11 @@ -152,7 +152,7 @@ ..., and F can be derived by ascertaining that these objects are children of A by traversing the context hierarchy. As it turns out, hierarchical queries are expensive. As - Rafael Schloming put it so aptly, Oracle can't deal with hierarchies for shit. + Rafael Schloming put it so aptly, Oracle can't deal with hierarchies for shit.

    One way to solve this problem is to cache a flattened view of the context tree like so:

    objectancestorn_generations
    AA0
    BB0
    BA1
    CC0
    CA1
    DD0
    DB1
    DA2
    EE0
    EB1
    EA2
    FF0
    FC1
    FA2

    @@ -223,7 +223,7 @@

    One final note about acs_objects. By setting - an object's security_inherit_p column to 'f', you can stop permissions + an object's security_inherit_p column to 'f', you can stop permissions from cascading down the context tree. In the following example, Joe does not have the read permissions on C and F.

    @@ -615,7 +615,7 @@ as exists_p char(1); begin - -- XXX This must be fixed: -1 shouldn't be hardcoded (it is the public) + -- XXX This must be fixed: -1 shouldn't be hardcoded (it is the public) select decode(count(*),0,'f','t') into exists_p from acs_object_party_privilege_map where object_id = permission_p.object_id Index: openacs-4/packages/acs-core-docs/www/permissions.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions.adp,v diff -u -N -r1.1.2.5 -r1.1.2.6 --- openacs-4/packages/acs-core-docs/www/permissions.adp 9 Jun 2016 13:03:11 -0000 1.1.2.5 +++ openacs-4/packages/acs-core-docs/www/permissions.adp 23 Jun 2016 08:32:46 -0000 1.1.2.6 @@ -84,10 +84,10 @@ so that developers can define privileges that aggregate some set of privileges together. For example, if we have read, write, create and delete privileges, it might be convenient to combine them into -a new privilege called "admin". Then, when a user is granted -"admin" privilege, she is automatically granted all the child -privileges that the privilege contains. The OpenACS 5.9.0 kernel -data model defines these privileges:

    +a new privilege called "admin". Then, when a user is
+granted "admin" privilege, she is automatically granted
+all the child privileges that the privilege contains. The OpenACS
+5.9.0 kernel data model defines these privileges:
     # 
 begin
  acs_privilege.create_privilege('read');
@@ -125,8 +125,8 @@
 
    
 
    
 Object Context
    In OpenACS 5.9.0, object context is a scoping mechanism.
-"Scoping" and "scope" are terms best explained by example: consider
-some hypothetical rows in the address_book table:
    
+"Scoping" and "scope" are terms best explained
+by example: consider some hypothetical rows in the address_book table:
    
@@ -140,15 +140,13 @@
 
-
    
 
 
 
    ...public...
 
    
 
    The first row represents an entry in User 123's personal address
-book, the second row represents an entry in User Group 456's shared
-address book, and the third row represents an entry in the site's
-public address book. In this way, the scoping columns identify the
-security context in which a given object belongs, where each
-context is either a person
-or a group of people
-or the general public
-(itself a group of people).
    Every object lives in a single context. A context is just an another
+

    The first row represents an entry in User 123's personal +address book, the second row represents an entry in User Group +456's shared address book, and the third row represents an +entry in the site's public address book. In this way, the +scoping columns identify the security context in which a given +object belongs, where each context is either a person or a group of people or the general public (itself a group of +people).

    Every object lives in a single context. A context is just an another object that represents the security domain to which the object belongs. By convention, if an object A does not have any permissions explicitly attached to it, then the system will look at @@ -160,8 +158,8 @@

    If security_inherit_p flag is set to 't', then the automatic search through the context happens, otherwise it does -not. You might set this field to 'f' if you want to override the default -permissions in a subtree of some context.

    For an example of how to use context hierarchy, consider the +not. You might set this field to 'f' if you want to override the +default permissions in a subtree of some context.

    For an example of how to use context hierarchy, consider the forums application. With only row-level permissions it is not obvious how to reasonably initialize the access control list when creating a message. At best, we have to explicitly grant various @@ -171,14 +169,15 @@ forum. Then, suppose we grant every user in the system read-access to this forum. By default, they will automatically have read-access to the new message we just inserted, since the system automatically -checks permissions on the message's context. To allow the creator -of the message to change the message after it has been posted we -grant the user write-access on the message, and we are done.

    This mechanism allows developers and administrators to define a +checks permissions on the message's context. To allow the +creator of the message to change the message after it has been +posted we grant the user write-access on the message, and we are +done.

    This mechanism allows developers and administrators to define a hierarchy that matches the structure they need for access control in their application. The following picture shows a typical context -hierarchy for a hypothetical site:

    The top two contexts in the diagram are called "magic" numbers, -because in some sense, they are created by default by OpenACS for a -specific purpose. The object default_context represents the root of the +hierarchy for a hypothetical site:

    The top two contexts in the diagram are called "magic" +numbers, because in some sense, they are created by default by +OpenACS for a specific purpose. The object default_context represents the root of the context hierarchy for the entire site. All permission searches walk up the tree to this point and then stop. If you grant permissions on this object, then by default those permissions will hold for @@ -197,8 +196,8 @@ user rights.

  • The Context hierarchy allows you to define organize default permissions in a hierarchical fashion.

    • A PL/SQL or Tcl API is then used to check permissions in -application pages.

    ($‌Id: permissions.xml,v 1.17 2010/12/11 -23:36:32 ryang Exp $)
    +application pages.

    ($‌Id: permissions.html,v 1.50.2.10 2016/06/21 +07:44:36 gustafn Exp $)
    ...scopeuser_idgroup_id...
    ...user123 ...
    ...group 456...
    ...public ...

    The first row represents an entry in User 123's personal address book, the second row represents an entry in User Group 456's shared address -book, and the third row represents an entry in the site's public +book, and the third row represents an entry in the site's public address book. In this way, the scoping columns identify the security context in which a given object belongs, where each context is either a person or a group of people or the general public @@ -175,7 +175,7 @@ forum. Then, suppose we grant every user in the system read-access to this forum. By default, they will automatically have read-access to the new message we just inserted, since the system automatically -checks permissions on the message's context. To allow the creator of +checks permissions on the message's context. To allow the creator of the message to change the message after it has been posted we grant the user write-access on the message, and we are done.

    Index: openacs-4/packages/acs-core-docs/www/programming-with-aolserver.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/programming-with-aolserver.adp,v diff -u -N -r1.1.2.3 -r1.1.2.4 --- openacs-4/packages/acs-core-docs/www/programming-with-aolserver.adp 28 Sep 2015 07:54:22 -0000 1.1.2.3 +++ openacs-4/packages/acs-core-docs/www/programming-with-aolserver.adp 23 Jun 2016 08:32:46 -0000 1.1.2.4 @@ -18,12 +18,14 @@ two types of global namespace, not one:

    1. -Server-global: As you'd -expect, there is only one server-global namespace per server, and -variables set within it can be accessed by any Tcl code running -subsequently, in any of the server's threads. To set/get -server-global variables, use AOLserver 3's -nsv API (which supersedes ns_share from the pre-3.0 API).

    2. +Server-global: As +you'd expect, there is only one server-global namespace per +server, and variables set within it can be accessed by any Tcl code +running subsequently, in any of the server's threads. To +set/get server-global variables, use AOLserver 3's +nsv API (which +supersedes ns_share from the +pre-3.0 API).

    3. Script-global: Each Tcl script (ADP, Tcl page, registered proc, filter, etc.) executing within an AOLserver thread has its own global namespace. Any @@ -36,11 +38,12 @@ server-global, variables from within a procedure. This distinction is important to understand in order to use global correctly when programming AOLserver.

      Also, AOLserver purges all script-global variables in a thread -(i.e., Tcl interpreter) between HTTP requests. If it didn't, that -would affect (and complicate) our use of script-global variables -dramatically, which would then be better described as thread-global variables. Given -AOLserver's behaviour, however, "script-global" is a more -appropriate term.

      +(i.e., Tcl interpreter) between HTTP requests. If it didn't, +that would affect (and complicate) our use of script-global +variables dramatically, which would then be better described as +thread-global variables. +Given AOLserver's behaviour, however, "script-global" +is a more appropriate term.

    Threads and Scheduled @@ -50,14 +53,14 @@ -thread flag to cause a scheduled procedure to run asychronously, in its own thread. It almost always seems like a good idea to specify this switch, but -there's a problem.

    It turns out that whenever a task scheduled with ns_schedule_proc -thread or ad_schedule_proc -thread t is run, +there's a problem.

    It turns out that whenever a task scheduled with ns_schedule_proc -thread or ad_schedule_proc -thread t is run, AOLserver creates a brand new thread and a brand new interpreter, and reinitializes the procedure table (essentially, loads all procedures that were created during server initialization into the new interpreter). This happens every time the task is executed - and it is a very expensive process that should not be taken lightly!

    The moral: if you have a lightweight scheduled procedure which -runs frequently, don't use the -thread switch.

    Note also that thread is initialized +runs frequently, don't use the -thread switch.

    Note also that thread is initialized with a copy of what was installed during server startup, so if the procedure table have changed since startup (e.g. using the APM watch facility), that will not be @@ -73,9 +76,10 @@ triggered from inside a procedure e.g., a permission denied exception. At this point, the procedure that detects invalid permission wants to write an error message to the user, and -completely abort execution of the caller thread. return doesn't work, because the procedure -may be nested several levels deep. We therefore use ad_script_abort to -abort the remainder of the thread. Note that using return instead of ad_script_abort may raise some security +completely abort execution of the caller thread. return doesn't work, because the +procedure may be nested several levels deep. We therefore use +ad_script_abort to abort the remainder +of the thread. Note that using return instead of ad_script_abort may raise some security issues: an attacker could call a page that performed some DML statement, pass in some arguments, and get a permission denied error -- but the DML statement would still be executed because the @@ -88,13 +92,13 @@ Value From a Function

    Many functions have a single return value. For instance, util_email_valid_p returns a number: 1 or 0. Other functions need to return a composite value. For -instance, consider a function that looks up a user's name and email -address, given an ID. One way to implement this is to return a -three-element list and document that the first element contains the -name, and the second contains the email address. The problem with -this technique is that, because Tcl does not support constants, -calling procedures that returns lists in this way necessitates the -use of magic numbers, e.g.:

    +instance, consider a function that looks up a user's name and
+email address, given an ID. One way to implement this is to return
+a three-element list and document that the first element contains
+the name, and the second contains the email address. The problem
+with this technique is that, because Tcl does not support
+constants, calling procedures that returns lists in this way
+necessitates the use of magic numbers, e.g.:
     set user_info [ad_get_user_info $user_id]
 set first_name [lindex $user_info 0]
 set email [lindex $user_info 1]
@@ -128,17 +132,17 @@
     return [array get user_info]
 }
 
-
    Using Arrays and Pass-By-Reference
    Sometimes pass-by-value incurs too much overhead, and you'd
-rather pass-by-reference. Specifically, if you're writing a proc
-that uses arrays internally to build up some value, there are many
-entries in the array, and you're planning on iterating over the
-proc many times. In this case, pass-by-value is expensive, and
-you'd use pass-by-reference.
    The transformation of the array into
+

    Using Arrays and Pass-By-Reference

    Sometimes pass-by-value incurs too much overhead, and you'd +rather pass-by-reference. Specifically, if you're writing a +proc that uses arrays internally to build up some value, there are +many entries in the array, and you're planning on iterating +over the proc many times. In this case, pass-by-value is expensive, +and you'd use pass-by-reference.

    The transformation of the array into a list and back to an array takes, in our test environment, -approximately 10 microseconds per entry of 100 character's length. -Thus you can process about 100 entries per milisecond. The time -depends almost completely on the number of entries, and almost not -at all on the size of the entries.

    You implement pass-by-reference in Tcl by taking the name of an +approximately 10 microseconds per entry of 100 character's +length. Thus you can process about 100 entries per milisecond. The +time depends almost completely on the number of entries, and almost +not at all on the size of the entries.

    You implement pass-by-reference in Tcl by taking the name of an array as an argument and upvar it.

     
@@ -162,16 +166,16 @@
 Pass-by-reference makes the code harder to read and debug, because
 changing a value in one place has side effects in other places.
 Especially if have a chain of upvars through several layers of the call
-stack, you'll have a hard time debugging.
    Multisets: Using ns_sets and
-Pass-By-Reference
    An array is a type of set, which means you can't have multiple
-entries with the same key. Data structures that can have multiple
-entries for the same key are known as a multiset or bag.
    If your data can have multiple entries with the same key, you
+stack, you'll have a hard time debugging.
    Multisets: Using ns_sets and
+Pass-By-Reference
    An array is a type of set, which means you can't have
+multiple entries with the same key. Data structures that can have
+multiple entries for the same key are known as a multiset or bag.
    If your data can have multiple entries with the same key, you
 should use the AOLserver built-in ns_set. You can also
-do a case-insensitive lookup on an ns_set, something you can't easily do on an
-array. This is especially useful for things like HTTP headers,
-which happen to have these exact properties.
    You always use pass-by-reference with ns_sets, since they don't have any built-in
-way of generating and reconstructing themselves from a string
-representation. Instead, you pass the handle to the set.
    +do a case-insensitive lookup on an ns_set, something you can't easily do
+on an array. This is especially useful for things like HTTP
+headers, which happen to have these exact properties.
    You always use pass-by-reference with ns_sets, since they don't have any
+built-in way of generating and reconstructing themselves from a
+string representation. Instead, you pass the handle to the set.
     
 ad_proc ad_get_user_info {
     -set:required
@@ -189,11 +193,11 @@
 
 doc_body_append "[ns_set get $user_info namelink] ([ns_set get $user_info emaillink])"
 
-
    We don't recommend ns_set as
-a general mechanism for passing sets (as opposed to multisets) of
-data. Not only do they inherently use pass-by-reference, which we
-dis-like, they're also somewhat clumsy to use, since Tcl doesn't
-have built-in syntactic support for them.
    Consider for example a loop over the entries in a ns_set as compared to an array:
    +
    We don't recommend ns_set as a general mechanism for passing
+sets (as opposed to multisets) of data. Not only do they inherently
+use pass-by-reference, which we dis-like, they're also somewhat
+clumsy to use, since Tcl doesn't have built-in syntactic
+support for them.
    Consider for example a loop over the entries in a ns_set as compared to an array:
     
 # ns_set variant
 set size [ns_set size $myset]
@@ -226,8 +230,8 @@
 However, when using ns_set get
 to perform lookup by name, they perform a linear lookup, whereas
 arrays use a hash table, so ns_sets are slower than arrays when the
-number of entries is large.
    ($‌Id: programming-with-aolserver.xml,v 1.7
-2014/10/27 16:39:30 victorg Exp $)
    
+number of entries is large.
    ($‌Id: programming-with-aolserver.html,v
+1.49.2.10 2016/06/21 07:44:36 gustafn Exp $)

    The global command

    When using AOLserver, remember that there are effectively two types of global namespace, not one: -

    1. Server-global: As you'd expect, there is +

      1. Server-global: As you'd expect, there is only one server-global namespace per server, and variables set within it can -be accessed by any Tcl code running subsequently, in any of the server's +be accessed by any Tcl code running subsequently, in any of the server's threads. To set/get server-global variables, use AOLserver 3's nsv API (which supersedes ns_share from the pre-3.0 API).

      2. Script-global: Each Tcl script (ADP, Tcl page, @@ -21,23 +21,23 @@ procedure. This distinction is important to understand in order to use global correctly when programming AOLserver.

        Also, AOLserver purges all script-global variables in a thread (i.e., Tcl -interpreter) between HTTP requests. If it didn't, that would affect (and +interpreter) between HTTP requests. If it didn't, that would affect (and complicate) our use of script-global variables dramatically, which would then be better described as thread-global variables. Given -AOLserver's behaviour, however, "script-global" is a more +AOLserver's behaviour, however, "script-global" is a more appropriate term.

      Threads and Scheduled Procedures

      ns_schedule_proc and ad_schedule_proc each take a -thread flag to cause a scheduled procedure to run asychronously, in its own thread. It almost always seems like a good idea to -specify this switch, but there's a problem. +specify this switch, but there's a problem.

      It turns out that whenever a task scheduled with ns_schedule_proc -thread or ad_schedule_proc -thread t is run, AOLserver creates a brand new thread and a brand new interpreter, and reinitializes the procedure table (essentially, loads all procedures that were created during server initialization into the new interpreter). This happens every time the task is executed - and it is a very expensive process that should not be taken lightly!

      The moral: if you have a lightweight scheduled procedure -which runs frequently, don't use the -thread +which runs frequently, don't use the -thread switch.

      Note also that thread is initialized with a copy of what was installed during server startup, so if the procedure table have changed since startup (e.g. using the APM watch @@ -50,7 +50,7 @@ that can be triggered from inside a procedure e.g., a permission denied exception. At this point, the procedure that detects invalid permission wants to write an error message to the user, and completely abort execution of the -caller thread. return doesn't work, because the procedure may be +caller thread. return doesn't work, because the procedure may be nested several levels deep. We therefore use ad_script_abort to abort the remainder of the thread. Note that using return instead of ad_script_abort may raise some security issues: an attacker could @@ -62,7 +62,7 @@

      Returning More Than One Value From a Function

      Many functions have a single return value. For instance, util_email_valid_p returns a number: 1 or 0. Other functions need to return a composite value. -For instance, consider a function that looks up a user's name and email +For instance, consider a function that looks up a user's name and email address, given an ID. One way to implement this is to return a three-element list and document that the first element contains the name, and the second contains the email address. The problem with this technique is that, because @@ -106,14 +106,14 @@ }

      Using Arrays and Pass-By-Reference

      -Sometimes pass-by-value incurs too much overhead, and you'd rather -pass-by-reference. Specifically, if you're writing a proc that uses +Sometimes pass-by-value incurs too much overhead, and you'd rather +pass-by-reference. Specifically, if you're writing a proc that uses arrays internally to build up some value, there are many entries in the -array, and you're planning on iterating over the proc many times. In this -case, pass-by-value is expensive, and you'd use pass-by-reference. +array, and you're planning on iterating over the proc many times. In this +case, pass-by-value is expensive, and you'd use pass-by-reference.

      The transformation of the array into a list and back to an array takes, in our test environment, approximately 10 microseconds per entry -of 100 character's length. Thus you can process about 100 entries per +of 100 character's length. Thus you can process about 100 entries per milisecond. The time depends almost completely on the number of entries, and almost not at all on the size of the entries.

      You implement pass-by-reference in Tcl by taking the name of an array @@ -139,18 +139,18 @@

      We prefer pass-by-value over pass-by-reference. Pass-by-reference makes the code harder to read and debug, because changing a value in one place has side effects in other places. Especially if have a chain of -upvars through several layers of the call stack, you'll have +upvars through several layers of the call stack, you'll have a hard time debugging.

      Multisets: Using ns_sets and Pass-By-Reference

      -An array is a type of set, which means you can't have multiple +An array is a type of set, which means you can't have multiple entries with the same key. Data structures that can have multiple entries for the same key are known as a multiset or bag.

      If your data can have multiple entries with the same key, you should use the AOLserver built-in ns_set. You can also do a case-insensitive lookup on an -ns_set, something you can't easily do on an array. This is +ns_set, something you can't easily do on an array. This is especially useful for things like HTTP headers, which happen to have these exact properties.

      You always use pass-by-reference with ns_sets, since they -don't have any built-in way of generating and reconstructing themselves +don't have any built-in way of generating and reconstructing themselves from a string representation. Instead, you pass the handle to the set.

       
 ad_proc ad_get_user_info {
@@ -170,10 +170,10 @@
 doc_body_append "[ns_set get $user_info namelink] ([ns_set get $user_info emaillink])"

      -We don't recommend ns_set as a general mechanism for passing +We don't recommend ns_set as a general mechanism for passing sets (as opposed to multisets) of data. Not only do they inherently use -pass-by-reference, which we dis-like, they're also somewhat clumsy to -use, since Tcl doesn't have built-in syntactic support for them. +pass-by-reference, which we dis-like, they're also somewhat clumsy to +use, since Tcl doesn't have built-in syntactic support for them.

      Consider for example a loop over the entries in a ns_set as compared to an array:

       
Index: openacs-4/packages/acs-core-docs/www/psgml-for-emacs.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-for-emacs.adp,v
diff -u -N -r1.1.2.10 -r1.1.2.11
--- openacs-4/packages/acs-core-docs/www/psgml-for-emacs.adp	21 Jun 2016 07:44:36 -0000	1.1.2.10
+++ openacs-4/packages/acs-core-docs/www/psgml-for-emacs.adp	23 Jun 2016 08:32:46 -0000	1.1.2.11
@@ -12,7 +12,7 @@
 
      
 Add PSGML commands to emacs init file
 (OPTIONAL)
      
- If you plan to write or edit any
+ If you plan to write or edit any
 documentation with emacs, install a customized emacs configuration
 file with DocBook commands in the skeleton directory, so it will be
 used for all new users. The file also fixes the backspace ->
Index: openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html,v
diff -u -N -r1.41.2.10 -r1.41.2.11
--- openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html	21 Jun 2016 07:44:36 -0000	1.41.2.10
+++ openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html	23 Jun 2016 08:32:46 -0000	1.41.2.11
@@ -1,5 +1,5 @@
 
-Add PSGML commands to emacs init file (OPTIONAL)
      Alex logo
      Prev Appendix B. Install additional supporting software Next
      Add PSGML commands to emacs init file (OPTIONAL)
      
+Add PSGML commands to emacs init file (OPTIONAL)
      Alex logo
      Prev Appendix B. Install additional supporting software Next
      Add PSGML commands to emacs init file (OPTIONAL)
      
 If you plan to write or edit any documentation with emacs, install a
       customized emacs configuration file with DocBook commands in the skeleton
       directory, so it will be used for all new users.  The file also
Index: openacs-4/packages/acs-core-docs/www/psgml-mode.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-mode.adp,v
diff -u -N -r1.1.2.5 -r1.1.2.6
--- openacs-4/packages/acs-core-docs/www/psgml-mode.adp	9 Jun 2016 08:44:50 -0000	1.1.2.5
+++ openacs-4/packages/acs-core-docs/www/psgml-mode.adp	23 Jun 2016 08:32:46 -0000	1.1.2.6
@@ -18,8 +18,8 @@
 
      
 What it is
      PSGML Mode is a mode for editing, umm, SGML and XML documents in
 emacs. It can parse a DTD and help you insert the right tags in the
-right place, knows about tags' attributes and can tell you in which
-contexts a tag can be used. If you give it the right DTD, that is.
+right place, knows about tags' attributes and can tell you in
+which contexts a tag can be used. If you give it the right DTD, that is.
 But even without a DTD, it can save you some typing since pressing
 C-c/ will close an open tag
 automatically.
      
@@ -29,10 +29,9 @@
 find out whether your emacs has it with the locate-library command. In Emacs, type
 M-x locate-library and enter
 psgml. Emacs will tell you if
-it found it or not.
      If you don't have PSGML preinstalled in your Emacs, there are
-two things you can do:
        
-
      1. On Linux: Get the psgml rpm from RedHat's
-docbook-tools and install it as usual.
      2. On other systems: Get the tarball from the PSGML Website. Unpack it and follow the install
+it found it or not.
        If you don't have PSGML preinstalled in your Emacs, there
+are two things you can do:
          
+
        1. On Linux: Get the psgml rpm from RedHat's docbook-tools and install it as usual.
        2. On other systems: Get the tarball from the PSGML Website. Unpack it and follow the install
 instructions.
          3. 
 
        
 
      
@@ -57,8 +56,8 @@
 get from W3C ? The DTD is in the zip archives and tarballs
 available on the site.)
      2. -

    That's it. Now you are ready to tell emacs all about PSGML mode -and that funky CATALOG +

    That's it. Now you are ready to tell emacs all about PSGML +mode and that funky CATALOG

    @@ -117,7 +116,7 @@ file top.xml, that the element in the parent that will enclose the current document is a book and that the current -file's topmost element is a sect1.

    +file's topmost element is a sect1.

    How to use it

    Of course, you should read the emacs texinfo pages that come @@ -134,7 +133,7 @@ C-c C-aEdit attributes of enclosing element. -C-c C-x C-iShow information about the document's DTD. +C-c C-x C-iShow information about the document's DTD. C-c C-x C-eDescribe element. Shows for one element which elements can be parents, what its contents can be and lists its attributes. @@ -146,8 +145,8 @@ Further reading

    Start with the the section called “OpenACS Documentation Guide” -

    ($‌Id: psgml-mode.xml,v 1.8 2006/07/17 05:38:37 -torbenb Exp $)
    +

    ($‌Id: psgml-mode.html,v 1.48.2.10 2016/06/21 +07:44:36 gustafn Exp $)

    Where to get it

    Most newer emacsen come with PSGML mode preinstalled. You can find out whether your emacs has it with the locate-library command. In Emacs, type M-x locate-library and enter psgml. Emacs will tell -you if it found it or not.

    If you don't have PSGML preinstalled in your Emacs, there are two +you if it found it or not.

    If you don't have PSGML preinstalled in your Emacs, there are two things you can do:

    1. On Linux: Get the -psgml rpm from RedHat's +psgml rpm from RedHat's docbook-tools and install it as usual.

    2. On other systems: Get the tarball from the PSGML Website. Unpack it and follow the install instructions.

    Using CATALOG files

    The easiest way to teach PSGML mode about a DTD is by adding it to your own CATALOG. Here is an example of how you can set that up for the @@ -29,7 +29,7 @@ in it. By maintaining your own CATALOG, it is easy to add more DTD's without changing your emacs settings. (How about that HTML 4.01 DTD you always wanted to get from W3C ? The -DTD is in the zip archives and tarballs available on the site.)

    That's it. Now you are ready to tell emacs all about PSGML mode and +DTD is in the zip archives and tarballs available on the site.)

    That's it. Now you are ready to tell emacs all about PSGML mode and that funky CATALOG

    What to tell emacs

    If you installed PSGML mode in a non-standard location, e.g., somewhere in your home directory, you need to add this to the load-path by adding this line to your .emacs file:

    @@ -79,8 +79,8 @@

    Which says that the parent of this document can be found in the file top.xml, that the element in the parent that will enclose the -current document is a book and that the current file's topmost +current document is a book and that the current file's topmost element is a sect1.

    How to use it

    Of course, you should read the emacs texinfo pages that come with PSGML mode from start to finish. Barring that, here are some handy commands:

    KeyCommand
    C-c C-eInsert an element. Uses completion and only lets you insert elements that -are valid
    C-c C-aEdit attributes of enclosing element.
    C-c C-x C-iShow information about the document's DTD.
    C-c C-x C-eDescribe element. Shows for one element which elements can be parents, +are valid
    C-c C-aEdit attributes of enclosing element.
    C-c C-x C-iShow information about the document's DTD.
    C-c C-x C-eDescribe element. Shows for one element which elements can be parents, what its contents can be and lists its attributes.

    Further reading

    Start with the the section called “OpenACS Documentation Guide”

    ($Id$)
    Prev Home Next
    OpenACS Documentation Guide Up Using nXML mode in Emacs
    docs@openacs.org
    View comments on this page at openacs.org
    Index: openacs-4/packages/acs-core-docs/www/release-notes.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/release-notes.adp,v diff -u -N -r1.1.2.12 -r1.1.2.13 --- openacs-4/packages/acs-core-docs/www/release-notes.adp 21 Jun 2016 07:44:36 -0000 1.1.2.12 +++ openacs-4/packages/acs-core-docs/www/release-notes.adp 23 Jun 2016 08:32:46 -0000 1.1.2.13 @@ -31,8 +31,9 @@ from db_* calls, which were ignored due .xql files

  • Removed bug where same query-name was used in different branches of an if-statement for different sql statements, but the query-name lead to the wrong result.

  • Removed multiple entries of same query name from .xql files -(e.g. the entry "package_create_attribute_list.select_type_info" -was 7 (!) times in a single .xql file)

    • +(e.g. the entry +"package_create_attribute_list.select_type_info" was 7 +(!) times in a single .xql file)

    @@ -48,17 +49,17 @@ (/acs-admin).

  • Added explanatory text to several admin pages.

  • Add lightweight support for ckeditor4 for templating::richtext -widget (configurable via package parameter "RichTextEditor" of -acs-templating. ckeditor4 supports mobile devices (such as iPad, -...)

    • +widget (configurable via package parameter +"RichTextEditor" of acs-templating. ckeditor4 supports +mobile devices (such as iPad, ...)

  • Templating:

    • Improved theme-ability: Moved more information into theme packages in order to create responsive designs, reduce hard-coding of paths, HTML etc.

    • Improved include-handling: All includes are now theme-able, -interfaces of includes can be defined with "ad_include_contract" -(similar to ad_page_contract).

    • Improved them-ability for display_templates. One can now provide +interfaces of includes can be defined with +"ad_include_contract" (similar to ad_page_contract).

    • Improved them-ability for display_templates. One can now provide a display_template_name (similar to the sql statement name) to refer to display templates. This enables reusability and is theme-able.

    • Dimensional slider reform (ad_dimensional): Removed hard-coded @@ -71,20 +72,22 @@ timeout after e.g. 60 seconds; after that, the link is invalid. A secret (password) can be set in section ns/server/$server/acs parameter "parametersecret". For example, one can use now -"user_id:sign(max_age=60)" in export_vars to let the exported -variable expire after 60 seconds.

      • +"user_id:sign(max_age=60)" in export_vars to let the +exported variable expire after 60 seconds.

  • Misc:

    • Added ability to show ns_log statements of current request to developer support output when developer support is activated -(controlled via package parameter "TclTraceLogServerities" in the -acs-tcl package parameters)

    • Added ability to save data sent by ns_return in files on the +(controlled via package parameter +"TclTraceLogServerities" in the acs-tcl package +parameters)

    • Added ability to save data sent by ns_return in files on the file system. This can be used to validate HTML content also for password protected pages (controlled via package parameter -"TclTraceSaveNsReturn" in the acs-tcl package parameters)

    • New api function "ad_log" having the same interface as ns_log, -but which logs the calling information (like URL and call-stack) to -ease tracking of errors.

    • Use per-thread caching to reduce number of mutex lock operations +"TclTraceSaveNsReturn" in the acs-tcl package +parameters)

    • New api function "ad_log" having the same interface as +ns_log, but which logs the calling information (like URL and +call-stack) to ease tracking of errors.

    • Use per-thread caching to reduce number of mutex lock operations and lock contention on various caches (util-memoize, xo_site_nodes, xotcl_object_types) and nsvs (e.g ds_properties)

    • Improved templating of OpenACS core documentation

    • Improved Russian Internationalization

    • Make pretty-names of acs-core packages more consistent

    • Mark unused functions of acs-tcl/tcl/table-display-procs.tcl as deprecated

    • Many more bug fixes (from bug tracker and extra) and performance @@ -176,55 +179,58 @@ committers.

    -Release 5.7.0

    • Made changes that extend acs-kernel's create_type and -create_attribute procs, so they're optionally able to create sql -tables and columns. Optional metadata params allow for the +Release 5.7.0

    • Made changes that extend acs-kernel's create_type and +create_attribute procs, so they're optionally able to create +sql tables and columns. Optional metadata params allow for the automatic generation of foreign key references, check exprs, etc.

    Release 5.6.0

    • -

      Added new package dependency type, "embeds". This is a variant -of the "extends" package dependency type added in OpenACS 5.5.0. It -allows one to write embeddable packages, with scripts made visible -in client packages using URLs which include the embedded package's -package key. An example embeddable package might be a rewritten -"attachments" package. The current implementation requires a global -instance be mounted, and client packages generate urls to that -global instance. Among other things, this leads to the user -navigating to the top-level subsite, losing any subsite theming -that might be associated with a community. Using "embeds", a -rewritten package would run in the client package's context, -maintaining theming and automatically associating attachments with -the client package.

      Added global package parameters - parameters can now have scope -"local" or "global", with "local" being the default..

      Fixes for ns_proxy handling

      Significant speedup for large sites

      Optional support for selenium remote control +

      Added new package dependency type, "embeds". This is a +variant of the "extends" package dependency type added in +OpenACS 5.5.0. It allows one to write embeddable packages, with +scripts made visible in client packages using URLs which include +the embedded package's package key. An example embeddable +package might be a rewritten "attachments" package. The +current implementation requires a global instance be mounted, and +client packages generate urls to that global instance. Among other +things, this leads to the user navigating to the top-level subsite, +losing any subsite theming that might be associated with a +community. Using "embeds", a rewritten package would run +in the client package's context, maintaining theming and +automatically associating attachments with the client package.

      Added global package parameters - parameters can now have scope +"local" or "global", with "local" +being the default..

      Fixes for ns_proxy handling

      Significant speedup for large sites

      Optional support for selenium remote control (acs-automated-tests)

      New administration UI to manage mime types and extension map

      Added acs-mail-lite package params for rollout support

      Support for 3-chars language codes in acs-lang

      Added OOXML mime types in acs-content-repository

    Release 5.5.0

    • PostgreSQL 8.3 is now fully supported, including the use of the built-in standard version of tsearch2.

      TinyMCE has been upgraded to 3.2.4.1 with language pack -support.

      acs-mail-lite now correctly implements rollout support.

      Added new package dependency type, "extends". Implements a weak -form of package inheritance (parameters and, optionally, -templates). Multiple inheritance is supported. For instance, the -non-core "layout-managed-subsite" extends the "acs-subsite" and -"layout-manager" packages, resulting in a package that combines the -semantics of both.

      Added new package attribute "implements-subsite-p" (default -"f"). If true, this package may be mounted as a subsite and is -expected to implement subsite semantics. Typically used by packages -which extend acs-subsite.

      Added new package attribute "inherit-templates-p" (default "t"). -If true, the package inherits templates defined in the packages it -extends. This means that the package only needs to specify -templates where the UI of an extended package is modified or -extended. This greatly reduces the need to fork base packages when -one needs to customize it. Rather than modify the package directly, -use "extends" rather than "requires" then rewrite those templates -you need to customize.

      Added a simple mechanism for defining subsite themes, removing +support.

      acs-mail-lite now correctly implements rollout support.

      Added new package dependency type, "extends". +Implements a weak form of package inheritance (parameters and, +optionally, templates). Multiple inheritance is supported. For +instance, the non-core "layout-managed-subsite" extends +the "acs-subsite" and "layout-manager" +packages, resulting in a package that combines the semantics of +both.

      Added new package attribute "implements-subsite-p" +(default "f"). If true, this package may be mounted as a +subsite and is expected to implement subsite semantics. Typically +used by packages which extend acs-subsite.

      Added new package attribute "inherit-templates-p" +(default "t"). If true, the package inherits templates +defined in the packages it extends. This means that the package +only needs to specify templates where the UI of an extended package +is modified or extended. This greatly reduces the need to fork base +packages when one needs to customize it. Rather than modify the +package directly, use "extends" rather than +"requires" then rewrite those templates you need to +customize.

      Added a simple mechanism for defining subsite themes, removing the hard-wired choices implemented in earlier versions of OpenACS. The default theme has been moved into a new package, -"openacs-default-theme". Simplifies the customization of the look -and feel of OpenACS sites and subsites.

      The install xml facility has been enhanced to allow the calling +"openacs-default-theme". Simplifies the customization of +the look and feel of OpenACS sites and subsites.

      The install xml facility has been enhanced to allow the calling of arbitrary Tcl procedures and includes various other enhancements written by Xarg. Packages can extend the facility, too. As an example of what can be done, the configuration of .LRN communities @@ -238,7 +244,7 @@

    Release 5.4.2

    • -

      This is a minor bugfix release.

      Site node caching was removed as doesn't work correctly

      Critical issues with search on oracle were fixed

      More html strict work etc

      +

      This is a minor bugfix release.

      Site node caching was removed as doesn't work correctly

      Critical issues with search on oracle were fixed

      More html strict work etc

    @@ -249,10 +255,10 @@

    New Templating API added to add scripts, css, etc to the HTML HEAD and BODY sections of the generated HTML document. Please see /packages/acs-templating/tcl/head-procs.tcl or visit the -template::head procs in the API browser for details.

    Templates have been modified to comply with HTML strict

    The Search package's results page has been improved

    TinyMCE WYSIWYG support has been added, RTE and HTMLArea support -dropped

    acs-mail-lite's send has been cleaned up to properly encode -content, to handle file attachments, etc. "complex-send" will -disappear from acs-core in a future release.

    +template::head procs in the API browser for details.

    Templates have been modified to comply with HTML strict

    The Search package's results page has been improved

    TinyMCE WYSIWYG support has been added, RTE and HTMLArea support +dropped

    acs-mail-lite's send has been cleaned up to properly encode +content, to handle file attachments, etc. "complex-send" +will disappear from acs-core in a future release.

    • The ChangeLogs include an annotated list of changes (???) since the last release and in the entire 5.9 release sequence ???.

    @@ -347,7 +353,7 @@ for the section called “a Unix-like system”. Note that the Windows documentation is not current for OpenACS 5.9.0, but an alternative -is to use John Sequeira's Oasis VM project.

    After installation, the full documentation set can be found by +is to use John Sequeira's Oasis VM project.

    After installation, the full documentation set can be found by visiting http://yourserver/doc.

    New features in this release:

    • Internationalization support. A message catalog to store translated text, localization of dates, number formatting, timezone @@ -358,33 +364,33 @@ to support other authentication, password management, account creation, and account import mechanisms. This includes improvements to the basic cookie handling, so logins can be expired without the -user's identity being completely lost. You can set login to expire -after a certain period (e.g. 8 hours, then password must be +user's identity being completely lost. You can set login to +expire after a certain period (e.g. 8 hours, then password must be refreshed), or you can have all issues login cookies expired at once, e.g. if you have left a permanent login cookie on a public machine somewhere.

    • User interface enhancements. All pages, including site-wide and subsite admin pages, will be templated, so they can be styled using master template and site-wide stylesheets. We have a new default-master template, which includes links to administration, your workspace, and login/logout, and is rendered using CSS. And -there's a new community template +there's a new community template (/packages/acs-subsite/www/group-master), which provides useful navigation to the applications and administrative UI in a subsite. -In addition, there's new, simpler UI for managing members of a +In addition, there's new, simpler UI for managing members of a subsite, instantiating and mounting applications, setting permissions, parameters, etc. Site-wide admin as also seen the addition of a new simpler software install UI to replace the APM for non-developer users, and improved access to parameters, internationalization, automated testing, service contracts, etc. The list builder has been added for easily generating templated tables and lists, with features such as filtering, sorting, actions -on multiple rows with checkboxes, etc. Most of all, it's fast to -use, and results in consistently-looking, consistently-behaving, +on multiple rows with checkboxes, etc. Most of all, it's fast +to use, and results in consistently-looking, consistently-behaving, templated tables.

    • Automated testing. The automated testing framework has been improved significantly, and there are automated tests for a number of packages.

    • Security enhancements. HTML quoting now happens in the templating system, greatly minimizing the chance that users can -sneak malicious HTML into the pages of other users.

    • Oracle 9i support.

    • Who's online feature.

    • Spell checking.

      • +sneak malicious HTML into the pages of other users.

    • Oracle 9i support.

    • Who's online feature.

    • Spell checking.

    Potential incompatibilities:

    • With the release of OpenACS 5, PostgreSQL 7.2 is no longer supported. Upgrades are supported from OpenACS 4.6.3 under Oracle @@ -396,8 +402,8 @@ turned off by default via the acs-kernel parameter ExcludedFiles in section request-processor (The variable provides a string match glob list of files and is defaulted to "*/CVS/* *~")

      • -
    ($‌Id: release-notes.xml,v 1.30.2.6 2015/12/01 -14:38:54 gustafn Exp $)
    +
    ($‌Id: release-notes.html,v 1.55.2.10 2016/06/21 +07:44:36 gustafn Exp $)

    Release 4.6.3

    Release Notes for 4.6.3

    @@ -415,7 +421,7 @@ \ No newline at end of file Index: openacs-4/packages/acs-core-docs/www/release-notes.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/release-notes.html,v diff -u -N -r1.55.2.10 -r1.55.2.11 --- openacs-4/packages/acs-core-docs/www/release-notes.html 21 Jun 2016 07:44:36 -0000 1.55.2.10 +++ openacs-4/packages/acs-core-docs/www/release-notes.html 23 Jun 2016 08:32:46 -0000 1.55.2.11 @@ -1,5 +1,5 @@ -OpenACS Release Notes
    Alex logo
    Prev Chapter 1. High level information: What is OpenACS? Next

    OpenACS Release Notes

    Release 5.9.0

    • +OpenACS Release Notes

      Alex logo
      Prev Chapter 1. High level information: What is OpenACS? Next

      OpenACS Release Notes

      Release 5.9.0

      • The release of OpenACS 5.9.0 contains the 78 packages of the oacs-5-9 branch. These packages include the OpenACS core packages, the major application packages (e.g. most the ones used on OpenACS.org), and @@ -263,21 +263,21 @@ more than 18.000 modifications (781 commits) contributed by 7 committers.

      Release 5.7.0

      • - Made changes that extend acs-kernel's create_type and create_attribute procs, - so they're optionally able to create sql tables and columns. Optional metadata + Made changes that extend acs-kernel's create_type and create_attribute procs, + so they're optionally able to create sql tables and columns. Optional metadata params allow for the automatic generation of foreign key references, check exprs, etc.

      Release 5.6.0

      • Added new package dependency type, "embeds". This is a variant of the "extends" package dependency type added in OpenACS 5.5.0. It allows one to write embeddable packages, with scripts made visible in client packages - using URLs which include the embedded package's package key. An example + using URLs which include the embedded package's package key. An example embeddable package might be a rewritten "attachments" package. The current implementation requires a global instance be mounted, and client packages generate urls to that global instance. Among other things, this leads to the user navigating to the top-level subsite, losing any subsite theming that might be associated with a community. Using "embeds", a rewritten - package would run in the client package's context, maintaining theming and + package would run in the client package's context, maintaining theming and automatically associating attachments with the client package.

        Added global package parameters - parameters can now have scope "local" or "global", @@ -335,12 +335,12 @@ site-wide one if not. This will cause message keys (entered as <span>#</span>....# strings) to be replaced with the language text for the chosen locale.

      Release 5.4.2

      • This is a minor bugfix release. -

        Site node caching was removed as doesn't work correctly

        Critical issues with search on oracle were fixed

        More html strict work etc

      Release 5.4.1

      • This is a minor bugfix release. +

        Site node caching was removed as doesn't work correctly

        Critical issues with search on oracle were fixed

        More html strict work etc

      Release 5.4.1

      • This is a minor bugfix release.

      Release 5.4.0

      • New Templating API added to add scripts, css, etc to the HTML HEAD and BODY sections of the generated HTML document. Please see /packages/acs-templating/tcl/head-procs.tcl or visit the template::head procs in the API browser for details. -

        Templates have been modified to comply with HTML strict

        The Search package's results page has been improved

        TinyMCE WYSIWYG support has been added, RTE and HTMLArea support dropped

        acs-mail-lite's send has been cleaned up to properly encode content, to handle +

        Templates have been modified to comply with HTML strict

        The Search package's results page has been improved

        TinyMCE WYSIWYG support has been added, RTE and HTMLArea support dropped

        acs-mail-lite's send has been cleaned up to properly encode content, to handle file attachments, etc. "complex-send" will disappear from acs-core in a future release.

      The ChangeLogs include an annotated list of changes (???) since the last release and in the entire 5.9 release sequence ???.

      Release 5.3.1

      • Bug fixes.

        New TIPs implemented.

        All Core Automated Tests for Postgres pass.

        New Site and Blank master templates and CSS compatible with the .LRN Zen @@ -371,7 +371,7 @@ You may want to begin by reading our installation documentation for the section called “a Unix-like system”. Note that the Windows documentation is not current for OpenACS 5.9.0, but an alternative is to use John - Sequeira's Oasis VM + Sequeira's Oasis VM project.

        After installation, the full documentation set can be found by visiting @@ -392,7 +392,7 @@ authentication, password management, account creation, and account import mechanisms. This includes improvements to the basic cookie handling, so logins can be expired without the - user's identity being completely lost. You can set login to expire after a certain period + user's identity being completely lost. You can set login to expire after a certain period (e.g. 8 hours, then password must be refreshed), or you can have all issues login cookies expired at once, e.g. if you have left a permanent login cookie on a public machine somewhere.

      • @@ -406,12 +406,12 @@ administration, your workspace, and login/logout, and is rendered using CSS. - And there's a new community template + And there's a new community template (/packages/acs-subsite/www/group-master), which provides useful navigation to the applications and administrative UI in a subsite. - In addition, there's new, simpler UI for managing members of a + In addition, there's new, simpler UI for managing members of a subsite, instantiating and mounting applications, setting permissions, parameters, etc. @@ -422,7 +422,7 @@ The list builder has been added for easily generating templated tables and lists, with features such as filtering, sorting, - actions on multiple rows with checkboxes, etc. Most of all, it's + actions on multiple rows with checkboxes, etc. Most of all, it's fast to use, and results in consistently-looking, consistently-behaving, templated tables.

      • @@ -439,7 +439,7 @@

      • Oracle 9i support.

      • - Who's online feature. + Who's online feature.

      • Spell checking.

      @@ -458,4 +458,4 @@

    • Serving backup files and files from the CVS directories is turned off by default via the acs-kernel parameter ExcludedFiles in section request-processor (The variable provides a string match glob list of files and is defaulted to "*/CVS/* *~") -

    ($Id$)

    Release 4.6.3

    Release Notes for 4.6.3

    Release 4.6.2

    Release Notes for 4.6.2

    Release 4.6

    Release Notes for 4.6

    Release 4.5

    Release Notes for 4.5

    Prev Home Next
    Overview Up Part II. Administrator's Guide
    docs@openacs.org
    View comments on this page at openacs.org
    +

    ($Id$)

    Release 4.6.3

    Release Notes for 4.6.3

    Release 4.6.2

    Release Notes for 4.6.2

    Release 4.6

    Release Notes for 4.6

    Release 4.5

    Release Notes for 4.5

    Prev Home Next
    Overview Up Part II. Administrator's Guide
    docs@openacs.org
    View comments on this page at openacs.org
    Index: openacs-4/packages/acs-core-docs/www/releasing-openacs-core.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/releasing-openacs-core.adp,v diff -u -N -r1.1.2.5 -r1.1.2.6 --- openacs-4/packages/acs-core-docs/www/releasing-openacs-core.adp 9 Jun 2016 13:03:11 -0000 1.1.2.5 +++ openacs-4/packages/acs-core-docs/www/releasing-openacs-core.adp 23 Jun 2016 08:32:46 -0000 1.1.2.6 @@ -17,26 +17,27 @@ translations”

  • -Rebuild the Changelog. Rebuild the Changelog. -I use a tool called cvs2cl. Run this command from the package root -to automatically generate a Changelog file in the same dir. We -generate two changelogs, one for the minor branch and one for the -most recent release. The example below is for OpenACS 5.0.2:

    cd /var/lib/aolserver/$OPENACS_SERVICE_NAME
+Rebuild the Changelog. Rebuild the
+Changelog. I use a tool called cvs2cl. Run this command from the
+package root to automatically generate a Changelog file in the same
+dir. We generate two changelogs, one for the minor branch and one
+for the most recent release. The example below is for OpenACS
+5.0.2:
    cd /var/lib/aolserver/$OPENACS_SERVICE_NAME
 cvs2cl -F oacs-5-0 --delta openacs-5-0-0-final:oacs-5-0 -f ChangeLog
 cvs2cl -F oacs-5-0 --delta openacs-5-0-1-final:oacs-5-0 -f ChangeLog-recent

  • -Update Version Numbers. The version numbers -in the documentation and in the packages must be updated. This -should only happen after a release candidate is approved.

    .LRN: this must be +Update Version Numbers. The version +numbers in the documentation and in the packages must be updated. +This should only happen after a release candidate is approved.

    .LRN: this must be repeated for .LRN modules (dotlrn-core in the dotlrn cvs tree) and for any modified modules in the .LRN prerequisites (dotlrn-prereq in openacs cvs tree). My current working model is that I -bulk-update .LRN and OpenACS core but that I don't touch -dotlrn-prereq modules - I just use the most recent release and it's -up to individual package developers to tag and release those +bulk-update .LRN and OpenACS core but that I don't touch +dotlrn-prereq modules - I just use the most recent release and +it's up to individual package developers to tag and release those packages when they change. This model is already broken because -following it means that dotlrn-prereqs don't get new +following it means that dotlrn-prereqs don't get new translations.

    1. Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/variables.ent @@ -61,10 +62,10 @@

  • -Tag the files in CVS. The steps to this point -should have ensured that the head of the current branch contains -the full set of code to release. Now we need to tag it as the code -to be released.

      +Tag the files in CVS. The steps to +this point should have ensured that the head of the current branch +contains the full set of code to release. Now we need to tag it as +the code to be released.

      1. Check out OpenACS Core. The files must be checked out through a cvs account with write access and should be a checkout from the @@ -77,9 +78,9 @@ cvs -d /dotlrn-cvsroot checkout -r dotlrn-2-0 dotlrn-all

      2. -

        Tag the tree. If it's a final release of core, move or create -the appropriate openacs-major-minor-compat tag. (Ie, if releasing -5.0.3 final, move the openacs-5-0-compat flag.)

        cd /var/tmp/openacs-4
+
        Tag the tree. If it's a final release of core, move or
+create the appropriate openacs-major-minor-compat tag. (Ie, if
+releasing 5.0.3 final, move the openacs-5-0-compat flag.)
        cd /var/tmp/openacs-4
 cvs tag -F openacs-5-0-0a1
 cvs tag -F openacs-5-0-compat
 
        
@@ -97,15 +98,15 @@
 somefile.
         cvs tag -b oacs-5-0
 
        
-
        If doing .LRN: Since the .LRN packages aren't all in one module,
-we iterate through all of the modules. Log in first (cvs login) so
-that you don't have to log in for each module.
        cd /var/tmp/dotlrn-packages
+

      If doing .LRN: Since the .LRN packages aren't all in one +module, we iterate through all of the modules. Log in first (cvs +login) so that you don't have to log in for each module.

      cd /var/tmp/dotlrn-packages
 for dir in *; do ( cd $dir && cvs tag dotlrn-2-0-2-final ); done
 for dir in *; do ( cd $dir && cvs tag -F openacs-5-0-compat ); done

      Note that for the compat tag we use the -F flag which will force the tag to the new version (just in case someone has created the tag already on another version). Excercise care when doing this -since you don't want to inadvertently move a prior release tag. +since you don't want to inadvertently move a prior release tag. Also if the tagging goes horribly wrong for some reason you can delete the tag via "cvs tag -d <symbolic_tag>".

      @@ -162,25 +163,26 @@

  • -Test the new tarball(s). Download the -tarballs just created and install them and make sure everything +Test the new tarball(s). Download +the tarballs just created and install them and make sure everything looks okay and that automated tests pass.

  • -Update Web site. Update the different places -on OpenACS.org where we track status.

      +Update Web site. Update the +different places on OpenACS.org where we track status.

      • Release Status for the current version - something like http://openacs.org/projects/openacs/5.0/milestones

      • Home page of openacs.org

      • Post a new news item

    • -Clean Up. Clean up after yourself.

      cd /var/tmp
+Clean Up. Clean up after
+yourself.
      cd /var/tmp
 rm -rf tarball dotlrn-tarball dotlrn-packages openacs-5.0.0a1
 rm -rf /var/tmp/openacs-4

    Here is a shell script that automates packaging the tarball -(it's a bit out of date with the new steps - I've been doing -everything manually or with little throwaway scripts as detailed -above until the process is stabilized).

    +(it's a bit out of date with the new steps - I've been
+doing everything manually or with little throwaway scripts as
+detailed above until the process is stabilized).
     #!/bin/bash
 
 # if TAG=1 create the cvs tags otherwise assume they exist.
@@ -262,8 +264,8 @@
 
 # Clean up after ourselves...
 cd $BASE && rm -rf dotlrn-tarball tarball openacs-4 dotlrn-packages
-
    ($‌Id: releasing-openacs.xml,v 1.22 2014/10/27
-16:39:30 victorg Exp $)
    
+
    ($‌Id: releasing-openacs-core.html,v 1.20.2.10 +2016/06/21 07:44:36 gustafn Exp $)
    OpenACS Core and .LRN
    Alex logo
    Prev Chapter 16. Releasing OpenACS Next

    OpenACS Core and .LRN

    1. Update Translations. the section called “How to Update the translations”

    2. Rebuild the Changelog. Rebuild the Changelog. I use a tool called cvs2cl. Run this command from the package root to automatically generate a Changelog file in the same dir. We generate two changelogs, one for the minor branch and one for the most recent release. The example below is for OpenACS 5.0.2:

      cd /var/lib/aolserver/$OPENACS_SERVICE_NAME
 cvs2cl -F oacs-5-0 --delta openacs-5-0-0-final:oacs-5-0 -f ChangeLog
-cvs2cl -F oacs-5-0 --delta openacs-5-0-1-final:oacs-5-0 -f ChangeLog-recent

    3. Update Version Numbers. The version numbers in the documentation and in the packages must be updated. This should only happen after a release candidate is approved.

      .LRN: this must be repeated for .LRN modules (dotlrn-core in the dotlrn cvs tree) and for any modified modules in the .LRN prerequisites (dotlrn-prereq in openacs cvs tree). My current working model is that I bulk-update .LRN and OpenACS core but that I don't touch dotlrn-prereq modules - I just use the most recent release and it's up to individual package developers to tag and release those packages when they change. This model is already broken because following it means that dotlrn-prereqs don't get new translations.

      1. Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/variables.ent with the new version number. +cvs2cl -F oacs-5-0 --delta openacs-5-0-1-final:oacs-5-0 -f ChangeLog-recent

      2. Update Version Numbers. The version numbers in the documentation and in the packages must be updated. This should only happen after a release candidate is approved.

        .LRN: this must be repeated for .LRN modules (dotlrn-core in the dotlrn cvs tree) and for any modified modules in the .LRN prerequisites (dotlrn-prereq in openacs cvs tree). My current working model is that I bulk-update .LRN and OpenACS core but that I don't touch dotlrn-prereq modules - I just use the most recent release and it's up to individual package developers to tag and release those packages when they change. This model is already broken because following it means that dotlrn-prereqs don't get new translations.

        1. Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/variables.ent with the new version number.

        2. Add new section in /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml

        3. Regenerate all HTML docs

          cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml
 make

        4. Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/readme.txt with the new version number

        5. Update version number and release date in all of the @@ -18,18 +18,18 @@ mkdir dotlrn-packages cd dotlrn-packages cvs -d /dotlrn-cvsroot checkout -r dotlrn-2-0 dotlrn-all -

        6. Tag the tree. If it's a final release of core, move or create the appropriate openacs-major-minor-compat tag. (Ie, if releasing 5.0.3 final, move the openacs-5-0-compat flag.)

          cd /var/tmp/openacs-4
+

        7. Tag the tree. If it's a final release of core, move or create the appropriate openacs-major-minor-compat tag. (Ie, if releasing 5.0.3 final, move the openacs-5-0-compat flag.)

          cd /var/tmp/openacs-4
 cvs tag -F openacs-5-0-0a1
 cvs tag -F openacs-5-0-compat
-

          Branching

          When we feature-freeze on HEAD as part of the release process, we are blocking new development. To avoid this, we branch the code at this point, so that new work can continue on HEAD while the branch is stabilized for release. However, branching means that bug fixes have to be synchronized between HEAD and the branch, and bug fixes tend to be more frequent right at this time. Therefore, our actual branch point is as late as possible - essentially, we do not branch until and unless new feature work is actively blocked by the feature freeze. Branching is almost the same as tagging, except for the flag and slightly different tag nomenclature. To see the list of old branches, cvs status -v somefile.

          cvs tag -b oacs-5-0

          If doing .LRN: Since the .LRN packages aren't all in one +

          Branching

          When we feature-freeze on HEAD as part of the release process, we are blocking new development. To avoid this, we branch the code at this point, so that new work can continue on HEAD while the branch is stabilized for release. However, branching means that bug fixes have to be synchronized between HEAD and the branch, and bug fixes tend to be more frequent right at this time. Therefore, our actual branch point is as late as possible - essentially, we do not branch until and unless new feature work is actively blocked by the feature freeze. Branching is almost the same as tagging, except for the flag and slightly different tag nomenclature. To see the list of old branches, cvs status -v somefile.

          cvs tag -b oacs-5-0

          If doing .LRN: Since the .LRN packages aren't all in one module, we iterate through all of the modules. Log in first - (cvs login) so that you don't have to log in for each + (cvs login) so that you don't have to log in for each module.

          cd /var/tmp/dotlrn-packages
 for dir in *; do ( cd $dir && cvs tag dotlrn-2-0-2-final ); done
 for dir in *; do ( cd $dir && cvs tag -F openacs-5-0-compat ); done

          Note that for the compat tag we use the -F flag which will force the tag to the new version (just in case someone has created the tag already on another version). Excercise care when doing this since - you don't want to inadvertently move a prior release tag. Also if the tagging goes horribly wrong + you don't want to inadvertently move a prior release tag. Also if the tagging goes horribly wrong for some reason you can delete the tag via "cvs tag -d <symbolic_tag>".

        8. Apply the final tag across the tree. First, check out the entire OpenACS tree, getting the most recent stable version of each package. This is most simply done on openacs.org:

          cd /var/tmp
 cvs -d /cvsroot checkout -r openacs-5-1-compat openacs-4
 cd openacs-4
@@ -57,7 +57,7 @@

    4. Test the new tarball(s). Download the tarballs just created and install them and make sure everything looks okay and that automated tests pass.

    5. Update Web site. Update the different places on OpenACS.org where we track status.

      • Release Status for the current version - something like http://openacs.org/projects/openacs/5.0/milestones

      • Home page of openacs.org

      • Post a new news item

    6. Clean Up. Clean up after yourself.

      cd /var/tmp
 rm -rf tarball dotlrn-tarball dotlrn-packages openacs-5.0.0a1
 rm -rf /var/tmp/openacs-4

    - Here is a shell script that automates packaging the tarball (it's a bit out of date with the new steps - I've been doing everything manually or with little throwaway scripts as detailed above until the process is stabilized). + Here is a shell script that automates packaging the tarball (it's a bit out of date with the new steps - I've been doing everything manually or with little throwaway scripts as detailed above until the process is stabilized). 

    #!/bin/bash
 
 # if TAG=1 create the cvs tags otherwise assume they exist.
Index: openacs-4/packages/acs-core-docs/www/remote-postgres.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/remote-postgres.adp,v
diff -u -N -r1.1.2.1 -r1.1.2.2
--- openacs-4/packages/acs-core-docs/www/remote-postgres.adp	23 Sep 2015 11:54:50 -0000	1.1.2.1
+++ openacs-4/packages/acs-core-docs/www/remote-postgres.adp	23 Jun 2016 08:32:46 -0000	1.1.2.2
@@ -12,7 +12,8 @@
 Running a PostgreSQL database on another
 server

    To run a database on a different machine than the webserver requires changes to the database configuration file and access -control file, and to the OpenACS service's configuration file.

      +control file, and to the OpenACS service's configuration +file.

      • Edit the database configuration file, which in a Reference install is located at /usr/local/pgsql/data/postgresql.conf and @@ -24,8 +25,8 @@

      • Change the access control file for the database to permit specific remote clients to access. Access can be controlled ... (add notes from forum post)

      • -

        Change the OpenACS service's configuration file to point to the -remote database. Edit /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl +

        Change the OpenACS service's configuration file to point to +the remote database. Edit /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl and change

        to
        
 
        • 
 
      
Index: openacs-4/packages/acs-core-docs/www/remote-postgres.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/remote-postgres.html,v
diff -u -N -r1.13.2.1 -r1.13.2.2
--- openacs-4/packages/acs-core-docs/www/remote-postgres.html	9 Jun 2016 08:44:50 -0000	1.13.2.1
+++ openacs-4/packages/acs-core-docs/www/remote-postgres.html	23 Jun 2016 08:32:46 -0000	1.13.2.2
@@ -1,12 +1,12 @@
 
 Running a PostgreSQL database on another server
      Alex logo
      Prev Chapter 7. Database Management Next
      Running a PostgreSQL database on another server
      To run a database on a different machine than the
       webserver requires changes to the database configuration file
-      and access control file, and to the OpenACS service's
+      and access control file, and to the OpenACS service's
       configuration file.
      • Edit the database configuration file, which in a
       Reference install is located at /usr/local/pgsql/data/postgresql.conf
       and change
        #tcpip_socket = false
        to
        tcpip_socket = true
      • Change the access control file for the database to
           permit specific remote clients to access.  Access can be
-          controlled ... (add notes from forum post) 
      • Change the OpenACS service's configuration file to
+          controlled ... (add notes from forum post) 
      • Change the OpenACS service's configuration file to
           point to the remote database.  Edit
           /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl
           and change
        to 
      Prev Home Next
      Chapter 7. Database Management Up Deleting a tablespace
      docs@openacs.org
      View comments on this page at openacs.org
      
Index: openacs-4/packages/acs-core-docs/www/request-processor.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/request-processor.adp,v
diff -u -N -r1.1.2.4 -r1.1.2.5
--- openacs-4/packages/acs-core-docs/www/request-processor.adp	9 Jun 2016 13:03:11 -0000	1.1.2.4
+++ openacs-4/packages/acs-core-docs/www/request-processor.adp	23 Jun 2016 08:32:46 -0000	1.1.2.5
@@ -41,49 +41,48 @@
 which instance was requested.
      
 
      Stage 2: Authentication
      Next, the Request Processor examines the request for session
 information. Session information is generally sent from the client
-(the user's browser) to the server via cookies. The security/session
-handler is described in detail in its own document. It examines
-the client request and either extracts or sets up new session
-tokens for the user.
      Stage 3: Authorization
      Next, the Request Processor checks if the user has appropriate
+(the user's browser) to the server via cookies. The security/session handler is described in
+detail in its own document. It examines the client request and
+either extracts or sets up new session tokens for the user.
      Stage 3: Authorization
      Next, the Request Processor checks if the user has appropriate
 access privileges to the requested part of the site. In OpenACS
 5.9.0, access control is dictated by the permissions system. In this case,
-the RP checks if the user has "read" priviledges on the object in
-the site map specified by the URL. This object is typically a
-package instance, but it could easily be something more granular,
-such as whehter the user can view a particular piece of content
-within a package instance. This automatic check makes it easy to
-set up sites with areas that are only accessible to specific groups
-of users.
      Stage 4: URL Processing, File
+the RP checks if the user has "read" priviledges on the
+object in the site map specified by the URL. This object is
+typically a package instance, but it could easily be something more
+granular, such as whehter the user can view a particular piece of
+content within a package instance. This automatic check makes it
+easy to set up sites with areas that are only accessible to
+specific groups of users.
      Stage 4: URL Processing, File
 Search
      
 
      Finally, the Request Processor finds the file we intend to
 serve, searching the filesystem to locate the actual file that
 corresponds to an abstract URL. It searches for files with
 predefined "magic" extensions, i.e. files that end with:
-.html, .tcl and .adp.
      If the RP can't find any matching files with the expected
+.html, .tcl and .adp.
      If the RP can't find any matching files with the expected
 extensions, it will look for virtual-url-handler files, or
 .vuh files. A .vuh file will be executed as if it were a
 Tcl file, but with the tail end of the URL removed. This allows the
 code in the .vuh file to act
 like a registered procedure for an entire subtree of the URL
 namespace. Thus a .vuh file can
 be thought of as a replacement for filters and registered procs,
-except that they integrate cleanly and correctly with the RP's URL
-mapping mechanisms. The details of how to use these files are
+except that they integrate cleanly and correctly with the RP's
+URL mapping mechanisms. The details of how to use these files are
 described in OpenACS 4 Request Processor
 Design.
      Once the appropriate file is found, it is either served directly
-if it's static content, or sent to the template system or the
-standard Tcl interpreter if it's a dynamic page.
      
+if it's static content, or sent to the template system or the
+standard Tcl interpreter if it's a dynamic page.
      
 
      
 
    
 
    
 
    
 Basic
 API
    Once the flow of control reaches a dynamic page, the Request
 Processor has populated the environment of the request with several
-pieces of useful information. The RP's environment is accessible
-through the ad_conn interface,
-and the following calls should be useful to you when developing
-dynamic pages:
    
+pieces of useful information. The RP's environment is
+accessible through the ad_conn
+interface, and the following calls should be useful to you when
+developing dynamic pages:
    
 
    [ad_conn
 user_id]
    The ID of the user associated with this request. By convention
 this is zero if there is no user.
    [ad_conn
@@ -107,8 +106,8 @@
 name of the package.
    [ad_conn
 path_info]
    In a .vuh file, path_info is the trailing part of the URL not
 matched by the .vuh file.
    
-
    ($‌Id: rp.xml,v 1.12 2010/12/11 23:36:32 ryang
-Exp $)
    
+
    ($‌Id: request-processor.html,v 1.49.2.10
+2016/06/21 07:44:36 gustafn Exp $)
    
 
    
 
 
    Stage 2: Authentication
    
 Next, the Request Processor examines the request for session
 information. Session information is generally sent from the client
-(the user's browser) to the server via cookies. The security/session handler is described in
+(the user's browser) to the server via cookies. The security/session handler is described in
 detail in its own document. It examines the client request and either
 extracts or sets up new session tokens for the user.
 
    Stage 3: Authorization
    
@@ -51,7 +51,7 @@
 extensions, i.e. files that end with: .html,
 .tcl and .adp.  
 
    
-If the RP can't find any matching files with the expected extensions,
+If the RP can't find any matching files with the expected extensions,
 it will look for virtual-url-handler files, or .vuh
 files. A .vuh file will be executed as if it were a Tcl
 file, but with the tail end of the URL removed. This allows the code
@@ -63,8 +63,8 @@
 described in OpenACS 4 Request Processor Design.
 
    
 Once the appropriate file is found, it is either served directly if
-it's static content, or sent to the template system or the standard
-Tcl interpreter if it's a dynamic page.
+it's static content, or sent to the template system or the standard
+Tcl interpreter if it's a dynamic page.
 
    Basic API
    
 Once the flow of control reaches a dynamic page, the Request Processor
 has populated the environment of the request with several pieces of
Index: openacs-4/packages/acs-core-docs/www/requirements-template.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/requirements-template.adp,v
diff -u -N -r1.1.2.4 -r1.1.2.5
--- openacs-4/packages/acs-core-docs/www/requirements-template.adp	9 Jun 2016 08:44:50 -0000	1.1.2.4
+++ openacs-4/packages/acs-core-docs/www/requirements-template.adp	23 Jun 2016 08:32:46 -0000	1.1.2.5
@@ -30,19 +30,19 @@
 Vision Statement
    Very broadly, describe how the system
 meets a need of a business, group, the OpenACS as a whole, etc.
 Make sure that technical and non-technical readers alike would
-understand what the system would do and why it's useful. Whenever
-applicable, you should explicitly state what the business value of
-the system is.
    
+understand what the system would do and why it's useful.
+Whenever applicable, you should explicitly state what the business
+value of the system is.
    
 
    
 
    
 System/Application
 Overview
    Discuss the high-level breakdown of
 the components that make up the system. You can go by functional
 areas, by the main transactions the system allows,
 etc.
    You should also state the context and
-dependencies of the system here, e.g. if it's an application-level
-package for OpenACS 4, briefly describe how it uses kernel
-services, like permissions or subsites.
    
+dependencies of the system here, e.g. if it's an
+application-level package for OpenACS 4, briefly describe how it
+uses kernel services, like permissions or subsites.
    
 
    
 
    
 Use-cases and
@@ -55,17 +55,17 @@
 
    
 Optional:
 Competitive Analysis
    Describe other systems or services
-that are comparable to what you're building. If applicable, say why
-your implementation will be superior, where it will match the
+that are comparable to what you're building. If applicable, say
+why your implementation will be superior, where it will match the
 competition, and where/why it will lack existing best-of-breed
 capabilities. This section is also in the Design doc, so write
 about it where you deem most appropriate.
    
 
    
 
    
 Related Links
    Include all pertinent links to supporting and related material,
 such as:
      
-
    • System/Package "coversheet" - where all documentation for this
-software is linked off of
    • Design document
    • Developer's guide
    • User's guide
    • Other-cool-system-related-to-this-one document
    • Test plan
    • Competitive system(s)
      • 
+
    • System/Package "coversheet" - where all documentation
+for this software is linked off of
    • Design document
    • Developer's guide
    • User's guide
    • Other-cool-system-related-to-this-one document
    • Test plan
    • Competitive system(s)
      • 
 
    
 
    
 
    
@@ -75,8 +75,8 @@
 identifiers that reflect any functional hierarchy present, e.g.
 20.5.13. - for the first number, leave generous gaps on the first
 writing of requirements (e.g. 1, 10, 20, 30, 40, etc.) because
-you'll want to leave room for any missing key requirements that may
-arise.
    • 
+you'll want to leave room for any missing key requirements that
+may arise.
      • 
 
        10.0 A Common
 Solution
        Programmers and designers should only have to learn a single
 system that serves as a UI substrate for all the functionally
@@ -127,8 +127,8 @@
 0.1Created8/21/2000Josh Finkler, Audrey McLoghlin
 
 
-
      ($‌Id: requirements-template.xml,v 1.6
-2006/07/17 05:38:37 torbenb Exp $)
      
+
    ($‌Id: requirements-template.html,v 1.49.2.10
+2016/06/21 07:44:36 gustafn Exp $)
    
 
    
 
    
 Very broadly, describe how the system meets a need of a business,
 	group, the OpenACS as a whole, etc.  Make sure that technical and
 	non-technical readers alike would understand what the system would do
-	and why it's useful.  Whenever applicable, you should explicitly state
+	and why it's useful.  Whenever applicable, you should explicitly state
 	what the business value of the system is. 
     
    System/Application Overview
    
       Discuss the high-level breakdown of the components that make up
 	the system.  You can go by functional areas, by the main transactions
 	the system allows, etc.  
     
    
       You should also state the context and dependencies of the system
-	here, e.g. if it's an application-level package for OpenACS 4, briefly
+	here, e.g. if it's an application-level package for OpenACS 4, briefly
 	describe how it uses kernel services, like permissions or subsites. 
     
    Use-cases and User-scenarios
    
       Determine the types or classes of users who would use the
@@ -34,18 +34,18 @@
 	take, and how the system would support them.  
     
    Optional: Competitive Analysis
    
       Describe other systems or services that are comparable to what
-	you're building.  If applicable, say why your implementation will be
+	you're building.  If applicable, say why your implementation will be
 	superior, where it will match the competition, and where/why it will
 	lack existing best-of-breed capabilities.  This section is also in the
 	Design doc, so write about it where you deem most appropriate.
     
    Related Links
    Include all pertinent links to supporting and related material,
-      such as: 
    •  System/Package "coversheet" - where all documentation for this software is linked off of
    •  Design document
    •  Developer's guide
    •  User's guide
    •  Other-cool-system-related-to-this-one document
    •  Test plan 
    •  Competitive system(s)
    Requirements
    
+      such as: 
    •  System/Package "coversheet" - where all documentation for this software is linked off of
    •  Design document
    •  Developer's guide
    •  User's guide
    •  Other-cool-system-related-to-this-one document
    •  Test plan 
    •  Competitive system(s)
    Requirements
    
       The main course of the document, requirements. Break up the
 	requirements sections (A, B, C, etc.) as needed.  Within each section,
 	create a list denominated with unique identifiers that reflect any
 	functional hierarchy present, e.g. 20.5.13. - for the first number,
 	leave generous gaps on the first writing of requirements (e.g. 1, 10,
-	20, 30, 40, etc.) because you'll want to leave room for any missing
+	20, 30, 40, etc.) because you'll want to leave room for any missing
 	key requirements that may arise.  
     
    • 10.0 A Common Solution
      
 	  Programmers and designers should only have to learn a single
Index: openacs-4/packages/acs-core-docs/www/rp-design.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-design.adp,v
diff -u -N -r1.1.2.3 -r1.1.2.4
--- openacs-4/packages/acs-core-docs/www/rp-design.adp	9 Jun 2016 08:44:50 -0000	1.1.2.3
+++ openacs-4/packages/acs-core-docs/www/rp-design.adp	23 Jun 2016 08:32:46 -0000	1.1.2.4
@@ -55,13 +55,13 @@
 global namespace containing variables associated with the current
 request.
    • 
 abstract URL -- A
-URL with no extension that doesn't directly correspond to a file in
-the filesystem.
    • 
+URL with no extension that doesn't directly correspond to a
+file in the filesystem.
    • 
 abstract file or
 abstract path -- A URL
 that has been translated into a file system path (probably by
-prepending the appropriate pageroot), but still doesn't have any
-extension and so does not directly correspond to a file in the
+prepending the appropriate pageroot), but still doesn't have
+any extension and so does not directly correspond to a file in the
 filesystem.
    • 
 concrete file or
 concrete path -- A
@@ -149,8 +149,8 @@
 Request Environment
    The request environment is managed by the procedure ad_conn. Variables can be set and
 retrieved through use of the ad_conn procedure. The following
 variables are available for public use. If the ad_conn procedure
-doesn't recognize a variable being passed to it for a lookup, it
-tries to get a value using ns_conn. This guarantees that ad_conn
+doesn't recognize a variable being passed to it for a lookup,
+it tries to get a value using ns_conn. This guarantees that ad_conn
 subsumes the functionality of ns_conn.
    @@ -192,8 +192,8 @@
 Otherwise, it is blank
+sec_validated]
    
 
 

 
    
 [ad_conn
-sec_validated]This becomes "secure" when the connection uses
-SSLThis becomes "secure" when the
+connection uses SSL
 
    Database
 API
    
 [ad_conn
Index: openacs-4/packages/acs-core-docs/www/rp-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-design.html,v
diff -u -N -r1.37.2.1 -r1.37.2.2
--- openacs-4/packages/acs-core-docs/www/rp-design.html	9 Jun 2016 08:44:50 -0000	1.37.2.1
+++ openacs-4/packages/acs-core-docs/www/rp-design.html	23 Jun 2016 08:32:46 -0000	1.37.2.2
@@ -25,10 +25,10 @@
 (/var/lib/aolserver/servicename/packages/package_key/www)
 -- This is the pageroot for the package_key package.
  • request environment (ad_conn) -- This is
 a global namespace containing variables associated with the current
-request.
  • abstract URL -- A URL with no extension that doesn't
+request.
  • abstract URL -- A URL with no extension that doesn't
 directly correspond to a file in the filesystem.
  • abstract file or abstract path -- A URL
 that has been translated into a file system path (probably by prepending the
-appropriate pageroot), but still doesn't have any extension and so does
+appropriate pageroot), but still doesn't have any extension and so does
 not directly correspond to a file in the filesystem.
  • concrete file or concrete path -- A file
 or path that actually references something in the filesystem.
    • System Overview
    Package Lookup
    One of the first things the request processor must do is to determine
 which package instance a given request references, and based on this
@@ -90,7 +90,7 @@
 number of entries in the mapping.
    Request Environment
    The request environment is managed by the procedure
 ad_conn. Variables can be set and retrieved through use of
 the ad_conn procedure. The following variables are available for public use.
-If the ad_conn procedure doesn't recognize a variable being passed to it
+If the ad_conn procedure doesn't recognize a variable being passed to it
 for a lookup, it tries to get a value using ns_conn. This guarantees that
 ad_conn subsumes the functionality of ns_conn.
    
-
    Request processor
    [ad_conn urlv] A list containing each element of the URL
    [ad_conn url] The URL associated with the request.
    [ad_conn query] The portion of the URL from the ? on (i.e. GET
               variables) associated with the request.
    [ad_conn file] The filepath including filename of the file being served
    [ad_conn request] The number of requests since the server was last started
    [ad_conn start_clicks] The system time when the RP starts handling the request
     
    Session System Variables: set in
Index: openacs-4/packages/acs-core-docs/www/rp-requirements.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-requirements.adp,v
diff -u -N -r1.1.2.1 -r1.1.2.2
--- openacs-4/packages/acs-core-docs/www/rp-requirements.adp	23 Sep 2015 11:54:52 -0000	1.1.2.1
+++ openacs-4/packages/acs-core-docs/www/rp-requirements.adp	23 Jun 2016 08:32:46 -0000	1.1.2.2
@@ -29,8 +29,8 @@
 components.
    
 
    
 
    
-System Overview
    The request processor's functionality can be split into two main
-pieces.
      
+System Overview
    The request processor's functionality can be split into two
+main pieces.
      
 
    1. 
 
      Set up the environment in which a server side script expects to
 run. This includes things like:
        
@@ -65,8 +65,8 @@
 Context
        
 20.10 The request
 processor must be able to determine a primary context or state
-associated with a pageroot based on it's location within the URL
-space.
        30.0
+associated with a pageroot based on it's location within the
+URL space.
      30.0
 Authentication
      
 30.10 The request
 processor must be able to verify that the connecting browser
Index: openacs-4/packages/acs-core-docs/www/rp-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-requirements.html,v
diff -u -N -r1.33.2.1 -r1.33.2.2
--- openacs-4/packages/acs-core-docs/www/rp-requirements.html	9 Jun 2016 08:44:50 -0000	1.33.2.1
+++ openacs-4/packages/acs-core-docs/www/rp-requirements.html	23 Jun 2016 08:32:46 -0000	1.33.2.2
@@ -8,7 +8,7 @@
 mounted at arbitrary urls, and tighter integration with the database to allow
 for flexible user controlled url structures, and subsites.
      Vision Statement
      Most web servers are designed to serve pages from exactly one static
 pageroot. This restriction can become cumbersome when trying to build a web
-toolkit full of reusable and reconfigurable components.
      System Overview
      The request processor's functionality can be split into two main
+toolkit full of reusable and reconfigurable components.
      System Overview
      The request processor's functionality can be split into two main
 pieces.
      1. Set up the environment in which a server side script expects to run. This
 includes things like:
        • Initialize common variables associated with a request.
        • Authenticate the connecting party.
        • Check that the connecting party is authorized to proceed with the
 request.
        • Invoke any filters associated with the request URI.
      2. Determine to which entity the request URI maps, and deliver the content
@@ -20,7 +20,7 @@
 for the delivered content.
      It is essential that any errors that occur during the above steps be
 reported to developers in an easily decipherable manner.
      Related Links
      OpenACS 4 Request Processor Design
      Requirements
      10.0 Multiple Pageroots
      10.10 Pageroots may be combined into one URL space.
      10.20 Pageroots may be mounted at more than one location in the URL
 space.
      20.0 Application Context
      20.10 The request processor must be able to determine a primary context
-or state associated with a pageroot based on it's location within the URL
+or state associated with a pageroot based on it's location within the URL
 space.
      30.0 Authentication
      30.10 The request processor must be able to verify that the connecting
 browser actually represents the party it claims to represent.
      40.0 Authorization
      40.10 The request processor must be able to verify that the party the
 connecting browser represents is allowed to make the request.
      50.0 Scalability
    Prev Home Next
    Security Notes Up Request Processor Design
    docs@openacs.org
    View comments on this page at openacs.org
    
Index: openacs-4/packages/acs-core-docs/www/security-design.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-design.adp,v
diff -u -N -r1.1.2.2 -r1.1.2.3
--- openacs-4/packages/acs-core-docs/www/security-design.adp	9 Jun 2016 08:44:50 -0000	1.1.2.2
+++ openacs-4/packages/acs-core-docs/www/security-design.adp	23 Jun 2016 08:32:46 -0000	1.1.2.3
@@ -107,7 +107,7 @@
 
 
  • 
 
    ad_secure_token
      
-
    • is a session-level cookie from the browser's standpoint
    • its signature expires in SessionLifetime seconds
    • contains random garbage (ns_time) to prevent attack against the
+
    • is a session-level cookie from the browser's standpoint
    • its signature expires in SessionLifetime seconds
    • contains random garbage (ns_time) to prevent attack against the
 secure hash
    • user_id is extraneous
      • 
 
    
 
    • 
@@ -133,8 +133,8 @@
 function ad_secure_conn_p is
 used to determine whether or not the URL being accessed is requires
 a secure login. The function simply checks if the location begins
-with "https". (This is safe because the location is set during the
-server initialization.)
    If secure authentication is required, the ad_secure_token cookie is checked to make
+with "https". (This is safe because the location is set
+during the server initialization.)
    If secure authentication is required, the ad_secure_token cookie is checked to make
 sure its data matches the data stored in ad_session_id. This is true for all pages
 except those that are part of the login process. On these pages,
 the user can not yet have received the appropriate ad_secure_token cookie, so no check against
@@ -305,16 +305,17 @@
 of the value and the signature. In addition to the expiration of
 the digital signature, RFC 2109 specifies an optional max age that
 is returned to the client. For most cookies, this max age matches
-the expiration date of the cookie's signature. The standard
+the expiration date of the cookie's signature. The standard
 specifies that when the max age is not included, the cookie should
-be "discarded when the user agent exits." Because we can not trust
-the client to do this, we must specify a timeout for the signature.
-The SessionLifetime parameter is used for this purpose, as it
-represents the maximum possible lifetime of a single session.
    RFC 2109 specifies this optional "secure" parameter which
-mandates that the user-agent use "secure means" to contact the
-server when transmitting the cookie. If a secure cookie is returned
-to the client over https, then the cookie will never be transmitted
-over insecure means.
    
+be "discarded when the user agent exits." Because we can
+not trust the client to do this, we must specify a timeout for the
+signature. The SessionLifetime parameter is used for this purpose,
+as it represents the maximum possible lifetime of a single
+session.
    RFC 2109 specifies this optional "secure" parameter
+which mandates that the user-agent use "secure means" to
+contact the server when transmitting the cookie. If a secure cookie
+is returned to the client over https, then the cookie will never be
+transmitted over insecure means.
    
 
    
 Performance
    Performance is a key goal of this implementation of signed
 cookies. To maximize performance, we will use the following
@@ -347,19 +348,19 @@
 
    
 Security
    Storing information on a client always presents an additional
 security risk.
    Since we are only validating the information and not trying to
-protect it as a secret, we don't use salt. Cryptographic salt is
-useful if you are trying to protect information from being read
+protect it as a secret, we don't use salt. Cryptographic salt
+is useful if you are trying to protect information from being read
 (e.g., hashing passwords).
    
 
    
 
    
 
    
 External SSL
    External SSL mechanisms (firewall, dedicated hardware, etc.) can
 be used by creating two pools of AOLservers. In one pool the
 servers should be configured with the location parameter of nssock
-module set to "https://yourservername". The servers in the other
-pool are configured as normal. The external SSL agent should direct
-SSL queries to the pool of secure servers, and it should direct
-non-SSL queries to the insecure servers.
    
+module set to "https://yourservername". The servers in
+the other pool are configured as normal. The external SSL agent
+should direct SSL queries to the pool of secure servers, and it
+should direct non-SSL queries to the insecure servers.
    
 
    
 
    
 PRNG
    The pseudorandom number generator depends primarily on ns_rand,
Index: openacs-4/packages/acs-core-docs/www/security-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-design.html,v
diff -u -N -r1.35.2.1 -r1.35.2.2
--- openacs-4/packages/acs-core-docs/www/security-design.html	9 Jun 2016 08:44:50 -0000	1.35.2.1
+++ openacs-4/packages/acs-core-docs/www/security-design.html	23 Jun 2016 08:32:46 -0000	1.35.2.2
@@ -44,7 +44,7 @@
 with each cookie serving a different purpose. These cookies are:
    namevaluemax-agesecure?
    ad_session_idsession_id,user_idSessionTimeoutno
    ad_user_loginuser_idInfinityno
    ad_user_login_secureuser_id,randomInfinityyes
    ad_secure_tokensession_id,user_id,randomSessionLifetimeyes
    • ad_session_id
      • reissued on any hit separated by more than SessionRenew seconds from the
 previous hit that received a cookie
      • is valid only for SessionTimeout seconds
      • is the canonical source for the session ID in ad_conn
    • ad_user_login
      • is used for permanent logins
    • ad_user_login_secure
      • is used for permanent secure logins
      • contains random garbage (ns_time) to prevent attack against the secure
 hash
    • ad_secure_token
-
      • is a session-level cookie from the browser's standpoint
      • its signature expires in SessionLifetime seconds
      • contains random garbage (ns_time) to prevent attack against the secure
+
        • is a session-level cookie from the browser's standpoint
        • its signature expires in SessionLifetime seconds
        • contains random garbage (ns_time) to prevent attack against the secure
 hash
        • user_id is extraneous
    Authentication Process
    The Tcl function (sec_handler) is called by the request
 processor to authenticate the user. It first checks the
 ad_session_id cookie. If there is no valid session in progress,
@@ -185,7 +185,7 @@
 value and the signature. In addition to the expiration of the digital
 signature, RFC 2109 specifies an optional max age that is returned to the
 client. For most cookies, this max age matches the expiration date of the
-cookie's signature. The standard specifies that when the max age is not
+cookie's signature. The standard specifies that when the max age is not
 included, the cookie should be "discarded when the user agent
 exits." Because we can not trust the client to do this, we must specify
 a timeout for the signature. The SessionLifetime parameter is used for this
@@ -215,7 +215,7 @@
 the thread is destroyed by AOLserver. 
 
    Security
    Storing information on a client always presents an additional security
 risk.
    Since we are only validating the information and not trying to protect it
-as a secret, we don't use salt. Cryptographic salt is useful if you are
+as a secret, we don't use salt. Cryptographic salt is useful if you are
 trying to protect information from being read (e.g., hashing passwords).
    External SSL
    
 External SSL mechanisms (firewall, dedicated hardware, etc.) can be used by
 creating two pools of AOLservers. In one pool the servers should be
Index: openacs-4/packages/acs-core-docs/www/security-requirements.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-requirements.adp,v
diff -u -N -r1.1.2.1 -r1.1.2.2
--- openacs-4/packages/acs-core-docs/www/security-requirements.adp	23 Sep 2015 11:54:53 -0000	1.1.2.1
+++ openacs-4/packages/acs-core-docs/www/security-requirements.adp	23 Jun 2016 08:32:46 -0000	1.1.2.2
@@ -24,17 +24,17 @@
 displaying the name of the user on certain pages or can be as
 sophisticated as dynamically recommending sections of site that the
 user may be interested in based on prior browsing history. In any
-case, the user's identity must be validated and made available to
-the rest of the system. In addition, sites such as ecommerce
+case, the user's identity must be validated and made available
+to the rest of the system. In addition, sites such as ecommerce
 vendors require that the user identity be securely validated.
    
 
    
 
    
 Security System
 Overview
    The security system consists of a number of subsystems.
    Signed Cookies
    Cookies play a key role in storing user information. However,
-since they are stored in plaintext on a user's system, the validity
-of cookies is an important issue in trusting cookie information.
-Thus, we want to be able to validate a cookie, but we also want to
-validate the cookie without a database hit.
      
+since they are stored in plaintext on a user's system, the
+validity of cookies is an important issue in trusting cookie
+information. Thus, we want to be able to validate a cookie, but we
+also want to validate the cookie without a database hit.
        
 
      • 
 10.0 Guaranteed Tamper
 Detection Any tampering of cookie data should be
Index: openacs-4/packages/acs-core-docs/www/security-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-requirements.html,v
diff -u -N -r1.35.2.1 -r1.35.2.2
--- openacs-4/packages/acs-core-docs/www/security-requirements.html	9 Jun 2016 08:44:50 -0000	1.35.2.1
+++ openacs-4/packages/acs-core-docs/www/security-requirements.html	23 Jun 2016 08:32:46 -0000	1.35.2.2
@@ -9,14 +9,14 @@
 The level of personalization may be as simple as displaying the name of the
 user on certain pages or can be as sophisticated as dynamically recommending
 sections of site that the user may be interested in based on prior browsing
-history. In any case, the user's identity must be validated and made
+history. In any case, the user's identity must be validated and made
 available to the rest of the system. In addition, sites such as ecommerce
 vendors require that the user identity be securely validated. 
 
      Security System Overview
      
 The security system consists of a number of subsystems. 
 
      Signed Cookies
      
 Cookies play a key role in storing user information. However, since they are
-stored in plaintext on a user's system, the validity of cookies is an
+stored in plaintext on a user's system, the validity of cookies is an
 important issue in trusting cookie information. Thus, we want to be able to
 validate a cookie, but we also want to validate the cookie without a database
 hit. 
Index: openacs-4/packages/acs-core-docs/www/snapshot-backup.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/snapshot-backup.adp,v
diff -u -N -r1.1.2.2 -r1.1.2.3
--- openacs-4/packages/acs-core-docs/www/snapshot-backup.adp	9 Jun 2016 13:03:11 -0000	1.1.2.2
+++ openacs-4/packages/acs-core-docs/www/snapshot-backup.adp	23 Jun 2016 08:32:46 -0000	1.1.2.3
@@ -17,7 +17,8 @@
 the information needed to rebuild the site, including the AOLserver
 config files, is then in tree for regular file system backup.
        
 
      1. 
-
        Back up the database to a file. 
          
+
          Back up the database to a
+file. 
            
 
          • 
 
            
 Oracle. 
@@ -106,9 +107,9 @@
 
          
 
        • 
 
          
-Back up the file system. Back up all of the
-files in the service, including the database backup file but
-excluding the auto-generated supervise directory, which is unneccesary and has
+Back up the file system. Back up
+all of the files in the service, including the database backup file
+but excluding the auto-generated supervise directory, which is unneccesary and has
 complicated permissions.
          In the tar command,
            
 
          • 
 c create a new tar
@@ -120,7 +121,7 @@
 gzip.
          • The --exclude clauses skips
 some daemontools files that are owned by root and thus cannot be
 backed up by the service owner. These files are autogenerated and
-we don't break anything by omitting them.
          • The --file clause specifies
+we don't break anything by omitting them.
          • The --file clause specifies
 the name of the output file to be generated; we manually add the
 correct extensions.
          • The last clause, /var/lib/aolserver/$OPENACS_SERVICE_NAME/,
 specifies the starting point for backup. Tar defaults to recursive
@@ -136,7 +137,7 @@
 
          • 
 
            
 Suffer a catastrophic failure on your production
-system. (We'll simulate this step)
            +system. (We'll simulate this step)
             [root root]# svc -d /service/$OPENACS_SERVICE_NAME
 [root root]# mv /var/lib/aolserver/$OPENACS_SERVICE_NAME/ /var/lib/aolserver/$OPENACS_SERVICE_NAME.lost
 [root root]# rm /service/$OPENACS_SERVICE_NAME
@@ -185,8 +186,8 @@
 
      
 
    • 
 
      
-Postgres. If the database
-user does not already exist, create it.
      +Postgres. If
+the database user does not already exist, create it.
       [root root]# su - postgres
 [postgres ~]$ createuser $OPENACS_SERVICE_NAME
 
Index: openacs-4/packages/acs-core-docs/www/snapshot-backup.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/snapshot-backup.html,v
diff -u -N -r1.13.2.1 -r1.13.2.2
--- openacs-4/packages/acs-core-docs/www/snapshot-backup.html	9 Jun 2016 08:44:50 -0000	1.13.2.1
+++ openacs-4/packages/acs-core-docs/www/snapshot-backup.html	23 Jun 2016 08:32:46 -0000	1.13.2.2
@@ -79,7 +79,7 @@
           unneccesary and has complicated permissions.  
      In the tar command,
      • c create a
             new tar archive
      • p preserves permissions.
      • s preserves file sort order
      • z compresses the output with gzip.
      • The --exclude clauses skips some daemontools files that
             are owned by root and thus cannot be backed up by the
-            service owner.  These files are autogenerated and we don't
+            service owner.  These files are autogenerated and we don't
             break anything by omitting them.
      • The --file clause
             specifies the name of the output file to be generated; we
             manually add the correct extensions.
      • The last clause,
@@ -89,7 +89,7 @@
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ tar -cpsz --exclude /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/supervise \
    --file /var/tmp/$OPENACS_SERVICE_NAME-backup.tar.gz /var/lib/aolserver/$OPENACS_SERVICE_NAME/
 tar: Removing leading `/' from member names
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
    • Suffer a catastrophic failure on your production system. (We'll simulate this step)
      [root root]# svc -d /service/$OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
    • Suffer a catastrophic failure on your production system. (We'll simulate this step)
      [root root]# svc -d /service/$OPENACS_SERVICE_NAME
 [root root]# mv /var/lib/aolserver/$OPENACS_SERVICE_NAME/ /var/lib/aolserver/$OPENACS_SERVICE_NAME.lost
 [root root]# rm /service/$OPENACS_SERVICE_NAME
 rm: remove symbolic link `/service/$OPENACS_SERVICE_NAME'? y
Index: openacs-4/packages/acs-core-docs/www/style-guide.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/style-guide.adp,v
diff -u -N -r1.1.2.5 -r1.1.2.6
--- openacs-4/packages/acs-core-docs/www/style-guide.adp	9 Jun 2016 13:03:11 -0000	1.1.2.5
+++ openacs-4/packages/acs-core-docs/www/style-guide.adp	23 Jun 2016 08:32:46 -0000	1.1.2.6
@@ -17,9 +17,9 @@
 of tcl code, about 460,000 lines of sql (in datamodel scripts and
 .xql files), about 80,000 lines of markup in .adp files, and about
 100,000 lines of documentation. All told, just about a million
-lines of "stuff". In terms of logical units there are about 160
-packages, 800 tables, 2,000 stored procedures, about 2,000
-functional pages, and about 3,200 tcl procedures.
      When confronted by this much complexity it's important to be
+lines of "stuff". In terms of logical units there are
+about 160 packages, 800 tables, 2,000 stored procedures, about
+2,000 functional pages, and about 3,200 tcl procedures.
      When confronted by this much complexity it's important to be
 able to make sense of it without having to wade through it all.
 Things should be coherent, things should be named predictably and
 behave like you would expect, and your guess about what something
@@ -38,53 +38,56 @@
 requirements for things to function correctly (for example data
 model creation scripts and tcl library files must be named properly
 to be used), while some are suggestions (the object-verb naming convention) which if
-ignored won't break anything, but if you follow the rules people
-will be able to understand your package much more easily.
    • 
-Be literate in your programming.  Use
-ad_proc, ad_library, and ad_page_contract to provide documentation
-for your code, use comments on your datamodel, explain what things
-mean and how they should work.
    • 
-Test.  Write test cases for your API and data
-model; test negative cases as well as positive; document your
-tests. Provide tests for bugs which are not yet fixed. Test, Test,
-Test.
    • 
-Use namespaces.  For new packages choose a
-namespace and place all procedures in it and in oracle create
-packages.
    • 
+ignored won't break anything, but if you follow the rules
+people will be able to understand your package much more
+easily.
    • 
+Be literate in your programming. 
+Use ad_proc, ad_library, and ad_page_contract to provide
+documentation for your code, use comments on your datamodel,
+explain what things mean and how they should work.
    • 
+Test.  Write test cases for your
+API and data model; test negative cases as well as positive;
+document your tests. Provide tests for bugs which are not yet
+fixed. Test, Test, Test.
    • 
+Use namespaces.  For new packages
+choose a namespace and place all procedures in it and in oracle
+create packages.
    • 
 Follow the constraint naming and the PL/SQL and PL/pgSQL
 rules.  Naming constraints is important for
 upgradability and for consistency. Also, named constraints can be
 immensely helpful in developing good error handling. Following the
 PL/SQL and PL/pgSQL rules ensure that the procedures created can be
 handled similarly across both Oracle and PostgreSQL databases.
    • 
-Follow the code formatting guidelines.  The
-code base is very large and if things are formatted consistently it
-is easier to read. Also, if it conforms to the standard it won't be
-reformatted (which can mask the change history and making tracking
-down bugs much harder). Using spaces rather than tabs makes patches
-easier to read and manage and does not force other programmers to
-decipher what tab settings you had in place in your editor.
    • 
-Use the standard APIs.  Don't reinvent the
-wheel. Prefer extending an existing core API to creating your own.
-If something in the core does not meet your particular needs it
-probably won't meet others as well and fleshing out the core API's
-makes the toolkit more useful for everyone and more easily
-extended.
    • 
+Follow the code formatting
+guidelines.  The code base is very large and
+if things are formatted consistently it is easier to read. Also, if
+it conforms to the standard it won't be reformatted (which can
+mask the change history and making tracking down bugs much harder).
+Using spaces rather than tabs makes patches easier to read and
+manage and does not force other programmers to decipher what tab
+settings you had in place in your editor.
    • 
+Use the standard APIs.  Don't
+reinvent the wheel. Prefer extending an existing core API to
+creating your own. If something in the core does not meet your
+particular needs it probably won't meet others as well and
+fleshing out the core API's makes the toolkit more useful for
+everyone and more easily extended.
    • 
 Make sure your datamodel create/drop scripts
 work.  Break the table creation out from the
 package/stored procedure creation and use create or replace where possible so that
 scripts can be sourced more than once. Make sure your drop script
 works if data has been inserted (and permissioned and notifications
 have been attached etc).
    • 
 
      
-Practice CVS/Bug Tracker Hygiene.  Commit
-your work. commit with sensible messages and include patch and bug
-numbers in your commit messages.
      Create bug tracker tickets for things you are going to work on
-yourself (just in case you don't get to it and to act as a pointer
-for others who might encounter the same problem).
      
+Practice CVS/Bug Tracker Hygiene. 
+Commit your work. commit with sensible messages and include patch
+and bug numbers in your commit messages.
      Create bug tracker tickets for things you are going to work on
+yourself (just in case you don't get to it and to act as a
+pointer for others who might encounter the same problem).
      
 
    • 
-Solicit code reviews.  Ask others to look
-over your code and provide feedback and do the same for others.
      • 
+Solicit code reviews.  Ask others
+to look over your code and provide feedback and do the same for
+others.
      
 
      
 
    
 
    
@@ -96,8 +99,8 @@
 
    
 0.1Creation12/2003Jeff Davis
 
    ($‌Id: style-guide.xml,v 1.3 2006/07/17 05:38:37
-torbenb Exp $)
    
+
    ($‌Id: style-guide.html,v 1.28.2.10 2016/06/21
+07:44:36 gustafn Exp $)
    
 
    
 
    
 
    
-      When confronted by this much complexity it's important to be
+      When confronted by this much complexity it's important to be
       able to make sense of it without having to wade through it all.
       Things should be coherent, things should be named predictably
       and behave like you would expect, and your guess about what
@@ -35,7 +35,7 @@
             scripts and tcl library files must be named properly to be
             used), while some are suggestions (the
             object-verb naming convention) which
-            if ignored won't break anything, but if you follow the
+            if ignored won't break anything, but if you follow the
             rules people will be able to understand your package much
             more easily.
           
  • Be literate in your programming. 
@@ -59,16 +59,16 @@
           
  • Follow the code formatting guidelines. 
             The code base is very large and if things are formatted
             consistently it is easier to read.  Also, if it conforms
-            to the standard it won't be reformatted (which can mask
+            to the standard it won't be reformatted (which can mask
             the change history and making tracking down bugs much
             harder).  Using spaces rather than tabs makes patches
             easier to read and manage and does not force other
             programmers to decipher what tab settings you had in place
             in your editor.
           
  • Use the standard APIs. 
-            Don't reinvent the wheel.  Prefer extending an existing
+            Don't reinvent the wheel.  Prefer extending an existing
             core API to creating your own.  If something in the core
-            does not meet your particular needs it probably won't meet
+            does not meet your particular needs it probably won't meet
             others as well and fleshing out the core API's makes the
             toolkit more useful for everyone and more easily extended.
           
  • Make sure your datamodel create/drop scripts work. 
@@ -83,7 +83,7 @@
             patch and bug numbers in your commit messages.
           
    
           Create bug tracker tickets for things you are going to work
-          on yourself (just in case you don't get to it and to act as
+          on yourself (just in case you don't get to it and to act as
           a pointer for others who might encounter the same problem).
         
  • Solicit code reviews. 
             Ask others to look over your code and provide feedback and do 
Index: openacs-4/packages/acs-core-docs/www/subsites-design.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-design.adp,v
diff -u -N -r1.1.2.1 -r1.1.2.2
--- openacs-4/packages/acs-core-docs/www/subsites-design.adp	23 Sep 2015 11:54:54 -0000	1.1.2.1
+++ openacs-4/packages/acs-core-docs/www/subsites-design.adp	23 Jun 2016 08:32:46 -0000	1.1.2.2
@@ -41,14 +41,15 @@
 Historical
 Considerations
    The subsites problem actually has several quite diverse origins.
 It was originally recognized as a toolkit feature in the form of
-"scoping". The basic concept behind scoping was to allow one scoped
-OpenACS installation to behave as multiple unscoped OpenACS
-installations so that one OpenACS install could serve multiple
-communities. Each piece of application data was tagged with a
-"scope" consisting of the (user_id, group_id, scope) triple. In
-practice the highly denormalized data models that this method uses
-produced large amounts of very redundant code and in general made
-it an extremely cumbersome process to "scopify" a module.
    Before the advent of scoping there were several cases of client
+"scoping". The basic concept behind scoping was to allow
+one scoped OpenACS installation to behave as multiple unscoped
+OpenACS installations so that one OpenACS install could serve
+multiple communities. Each piece of application data was tagged
+with a "scope" consisting of the (user_id, group_id,
+scope) triple. In practice the highly denormalized data models that
+this method uses produced large amounts of very redundant code and
+in general made it an extremely cumbersome process to
+"scopify" a module.
    Before the advent of scoping there were several cases of client
 projects implementing their own version of scoping in special
 cases. One example being the wineaccess multi-retailer ecommerce.
 (Remember the other examples and get details. Archnet?,
@@ -218,9 +219,9 @@
 
 
    
 
    
-Data Model Discussion
    The subsites implementation doesn't really have it's own data
-model, although it depends heavily on the site-nodes data model,
-and the APM data model.
    
+Data Model Discussion
    The subsites implementation doesn't really have it's own
+data model, although it depends heavily on the site-nodes data
+model, and the APM data model.
    
 
    
 
    
 User Interface
    The primary elements of the subsite user interface consist of
@@ -242,14 +243,15 @@
 developers begin to use the subsites system for more sophisticated
 projects, it will become necessary to develop tools to help build
 tightly integrated packages. The general area this falls under is
-"inter-package communication". An actual implementation of this
-could be anything from clever use of configuration parameters to
-lots of package level introspection. Another area that is currently
-underdeveloped is the ability to "tar up" and distribute a
-particular configuration of site nodes/packages. As we build more
-fundamental applications that can be applied in more general areas,
-this feature will become more and more in demand since more
-problems will be solvable by configuration instead of coding.
    
+"inter-package communication". An actual implementation
+of this could be anything from clever use of configuration
+parameters to lots of package level introspection. Another area
+that is currently underdeveloped is the ability to "tar
+up" and distribute a particular configuration of site
+nodes/packages. As we build more fundamental applications that can
+be applied in more general areas, this feature will become more and
+more in demand since more problems will be solvable by
+configuration instead of coding.
    
 
    
 
    
 Authors
    rhs\@mit.edu
    
Index: openacs-4/packages/acs-core-docs/www/subsites-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-design.html,v
diff -u -N -r1.35.2.1 -r1.35.2.2
--- openacs-4/packages/acs-core-docs/www/subsites-design.html	9 Jun 2016 08:44:50 -0000	1.35.2.1
+++ openacs-4/packages/acs-core-docs/www/subsites-design.html	23 Jun 2016 08:32:46 -0000	1.35.2.2
@@ -192,7 +192,7 @@
 [ad_conn subsite_url]
     
 
-
    Data Model Discussion
    The subsites implementation doesn't really have it's own data
+
    Data Model Discussion
    The subsites implementation doesn't really have it's own data
 model, although it depends heavily on the site-nodes data model, and the APM
 data model.
    User Interface
    The primary elements of the subsite user interface consist of the subsite
 admin pages. These pages are divided up into two areas: Group administration,
Index: openacs-4/packages/acs-core-docs/www/subsites-requirements.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-requirements.adp,v
diff -u -N -r1.1.2.2 -r1.1.2.3
--- openacs-4/packages/acs-core-docs/www/subsites-requirements.adp	9 Jun 2016 08:44:50 -0000	1.1.2.2
+++ openacs-4/packages/acs-core-docs/www/subsites-requirements.adp	23 Jun 2016 08:32:46 -0000	1.1.2.3
@@ -28,39 +28,39 @@
 company (e.g., offices, departments, teams, projects) and external
 parties (e.g., customers, partners, vendors). Subsites enable a
 single OpenACS instance to provide each subcommunity with its own
-"virtual website," by assembling OpenACS packages that together
-deliver a feature set tailored to the needs of the
+"virtual website," by assembling OpenACS packages that
+together deliver a feature set tailored to the needs of the
 subcommunity.
    
 
    
 
    
 System Overview
    The OpenACS subsite system allows a single OpenACS installation
 to serve multiple communities. At an implementation level this is
-primarily accomplished by having an application "scope" its content
-to a particular package instance. The request
+primarily accomplished by having an application "scope"
+its content to a particular package instance. The request
 processor then figures out which package_id a particular URL
 references and then provides this information through the
 ad_conn api ([ad_conn package_id], [ad_conn package_url]).
    The other piece of the subsite system is a subsite package that
-provides subsite admins a "control panel" for administering their
-subsite. This is the same package used to provide all the community
-core functionality available at the "main" site which is in fact
-simply another subsite.
    
+provides subsite admins a "control panel" for
+administering their subsite. This is the same package used to
+provide all the community core functionality available at the
+"main" site which is in fact simply another subsite.
    
 
    
 
    
 Use-cases and
 User-scenarios
    The Subsites functionality is intended for use by two different
 classes of users:
      
-
    1. Package programmers (referred to as 'the programmer') must
-develop subcommunity-aware applications.
    2. Site administrators (referred to as 'the administrator') use
-subsites to provide tailored "virtual websites" to different
-subcommunities.
      3. 
+
    3. Package programmers (referred to as 'the programmer')
+must develop subcommunity-aware applications.
    4. Site administrators (referred to as 'the administrator')
+use subsites to provide tailored "virtual websites" to
+different subcommunities.
      5. 
 
    Joe Programmer is working on the forum package and wants to make
 it subsite-aware. Using [ad_conn package_id], Joe adds code that
 only displays forum messages associated with the current package
 instance. Joe is happy to realize that parameter::get is already
 smart enough to return configuration parameters for the current
 package instance, and so he has to do no extra work to tailor
-configuration parameters to the current subsite.
    Jane Admin maintains www.company.com. She learns of Joe's work
-and would like to set up individual forums for the Boston and
+configuration parameters to the current subsite.
    Jane Admin maintains www.company.com. She learns of Joe's
+work and would like to set up individual forums for the Boston and
 Austin offices of her company. The first thing she does is use the
 APM to install the new forum package.
    Next, Jane uses the Subsite UI to create subsites for the Boston
 and Austin offices. Then Jane uses the Subsite UI to create forums
@@ -77,27 +77,28 @@
 
    
 
    
 
    
-Requirements: Programmer's API
    A subsite API is required for programmers to ensure their
+Requirements: Programmer's
+API
    A subsite API is required for programmers to ensure their
 packages are subsite-aware. The following functions should be
 sufficient for this:
    10.10.0 Package
 creation
    The system must provide an API call to create a package, and it
 must be possible for the context (to which the package belongs) to
 be specified.
    10.20.0 Package
 deletion
    The system must provide an API call to delete a package and all
-related objects in the subsite's context.
    10.30.0 Object's package
+related objects in the subsite's context.
    10.30.0 Object's package
 information
    Given an object ID, the system must provide an API call to
 determine the package (ID) to which the object belongs.
    10.40.0 URL from
 package
    Given a package (ID), the system must provide an API call to
-return the canonical URL for that package.
    10.50.0 Main subsite's
+return the canonical URL for that package.
    10.50.0 Main subsite's
 package_id
    The system must provide an API call to return a package ID
-corresponding to the main subsite's package ID (the degenerate
+corresponding to the main subsite's package ID (the degenerate
 subsite).
    
 
    
 
    
 Requirements: The User
-Interface
    The Programmer's User
-Interface
    There is no programmer's UI, other than the API described
-above.
    The Administrator's User
+Interface
    The Programmer's User
+Interface
    There is no programmer's UI, other than the API described
+above.
    The Administrator's User
 Interface
    The UI for administrators is a set of HTML pages that are used
 to drive the underlying API for package instance management (i.e.
 adding, removing, or altering packages). It is restricted to
Index: openacs-4/packages/acs-core-docs/www/subsites-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-requirements.html,v
diff -u -N -r1.34.2.1 -r1.34.2.2
--- openacs-4/packages/acs-core-docs/www/subsites-requirements.html	9 Jun 2016 08:44:50 -0000	1.34.2.1
+++ openacs-4/packages/acs-core-docs/www/subsites-requirements.html	23 Jun 2016 08:32:46 -0000	1.34.2.2
@@ -31,7 +31,7 @@
 forum messages associated with the current package instance. Joe is happy to
 realize that parameter::get is already smart enough to return configuration
 parameters for the current package instance, and so he has to do no extra
-work to tailor configuration parameters to the current subsite.
    Jane Admin maintains www.company.com. She learns of Joe's work and
+work to tailor configuration parameters to the current subsite.
    Jane Admin maintains www.company.com. She learns of Joe's work and
 would like to set up individual forums for the Boston and Austin offices of
 her company. The first thing she does is use the APM to install the new
 forum package.
    Next, Jane uses the Subsite UI to create subsites for the Boston and
@@ -40,13 +40,13 @@
 http://www.company.com/offices/boston/forum, and similarly for the Austin
 office. At this point, the Boston and Austin office admins can customize the
 configurations for each of their forums, or they can just use the
-defaults.
    Related Links
    Requirements: Programmer's API
    A subsite API is required for programmers to ensure their packages are
+defaults.
    Related Links
    Requirements: Programmer's API
    A subsite API is required for programmers to ensure their packages are
 subsite-aware. The following functions should be sufficient for this:
    10.10.0 Package creation
    The system must provide an API call to create a package, and it must be
 possible for the context (to which the package belongs) to be specified.
    10.20.0 Package deletion
    The system must provide an API call to delete a package and all related
-objects in the subsite's context.
    10.30.0 Object's package information
    Given an object ID, the system must provide an API call to determine the
+objects in the subsite's context.
    10.30.0 Object's package information
    Given an object ID, the system must provide an API call to determine the
 package (ID) to which the object belongs.
    10.40.0 URL from package
    Given a package (ID), the system must provide an API call to return the
-canonical URL for that package.
    10.50.0 Main subsite's package_id
    The system must provide an API call to return a package ID corresponding
-to the main subsite's package ID (the degenerate subsite).
    Requirements: The User Interface
    The Programmer's User Interface
    There is no programmer's UI, other than the API described above.
    The Administrator's User Interface
    The UI for administrators is a set of HTML pages that are used to drive
+canonical URL for that package.
    10.50.0 Main subsite's package_id
    The system must provide an API call to return a package ID corresponding
+to the main subsite's package ID (the degenerate subsite).
    Requirements: The User Interface
    The Programmer's User Interface
    There is no programmer's UI, other than the API described above.
    The Administrator's User Interface
    The UI for administrators is a set of HTML pages that are used to drive
 the underlying API for package instance management (i.e. adding, removing, or
 altering packages). It is restricted to administrators of the current subsite
 such that administrators can only manage their own subsites. Of course,
Index: openacs-4/packages/acs-core-docs/www/subsites.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites.adp,v
diff -u -N -r1.1.2.4 -r1.1.2.5
--- openacs-4/packages/acs-core-docs/www/subsites.adp	9 Jun 2016 13:03:11 -0000	1.1.2.4
+++ openacs-4/packages/acs-core-docs/www/subsites.adp	23 Jun 2016 08:32:46 -0000	1.1.2.5
@@ -14,15 +14,15 @@
 OpenACS docs are written by the named authors, and may be edited by
 OpenACS documentation staff.
    
 
    
-Overview
    In this document, we'll examine the user interface pages of the
-Notes application in more detail, covering two separate aspects of
-page development in OpenACS. First, we'll talk about the code
-needed to make your pages aware of which application instance they
-are running in. Second, we'll talk about using the form builder to
-develop form-based user interfaces in OpenACS. While these seem
-like unrelated topics, they both come up in the example page that
-we are going to look at, so it makes sense to address them at the
-same time.
    
+Overview
    In this document, we'll examine the user interface pages of
+the Notes application in more detail, covering two separate aspects
+of page development in OpenACS. First, we'll talk about the
+code needed to make your pages aware of which application instance
+they are running in. Second, we'll talk about using the form
+builder to develop form-based user interfaces in OpenACS. While
+these seem like unrelated topics, they both come up in the example
+page that we are going to look at, so it makes sense to address
+them at the same time.
    
 
    
 
    
 Application Instances and Subsites
    As you will recall from the packages tutorial, the Request
@@ -34,8 +34,8 @@
 mapping mounting the
 application instance at a particular URL. The tutorial also showed
 how a given URL is translated into a physical file to serve using
-the site map. We'll repeat this description here, assuming that you
-have mounted an instance of Notes at the URL /notes as we did in the packages-example:
      
+the site map. We'll repeat this description here, assuming that
+you have mounted an instance of Notes at the URL /notes as we did in the packages-example:
        
 
      • AOLserver receives your request for the URL /notes/somepage.
      • This URL is passed to the request processor.
      • The RP looks up the URL in the site map, and sees that the
 object mounted at that location is an instance of the notes application.
      • The RP asks the package manager where in the file system the
 Notes package lives. In the standard case, this would be
@@ -60,8 +60,8 @@
 following the part that matched a site map entry.
        
 
      In the Notes example, we are particularly interested in the
 package_id field. If you study
-the data model and code, you'll see why. As we said before in the
-data modeling
+the data model and code, you'll see why. As we said before in
+the data modeling
 tutorial, the Notes application points the context_id of each Note object that it
 creates to the package instance that created it. That is, the
 context_id corresponds exactly
@@ -110,7 +110,7 @@
 the template system. This API allows you to write forms-based pages
 without generating a lot of duplicated HTML in your pages. It also
 encapsulates most of the common logic that we use in dealing with
-forms, which we'll discuss next.
      
+forms, which we'll discuss next.
      
 
    
 
    
 Using Forms
    The forms API is pretty simple: You use calls in the
@@ -208,9 +208,9 @@
   ad_returnredirect "."
 }
 
-
    In this simple example, we don't do any custom validation. The
-nice thing about using this API is that the forms library handles
-all of the HTML rendering, input validation and database
+
    In this simple example, we don't do any custom validation.
+The nice thing about using this API is that the forms library
+handles all of the HTML rendering, input validation and database
 transaction logic on your behalf. This means that you can write
 pages without duplicating all of that code in every set of pages
 that uses forms.
    
@@ -222,7 +222,7 @@
 server and then try out the user interface pages. It should become
 clear that in a real site, you would be able to, say, create a
 custom instance of Notes for every registered user, mount that
-instance at the user's home page, and set up the permissions so
+instance at the user's home page, and set up the permissions so
 that the instance is only visible to that user. The end result is a
 site where users can come and write notes to themselves.
    This is a good example of the leverage available in the OpenACS
 5.9.0 system. The code that we have written for Notes is not at all
@@ -240,10 +240,10 @@
 structure web services in very flexible ways.
    We saw how to use this mechanism in the Notes application and
 how it makes it possible to easily turn Notes into an application
 that appears to provide each user in a system with their own
-private notes database.
    We also saw how to use the templating system's forms API in a
-simple way, to create forms based pages with minimal duplication of
-code.
    ($‌Id: subsites.xml,v 1.9 2014/10/27 16:39:30
-victorg Exp $)
    
+private notes database.
    We also saw how to use the templating system's forms API in
+a simple way, to create forms based pages with minimal duplication
+of code.
    ($‌Id: subsites.html,v 1.48.2.10 2016/06/21
+07:44:36 gustafn Exp $)
    
 
    
 
    
 
    Overview
    
-In this document, we'll examine the user interface pages of the Notes
+In this document, we'll examine the user interface pages of the Notes
 application in more detail, covering two separate aspects of page
-development in OpenACS. First, we'll talk about the code needed to make
+development in OpenACS. First, we'll talk about the code needed to make
 your pages aware of which application instance they are running
-in. Second, we'll talk about using the form builder to develop
+in. Second, we'll talk about using the form builder to develop
 form-based user interfaces in OpenACS. While these seem like unrelated
 topics, they both come up in the example page that we are going to
 look at, so it makes sense to address them at the same time.
@@ -20,7 +20,7 @@
 application instances to particular URLs within a site. We call
 creating such a mapping mounting the application instance at a
 particular URL.  The tutorial also showed how a given URL is
-translated into a physical file to serve using the site map. We'll
+translated into a physical file to serve using the site map. We'll
 repeat this description here, assuming that you have mounted an
 instance of Notes at the URL /notes as we did in the packages-example:
 
    • 
@@ -67,7 +67,7 @@
 
    
 In the Notes example, we are particularly interested in the
 package_id field.  If you study the data model and code,
-you'll see why. As we said before in the data modeling tutorial, the Notes application points the
+you'll see why. As we said before in the data modeling tutorial, the Notes application points the
 context_id of each Note object that it creates to the
 package instance that created it. That is, the context_id
 corresponds exactly to the package_id that comes in from
@@ -123,7 +123,7 @@
 template system. This API allows you to write forms-based pages
 without generating a lot of duplicated HTML in your pages. It also
 encapsulates most of the common logic that we use in dealing with
-forms, which we'll discuss next.
+forms, which we'll discuss next.
 
    Using Forms
    
 The forms API is pretty simple: You use calls in the
 template::form namespace in your Tcl script to create
@@ -238,7 +238,7 @@
 }
 
 
    
-In this simple example, we don't do any custom validation. The nice
+In this simple example, we don't do any custom validation. The nice
 thing about using this API is that the forms library handles all of
 the HTML rendering, input validation and database transaction logic on
 your behalf. This means that you can write pages without duplicating
@@ -249,7 +249,7 @@
 repository, mount an instance of Notes somewhere in your server and
 then try out the user interface pages. It should become clear that in
 a real site, you would be able to, say, create a custom instance of
-Notes for every registered user, mount that instance at the user's
+Notes for every registered user, mount that instance at the user's
 home page, and set up the permissions so that the instance is only
 visible to that user. The end result is a site where users can come
 and write notes to themselves.
@@ -272,6 +272,6 @@
 appears to provide each user in a system with their own private notes
 database.
 
    
-We also saw how to use the templating system's forms API in a simple
+We also saw how to use the templating system's forms API in a simple
 way, to create forms based pages with minimal duplication of code.
 
    ($Id$)
    Prev Home Next
    Groups, Context, Permissions Up Parties in OpenACS
    docs@openacs.org
    View comments on this page at openacs.org
    
Index: openacs-4/packages/acs-core-docs/www/tcl-doc.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tcl-doc.adp,v
diff -u -N -r1.1.2.4 -r1.1.2.5
--- openacs-4/packages/acs-core-docs/www/tcl-doc.adp	28 Sep 2015 07:54:25 -0000	1.1.2.4
+++ openacs-4/packages/acs-core-docs/www/tcl-doc.adp	23 Jun 2016 08:32:46 -0000	1.1.2.5
@@ -22,15 +22,15 @@
 #
 # path from server home/filename
 #
-# Brief description of the file's purpose
+# Brief description of the file's purpose
 #
-# author's email address, file creation date
+# author's email address, file creation date
 #
-# $‌Id: tcl-doc.xml,v 1.7 2006/07/17 05:38:38 torbenb Exp $
+# $‌Id: tcl-doc.html,v 1.49.2.10 2016/06/21 07:44:36 gustafn Exp $
 #
 
    In addition, the inputs expected by a Tcl page (i.e., form
 variables) would be enumerated in a call to ad_page_variables, in effect, documenting
-the page's argument list.
    The problem with these practices is that the documentation is
+the page's argument list.
    The problem with these practices is that the documentation is
 only accessible by reading the source file itself. For this reason,
 ACS 3.4 introduces a new API for documenting Tcl files and, on top
 of that, a web-based user interface for browsing the
@@ -50,22 +50,23 @@
 
  • Facilitates automatic generation of human-readable
 documentation.
  • Promotes security, by introducing a standard and automated way
 to check inputs to scripts for correctness.
  • Allows graphical designers to determine easily how to customize
-sites' UIs, e.g., what properties are available in templates.
  • Allows the request processor to be intelligent: a script can
+sites' UIs, e.g., what properties are available in
+templates.
  • Allows the request processor to be intelligent: a script can
 specify in its contract which type of abstract document it returns,
 and the request processor can transform it automatically into
-something useful to a particular user agent. (Don't worry about
-this for now - it's not complete for ACS 3.4.)
    • 
+something useful to a particular user agent. (Don't worry about
+this for now - it's not complete for ACS 3.4.)
    
 
 
    
 
    
 ad_page_contract
    Currently ad_page_contract
 serves mostly as a replacement for ad_page_variables. Eventually, it will be
-integrated closely with the documents API so that each script's
+integrated closely with the documents API so that each script's
 contract will document precisely the set of properties available to
 graphical designers in templates. (Document API integration is
-subject to change, so we don't decsribe it here yet; for now, you
-can just consider ad_page_contract a newer, better,
-documented ad_page_variables.)
    Let's look at an example usage of ad_page_contract:
    +subject to change, so we don't decsribe it here yet; for now,
+you can just consider ad_page_contract a newer, better,
+documented ad_page_variables.)
    Let's look at an example usage of ad_page_contract:
     
 # /packages/acs-kernel/api-doc/www/package-view.tcl
 ad_page_contract {
@@ -85,17 +86,17 @@
 
     \@author Jon Salz (jsalz\@mit.edu)
     \@creation-date 3 Jul 2000
-    \@cvs-id $‌Id$
+    \@cvs-id $‌Id: tcl-doc.html,v 1.49.2.10 2016/06/21 07:44:36 gustafn Exp $
 }
 
 
    Note that:
      
 
    • 
 By convention, ad_page_contract should be preceded by a
-comment line containing the file's path. The
+comment line containing the file's path. The
 comment is on line 1, and the contract starts on line 2.
    • 
-ad_page_contract's first
-argument is the list of expected arguments from the HTTP query
-(version_id, public_p, kind, and format). Like ad_page_variables, ad_page_contract sets the corresponding Tcl
+ad_page_contract's
+first argument is the list of expected arguments from the HTTP
+query (version_id, public_p, kind, and format). Like ad_page_variables, ad_page_contract sets the corresponding Tcl
 variables when the page is executed.
    • 
 Arguments can have
 defaults, specified using the same syntax as in the
@@ -109,10 +110,11 @@
 (separated by commas):
        
 
      • 
 optional: the query
-argument doesn't need to be provided; if it's not, the variable for
-that argument simply won't be set. For instance, if I call the
-script above without a public_p
-in the query, then in the page body [info exists public_p] will return 0.
      • 
+argument doesn't need to be provided; if it's not, the
+variable for that argument simply won't be set. For instance,
+if I call the script above without a public_p in the query, then in the page
+body [info exists public_p]
+will return 0.
      • 
 integer: the argument must
 be an integer (ad_page_contract
 will fail and display and error if not). This flag, like the next,
@@ -127,8 +129,10 @@
 multiple: the argument may
 be specified arbitrarily many times in the query string, and the
 variable will be set to a list of all those values (or an empty
-list if it's unspecified). This is analogous to the -multiple-list flag to ad_page_variables, and is useful for
-handling form input generated by <SELECT MULTIPLE> tags and
+list if it's unspecified). This is analogous to the
+-multiple-list flag to
+ad_page_variables, and is
+useful for handling form input generated by <SELECT MULTIPLE> tags and
 checkboxes.
        For instance, if dest_user_id:multiple is specified in the
 contract, and the query string is
         
@@ -157,8 +161,8 @@
 You can provide structured,
 HTML-formatted documentation for your contract.
 Note that format is derived heavily from Javadoc: a general
-description of the script's functionality, followed optionally by a
-series of named attributes tagged by at symbols (\@). You are encouraged to provide:
          
+description of the script's functionality, followed optionally
+by a series of named attributes tagged by at symbols (\@). You are encouraged to provide:
            
 
          • A description of the functionality of the page. If the
 description contains more than one sentence, the first sentence
 should be a brief summary.
          • 
@@ -168,10 +172,10 @@
 \@param parameter-namedescription...
 
        
 
      • An \@author tag for each
-author. Specify the author's name, followed his or her email
+author. Specify the author's name, followed his or her email
 address in parentheses.
      • A \@creation-date tag
 indicating when the script was first created.
      • A \@cvs-id tag containing the
-page's CVS identification string. Just use $‌Id: tcl-documentation.html,v 1.2 2000/09/19
+page's CVS identification string. Just use $‌Id: tcl-documentation.html,v 1.2 2000/09/19
 07:22:35 ron Exp $ when creating the file, and CVS will
 substitute an appropriate string when you check the file in.
        • 
 
      These \@ tags are optional,
@@ -191,9 +195,9 @@
 #
 # jsalz\@mit.edu, 7 Jun 2000
 #
-# $‌Id: tcl-doc.xml,v 1.7 2006/07/17 05:38:38 torbenb Exp $
+# $‌Id: tcl-doc.html,v 1.49.2.10 2016/06/21 07:44:36 gustafn Exp $
 
-
    you'll now write:
    +
    you'll now write:
     
 # /packages/acs-kernel/00-proc-procs.tcl
 ad_library {
@@ -203,23 +207,23 @@
 
     \@creation-date 7 Jun 2000
     \@author Jon Salz (jsalz\@mit.edu)
-    \@cvs-id $‌Id$
+    \@cvs-id $‌Id: tcl-doc.html,v 1.49.2.10 2016/06/21 07:44:36 gustafn Exp $
 
 }
 
 
    Note that format is derived heavily from Javadoc: a general
-description of the script's functionality, followed optionally by a
-series of named attributes tagged by at symbols (\@). HTML formatting is allowed. You are
+description of the script's functionality, followed optionally
+by a series of named attributes tagged by at symbols (\@). HTML formatting is allowed. You are
 encouraged to provide:
      
 
    • An \@author tag for each
-author. Specify the author's name, followed his or her email
+author. Specify the author's name, followed his or her email
 address in parentheses.
    • A \@creation-date tag
 indicating when the script was first created.
    • A \@cvs-id tag containing the
-page's CVS identification string. Just use $‌Id: tcl-documentation.html,v 1.2 2000/09/19
+page's CVS identification string. Just use $‌Id: tcl-documentation.html,v 1.2 2000/09/19
 07:22:35 ron Exp $ when creating the file, and CVS will
 substitute an appropriate string when you check the file in.
      • 
-
    ($‌Id: tcl-doc.xml,v 1.7 2006/07/17 05:38:38
-torbenb Exp $)
    
+
    ($‌Id: tcl-doc.html,v 1.49.2.10 2016/06/21
+07:44:36 gustafn Exp $)
    
 
 
 path from server home/filename
 #
-# Brief description of the file's purpose
+# Brief description of the file's purpose
 #
-# author's email address, file creation date
+# author's email address, file creation date
 #
 # $Id$
 #
 
    
 In addition, the inputs expected by a Tcl page (i.e., form variables) would
 be enumerated in a call to ad_page_variables, in effect,
-documenting the page's argument list. 
+documenting the page's argument list. 
 
    The problem with these practices is that the documentation is only
 accessible by reading the source file itself. For this reason, ACS 3.4
 introduces a new API for documenting Tcl files and, on top of that, a
@@ -36,17 +36,17 @@
 sites' UIs, e.g., what properties are available in templates.
  • Allows the request processor to be intelligent: a script can specify in
 its contract which type of abstract document it
 returns, and the request processor can transform it automatically into
-something useful to a particular user agent. (Don't worry about this for
-now - it's not complete for ACS 3.4.)
    • ad_page_contract
    
+something useful to a particular user agent. (Don't worry about this for
+now - it's not complete for ACS 3.4.)
    ad_page_contract
    
 Currently ad_page_contract serves mostly as a replacement for
 ad_page_variables. Eventually, it will be integrated closely
-with the documents API so that each script's contract will document
+with the documents API so that each script's contract will document
 precisely the set of properties available to graphical designers in
-templates. (Document API integration is subject to change, so we don't
+templates. (Document API integration is subject to change, so we don't
 decsribe it here yet; for now, you can just consider
 ad_page_contract a newer, better, documented
 ad_page_variables.) 
-
    Let's look at an example usage of ad_page_contract:
    +
    Let's look at an example usage of ad_page_contract:
     
 # /packages/acs-kernel/api-doc/www/package-view.tcl
 ad_page_contract {
@@ -72,7 +72,7 @@
 
    
 Note that: 
 
    • By convention, ad_page_contract should be preceded
-by a comment line containing the file's path. The comment is on
+by a comment line containing the file's path. The comment is on
 line 1, and the contract starts on line 2.
 
    • ad_page_contract's first argument is
 the list of expected arguments from the HTTP query (version_id,
@@ -85,9 +85,9 @@
 
 
    • Arguments can have flags, specified by following the
 name of the query argument with a colon and one or more of the following
-strings (separated by commas): 
      • optional: the query argument doesn't
-need to be provided; if it's not, the variable for that argument simply
-won't be set. For instance, if I call the script above without a
+strings (separated by commas): 
        • optional: the query argument doesn't
+need to be provided; if it's not, the variable for that argument simply
+won't be set. For instance, if I call the script above without a
 public_p in the query, then in the page body [info exists
 public_p] will return 0.
 
        • integer: the argument must be an integer
@@ -104,7 +104,7 @@
 
 
        • multiple: the argument may be specified
 arbitrarily many times in the query string, and the variable will be set to a
-list of all those values (or an empty list if it's unspecified). This is
+list of all those values (or an empty list if it's unspecified). This is
 analogous to the -multiple-list flag to
 ad_page_variables, and is useful for handling form input
 generated by <SELECT MULTIPLE> tags and checkboxes. 
          For instance, if dest_user_id:multiple is specified in the
@@ -128,7 +128,7 @@
 
    
 then $dest_user_id is set to [list 913 891 9].
  • You can provide structured, HTML-formatted documentation for your
 contract. Note that format is derived heavily from Javadoc: a
-general description of the script's functionality, followed optionally by
+general description of the script's functionality, followed optionally by
 a series of named attributes tagged by at symbols (@). You are
 encouraged to provide: 
 
    • A description of the functionality of the page. If the description
@@ -141,8 +141,8 @@
 @param parameter-name description...
 
 
    • An @author tag for each author. Specify the
-author's name, followed his or her email address in parentheses.
    • A @creation-date tag indicating when the
-script was first created.
    • A @cvs-id tag containing the page's CVS
+author's name, followed his or her email address in parentheses.
    • A @creation-date tag indicating when the
+script was first created.
    • A @cvs-id tag containing the page's CVS
 identification string. Just use $Id: tcl-documentation.html,v 1.2
 2000/09/19 07:22:35 ron Exp $ when creating the file, and CVS will
 substitute an appropriate string when you check the file in.
    
@@ -160,7 +160,7 @@
 # $Id$
 
 
    
-you'll now write: 
+you'll now write: 
 
     
 # /packages/acs-kernel/00-proc-procs.tcl
@@ -177,12 +177,12 @@
 
 
    
 Note that format is derived heavily from Javadoc: a general description of
-the script's functionality, followed optionally by a series of named
+the script's functionality, followed optionally by a series of named
 attributes tagged by at symbols (@). HTML formatting is allowed.
 You are encouraged to provide: 
 
    • An @author tag for each author. Specify the
-author's name, followed his or her email address in parentheses.
    • A @creation-date tag indicating when the
-script was first created.
    • A @cvs-id tag containing the page's CVS
+author's name, followed his or her email address in parentheses.
    • A @creation-date tag indicating when the
+script was first created.
    • A @cvs-id tag containing the page's CVS
 identification string. Just use $Id: tcl-documentation.html,v 1.2
 2000/09/19 07:22:35 ron Exp $ when creating the file, and CVS will
 substitute an appropriate string when you check the file in.
    ($Id$)
    Prev Home Next
    Request Processor Design Up Bootstrapping OpenACS
    docs@openacs.org
    View comments on this page at openacs.org
    
Index: openacs-4/packages/acs-core-docs/www/templates.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/templates.adp,v
diff -u -N -r1.1.2.3 -r1.1.2.4
--- openacs-4/packages/acs-core-docs/www/templates.adp	28 Sep 2015 07:54:25 -0000	1.1.2.3
+++ openacs-4/packages/acs-core-docs/www/templates.adp	23 Jun 2016 08:32:46 -0000	1.1.2.4
@@ -19,8 +19,8 @@
 of the logic related to manipulating the database and other
 application state data in one place, and all the logic related to
 displaying the state of the application in another place. This
-gives developer's quicker customization and easier upgrades, and
-also allows developers and graphic designers to work more
+gives developer's quicker customization and easier upgrades,
+and also allows developers and graphic designers to work more
 independently.
    In ATS, you write two files for every user-visible page in the
 system. One is a plain .tcl
 file and the other is a special .adp file. The .tcl file runs a script that sets up a set
@@ -33,20 +33,21 @@
 template related tags, and data source substitutions.
    In the overall context of our example OpenACS Notes application,
 this document will show you how to set up a simple templated page
 that displays a form to the user for entering new notes into the
-system. In later sections of the DG, we'll discuss how to develop
-the pages that actually add notes to the database, how to provide a
-separate instance of the Notes application to every user and how to
-design appropriate access control policies for the system.
    
+system. In later sections of the DG, we'll discuss how to
+develop the pages that actually add notes to the database, how to
+provide a separate instance of the Notes application to every user
+and how to design appropriate access control policies for the
+system.
    
 
    
 
    
 Entering Notes
    In order for the Notes application to be useful, we have to
 allow users to enter data into the database. Typically, this takes
 two pages: one that displays a form for data entry, and another
 page that runs the code to update the database and tells the user
 whether the operation failed. In this document, we will use the
-template system to build the first of these pages. This isn't a
-very interesting use of the system since we won't be displaying
-much data, but we'll cover more on that end later.
    The .tcl file for the form
+template system to build the first of these pages. This isn't a
+very interesting use of the system since we won't be displaying
+much data, but we'll cover more on that end later.
    The .tcl file for the form
 entry template is pretty simple. Here, the only thing we need from
 the database is a new ID for the note object to be inserted. Open
 up a file called note-add.tcl
@@ -85,17 +86,17 @@
 
 
    Some things to note about this code:
      
 
    • The procedure ad_page_contract is always the first thing a
-.tcl file calls, if it's under
-the www/ directory (i.e. not a Tcl library file). It does
+.tcl file calls, if it's
+under the www/ directory (i.e. not a Tcl library file). It does
 validation of input values from the HTTP request (i.e. form
 variables) and in this case, the -properties clause is used to set up the
 data sources that we will ship over to the .adp part of the page. In this case, we
 only use the simplest possible kind of data source, called a
 onevalue, which hold just a
-single string value. Later on, we'll see how to use more powerful
-kinds of data sources for representing multiple rows from an SQL
-query. You also include overall documentation for the page in the
-contract, and OpenACS has automatic tools that extract this
+single string value. Later on, we'll see how to use more
+powerful kinds of data sources for representing multiple rows from
+an SQL query. You also include overall documentation for the page
+in the contract, and OpenACS has automatic tools that extract this
 documentation and make it browsable.
    • After being declared in the ad_page_contract, each property is just a
 simple Tcl variable. The template system passes the final value of
 the variable to the .adp
@@ -131,11 +132,11 @@
 
 
      The main point to note here is: when you want to substitute a
 value into a page, you put the name of the data source between two
-"\@" characters. Another point to note is the use of a master
-template: Master templates allow you do centralize display code
-that is used throughout an application in a single file. In this
-case, we intend to have a master template that does the standard
-page headers and footers for us
      After putting all these files into ROOT/packages/notes/www, you should be able
+"\@" characters. Another point to note is the use of a
+master template: Master templates allow you do centralize display
+code that is used throughout an application in a single file. In
+this case, we intend to have a master template that does the
+standard page headers and footers for us
      After putting all these files into ROOT/packages/notes/www, you should be able
 to go to /notes/ URL for your
 server and see the input form.
      
 
    
@@ -147,13 +148,13 @@
 display part of the page. The display part of the page is an
 .adp file with some special
 tags and notations for dealing with display logic and inserting
-properties into the text of the page. Later on we'll get into
+properties into the text of the page. Later on we'll get into
 templates more deeply, and show how to use database queries as data
 sources.
    
 
    
 
    
-Documentation
    Templating system documentation
    ($‌Id: templates.xml,v 1.12 2015/07/02 20:03:56
-gustafn Exp $)
    
+Documentation
    Templating system documentation
    ($‌Id: templates.html,v 1.49.2.10 2016/06/21
+07:44:36 gustafn Exp $)
    
 
 
 . The intent is to have all of the logic related to
 manipulating the database and other application state data in one
 place, and all the logic related to displaying the state of the
-application in another place.  This gives developer's quicker
+application in another place.  This gives developer's quicker
 customization and easier upgrades, and also allows developers and
 graphic designers to work more independently.
 
    
@@ -25,7 +25,7 @@
 In the overall context of our example OpenACS Notes application, this
 document will show you how to set up a simple templated page that
 displays a form to the user for entering new notes into the system. In
-later sections of the DG, we'll discuss how to develop the pages that
+later sections of the DG, we'll discuss how to develop the pages that
 actually add notes to the database, how to provide a separate instance
 of the Notes application to every user and how to design appropriate
 access control policies for the system.
@@ -35,8 +35,8 @@
 pages: one that displays a form for data entry, and another page that
 runs the code to update the database and tells the user whether the
 operation failed. In this document, we will use the template system to
-build the first of these pages. This isn't a very interesting use of
-the system since we won't be displaying much data, but we'll cover
+build the first of these pages. This isn't a very interesting use of
+the system since we won't be displaying much data, but we'll cover
 more on that end later.
 
    
 The .tcl file for the form entry template is pretty
@@ -80,14 +80,14 @@
 Some things to note about this code:
 
    • 
 The procedure ad_page_contract is
-always the first thing a .tcl file calls, if it's under
+always the first thing a .tcl file calls, if it's under
 the www/ directory (i.e. not a Tcl library file). It does validation
 of input values from the HTTP request (i.e. form variables) and in
 this case, the -properties clause is used to set up the
 data sources that we will ship over to the .adp part of
 the page. In this case, we only use the simplest possible kind of data
 source, called a onevalue, which hold just a single
-string value.  Later on, we'll see how to use more powerful kinds of
+string value.  Later on, we'll see how to use more powerful kinds of
 data sources for representing multiple rows from an SQL query.  You
 also include overall documentation for the page in the contract, and
 OpenACS has automatic tools that extract this documentation and make it
@@ -149,7 +149,7 @@
 data sources that are used by the display part of the page. The
 display part of the page is an .adp file with some
 special tags and notations for dealing with display logic and
-inserting properties into the text of the page. Later on we'll get
+inserting properties into the text of the page. Later on we'll get
 into templates more deeply, and show how to use database queries as
 data sources.
 
    Documentation
    
Index: openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.adp,v
diff -u -N -r1.1.2.1 -r1.1.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.adp	23 Sep 2015 11:54:56 -0000	1.1.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.adp	23 Jun 2016 08:32:46 -0000	1.1.2.2
@@ -17,15 +17,15 @@
 checkboxes next to every item seen on a list and the Delete
 Selected button on the bottom of the list.
  • 
 
    Dedicated admin pages. If you want admins to have access to data
-that users aren't interested in or aren't allowed to see you will
-need dedicated admin pages. The conventional place to put those
-dedicated admin pages is in the /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin
+that users aren't interested in or aren't allowed to see
+you will need dedicated admin pages. The conventional place to put
+those dedicated admin pages is in the /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin
 directory.
     [$OPENACS_SERVICE_NAME www]$ mkdir admin
 
     [$OPENACS_SERVICE_NAME www]$ cd admin
-
    Even if your application doesn't need any admin pages of its own
-you will usually need at least one simple page with a bunch of
+
    Even if your application doesn't need any admin pages of its
+own you will usually need at least one simple page with a bunch of
 links to existing administration UI such as Category Management or
 standard Parameters UI. Adding the link to Category Management is
 described in the section on categories. The listing below adds a
@@ -62,13 +62,14 @@
 }]
 
 
    Now that you have the first admin page it would be nice to have
-a link to it somewhere in the system so that admins don't have to
-type in the /admin every time
-they need to reach it. You could put a static link to the toplevel
-index.adp but that might be
-distracting for people who are not admins. Besides, some people
-consider it impolite to first offer a link and then display a nasty
-"You don't have permission to access this page" message.
    In order to display the link to the admin page only to users
+a link to it somewhere in the system so that admins don't have
+to type in the /admin every
+time they need to reach it. You could put a static link to the
+toplevel index.adp but that
+might be distracting for people who are not admins. Besides, some
+people consider it impolite to first offer a link and then display
+a nasty "You don't have permission to access this
+page" message.
    In order to display the link to the admin page only to users
 that have admin privileges add the following code near the top of
 /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.tcl:
     
Index: openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html,v
diff -u -N -r1.14.2.1 -r1.14.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html	9 Jun 2016 08:44:50 -0000	1.14.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html	23 Jun 2016 08:32:46 -0000	1.14.2.2
@@ -7,13 +7,13 @@
        could provide checkboxes next to every item seen on a list and the
        Delete Selected button on the bottom of the list.
        
  • Dedicated admin pages.  If you want admins to have
-       access to data that users aren't interested in or aren't allowed
+       access to data that users aren't interested in or aren't allowed
        to see you will need dedicated admin pages.  The conventional
        place to put those dedicated admin pages is in the
  /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin
  directory.
       
    [$OPENACS_SERVICE_NAME www]$ mkdir admin
    [$OPENACS_SERVICE_NAME www]$ cd admin
    
-      Even if your application doesn't need any admin pages of its own you will
+      Even if your application doesn't need any admin pages of its own you will
       usually need at least one simple page with a bunch of links to existing
       administration UI such as Category Management or standard Parameters UI.
       Adding the link to Category Management is described in the section on
@@ -49,12 +49,12 @@
 
 
    
 Now that you have the first admin page it would be nice to have a link to it
-somewhere in the system so that admins don't have to type in the
+somewhere in the system so that admins don't have to type in the
 /admin every time they need to reach it.  You
 could put a static link to the toplevel
 index.adp but that might be distracting for
 people who are not admins.  Besides, some people consider it impolite to first
-offer a link and then display a nasty "You don't have permission to access this
+offer a link and then display a nasty "You don't have permission to access this
 page" message.
 
    
 In order to display the link to the admin page only to users that have admin
Index: openacs-4/packages/acs-core-docs/www/tutorial-advanced.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-advanced.adp,v
diff -u -N -r1.1.2.2 -r1.1.2.3
--- openacs-4/packages/acs-core-docs/www/tutorial-advanced.adp	9 Jun 2016 13:03:11 -0000	1.1.2.2
+++ openacs-4/packages/acs-core-docs/www/tutorial-advanced.adp	23 Jun 2016 08:32:46 -0000	1.1.2.3
@@ -36,8 +36,8 @@
 OpenACS docs are written by the named authors, and may be edited by
 OpenACS documentation staff.
    This tutorial covers topics which are not essential to creating
 a minimal working package. Each section can be used independently
-of all of the others; all sections assume that you've completed the
-basic tutorial.
    
+of all of the others; all sections assume that you've completed
+the basic tutorial.
    
 
 
    This tutorial covers topics which are not essential to
     creating a minimal working package.  Each section can be used
     independently of all of the others; all sections assume that
-    you've completed the basic tutorial.
    Prev Home Next
    Debugging and Automated Testing Up Write the Requirements and Design Specs
    docs@openacs.org
    View comments on this page at openacs.org
    
+    you've completed the basic tutorial.
    Prev Home Next
    Debugging and Automated Testing Up Write the Requirements and Design Specs
    docs@openacs.org
    View comments on this page at openacs.org
    
Index: openacs-4/packages/acs-core-docs/www/tutorial-caching.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-caching.adp,v
diff -u -N -r1.1.2.1 -r1.1.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-caching.adp	23 Sep 2015 11:54:56 -0000	1.1.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-caching.adp	23 Jun 2016 08:32:46 -0000	1.1.2.2
@@ -43,8 +43,9 @@
 need to be reloaded. You may wish to pre-load it, so that the
 loading delay does not impact users. If you have a sequence of
 pages, you could call the cached proc in advance, to increase the
-chances that it's loaded and current when the user reaches it. Or,
-you can call (and discard) it immediately after flushing it.
    • 
+chances that it's loaded and current when the user reaches it.
+Or, you can call (and discard) it immediately after flushing
+it.
    
 
 
 
  • In your code, always call my_proc.  There will be a seperate cache item for each unique call to my_proc_not_cached so that calls with different arguments are cached seperately. You can flush the cache for each cache key by calling util_memoize_flush my_proc_not_cached args.
  • 
           The cached material will of course become obsolete over time.  There are two ways to handle this.
    • Timed Expiration: pass in max_age to util_memoize.  If the content is older than max_age, it will be re-generated.
    • 
-              Direct Flushing.  In any proc which invalidates the cached content, call  util_memoize_flush my_proc_not_cached args.
  • If you are correctly flushing the cached value, then it will need to be reloaded.  You may wish to pre-load it, so that the loading delay does not impact users.  If you have a sequence of pages, you could call the cached proc in advance, to increase the chances that it's loaded and current when the user reaches it.  Or, you can call (and discard) it immediately after flushing it.
    • Prev Home Next
    Sending HTML email from your application Up Scheduled Procedures
    docs@openacs.org
    View comments on this page at openacs.org
    
+              Direct Flushing.  In any proc which invalidates the cached content, call  util_memoize_flush my_proc_not_cached args.
  • If you are correctly flushing the cached value, then it will need to be reloaded.  You may wish to pre-load it, so that the loading delay does not impact users.  If you have a sequence of pages, you could call the cached proc in advance, to increase the chances that it's loaded and current when the user reaches it.  Or, you can call (and discard) it immediately after flushing it.
    • Prev Home Next
    Sending HTML email from your application Up Scheduled Procedures
    docs@openacs.org
    View comments on this page at openacs.org
    
Index: openacs-4/packages/acs-core-docs/www/tutorial-categories.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-categories.adp,v
diff -u -N -r1.1.2.7 -r1.1.2.8
--- openacs-4/packages/acs-core-docs/www/tutorial-categories.adp	10 Jun 2016 07:35:08 -0000	1.1.2.7
+++ openacs-4/packages/acs-core-docs/www/tutorial-categories.adp	23 Jun 2016 08:32:46 -0000	1.1.2.8
@@ -14,15 +14,15 @@
 
    
 OpenACS docs are written by the named authors, and may be edited by
 OpenACS documentation staff.
    You can associate any ACS Object with one or more categories. In
-this tutorial we'll show how to equip your application with user
-interface to take advantage of the Categories service.
    We'll start by installing the Categories service. Go to
+this tutorial we'll show how to equip your application with
+user interface to take advantage of the Categories service.
    We'll start by installing the Categories service. Go to
 /acs/admin and install it. This
-step won't be necessary for the users of your applications because
-you'll create a dependency with the Package Manager which will take
-care that the Categories service always gets installed when your
-application gets installed.
    Now that we have installed the Categories service we can proceed
+step won't be necessary for the users of your applications
+because you'll create a dependency with the Package Manager
+which will take care that the Categories service always gets
+installed when your application gets installed.
    Now that we have installed the Categories service we can proceed
 to modifying our application so that it can take advantage of it.
-We'll do it in three steps:
      
+We'll do it in three steps:
        
 
      1. 
 
        The Categories service provides a mechanism to associate one or
 more category trees that are
@@ -50,18 +50,18 @@
 by this package_id. The
 categorization service is actually more general than that: instead
 of package_id you could use an
-ID of some other object that serves as a "container" in your
-application. For example, if your discussion forums application
-supports multiple forums you would use forum_id to associate category trees with
+ID of some other object that serves as a "container" in
+your application. For example, if your discussion forums
+application supports multiple forums you would use forum_id to associate category trees with
 just that one forum rather than the entire application
 instance.
        
 
      2. 
 
        Once the category trees have been selected users need a way to
 categorize items. The easiest way to do this is by adding the
 category widget type of the
 form builder to note-edit.tcl.
-To achieve this we'll need to use the -extend switch to the ad_form command. Here's the "meat" of the
-note-edit.tcl page:
        +To achieve this we'll need to use the -extend switch to the ad_form command. Here's the
+"meat" of the note-edit.tcl page:
                                 # extend the form to support categories
                         set package_id [ad_conn package_id]
                             
@@ -100,7 +100,7 @@
 create a form to allow the user to confirm the deletion. Note that
 in entry-edit.tcl we used
 ad_form to access the Form
-Template commands; here, we call them directly because we don't
+Template commands; here, we call them directly because we don't
 need the extra features of ad_form. The form calls itself, but with
 hidden variables carrying both note_id and confirm_p. If confirm_p is present, we
 delete the record, set redirection back to the index, and abort
@@ -137,8 +137,8 @@
 
        We will now make categories optional on package instance level
 and also add a configuration page to allow the package admin to
 enable/disable categories for his package.
        Go to the APM and create a number parameter with the name
-"EnableCategoriesP" and the
-default value "0".
        Add the following lines to your index.tcl:
        +"EnableCategoriesP"
+and the default value "0".
        Add the following lines to your index.tcl:
                   set return_url [ns_conn url]
           set use_categories_p [parameter::get -parameter "EnableCategoriesP"]
           
@@ -247,7 +247,7 @@
                         set category_name [category::get_name $category_id]
                         if { $category_name eq "" } {
                         ad_return_exception_page 404 "No such category" "Site-wide \
-                                Category with ID $category_id doesn't exist"
+                                Category with ID $category_id doesn't exist"
                         return
                         }
                         # Show Category in context bar
Index: openacs-4/packages/acs-core-docs/www/tutorial-categories.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-categories.html,v
diff -u -N -r1.14.2.5 -r1.14.2.6
--- openacs-4/packages/acs-core-docs/www/tutorial-categories.html	10 Jun 2016 07:35:08 -0000	1.14.2.5
+++ openacs-4/packages/acs-core-docs/www/tutorial-categories.html	23 Jun 2016 08:32:46 -0000	1.14.2.6
@@ -3,18 +3,18 @@
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
      You can associate any ACS Object with one or more categories.
-    In this tutorial we'll show how to equip your application with user
+    In this tutorial we'll show how to equip your application with user
     interface to take advantage of the Categories service.
     
      
-    We'll start by installing the Categories service.  Go to
+    We'll start by installing the Categories service.  Go to
     /acs/admin and install it.  This step
-    won't be necessary for the users of your applications because you'll create
+    won't be necessary for the users of your applications because you'll create
     a dependency with the Package Manager which will take care that the
     Categories service always gets installed when your application gets
     installed.
     
      
     Now that we have installed the Categories service we can proceed to
-    modifying our application so that it can take advantage of it.  We'll do it
+    modifying our application so that it can take advantage of it.  We'll do it
     in three steps:
     
      1. 
           The Categories service provides a mechanism to associate one or
@@ -59,8 +59,8 @@
           to categorize items.  The easiest way to do this is by adding the
           category widget type of the
           form builder to note-edit.tcl.
-          To achieve this we'll need to use the -extend
-          switch to the ad_form command. Here's the "meat" of the
+          To achieve this we'll need to use the -extend
+          switch to the ad_form command. Here's the "meat" of the
           note-edit.tcl page:
         			# extend the form to support categories
 			set package_id [ad_conn package_id]
@@ -95,7 +95,7 @@
 should initially be absert.  If it is absent, we create a form to
 allow the user to confirm the deletion.  Note that in
 entry-edit.tcl we used ad_form to access the Form Template
-commands; here, we call them directly because we don't need the extra
+commands; here, we call them directly because we don't need the extra
 features of ad_form.  The form calls itself, but
 with hidden variables carrying both
 note_id and
@@ -226,7 +226,7 @@
         		set category_name [category::get_name $category_id]
         		if { $category_name eq "" } {
             		ad_return_exception_page 404 "No such category" "Site-wide \
-          			Category with ID $category_id doesn't exist"
+          			Category with ID $category_id doesn't exist"
             		return
         		}
         		# Show Category in context bar
Index: openacs-4/packages/acs-core-docs/www/tutorial-comments.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-comments.adp,v
diff -u -N -r1.1.2.1 -r1.1.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-comments.adp	23 Sep 2015 11:54:57 -0000	1.1.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-comments.adp	23 Jun 2016 08:32:46 -0000	1.1.2.2
@@ -9,7 +9,7 @@
 		    rightLink="tutorial-admin-pages" rightLabel="Next">
 		
        
 
        
-Adding Comments
        You can track comments for any ACS Object. Here we'll track
+Adding Comments
    You can track comments for any ACS Object. Here we'll track
 comments for notes. On the note-edit.tcl/adp pair, which is used to
 display individual notes, we want to put a link to add comments at
 the bottom of the screen. If there are any comments, we want to
Index: openacs-4/packages/acs-core-docs/www/tutorial-comments.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-comments.html,v
diff -u -N -r1.15.2.1 -r1.15.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-comments.html	9 Jun 2016 08:44:50 -0000	1.15.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-comments.html	23 Jun 2016 08:32:46 -0000	1.15.2.2
@@ -1,5 +1,5 @@
 
-Adding Comments
    Alex logo
    Prev Chapter 10. Advanced Topics Next
    Adding Comments
    You can track comments for any ACS Object.  Here we'll track
+Adding Comments
    Alex logo
    Prev Chapter 10. Advanced Topics Next
    Adding Comments
    You can track comments for any ACS Object.  Here we'll track
      comments for notes.  On the note-edit.tcl/adp pair, which is used to
      display individual notes, we want to put a link to add comments at
      the bottom of the screen.  If there are any comments, we want to
Index: openacs-4/packages/acs-core-docs/www/tutorial-css-layout.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-css-layout.adp,v
diff -u -N -r1.1.2.10 -r1.1.2.11
--- openacs-4/packages/acs-core-docs/www/tutorial-css-layout.adp	21 Jun 2016 07:44:36 -0000	1.1.2.10
+++ openacs-4/packages/acs-core-docs/www/tutorial-css-layout.adp	23 Jun 2016 08:32:46 -0000	1.1.2.11
@@ -12,7 +12,7 @@
 Laying out a page with CSS instead of
 tables
    
 
    
-.LRN home page with table-based
+.LRN home page with table-based
 layout
    A sample of the HTML code (full source)
     <table border="0" width="100%">
   <tr>
@@ -40,7 +40,7 @@
 
    
 
    
 
    
-.LRN Home with CSS-based layout
    A sample of the HTML code (full source)
    +.LRN Home with CSS-based layout
    A sample of the HTML code (full source)
     <div class="left">
   <div class="portlet-wrap-shadow">
     <div class="portlet-wrap-bl">
Index: openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html,v
diff -u -N -r1.12.2.10 -r1.12.2.11
--- openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html	21 Jun 2016 07:44:36 -0000	1.12.2.10
+++ openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html	23 Jun 2016 08:32:46 -0000	1.12.2.11
@@ -1,5 +1,5 @@
 
-Laying out a page with CSS instead of tables
    Alex logo
    Prev Chapter 10. Advanced Topics Next
    Laying out a page with CSS instead of tables
    .LRN home page with table-based layout
    A sample of the HTML code (full source)
    <table border="0" width="100%">
+Laying out a page with CSS instead of tables
    Alex logo
    Prev Chapter 10. Advanced Topics Next
    Laying out a page with CSS instead of tables
    .LRN home page with table-based layout
    A sample of the HTML code (full source)
    <table border="0" width="100%">
   <tr>
     <td valign="top" width="50%">
       <table class="element" border=0 cellpadding="0" cellspacing="0" width="100%">
@@ -21,7 +21,7 @@
                   <table border="0" bgcolor="white" cellpadding="0" cellspacing="0" width="100%">
                     <tr>
                       <td class=element-text>
-                        MBA 101
    .LRN Home with CSS-based layout
    A sample of the HTML code (full source)
    <div class="left">
+                        MBA 101
    .LRN Home with CSS-based layout
    A sample of the HTML code (full source)
    <div class="left">
   <div class="portlet-wrap-shadow">
     <div class="portlet-wrap-bl">
       <div class="portlet-wrap-tr">
Index: openacs-4/packages/acs-core-docs/www/tutorial-cvs.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-cvs.adp,v
diff -u -N -r1.1.2.10 -r1.1.2.11
--- openacs-4/packages/acs-core-docs/www/tutorial-cvs.adp	21 Jun 2016 07:44:36 -0000	1.1.2.10
+++ openacs-4/packages/acs-core-docs/www/tutorial-cvs.adp	23 Jun 2016 08:32:46 -0000	1.1.2.11
@@ -10,9 +10,9 @@
 		
    
 
    
 Add the new package to CVS
    Before you do any more work, make sure that your work is
-protected by putting it all into cvs. The cvs add command is not recursive, so you'll
-have to traverse the directory tree manually and add as you go.
-(More on CVS)
    +protected by putting it all into cvs. The cvs add command is not recursive, so
+you'll have to traverse the directory tree manually and add as
+you go. (More on CVS)
     [$OPENACS_SERVICE_NAME xml]$ cd ..
 [$OPENACS_SERVICE_NAME doc]$ cd ..
 [$OPENACS_SERVICE_NAME www]$ cd ..
@@ -71,8 +71,8 @@
 (many lines omitted)
 [$OPENACS_SERVICE_NAME myfirstpackage]$
 
    
-
    Figure 10.1. Upgrading
-a local CVS repository
    Upgrading a local CVS repository
    
+
    Figure 10.1. Upgrading a local CVS
+repository
    Upgrading a local CVS repository
    
 

    
 
    
 
 Add the new package to CVS
    Alex logo
    Prev Chapter 10. Advanced Topics Next
    Add the new package to CVS
    Before you do any more work, make sure that your work is
       protected by putting it all into cvs.  The cvs
-      add command is not recursive, so you'll have to
+      add command is not recursive, so you'll have to
       traverse the directory tree manually and add as you go.  (More on
       CVS)
    [$OPENACS_SERVICE_NAME xml]$ cd ..
 [$OPENACS_SERVICE_NAME doc]$ cd ..
Index: openacs-4/packages/acs-core-docs/www/tutorial-database.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-database.adp,v
diff -u -N -r1.1.2.11 -r1.1.2.12
--- openacs-4/packages/acs-core-docs/www/tutorial-database.adp	21 Jun 2016 07:44:36 -0000	1.1.2.11
+++ openacs-4/packages/acs-core-docs/www/tutorial-database.adp	23 Jun 2016 08:32:46 -0000	1.1.2.12
@@ -42,11 +42,12 @@
 simplify our database creation. (More information about ACS
 Objects. More information about the Content
 Repository.)
    
-
    Figure 9.2. Tutorial
-Data Model
    Tutorial Data Model
    
+
    Figure 9.2. Tutorial Data
+Model
    Tutorial Data Model
    
 

    The top of each sql file has some standard comments, including
 doc tags such as \@author which
-will be picked up by the API browser. The string $‌Id:$ will automatically be expanded when
+will be picked up by the API browser. The string $‌Id: tutorial-database.html,v 1.44.2.10 2016/06/21
+07:44:36 gustafn Exp $ will automatically be expanded when
 the file is checked in to cvs.
     [$OPENACS_SERVICE_NAME ~]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/sql/postgresql
 [$OPENACS_SERVICE_NAME postgresql]$ emacs myfirstpackage-create.sql
@@ -75,14 +76,14 @@
 

    The creation script calls a function in PL/pgSQL (PL/pgSQL is a
 procedural language extention to sql), content_type__create_type, which in turn
 creates the necessary database changes to support our data object.
-Notice the use of "mfp." This is derived from "My First Package"
-and ensures that our object is unlikely to conflict with objects
-from other packages.
    Create a database file to drop everything if the package is
+Notice the use of "mfp." This is derived from "My
+First Package" and ensures that our object is unlikely to
+conflict with objects from other packages.
    Create a database file to drop everything if the package is
 uninstalled.
     [$OPENACS_SERVICE_NAME postgresql]$ emacs myfirstpackage-drop.sql
 
    
-
    Figure 9.4. Database
-Deletion Script
    +
    Figure 9.4. Database Deletion
+Script
     -- drop script
 --
 -- \@author joel\@aufrecht.org
@@ -113,7 +114,7 @@
 again. If there are errors in the database table creation, you may
 need to run the drop script to drop the table so that you can
 recreate it. The drop script will probably have errors since some
-of the things it's trying to drop may be missing. They can be
+of the things it's trying to drop may be missing. They can be
 ignored.
    Once you get the same output as shown above, test the drop
 script:
     [$OPENACS_SERVICE_NAME postgresql]$ psql service0 -f myfirstpackage-drop.sql
Index: openacs-4/packages/acs-core-docs/www/tutorial-database.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-database.html,v
diff -u -N -r1.44.2.10 -r1.44.2.11
--- openacs-4/packages/acs-core-docs/www/tutorial-database.html	21 Jun 2016 07:44:36 -0000	1.44.2.10
+++ openacs-4/packages/acs-core-docs/www/tutorial-database.html	23 Jun 2016 08:32:46 -0000	1.44.2.11
@@ -82,7 +82,7 @@
                          0
 (1 row)
 
-[$OPENACS_SERVICE_NAME postgresql]$
    If there are errors, use them to debug the sql file and try again.  If there are errors in the database table creation, you may need to run the drop script to drop the table so that you can recreate it.  The drop script will probably have errors since some of the things it's trying to drop may be missing.  They can be ignored.
    Once you get the same output as shown above, test the drop script:
    [$OPENACS_SERVICE_NAME postgresql]$ psql service0 -f myfirstpackage-drop.sql
+[$OPENACS_SERVICE_NAME postgresql]$
    If there are errors, use them to debug the sql file and try again.  If there are errors in the database table creation, you may need to run the drop script to drop the table so that you can recreate it.  The drop script will probably have errors since some of the things it's trying to drop may be missing.  They can be ignored.
    Once you get the same output as shown above, test the drop script:
    [$OPENACS_SERVICE_NAME postgresql]$ psql service0 -f myfirstpackage-drop.sql
 
  content_type__drop_type
 -------------------------
Index: openacs-4/packages/acs-core-docs/www/tutorial-debug.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-debug.adp,v
diff -u -N -r1.1.2.11 -r1.1.2.12
--- openacs-4/packages/acs-core-docs/www/tutorial-debug.adp	21 Jun 2016 07:44:36 -0000	1.1.2.11
+++ openacs-4/packages/acs-core-docs/www/tutorial-debug.adp	23 Jun 2016 08:32:46 -0000	1.1.2.12
@@ -16,19 +16,20 @@
 OpenACS documentation staff.
    
 
    
 Debugging
    
-Developer Support. The Developer Support
-package adds several goodies: debug information for every page; the
-ability to log comments to the page instead of the error log, and
-fast user switching so that you can test pages as anonymous and as
-dummy users without logging in and out.
    
-PostgreSQL. You can work directly with the
-database to do debugging steps like looking directly at tables and
-testing stored procedures. Start emacs. Type M-x sql-postgres. Press enter for
-server name and use $OPENACS_SERVICE_NAME
+Developer Support. The Developer
+Support package adds several goodies: debug information for every
+page; the ability to log comments to the page instead of the error
+log, and fast user switching so that you can test pages as
+anonymous and as dummy users without logging in and out.
    
+PostgreSQL. You can work directly
+with the database to do debugging steps like looking directly at
+tables and testing stored procedures. Start emacs. Type
+M-x sql-postgres.
+Press enter for server name and use $OPENACS_SERVICE_NAME
 for database name. You can use C-(up arrow) and C-(down arrow) for
-command history.
    Hint: "Parse error near *" usually means that an xql file wasn't
-recognized, because the tcl file is choking on the *SQL*
-placeholder that it falls back on.
    Watching the server log. 
    To set up real-time monitoring of the AOLserver error log,
+command history.
    Hint: "Parse error near *" usually means that an xql
+file wasn't recognized, because the tcl file is choking on the
+*SQL* placeholder that it falls back on.
    Watching the server log. 
    To set up real-time monitoring of the AOLserver error log,
 type
 
     less /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/openacs-dev-error.log
@@ -68,8 +69,8 @@
 mfp::note::delete.Proc should return 0 for success.
 
 
-
    Other things to test: try to delete someone else's note. Try to
-delete your own note. Edit your own note. Search for a note.
    
+
    Other things to test: try to delete someone else's note. Try
+to delete your own note. Edit your own note. Search for a note.
    
 
    
 
    
 Write automated tests
    
@@ -79,7 +80,7 @@
  It seems to me that a lot of people have
 been asking for some guidelines on how to write automated tests.
 I've done several tests by now and have found the process to be
-extremely easy and useful. It's a joy to work with automated
+extremely easy and useful. It's a joy to work with automated
 testing once you get the hang of it.
    Create the directory that will contain the test script and edit
 the script file. The directory location and file name are standards
 which are recognized by the automated testing package:
    @@ -92,23 +93,24 @@
     ...
 }
 
    To create a test case you call 
-aa_register_case test_case_name.. Once you've
-created the test case you start writing the needed logic. We'll use
-the tutorial package, "myfirstpackage," as an example. Let's say
-you just wrote an API for adding and deleting notes in the notes packages
-and wanted to test that. You'd probably want to write a test that
-first creates a note, then verifies that it was inserted, then
-perhaps deletes it again, and finally verifies that it is gone.
    Naturally this means you'll be adding a lot of bogus data to the
-database, which you're not really interested in having there. To
-avoid this I usually do two things. I always put all my test code
-inside a call to aa_run_with_teardown which basically means that
-all the inserts, deletes, and updates will be rolled back once the
-test has been executed. A very useful feature. Instead of inserting
-bogus data like: set name
-"Simon", I tend to generate a random script in order avoid
-inserting a value that's already in the database:
    +aa_register_case test_case_name.. Once you've
+created the test case you start writing the needed logic. We'll
+use the tutorial package, "myfirstpackage," as an
+example. Let's say you just wrote an API for adding and deleting notes in
+the notes packages and wanted to test that. You'd probably want
+to write a test that first creates a note, then verifies that it
+was inserted, then perhaps deletes it again, and finally verifies
+that it is gone.
    Naturally this means you'll be adding a lot of bogus data to
+the database, which you're not really interested in having
+there. To avoid this I usually do two things. I always put all my
+test code inside a call to aa_run_with_teardown which basically
+means that all the inserts, deletes, and updates will be rolled
+back once the test has been executed. A very useful feature.
+Instead of inserting bogus data like: set name "Simon", I tend to
+generate a random script in order avoid inserting a value
+that's already in the database:
     set name [ad_generate_random_string]
-
    Here's how the test case looks so far:
    +
    Here's how the test case looks so far:
     aa_register_case mfp_basic_test {
     My test
 } {
@@ -118,39 +120,42 @@
 
        }
 }
-
    Now let's look at the actual test code. That's the code that
-goes inside -test_code {}. We
-want to implement test case API-001, "Given an object id from
-API-001, invoke mfp::note::get. Proc should return the specific
-word in the title."
    +
    Now let's look at the actual test code. That's the code
+that goes inside -test_code {}.
+We want to implement test case API-001, "Given an object id
+from API-001, invoke mfp::note::get. Proc should return the
+specific word in the title."
           set name [ad_generate_random_string]
       set new_id [mfp::note::add -title $name]
       aa_true "Note add succeeded" ([info exists new_id] && $new_id ne "")
 
    To test our simple case, we must load the test file into the
 system (just as with the /tcl file in the basic tutorial, since the
-file didn't exist when the system started, the system doesn't know
-about it.) To make this file take effect, go to the APM and choose
-"Reload changed" for "MyFirstPackage". Since we'll be changing it
-frequently, select "watch this file" on the next page. This will
-cause the system to check this file every time any page is
-requested, which is bad for production systems but convenient for
-developing. We can also add some aa_register_case flags to make it
-easier to run the test. The -procs flag, which indicates which procs
+file didn't exist when the system started, the system
+doesn't know about it.) To make this file take effect, go to
+the APM
+and choose "Reload changed" for
+"MyFirstPackage". Since we'll be changing it
+frequently, select "watch this file" on the next page.
+This will cause the system to check this file every time any page
+is requested, which is bad for production systems but convenient
+for developing. We can also add some aa_register_case flags to make
+it easier to run the test. The -procs flag, which indicates which procs
 are tested by this test case, makes it easier to find procs in your
-package that aren't tested at all. The -cats flag, setting categories, makes it
+package that aren't tested at all. The -cats flag, setting categories, makes it
 easier to control which tests to run. The smoke test setting means that this is a
 basic test case that can and should be run any time you are doing
 any test. (a definition of "smoke test")
    Once the file is loaded, go to ACS Automated Testing and click on
 myfirstpackage. You should see your test case. Run it and examine
 the results.
    
 
    
-TCLWebtest tests
    API testing can only test part of our package - it doesn't test
-the code in our adp/tcl pairs. For this, we can use TCLwebtest.
-TCLwebtest must be installed for this test to work.
-This provides a library of functions that make it easy to call a page
-through HTTP, examine the results, and drive forms. TCLwebtest's
-functions overlap slightly with acs-automated-testing; see the
-example provided for one approach on integrating them.
    
+TCLWebtest tests
    API testing can only test part of our package - it doesn't
+test the code in our adp/tcl pairs. For this, we can use
+TCLwebtest. TCLwebtest must be installed
+for this test to work. This provides a library of functions that make it easy to call a page
+through HTTP, examine the results, and drive forms.
+TCLwebtest's functions overlap slightly with
+acs-automated-testing; see the example provided for one approach on
+integrating them.
    
 
    
 
    
 Example
    Now we can add the rest of the API tests, including a test with
@@ -218,15 +223,15 @@
         
         \@author Peter Marklund
     } {
-        # we need to get a user_id here so that it's available throughout
+        # we need to get a user_id here so that it's available throughout
         # this proc
         set user_id [db_nextval acs_object_id_seq]
 
         set note_title [ad_generate_random_string]
 
         # NOTE: Never use the aa_run_with_teardown with the rollback switch
         # when running Tclwebtest tests since this will put the test code in
-        # a transaction and changes won't be visible across HTTP requests.
+        # a transaction and changes won't be visible across HTTP requests.
         
         aa_run_with_teardown -test_code {
             
@@ -276,7 +281,7 @@
             # 1) go directly to the database to get the id
             # 2) require an API function that takes name and returns ID
             # 3) screen-scrape for the ID
-            # all options are problematic.  We'll do #1 in this example:
+            # all options are problematic.  We'll do #1 in this example:
 
             set note_id [db_string get_note_id_from_name " 
                 select item_id 
Index: openacs-4/packages/acs-core-docs/www/tutorial-debug.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-debug.html,v
diff -u -N -r1.43.2.10 -r1.43.2.11
--- openacs-4/packages/acs-core-docs/www/tutorial-debug.html	21 Jun 2016 07:44:36 -0000	1.43.2.10
+++ openacs-4/packages/acs-core-docs/www/tutorial-debug.html	23 Jun 2016 08:32:46 -0000	1.43.2.11
@@ -14,7 +14,7 @@
             database name.  You can use C-(up arrow) and C-(down arrow)
             for command history.
 
    Hint: "Parse error near *" usually means that an xql file
-      wasn't recognized, because the tcl file is choking on the *SQL*
+      wasn't recognized, because the tcl file is choking on the *SQL*
       placeholder that it falls back on.
    Watching the server log. 
    To set up real-time monitoring of the AOLserver error
           log, type 
    less /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/openacs-dev-error.log
    
           
    F to show new log entries in real time (like tail -f)
    
@@ -27,35 +27,35 @@
             while one or more notes exist.No edit or delete or add links should appear.002Browse to the index page while logged in.  An Edit
             link should appear.  Click on it.  Fill out the form and
             click Submit.The text added in the form should be visible on the
-            index page.API-001Invoke mfp::note::create with a specific word as the title.Proc should return an object id.API-002Given an object id from API-001, invoke mfp::note::get.Proc should return the specific word in the title.API-003Given the object id from API-001, invoke mfp::note::delete.Proc should return 0 for success.
    Other things to test: try to delete someone else's
+            index page.API-001Invoke mfp::note::create with a specific word as the title.Proc should return an object id.API-002Given an object id from API-001, invoke mfp::note::get.Proc should return the specific word in the title.API-003Given the object id from API-001, invoke mfp::note::delete.Proc should return 0 for success.
    Other things to test: try to delete someone else's
         note.  Try to delete your own note.  Edit your own note.
         Search for a note.
    Write automated tests
    by Simon Carstensen and Joel Aufrecht
    
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
    
-    It seems to me that a lot of people have been asking for some guidelines on how to write automated tests. I've done several tests by now and have found the process to be extremely easy and useful. It's a joy to work with automated testing once you get the hang of it.
    Create the directory that will contain the test
+    It seems to me that a lot of people have been asking for some guidelines on how to write automated tests. I've done several tests by now and have found the process to be extremely easy and useful. It's a joy to work with automated testing once you get the hang of it.
    Create the directory that will contain the test
     script and edit the script file.  The directory location and file name are standards which are recognized by the automated testing package:
    [$OPENACS_SERVICE_NAME www]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/test
 [$OPENACS_SERVICE_NAME www]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/test
 [$OPENACS_SERVICE_NAME test]$ emacs myfirstpackages-procs.tcl
    Write the tests.  This is obviously the big step :)  The script should first call ad_library like any normal -procs.tcl file:
    ad_library {
     ...
 }
 
    To create a test case you call
 aa_register_case test_case_name..   
-Once you've created the test case you start writing the needed logic.
-We'll use the tutorial package, "myfirstpackage," as an example.
-Let's say you just wrote an API for adding and deleting notes in the
-notes packages and wanted to test that. You'd probably want to write a
+Once you've created the test case you start writing the needed logic.
+We'll use the tutorial package, "myfirstpackage," as an example.
+Let's say you just wrote an API for adding and deleting notes in the
+notes packages and wanted to test that. You'd probably want to write a
 test that first creates a note, then verifies that it was inserted,
 then perhaps deletes it again, and finally verifies that it is
 gone.
    
-Naturally this means you'll be adding a lot of bogus data to the
-database, which you're not really interested in having there. To avoid
+Naturally this means you'll be adding a lot of bogus data to the
+database, which you're not really interested in having there. To avoid
 this I usually do two things. I always put all my test code inside a
 call to aa_run_with_teardown which basically means that all the
 inserts, deletes, and updates will be rolled back once the test has
 been executed. A very useful feature. Instead of inserting bogus data
-like:        set name "Simon", I tend to generate a random script in order avoid inserting a value that's already in the database:
    set name [ad_generate_random_string]
-
    Here's how the test case looks so far:
    aa_register_case mfp_basic_test {
+like:        set name "Simon", I tend to generate a random script in order avoid inserting a value that's already in the database:
    set name [ad_generate_random_string]
+
    Here's how the test case looks so far:
    aa_register_case mfp_basic_test {
     My test
 } {
     aa_run_with_teardown \
@@ -64,11 +64,11 @@
 
        }
 }
-
    Now let's look at the actual test code. That's the code that
+
    Now let's look at the actual test code. That's the code that
 goes inside -test_code {}.  We want to implement test case API-001, "Given an object id from API-001, invoke mfp::note::get.  Proc should return the specific word in the title."
           set name [ad_generate_random_string]
       set new_id [mfp::note::add -title $name]
-      aa_true "Note add succeeded" ([info exists new_id] && $new_id ne "")
    To test our simple case, we must load the test file into the system (just as with the /tcl file in the basic tutorial, since the file didn't exist when the system started, the system doesn't know about it.)  To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage".  Since we'll be changing it frequently, select "watch this file" on the next page.  This will cause the system to check this file every time any page is requested, which is bad for production systems but convenient for developing.  We can also add some aa_register_case flags to make it easier to run the test.  The -procs flag, which indicates which procs are tested by this test case, makes it easier to find procs in your package that aren't tested at all.  The -cats flag, setting categories, makes it easier to control which tests to run.  The smoke test setting means that this is a basic test case that can and should be run any time you are doing any test. (a definition of "smoke test")
    Once the file is loaded, go to ACS Automated Testing and click on myfirstpackage.  You should see your test case.  Run it and examine the results.
    TCLWebtest tests
    API testing can only test part of our package - it doesn't test the code in our adp/tcl pairs.  For this, we can use TCLwebtest.  TCLwebtest must be installed for this test to work.  This provides a library of functions that make it easy to call a page through HTTP, examine the results, and drive forms.  TCLwebtest's functions overlap slightly with acs-automated-testing; see the example provided for one approach on integrating them.
    Example
    Now we can add the rest of the API tests, including a test with deliberately bad data.  The complete test looks like:
    ad_library {
+      aa_true "Note add succeeded" ([info exists new_id] && $new_id ne "")
    To test our simple case, we must load the test file into the system (just as with the /tcl file in the basic tutorial, since the file didn't exist when the system started, the system doesn't know about it.)  To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage".  Since we'll be changing it frequently, select "watch this file" on the next page.  This will cause the system to check this file every time any page is requested, which is bad for production systems but convenient for developing.  We can also add some aa_register_case flags to make it easier to run the test.  The -procs flag, which indicates which procs are tested by this test case, makes it easier to find procs in your package that aren't tested at all.  The -cats flag, setting categories, makes it easier to control which tests to run.  The smoke test setting means that this is a basic test case that can and should be run any time you are doing any test. (a definition of "smoke test")
    Once the file is loaded, go to ACS Automated Testing and click on myfirstpackage.  You should see your test case.  Run it and examine the results.
    TCLWebtest tests
    API testing can only test part of our package - it doesn't test the code in our adp/tcl pairs.  For this, we can use TCLwebtest.  TCLwebtest must be installed for this test to work.  This provides a library of functions that make it easy to call a page through HTTP, examine the results, and drive forms.  TCLwebtest's functions overlap slightly with acs-automated-testing; see the example provided for one approach on integrating them.
    Example
    Now we can add the rest of the API tests, including a test with deliberately bad data.  The complete test looks like:
    ad_library {
     Test cases for my first package.
 }
 
@@ -131,15 +131,15 @@
         
         @author Peter Marklund
     } {
-        # we need to get a user_id here so that it's available throughout
+        # we need to get a user_id here so that it's available throughout
         # this proc
         set user_id [db_nextval acs_object_id_seq]
 
         set note_title [ad_generate_random_string]
 
         # NOTE: Never use the aa_run_with_teardown with the rollback switch
         # when running Tclwebtest tests since this will put the test code in
-        # a transaction and changes won't be visible across HTTP requests.
+        # a transaction and changes won't be visible across HTTP requests.
         
         aa_run_with_teardown -test_code {
             
@@ -189,7 +189,7 @@
             # 1) go directly to the database to get the id
             # 2) require an API function that takes name and returns ID
             # 3) screen-scrape for the ID
-            # all options are problematic.  We'll do #1 in this example:
+            # all options are problematic.  We'll do #1 in this example:
 
             set note_id [db_string get_note_id_from_name " 
                 select item_id 
Index: openacs-4/packages/acs-core-docs/www/tutorial-distribute.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-distribute.adp,v
diff -u -N -r1.1.2.10 -r1.1.2.11
--- openacs-4/packages/acs-core-docs/www/tutorial-distribute.adp	21 Jun 2016 07:44:36 -0000	1.1.2.10
+++ openacs-4/packages/acs-core-docs/www/tutorial-distribute.adp	23 Jun 2016 08:32:46 -0000	1.1.2.11
@@ -13,7 +13,7 @@
 distribution.
    Browse to the package manager. Click on tutorialapp.
    Click on Generate a distribution file for
 this package from the filesystem.
    Click on the file size (37.1KB) after the label
 Distribution File: and save the
-file to /var/tmp.
    Package development guidelines
    
+file to /var/tmp.
    Package development guidelines
    
 
    
 37.1KB    )
         after the label Distribution
         File: and save the file to
-        /var/tmp.
    
+        /var/tmp.
    
 
    Package development guidelines
    Prev Home Next
    Profile your code Up Distributing upgrades of your package
    docs@openacs.org
    View comments on this page at openacs.org
    
Index: openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.adp,v
diff -u -N -r1.1.2.11 -r1.1.2.12
--- openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.adp	21 Jun 2016 07:44:36 -0000	1.1.2.11
+++ openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.adp	23 Jun 2016 08:32:46 -0000	1.1.2.12
@@ -54,8 +54,8 @@
             cvs -d:pserver:anonymous\@openacs.org:/cvsroot co edit-this-page
 
    
 
  • Go to the package manager at http://yoursite/acs-admin/apm. And
-install the new package: edit-this-page.
  • Or use the "Add Application" form available on the Main
-site.
    • 
+install the new package: edit-this-page.
  • Or use the "Add Application" form available on the
+Main site.
    • 
 
 
    
 
    
@@ -86,8 +86,8 @@
 
  • 
 
    The template should provide us with the following ETP
 layout:
    
-
    Table 10.1. table showing
-ETP layout
    
+
    Table 10.1. table
+showing ETP layout
    
@@ -97,10 +97,10 @@
 
    
 
 
 
 
    
 

    
-
  • The "Main Content" pane should contain the editable content that
-ETP provides.
  • The "Header" should display the title of the page that you set
-in ETP.
  • The "Sidebar" should display the extlinks that you add as a
-content item in ETP.
    • 
+
  • The "Main Content" pane should contain the editable
+content that ETP provides.
  • The "Header" should display the title of the page that
+you set in ETP.
  • The "Sidebar" should display the extlinks that you add
+as a content item in ETP.
    • 
 
    
 
    
 
    
Index: openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.html,v
diff -u -N -r1.9.2.10 -r1.9.2.11
--- openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.html	21 Jun 2016 07:44:36 -0000	1.9.2.10
+++ openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.html	23 Jun 2016 08:32:46 -0000	1.9.2.11
@@ -13,5 +13,5 @@
             cvs -d:pserver:anonymous@openacs.org:/cvsroot co edit-this-page
  • Go to the package manager at http://yoursite/acs-admin/apm. And install  the new package: edit-this-page.
  • Or use the "Add Application" form available on the Main site.
    • Change ETP Application
    • Work out how to change the ETP application.
    • Investigate each of the available ETP templates:
      • Default
      • News
      • FAQ
    Exercise 4: Create a New ETP Template
    • Browse the files for each of the above ETP templates at:
      cd ~/openacs/packages/edit-this-page/templates
    • Use the article template as the basis of our new col2 template.
      cp article-content.adp col2-content.adp
             cp article-content.tcl col2-content.tcl
             cp article-index.adp col2-index.adp
-            cp article-index.tcl col2-index.tcl
    • The template should provide us with the following ETP layout:
      Table 10.1. table showing ETP layout
      Header
      SidebarMain Content Pane

    • The "Main Content" pane should contain the editable content that ETP provides.
    • The "Header" should display the title of the page that you set in ETP.
    • The "Sidebar" should display the extlinks that you add as a content item in ETP.
    Exercise 5: Register the col2 Template with ETP
    • Need to register your template with ETP so that it appears in the drop-down menu that you would have seen in Exercise 3.
      cd ~/openacs/packages/edit-this-page/tcl
+            cp article-index.tcl col2-index.tcl
    • The template should provide us with the following ETP layout:
      Table 10.1. table showing ETP layout
      Header
      SidebarMain Content Pane

    • The "Main Content" pane should contain the editable content that ETP provides.
    • The "Header" should display the title of the page that you set in ETP.
    • The "Sidebar" should display the extlinks that you add as a content item in ETP.
    Exercise 5: Register the col2 Template with ETP
    • Need to register your template with ETP so that it appears in the drop-down menu that you would have seen in Exercise 3.
      cd ~/openacs/packages/edit-this-page/tcl
             emacs etp-custom-init.tcl
    • Use the function etp::define_application to register your template with ETP
      • Uncomment the "asc" definition
      • Set allow_extlinks to true, the rest should be false.
    • Restart your server for the changes to take effect.
    Exercise 6: Configure ETP to use the col2 Template
    • Configure your ETP instance at /lab4/index to use the col2 template.
    • Create external links to link to other mounted ETP instances.
    • Check that your external links show up in the sidebar when you view your ETP application using the col2 template.
    Who Wrote This and When
    This problem set was originally written by Nick Carroll in August 2004 for the University of Sydney Course EBUS5002.
    This material is copyright 2004 by Nick Carroll.  It may be copied, reused, and modified, provided credit is given to the original author.
    ($Id$)
    Prev Home Next
    Add the new package to CVS Up Adding Comments
    docs@openacs.org
    View comments on this page at openacs.org
    
Index: openacs-4/packages/acs-core-docs/www/tutorial-future-topics.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-future-topics.adp,v
diff -u -N -r1.1.2.1 -r1.1.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-future-topics.adp	23 Sep 2015 11:54:59 -0000	1.1.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-future-topics.adp	23 Jun 2016 08:32:46 -0000	1.1.2.2
@@ -11,11 +11,11 @@
 
    
 Future
 Topics
      
-
    • How to enforce security so that users can't change other users
-records
    • How to use the content management tables so that ... what?
    • How to change the default stylesheets for Form Builder HTML
+
    • How to enforce security so that users can't change other
+users records
    • How to use the content management tables so that ... what?
    • How to change the default stylesheets for Form Builder HTML
 forms.
    • How to make your package searchable with OpenFTS/Oracle
    • How to prepare pagelets for inclusion in other pages
    • How and when to put procedures in a tcl procedure library
    • More on ad_form - data validation, other stuff. (plan to draw
-from Jon Griffin's doc)
    • partialquery in xql
    • How to use the html/text entry widget to get the "does this look
-right" confirm page
    • APM package dependencies
      • 
+from Jon Griffin's doc)
    • partialquery in xql
    • How to use the html/text entry widget to get the "does this
+look right" confirm page
    • APM package dependencies
      • 
 
    See also the OpenACS
 Programming FAQ
 
    
Index: openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html,v
diff -u -N -r1.17.2.1 -r1.17.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html	9 Jun 2016 08:44:50 -0000	1.17.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html	23 Jun 2016 08:32:46 -0000	1.17.2.2
@@ -1,7 +1,7 @@
 
-Future Topics
    Alex logo
    Prev Chapter 10. Advanced Topics Next
    Future Topics
    • How to enforce security so that users can't
+Future Topics
      Alex logo
      Prev Chapter 10. Advanced Topics Next
      Future Topics
      • How to enforce security so that users can't
       change other users records
      • How to use the content management tables so that
       ... what?
      • How to change the default stylesheets for Form
       Builder HTML forms.
      • How to make your package searchable with OpenFTS/Oracle
      • How to prepare pagelets for inclusion in other pages
      • How and when to put procedures in a tcl procedure library
      • More on ad_form - data validation, other stuff.
-      (plan to draw from Jon Griffin's doc)
      • partialquery in xql
      • How to use the html/text entry widget to get the
+      (plan to draw from Jon Griffin's doc)
      • partialquery in xql
      • How to use the html/text entry widget to get the
       "does this look right" confirm page 
      • APM package dependencies
      See also the OpenACS Programming FAQ
      Prev Home Next
      Connect to a second database Up Chapter 11. Development Reference
      docs@openacs.org
      View comments on this page at openacs.org
      
Index: openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.adp,v
diff -u -N -r1.1.2.1 -r1.1.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.adp	23 Sep 2015 11:54:59 -0000	1.1.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.adp	23 Jun 2016 08:32:46 -0000	1.1.2.2
@@ -40,7 +40,7 @@
       o.tree_sortkey"
     
 
      Note the use of the tree_level() function, which gives you the
-level, starting from 1, 2, 3...
      Here's an example, pulling all of the children for a given
+level, starting from 1, 2, 3...
      Here's an example, pulling all of the children for a given
 parent:
             SELECT 
       children.*,
@@ -54,13 +54,13 @@
       and parent.tree_sortkey <> children.tree_sortkey
       and parent.key = :the_parent_key;
       
-
      The reason we substract the parent's tree_level from the child's
-tree_level is that the tree_levels are global, so if you want the
-parent's tree_level to start with 0, you'll want the subtraction in
-there. This is a reason you'll commonly see magic numbers in
-tree_sortkey SQL queries, like tree_level(children.tree_sortkey) - 4. That
+
      The reason we substract the parent's tree_level from the
+child's tree_level is that the tree_levels are global, so if
+you want the parent's tree_level to start with 0, you'll
+want the subtraction in there. This is a reason you'll commonly
+see magic numbers in tree_sortkey SQL queries, like tree_level(children.tree_sortkey) - 4. That
 is basically an incorrect way to do it, and subtracting the
-parent's tree_level is the preferred method.
      This example does not include the parent. To return the entire
+parent's tree_level is the preferred method.
      This example does not include the parent. To return the entire
 subtree including the parent, leave out the non-equals clause:
             SELECT
       subtree.*,
Index: openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.html,v
diff -u -N -r1.11.2.1 -r1.11.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.html	9 Jun 2016 08:44:50 -0000	1.11.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.html	23 Jun 2016 08:32:46 -0000	1.11.2.2
@@ -30,7 +30,7 @@
       o.tree_sortkey"
     
      Note the use of the
     tree_level() function, which
-    gives you the level, starting from 1, 2, 3... 
      Here's an example, pulling all of the children for a given
+    gives you the level, starting from 1, 2, 3... 
      Here's an example, pulling all of the children for a given
   parent:
             SELECT 
       children.*,
@@ -43,14 +43,14 @@
       children.tree_sortkey between parent.tree_sortkey and tree_right(parent.tree_sortkey)
       and parent.tree_sortkey <> children.tree_sortkey
       and parent.key = :the_parent_key;
-      
      The reason we substract the parent's tree_level from the
-    child's tree_level is that the tree_levels are global, so if you
-    want the parent's tree_level to start with 0, you'll want the
-    subtraction in there. This is a reason you'll commonly see magic
+      
      The reason we substract the parent's tree_level from the
+    child's tree_level is that the tree_levels are global, so if you
+    want the parent's tree_level to start with 0, you'll want the
+    subtraction in there. This is a reason you'll commonly see magic
     numbers in tree_sortkey SQL queries, like
     tree_level(children.tree_sortkey) -
     4. That is basically an incorrect way to do it,
-    and subtracting the parent's tree_level is the preferred method.
      This example does not include the parent. To return the entire subtree including the parent, leave out the non-equals clause:
      +    and subtracting the parent's tree_level is the preferred method.
      This example does not include the parent. To return the entire subtree including the parent, leave out the non-equals clause:
             SELECT
       subtree.*,
       tree_level(subtree.tree_sortkey) -
Index: openacs-4/packages/acs-core-docs/www/tutorial-newpackage.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-newpackage.adp,v
diff -u -N -r1.1.2.10 -r1.1.2.11
--- openacs-4/packages/acs-core-docs/www/tutorial-newpackage.adp	21 Jun 2016 07:44:36 -0000	1.1.2.10
+++ openacs-4/packages/acs-core-docs/www/tutorial-newpackage.adp	23 Jun 2016 08:32:46 -0000	1.1.2.11
@@ -30,21 +30,21 @@
 setting up database tables and procedures, writing web pages,
 debugging, and automatic regression testing.
      This tutorial uses the content repository package. This
 radically simplifies the database work, but forces us to work
-around the content repository's limitations, including an
-incomplete Tcl API. So the tutorial is messier than we'd like right
-now. Code that is temporary hackage is clearly marked.
      In this tutorial, we will make an application package for
+around the content repository's limitations, including an
+incomplete Tcl API. So the tutorial is messier than we'd like
+right now. Code that is temporary hackage is clearly marked.
      In this tutorial, we will make an application package for
 displaying a list of text notes.
      
 
    
 
    
 Before you begin
    You will need:
    
-
    Figure 9.1. Assumptions
-in this section
    
+
    Figure 9.1. Assumptions in this
+section
    
@@ -74,8 +74,8 @@
 .
  • 
 
    Click Create a New
 Package.
    Fill in the fields listed below. Ignore the rest (and leave the check boxes
-alone). (Some will change automatically. Don't mess
-with those.)
    
 
    
@@ -110,13 +110,13 @@
 URL requests and an instance
 of the application. (More on applications and nodes)
    You can have instances of a package on one site, each with a
 different URL and different permissions, all sharing the same code
-and tables. This requires that a package be developed package-aware. You'll see how to do that
-in this tutorial.
      
+and tables. This requires that a package be developed package-aware. You'll see how to do
+that in this tutorial.
        
 
      1. Browse to 
 http://yourserver.test:8000/admin/applications/application-add/
-.
      2. Choose "My First Package" from the list and click OK (the other
-fields are optional).
        3. 
-
      By mounting the package, we've caused all requests to
+.
    1. Choose "My First Package" from the list and click OK
+(the other fields are optional).
      2. 
+
    By mounting the package, we've caused all requests to
 http://yourserver.test:8000/myfirstpackage
 to be satisfied from the files at /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www.
    
 
    
Index: openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html,v
diff -u -N -r1.43.2.10 -r1.43.2.11
--- openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html	21 Jun 2016 07:44:36 -0000	1.43.2.10
+++ openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html	23 Jun 2016 08:32:46 -0000	1.43.2.11
@@ -13,13 +13,13 @@
       
    
         This tutorial uses the content repository package.  This
         radically simplifies the database work, but forces us to work
-        around the content repository's limitations, including an
-        incomplete Tcl API.  So the tutorial is messier than we'd like
+        around the content repository's limitations, including an
+        incomplete Tcl API.  So the tutorial is messier than we'd like
         right now.  Code that is temporary hackage is clearly marked.
       
    In this tutorial, we will make an application package for
     displaying a list of text notes.
 
    Before you begin
    You will need:
    Figure 9.1. Assumptions in this section
    • 
 
 
 
    Fully qualified domain name of your serveryourserver.test
    URL of your serverhttp://yourserver.test:8000
    Name of development account$OPENACS_SERVICE_NAME
    New Package keymyfirstpackage

    Use the APM to initialize a new package
    We use the ACS Package Manager (APM) to add, remove, and
@@ -33,7 +33,7 @@
 
    1. Browse to
         http://yourserver:8000/acs-admin/apm.
 
    2. Click Create a New Package.
      Fill in the fields listed below.   Ignore the rest (and leave the check boxes alone).
-        (Some will change automatically.  Don't mess with those.)
+        (Some will change automatically.  Don't mess with those.)
 
      • 
               Package Key:
               myfirstpackage
      • 
@@ -62,9 +62,9 @@
       instance of the application.  (More on applications and nodes)
        You can have instances of a package on one site, each with a
       different URL and different permissions, all sharing the same
       code and tables.  This requires that a package be developed
-      package-aware.  You'll see how to do that
+      package-aware.  You'll see how to do that
       in this tutorial.
        1. Browse to
-http://yourserver.test:8000/admin/applications/application-add/.
        2. Choose "My First Package" from the list and click OK (the other fields are optional).
        By mounting the package, we've caused all requests to
+http://yourserver.test:8000/admin/applications/application-add/.
      • Choose "My First Package" from the list and click OK (the other fields are optional).
    By mounting the package, we've caused all requests to
       http://yourserver.test:8000/myfirstpackage
       to be satisfied from the files at /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www.
    Quick start
    The remainder of the tutorial walks you through each file one at a time as you create the package.  You can skip all this, and get a working package, by doing the following:
    cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/tutorial
 psql $OPENACS_SERVICE_NAME -f myfirstpackage-create.sql
Index: openacs-4/packages/acs-core-docs/www/tutorial-notifications.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-notifications.adp,v
diff -u -N -r1.1.2.1 -r1.1.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-notifications.adp	23 Sep 2015 11:55:00 -0000	1.1.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-notifications.adp	23 Jun 2016 08:32:46 -0000	1.1.2.2
@@ -93,7 +93,7 @@
       -- \@creation-date 2002-05-16
       --
       -- This code is newly concocted by Ben, but with significant concepts and code
-      -- lifted from Gilbert's UBB forums. Thanks Orchard Labs.
+      -- lifted from Gilbert's UBB forums. Thanks Orchard Labs.
       -- Lars and Jade in turn lifted this from gwong and ben.
 
 create function inline_0 ()
Index: openacs-4/packages/acs-core-docs/www/tutorial-notifications.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-notifications.html,v
diff -u -N -r1.17.2.1 -r1.17.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-notifications.html	9 Jun 2016 08:44:50 -0000	1.17.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-notifications.html	23 Jun 2016 08:32:46 -0000	1.17.2.2
@@ -79,7 +79,7 @@
       -- @creation-date 2002-05-16
       --
       -- This code is newly concocted by Ben, but with significant concepts and code
-      -- lifted from Gilbert's UBB forums. Thanks Orchard Labs.
+      -- lifted from Gilbert's UBB forums. Thanks Orchard Labs.
       -- Lars and Jade in turn lifted this from gwong and ben.
 
 create function inline_0 ()
Index: openacs-4/packages/acs-core-docs/www/tutorial-pages.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-pages.adp,v
diff -u -N -r1.1.2.12 -r1.1.2.13
--- openacs-4/packages/acs-core-docs/www/tutorial-pages.adp	21 Jun 2016 07:44:36 -0000	1.1.2.12
+++ openacs-4/packages/acs-core-docs/www/tutorial-pages.adp	23 Jun 2016 08:32:46 -0000	1.1.2.13
@@ -16,15 +16,16 @@
 OpenACS documentation staff.
    
 
    
 Install some API
    As a workaround for missing content-repository functionality,
-copy a provided file into the directory for tcl files:
    cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/tutorial/note-procs.tcl /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/
    To make this file take effect, go to the APM and choose "Reload changed"
-for "MyFirstPackage".
    
+copy a provided file into the directory for tcl files:
    cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/tutorial/note-procs.tcl /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/
    To make this file take effect, go to the APM and choose "Reload
+changed" for "MyFirstPackage".
    
 
    
 
    
 Page Map
    Our package will have two visible pages. The first shows a list
 of all objects; the second shows a single object in view or edit
 mode, and can also be used to add an object. The index page will
-display the list, but since we might reuse the list later, we'll
-put it in a seperate file and include it on the index page.
    
+display the list, but since we might reuse the list later,
+we'll put it in a seperate file and include it on the index
+page.
    
 
    Figure 9.5. Page
 Map
    Page Map
    
 

    
@@ -38,7 +39,7 @@
 the adp page holds html. The
 -postgres.xql and -oracle.xql files contains
 database-specific SQL. The default page in any directory is
-index, so we'll build that
+index, so we'll build that
 first, starting with the tcl file:
     [$OPENACS_SERVICE_NAME postgresql]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackages/www
 [$OPENACS_SERVICE_NAME www]$ emacs index.tcl
@@ -47,7 +48,7 @@
     This is the main page for the package.  It displays all of the Notes and provides links to edit them and to create new Notes.
 
     \@author Your Name (you\@example.com)
-    \@cvs-id $‌Id: index.tcl,v 1.2.22.1 2015/09/10 08:21:20 gustafn Exp $
+    \@cvs-id $‌Id: tutorial-pages.html,v 1.44.2.10 2016/06/21 07:44:36 gustafn Exp $
 }
 
 set page_title [ad_conn instance_name]
@@ -63,8 +64,8 @@
   <property name="context">\@context;literal\@</property>
 <include src="/packages/myfirstpackage/lib/note-list">
 
    The index page includes the list page, which we put in /lib
-instead of /www to designate that it's available for reuse by other
-packages.
    +instead of /www to designate that it's available for reuse by
+other packages.
     [$OPENACS_SERVICE_NAME www]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib
 [$OPENACS_SERVICE_NAME www]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib
 [$OPENACS_SERVICE_NAME lib]$ emacs note-list.tcl
@@ -126,7 +127,7 @@
     This is the view-edit page for notes.
 
     \@author Your Name (you\@example.com)
-    \@cvs-id $‌Id: note-edit.tcl,v 1.3.2.1 2015/09/10 08:21:20 gustafn Exp $
+    \@cvs-id $‌Id: tutorial-pages.html,v 1.44.2.10 2016/06/21 07:44:36 gustafn Exp $
  
     \@param item_id If present, assume we are editing that note.  Otherwise, we are creating a new note.
 } {
@@ -185,7 +186,7 @@
     This deletes a note
 
     \@author Your Name (you\@example.com)
-    \@cvs-id $‌Id: note-delete.tcl,v 1.3.2.1 2015/09/10 08:21:20 gustafn Exp $
+    \@cvs-id $‌Id: tutorial-pages.html,v 1.44.2.10 2016/06/21 07:44:36 gustafn Exp $
  
     \@param item_id The item_id of the note to delete
 } {
@@ -197,7 +198,7 @@
 mfp::note::delete -item_id $item_id
 
 ad_returnredirect "."
-# stop running this code, since we're redirecting
+# stop running this code, since we're redirecting
 abort
 
 # Local variables:
Index: openacs-4/packages/acs-core-docs/www/tutorial-pages.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-pages.html,v
diff -u -N -r1.44.2.10 -r1.44.2.11
--- openacs-4/packages/acs-core-docs/www/tutorial-pages.html	21 Jun 2016 07:44:36 -0000	1.44.2.10
+++ openacs-4/packages/acs-core-docs/www/tutorial-pages.html	23 Jun 2016 08:32:46 -0000	1.44.2.11
@@ -3,7 +3,7 @@
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
    Install some API
    As a workaround for missing content-repository functionality, copy a provided file into the directory for tcl files:
    -    cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/tutorial/note-procs.tcl /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/
    To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage".
    Page Map
    Our package will have two visible pages.  The first shows a list of all objects; the second shows a single object in view or edit mode, and can also be used to add an object.  The index page will display the list, but since we might reuse the list later, we'll put it in a seperate file and include it on the index page.
    Figure 9.5. Page Map
    Page Map

    Build the "Index" page
    Each user-visible page in your package has, typically,
+    cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/tutorial/note-procs.tcl /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/
    To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage".
    Page Map
    Our package will have two visible pages.  The first shows a list of all objects; the second shows a single object in view or edit mode, and can also be used to add an object.  The index page will display the list, but since we might reuse the list later, we'll put it in a seperate file and include it on the index page.
    Figure 9.5. Page Map
    Page Map

    Build the "Index" page
    Each user-visible page in your package has, typically,
       three parts.  The  tcl file
       holds the procedural logic for the page, including Tcl and
       database-independent SQL code, and does things like
@@ -12,7 +12,7 @@
       holds html.  The -postgres.xql
       and -oracle.xql files contains
       database-specific SQL.  The default page in any directory is
-      index, so we'll build that
+      index, so we'll build that
       first, starting with the tcl file:
    [$OPENACS_SERVICE_NAME postgresql]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackages/www
 [$OPENACS_SERVICE_NAME www]$ emacs index.tcl
    Paste this into the file.
    ad_page_contract {
     This is the main page for the package.  It displays all of the Notes and provides links to edit them and to create new Notes.
@@ -31,7 +31,7 @@
 
    Now index.adp:
    <master>
   <property name="doc(title)">@page_title;literal@</property>
   <property name="context">@context;literal@</property>
-<include src="/packages/myfirstpackage/lib/note-list">
    The index page includes the list page, which we put in /lib instead of /www to designate that it's available for reuse by other packages.
    [$OPENACS_SERVICE_NAME www]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib
+<include src="/packages/myfirstpackage/lib/note-list">
    The index page includes the list page, which we put in /lib instead of /www to designate that it's available for reuse by other packages.
    [$OPENACS_SERVICE_NAME www]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib
 [$OPENACS_SERVICE_NAME www]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib
 [$OPENACS_SERVICE_NAME lib]$ emacs note-list.tcl
    template::list::create \
     -name notes \
@@ -146,7 +146,7 @@
 mfp::note::delete -item_id $item_id
 
 ad_returnredirect "."
-# stop running this code, since we're redirecting
+# stop running this code, since we're redirecting
 abort
 
 # Local variables:
Index: openacs-4/packages/acs-core-docs/www/tutorial-parameters.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-parameters.adp,v
diff -u -N -r1.1.2.1 -r1.1.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-parameters.adp	23 Sep 2015 11:55:01 -0000	1.1.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-parameters.adp	23 Jun 2016 08:32:46 -0000	1.1.2.2
@@ -14,7 +14,7 @@
 it. These are like preferences, and they can be set by the
 administrator for each application to change the behavior of your
 application.
    To add parameters for your package, go to the Automatic Package
-Manager (/acs-admin/apm)
    Click on your package
    Under the Manage section, click on Parameters
    It's fairly self-explanatory at this point. Create the
+Manager (/acs-admin/apm)
    Click on your package
    Under the Manage section, click on Parameters
    It's fairly self-explanatory at this point. Create the
 parameters you want, and then access them in your code using the
 parameter::get procedure.
    
 
    
Index: openacs-4/packages/acs-core-docs/www/tutorial-parameters.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-parameters.html,v
diff -u -N -r1.9.2.1 -r1.9.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-parameters.html	9 Jun 2016 08:44:50 -0000	1.9.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-parameters.html	23 Jun 2016 08:32:46 -0000	1.9.2.2
@@ -3,6 +3,6 @@
     with it. These are like preferences, and they can be set by the
     administrator for each application to change the behavior of your
     application. 
    To add parameters for your package, go to the Automatic
-    Package Manager (/acs-admin/apm)
    Click on your package
    Under the Manage section, click on Parameters
    It's fairly self-explanatory at this point. Create the
+    Package Manager (/acs-admin/apm)
    Click on your package
    Under the Manage section, click on Parameters
    It's fairly self-explanatory at this point. Create the
     parameters you want, and then access them in your code using the
     parameter::get procedure.
    Prev Home Next
    Enabling WYSIWYG Up Writing upgrade scripts
    docs@openacs.org
    View comments on this page at openacs.org
    
Index: openacs-4/packages/acs-core-docs/www/tutorial-second-database.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-second-database.adp,v
diff -u -N -r1.1.2.1 -r1.1.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-second-database.adp	23 Sep 2015 11:55:01 -0000	1.1.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-second-database.adp	23 Jun 2016 08:32:46 -0000	1.1.2.2
@@ -72,8 +72,9 @@
 
 
  • 
 
    To use the legacy database, use the -dbn flag for any of the db_ API calls. For example, suppose there is a table
-called "foo" in the legacy system, with a field "bar". List "bar"
-for all records with this tcl file:
    +called "foo" in the legacy system, with a field
+"bar". List "bar" for all records with this tcl
+file:
     db_foreach -dbn legacy get_bar_query {
   select bar from foo
   limit 10
Index: openacs-4/packages/acs-core-docs/www/tutorial-specs.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-specs.adp,v
diff -u -N -r1.1.2.2 -r1.1.2.3
--- openacs-4/packages/acs-core-docs/www/tutorial-specs.adp	23 Sep 2015 18:51:44 -0000	1.1.2.2
+++ openacs-4/packages/acs-core-docs/www/tutorial-specs.adp	23 Jun 2016 08:32:46 -0000	1.1.2.3
@@ -13,9 +13,9 @@
 the tags that are used to write your documentation. For tips on
 editing SGML files in emacs, see the
 section called “OpenACS Documentation
-Guide”.
    It's time to document. For the tutorial we'll use pre-written
-documentation. When creating a package from scratch, start by
-copying the documentation template from /var/lib/aolserver/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml
+Guide”.
    It's time to document. For the tutorial we'll use
+pre-written documentation. When creating a package from scratch,
+start by copying the documentation template from /var/lib/aolserver/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml
 to myfirstpackage/www/docs/xml/index.xml.
    You then edit that file with emacs to write the requirements and
 design sections, generate the html, and start coding. Store any
 supporting files, like page maps or schema diagrams, in the
Index: openacs-4/packages/acs-core-docs/www/tutorial-specs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-specs.html,v
diff -u -N -r1.14.2.1 -r1.14.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-specs.html	9 Jun 2016 08:44:50 -0000	1.14.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-specs.html	23 Jun 2016 08:32:46 -0000	1.14.2.2
@@ -1,7 +1,7 @@
 
 Write the Requirements and Design Specs
    Alex logo
    Prev Chapter 10. Advanced Topics Next
    Write the Requirements and Design Specs
    Before you get started you should make yourself familiar with
       the tags that are used to write your documentation. For tips on
-        editing SGML files in emacs, see the section called “OpenACS Documentation Guide”.
    It's time to document.  For the tutorial we'll use
+        editing SGML files in emacs, see the section called “OpenACS Documentation Guide”.
    It's time to document.  For the tutorial we'll use
       pre-written documentation.  When creating a package
       from scratch, start by copying the documentation template from
 	/var/lib/aolserver/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml
Index: openacs-4/packages/acs-core-docs/www/tutorial-upgrades.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-upgrades.adp,v
diff -u -N -r1.1.2.2 -r1.1.2.3
--- openacs-4/packages/acs-core-docs/www/tutorial-upgrades.adp	23 Sep 2015 18:51:44 -0000	1.1.2.2
+++ openacs-4/packages/acs-core-docs/www/tutorial-upgrades.adp	23 Jun 2016 08:32:46 -0000	1.1.2.3
@@ -17,10 +17,10 @@
 can be installed on OpenACS installations, and can be used by
 administrators to update their packages. If you are a package
 developer, there are a couple of steps you need to take in order to
-release a new version of your package.
    For the sake of this example, let's assume you are the package
-owner of the notes package. It
-is currently at version 1.5, and you are planning on releasing
-version 1.6. It is also located in OpenACS's CVS.
    To release your package:
    +release a new version of your package.
    For the sake of this example, let's assume you are the
+package owner of the notes
+package. It is currently at version 1.5, and you are planning on
+releasing version 1.6. It is also located in OpenACS's CVS.
    To release your package:
     cd /path/to/notes
 cvs commit -m "Update package to version 1.6."
 cvs tag notes-1-6-final
Index: openacs-4/packages/acs-core-docs/www/tutorial-upgrades.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-upgrades.html,v
diff -u -N -r1.9.2.1 -r1.9.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-upgrades.html	9 Jun 2016 08:44:50 -0000	1.9.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-upgrades.html	23 Jun 2016 08:32:46 -0000	1.9.2.2
@@ -6,7 +6,7 @@
     that can be installed on OpenACS installations, and can be used by
     administrators to update their packages. If you are a package
     developer, there are a couple of steps you need to take in order
-    to release a new version of your package. 
    For the sake of this example, let's assume you are the
+    to release a new version of your package. 
    For the sake of this example, let's assume you are the
     package owner of the notes
     package. It is currently at version 1.5, and you are planning on
     releasing version 1.6. It is also located in OpenACS's CVS.
    To release your package:
    cd /path/to/notes
Index: openacs-4/packages/acs-core-docs/www/tutorial-vuh.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-vuh.adp,v
diff -u -N -r1.1.2.2 -r1.1.2.3
--- openacs-4/packages/acs-core-docs/www/tutorial-vuh.adp	9 Jun 2016 13:03:12 -0000	1.1.2.2
+++ openacs-4/packages/acs-core-docs/www/tutorial-vuh.adp	23 Jun 2016 08:32:46 -0000	1.1.2.3
@@ -45,9 +45,9 @@
 final / as the item id. Note that this simple redirection will lose
 any additional query parameters passed in. Many OpenACS objects
 maintain a pretty-name, which is a unique, human-readable string,
-usually derived from title, which makes an even better 'pretty url'
-than a numeric id; this requires that your display page be able to
-look up an item based on pretty id.
    We use rp_form_put to store
+usually derived from title, which makes an even better 'pretty
+url' than a numeric id; this requires that your display page be
+able to look up an item based on pretty id.
    We use rp_form_put to store
 the item id in the internal register that the next page is
 expecting, and then redirects the request in process internally
 (ie, without a browser refresh).
    Next, modify note-list so that its link is of the new form.:
    Index: openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.adp,v
diff -u -N -r1.1.2.3 -r1.1.2.4
--- openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.adp	10 Jun 2016 07:35:08 -0000	1.1.2.3
+++ openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.adp	23 Jun 2016 08:32:46 -0000	1.1.2.4
@@ -41,7 +41,7 @@
         
 
    
 
    Warning
    You must not give your your form the same name that your page
-has. Otherwise HTMLArea won't load.
    
+has. Otherwise HTMLArea won't load.
    
 
    Convert your textarea widget to a richtext widget and enable
 htmlarea.
    The htmlarea_p-flag can be used to
 prevent WYSIWYG functionality. Defaults to true if left away.
    From:
    @@ -53,11 +53,13 @@
         
 
    The richtext widget presents a list with two elements: text and
 content type. To learn more on existing content types search in
-Google for "MIME-TYPES" or take a look at the cr_mime_types table.
    Make sure that both values are passed as a list to your
+Google for "MIME-TYPES" or take a look at the
+cr_mime_types table.
    Make sure that both values are passed as a list to your
 ad_form or you will have problems
 displaying the content or handling the data manipulation
 correctly.
    Depending on the data model of your package you either support a
-content format or don't. If you don't you can assume "text/html" or "text/richtext" or "text/enhanced".
    The relevant parts in your ad_form
+content format or don't. If you don't you can assume
+"text/html" or "text/richtext" or "text/enhanced".
    The relevant parts in your ad_form
 definition are the switches -new_data,
 -edit_data, -on_request and -on_submit.
    To allow your data to display correctly you need to add an
 -on_request block. If you have the format
@@ -74,8 +76,8 @@
         
 
    Now the correct values for my_input_field_2 and format
 are passed to the -new_data and
--edit_data blocks which don't need to get
-touched.
    To make HTMLArea optional per package instance define a string
+-edit_data blocks which don't need to
+get touched.
    To make HTMLArea optional per package instance define a string
 parameter UseWysiwygP which defaults
 0 for your package using the APM.
    In your edit page make the following changes
             # Is WYSIWYG enabled?
Index: openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.html,v
diff -u -N -r1.9.2.3 -r1.9.2.4
--- openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.html	10 Jun 2016 07:35:08 -0000	1.9.2.3
+++ openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.html	23 Jun 2016 08:32:46 -0000	1.9.2.4
@@ -20,7 +20,7 @@
 	       	   {after_html
                {<a name="#">Anchor</a>}}}
 	} ...
-	
    Warning
    You must not give your your form the same name that your page has. Otherwise HTMLArea won't load.
    Convert your textarea widget to a richtext widget and enable htmlarea.
    The htmlarea_p-flag can be used to prevent 
+	
    Warning
    You must not give your your form the same name that your page has. Otherwise HTMLArea won't load.
    Convert your textarea widget to a richtext widget and enable htmlarea.
    The htmlarea_p-flag can be used to prevent 
 	WYSIWYG functionality. Defaults to true if left away.
    From:
     	{my_input_field_2:text
 	
    To:
    @@ -31,7 +31,7 @@
 	take a look at the cr_mime_types table.
    Make sure that both values are passed as a list to your 
 	ad_form or you will have problems 
 	displaying the content or handling the data manipulation correctly.
    Depending on the data model of your package you either support a content format 
-	or don't. If you don't you can assume "text/html" or 
+	or don't. If you don't you can assume "text/html" or 
 	"text/richtext" or "text/enhanced".
    The relevant parts in your ad_form definition are the 
 	switches -new_data, -edit_data, 
 	-on_request and -on_submit.
    To allow your data to display correctly you need to add an -on_request block. 
@@ -44,7 +44,7 @@
 	set format [ template::util::richtext::get_property format $my_input_field_2] #This is optional
 	
    Now the correct values for my_input_field_2 and 
 	format are passed to the -new_data and 
-	-edit_data blocks which don't need to get touched.
    To make HTMLArea optional per package instance define a string parameter 
+	-edit_data blocks which don't need to get touched.
    To make HTMLArea optional per package instance define a string parameter 
 	UseWysiwygP which defaults 0 for your 
 	package using the APM.
    In your edit page make the following changes
     	# Is WYSIWYG enabled?
Index: openacs-4/packages/acs-core-docs/www/update-repository.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/update-repository.adp,v
diff -u -N -r1.1.2.1 -r1.1.2.2
--- openacs-4/packages/acs-core-docs/www/update-repository.adp	23 Sep 2015 11:55:04 -0000	1.1.2.1
+++ openacs-4/packages/acs-core-docs/www/update-repository.adp	23 Jun 2016 08:32:46 -0000	1.1.2.2
@@ -17,13 +17,14 @@
 oacs-x-y, and build a repository channel for each of those branches
 where x>=5 (so not for 4.6 and earlier). It will also build a
 channel for HEAD, which will be named after what you set in
-'head_channel' above.
  • For each channel, it'll do an anonymous checkout of packges and
-contrib/packages, then build .apm files for each package in the
-checkout.
  • The files will be stored on the server's hard drive in the
-directory specified by the 'repository_dir' variable in the page
-script, by default "$::acs::rootdir/www/repository/".
    • 
+'head_channel' above.
  • For each channel, it'll do an anonymous checkout of packges
+and contrib/packages, then build .apm files for each package in the
+checkout.
  • The files will be stored on the server's hard drive in the
+directory specified by the 'repository_dir' variable in the
+page script, by default
+"$::acs::rootdir/www/repository/".
    • 
 
  • 
-
    If you're on openacs.org, everything should now be fine.
+
    If you're on openacs.org, everything should now be fine.
 Otherwise, you need to move the entire directory tree to
 openacs.org:/web/openacs/www/repository, replacing what was already
 there.
    This is automated on OpenACS.org by having a dedicated site just
Index: openacs-4/packages/acs-core-docs/www/update-repository.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/update-repository.html,v
diff -u -N -r1.18.2.1 -r1.18.2.2
--- openacs-4/packages/acs-core-docs/www/update-repository.html	9 Jun 2016 08:44:50 -0000	1.18.2.1
+++ openacs-4/packages/acs-core-docs/www/update-repository.html	23 Jun 2016 08:32:46 -0000	1.18.2.2
@@ -9,11 +9,11 @@
               those branches where x>=5 (so not for 4.6 and earlier).  It will also build a channel for HEAD,
               which will be named after what you set in 'head_channel' above.
             
  • 
-              For each channel, it'll do an anonymous checkout of packges and contrib/packages, then build .apm files for each package in the checkout.
+              For each channel, it'll do an anonymous checkout of packges and contrib/packages, then build .apm files for each package in the checkout.
             
  • 
-              The files will be stored on the server's hard drive in the directory specified by the 'repository_dir' variable in the page script, by default "$::acs::rootdir/www/repository/".
+              The files will be stored on the server's hard drive in the directory specified by the 'repository_dir' variable in the page script, by default "$::acs::rootdir/www/repository/".
             
  • 
-          If you're on openacs.org, everything should now be fine. Otherwise, you need to move the entire directory tree to openacs.org:/web/openacs/www/repository, replacing what was already there.
+          If you're on openacs.org, everything should now be fine. Otherwise, you need to move the entire directory tree to openacs.org:/web/openacs/www/repository, replacing what was already there.
         
    This is automated on OpenACS.org by having a dedicated site just for building the repository, invoked with this shell script.  Since the page circumvents security checks for ease of use, the entire site is limited to local requests.  The script is called daily with a cron job.
    #!/bin/sh
 #set -x
 
Index: openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.adp,v
diff -u -N -r1.1.2.12 -r1.1.2.13
--- openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.adp	21 Jun 2016 07:44:36 -0000	1.1.2.12
+++ openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.adp	23 Jun 2016 08:32:46 -0000	1.1.2.13
@@ -12,7 +12,7 @@
 Upgrading 4.5 or higher to 4.6.3
    • The required platform for OpenACS 4.6 is the same as 4.5, with
 the exception of OpenFTS. OpenACS 4.6 and later require OpenFTS
 0.3.2 for full text search on PostGreSQL. If you have OpenFTS 0.2,
-you'll need to upgrade.
    If upgrading from 4.4, you need to manually run
+you'll need to upgrade.
    If upgrading from 4.4, you need to manually run
 acs-kernel/sql/postgres/upgrade-4.4-4.5.sql. See Bug #632
 
      
 
    • A computer with OpenACS 4.5.
    • 
@@ -21,11 +21,12 @@
 
      • 
 
      
 
    1. 
-Make a Backup. Back up the database and file
-system (see the section called
+Make a Backup. Back up the database
+and file system (see the section called
 “Manual backup and
 recovery”).
    2. 
-OPTIONAL: Upgrade OpenFTS. the section called
+OPTIONAL: Upgrade
+OpenFTS. the section called
 “Upgrading OpenFTS from 0.2 to
 0.3.2”
 
    3. 
@@ -45,16 +46,16 @@
 
 
    4. 
 
      
-Use APM
-to upgrade the database. 
+Use
+APM to upgrade the database. 
 
        
 
      1. Browse to the package manager, http://yourserver/acs-admin/apm.
      2. Click Install
 packages.
 
      3. Select the packages you want to install. This should be
 everything that says upgrade,
-plus any new packages you want. It's safest to upgrade the kernel
-by itself, and then come back and upgrade the rest of the desired
-packages in a second pass.
      4. On the next screen, click Install Packages
+plus any new packages you want. It's safest to upgrade the
+kernel by itself, and then come back and upgrade the rest of the
+desired packages in a second pass.
      5. On the next screen, click Install Packages
 
      6. 
 
        When prompted, restart the server:
         [root root]# restart-aolserver $OPENACS_SERVICE_NAME
@@ -65,8 +66,8 @@
 5.9.0.
        7. 
 
      
 
    5. 
-Rollback. If anything goes wrong, roll
-back to the backup snapshot.
      6. 
+Rollback. If anything goes wrong,
+roll back to the backup snapshot.
      
 
    
 
 
 Upgrading 4.5 or higher to 4.6.3
    Alex logo
    Prev Chapter 5. Upgrading Next
    Upgrading 4.5 or higher to 4.6.3
    The required platform for OpenACS 4.6 is the same as
-      4.5, with the exception of OpenFTS.  OpenACS 4.6 and later require OpenFTS 0.3.2 for full text search on PostGreSQL.  If you have OpenFTS 0.2, you'll need to upgrade.  
    If upgrading from 4.4, you need to manually run acs-kernel/sql/postgres/upgrade-4.4-4.5.sql.  See Bug #632
    1. Make a Backup. Back up the database and file system (see the section called “Manual backup and recovery”).
    2. OPTIONAL: Upgrade OpenFTS. the section called “Upgrading OpenFTS from 0.2 to 0.3.2”
    3. 
+      4.5, with the exception of OpenFTS.  OpenACS 4.6 and later require OpenFTS 0.3.2 for full text search on PostGreSQL.  If you have OpenFTS 0.2, you'll need to upgrade.  
      If upgrading from 4.4, you need to manually run acs-kernel/sql/postgres/upgrade-4.4-4.5.sql.  See Bug #632
      1. Make a Backup. Back up the database and file system (see the section called “Manual backup and recovery”).
      2. OPTIONAL: Upgrade OpenFTS. the section called “Upgrading OpenFTS from 0.2 to 0.3.2”
      3. 
             Stop the server
           
        [root root]# svc -d /service/$OPENACS_SERVICE_NAME
      4. Upgrade the file system. the section called “Upgrading the OpenACS files”
      5. 
             Start the server
           
        [root root]# svc -u /service/$OPENACS_SERVICE_NAME
      6. Use APM to upgrade the database. 
        1. Browse to the package manager, http://yourserver/acs-admin/apm.
        2. Click Install packages.
        3. Select the packages you want to install.  This should
               be everything that says
               upgrade, plus any new
-              packages you want.  It's safest to upgrade the kernel by
+              packages you want.  It's safest to upgrade the kernel by
               itself, and then come back and upgrade the rest of the
               desired packages in a second pass.
        4. On the next screen, click Install Packages
        5. When prompted, restart the server:
          [root root]# restart-aolserver $OPENACS_SERVICE_NAME
        6. Wait a minute, then browse to the package manager, http://yourserver/acs-admin/apm.
        7. Check that the kernel upgrade worked by clicking All and making sure that acs-kernel version is 5.9.0.
      7. Rollback. If anything goes wrong, roll back to the backup snapshot.
    Prev Home Next
    Overview Up Upgrading OpenACS 4.6.3 to 5.0
    docs@openacs.org
    View comments on this page at openacs.org
    
Index: openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.adp,v
diff -u -N -r1.1.2.4 -r1.1.2.5
--- openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.adp	9 Jun 2016 13:03:12 -0000	1.1.2.4
+++ openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.adp	23 Jun 2016 08:32:46 -0000	1.1.2.5
@@ -11,12 +11,12 @@
 
    
 Upgrading OpenACS 4.6.3 to 5.0
    See also these forum posts: Forum OpenACS Development: 4.6.3 upgrade to 5-HEAD: final
-results, OpenACS 5.0 Upgrade Experiences.
    There are a few things you might want to do once you've
+results, OpenACS 5.0 Upgrade Experiences.
    There are a few things you might want to do once you've
 upgraded. First, the acs-kernel parameters need to be set to allow
 HREF and IMG tags, if you want users who can edit HTML to be able
 to insert HREF and IMG tags. Also, you might need to set the
Index: openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.html,v
diff -u -N -r1.17.2.1 -r1.17.2.2
--- openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.html	9 Jun 2016 08:44:50 -0000	1.17.2.1
+++ openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.html	23 Jun 2016 08:32:46 -0000	1.17.2.2
@@ -4,7 +4,7 @@
             how to upgrade an Oracle installation from OpenACS 4.6.3 to 5
             .
             
  • PostGreSQL. You must use PostGreSQL 7.3.x or newer to upgrade OpenACS beyond 4.6.3.  See Upgrade PostGreSQL to 7.3; Table 2.2, “Version Compatibility Matrix”
-            
    1. Back up the database and file system.
    2. Upgrade the file system for packages/acs-kernel. the section called “Upgrading the OpenACS files”
    3. Upgrade the kernel manually. (There is a script to do most of the rest: /contrib/misc/upgrade_4.6_to_5.0.sh on HEAD).  You'll still have to do a lot of stuff manually, but automated trial and error is much more fun.)
      [root root]# su - $OPENACS_SERVICE_NAME
+            
      1. Back up the database and file system.
      2. Upgrade the file system for packages/acs-kernel. the section called “Upgrading the OpenACS files”
      3. Upgrade the kernel manually. (There is a script to do most of the rest: /contrib/misc/upgrade_4.6_to_5.0.sh on HEAD).  You'll still have to do a lot of stuff manually, but automated trial and error is much more fun.)
        [root root]# su - $OPENACS_SERVICE_NAME
 [$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/ $OPENACS_SERVICE_NAME/packages/acs-kernel/sql/postgresql/upgrade
        
                 Manually execute each of the upgrade scripts in sequence, either from within psql or from the command line with commands such as psql -f upgrade-4.6.3-4.6.4.sql  $OPENACS_SERVICE_NAME.  Run the scripts in this order (order is tentative, not verified):
               
        psql -f upgrade-4.6.3-4.6.4.sql $OPENACS_SERVICE_NAME
@@ -22,7 +22,7 @@
 psql -f upgrade-5.0.0b2-5.0.0b3.sql $OPENACS_SERVICE_NAME
 psql -f upgrade-5.0.0b3-5.0.0b4.sql $OPENACS_SERVICE_NAME
      4. Upgrade ACS Service Contracts manually:
        [$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/ $OPENACS_SERVICE_NAME/packages/acs-service-contracts/sql/postgresql/upgrade
 psql -f upgrade-4.7d2-4.7d3.sql $OPENACS_SERVICE_NAME
-
      5. Load acs-authentication data model.
        psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/openacs-5/packages/acs-authentication/sql/postgresql/acs-authentication-create.sql $OPENACS_SERVICE_NAME
      6. Load acs-lang data model.
        psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-lang/sql/postgresql/acs-lang-create.sql $OPENACS_SERVICE_NAME
      7. (This step may overlap with the two previous steps, but I think it's harmless?) Create a file which will be executed on startup which takes care of a few issues with authentication and internationalization: create $OPENACS_SERVICE_NAME/tcl/zzz-postload.tcl containing:
        if {![apm_package_installed_p acs-lang]} {
+
      8. Load acs-authentication data model.
        psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/openacs-5/packages/acs-authentication/sql/postgresql/acs-authentication-create.sql $OPENACS_SERVICE_NAME
      9. Load acs-lang data model.
        psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-lang/sql/postgresql/acs-lang-create.sql $OPENACS_SERVICE_NAME
      10. (This step may overlap with the two previous steps, but I think it's harmless?) Create a file which will be executed on startup which takes care of a few issues with authentication and internationalization: create $OPENACS_SERVICE_NAME/tcl/zzz-postload.tcl containing:
        if {![apm_package_installed_p acs-lang]} {
 apm_package_install -enable -mount_path acs-lang $::acs::rootdir/packages/acs-lang/acs-lang.info
 lang::catalog::import -locales [list "en_US"]
 }
@@ -40,7 +40,7 @@
 }
      11. If you can login, visit /acs-admin/apm and upgrade acs-kernel and acs-service-contract and uncheck the data model scripts. Restart. If everything is still working, make another backup of the database.
               
      12. Upgrade other packages via the APM
      
           See also these forum posts: Forum OpenACS Development: 4.6.3 upgrade to 5-HEAD: final results, OpenACS 5.0 Upgrade Experiences.
      
-          There are a few things you might want to do once you've
+          There are a few things you might want to do once you've
           upgraded. First, the acs-kernel parameters need to be set to
           allow HREF and IMG tags, if you want users who can edit HTML
           to be able to insert HREF and IMG tags. Also, you might need
Index: openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.adp,v
diff -u -N -r1.1.2.4 -r1.1.2.5
--- openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.adp	9 Jun 2016 13:03:12 -0000	1.1.2.4
+++ openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.adp	23 Jun 2016 08:32:46 -0000	1.1.2.5
@@ -13,30 +13,30 @@
 installation
      • 
 
    • 
 
      
-Upgrading a stock site. If you have no custom
-code, and your site is not in a CVS repository, upgrade with these
-steps:
        
-
      1. Go to /acs-admin/install/ and click "Upgrade Your System" in
-"Install from OpenACS Repository"
      2. Select all of the packages you want to upgrade and proceed
      3. After upgrade is complete, restart the server as indicated.
      4. If you are using locales other than en_US, go to acs-lang/admin
-and "Import all Messages" to load the new translated messages. Your
-local translations, if any, will take precedence over imported
-translations.
        5. 
+Upgrading a stock site. If you have
+no custom code, and your site is not in a CVS repository, upgrade
+with these steps:
          
+
        1. Go to /acs-admin/install/ and click "Upgrade Your
+System" in "Install from OpenACS Repository"
        2. Select all of the packages you want to upgrade and proceed
        3. After upgrade is complete, restart the server as indicated.
        4. If you are using locales other than en_US, go to acs-lang/admin
+and "Import all Messages" to load the new translated
+messages. Your local translations, if any, will take precedence
+over imported translations.
          5. 
 
        
 
      5. 
 
        
-Upgrading a Custom or CVS site. If you have
-custom code, and your site is in a CVS repository, upgrade with
-these steps:
          
+Upgrading a Custom or CVS site. If
+you have custom code, and your site is in a CVS repository, upgrade
+with these steps:
            
 
          1. 
 Upgrade the file system for all packages in
 use. the section called
 “Upgrading the OpenACS
 files”
-
          2. Go to /acs-admin/install/ and click "Upgrade Your System" in
-"Install from local file system"
          3. Select all of the packages you want to upgrade and proceed
          4. After upgrade is complete, restart the server as indicated.
          5. If you are using locales other than en_US, go to acs-lang/admin
-and "Import all Messages" to load the new translated messages. Your
-local translations, if any, will take precedence over imported
-translations.
            6. 
+
          6. Go to /acs-admin/install/ and click "Upgrade Your
+System" in "Install from local file system"
          7. Select all of the packages you want to upgrade and proceed
          8. After upgrade is complete, restart the server as indicated.
          9. If you are using locales other than en_US, go to acs-lang/admin
+and "Import all Messages" to load the new translated
+messages. Your local translations, if any, will take precedence
+over imported translations.
            10. 
 
          
 
 
    
Index: openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.adp,v
diff -u -N -r1.1.2.11 -r1.1.2.12
--- openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.adp	21 Jun 2016 07:44:36 -0000	1.1.2.11
+++ openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.adp	23 Jun 2016 08:32:46 -0000	1.1.2.12
@@ -31,10 +31,10 @@
 
  • 
 
    
 Upgrading files for a site which is not in a CVS
-repository. Unpack the tarball into a new directory
-and copy its contents on top of your working directory. Or just
-'install software', select remote repository, and upgrade your
-files from there.
    +repository. Unpack the tarball into a new
+directory and copy its contents on top of your working directory.
+Or just 'install software', select remote repository, and
+upgrade your files from there.
     [root root]# su - $OPENACS_SERVICE_NAME
 
 [$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver
@@ -56,25 +56,26 @@
 version, without overriding your own local customizations.
    This diagram explains the basic idea. However, the labels are
 incorrect. Step 1(a) has been removed, and Step 1(b) should be
 labelled Step 1.
    
-
    Figure 5.2. Upgrading a
-local CVS repository
    Upgrading a local CVS repository
    
+
    Figure 5.2. Upgrading a local CVS
+repository
    Upgrading a local CVS repository
    
 

      
 
    • 
 
      
-Step 0: Set up a working CVS checkout. To get
-your OpenACS code into your local CVS repository, you will set up a
-working CVS checkout of OpenACS. When you want to update your site,
-you'll update the working CVS checkout, import those changes into
-your local CVS checkout, create a temporary CVS checkout to merge
-your local changes, fix any conflicts, commit your changes, and
-then update your site. It sounds complicated, but it's not too bad,
-and it is the best way to work around CVS's limitations.
      This part describes how to set up your working CVS checkout.
-Once it is set up, you'll be able to update any packages using the
-existing working CVS checkout. We use one dedicated directory for
-each branch of OpenACS - if you are using OpenACS 5.1,x, you will
-need a 5.1 checkout. That will be good for 5.1, 5.11, 5.12, and so
-on. But when you want to upgrade to OpenACS 5.2, you'll need to
-check out another branch.
      The openacs-5-1-compat tag identifies the
+Step 0: Set up a working CVS
+checkout. To get your OpenACS code into your
+local CVS repository, you will set up a working CVS checkout of
+OpenACS. When you want to update your site, you'll update the
+working CVS checkout, import those changes into your local CVS
+checkout, create a temporary CVS checkout to merge your local
+changes, fix any conflicts, commit your changes, and then update
+your site. It sounds complicated, but it's not too bad, and it
+is the best way to work around CVS's limitations.
      This part describes how to set up your working CVS checkout.
+Once it is set up, you'll be able to update any packages using
+the existing working CVS checkout. We use one dedicated directory
+for each branch of OpenACS - if you are using OpenACS 5.1,x, you
+will need a 5.1 checkout. That will be good for 5.1, 5.11, 5.12,
+and so on. But when you want to upgrade to OpenACS 5.2, you'll
+need to check out another branch.
      The openacs-5-1-compat tag identifies the
 latest released version of OpenACS 5.1 (ie, 5.1.3 or 5.1.4) and the
 latest compatible version of each package. Each minor release of
 OpenACS since 5.0 has this tagging structure. For example, OpenACS
@@ -90,17 +91,18 @@
 [$OPENACS_SERVICE_NAME aolserver]$ cd ../..
 [$OPENACS_SERVICE_NAME aolserver]$ mv openacs-4 openacs-5-1
 
-
    Make sure your working CVS checkout doesn't have the entire CVS
-tree from OpenACS. A good way to check this is if it has a contrib
-directory. If it does, you probably checked out the entire tree.
-You might want to start over, remove your working CVS checkout, and
-try again.
    
+
    Make sure your working CVS checkout doesn't have the entire
+CVS tree from OpenACS. A good way to check this is if it has a
+contrib directory. If it does, you probably checked out the entire
+tree. You might want to start over, remove your working CVS
+checkout, and try again.
    
 
  • 
-
    Step 1: Import new OpenACS code. 
      
+
      Step 1: Import new OpenACS
+code. 
        
 
      • 
 
        
-Update CVS. Update your local CVS working
-checkout (unless you just set it up).
        +Update CVS. Update your local CVS
+working checkout (unless you just set it up).
         [root root]# su - $OPENACS_SERVICE_NAME
 
 [$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/openacs-5-1
@@ -110,8 +112,8 @@
 
      • 
 
        
 Update a single package via cvs working
-checkout. You can add or upgrade a single package
-at a time, if you already have a cvs working directory.
        +checkout. You can add or upgrade a single
+package at a time, if you already have a cvs working directory.
         [root root]# su - $OPENACS_SERVICE_NAME
 
 [$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/packages/openacs-5-1
@@ -124,10 +126,10 @@
 
      
 
    • 
 
      
-Step 2: Merge New OpenACS code. Now that you
-have a local copy of the new OpenACS code, you need to import it
-into your local CVS repository and resolve any conflicts that
-occur.
      Import the new files into your cvs repository; where they match
+Step 2: Merge New OpenACS code. Now
+that you have a local copy of the new OpenACS code, you need to
+import it into your local CVS repository and resolve any conflicts
+that occur.
      Import the new files into your cvs repository; where they match
 existing files, they will become the new version of the file.
       [$OPENACS_SERVICE_NAME openacs-5-1]$  cd /var/lib/aolserver/openacs-5-1
 
@@ -147,7 +149,7 @@
 
    Create a new directory as temporary working space to reconcile
 conflicts between the new files and your current work. The example
 uses the cvs keyword yesterday, making the assumption that you
-haven't checked in new code to your local tree in the last day.
+haven't checked in new code to your local tree in the last day.
 This section should be improved to use tags instead of the keyword
 yesterday!
     [$OPENACS_SERVICE_NAME openacs-5.1]$  cd /var/lib/aolserver
@@ -157,23 +159,23 @@
 (CVS feedback here)
 
    The file /var/tmp/openacs-upgrade/cvs.txt contains the results
 of the upgrade. If you changed files that are part of the OpenACS
-tarball and those changes conflict, you'll have to manually
+tarball and those changes conflict, you'll have to manually
 reconcile them. Use the emacs command M-x sort-lines (you may have to click
 Ctrl-space at the beginning of the file, and go to the end, and
 then try M-x sort-lines) and then, for each line that starts with a
 C, open that file and manually resolve the conflict by deleting the
-excess lines. When you're finished, or if there aren't any
-conflicts, save and exit.
    Once you've fixed any conflicts, commit the new code to your
+excess lines. When you're finished, or if there aren't any
+conflicts, save and exit.
    Once you've fixed any conflicts, commit the new code to your
 local tree.
     [$OPENACS_SERVICE_NAME tmp]$ cd $OPENACS_SERVICE_NAME-upgrade
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME-upgrade]$ cvs commit -m "Upgraded to 5.1"
 
    
 
  • 
 
    
 Step 3: Upgrade your local staging
-site. Update your working tree with the new files.
-The CVS flags ensure that new directories are created and pruned
-directories destroyed.
    +site. Update your working tree with the new
+files. The CVS flags ensure that new directories are created and
+pruned directories destroyed.
     [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME-upgrade]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME
 
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs up -Pd
@@ -203,9 +205,10 @@
 
    Import the new code (for example, OpenACS 5.0.4,
 openacs-5-0-compat versions of ETP, blogger, and other
 applications) into a "vendor branch" of the $OPENACS_SERVICE_NAME CVS tree, as
-described in "Upgrading a local CVS repository", step 1, above. As
-soon as we do this, any cvs update command on production might
-bring new code onto the production site, which would be bad.
    Do step 2 above (merging conflicts in a $OPENACS_SERVICE_NAME-upgrade working
+described in "Upgrading a local CVS repository", step 1,
+above. As soon as we do this, any cvs update command on production
+might bring new code onto the production site, which would be
+bad.
    Do step 2 above (merging conflicts in a $OPENACS_SERVICE_NAME-upgrade working
 tree).
    
 
  • Manually resolve any conflicts in the working upgrade tree
  • Use the upgrade script and a recent backup of the production
 database, to ake a new upgraded database called $OPENACS_SERVICE_NAME-upgrade. Now we
Index: openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html,v
diff -u -N -r1.27.2.10 -r1.27.2.11
--- openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html	21 Jun 2016 07:44:36 -0000	1.27.2.10
+++ openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html	23 Jun 2016 08:32:46 -0000	1.27.2.11
@@ -34,19 +34,19 @@
         labels are incorrect. Step 1(a) has been removed, and Step
         1(b) should be labelled Step 1.
    Figure 5.2. Upgrading a local CVS repository
    Upgrading a local CVS repository

    • Step 0: Set up a working CVS checkout. To get your OpenACS code into your local CVS
                 repository, you will set up a working CVS checkout of
-                OpenACS. When you want to update your site, you'll
+                OpenACS. When you want to update your site, you'll
                 update the working CVS checkout, import those changes
                 into your local CVS checkout, create a temporary CVS
                 checkout to merge your local changes, fix any
                 conflicts, commit your changes, and then update your
-                site. It sounds complicated, but it's not too bad, and
+                site. It sounds complicated, but it's not too bad, and
                 it is the best way to work around CVS's limitations.
      This part describes how to set up your working CVS
-        checkout. Once it is set up, you'll be able to update any
+        checkout. Once it is set up, you'll be able to update any
         packages using the existing working CVS checkout. We use one
         dedicated directory for each branch of OpenACS - if you are
         using OpenACS 5.1,x, you will need a 5.1 checkout. That will
         be good for 5.1, 5.11, 5.12, and so on. But when you want to
-        upgrade to OpenACS 5.2, you'll need to check out another
+        upgrade to OpenACS 5.2, you'll need to check out another
         branch.
      The openacs-5-1-compat tag identifies the latest released version of OpenACS 5.1 (ie, 5.1.3 or 5.1.4) and the latest compatible version of each package.  Each minor release of OpenACS since 5.0 has this tagging structure.  For example, OpenACS 5.1.x has openacs-5-1-compat.
      You will want to separately check out all the
                 packages you are using.
               
      [root root]# su - $OPENACS_SERVICE_NAME
@@ -55,7 +55,7 @@
 [$OPENACS_SERVICE_NAME aolserver]$ cd openacs-4/packages
 [$OPENACS_SERVICE_NAME aolserver]$ cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r openacs-5-1-compat packagename packagename2...
 [$OPENACS_SERVICE_NAME aolserver]$ cd ../..
-[$OPENACS_SERVICE_NAME aolserver]$ mv openacs-4 openacs-5-1
      Make sure your working CVS checkout doesn't have
+[$OPENACS_SERVICE_NAME aolserver]$ mv openacs-4 openacs-5-1
      Make sure your working CVS checkout doesn't have
               the entire CVS tree from OpenACS. A good way to check
               this is if it has a contrib directory. If it does, you
               probably checked out the entire tree. You might want to
@@ -74,7 +74,7 @@
 [$OPENACS_SERVICE_NAME myfirstpackage]$ cvs -d /var/lib/cvs/ import -m "importing package" $OPENACS_SERVICE_NAME/packages/myfirstpackage OpenACS openacs-5-1
    Create a new directory as temporary working space to
             reconcile conflicts between the new files and your current
             work.  The example uses the cvs keyword yesterday, making
-            the assumption that you haven't checked in new code to
+            the assumption that you haven't checked in new code to
             your local tree in the last day. This section should be
             improved to use tags instead of the keyword yesterday!
    [$OPENACS_SERVICE_NAME openacs-5.1]$  cd /var/lib/aolserver
 [$OPENACS_SERVICE_NAME tmp]$ rm -rf $OPENACS_SERVICE_NAME-upgrade
@@ -83,10 +83,10 @@
 (CVS feedback here)
    The file /var/tmp/openacs-upgrade/cvs.txt contains the
             results of the upgrade.  If you changed files that are
             part of the OpenACS tarball and those changes conflict,
-            you'll have to manually reconcile them.  Use the emacs
+            you'll have to manually reconcile them.  Use the emacs
             command M-x sort-lines
             (you may have to click Ctrl-space at the beginning of the
-            file, and go to the end, and then try M-x sort-lines) and then, for each line that starts with a C, open that file and manually resolve the conflict by deleting the excess lines.  When you're finished, or if there aren't any conflicts, save and exit.
    Once you've fixed any conflicts, commit the new code
+            file, and go to the end, and then try M-x sort-lines) and then, for each line that starts with a C, open that file and manually resolve the conflict by deleting the excess lines.  When you're finished, or if there aren't any conflicts, save and exit.
    Once you've fixed any conflicts, commit the new code
             to your local tree.  
    [$OPENACS_SERVICE_NAME tmp]$ cd $OPENACS_SERVICE_NAME-upgrade
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME-upgrade]$ cvs commit -m "Upgraded to 5.1"
  • Step 3: Upgrade your local staging site. Update your working tree with the new files.  The CVS flags ensure that new directories are created and pruned directories destroyed.
    [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME-upgrade]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs up -Pd
Index: openacs-4/packages/acs-core-docs/www/upgrade-overview.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-overview.adp,v
diff -u -N -r1.1.2.11 -r1.1.2.12
--- openacs-4/packages/acs-core-docs/www/upgrade-overview.adp	21 Jun 2016 07:44:36 -0000	1.1.2.11
+++ openacs-4/packages/acs-core-docs/www/upgrade-overview.adp	23 Jun 2016 08:32:46 -0000	1.1.2.12
@@ -12,26 +12,26 @@
 Overview
    Starting with Version 4.5, all OpenACS core packages support
 automatic upgrade. That means that, if you have OpenACS 4.5 or
 better, you should always be able to upgrade all of your core
-packages automatically. If you haven't changed anything, no manual
-intervention should be required. If you are running OpenACS prior
-to 4.5, upgrading will require manual effort.
    If all of these conditions are true:
      
+packages automatically. If you haven't changed anything, no
+manual intervention should be required. If you are running OpenACS
+prior to 4.5, upgrading will require manual effort.
      If all of these conditions are true:
        
 
      • Your OpenACS Core is 5.0.0 or later
      • You do not keep your OpenACS site in a local CVS repository
      • You do not have any custom code
        • 
 
      then you can upgrade automatically using the automated installer
 in the OpenACS Package Manager (APM), and you can probably skip the
 rest of this chapter. To upgrade directly from the OpenACS
 repository using the APM:
        
-
      1. Browse to the Installer.
      2. Click install or upgrade under "Install from OpenACS Repository"
-and select the packages to install or upgrade.
      3. The APM will download the requested packages from OpenACS.org,
+
      4. Browse to the Installer.
      5. Click install or upgrade under "Install from OpenACS
+Repository" and select the packages to install or upgrade.
      6. The APM will download the requested packages from OpenACS.org,
 install the files on your hard drive, run any appropriate database
 upgrade scripts, and prompt you to restart the server. After
 restarting the server again, the upgrade is complete.
        7. 
 
      
-
      Figure 5.1. Upgrading
-with the APM
      Upgrading with the APM
      
-

      It's always a good idea to precede an upgrade attempt with a
+
      Figure 5.1. Upgrading with the
+APM
      Upgrading with the APM
      
+

    It's always a good idea to precede an upgrade attempt with a
 snapshot backup.
    
-
    Table 5.1. Assumptions
-in this section
    
+
    Table 5.1. Assumptions in this
+section
    
Index: openacs-4/packages/acs-core-docs/www/upgrade-overview.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-overview.html,v
diff -u -N -r1.27.2.10 -r1.27.2.11
--- openacs-4/packages/acs-core-docs/www/upgrade-overview.html	21 Jun 2016 07:44:36 -0000	1.27.2.10
+++ openacs-4/packages/acs-core-docs/www/upgrade-overview.html	23 Jun 2016 08:32:46 -0000	1.27.2.11
@@ -2,6 +2,6 @@
 Overview
    Alex logo
    
 
 
 
    Prev Chapter 5. Upgrading Next
    Overview
    Starting with Version 4.5, all OpenACS core packages support
     automatic upgrade.  That means that, if you have OpenACS 4.5
     or better, you should always be able to upgrade all of your core
-    packages automatically.  If you haven't changed anything, no
+    packages automatically.  If you haven't changed anything, no
     manual intervention should be required.  If you are running
-    OpenACS prior to 4.5, upgrading will require manual effort.
    If all of these conditions are true:
    • Your OpenACS Core is 5.0.0 or later
    • You do not keep your OpenACS site in a local CVS repository
    • You do not have any custom code
    then you can upgrade automatically using the automated installer in the OpenACS Package Manager (APM), and you can probably skip the rest of this chapter.  To upgrade directly from the OpenACS repository using the APM:
    1. Browse to the Installer.
    2. Click install or upgrade under "Install from OpenACS Repository" and select the packages to install or upgrade.
    3. The APM will download the requested packages from OpenACS.org, install the files on your hard drive, run any appropriate database upgrade scripts, and prompt you to restart the server.  After restarting the server again, the upgrade is complete.
    Figure 5.1. Upgrading with the APM
    Upgrading with the APM

    It's always a good idea to precede an upgrade attempt with a snapshot backup.
    Table 5.1. Assumptions in this section
    name of OpenACS user$OPENACS_SERVICE_NAME
    OpenACS server name$OPENACS_SERVICE_NAME
    Root of OpenACS file tree/var/lib/aolserver/$OPENACS_SERVICE_NAME
    Database backup directory/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup

    Prev Home Next
    Chapter 5. Upgrading Up Upgrading 4.5 or higher to 4.6.3
    docs@openacs.org
    View comments on this page at openacs.org
    
+    OpenACS prior to 4.5, upgrading will require manual effort.
    If all of these conditions are true:
    • Your OpenACS Core is 5.0.0 or later
    • You do not keep your OpenACS site in a local CVS repository
    • You do not have any custom code
    then you can upgrade automatically using the automated installer in the OpenACS Package Manager (APM), and you can probably skip the rest of this chapter.  To upgrade directly from the OpenACS repository using the APM:
    1. Browse to the Installer.
    2. Click install or upgrade under "Install from OpenACS Repository" and select the packages to install or upgrade.
    3. The APM will download the requested packages from OpenACS.org, install the files on your hard drive, run any appropriate database upgrade scripts, and prompt you to restart the server.  After restarting the server again, the upgrade is complete.
    Figure 5.1. Upgrading with the APM
    Upgrading with the APM

    It's always a good idea to precede an upgrade attempt with a snapshot backup.
    Table 5.1. Assumptions in this section
    name of OpenACS user$OPENACS_SERVICE_NAME
    OpenACS server name$OPENACS_SERVICE_NAME
    Root of OpenACS file tree/var/lib/aolserver/$OPENACS_SERVICE_NAME
    Database backup directory/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup

    Prev Home Next
    Chapter 5. Upgrading Up Upgrading 4.5 or higher to 4.6.3
    docs@openacs.org
    View comments on this page at openacs.org
    
Index: openacs-4/packages/acs-core-docs/www/upgrade-supporting.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-supporting.adp,v
diff -u -N -r1.1.2.2 -r1.1.2.3
--- openacs-4/packages/acs-core-docs/www/upgrade-supporting.adp	9 Jun 2016 13:03:12 -0000	1.1.2.2
+++ openacs-4/packages/acs-core-docs/www/upgrade-supporting.adp	23 Jun 2016 08:32:46 -0000	1.1.2.3
@@ -68,9 +68,10 @@
 
    
 
  • 
 
    
-OPTIONAL: Install the new OpenFTS Engine. If
-you want to upgrade the OpenFTS Engine, do these steps. (You must
-have already upgraded the OpenFTS driver to 0.3.2.)
      
+OPTIONAL: Install the new OpenFTS
+Engine. If you want to upgrade the OpenFTS
+Engine, do these steps. (You must have already upgraded the OpenFTS
+driver to 0.3.2.)
        
 
      1. Browse to http://yourserver/admin/site-map
 
      2. On the openfts line, click
 on set parameters.
      3. Change the value of openfts_tcl_src_path from /usr/local/src/Search-OpenFTS-tcl-0.2/ to
@@ -96,8 +97,8 @@
 creation and at function calling, so they still match. But if you
 use a database created in 7.2 in 7.3, the function names in the
 database remain truncated but the function calls are not, and so
-they don't match. Also some functions use casting commands that no
-longer work in 7.3 and these functions must be recreated.
        To upgrade an OpenACS site from PostGreSQL 7.2 to 7.3, first
+they don't match. Also some functions use casting commands that
+no longer work in 7.3 and these functions must be recreated.
        To upgrade an OpenACS site from PostGreSQL 7.2 to 7.3, first
 upgrade the kernel to 4.6.3. Then, dump the database, run the
 upgrade script /var/lib/aolserver/$OPENACS_SERVICE_NAME/bin/pg_7.2to7.3_upgrade_helper.pl
 on the dump file, and reply the dump. See Forum OpenACS Q&A: PG 7.2->7.3 upgrade gotcha?.
@@ -128,15 +129,15 @@
 installation guide. Keep in mind that your installation location is
 different, and your startup script (/etc/init.d/postgres73 should
 be named differently. You might even need to edit that file to make
-the paths correct). You'll also need to add export PGPORT=5434 to the .bashrc and/or
+the paths correct). You'll also need to add export PGPORT=5434 to the .bashrc and/or
 .bash_profile for the postgres73 user.
      4. Install PostgreSQL 7.3.x. Note that you PostgreSQL must listen
-on a different port in order to work correctly, so you'll need to
-edit the configuration file
+on a different port in order to work correctly, so you'll need
+to edit the configuration file
 (/usr/local/pgsql73/data/postgresql.conf) and change the port (to
 5433, say). create a second postgres user to differentiate between
-the two postgres installs. When you do ./configure, you'll need to
-include --prefix=$HOME to ensure that it is installed in the
-postgres73 user's home directory.
      5. Change the path in $OPENACS_SERVICE_NAME's .bashrc or
+the two postgres installs. When you do ./configure, you'll need
+to include --prefix=$HOME to ensure that it is installed in the
+postgres73 user's home directory.
      6. Change the path in $OPENACS_SERVICE_NAME's .bashrc or
 .bash_profile (or both) files to reflect the new postgres73 user
 directory. Also add in the PGPORT.
      7. Restore the database from dump as per the recovery
 instructions.
        8. 
Index: openacs-4/packages/acs-core-docs/www/upgrade-supporting.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-supporting.html,v
diff -u -N -r1.20.2.1 -r1.20.2.2
--- openacs-4/packages/acs-core-docs/www/upgrade-supporting.html	9 Jun 2016 08:44:50 -0000	1.20.2.1
+++ openacs-4/packages/acs-core-docs/www/upgrade-supporting.html	23 Jun 2016 08:32:46 -0000	1.20.2.2
@@ -40,7 +40,7 @@
       function creation and at function calling, so they still match.
       But if you use a database created in 7.2 in 7.3, the function
       names in the database remain truncated but the function calls
-      are not, and so they don't match.  Also some functions use
+      are not, and so they don't match.  Also some functions use
       casting commands that no longer work in 7.3 and these functions
       must be recreated.
        
       To upgrade an OpenACS site from PostGreSQL 7.2 to 7.3, first upgrade the kernel to 4.6.3.  Then, dump the database, run the upgrade script /var/lib/aolserver/$OPENACS_SERVICE_NAME/bin/pg_7.2to7.3_upgrade_helper.pl on the dump file, and reply the dump.  See Forum OpenACS Q&A: PG 7.2->7.3 upgrade gotcha?.  Example:
        1. Back up the database as per PostgreSQL.
        2. Run the upgrade script on the backup file.
          [root root]# su - $OPENACS_SERVICE_NAME
@@ -62,18 +62,18 @@
           installation location is different, and your startup script
           (/etc/init.d/postgres73 should be named differently. You
           might even need to edit that file to make the paths
-          correct). You'll also need to add export
+          correct). You'll also need to add export
           PGPORT=5434 to the .bashrc and/or
           .bash_profile for the postgres73 user.
           
        3. Install PostgreSQL 7.3.x. Note that you PostgreSQL
           must listen on a different port in order to work
-          correctly, so you'll need to edit the configuration file
+          correctly, so you'll need to edit the configuration file
           (/usr/local/pgsql73/data/postgresql.conf) and
           change the port (to 5433, say). create a second postgres
           user to differentiate between the two postgres
-          installs. When you do ./configure, you'll need to include
+          installs. When you do ./configure, you'll need to include
           --prefix=$HOME to ensure that it is installed in the
-          postgres73 user's home directory.
        4. Change the path in
+          postgres73 user's home directory.
        5. Change the path in
           $OPENACS_SERVICE_NAME's .bashrc or
           .bash_profile (or both) files to reflect the new postgres73
           user directory. Also add in the PGPORT.
        6. Restore the database from dump as per the recovery instructions.
    Prev Home Next
    Upgrading the OpenACS files Up Chapter 6. Production Environments
    docs@openacs.org
    View comments on this page at openacs.org
    
Index: openacs-4/packages/acs-core-docs/www/upgrade.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade.adp,v
diff -u -N -r1.1.2.3 -r1.1.2.4
--- openacs-4/packages/acs-core-docs/www/upgrade.adp	9 Jun 2016 13:03:12 -0000	1.1.2.3
+++ openacs-4/packages/acs-core-docs/www/upgrade.adp	23 Jun 2016 08:32:46 -0000	1.1.2.4
@@ -5,7 +5,7 @@
 
 		
    
 
    
Index: openacs-4/packages/acs-core-docs/www/upgrade.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade.html,v
diff -u -N -r1.30.2.1 -r1.30.2.2
--- openacs-4/packages/acs-core-docs/www/upgrade.html	9 Jun 2016 08:44:50 -0000	1.30.2.1
+++ openacs-4/packages/acs-core-docs/www/upgrade.html	23 Jun 2016 08:32:46 -0000	1.30.2.2
@@ -1,5 +1,5 @@
 
-Chapter 5. Upgrading
    Alex logo
    Prev Part II. Administrator's Guide Next
    Chapter 5. Upgrading
    Table of Contents
    Overview
    Upgrading 4.5 or higher to 4.6.3
    Upgrading OpenACS 4.6.3 to 5.0
    Upgrading an OpenACS 5.0.0 or greater installation
    Upgrading the OpenACS files
    Upgrading Platform components
    by Joel Aufrecht
    
+Chapter 5. Upgrading
    Alex logo
    Prev Part II. Administrator's Guide Next
    Chapter 5. Upgrading
    Table of Contents
    Overview
    Upgrading 4.5 or higher to 4.6.3
    Upgrading OpenACS 4.6.3 to 5.0
    Upgrading an OpenACS 5.0.0 or greater installation
    Upgrading the OpenACS files
    Upgrading Platform components
    by Joel Aufrecht
    
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
    Prev Home Next
    How Do I? Up Overview
    docs@openacs.org
    View comments on this page at openacs.org
    
Index: openacs-4/packages/acs-core-docs/www/variables.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/variables.adp,v
diff -u -N -r1.1.2.11 -r1.1.2.12
--- openacs-4/packages/acs-core-docs/www/variables.adp	21 Jun 2016 07:44:36 -0000	1.1.2.11
+++ openacs-4/packages/acs-core-docs/www/variables.adp	23 Jun 2016 08:32:46 -0000	1.1.2.12
@@ -19,8 +19,8 @@
 OpenACS documentation staff.
    Starting with OpenACS 5.0 and the introduction of acs-lang, we
 recommend retrieving date/time information from the database in
 ANSI format and then using lc_time_fmt to format it for display.
    
-
    Example 12.1. Getting
-datetime from the database ANSI-style
    +
    Example 12.1. Getting datetime from
+the database ANSI-style
     db_multirow -extend { mydate_pretty } {
     select to_char(mydate, 'YYYY-MM-DD HH24:MI:SS') as mydate_ansi,
           ...
Index: openacs-4/packages/acs-core-docs/www/variables.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/variables.html,v
diff -u -N -r1.30.2.10 -r1.30.2.11
--- openacs-4/packages/acs-core-docs/www/variables.html	21 Jun 2016 07:44:36 -0000	1.30.2.10
+++ openacs-4/packages/acs-core-docs/www/variables.html	23 Jun 2016 08:32:46 -0000	1.30.2.11
@@ -4,7 +4,7 @@
           by OpenACS documentation staff.
         
    Starting with OpenACS 5.0 and the introduction of acs-lang,
     we recommend retrieving date/time information from the database in
-    ANSI format and then using lc_time_fmt to format it for display.
    Example 12.1. Getting datetime from the database ANSI-style
    db_multirow -extend { mydate_pretty } {
+    ANSI format and then using lc_time_fmt to format it for display.
    Example 12.1. Getting datetime from the database ANSI-style
    db_multirow -extend { mydate_pretty } {
     select to_char(mydate, 'YYYY-MM-DD HH24:MI:SS') as mydate_ansi,
           ...
     ...
Index: openacs-4/packages/acs-core-docs/www/files/dotlrn-style-2.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/files/dotlrn-style-2.adp,v
diff -u -N -r1.1.2.1 -r1.1.2.2
--- openacs-4/packages/acs-core-docs/www/files/dotlrn-style-2.adp	23 Sep 2015 11:55:07 -0000	1.1.2.1
+++ openacs-4/packages/acs-core-docs/www/files/dotlrn-style-2.adp	23 Jun 2016 08:32:46 -0000	1.1.2.2
@@ -33,7 +33,7 @@
 
    
 
    Latest News
    MBA 101
      
 
    • 
-Here's what we have to say
      Posted by Anders Pollas on May 21 2004
      
+Here's what we have to say
      Posted by Anders Pollas on May 21 2004
      
 
    • 
 Another subject
      Posted by Anders Pollas on May 17 2004
      
 
      • 
Index: openacs-4/packages/acs-core-docs/www/files/dotlrn-style-2.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/files/dotlrn-style-2.html,v
diff -u -N -r1.1 -r1.1.20.1
--- openacs-4/packages/acs-core-docs/www/files/dotlrn-style-2.html	24 Jun 2004 10:44:41 -0000	1.1
+++ openacs-4/packages/acs-core-docs/www/files/dotlrn-style-2.html	23 Jun 2016 08:32:46 -0000	1.1.20.1
@@ -248,7 +248,7 @@
    }
 
 /* IE 6 Hack - see http://css-discuss.incutio.com/?page=StarHtmlHack */
-/* We can't find a way to make drop-shadows work on IE 6 */
+/* We can't find a way to make drop-shadows work on IE 6 */
 * html .portlet-wrap-shadow {
    background: none;
    }
@@ -464,7 +464,7 @@
                    
        
                      
      • 
 
-                       Here's what we have to say
+                       Here's what we have to say
                        
        Posted by Anders Pollas on May 
 21 2004
        
                      
        • 
Index: openacs-4/packages/acs-core-docs/www/files/package-documentation.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/files/package-documentation.xml,v
diff -u -N -r1.2 -r1.2.24.1
--- openacs-4/packages/acs-core-docs/www/files/package-documentation.xml	28 Apr 2003 04:02:44 -0000	1.2
+++ openacs-4/packages/acs-core-docs/www/files/package-documentation.xml	23 Jun 2016 08:32:46 -0000	1.2.24.1
@@ -84,7 +84,7 @@
             
             
               An Author changes a note previously written.
-              Authors can't change other authors' notes.
+              Authors can't change other authors' notes.
             
             
               An Author deletes a note that is no longer
@@ -304,7 +304,7 @@
           
             Use the template system to generate a form for
             editing/creating a note.  If an existing note id was
-            passed in, populate the form fields wih that note's
+            passed in, populate the form fields wih that note's
             values.
 
           
@@ -320,7 +320,7 @@
   
 
   
-    Administrator's guide
+    Administrator's guide
     No administrative tasks are needed or possible
   
   
Index: openacs-4/packages/acs-core-docs/www/unit-testing-guide/index.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/unit-testing-guide/index.adp,v
diff -u -N -r1.1.2.2 -r1.1.2.3
--- openacs-4/packages/acs-core-docs/www/unit-testing-guide/index.adp	9 Jun 2016 13:03:12 -0000	1.1.2.2
+++ openacs-4/packages/acs-core-docs/www/unit-testing-guide/index.adp	23 Jun 2016 08:32:46 -0000	1.1.2.3
@@ -18,16 +18,17 @@
 
        Installation
        
 
 The ACS4 unit testing suite requires several pieces of software to
-function. First, you'll need to install Ant
+function. First, you'll need to install Ant
 . Ant is a build tool
-similar to make. It's used to both build your test cases and run
-the tests themselves. The basic Ant functionality doesn't have
-everything needed to automate the testing, so you'll want to obtain
-David Eison's ForeachFileAntTask.java, available at 
+similar to make. It's used to both build your test cases and
+run the tests themselves. The basic Ant functionality doesn't
+have everything needed to automate the testing, so you'll want
+to obtain David Eison's ForeachFileAntTask.java, available at
+
 http://cvs.arsdigita.com/cgi-bin/cvsweb.pl/acs-java-4/WEB-INF/src/com/arsdigita/build/
 .
 Compile the files and make sure that they are in your classpath.
-
        Once Ant is working, you'll need to obtain copies of both
+
        Once Ant is working, you'll need to obtain copies of both
 JUnit and HTTPUnit. JUnit is a
 framework to automate the running of unit tests, and HTTPUnit
 provides an abstraction layer for HTTP. These are both needed to
@@ -36,50 +37,54 @@
 
        The final step is to replace the server properties in the
 build.xml file so it will know how to talk to your server. You will
 need to give it a base URL, a username, and password for that user.
-are the "JVMARG" lines in the "JUNIT" section. ). In the near
-future, this will be moved out of the subdirectories and either
-into the toplevel build.xml file or into a configuration file.
        
-
        You should now be ready to run the tests. Go to your server's
-"packages" directory and type source ./paths.sh to set
-up your classpath. Now type ant. Ant should find the
-toplevel build.xml file, check that it can see JUnit, compile your
-java files, and finally call Ant on each of the sub-directory
-build.xml files to run the tests. You should be shown a report of
-which tests failed and which succeeded.
        
+are the "JVMARG" lines in the "JUNIT" section.
+). In the near future, this will be moved out of the subdirectories
+and either into the toplevel build.xml file or into a configuration
+file.
        
+
        You should now be ready to run the tests. Go to your
+server's "packages" directory and type source
+./paths.sh to set up your classpath. Now type
+ant. Ant should find the toplevel build.xml file,
+check that it can see JUnit, compile your java files, and finally
+call Ant on each of the sub-directory build.xml files to run the
+tests. You should be shown a report of which tests failed and which
+succeeded.
        
 
        Adding Your Own Unit Tests
        
 
 Adding new test cases is meant to be as easy as possible. Simple
 create a new function in the appropriate .java file, making sure
-that the function name begins with "test". I've adopted a naming
-convention where the function name consists of the word "test", a
-short description of what the function does (with words delimited
-by underscores), followed finally by the QAS testcase ID, if such a
-testcase exists. If you need to test an area of the site that
-requires a user id, you can use the ACSCommon.Login function in the
-com.arsdigita.acs.acsKernel.test package to obtain a Session object
-with appropriate cookies.
+that the function name begins with "test". I've
+adopted a naming convention where the function name consists of the
+word "test", a short description of what the function
+does (with words delimited by underscores), followed finally by the
+QAS testcase ID, if such a testcase exists. If you need to test an
+area of the site that requires a user id, you can use the
+ACSCommon.Login function in the com.arsdigita.acs.acsKernel.test
+package to obtain a Session object with appropriate cookies.
 
        Within the function, a typical unit test involves requesting a
 page, saving the result, checking the HTTP return code, then
 parsing out various strings to check for page functionality. The
-return code should be checked with "assertEquals", and any other
-checks should be performed with "assert". Use of "assert",
-"assertEquals", and exceptions allow JUnit to accurately report
-where a test fails.
        
+return code should be checked with "assertEquals", and
+any other checks should be performed with "assert". Use
+of "assert", "assertEquals", and exceptions
+allow JUnit to accurately report where a test fails.
        
 
        If you need to create a set of tests for a module, the first
 step is to create a directory tree beneath the module directory.
 The current convention is to put all .java files in a
-"/java/src/com/arsdigita/acs/module name/test" directory.
-The module name should be the ACS module name, but with all
-dashes removed and with appropriate capitilization. All .java files
-that you create that contain test cases must have the word Test in
-the filename. All of the classes you create should be in the
-com.arsdigita.acs.module name.test package, and should
-import "com.dallaway.jsptest.*" and "junit.framework.*" (and
-optionally, if needed, com.arsdigita.acs.acsKernel.ACSCommon).
-Next, the public class needs to extend "TestCase", and provide new
-method definitions for "suite()" and the constructor. Typically, in
-the constructor, you should extract the system property
-"system.url" to determine which server to test against.
        
+"/java/src/com/arsdigita/acs/module name/test"
+directory. The module name should be the ACS module name,
+but with all dashes removed and with appropriate capitilization.
+All .java files that you create that contain test cases must have
+the word Test in the filename. All of the classes you create should
+be in the com.arsdigita.acs.module name.test package, and
+should import "com.dallaway.jsptest.*" and
+"junit.framework.*" (and optionally, if needed,
+com.arsdigita.acs.acsKernel.ACSCommon). Next, the public class
+needs to extend "TestCase", and provide new method
+definitions for "suite()" and the constructor. Typically,
+in the constructor, you should extract the system property
+"system.url" to determine which server to test
+against.
        
 
        
 Last updated - 2000-12-19
 
        
Index: openacs-4/packages/acs-core-docs/www/unit-testing-guide/index.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/unit-testing-guide/index.html,v
diff -u -N -r1.1.1.1 -r1.1.1.1.30.1
--- openacs-4/packages/acs-core-docs/www/unit-testing-guide/index.html	13 Mar 2001 22:59:26 -0000	1.1.1.1
+++ openacs-4/packages/acs-core-docs/www/unit-testing-guide/index.html	23 Jun 2016 08:32:46 -0000	1.1.1.1.30.1
@@ -20,17 +20,17 @@
 
        Installation
        
 
 The ACS4 unit testing suite requires several pieces of software to function.
-First, you'll need to install Ant.
-Ant is a build tool similar to make.  It's used to both build your test cases
-and run the tests themselves.  The basic Ant functionality doesn't have 
-everything needed to automate the testing, so you'll want to obtain David 
-Eison's ForeachFileAntTask.java, available
+First, you'll need to install Ant.
+Ant is a build tool similar to make.  It's used to both build your test cases
+and run the tests themselves.  The basic Ant functionality doesn't have 
+everything needed to automate the testing, so you'll want to obtain David 
+Eison's ForeachFileAntTask.java, available
 at http://cvs.arsdigita.com/cgi-bin/cvsweb.pl/acs-java-4/WEB-INF/src/com/arsdigita/build/.  Compile the files and make sure that they
 are in your classpath.
 
 
        
 
-Once Ant is working, you'll need to obtain copies of both
+Once Ant is working, you'll need to obtain copies of both
 JUnit and
 HTTPUnit.  JUnit
 is a framework to automate the running of unit tests, and HTTPUnit provides
@@ -47,7 +47,7 @@
 
 
        
 
-You should now be ready to run the tests.  Go to your server's "packages"
+You should now be ready to run the tests.  Go to your server's "packages"
 directory and type source ./paths.sh to set up your classpath.
 Now type ant.  Ant should find the toplevel build.xml file,
 check that it can see JUnit, compile your java files, and finally call Ant on 
Index: openacs-4/packages/acs-core-docs/www/xml/index.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/index.xml,v
diff -u -N -r1.32 -r1.32.2.1
--- openacs-4/packages/acs-core-docs/www/xml/index.xml	27 Oct 2014 16:39:30 -0000	1.32
+++ openacs-4/packages/acs-core-docs/www/xml/index.xml	23 Jun 2016 08:32:46 -0000	1.32.2.1
@@ -22,7 +22,7 @@
       
         OpenACS (Open Architecture Community System) is an
         advanced toolkit for building scalable, community-oriented
-        web applications.  If you're thinking of building an
+        web applications.  If you're thinking of building an
         enterprise-level web application, OpenACS is a solid,
         scalable framework for building dynamic content driven
         sites.
@@ -77,7 +77,7 @@
         users are actively funding and contributing work back to the
         project.  Formal, consensus driven governance has been
         established (with semi-annual elections) which ensures the
-        project serves the needs of it's constituents.
+        project serves the needs of it's constituents.
       
 
       
@@ -94,7 +94,7 @@
 
 
 
-  Administrator's Guide
+  Administrator's Guide
 
   
     Installation Overview
Index: openacs-4/packages/acs-core-docs/www/xml/releasing-openacs.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/releasing-openacs.xml,v
diff -u -N -r1.22 -r1.22.2.1
--- openacs-4/packages/acs-core-docs/www/xml/releasing-openacs.xml	27 Oct 2014 16:39:30 -0000	1.22
+++ openacs-4/packages/acs-core-docs/www/xml/releasing-openacs.xml	23 Jun 2016 08:32:46 -0000	1.22.2.1
@@ -31,7 +31,7 @@
           Update Version Numbers
           The version numbers in the documentation and in the packages must be updated.  This should only happen after a release candidate is approved.
         
-        .LRN: this must be repeated for .LRN modules (dotlrn-core in the dotlrn cvs tree) and for any modified modules in the .LRN prerequisites (dotlrn-prereq in openacs cvs tree).  My current working model is that I bulk-update .LRN and OpenACS core but that I don't touch dotlrn-prereq modules - I just use the most recent release and it's up to individual package developers to tag and release those packages when they change.  This model is already broken because following it means that dotlrn-prereqs don't get new translations.
+        .LRN: this must be repeated for .LRN modules (dotlrn-core in the dotlrn cvs tree) and for any modified modules in the .LRN prerequisites (dotlrn-prereq in openacs cvs tree).  My current working model is that I bulk-update .LRN and OpenACS core but that I don't touch dotlrn-prereq modules - I just use the most recent release and it's up to individual package developers to tag and release those packages when they change.  This model is already broken because following it means that dotlrn-prereqs don't get new translations.
         
           
             Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/variables.ent with the new version number.
@@ -88,7 +88,7 @@
 
       
       
-        Tag the tree.  If it's a final release of core, move or create the appropriate openacs-major-minor-compat tag.  (Ie, if releasing 5.0.3 final, move the openacs-5-0-compat flag.)
+        Tag the tree.  If it's a final release of core, move or create the appropriate openacs-major-minor-compat tag.  (Ie, if releasing 5.0.3 final, move the openacs-5-0-compat flag.)
         cd /var/tmp/openacs-4
 cvs tag -F openacs-5-0-0a1
 cvs tag -F openacs-5-0-compat
@@ -98,17 +98,17 @@
           When we feature-freeze on HEAD as part of the release process, we are blocking new development.  To avoid this, we branch the code at this point, so that new work can continue on HEAD while the branch is stabilized for release. However, branching means that bug fixes have to be synchronized between HEAD and the branch, and bug fixes tend to be more frequent right at this time.  Therefore, our actual branch point is as late as possible - essentially, we do not branch until and unless new feature work is actively blocked by the feature freeze.  Branching is almost the same as tagging, except for the flag and slightly different tag nomenclature.  To see the list of old branches, cvs status -v somefile.
               cvs tag -b oacs-5-0
         
-        If doing .LRN: Since the .LRN packages aren't all in one
+        If doing .LRN: Since the .LRN packages aren't all in one
           module, we iterate through all of the modules.  Log in first
-          (cvs login) so that you don't have to log in for each
+          (cvs login) so that you don't have to log in for each
           module.
         cd /var/tmp/dotlrn-packages
 for dir in *; do ( cd $dir && cvs tag dotlrn-2-0-2-final ); done
 for dir in *; do ( cd $dir && cvs tag -F openacs-5-0-compat ); done
 
         Note that for the compat tag we use the -F flag which will force the tag to the new version (just in 
           case someone has created the tag already on another version).  Excercise care when doing this since 
-          you don't want to inadvertently move a prior release tag.  Also if the tagging goes horribly wrong 
+          you don't want to inadvertently move a prior release tag.  Also if the tagging goes horribly wrong 
           for some reason you can delete the tag via "cvs tag -d <symbolic_tag>".
       
           
@@ -223,7 +223,7 @@
     
 
     
-      Here is a shell script that automates packaging the tarball (it's a bit out of date with the new steps - I've been doing everything manually or with little throwaway scripts as detailed above until the process is stabilized).
+      Here is a shell script that automates packaging the tarball (it's a bit out of date with the new steps - I've been doing everything manually or with little throwaway scripts as detailed above until the process is stabilized).
     
 
     release script missing
@@ -258,19 +258,19 @@
             	
           
             
-              For each channel, it'll do an anonymous checkout of packges and contrib/packages, then build .apm files for each package in the checkout.
+              For each channel, it'll do an anonymous checkout of packges and contrib/packages, then build .apm files for each package in the checkout.
             
           
           
             
-              The files will be stored on the server's hard drive in the directory specified by the 'repository_dir' variable in the page script, by default "$::acs::rootdir/www/repository/".
+              The files will be stored on the server's hard drive in the directory specified by the 'repository_dir' variable in the page script, by default "$::acs::rootdir/www/repository/".
             
           
         
       
       
         
-          If you're on openacs.org, everything should now be fine. Otherwise, you need to move the entire directory tree to openacs.org:/web/openacs/www/repository, replacing what was already there.
+          If you're on openacs.org, everything should now be fine. Otherwise, you need to move the entire directory tree to openacs.org:/web/openacs/www/repository, replacing what was already there.
         
         This is automated on OpenACS.org by having a dedicated site just for building the repository, invoked with this shell script.  Since the page circumvents security checks for ease of use, the entire site is limited to local requests.  The script is called daily with a cron job.
         #!/bin/sh
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/db-api.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/db-api.xml,v
diff -u -N -r1.13.8.1 -r1.13.8.2
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/db-api.xml	2 Jan 2016 21:55:21 -0000	1.13.8.1
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/db-api.xml	23 Jun 2016 08:32:46 -0000	1.13.8.2
@@ -32,7 +32,7 @@
     
       The OpenACS database API is meant to save developers from making
       common mistakes and to provide a more structured syntax for
-      specifying database operations, including transactions.  Here's
+      specifying database operations, including transactions.  Here's
       an example of the API.
     
     
@@ -212,7 +212,7 @@
     
 
     
-      SQL will not allow a literal to occur where we've put the bind
+      SQL will not allow a literal to occur where we've put the bind
       variables, so the query is syntactically incorrect. You have to
       remember that while the bind variable syntax looks similar to variable
       interpolation in Tcl, It is not the same thing at all.
@@ -498,13 +498,13 @@
     
     Each row also has a column, rownum, automatically
     added and set to the row number, starting with 1. Note that this will
-    override any column in the SQL statement named 'rownum', also if you're
+    override any column in the SQL statement named 'rownum', also if you're
     using the Oracle rownum pseudo-column.
                                                                                                                                                
 
     
     If the -local is passed, the variables defined
-    by db_multirow will be set locally (useful if you're compiling dynamic templates
+    by db_multirow will be set locally (useful if you're compiling dynamic templates
     in a function or similar situations).
     
     
@@ -526,7 +526,7 @@
     
 
     
-    If you're constructing your multirow through multiple queries with the
+    If you're constructing your multirow through multiple queries with the
     same set of columns, but with different rows, you can use the
     -append switch. This causes the rows returned by this query
     to be appended to the rows already in the multirow, instead of starting
@@ -580,7 +580,7 @@
 }
           
 
-          Technically it's equivalent to using a code block on
+          Technically it's equivalent to using a code block on
           the end of your db_multirow.
 
   	
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/form-builder.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/form-builder.xml,v
diff -u -N -r1.9.2.1 -r1.9.2.2
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/form-builder.xml	23 Sep 2015 11:55:07 -0000	1.9.2.1
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/form-builder.xml	23 Jun 2016 08:32:46 -0000	1.9.2.2
@@ -73,7 +73,7 @@
 
     What this will do is set the value for pm_task_id and all the
     other form elements, and resubmit the form. If you then include a
-    block that extends the form, you'll have the opportunity to add in
+    block that extends the form, you'll have the opportunity to add in
     subcategories:
     
         if {[info exists pm_task_id] && $pm_task_id ne ""} {
@@ -82,8 +82,8 @@
     
     
     Note that you will get strange results when you try to set
-    the values for the form. You'll need to set them explicitly in an
-    -on_refresh section of your ad_form. In that section, you'll get
+    the values for the form. You'll need to set them explicitly in an
+    -on_refresh section of your ad_form. In that section, you'll get
     the values from the database, and set the values as so:
 
         db_1row get_task_values { }
@@ -94,12 +94,12 @@
 
   
     Troubleshooting
-    A good way to troubleshoot when you're using ad_form is to
+    A good way to troubleshoot when you're using ad_form is to
     add the following code at the top of the .tcl page (thanks Jerry
     Asher):
 
     
-ns_log notice it's my page!
+ns_log notice it's my page!
 set mypage [ns_getform]
 if {$mypage eq ""} {
     ns_log notice no form was submitted on my page
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml,v
diff -u -N -r1.27.2.2 -r1.27.2.3
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml	11 Jun 2016 08:44:02 -0000	1.27.2.2
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml	23 Jun 2016 08:32:46 -0000	1.27.2.3
@@ -129,7 +129,7 @@
     
 
       Separate Templates for each Locale
-      If the request processor finds a file named filename.locale.adp, where locale matches the user's locale, it will process that file instead of filename.adp.  For example, for a user with locale tl_PH, the file index.tl_PH.adp, if found, will be used instead of index.adp.  The locale-specific file should thus contain text in the language appropriate for that locale.  The code in the page, however, should still be in English.  Message keys are processed normally.
+      If the request processor finds a file named filename.locale.adp, where locale matches the user's locale, it will process that file instead of filename.adp.  For example, for a user with locale tl_PH, the file index.tl_PH.adp, if found, will be used instead of index.adp.  The locale-specific file should thus contain text in the language appropriate for that locale.  The code in the page, however, should still be in English.  Message keys are processed normally.
     
     
     Message Catalogs
@@ -163,7 +163,7 @@
             #package_key.message_key#
           
           
-            The advantage of the short syntax is that it's short. It's
+            The advantage of the short syntax is that it's short. It's
             as simple as inserting the value of a variable.  Example:
             #forum.title#
           
@@ -180,8 +180,8 @@
             The verbose syntax allows you to specify a default text in
             a certain language. This syntax is not recommended
             anymore, but it can be convenient for development, because
-            it still works even if you haven't created the message
-            in the message catalog yet, because what it'll do is
+            it still works even if you haven't created the message
+            in the message catalog yet, because what it'll do is
             create the message key with the default text from the tag
             as the localized message.  Example: <trn
             key="forum.title" locale="en_US">Title</trn>
@@ -197,7 +197,7 @@
           
             This syntax has been designed to make it easy to
             internationalize existing pages. This is not a syntax that
-            stays in the page. As you'll see later, it'll be replaced
+            stays in the page. As you'll see later, it'll be replaced
             with the short syntax by a special feature of the APM. You
             may leave out the message_key by writing an underscore (_)
             character instead, in which case a message key will be
@@ -224,11 +224,11 @@
 
       
         
-          Typical static key lookup: [_ package_key.message_key] - The message key and package key used here must be string literals, they can't result from variable evaluation.
+          Typical static key lookup: [_ package_key.message_key] - The message key and package key used here must be string literals, they can't result from variable evaluation.
            
 
           
-            Static key lookup with non-default locale: [lang::message::lookup $locale package_key.message_key] - The message key and package key used here must be string literals, they can't result from variable evaluation.
+            Static key lookup with non-default locale: [lang::message::lookup $locale package_key.message_key] - The message key and package key used here must be string literals, they can't result from variable evaluation.
           
 
           
@@ -331,7 +331,7 @@
 # in curly braces (should return nothing, or possibly a few lines for inspection)
 find -iname '*.tcl'|xargs egrep -i '\{.*<#'
 
-# Check if you've forgotten space between default key and text in message tags (should return nothing)
+# Check if you've forgotten space between default key and text in message tags (should return nothing)
 find -iname '*.tcl'|xargs egrep -i '<#_[^ ]'
 
 # Review the list of tcl files with no message lookups
@@ -342,7 +342,7 @@
         When you feel ready you may vist your package in the
         package manager
         and run the action "Replace tags with keys
-        and insert into catalog" on the Tcl files that you've edited to
+        and insert into catalog" on the Tcl files that you've edited to
         replace the temporary tags with calls to the message lookup
         procedure.
       
@@ -354,13 +354,13 @@
     
       Most date, time, and number variables are calculated in Tcl files.  Dates and times must be converted when stored in the database,
       when retrieved from the database, and when displayed.  All dates
-      are stored in the database in the server's timezone, which is an
+      are stored in the database in the server's timezone, which is an
       APM Parameter set at
       /acs-lang/admin/set-system-timezone
       and readable at
       lang::system::timezone..  When
       retrieved from the database and displayed, dates and times must
-      be localized to the user's locale.
+      be localized to the user's locale.
     
     
     
@@ -413,7 +413,7 @@
       
 
       
-        Then, depending on how we retrieve the value, here's what we get:
+        Then, depending on how we retrieve the value, here's what we get:
       
   
       
@@ -582,14 +582,14 @@
         
 
         
-          In Tcl files where the date fields are used, convert the datetime from local server timezone, which is how it's stored in the database, to the user's timezone for display.  Do this with the localizing function lc_time_system_to_conn:
+          In Tcl files where the date fields are used, convert the datetime from local server timezone, which is how it's stored in the database, to the user's timezone for display.  Do this with the localizing function lc_time_system_to_conn:
 
 set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]
-          When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with lc_time_conn_to_system.
+          When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with lc_time_conn_to_system.
 
         
         
-          When a datetime field will be displayed, format it using the localizing function lc_time_fmt. lc_time_fmt takes two parameters, datetime and format code.  Several format codes are usable for localization; they are placeholders that format dates with the appropriate codes for the user's locale.  These codes are: %x, %X, %q, %Q, and %c.
+          When a datetime field will be displayed, format it using the localizing function lc_time_fmt. lc_time_fmt takes two parameters, datetime and format code.  Several format codes are usable for localization; they are placeholders that format dates with the appropriate codes for the user's locale.  These codes are: %x, %X, %q, %Q, and %c.
           set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]
 
         
@@ -677,7 +677,7 @@
 
       
         where package_key is the key of the package that you want to
-        test. If you don't provide the package_key argument then all
+        test. If you don't provide the package_key argument then all
         packages with catalog files will be checked. 
         The script will run its checks primarily on en_US xml catalog files.
       
@@ -773,8 +773,8 @@
 
         
           
-            Don't combine keys in  display text
-            Converting a phrase from one language to another is usually more complicated than simply replacing each word with an equivalent.  When several keys are concatenated, the resulting word order will not be correct for every language.  Different languages may use expressions or idioms that don't match the phrase key-for-key.  Create complete, distinct keys instead of building text from several keys.  For example:
+            Don't combine keys in  display text
+            Converting a phrase from one language to another is usually more complicated than simply replacing each word with an equivalent.  When several keys are concatenated, the resulting word order will not be correct for every language.  Different languages may use expressions or idioms that don't match the phrase key-for-key.  Create complete, distinct keys instead of building text from several keys.  For example:
           
           Original code:
           multirow append links "New [bug_tracker::conn Bug]" 
@@ -820,8 +820,8 @@
 
           
             
-              Don't internationalize internal code words
-              Many packages use code words or key words, such as "open" and "closed", which will never be shown to the user.  They may match key values in the database, or be used in a switch or if statement.  Don't change these.
+              Don't internationalize internal code words
+              Many packages use code words or key words, such as "open" and "closed", which will never be shown to the user.  They may match key values in the database, or be used in a switch or if statement.  Don't change these.
             
             For example, the original code is 
           workflow::case::add_log_data \ 	    
@@ -833,7 +833,7 @@
        -entry_id $entry_id \
        -key "[_ bug-tracker.resolution]" \
        -value [db_string select_resolution_code {}]
-       But resolution is a keyword in a table and in the code, so this breaks the code.  It should not have been internationalized at all.  Here's another example of text that should not have been internationalized:
+       But resolution is a keyword in a table and in the code, so this breaks the code.  It should not have been internationalized at all.  Here's another example of text that should not have been internationalized:
        {show_patch_status "open"}
        It is broken if changed to
        {show_patch_status "[_ bug-tracker.open]"}
@@ -850,9 +850,9 @@
 and users with write permission on this Bug Tracker project (package instance) may do so.</msg>
 <msg key="You_2">You do not have permission to edit this patch. Only the submitter of the patch 
 and users with write permission on the Bug Tracker project (package instance) may do so.</msg>
-          These would be more useful if they were, "you_can_filter", "you_do_not_have_permission_to_map_this_patch", and "you_do_not_have_permission_to_edit_this_patch".  Don't worry about exactly matching the english text, because that might change; instead try to capture the meaning of the phrase.  Ask yourself, if I was a translator and didn't know how this application worked, would this key and text make translation easy for me?
+          These would be more useful if they were, "you_can_filter", "you_do_not_have_permission_to_map_this_patch", and "you_do_not_have_permission_to_edit_this_patch".  Don't worry about exactly matching the english text, because that might change; instead try to capture the meaning of the phrase.  Ask yourself, if I was a translator and didn't know how this application worked, would this key and text make translation easy for me?
 
-          Sometimes the automatic converter creates keys that don't semantically match their text.  Fix these:
+          Sometimes the automatic converter creates keys that don't semantically match their text.  Fix these:
           <msg key="Fix">for version</msg>
 <msg key="Fix_1">for</msg>
 <msg key="Fix_2">for Bugs</msg>
@@ -887,19 +887,19 @@
           When it becomes a key, it should be:
           <msg>Patch "$patch_summary" is nice.</msg>
           Also, some keys had %var;noquote%, which is not needed since those
-          variables are not quoted (and in fact the variable won't even be
+          variables are not quoted (and in fact the variable won't even be
           recognized so you get the literal %var;noquote% in the output).
         
 
         
           
             Be careful with curly brackets
-            Code within curly brackets isn't evaluated.  Tcl uses curly brackets as an alternative way to build lists.  But Tcl also uses curly brackets as an alternative to quotation marks for quoting text.  So this original code
+            Code within curly brackets isn't evaluated.  Tcl uses curly brackets as an alternative way to build lists.  But Tcl also uses curly brackets as an alternative to quotation marks for quoting text.  So this original code
           
           array set names { key "Pretty" ...} 
           ... if converted to 
           array set names { key "[_bug-tracker.Pretty]" ...} 
-          ... won't work since the _ func will not be called.  Instead, it should be 
+          ... won't work since the _ func will not be called.  Instead, it should be 
           array set names [list key [_bug-tracker.Pretty] ...]
          
       
@@ -913,17 +913,17 @@
       Use user preference for this package (stored in ad_locale_user_prefs)
       Use system preference for the package (stored in apm_packages)
       
-      Use user's general preference (stored in user_preferences)
+      Use user's general preference (stored in user_preferences)
       Use Browser header (Accept-Language HTTP header)
       Use system locale (an APM parameter for acs_lang)
 default to en_US
     
-    For ADP pages, message key lookup occurs in the templating engine.  For Tcl pages, message key lookup happens with the _ function.  In both cases, if the requested locale is not found but a locale which is the default for the language which matches your locale's language is
+    For ADP pages, message key lookup occurs in the templating engine.  For Tcl pages, message key lookup happens with the _ function.  In both cases, if the requested locale is not found but a locale which is the default for the language which matches your locale's language is
 found, then that locale is offered instead.
   
 
   
-    Translator's Guide
+    Translator's Guide
     Most translators use the OpenACS Public Translation Server, because the process of getting new message keys onto the server and getting new translations back into the distribution are handled by the maintainers of that machine.  You can also do translation work on your own OpenACS site; this makes your own translations more readily available to you but also means that your work will not be shared with other users unless you take extra steps (contacting an OpenACS core developer or submitting a patch) to get your work back to the OpenACS core.
     The basic steps for translators:
     
@@ -960,6 +960,6 @@
 
       
     
-    When creating a new locale based on an existing one, such as creating the Guatamalan version of Spanish, you can copy the existing locale's catalog files using the script /packages/acs-core-docs/www/files/create-new-catalog.sh.
+    When creating a new locale based on an existing one, such as creating the Guatamalan version of Spanish, you can copy the existing locale's catalog files using the script /packages/acs-core-docs/www/files/create-new-catalog.sh.
   
 
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/objects.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/objects.xml,v
diff -u -N -r1.9 -r1.9.14.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/objects.xml	17 Jul 2006 05:38:37 -0000	1.9
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/objects.xml	23 Jun 2016 08:32:46 -0000	1.9.14.1
@@ -38,7 +38,7 @@
 
 
 
-We've omitted constraint names for the purpose of clarity.
+We've omitted constraint names for the purpose of clarity.
 
 
 
@@ -51,15 +51,15 @@
 Attach user comments on notes.
 Allow users to define custom fields to store on their notes.
 Automatically generate input forms or output displays for notes.
-Allow other applications to use notes in ways we don't know of yet.
+Allow other applications to use notes in ways we don't know of yet.
 
 
 
 In OpenACS, the key to enabling these types of services on your
 application data is to take advantage of the Object System.  The first
 question, then, is "Just what are objects, and what do
 you use them for anyway?".  The short answer: objects are anything
-represented in the application's data model that will need to be
+represented in the application's data model that will need to be
 managed by any central service in OpenACS, or that may be reusable in
 the context of future applications. Every object in the system is
 represented using a row in the acs_objects table. This
@@ -96,7 +96,7 @@
 How to Use Objects
 
 
-Using ACS objects is straightforward: all that's required are a few
+Using ACS objects is straightforward: all that's required are a few
 extra steps in the design of your application data model. 
 
 
@@ -119,7 +119,7 @@
 inherit attributes from a parent type, so the type system forms a
 hierarchy. Unlike Java, Oracle does not support this inheritance
 transparently, so we have to make sure we add our own bookkeeping code to
-keep everything consistent. Below you'll find the code needed to describe a
+keep everything consistent. Below you'll find the code needed to describe a
 new object type called notes in your
 system.
 
@@ -161,7 +161,7 @@
 note. This type is a subtype of the 
 acs_object type, which means that we want to inherit all
 of the basic attributes of all ACS objects. As mentioned, it will take
-some work on our part to make this happen, since Oracle can't do it
+some work on our part to make this happen, since Oracle can't do it
 automatically.  In general, most basic applications will define types
 that are simple subtypes of acs_object.
 
@@ -170,7 +170,7 @@
 Add entries to the acs_attributes table to describe
 the data attributes of the new type. This data can eventually be used
 to do things like automatically generate user interfaces to manipulate
-the notes table, though that functionality isn't yet
+the notes table, though that functionality isn't yet
 available.
 
 
@@ -287,9 +287,9 @@
 
 
 You might be wondering what all the extra parameters are to these
-calls, since we haven't mentioned them before.  These parameters are
+calls, since we haven't mentioned them before.  These parameters are
 needed to fill out information that will be stored about the object
-that's not stored directly in the table you defined. The OpenACS Object
+that's not stored directly in the table you defined. The OpenACS Object
 System defines these attributes on the type acs_object
 since all objects should have these attributes. Internally, there are
 tables that store this information for you. Most of the data is pretty
@@ -306,7 +306,7 @@
 then the object inherits its permissions from the context. For
 example, if I had told you how to use the permissions system to specify that an
 object OBJ was "read only", then any other object that used OBJ as its
-context would also be "read only" by default. We'll talk about this more
+context would also be "read only" by default. We'll talk about this more
 later.
 
 
@@ -379,17 +379,17 @@
 
 
 
-That's pretty much it! As long as you use the note.new
+That's pretty much it! As long as you use the note.new
 function to create notes, and the note.delete function to
-delete them, you'll be assured that the relationship each
+delete them, you'll be assured that the relationship each
 note has with its corresponding acs_object
 is preserved.
 
 
 
 The last thing to do is to make a file
-ROOT/packages/notes/sql/notes-drop.sql so it's easy to
-drop the data model when, say, you're testing:
+ROOT/packages/notes/sql/notes-drop.sql so it's easy to
+drop the data model when, say, you're testing:
 
 
 
@@ -435,7 +435,7 @@
 For example, for most applications, you will want to use objects to
 represent the data in your application that is user visible and thus
 requires access control. But other internal tables, views, mapping
-tables and so on probably don't need to be objects. As before, this
+tables and so on probably don't need to be objects. As before, this
 kind of design decision is mostly made on an
 application-by-application basis, but this is a good baseline from
 which to start.
@@ -475,7 +475,7 @@
 
 
 
-As we'll see later, the Notes example will point each note object's
+As we'll see later, the Notes example will point each note object's
 context_id to the package instance in which the note was
 created. The idea will be that in a real site, the administrator would
 create one package instance for every separate set of Notes (say, one
@@ -509,9 +509,9 @@
 are careful to define our own attribute for owner_id
 rather than overloading creation_user from the objects
 table. But, since we will probably use creation_date and
-so on for their intended purposes, we don't bother to define our own
+so on for their intended purposes, we don't bother to define our own
 attributes to store that data again. This will entail joins with
-acs_objects but that's OK because it makes the overall
+acs_objects but that's OK because it makes the overall
 data model cleaner. The real lesson is that deciding exactly how and
 when to use inherited attributes is fairly straightforward, but
 requires a good amount of thought at design time even for simple
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml,v
diff -u -N -r1.9 -r1.9.14.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml	17 Jul 2006 05:38:37 -0000	1.9
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml	23 Jun 2016 08:32:46 -0000	1.9.14.1
@@ -75,14 +75,14 @@
       packages that have been installed in the server, where those packages
       have been installed, and a standard way to map URLs that a client
       sends to our server to the right page in the appropriate
-      package. While we're at it, this tool should also automate
+      package. While we're at it, this tool should also automate
       package installation, dependency checking, upgrades, and package
       removal. In OpenACS &majorversion;, this tool is called the APM.
     
 
     
       OpenACS Package
-      To illustrate the general structure of a package, let's see what the
+      To illustrate the general structure of a package, let's see what the
       package for the "notes" application should look like.
     
 
@@ -452,7 +452,7 @@
 
 
       Fill out the form for adding a new package. The form explains what
-      everything means, but we'll repeat the important bits here for easy
+      everything means, but we'll repeat the important bits here for easy
       reference:
 
       
@@ -486,8 +486,8 @@
           
           If your package name is a nice singular noun, this should be the
           plural form of it. I assume the plural form is used when multiple
-          instances of the package are used by a single service. We'll talk more
-          about package instances later. Our example apllication doesn't really
+          instances of the package are used by a single service. We'll talk more
+          about package instances later. Our example apllication doesn't really
           have a good plural name. So just make it also be "Notes".
         
         
@@ -558,7 +558,7 @@
           The directory that APM created will be empty except for the
           notes.info file. Create a file
           called
-          ROOT/packages/notes/sql/oracle/notes-create.sql. We'll
+          ROOT/packages/notes/sql/oracle/notes-create.sql. We'll
           fill this file with our data model
           very soon. Create a file called
           ROOT/packages/notes/sql/oracle/notes-drop.sql. This
@@ -637,11 +637,11 @@
 
     
       At this point, you are probably excited to see your new package in
-      action. But, we haven't added any user visible pages yet. By
+      action. But, we haven't added any user visible pages yet. By
       convention, user visible pages go in the
       ROOT/packages/notes/www directory. So go there and add a
       file called hello.html with some text in it. Now we have
-      to make the user pages visible in the site. Since we didn't put the
+      to make the user pages visible in the site. Since we didn't put the
       pages underneath ROOT/www they will not appear on their
       own.  What we have to do is mount the application into the site
       map. That is, we have to define the URL from which the application
@@ -690,7 +690,7 @@
       ROOT/packages/notes/www. At this point, you can
       experiment with the site map by mounting multiple instances of the not
       yet written Notes application at various places in the site. In a
-      later document, we'll see how to write your application so that the
+      later document, we'll see how to write your application so that the
       code can detect from what URL it was invoked. This is the key
       to supporting subsites.
     
@@ -721,7 +721,7 @@
     
       
       Writes out package distribution files for other people to download and
-      install. We'll cover this later.
+      install. We'll cover this later.
     
     
 
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions-tediously-explained.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions-tediously-explained.xml,v
diff -u -N -r1.8 -r1.8.14.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions-tediously-explained.xml	25 Sep 2006 20:32:37 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions-tediously-explained.xml	23 Jun 2016 08:32:46 -0000	1.8.14.1
@@ -359,7 +359,7 @@
       ..., and F can be derived by ascertaining that these objects 
       are children of A by traversing the context hierarchy.
       As it turns out, hierarchical queries are expensive.  As
-      Rafael Schloming put it so aptly, Oracle can't deal with hierarchies for shit. 
+      Rafael Schloming put it so aptly, Oracle can't deal with hierarchies for shit. 
     
 
     
@@ -535,7 +535,7 @@
     
       One final note about 
       . By setting
-      an object's security_inherit_p column to 'f', you can stop permissions
+      an object's security_inherit_p column to 'f', you can stop permissions
       from cascading down the context tree. In the following example, Joe does not have
       the read permissions on C and F. 
     
@@ -1129,7 +1129,7 @@
     as
       exists_p char(1);
     begin
-      -- XXX This must be fixed: -1 shouldn't be hardcoded (it is the public)
+      -- XXX This must be fixed: -1 shouldn't be hardcoded (it is the public)
       select decode(count(*),0,'f','t') into exists_p
         from 
        where object_id = permission_p.object_id
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml,v
diff -u -N -r1.17 -r1.17.6.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml	11 Dec 2010 23:36:32 -0000	1.17
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml	23 Jun 2016 08:32:46 -0000	1.17.6.1
@@ -272,7 +272,7 @@
 
 The first row represents an entry in User 123's personal address book,
 the second row represents an entry in User Group 456's shared address
-book, and the third row represents an entry in the site's public
+book, and the third row represents an entry in the site's public
 address book. In this way, the scoping columns identify the security context in
 which a given object belongs, where each context is either a
 person or a group of people or the general public
@@ -310,7 +310,7 @@
 forum. Then, suppose we grant every user in the system read-access to
 this forum. By default, they will automatically have read-access to
 the new message we just inserted, since the system automatically
-checks permissions on the message's context. To allow the creator of
+checks permissions on the message's context. To allow the creator of
 the message to change the message after it has been posted we grant
 the user write-access on the message, and we are done.
 
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml,v
diff -u -N -r1.12 -r1.12.6.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml	11 Dec 2010 23:36:32 -0000	1.12
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml	23 Jun 2016 08:32:46 -0000	1.12.6.1
@@ -66,7 +66,7 @@
 
 Next, the Request Processor examines the request for session
 information. Session information is generally sent from the client
-(the user's browser) to the server via cookies. The security/session handler is described in
+(the user's browser) to the server via cookies. The security/session handler is described in
 detail in its own document. It examines the client request and either
 extracts or sets up new session tokens for the user.
 
@@ -98,7 +98,7 @@
 
 
 
-If the RP can't find any matching files with the expected extensions,
+If the RP can't find any matching files with the expected extensions,
 it will look for virtual-url-handler files, or .vuh
 files. A .vuh file will be executed as if it were a Tcl
 file, but with the tail end of the URL removed. This allows the code
@@ -112,8 +112,8 @@
 
 
 Once the appropriate file is found, it is either served directly if
-it's static content, or sent to the template system or the standard
-Tcl interpreter if it's a dynamic page.
+it's static content, or sent to the template system or the standard
+Tcl interpreter if it's a dynamic page.
 
 
 
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/subsites.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/subsites.xml,v
diff -u -N -r1.9 -r1.9.2.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/subsites.xml	27 Oct 2014 16:39:30 -0000	1.9
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/subsites.xml	23 Jun 2016 08:32:46 -0000	1.9.2.1
@@ -19,11 +19,11 @@
 
 
 
-In this document, we'll examine the user interface pages of the Notes
+In this document, we'll examine the user interface pages of the Notes
 application in more detail, covering two separate aspects of page
-development in OpenACS. First, we'll talk about the code needed to make
+development in OpenACS. First, we'll talk about the code needed to make
 your pages aware of which application instance they are running
-in. Second, we'll talk about using the form builder to develop
+in. Second, we'll talk about using the form builder to develop
 form-based user interfaces in OpenACS. While these seem like unrelated
 topics, they both come up in the example page that we are going to
 look at, so it makes sense to address them at the same time.
@@ -44,7 +44,7 @@
 application instances to particular URLs within a site. We call
 creating such a mapping mounting the application instance at a
 particular URL.  The tutorial also showed how a given URL is
-translated into a physical file to serve using the site map. We'll
+translated into a physical file to serve using the site map. We'll
 repeat this description here, assuming that you have mounted an
 instance of Notes at the URL /notes as we did in the packages-example:
 
@@ -134,7 +134,7 @@
 
 In the Notes example, we are particularly interested in the
 package_id field.  If you study the data model and code,
-you'll see why. As we said before in the data modeling tutorial, the Notes application points the
+you'll see why. As we said before in the data modeling tutorial, the Notes application points the
 context_id of each Note object that it creates to the
 package instance that created it. That is, the context_id
 corresponds exactly to the package_id that comes in from
@@ -207,7 +207,7 @@
 template system. This API allows you to write forms-based pages
 without generating a lot of duplicated HTML in your pages. It also
 encapsulates most of the common logic that we use in dealing with
-forms, which we'll discuss next.
+forms, which we'll discuss next.
 
 
 
@@ -372,7 +372,7 @@
 
 
 
-In this simple example, we don't do any custom validation. The nice
+In this simple example, we don't do any custom validation. The nice
 thing about using this API is that the forms library handles all of
 the HTML rendering, input validation and database transaction logic on
 your behalf. This means that you can write pages without duplicating
@@ -391,7 +391,7 @@
 repository, mount an instance of Notes somewhere in your server and
 then try out the user interface pages. It should become clear that in
 a real site, you would be able to, say, create a custom instance of
-Notes for every registered user, mount that instance at the user's
+Notes for every registered user, mount that instance at the user's
 home page, and set up the permissions so that the instance is only
 visible to that user. The end result is a site where users can come
 and write notes to themselves.
@@ -428,7 +428,7 @@
 
 
 
-We also saw how to use the templating system's forms API in a simple
+We also saw how to use the templating system's forms API in a simple
 way, to create forms based pages with minimal duplication of code.
 
 
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/templates.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/templates.xml,v
diff -u -N -r1.12 -r1.12.2.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/templates.xml	2 Jul 2015 20:03:56 -0000	1.12
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/templates.xml	23 Jun 2016 08:32:46 -0000	1.12.2.1
@@ -22,7 +22,7 @@
 logic. The intent is to have all of the logic related to
 manipulating the database and other application state data in one
 place, and all the logic related to displaying the state of the
-application in another place.  This gives developer's quicker
+application in another place.  This gives developer's quicker
 customization and easier upgrades, and also allows developers and
 graphic designers to work more independently.
 
@@ -43,7 +43,7 @@
 In the overall context of our example OpenACS Notes application, this
 document will show you how to set up a simple templated page that
 displays a form to the user for entering new notes into the system. In
-later sections of the DG, we'll discuss how to develop the pages that
+later sections of the DG, we'll discuss how to develop the pages that
 actually add notes to the database, how to provide a separate instance
 of the Notes application to every user and how to design appropriate
 access control policies for the system.
@@ -62,8 +62,8 @@
 pages: one that displays a form for data entry, and another page that
 runs the code to update the database and tells the user whether the
 operation failed. In this document, we will use the template system to
-build the first of these pages. This isn't a very interesting use of
-the system since we won't be displaying much data, but we'll cover
+build the first of these pages. This isn't a very interesting use of
+the system since we won't be displaying much data, but we'll cover
 more on that end later.
 
 
@@ -119,14 +119,14 @@
 
 
 The procedure ad_page_contract is
-always the first thing a .tcl file calls, if it's under
+always the first thing a .tcl file calls, if it's under
 the www/ directory (i.e. not a Tcl library file). It does validation
 of input values from the HTTP request (i.e. form variables) and in
 this case, the -properties clause is used to set up the
 data sources that we will ship over to the .adp part of
 the page. In this case, we only use the simplest possible kind of data
 source, called a onevalue, which hold just a single
-string value.  Later on, we'll see how to use more powerful kinds of
+string value.  Later on, we'll see how to use more powerful kinds of
 data sources for representing multiple rows from an SQL query.  You
 also include overall documentation for the page in the contract, and
 OpenACS has automatic tools that extract this documentation and make it
@@ -211,7 +211,7 @@
 data sources that are used by the display part of the page. The
 display part of the page is an .adp file with some
 special tags and notations for dealing with display logic and
-inserting properties into the text of the page. Later on we'll get
+inserting properties into the text of the page. Later on we'll get
 into templates more deeply, and show how to use database queries as
 data sources.
 
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml,v
diff -u -N -r1.52.2.1 -r1.52.2.2
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml	10 Jun 2016 07:35:08 -0000	1.52.2.1
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml	23 Jun 2016 08:32:46 -0000	1.52.2.2
@@ -12,14 +12,14 @@
     This tutorial covers topics which are not essential to
     creating a minimal working package.  Each section can be used
     independently of all of the others; all sections assume that
-    you've completed the basic tutorial.
+    you've completed the basic tutorial.
 
     
       Write the Requirements and Design Specs
       Before you get started you should make yourself familiar with
       the tags that are used to write your documentation. For tips on
         editing SGML files in emacs, see .
-      It's time to document.  For the tutorial we'll use
+      It's time to document.  For the tutorial we'll use
       pre-written documentation.  When creating a package
       from scratch, start by copying the documentation template from
 	/var/lib/aolserver/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml
@@ -82,7 +82,7 @@
       Add the new package to CVS
       Before you do any more work, make sure that your work is
       protected by putting it all into cvs.  The cvs
-      add command is not recursive, so you'll have to
+      add command is not recursive, so you'll have to
       traverse the directory tree manually and add as you go.  (More on
       CVS)
@@ -336,7 +336,7 @@
 
   
      Adding Comments
-     You can track comments for any ACS Object.  Here we'll track
+     You can track comments for any ACS Object.  Here we'll track
      comments for notes.  On the note-edit.tcl/adp pair, which is used to
      display individual notes, we want to put a link to add comments at
      the bottom of the screen.  If there are any comments, we want to
@@ -380,7 +380,7 @@
        Delete Selected button on the bottom of the list.
        
        Dedicated admin pages.  If you want admins to have
-       access to data that users aren't interested in or aren't allowed
+       access to data that users aren't interested in or aren't allowed
        to see you will need dedicated admin pages.  The conventional
        place to put those dedicated admin pages is in the
  /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin
@@ -389,7 +389,7 @@
 [$OPENACS_SERVICE_NAME www]$ mkdir admin
 [$OPENACS_SERVICE_NAME www]$ cd admin
       
-      Even if your application doesn't need any admin pages of its own you will
+      Even if your application doesn't need any admin pages of its own you will
       usually need at least one simple page with a bunch of links to existing
       administration UI such as Category Management or standard Parameters UI.
       Adding the link to Category Management is described in the section on
@@ -431,12 +431,12 @@
 
 
 Now that you have the first admin page it would be nice to have a link to it
-somewhere in the system so that admins don't have to type in the
+somewhere in the system so that admins don't have to type in the
 /admin every time they need to reach it.  You
 could put a static link to the toplevel
 index.adp but that might be distracting for
 people who are not admins.  Besides, some people consider it impolite to first
-offer a link and then display a nasty "You don't have permission to access this
+offer a link and then display a nasty "You don't have permission to access this
 page" message.
 
 
@@ -477,20 +477,20 @@
     extended by Nima Mazloumi
   
     You can associate any ACS Object with one or more categories.
-    In this tutorial we'll show how to equip your application with user
+    In this tutorial we'll show how to equip your application with user
     interface to take advantage of the Categories service.
     
     
-    We'll start by installing the Categories service.  Go to
+    We'll start by installing the Categories service.  Go to
     /acs/admin and install it.  This step
-    won't be necessary for the users of your applications because you'll create
+    won't be necessary for the users of your applications because you'll create
     a dependency with the Package Manager which will take care that the
     Categories service always gets installed when your application gets
     installed.
     
     
     Now that we have installed the Categories service we can proceed to
-    modifying our application so that it can take advantage of it.  We'll do it
+    modifying our application so that it can take advantage of it.  We'll do it
     in three steps:
     
     
@@ -543,8 +543,8 @@
           to categorize items.  The easiest way to do this is by adding the
           category widget type of the
           form builder to note-edit.tcl.
-          To achieve this we'll need to use the -extend
-          switch to the ad_form command. Here's the "meat" of the
+          To achieve this we'll need to use the -extend
+          switch to the ad_form command. Here's the "meat" of the
           note-edit.tcl page:
           
 			# extend the form to support categories
@@ -583,7 +583,7 @@
 should initially be absert.  If it is absent, we create a form to
 allow the user to confirm the deletion.  Note that in
 entry-edit.tcl we used ad_form to access the Form Template
-commands; here, we call them directly because we don't need the extra
+commands; here, we call them directly because we don't need the extra
 features of ad_form.  The form calls itself, but
 with hidden variables carrying both
 note_id and
@@ -744,7 +744,7 @@
         		set category_name [category::get_name $category_id]
         		if { $category_name eq "" } {
             		ad_return_exception_page 404 "No such category" "Site-wide \
-          			Category with ID $category_id doesn't exist"
+          			Category with ID $category_id doesn't exist"
             		return
         		}
         		# Show Category in context bar
@@ -846,7 +846,7 @@
     developer, there are a couple of steps you need to take in order
     to release a new version of your package. 
 
-    For the sake of this example, let's assume you are the
+    For the sake of this example, let's assume you are the
     package owner of the notes
     package. It is currently at version 1.5, and you are planning on
     releasing version 1.6. It is also located in OpenACS's CVS.
@@ -954,7 +954,7 @@
       -- @creation-date 2002-05-16
       --
       -- This code is newly concocted by Ben, but with significant concepts and code
-      -- lifted from Gilbert's UBB forums. Thanks Orchard Labs.
+      -- lifted from Gilbert's UBB forums. Thanks Orchard Labs.
       -- Lars and Jade in turn lifted this from gwong and ben.
 
 create function inline_0 ()
@@ -1138,7 +1138,7 @@
     tree_level() function, which
     gives you the level, starting from 1, 2, 3... 
 
-    Here's an example, pulling all of the children for a given
+    Here's an example, pulling all of the children for a given
   parent: 
 
     
@@ -1155,14 +1155,14 @@
       and parent.key = :the_parent_key;
       
 
-    The reason we substract the parent's tree_level from the
-    child's tree_level is that the tree_levels are global, so if you
-    want the parent's tree_level to start with 0, you'll want the
-    subtraction in there. This is a reason you'll commonly see magic
+    The reason we substract the parent's tree_level from the
+    child's tree_level is that the tree_levels are global, so if you
+    want the parent's tree_level to start with 0, you'll want the
+    subtraction in there. This is a reason you'll commonly see magic
     numbers in tree_sortkey SQL queries, like
     tree_level(children.tree_sortkey) -
     4. That is basically an incorrect way to do it,
-    and subtracting the parent's tree_level is the preferred method.
+    and subtracting the parent's tree_level is the preferred method.
 
     This example does not include the parent. To return the entire subtree including the parent, leave out the non-equals clause:
 
@@ -1384,7 +1384,7 @@
         
       
       
-        If you are correctly flushing the cached value, then it will need to be reloaded.  You may wish to pre-load it, so that the loading delay does not impact users.  If you have a sequence of pages, you could call the cached proc in advance, to increase the chances that it's loaded and current when the user reaches it.  Or, you can call (and discard) it immediately after flushing it.
+        If you are correctly flushing the cached value, then it will need to be reloaded.  You may wish to pre-load it, so that the loading delay does not impact users.  If you have a sequence of pages, you could call the cached proc in advance, to increase the chances that it's loaded and current when the user reaches it.  Or, you can call (and discard) it immediately after flushing it.
       
     
   
@@ -1434,7 +1434,7 @@
 	} ...
 	
 	
-	You must not give your your form the same name that your page has. Otherwise HTMLArea won't load.
+	You must not give your your form the same name that your page has. Otherwise HTMLArea won't load.
 	
 	Convert your textarea widget to a richtext widget and enable htmlarea.
 	The htmlarea_p-flag can be used to prevent 
@@ -1455,7 +1455,7 @@
 	ad_form or you will have problems 
 	displaying the content or handling the data manipulation correctly.
 	Depending on the data model of your package you either support a content format 
-	or don't. If you don't you can assume "text/html" or 
+	or don't. If you don't you can assume "text/html" or 
 	"text/richtext" or "text/enhanced".
 	The relevant parts in your ad_form definition are the 
 	switches -new_data, -edit_data, 
@@ -1474,7 +1474,7 @@
 	
 	Now the correct values for my_input_field_2 and 
 	format are passed to the -new_data and 
-	-edit_data blocks which don't need to get touched.
+	-edit_data blocks which don't need to get touched.
 	To make HTMLArea optional per package instance define a string parameter 
 	UseWysiwygP which defaults 0 for your 
 	package using the APM.
@@ -1555,7 +1555,7 @@
 
     Under the Manage section, click on Parameters
 
-    It's fairly self-explanatory at this point. Create the
+    It's fairly self-explanatory at this point. Create the
     parameters you want, and then access them in your code using the
     parameter::get procedure.
 
@@ -1674,7 +1674,7 @@
   
   Future Topics
     
-      How to enforce security so that users can't
+      How to enforce security so that users can't
       change other users records
       
       How to use the content management tables so that
@@ -1685,7 +1685,7 @@
       How to prepare pagelets for inclusion in other pages
       How and when to put procedures in a tcl procedure library
       More on ad_form - data validation, other stuff.
-      (plan to draw from Jon Griffin's doc)
+      (plan to draw from Jon Griffin's doc)
       partialquery in xql
       How to use the html/text entry widget to get the
       "does this look right" confirm page 
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml,v
diff -u -N -r1.18 -r1.18.6.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml	11 Dec 2010 23:36:32 -0000	1.18
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml	23 Jun 2016 08:32:46 -0000	1.18.6.1
@@ -89,7 +89,7 @@
 (1 row)
 
 [$OPENACS_SERVICE_NAME postgresql]$
-      If there are errors, use them to debug the sql file and try again.  If there are errors in the database table creation, you may need to run the drop script to drop the table so that you can recreate it.  The drop script will probably have errors since some of the things it's trying to drop may be missing.  They can be ignored.
+      If there are errors, use them to debug the sql file and try again.  If there are errors in the database table creation, you may need to run the drop script to drop the table so that you can recreate it.  The drop script will probably have errors since some of the things it's trying to drop may be missing.  They can be ignored.
       Once you get the same output as shown above, test the drop script:
       [$OPENACS_SERVICE_NAME postgresql]$ psql service0 -f myfirstpackage-drop.sql
 
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-debug.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-debug.xml,v
diff -u -N -r1.13.2.1 -r1.13.2.2
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-debug.xml	23 Sep 2015 11:55:08 -0000	1.13.2.1
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-debug.xml	23 Jun 2016 08:32:46 -0000	1.13.2.2
@@ -31,7 +31,7 @@
 
     
     Hint: "Parse error near *" usually means that an xql file
-      wasn't recognized, because the tcl file is choking on the *SQL*
+      wasn't recognized, because the tcl file is choking on the *SQL*
       placeholder that it falls back on.
     
       Watching the server log
@@ -85,7 +85,7 @@
             Proc should return 0 for success.
           
         
-        Other things to test: try to delete someone else's
+        Other things to test: try to delete someone else's
         note.  Try to delete your own note.  Edit your own note.
         Search for a note.
   
@@ -98,7 +98,7 @@
     
 
     Automated tests
-    It seems to me that a lot of people have been asking for some guidelines on how to write automated tests. I've done several tests by now and have found the process to be extremely easy and useful. It's a joy to work with automated testing once you get the hang of it.
+    It seems to me that a lot of people have been asking for some guidelines on how to write automated tests. I've done several tests by now and have found the process to be extremely easy and useful. It's a joy to work with automated testing once you get the hang of it.
     Create the directory that will contain the test
     script and edit the script file.  The directory location and file name are standards which are recognized by the automated testing package:
     [$OPENACS_SERVICE_NAME www]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/test
@@ -111,25 +111,25 @@
 
         To create a test case you call
 aa_register_case test_case_name..   
-Once you've created the test case you start writing the needed logic.
-We'll use the tutorial package, "myfirstpackage," as an example.
-Let's say you just wrote an API for adding and deleting notes in the
-notes packages and wanted to test that. You'd probably want to write a
+Once you've created the test case you start writing the needed logic.
+We'll use the tutorial package, "myfirstpackage," as an example.
+Let's say you just wrote an API for adding and deleting notes in the
+notes packages and wanted to test that. You'd probably want to write a
 test that first creates a note, then verifies that it was inserted,
 then perhaps deletes it again, and finally verifies that it is
 gone. 
 
 
-Naturally this means you'll be adding a lot of bogus data to the
-database, which you're not really interested in having there. To avoid
+Naturally this means you'll be adding a lot of bogus data to the
+database, which you're not really interested in having there. To avoid
 this I usually do two things. I always put all my test code inside a
 call to aa_run_with_teardown which basically means that all the
 inserts, deletes, and updates will be rolled back once the test has
 been executed. A very useful feature. Instead of inserting bogus data
-like:        set name "Simon", I tend to generate a random script in order avoid inserting a value that's already in the database:
+like:        set name "Simon", I tend to generate a random script in order avoid inserting a value that's already in the database:
 set name [ad_generate_random_string]
 
-Here's how the test case looks so far:
+Here's how the test case looks so far:
 
 aa_register_case mfp_basic_test {
     My test
@@ -141,17 +141,17 @@
        }
 }
 
-Now let's look at the actual test code. That's the code that
+Now let's look at the actual test code. That's the code that
 goes inside -test_code {}.  We want to implement test case API-001, "Given an object id from API-001, invoke mfp::note::get.  Proc should return the specific word in the title."
     
       set name [ad_generate_random_string]
       set new_id [mfp::note::add -title $name]
       aa_true "Note add succeeded" ([info exists new_id] && $new_id ne "")
-    To test our simple case, we must load the test file into the system (just as with the /tcl file in the basic tutorial, since the file didn't exist when the system started, the system doesn't know about it.)  To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage".  Since we'll be changing it frequently, select "watch this file" on the next page.  This will cause the system to check this file every time any page is requested, which is bad for production systems but convenient for developing.  We can also add some aa_register_case flags to make it easier to run the test.  The -procs flag, which indicates which procs are tested by this test case, makes it easier to find procs in your package that aren't tested at all.  The -cats flag, setting categories, makes it easier to control which tests to run.  The smoke test setting means that this is a basic test case that can and should be run any time you are doing any test. (a definition of "smoke test")
+    To test our simple case, we must load the test file into the system (just as with the /tcl file in the basic tutorial, since the file didn't exist when the system started, the system doesn't know about it.)  To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage".  Since we'll be changing it frequently, select "watch this file" on the next page.  This will cause the system to check this file every time any page is requested, which is bad for production systems but convenient for developing.  We can also add some aa_register_case flags to make it easier to run the test.  The -procs flag, which indicates which procs are tested by this test case, makes it easier to find procs in your package that aren't tested at all.  The -cats flag, setting categories, makes it easier to control which tests to run.  The smoke test setting means that this is a basic test case that can and should be run any time you are doing any test. (a definition of "smoke test")
       Once the file is loaded, go to ACS Automated Testing and click on myfirstpackage.  You should see your test case.  Run it and examine the results.
     
       TCLWebtest tests
-      API testing can only test part of our package - it doesn't test the code in our adp/tcl pairs.  For this, we can use TCLwebtest.  TCLwebtest must be installed for this test to work.  This provides a library of functions that make it easy to call a page through HTTP, examine the results, and drive forms.  TCLwebtest's functions overlap slightly with acs-automated-testing; see the example provided for one approach on integrating them.
+      API testing can only test part of our package - it doesn't test the code in our adp/tcl pairs.  For this, we can use TCLwebtest.  TCLwebtest must be installed for this test to work.  This provides a library of functions that make it easy to call a page through HTTP, examine the results, and drive forms.  TCLwebtest's functions overlap slightly with acs-automated-testing; see the example provided for one approach on integrating them.
     
     
       Example
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-pages.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-pages.xml,v
diff -u -N -r1.20 -r1.20.2.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-pages.xml	27 Oct 2014 16:39:31 -0000	1.20
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-pages.xml	23 Jun 2016 08:32:46 -0000	1.20.2.1
@@ -20,7 +20,7 @@
   
   
     Page Map
-    Our package will have two visible pages.  The first shows a list of all objects; the second shows a single object in view or edit mode, and can also be used to add an object.  The index page will display the list, but since we might reuse the list later, we'll put it in a seperate file and include it on the index page.
+    Our package will have two visible pages.  The first shows a list of all objects; the second shows a single object in view or edit mode, and can also be used to add an object.  The index page will display the list, but since we might reuse the list later, we'll put it in a seperate file and include it on the index page.
       
        
         Page Map
         
@@ -41,15 +41,15 @@
       holds html.  The -postgres.xql
       and -oracle.xql files contains
       database-specific SQL.  The default page in any directory is
-      index, so we'll build that
+      index, so we'll build that
       first, starting with the tcl file:
       [$OPENACS_SERVICE_NAME postgresql]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackages/www
 [$OPENACS_SERVICE_NAME www]$ emacs index.tcl
       Paste this into the file.      
       example missing
     Now index.adp:
       example missing
-      The index page includes the list page, which we put in /lib instead of /www to designate that it's available for reuse by other packages.
+      The index page includes the list page, which we put in /lib instead of /www to designate that it's available for reuse by other packages.
       [$OPENACS_SERVICE_NAME www]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib
 [$OPENACS_SERVICE_NAME www]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib
 [$OPENACS_SERVICE_NAME lib]$ emacs note-list.tcl
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml,v
diff -u -N -r1.21 -r1.21.2.1
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml	27 Oct 2014 16:39:31 -0000	1.21
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml	23 Jun 2016 08:32:46 -0000	1.21.2.1
@@ -37,8 +37,8 @@
       
         This tutorial uses the content repository package.  This
         radically simplifies the database work, but forces us to work
-        around the content repository's limitations, including an
-        incomplete Tcl API.  So the tutorial is messier than we'd like
+        around the content repository's limitations, including an
+        incomplete Tcl API.  So the tutorial is messier than we'd like
         right now.  Code that is temporary hackage is clearly marked.
       
       
@@ -51,7 +51,7 @@
     You will need:
     
       A computer with a working installation of
-	  OpenACS.  If you don't have this, see .
+	  OpenACS.  If you don't have this, see .
 	  
       Example files, which are included in the
 standard OpenACS &version; distribution.
@@ -107,7 +107,7 @@
       
         Click Create a New Package.
         Fill in the fields listed below.   Ignore the rest (and leave the check boxes alone).
-        (Some will change automatically.  Don't mess with those.)
+        (Some will change automatically.  Don't mess with those.)
 
         
           
@@ -156,7 +156,7 @@
       You can have instances of a package on one site, each with a
       different URL and different permissions, all sharing the same
       code and tables.  This requires that a package be developed
-      package-aware.  You'll see how to do that
+      package-aware.  You'll see how to do that
       in this tutorial.
       
         Browse to
@@ -167,7 +167,7 @@
           Choose "My First Package" from the list and click OK (the other fields are optional).
         
       
-      By mounting the package, we've caused all requests to
+      By mounting the package, we've caused all requests to
       http://yourserver.test:8000/myfirstpackage
       to be satisfied from the files at /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www.
     
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/auto-testing.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/auto-testing.xml,v
diff -u -N -r1.3 -r1.3.14.1
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/auto-testing.xml	17 Jul 2006 05:38:37 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/auto-testing.xml	23 Jun 2016 08:32:46 -0000	1.3.14.1
@@ -17,7 +17,7 @@
       
         Special characters in Tcl
         
-Try strings starting with a -Bad and strings containing [BAD], {, \077, and $Bad.  For user input, [BAD] should never be evaluated, \077 should not be turned into a ? and $Bad should not be interpolated.  The string -Bad [BAD] \077 { $Bad should be valid user input, should pass through the system unaltered, and if it isn't that's a bug.
+Try strings starting with a -Bad and strings containing [BAD], {, \077, and $Bad.  For user input, [BAD] should never be evaluated, \077 should not be turned into a ? and $Bad should not be interpolated.  The string -Bad [BAD] \077 { $Bad should be valid user input, should pass through the system unaltered, and if it isn't that's a bug.
 
       
     
@@ -29,9 +29,9 @@
 usually).  Look out especially for quoting errors in the context bar
 and in round trips via an edit form. For fields that disallow html
 tags you can use &amp; to check that the field is quoted
-properly.  If it is not displayed as &amp; then the quoting for the field is incorrect. (It's not clear whether this
+properly.  If it is not displayed as &amp; then the quoting for the field is incorrect. (It's not clear whether this
 should be considered an error but given that data for text fields can
-come from various sources if it's text it should be properly quoted
+come from various sources if it's text it should be properly quoted
 and we should not rely on input validation to prevent XSS security
 holes.)
       
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/constraint-naming.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/constraint-naming.xml,v
diff -u -N -r1.6.14.1 -r1.6.14.2
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/constraint-naming.xml	21 Jun 2016 07:44:36 -0000	1.6.14.1
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/constraint-naming.xml	23 Jun 2016 08:32:46 -0000	1.6.14.2
@@ -94,13 +94,13 @@
 
 
 
-In reality, this won't be possible because of the character limitation on 
+In reality, this won't be possible because of the character limitation on 
 names inside oracle. When the name is too long, we will follow these two
 steps in order:
 
 
 
-   Abbreviate the table name with the table's initials (e.g. users -> u and users_contact -> uc).
+   Abbreviate the table name with the table's initials (e.g. users -> u and users_contact -> uc).
 
    Truncate the column name until it fits.
 
@@ -152,10 +152,10 @@
 
 
 
-Why it's good to name primary keys
+Why it's good to name primary keys
 
 
-Naming primary keys might not have any obvious advantages. However, here's an 
+Naming primary keys might not have any obvious advantages. However, here's an 
 example where naming the primary key really helps (and this is by no means
 a rare case!
 
@@ -177,7 +177,7 @@
 
 
 
-Isn't it nice to see "EXAMPLE_TOPICS_TOPIC_ID_PK" in the trace
+Isn't it nice to see "EXAMPLE_TOPICS_TOPIC_ID_PK" in the trace
 and know exactly which table oracle is using at each step?
 
 
@@ -197,7 +197,7 @@
 About Naming the not null constraints
 
 
-Though naming "not null" constraints doesn't help immeditately in error
+Though naming "not null" constraints doesn't help immeditately in error
 debugging (e.g. the error will say something like 
 "Cannot insert null value into column"), we recommend naming not null
 constraints to be consistent in our naming of all constraints.
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/cvs.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/cvs.xml,v
diff -u -N -r1.6 -r1.6.14.1
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/cvs.xml	17 Jul 2006 05:38:37 -0000	1.6
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/cvs.xml	23 Jun 2016 08:32:46 -0000	1.6.14.1
@@ -71,7 +71,7 @@
         Administrator Note: These are the steps to grant CVS commit rights to a user:
       
         
-          Create the user's account.  On cvs.openacs.org:
+          Create the user's account.  On cvs.openacs.org:
           sudo bash
 /usr/sbin/useradd -c "Real Name" -G cvs -p passwd username
 /usr/sbin/usermod -G cvs,username username
@@ -245,7 +245,7 @@
                   calendar package. All non-core, non-dotlrn packages should have a
                   tag of this style, based on the package name. Many packages have
                   not been re-released since the new naming convention was adopted
-                  and so don't have a tag of this type.
+                  and so don't have a tag of this type.
                 
               
 
@@ -477,9 +477,9 @@
         be addressed with another upgrade script. E.g., the last planned
         upgrade script for a package previously in dev 1 would be
         upgrade-2.0.0d1-2.0.0b1.sql, not upgrade-2.0.0d1-2.0.0.sql. Note
-        that using rc1 instead of b1 would be nice, because that's the
+        that using rc1 instead of b1 would be nice, because that's the
         convention with release codes in cvs, but the package manager
-        doesn't support rc tags.
+        doesn't support rc tags.
       
 
           
@@ -629,9 +629,9 @@
           
         
         
-          For example, adding a new API function wouldn't require a
+          For example, adding a new API function wouldn't require a
           TIP. Changing an existing API function by adding an optional new
-          flag which defaults to no-effect wouldn't require a TIP. Added a
+          flag which defaults to no-effect wouldn't require a TIP. Added a
           new mandatory flag to an existing function would require a
           TIP.
         
@@ -715,13 +715,13 @@
       
         
           Commit one cohesive bug fix or feature change at a time.
-          Don't put a bunch of unrelated changes into one commit.
+          Don't put a bunch of unrelated changes into one commit.
         
       
       
         
           Before you throw out or change a piece of code that you
-          don't fully understand, use cvs annotate and cvs log on the file to
+          don't fully understand, use cvs annotate and cvs log on the file to
           see who wrote the code and why. Consider contacting the
           author.
         
@@ -768,7 +768,7 @@
               OpenACS cvs web
             and
             
-              Jeff's cvs
+              Jeff's cvs
               browser
             
             are useful tools in understanding what is
@@ -809,7 +809,7 @@
         
         
           
-            Piskorski's cvs refs
+            Piskorski's cvs refs
           
         
         
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/design-template.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/design-template.xml,v
diff -u -N -r1.8 -r1.8.14.1
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/design-template.xml	17 Jul 2006 05:38:37 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/design-template.xml	23 Jun 2016 08:32:46 -0000	1.8.14.1
@@ -93,7 +93,7 @@
     
 
     
-      Note: it's entirely possible that a discussion of what a package
+      Note: it's entirely possible that a discussion of what a package
       is not intended to do differs from a discussion of future
       improvements for the package.
     
@@ -140,7 +140,7 @@
 
     
       Note that such a discussion may differ from a discussion of a
-      package's potential future improvements.
+      package's potential future improvements.
     
 
   
@@ -187,7 +187,7 @@
     
 
     
-      Here's where you discuss the abstractions used by your package, such
+      Here's where you discuss the abstractions used by your package, such
       as the procedures encapsulating the legal transactions on the data
       model.  Explain the organization of procedures and their
       particulars (detail above and beyond what is documented in the
@@ -210,7 +210,7 @@
       Remember that the correctness, completeness, and stability of the API
       and interface are what experienced members of our audience are looking
       for.  This is a cultural shift for us at aD (as of mid-year 2000), in
-      that we've previously always looked at the data models as key, and
+      that we've previously always looked at the data models as key, and
       seldom spent much effort on the API (e.g. putting raw SQL in pages to
       handle transactions, instead of encapsulating them via procedures).
       Experience has taught us that we need to focus on the API for
@@ -279,8 +279,8 @@
 
     
       You may want to include page mockups, site-maps, or other visual aids.
-      Ideally this section is informed by some prototyping you've done, to
-      establish the package's usability with the client and other interested
+      Ideally this section is informed by some prototyping you've done, to
+      establish the package's usability with the client and other interested
       parties.
     
 
@@ -293,7 +293,7 @@
 
     
       Finally, note that as our templating system becomes more entrenched
-      within the OpenACS, this section's details are likely to shift from UI
+      within the OpenACS, this section's details are likely to shift from UI
       specifics to template interface specifics.
     
 
@@ -337,8 +337,8 @@
 
 
     
-      Although a system's data model file often contains this information,
-      this isn't always the case.  Furthermore, data model files often
+      Although a system's data model file often contains this information,
+      this isn't always the case.  Furthermore, data model files often
       undergo substantial revision, making it difficult to track down the
       system creator. An additional complication: package documentation may
       be authored by people not directly involved in coding.  Thus to avoid
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml,v
diff -u -N -r1.14 -r1.14.6.1
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml	11 Dec 2010 23:36:32 -0000	1.14
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml	23 Jun 2016 08:32:46 -0000	1.14.6.1
@@ -24,7 +24,7 @@
  
     
       The history of OpenACS documentation:  ..began by
-      building on a good documentation base from ArsDigita's ACS in the
+      building on a good documentation base from ArsDigita's ACS in the
       late 1990's. Some sections of the documentation, however, lacked
       details and examples; others simply did not exist. The OpenACS
       community began meeting the challenge by identifying needs and
@@ -53,7 +53,7 @@
       developers had to learn the system through experience with
       working with it and discussion in the forums.  Informal sharing
       of experiential and tacit knowledge has become the OpenACS
-      community's main method of sharing knowledge.
+      community's main method of sharing knowledge.
     
     
       This document attempts to shape ongoing documentation efforts by
@@ -225,7 +225,7 @@
         documentation is organized. 
       
       
-        The use licenses between OpenACS and Arsdigita's ACS are not
+        The use licenses between OpenACS and Arsdigita's ACS are not
         compatible, thereby creating strict limits on how much
         OpenACS developers should have access to Arsdigita code and
         resources.  The OpenACS documentation has a new legal
@@ -422,8 +422,8 @@
       
         Create a long bulleted list of features. Feature list should
         go deeper than high-level feature lists and look at the
-        quality of the implementations (from the user's perspective,
-        not the programmer's).  Example issues an end-user may have
+        quality of the implementations (from the user's perspective,
+        not the programmer's).  Example issues an end-user may have
         questions about: Ticket Tracker and Ticket Tracker Lite, why
         would I want one of them vs the other? And, before I specify
         to download and install it, what credit card gateways are
@@ -476,7 +476,7 @@
       
         Create a list of administrative tools that are useful to
         administrating OpenACS, including developer support,
-        schema-browser and api browser. Link to AOLserver's config
+        schema-browser and api browser. Link to AOLserver's config
         file documentation.
       
       
@@ -697,7 +697,7 @@
       
       
         Add overview diagrams showing the core parts of the
-        datamodel including an updated summary of Greenspun's
+        datamodel including an updated summary of Greenspun's
         Chapter 4: Data Models and the Object System 
       
       
@@ -868,7 +868,7 @@
     
     
       The following DocBook primer walks you through the basics, and should cover the
-      needs for 95 percent of the documentation we produce. You are welcome to explore DocBook's
+      needs for 95 percent of the documentation we produce. You are welcome to explore DocBook's
       
     list of elements and use more exotic features in your
       documents. The list is made up of SGML-elements but basically
@@ -921,7 +921,7 @@
     XSL
     Stylesheets (docbook-xsl) - The stylesheets to convert
     to HTML. We have been using a stylesheet based upon
-    NWalsh's chunk.xsl.
+    NWalsh's chunk.xsl.
     
       
       
@@ -991,7 +991,7 @@
              |
              +--sect2           : Sections - functional requirements
                  |
-                 +--sect3       : Subsections - Programmer's API
+                 +--sect3       : Subsections - Programmer's API
                      |
                     ...         : ...
     
@@ -1024,7 +1024,7 @@
       id, is standard and can be used with all elements. It comes in  very 
       handy when interlinking between documents (more about this when talking about links in ). 
       The value of id has to be unique 
-      throughout the book you're making since the id's in your 
+      throughout the book you're making since the id's in your 
       sect1's will turn into filenames when the book is parsed into HTML.
     
 
@@ -1036,7 +1036,7 @@
 
     
       Right after the opening tag you put the title of the document - this is usually the same as 
-      xreflabel-attribute. E.g. the top level of the document you're
+      xreflabel-attribute. E.g. the top level of the document you're
       reading right now looks like this:
     
 
@@ -1104,7 +1104,7 @@
 
     
       Linking
-      Linking falls into two different categories: inside the book you're making and outside:
+      Linking falls into two different categories: inside the book you're making and outside:
     
 
 
@@ -1117,7 +1117,7 @@
         with a simple tag, regardless of where that part is.
       
 
-      xreflinkendCheck out how I link to a subsection of the Developer's Guide:
+      xreflinkendCheck out how I link to a subsection of the Developer's Guide:
 
 
       Put this in your XML:
@@ -1152,7 +1152,7 @@
         
       
 
-      If the section you link to hasn't a specified xreflabel-attribute,
+      If the section you link to hasn't a specified xreflabel-attribute,
         the link is going to look like this:
 
 
@@ -1171,7 +1171,7 @@
 
 
       
-        Note that since I haven't provided an xreflabel for the subsection, 
+        Note that since I haven't provided an xreflabel for the subsection, 
         packages-looks, the
         parser will try its best to explain where the link takes you.
       
@@ -1184,7 +1184,7 @@
     2. Linking outside the documentation
     
         ulink
-        If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just
+        If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just
         a little different
 
         (<ulink>):
@@ -1261,7 +1261,7 @@
 
     
       lists
-      Here's how you make the DocBook equivalent of the three usual HTML-lists:
+      Here's how you make the DocBook equivalent of the three usual HTML-lists:
     
 
     
@@ -1311,7 +1311,7 @@
       
     3. How to make a <dl>
     
-        This kind of list is called a variablelist and these are the tags you'll need to 
+        This kind of list is called a variablelist and these are the tags you'll need to 
         make it happen:
         <variablelist>,
         <varlistentry>, 
@@ -1430,7 +1430,7 @@
     
 
     
-      The <emphasis> tag defaults to italics when parsed. If you're looking for 
+      The <emphasis> tag defaults to italics when parsed. If you're looking for 
       emphasizing with bold type, use <emphasis role="strong">.
     
 
@@ -1486,7 +1486,7 @@
     
     
       
-      This example uses Daniel Veillard's xsltproc command available
       as part of libxslt from http://www.xmlsoft.org/XSLT/.
@@ -1539,7 +1539,7 @@
       wrote an intro to the PSGML Mode in Emacs
     
       
-      James Clark's free Java parser
+      James Clark's free Java parser
       XP. Note that
       this does not validate XML, only parses it.
       
@@ -1562,7 +1562,7 @@
     
       In the process of transforming your HTML into XML, 
       HTML tidy
-      can be a handy tool to make your HTML "regexp'able".
+      can be a handy tool to make your HTML "regexp'able".
       Brandoch Calef has made a 
       Perl
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/eng-standards-versioning.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/eng-standards-versioning.xml,v
diff -u -N -r1.10 -r1.10.14.1
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/eng-standards-versioning.xml	17 Jul 2006 05:38:37 -0000	1.10
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/eng-standards-versioning.xml	23 Jun 2016 08:32:46 -0000	1.10.14.1
@@ -195,7 +195,7 @@
       
       
         The distance from OLDVERSION to NEWVERSION should never span a release.   For example if we had a bug fix in
-acs-kernel on 5.1.0 you wouldn't want a file upgrade-5.0.4-5.1.0d1.sql since if you subsequently need to provide a 5.0.4-5.0.5 upgrade you will have to rename the 5.0.4-5.1.0 upgrade since you can't have upgrades which overlap like that.  Instead, use upgrade-5.1.0d1-5.1.0d2.sql
+acs-kernel on 5.1.0 you wouldn't want a file upgrade-5.0.4-5.1.0d1.sql since if you subsequently need to provide a 5.0.4-5.0.5 upgrade you will have to rename the 5.0.4-5.1.0 upgrade since you can't have upgrades which overlap like that.  Instead, use upgrade-5.1.0d1-5.1.0d2.sql
 
       
     
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/filenaming.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/filenaming.xml,v
diff -u -N -r1.7 -r1.7.2.1
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/filenaming.xml	27 Oct 2014 16:39:31 -0000	1.7
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/filenaming.xml	23 Jun 2016 08:32:46 -0000	1.7.2.1
@@ -47,14 +47,14 @@
 
 
 
-For example, the page to erase a user's portrait from the database is
+For example, the page to erase a user's portrait from the database is
 /admin/users/portrait-erase.tcl.
 
 
 
 However, modules typically deal with only one primary type of object -
 e.g.,
-the Bookmarks module deals mainly with bookmarks - and so action-type files in modules don't need to be specified by the object they act on.  Example: the user pages
+the Bookmarks module deals mainly with bookmarks - and so action-type files in modules don't need to be specified by the object they act on.  Example: the user pages
 for the Bookmarks module live in the /bookmarks/
 directory, and so there is no need to name the bookmark editing page with a redundant url: /bookmarks/bookmark-edit.tcl. Instead, we omit the object type, and use this convention:
 
@@ -261,9 +261,9 @@
 # www/register/user-login-2.tcl
 
 ad_page_contract {
-    Verify the user's password and issue the cookie.
+    Verify the user's password and issue the cookie.
     
-    @param user_id The user's id in users table.
+    @param user_id The user's id in users table.
     @param password_from_from The password the user entered.
     @param return_url What url to return to after successful login.
     @param persistent_cookie_p Specifies whether a cookie should be set to keep the user logged in forever.
@@ -297,7 +297,7 @@
 ad_page_variables flags.
 
 There are new flags: trim, notnull and
-optional. They do what you'd expect; values will not be
+optional. They do what you'd expect; values will not be
 trimmed, unless you mark them for it; empty strings are valid input, unless
 you specify notnull; and a specified variable will be considered required,
 unless you declare it optional.
@@ -323,7 +323,7 @@
 For shared Tcl library files, use ad_library after
 the file path comment. Its only argument is a doc_string in the
 standard (javadoc-style) format, like
-ad_page_contract. Don't forget to put the @cvs-id in
+ad_page_contract. Don't forget to put the @cvs-id in
 there.  Here is an example of using ad_library:
 
  
@@ -350,7 +350,7 @@
 
 -- path relative to the ACS root directory
 --
--- brief description of the file's purpose
+-- brief description of the file's purpose
 --
 -- author
 -- created
@@ -415,7 +415,7 @@
 resource (namely, a database handle) for an unpredictable amount of
 time while sending packets back to the browser, and so it should be
 avoided in most cases. (On the other hand, for a page that requires an
-expensive database query, it's better to call
+expensive database query, it's better to call
 
 ad_return_top_of_page
 
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/plsql.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/plsql.xml,v
diff -u -N -r1.6 -r1.6.14.1
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/plsql.xml	17 Jul 2006 05:38:37 -0000	1.6
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/plsql.xml	23 Jun 2016 08:32:46 -0000	1.6.14.1
@@ -109,7 +109,7 @@
    
    
     Name parameters as simply as possible, i.e., use the column name
-    if the parameter corresponds to a table column. We're deprecating
+    if the parameter corresponds to a table column. We're deprecating
     the v_* and *_in syntax in favor of named parameters notation:
          
 
@@ -174,7 +174,7 @@
    
    
     Use 't' and 'f' for booleans, not the PL/SQL "boolean" datatype
-    because it can't be used in SQL queries.
+    because it can't be used in SQL queries.
    
 
    
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/requirements-template.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/requirements-template.xml,v
diff -u -N -r1.6 -r1.6.14.1
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/requirements-template.xml	17 Jul 2006 05:38:37 -0000	1.6
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/requirements-template.xml	23 Jun 2016 08:32:46 -0000	1.6.14.1
@@ -38,7 +38,7 @@
       Very broadly, describe how the system meets a need of a business,
 	group, the OpenACS as a whole, etc.  Make sure that technical and
 	non-technical readers alike would understand what the system would do
-	and why it's useful.  Whenever applicable, you should explicitly state
+	and why it's useful.  Whenever applicable, you should explicitly state
 	what the business value of the system is. 
     
 
@@ -56,7 +56,7 @@
 
     
       You should also state the context and dependencies of the system
-	here, e.g. if it's an application-level package for OpenACS 4, briefly
+	here, e.g. if it's an application-level package for OpenACS 4, briefly
 	describe how it uses kernel services, like permissions or subsites. 
     
 
@@ -81,7 +81,7 @@
 
     
       Describe other systems or services that are comparable to what
-	you're building.  If applicable, say why your implementation will be
+	you're building.  If applicable, say why your implementation will be
 	superior, where it will match the competition, and where/why it will
 	lack existing best-of-breed capabilities.  This section is also in the
 	Design doc, so write about it where you deem most appropriate.
@@ -98,8 +98,8 @@
     
        System/Package "coversheet" - where all documentation for this software is linked off of
        Design document
-       Developer's guide
-       User's guide
+       Developer's guide
+       User's guide
        Other-cool-system-related-to-this-one document
        Test plan 
        Competitive system(s)
@@ -118,7 +118,7 @@
 	create a list denominated with unique identifiers that reflect any
 	functional hierarchy present, e.g. 20.5.13. - for the first number,
 	leave generous gaps on the first writing of requirements (e.g. 1, 10,
-	20, 30, 40, etc.) because you'll want to leave room for any missing
+	20, 30, 40, etc.) because you'll want to leave room for any missing
 	key requirements that may arise.  
     
     
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/style-guide.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/style-guide.xml,v
diff -u -N -r1.3 -r1.3.14.1
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/style-guide.xml	17 Jul 2006 05:38:37 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/style-guide.xml	23 Jun 2016 08:32:46 -0000	1.3.14.1
@@ -29,7 +29,7 @@
       procedures.
     
     
-      When confronted by this much complexity it's important to be
+      When confronted by this much complexity it's important to be
       able to make sense of it without having to wade through it all.
       Things should be coherent, things should be named predictably
       and behave like you would expect, and your guess about what
@@ -62,7 +62,7 @@
             scripts and tcl library files must be named properly to be
             used), while some are suggestions (the
             object-verb naming convention) which
-            if ignored won't break anything, but if you follow the
+            if ignored won't break anything, but if you follow the
             rules people will be able to understand your package much
             more easily.
           
@@ -124,7 +124,7 @@
           
             The code base is very large and if things are formatted
             consistently it is easier to read.  Also, if it conforms
-            to the standard it won't be reformatted (which can mask
+            to the standard it won't be reformatted (which can mask
             the change history and making tracking down bugs much
             harder).  Using spaces rather than tabs makes patches
             easier to read and manage and does not force other
@@ -139,9 +139,9 @@
         
           Use the standard APIs
           
-            Don't reinvent the wheel.  Prefer extending an existing
+            Don't reinvent the wheel.  Prefer extending an existing
             core API to creating your own.  If something in the core
-            does not meet your particular needs it probably won't meet
+            does not meet your particular needs it probably won't meet
             others as well and fleshing out the core API's makes the
             toolkit more useful for everyone and more easily extended.
           
@@ -173,7 +173,7 @@
         
         
           Create bug tracker tickets for things you are going to work
-          on yourself (just in case you don't get to it and to act as
+          on yourself (just in case you don't get to it and to act as
           a pointer for others who might encounter the same problem).
         
       
Index: openacs-4/packages/acs-core-docs/www/xml/for-everyone/acs-faq.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/for-everyone/acs-faq.xml,v
diff -u -N -r1.8 -r1.8.14.1
--- openacs-4/packages/acs-core-docs/www/xml/for-everyone/acs-faq.xml	17 Jul 2006 05:38:37 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/xml/for-everyone/acs-faq.xml	23 Jun 2016 08:32:46 -0000	1.8.14.1
@@ -118,7 +118,7 @@
 
 During the exuberance of the dot com boom, training
 	  was provided for free at ArsDigita and other locations. But
-	  now you'll probably have to pay for some training from one
+	  now you'll probably have to pay for some training from one
 	  of the companies that do OpenACS work: http://openacs.org/community/
             
@@ -140,7 +140,7 @@
 
     
       NOTE: This material was provided by ArsDigita
-      Corporation. As ArsDigita has ceased their operations, we don't
+      Corporation. As ArsDigita has ceased their operations, we don't
       know for how long the following URLs will be operational, and we
       could not simply mirror them before asking permission from the
       authors. If arsdigita.com goes dead, you can find these
Index: openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml,v
diff -u -N -r1.30.2.6 -r1.30.2.7
--- openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml	1 Dec 2015 14:38:54 -0000	1.30.2.6
+++ openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml	23 Jun 2016 08:32:46 -0000	1.30.2.7
@@ -494,8 +494,8 @@
     
       
         
-          Made changes that extend acs-kernel's create_type and create_attribute procs,
-          so they're optionally able to create sql tables and columns.  Optional metadata
+          Made changes that extend acs-kernel's create_type and create_attribute procs,
+          so they're optionally able to create sql tables and columns.  Optional metadata
           params allow for the automatic generation of foreign key references, check
           exprs, etc.
         
@@ -512,13 +512,13 @@
           Added new package dependency type, "embeds".  This is a variant of the
           "extends" package dependency type added in OpenACS 5.5.0.  It allows one
           to write embeddable packages, with scripts made visible in client packages
-          using URLs which include the embedded package's package key.  An example
+          using URLs which include the embedded package's package key.  An example
           embeddable package might be a rewritten "attachments" package.  The current
           implementation requires a global instance be mounted, and client packages
           generate urls to that global instance.  Among other things, this leads to
           the user navigating to the top-level subsite, losing any subsite theming
           that might be associated with a community.  Using "embeds", a rewritten
-          package would run in the client package's context, maintaining theming and
+          package would run in the client package's context, maintaining theming and
           automatically associating attachments with the client package.
         
         
@@ -611,7 +611,7 @@
       
         This is a minor bugfix release.
         
-        Site node caching was removed as doesn't work correctly
+        Site node caching was removed as doesn't work correctly
         Critical issues with search on oracle were fixed
         More html strict work etc
       
@@ -640,9 +640,9 @@
               in the API browser for details.
               
         Templates have been modified to comply with HTML strict
-        The Search package's results page has been improved
+        The Search package's results page has been improved
         TinyMCE WYSIWYG support has been added, RTE and HTMLArea support dropped
-        acs-mail-lite's send has been cleaned up to properly encode content, to handle
+        acs-mail-lite's send has been cleaned up to properly encode content, to handle
               file attachments, etc.  "complex-send" will disappear from acs-core in a future
               release.
       
@@ -855,7 +855,7 @@
         You may want to begin by reading our installation documentation for
         .  Note that the Windows documentation is
         not current for OpenACS &version;, but an alternative is to use John
-        Sequeira's Oasis VM
         project.
   
@@ -889,7 +889,7 @@
           authentication, password management, account creation, and account import mechanisms.
 
           This includes improvements to the basic cookie handling, so logins can be expired without the 
-          user's identity being completely lost. You can set login to expire after a certain period 
+          user's identity being completely lost. You can set login to expire after a certain period 
           (e.g. 8 hours, then password must be refreshed), or you can have all issues login cookies
           expired at once, e.g. if you have left a permanent login cookie on a public machine somewhere.
         
@@ -907,12 +907,12 @@
           administration, your workspace, and login/logout, and is rendered
           using CSS.
 
-          And there's a new community template
+          And there's a new community template
           (/packages/acs-subsite/www/group-master), which provides useful
           navigation to the applications and administrative UI in a
           subsite.
 
-          In addition, there's new, simpler UI for managing members of a
+          In addition, there's new, simpler UI for managing members of a
           subsite, instantiating and mounting applications, setting
           permissions, parameters, etc.
 
@@ -923,7 +923,7 @@
 
           The list builder has been added for easily generating templated
           tables and lists, with features such as filtering, sorting,
-          actions on multiple rows with checkboxes, etc. Most of all, it's
+          actions on multiple rows with checkboxes, etc. Most of all, it's
           fast to use, and results in consistently-looking,
           consistently-behaving, templated tables.
         
@@ -956,7 +956,7 @@
 
       
         
-          Who's online feature.
+          Who's online feature.
         
       
 
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml,v
diff -u -N -r1.22 -r1.22.14.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml	17 Jul 2006 05:38:37 -0000	1.22
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml	23 Jun 2016 08:32:46 -0000	1.22.14.1
@@ -17,7 +17,7 @@
     Aolserver or Postgres. Several people have
     reported problems while trying to install using apt-get
     instead of from source. If you have the time to debug these
-    and submit what you did, that's great, but if not, you
+    and submit what you did, that's great, but if not, you
     should stick to installing from source. 
   
 
@@ -74,7 +74,7 @@
 
       conf-inst should contain the
           location where AOLserver is to be installed.  Overwrite the
-          tarball's default value with our default value, /usr/local/aolserver:
+          tarball's default value with our default value, /usr/local/aolserver:
       [root aolserver]# echo "/usr/local/aolserver" > conf-inst
 [root aolserver]#
       
@@ -126,7 +126,7 @@
 	  sets database environment variables before starting
 	  AOLserver; this allows the AOLserver instance can
 	  communicate with the database.  There is one script each for
-	  Oracle and PostgreSQL.  They don't conflict, so if you plan
+	  Oracle and PostgreSQL.  They don't conflict, so if you plan
 	  to use both databases, install both.
       
       
@@ -228,7 +228,7 @@
     
       
         Test AOLserver
-      In order to test AOLserver, we'll run it using the
+      In order to test AOLserver, we'll run it using the
       sample-config.tcl file provided in the AOLserver distribution,
       under the nobody user and web
       group.  The sample-config.tcl configuration writes to the
@@ -260,8 +260,8 @@
       Note: AOLserver4.x does not include a default start page, so we create one for this test. Type 
         echo "Welcome to AOLserver" > /usr/local/aolserver40r8/servers/server1/pages/index.html
       
-      Now, we'll run a quick test to ensure AOLserver is running
-          correctly. We'll use the sample config file provided with
+      Now, we'll run a quick test to ensure AOLserver is running
+          correctly. We'll use the sample config file provided with
           AOLserver. This file will attempt to guess your IP address and
           hostname. It will then start up the server at port 8000 of that
           IP address.
@@ -274,7 +274,7 @@
 [08/Mar/2003:15:07:18][31175.8192][-main-] Notice: config.tcl: finished reading
 config file.
 
-        The first warning, about nsssl, can be ignored.  We won't be using nsssl; we'll be using nsopenssl instead, and we haven't fully configured it yet.  The nscp warning refers to the fact that, without a user and password in the config file, the administrative panel of AOLserver won't load.  We don't plan to use it and can ignore that error as well.  Any other warning or error is unexpected and probably a problem.
+        The first warning, about nsssl, can be ignored.  We won't be using nsssl; we'll be using nsopenssl instead, and we haven't fully configured it yet.  The nscp warning refers to the fact that, without a user and password in the config file, the administrative panel of AOLserver won't load.  We don't plan to use it and can ignore that error as well.  Any other warning or error is unexpected and probably a problem.
 
       
 
@@ -283,7 +283,7 @@
           Lynx on the same
           computer and surfing over to your web page.  If
           you browse from another computer and the sample config file
-          didn't guess your hostname or ip correctly, you'll get a
+          didn't guess your hostname or ip correctly, you'll get a
           false negative test.
 
         
@@ -293,9 +293,9 @@
         
 
           You should see a "Welcome to AOLserver" page. If this
-          doesn't work, try going to
+          doesn't work, try going to
           http://127.0.0.1:8000/. If this
-          still doesn't work, check out the  section below.  Note that you will not be able to browse to the web page from another machine, because AOLserver is only listening to the local address.
 
         
@@ -319,7 +319,7 @@
           xreflabel="Troubleshooting AOLserver">
       
         Troubleshooting.
-      If you can't view the welcome page, it's likely there's a
+      If you can't view the welcome page, it's likely there's a
       problem with your server configuration. Start by viewing your
       AOLserver log, which is in
       /usr/local/aolserver/log/server.log.
@@ -353,10 +353,10 @@
 
     
 
-      If you get an error that nssock can't get the requested address, you
+      If you get an error that nssock can't get the requested address, you
       can set these manually. If you type 0.0.0.0, AOLserver will try to
       listen on all available addresses.  Note:
-      ns_info address doesn't appear
+      ns_info address doesn't appear
       to be supported in current versions of AOLserver.
 
     
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver4.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver4.xml,v
diff -u -N -r1.31 -r1.31.2.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver4.xml	27 Oct 2014 16:39:31 -0000	1.31
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver4.xml	23 Jun 2016 08:32:46 -0000	1.31.2.1
@@ -39,7 +39,7 @@
         Note for Debian users: you can apt-get install
       tcl8.4-dev if you have the right version (stable users will need
       to add tcl8.4 to their sources.list file as described on the
-      Install Postgres page). You'll
+      Install Postgres page). You'll
       have to use /usr/lib/tcl8.4/ instead of /usr/local/lib when you
       try to find the tcl libraries, however.
 
@@ -200,7 +200,7 @@
       Note that this section requires you to have OpenACS files available, which
       you can get through CVS, through a tarball, or by other
       means. You can come back to this section after you acquire the
-      OpenACS code, but don't forget to come back. (Note to
+      OpenACS code, but don't forget to come back. (Note to
       maintainers: this should be moved to the next page and
       integrated into the text there)
     
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/configuring.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/configuring.xml,v
diff -u -N -r1.13 -r1.13.2.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/configuring.xml	27 Oct 2014 16:39:31 -0000	1.13
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/configuring.xml	23 Jun 2016 08:32:46 -0000	1.13.2.1
@@ -22,22 +22,22 @@
       Installing OpenACS packages
 
       An OpenACS package extends your website and lets it do
-      things it wasn't able to do before. You can have a weblog, a
+      things it wasn't able to do before. You can have a weblog, a
       forums, a calendar, or even do sophisticated project-management
       via your website.
 
-      After you've installed OpenACS, you can congratulate
-      yourself for a job well done. Then, you'll probably want to
+      After you've installed OpenACS, you can congratulate
+      yourself for a job well done. Then, you'll probably want to
       install a couple of packages.
 
       To install packages, you have to be an administrator on
-      the OpenACS webserver. Log in, and you'll see a link to Admin or
+      the OpenACS webserver. Log in, and you'll see a link to Admin or
       the Control Panel. Click on that, then click on 'Install
       software'. Packages are sometimes also referred to as
       applications or software.
 
-      At this point, you'll need to determine whether or not
-      you're able to install from the repository, or whether you
+      At this point, you'll need to determine whether or not
+      you're able to install from the repository, or whether you
       should install from local files.
 
       Basically, if you have a local CVS repository, or have
@@ -48,7 +48,7 @@
       from Repository' or 'Install from Local'. Select the package,
       and click 'Install checked applications'. The system will check
       to make sure you have all necessary packages that the package
-      you want depends on. If you're installing from Local Files, and
+      you want depends on. If you're installing from Local Files, and
       you are missing any packages, you may have to add the packages
       your desired package depends on: 
         
@@ -71,23 +71,23 @@
     
       Mounting OpenACS packages
 
-      After you've installed your packages, you have to 'mount'
+      After you've installed your packages, you have to 'mount'
       them in order to make them appear on your website.
 
       Make sure you are logged in, and then click on the
       'Admin' or 'Control Panel' link to get to the Site-Wide
-      Administration page (at /acs-admin). Click on the subsite you'd
+      Administration page (at /acs-admin). Click on the subsite you'd
       like the application to be available at.
 
       Subsites are a way of dividing your website into logical
       chunks. Often they represent different groups of users, or parts
       of an organization. 
 
       Now click on 'Applications' (applications are the same
-      thing as packages). You'll see a list of Applications and the
+      thing as packages). You'll see a list of Applications and the
       URLs that each is located at. To mount a new application, you
       click on 'Add application', enter the Application, title
-      (application name), and URL (URL folder name), and you're
+      (application name), and URL (URL folder name), and you're
       done.
 
       Test it out now. The URL is based on a combination of the
@@ -109,7 +109,7 @@
     
     
       Configuring an OpenACS package
-      After you've installed and mounted your package, you can
+      After you've installed and mounted your package, you can
       configure each instance to act as you would like. 
 
       This is done from the Applications page. Log in, go to the
@@ -127,7 +127,7 @@
     
     
       Setting Permission on an OpenACS package
-      After you've installed and mounted your package, you can
+      After you've installed and mounted your package, you can
       configure each instance to act as you would like. 
 
       This is done from the Applications page. Log in, go to the
@@ -196,13 +196,13 @@
     cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-subsite/www/index* /var/lib/aolserver/$OPENACS_SERVICE_NAME/www
         
         
-          Edit the new index.adp to change the text; you shouldn't need to edit index.tcl unless you are adding new functionality.
+          Edit the new index.adp to change the text; you shouldn't need to edit index.tcl unless you are adding new functionality.
         
       
     
     
       How do I change the site-wide style?
-      Almost all pages on an OpenACS site use ACS Templating, and so their appearance is driven by a layer of different files.  Let's examine how this works:
+      Almost all pages on an OpenACS site use ACS Templating, and so their appearance is driven by a layer of different files.  Let's examine how this works:
       
         
           
@@ -261,12 +261,12 @@
         
           
             Finding the problem
-            We start with the page that has the error.  In the URL it's http://myserver.net/events/event-info.tcl, so open the file /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/events/www/event-info.tcl.  It contains this line:
+            We start with the page that has the error.  In the URL it's http://myserver.net/events/event-info.tcl, so open the file /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/events/www/event-info.tcl.  It contains this line:
           
           set can_register_p [events::security::can_register_for_event_p -event_id $event_id]
           We need to know what that procedure does, so go to /api-doc, paste events::security::can_register_for_event_p into the ACS Tcl API Search box, and click Feeling Lucky.  The next pages shows the proc, and we click "show source" to see more information.  The body of the proc is simply
           return [permission::permission_p -party_id $user_id -object_id $event_id -privilege write]
-          This means that a given user must have the write privilige on the event in order to register.  Let's assume that the priviliges inherit, so that if a user has the write privilige on the whole package, they will have the write privilege on the event.
+          This means that a given user must have the write privilige on the event in order to register.  Let's assume that the priviliges inherit, so that if a user has the write privilige on the whole package, they will have the write privilege on the event.
         
         
           
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml,v
diff -u -N -r1.12 -r1.12.14.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml	17 Jul 2006 05:38:37 -0000	1.12
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml	23 Jun 2016 08:32:46 -0000	1.12.14.1
@@ -25,7 +25,7 @@
 	  
 
 	   
-		  Gilbert Wong's FreeBSD
+		  Gilbert Wong's FreeBSD
 		  installation guide
 		 
 
@@ -69,9 +69,9 @@
     Where did this document come from?
     
       This document was created by Vinod Kurup, but it's really
+      url="mailto:vinod@kurup.com">Vinod Kurup, but it's really
       just plagiarism from a number of documents that came before it. If
-      I've used something that you've written without proper credit, let me
+      I've used something that you've written without proper credit, let me
       know and I'll fix it right away.
     
     Versions 4.6.2 to present were edited by  
 
        
-          Gilbert Wong's FreeBSD
+          Gilbert Wong's FreeBSD
           installation guide
          
 
        
-          Vinod Kurup's Brief OpenACS4
+          Vinod Kurup's Brief OpenACS4
           installation guide
         
 
        
           Joel
-          Aufrecht's OpenACS 4.5 Quick Guide.
+          Aufrecht's OpenACS 4.5 Quick Guide.
          
 
     
@@ -113,7 +113,7 @@
     
        
     Linux Install Guides
     
-      Here's a list of some helpful documentation for various OS's
+      Here's a list of some helpful documentation for various OS's
     
 
     
@@ -156,7 +156,7 @@
   
        
     Security Information
     
-      Once you get your OS installed, it's imperative that you secure your
+      Once you get your OS installed, it's imperative that you secure your
       installation. As Jon Griffin repeatedly warns us, "No distribution is
       secure out of the box."  The Reference Platform implements
       some basic precautions, but security is a process, not a
@@ -175,7 +175,7 @@
       
        
           Jon
-          Griffin's notes
+          Griffin's notes
           
        
           Linux Administrators
@@ -190,7 +190,7 @@
        
           Bruce
-          Schneier's Crypto-Gram, especially , especially The
           security patch treadmill and Monitoring First.
@@ -214,7 +214,7 @@
 
             Philip
-            and Alex's Guide to Web Publishing - A very readable
+            and Alex's Guide to Web Publishing - A very readable
             guide to database-backed community websites.
 
           
@@ -241,7 +241,7 @@
 
             UNIX
-            System Administrator's Bible -  (LePage and Iarerra 1998;
+            System Administrator's Bible -  (LePage and Iarerra 1998;
             IDG) 
 
           
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/database-maintenance.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/database-maintenance.xml,v
diff -u -N -r1.8 -r1.8.14.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/database-maintenance.xml	17 Jul 2006 05:38:37 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/database-maintenance.xml	23 Jun 2016 08:32:46 -0000	1.8.14.1
@@ -16,7 +16,7 @@
 
       To run a database on a different machine than the
       webserver requires changes to the database configuration file
-      and access control file, and to the OpenACS service's
+      and access control file, and to the OpenACS service's
       configuration file.
       
         
@@ -33,7 +33,7 @@
           controlled ... (add notes from forum post) 
         
         
-          Change the OpenACS service's configuration file to
+          Change the OpenACS service's configuration file to
           point to the remote database.  Edit
           /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl
           and change
@@ -90,8 +90,8 @@
       
         Dropping a PostgreSQL tablespace is easy. You have to stop any
         AOLserver instances that are using the database that you wish to
-        drop. If you're using daemontools, this is simple, just use the
-        'down' flag (-d). If you're using inittab, you have to comment out
+        drop. If you're using daemontools, this is simple, just use the
+        'down' flag (-d). If you're using inittab, you have to comment out
         your server in /etc/inittab,
         reread the inittab with /sbin/init
         q, and then restart-aolserver
@@ -114,18 +114,18 @@
       data can make a tremendous difference in the execution speed of
       queries. This command can also be run from cron, but it probably makes
       more sense to run this command as part of your nightly backup
-      procedure - if "vacuum" is going to screw up the database, you'd
-      prefer it to happen immediately after (not before!) you've made a
+      procedure - if "vacuum" is going to screw up the database, you'd
+      prefer it to happen immediately after (not before!) you've made a
       backup! The "vacuum" command is very reliable, but conservatism is
-      the key to good system management. So, if you're using the export
-      procedure described above, you don't need to do this extra
+      the key to good system management. So, if you're using the export
+      procedure described above, you don't need to do this extra
       step.
     
 
     Edit your crontab:
     [joeuser ~]$ crontab -e
 
-    We'll set vacuum up to run nightly at 1 AM. Add the following
+    We'll set vacuum up to run nightly at 1 AM. Add the following
     line:
     
 0 1 * * * /usr/local/pgsql/bin/vacuumdb $OPENACS_SERVICE_NAME
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml,v
diff -u -N -r1.30 -r1.30.6.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml	11 Dec 2010 23:36:32 -0000	1.30
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml	23 Jun 2016 08:32:46 -0000	1.30.6.1
@@ -130,7 +130,7 @@
       
             
 
-        Most of this information comes from Tom Jackson's AOLserver+Daemontools
           Mini-HOWTO.
 
@@ -202,12 +202,12 @@
              
 				Install a script called
 				restart-aolserver. This
-				script doesn't actually restart AOLserver - it just kills
+				script doesn't actually restart AOLserver - it just kills
 				it.  
 			  
             
             
-				Ask the OS to restart our service whenever it's not
+				Ask the OS to restart our service whenever it's not
 				running. We do this by adding a line to
 				/etc/inittab.
 			  
@@ -250,8 +250,8 @@
 
        
 			Test the restart-aolserver
-			script. We'll first kill all running servers to clean the
-			slate. Then, we'll start one server and use
+			script. We'll first kill all running servers to clean the
+			slate. Then, we'll start one server and use
 			restart-aolserver to kill
 			it. If it works, then there should be no more servers
 			running. You should see the following lines. 
@@ -352,7 +352,7 @@
     
 
     If you want to install two services with different host
-    names sharing the same ip, you'll need nsvhr to redirect requests
+    names sharing the same ip, you'll need nsvhr to redirect requests
     based on the contents of the tcp headers.  See AOLserver
     Virtual Hosting with TCP by markd.
@@ -402,10 +402,10 @@
       To set up a developmental installation, first set up
       either your developmental installation or your production
       installation, and follow the instructions for committing your
-      files to CVS. We'll assume in this example that you set up the
+      files to CVS. We'll assume in this example that you set up the
       production server (service0). To set up the developmental instance,
       you then follow the intall guide again, this time creating a new
-      user (service0-dev) that you'll use for the new installation. To get
+      user (service0-dev) that you'll use for the new installation. To get
       the files for service0-dev, you check them out from cvs (check out
       service0). 
 
@@ -418,18 +418,18 @@
 emacs web/etc/daemontools/run
 
 
-      In the config.tcl file, you'll probably want to pay attention
+      In the config.tcl file, you'll probably want to pay attention
       the rollout support section. That will ensure that email on your
       developmental server will not be sent out to the general world.
 
       Also, instead of going through the OpenACS online
-      installer, you'll actually load live data into your production
+      installer, you'll actually load live data into your production
       server. 
 
       You can even automate the process of getting live data
       from your production server. Copy something like this to
-      /home/service0-dev/bin and put it in service0-dev's crontab to
-      run once a night. You'll need to make sure the database backups
+      /home/service0-dev/bin and put it in service0-dev's crontab to
+      run once a night. You'll need to make sure the database backups
       are set up in service0's crontab, and that if the servers are on
       different physical machines, that the database backup is copied
       to the developmental machine once per night.
@@ -462,7 +462,7 @@
 if the file is /var/lib/aolserver/service0-dev/www/index.adp, do: 
 
 cd /var/lib/aolserver/service0-dev/www
-cvs diff index.adp (this is optional; it's just a
+cvs diff index.adp (this is optional; it's just a
 reality check)
 the lines starting > will be added and the lines
 starting < will be removed, when you commit
@@ -480,7 +480,7 @@
 
       If you make changes that require changes to the database,
       test them out first on service0-dev, using either -create.sql or
-      upgrade scripts. Once you've tested them, you then update and
+      upgrade scripts. Once you've tested them, you then update and
       run the upgrade scripts from the package manager. 
 
 The production site can run "HEAD" from cvs.
@@ -570,7 +570,7 @@
 chmod 700 /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs            
           
           
-            It takes two files to support an SSL connection.  The certificate is the public half of the key pair - the server sends the certificate to browser requesting ssl.  The key is the private half of the key pair.  In addition, the certificate must be signed by Certificate Authority or browsers will protest.  Each web browser ships with a built-in list of acceptable Certificate Authorities (CAs) and their keys.  Only a site certificate signed by a known and approved CA will work smoothly.  Any other certificate will cause browsers to produce some messages or block the site.  Unfortunately, getting a site certificate signed by a CA costs money.  In this section, we'll generate an unsigned certificate which will work in most browsers, albeit with pop-up messages.
+            It takes two files to support an SSL connection.  The certificate is the public half of the key pair - the server sends the certificate to browser requesting ssl.  The key is the private half of the key pair.  In addition, the certificate must be signed by Certificate Authority or browsers will protest.  Each web browser ships with a built-in list of acceptable Certificate Authorities (CAs) and their keys.  Only a site certificate signed by a known and approved CA will work smoothly.  Any other certificate will cause browsers to produce some messages or block the site.  Unfortunately, getting a site certificate signed by a CA costs money.  In this section, we'll generate an unsigned certificate which will work in most browsers, albeit with pop-up messages.
             Use an OpenSSL perl script to generate a certificate and key.
 
         
@@ -592,7 +592,7 @@
             Enter a pass phrase for the CA certificate.  Then, answer the rest of the questions.  At the end you should see this:
         Certificate (and private key) is in newreq.pem
 [$OPENACS_SERVICE_NAME certs]$
-        newreq.pem contains our certificate and private key.  The key is protected by a passphrase, which means that we'll have to enter the pass phrase each time the server starts.  This is impractical and unnecessary, so we create an unprotected version of the key.  Security implication: if anyone gets access to the file keyfile.pem, they effectively own the key as much as you do.  Mitigation: don't use this key/cert combo for anything besides providing ssl for the web site.
+        newreq.pem contains our certificate and private key.  The key is protected by a passphrase, which means that we'll have to enter the pass phrase each time the server starts.  This is impractical and unnecessary, so we create an unprotected version of the key.  Security implication: if anyone gets access to the file keyfile.pem, they effectively own the key as much as you do.  Mitigation: don't use this key/cert combo for anything besides providing ssl for the web site.
             [root misc]# openssl rsa -in newreq.pem -out keyfile.pem
 read RSA key
 Enter PEM pass phrase:
@@ -642,9 +642,9 @@
         Edit
 /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/analog.cfg and change the variable in HOSTNAME "[my
 organisation]" to reflect your website title.  If you
-don't want the traffic log to be publicly visible, change
+don't want the traffic log to be publicly visible, change
 OUTFILE /var/lib/aolserver/$OPENACS_SERVICE_NAME/www/log/traffic.html to use a private
-directory. You'll also need to edit all instances of service0 to your $OPENACS_SERVICE_NAME.
+directory. You'll also need to edit all instances of service0 to your $OPENACS_SERVICE_NAME.
       
       
         Run it.
@@ -694,7 +694,7 @@
       Isolating and solving database problems.
     
       
-          Without daily internal maintenance, most databases slowly degrade in performance.  For PostGreSQL, see .  For Oracle, use exec dbms_stats.gather_schema_stats('SCHEMA_NAME') (Andrew Piskorski's Oracle notes).
+          Without daily internal maintenance, most databases slowly degrade in performance.  For PostGreSQL, see .  For Oracle, use exec dbms_stats.gather_schema_stats('SCHEMA_NAME') (Andrew Piskorski's Oracle notes).
       
       
         You can track the exact amount of time each database query on a page takes:
@@ -771,7 +771,7 @@
  order by s.username ,s.sid ,s.serial# ,sql.piece ;
         To kill a troubled process:
         alter system kill session 'SID,SERIAL#';  --substitute values for SID and SERIAL#
-        (See Andrew Piskorski's Oracle notes)
+        (See Andrew Piskorski's Oracle notes)
         
 
         
@@ -809,9 +809,9 @@
       what is going on inside Oracle. Oracle provides Statspack, a package to
       monitor and save the state of the v$ performance views. These reports
       help finding severe problems by exposing summary data about the Oracle
-      wait interface, executed queries. You'll find the installation
+      wait interface, executed queries. You'll find the installation
       instructions in $ORACLE_HOME/rdbms/admin/spdoc.txt. Follow the
-      instructions carefully and take periodic snapshots, this way you'll be
+      instructions carefully and take periodic snapshots, this way you'll be
       able to look at historical performance data.
     
 
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml,v
diff -u -N -r1.31 -r1.31.14.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml	17 Jul 2006 05:38:37 -0000	1.31
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml	23 Jun 2016 08:32:46 -0000	1.31.14.1
@@ -16,29 +16,29 @@
     
       AOLserver needs to be started as the root user if you want to use
       port 80. Once it starts, though, it will drop the root privileges and
-      run as another user, which you must specify on the command line. It's
+      run as another user, which you must specify on the command line. It's
       important that this user has as few privileges as possible. Why?
-      Because if an intruder somehow breaks in through AOLserver, you don't
+      Because if an intruder somehow breaks in through AOLserver, you don't
       want her to have any ability to do damage to the rest of your
       server.
 
         At the same time, AOLserver needs to have write access to
       some files on your system in order for OpenACS to function
-      properly. So, we'll run AOLserver with a different user account
+      properly. So, we'll run AOLserver with a different user account
       for each different service.  A service name should be a single
       word, letters and numbers only. If the name
       of your site is one word, that would be a good choice. For
       example "$OPENACS_SERVICE_NAME" might be the service name for the
       $OPENACS_SERVICE_NAME.net
       community.
 
-        We'll leave the password blank, which prevents login by
+        We'll leave the password blank, which prevents login by
       password, for increased security.  The only way to log in will
       be with ssh certificates.  The only people who should log in are
       developers for that specific instance.  Add this user, and put
       it in the $OPENACS_SERVICE_NAME group so that it
       can use database and server commands associated with that group.
-      (If you don't know how to do this, type 
+      (If you don't know how to do this, type 
       man usermod. You can type
       groups to find out which groups a user
       is a part of)
@@ -96,7 +96,7 @@
         Get the install script from CVS.  It is located within
         the main cvs tree, at /etc/install.  Use anonymous CVS
         checkout to get that directory in the home directory of the
-        service's dedicated user.  We put it there so that it is not
+        service's dedicated user.  We put it there so that it is not
         overwritten when we do the main CVS checkout to the target
         location.
         [root root]# su - $OPENACS_SERVICE_NAME
@@ -110,7 +110,7 @@
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd install
 [$OPENACS_SERVICE_NAME install]$ emacs install.tcl
 
-        Edit the installation configuration file, /home/$OPENACS_SERVICE_NAME/install/install.tcl and update the site-specific values, such as the new service's IP address and name, which will be written into the new service's config.tcl file.  If your system is different from the one described in the previous sections, check the file paths as well.  Set do_checkout=yes to create a new OpenACS site directly from a CVS checkout, or =no if you have a fully configured site and just want to rebuild it (drop and recreate the database and repeat the installation).  If you have followed a stock installation, the default configuration will work without changes and will install an OpenACS site at 127.0.0.1:8000.
+        Edit the installation configuration file, /home/$OPENACS_SERVICE_NAME/install/install.tcl and update the site-specific values, such as the new service's IP address and name, which will be written into the new service's config.tcl file.  If your system is different from the one described in the previous sections, check the file paths as well.  Set do_checkout=yes to create a new OpenACS site directly from a CVS checkout, or =no if you have a fully configured site and just want to rebuild it (drop and recreate the database and repeat the installation).  If you have followed a stock installation, the default configuration will work without changes and will install an OpenACS site at 127.0.0.1:8000.
     Run the install script install.sh as root:
         [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit 
 [root root]# sh /home/$OPENACS_SERVICE_NAME/install/install.sh
@@ -172,7 +172,7 @@
           
             
               Prepare Oracle for OpenACS
-              If you won't be using Oracle, skip to If you won't be using Oracle, skip to 
             
             
@@ -288,7 +288,7 @@
 
                
 		  Create a database user for this service. Give the
-		  user access to the tablespace and rights to connect. We'll use
+		  user access to the tablespace and rights to connect. We'll use
 		  $OPENACS_SERVICE_NAMEpassword as our password.
 
                 
@@ -374,7 +374,7 @@
 
                 Depending on your distribution, you may receive
                 email when the crontab items are executed. If you
-                don't want to receive email for those crontab items,
+                don't want to receive email for those crontab items,
                 you can add > /dev/null
                 2>&1 to the end of each crontab
                 line
@@ -415,12 +415,12 @@
 [$OPENACS_SERVICE_NAME etc]$ emacs config.tcl
 
             
-	  You can continue without changing any values in the file.  However, if you don't change address to match the computer's ip address, you won't be able to browse to your server from other machines.
+	  You can continue without changing any values in the file.  However, if you don't change address to match the computer's ip address, you won't be able to browse to your server from other machines.
 	
             
             
               httpport - If you want your
-		  server on a different port, enter it here.  The Reference Platform port is 8000, which is suitable for development use.  Port 80 is the standard http port - it's the port used by your browser when you enter http://yourserver.test.  So you should use port 80 for your production site.
+		  server on a different port, enter it here.  The Reference Platform port is 8000, which is suitable for development use.  Port 80 is the standard http port - it's the port used by your browser when you enter http://yourserver.test.  So you should use port 80 for your production site.
               
               
                 httpsport - This is the
@@ -496,7 +496,7 @@
 	  the command line via -u
 	  501 -g
 	  502.    In AOLserver 4, you must also send a -b flag.  Do this by editing the run file as indicated in the comments.  
-          If you are root then killall will affect all OpenACS services on the machine, so if there's more than one you'll have to do ps -auxw | grep
+          If you are root then killall will affect all OpenACS services on the machine, so if there's more than one you'll have to do ps -auxw | grep
 	  nsd and selectively kill by job number.
         [$OPENACS_SERVICE_NAME etc]$ killall nsd
 nsd: no process killed
@@ -518,7 +518,7 @@
 
 	
 
-	  If you don't see the login page, view your error log
+	  If you don't see the login page, view your error log
 	  (/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log)
 	  to make sure the service is starting without any
 	  problems. The most common errors here are trying to start a
@@ -540,7 +540,7 @@
           Configure a Service with the OpenACS
           Installer
           
-	  Now that you've got AOLserver up and running, let's install OpenACS
+	  Now that you've got AOLserver up and running, let's install OpenACS
 	  &version;.
 	
         
@@ -562,7 +562,7 @@
 		  The next page shows the results of loading the OpenACS Kernel
 		  data model - be prepared to wait a few minutes as it works. You
 		  should see a string of output messages from the database as the
-		  datamodel is created.  You'll see the line:
+		  datamodel is created.  You'll see the line:
 
 		
 
@@ -663,7 +663,7 @@
         Set up database environment variables for the site
 	user.  Depending on how you installed Oracle or PostGreSQL, these settings may be necessary for working with the
 	database while logged in as the service user.  They do not
-	directly affect the service's run-time connection with the
+	directly affect the service's run-time connection with the
 	database, because those environmental variables are set by the
 	wrapper scripts nsd-postgres and nsd-oracle.
         
@@ -679,7 +679,7 @@
           
             Oracle.  These environment variables are specific for a local Oracle
       installation communicating via IPC. If you are connecting to a remote
-      Oracle installation, you'll need to adjust these appropriately. Also,
+      Oracle installation, you'll need to adjust these appropriately. Also,
       make sure that the '8.1.7' matches your Oracle version.
 
             export ORACLE_BASE=/ora8/m01/app/oracle
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/oracle.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/oracle.xml,v
diff -u -N -r1.21 -r1.21.14.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/oracle.xml	17 Jul 2006 05:38:37 -0000	1.21
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/oracle.xml	23 Jun 2016 08:32:46 -0000	1.21.14.1
@@ -15,7 +15,7 @@
     If you are installing PostGreSQL instead of Oracle, skip this section.
   
   
-    OpenACS &version; will install with Oracle 9i but has not been extensively tested so may still have bugs or tuning issues.  See Andrew Piskorski's Oracle 9i notes for guidance.
+    OpenACS &version; will install with Oracle 9i but has not been extensively tested so may still have bugs or tuning issues.  See Andrew Piskorski's Oracle 9i notes for guidance.
   
   
   
@@ -24,9 +24,9 @@
        
     
       
-      This document assumes that you'll be installing Oracle on the same
+      This document assumes that you'll be installing Oracle on the same
       box as AOLserver. For more details on a remote Oracle installation,
-      see Daryl Biberdorf's document.
       
     
@@ -38,7 +38,7 @@
         
         
         Dizwell - Howard
-        Roger's company - on Oracle on Linux
+        Roger's company - on Oracle on Linux
       
       
         Werner Puschitz - Oracle on Red Hat Linux
@@ -55,15 +55,15 @@
       Production Oracle systems should run on certified platforms.  Follow the
       metalink
-      note 223718.1to find certified platforms. If you don't have
+      note 223718.1to find certified platforms. If you don't have
       metalink access, take a look at the Oracle on Linux FAQ: Which
       Linux Distributions Are Directly Supported By Oracle?. In summary,
       free and inexpensive Linux distributions are not certified.
     
 
     
-      If you don't have an account at OTN
+      If you don't have an account at OTN
       get one: you can download the Oracle software from the 
       Oracle Downloads page. It is also get the CDs shipped to you for
@@ -110,7 +110,7 @@
       To be able to download a patchset, you need a (to-pay-for) account on Metalink. You may find the appropriate
       patchset by following Andrew's
+      url="http://openacs.org/forums/message-view?message_id=33004">Andrew's
       suggestion.
     
 
@@ -125,7 +125,7 @@
       printable PDFs and full-text search. Altogether there is more than
       20.000 pages of documentation, so do not expect to understand Oracle
       within in a few hours. The best starting pointing into Oracle is the
-      Concepts book. Here's the 8i
       version and the 9.2
@@ -136,7 +136,7 @@
     
       To give you an idea of how configurable Oracle is and how much thought
       you may need to put into buying the proper hardware and creating a sane
-      setup, you should thoroughly read Cary Millsap's Configuring
       Oracle Server for VLDB and the Optimal
@@ -182,7 +182,7 @@
       url="http://openacs.org/forums/message-view?message_id=28829">thread
       and Andrew
-      Piskorski's mini-guide.
+      Piskorski's mini-guide.
 
     
 
@@ -282,7 +282,7 @@
 
       
 
-          Set up the oracle user's
+          Set up the oracle user's
           environment
 
         
@@ -920,7 +920,7 @@
             Run the script. Switch to the oracle user first
             to set the environment appropriately and then do
             su to get root privileges, while keeping
-            the oracle user's enviroment.
+            the oracle user's enviroment.
             
 
             
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml,v
diff -u -N -r1.29 -r1.29.14.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml	17 Jul 2006 05:38:37 -0000	1.29
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml	23 Jun 2016 08:32:46 -0000	1.29.14.1
@@ -14,7 +14,7 @@
       This section assumes that the source tarballs for supporting
     software are in /tmp.  It assumes
     that you begin each continuous block of commands as root, and you
-    should end each block as root.  It doesn't care which directory
+    should end each block as root.  It doesn't care which directory
     you start in.  Text instructions always precede the commands they
       refer to.
 
@@ -208,7 +208,7 @@
       Install qmail (OPTIONAL)
       Qmail is a Mail Transfer Agent.  It handles incoming and
       outgoing mail.  Install qmail if you want your OpenACS server to
-      send and receive mail, and you don't want to use an alternate
+      send and receive mail, and you don't want to use an alternate
       MTA.
       Red Hat 9: all djb tools (qmail, daemontools, ucspi) will
       fail to compile in Red Hat 9 because of changes to glibc (patches)
@@ -257,14 +257,14 @@
               rcpthosts error message
             
 (I'm not sure if this next step is 100% necessary, but when I skip it
-I get problems.  If you get the error 553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1) then you need to do this.)  AOLserver sends outgoing mail via the ns_sendmail
+I get problems.  If you get the error 553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1) then you need to do this.)  AOLserver sends outgoing mail via the ns_sendmail
 command, which pipes a command to the sendmail executable.  Or, in our
 case, the qmail replacement wrapper for the sendmail executable.  In
 some cases, though, the outgoing mail requset is apparently sent
 through tcp/ip, so that it comes to qmail from 127.0.0.1 (a special IP
 address that means the local machine - the "loopback" interface).
 Unless this mail is addressed to the same machine, qmail thinks that
-it's an attempt to relay mail, and rejects it.  So these two commands
+it's an attempt to relay mail, and rejects it.  So these two commands
 set up an exception so that any mail sent from 127.0.0.1 is allowed to
 send outgoing mail.
           [root ucspi-tcp-0.88]# cp /tmp/&tarballpath;/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp
@@ -342,7 +342,7 @@
 ./collate.sh
 cd netqmail-1.04
 make setup check
-          Replace sendmail with qmail's wrapper.
+          Replace sendmail with qmail's wrapper.
           
             sendmail
             removing
@@ -352,7 +352,7 @@
 [root qmail-1.03]#
 rm -f /usr/bin/sendmail /usr/sbin/sendmail
 ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail
-          Configure qmail - specifically, run the config script to set up files in /var/qmail/control specifying the computer's identity and which addresses it should accept mail for.  This command will automatically set up qmail correctly if you have correctly set a valid host nome.  If not, you'll want to read /var/qmail/doc/INSTALL.ctl to find out how to configure qmail.
+          Configure qmail - specifically, run the config script to set up files in /var/qmail/control specifying the computer's identity and which addresses it should accept mail for.  This command will automatically set up qmail correctly if you have correctly set a valid host nome.  If not, you'll want to read /var/qmail/doc/INSTALL.ctl to find out how to configure qmail.
             [root qmail-1.03]# ./config-fast yourserver.test
 Your fully qualified host name is yourserver.test.
 Putting yourserver.test into control/me...
@@ -364,7 +364,7 @@
 Make sure to change rcpthosts if you add hosts to locals or virtualdomains!
 [root qmail-1.03]#
 ./config-fast yourserver.test
-          All incoming mail that isn't for a specific user is handled by the alias user.  This includes all root mail.  These commands prepare the alias user to receive mail.
+          All incoming mail that isn't for a specific user is handled by the alias user.  This includes all root mail.  These commands prepare the alias user to receive mail.
           [root qmail-1.03]# cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root
 [root alias]# chmod 644 ~alias/.qmail*
 [root alias]# /var/qmail/bin/maildirmake ~alias/Maildir/
@@ -432,7 +432,7 @@
 chmod 755 /var/qmail/supervise/qmail-smtpd/log/run
 ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service
 
-          Wait ten seconds or so, and then verify that that the four qmail processes are running.  If uptimes don't rise above 1 second, this may indicate broken scripts that are continuously restarting.  In that case, start debugging by checking permissions.
+          Wait ten seconds or so, and then verify that that the four qmail processes are running.  If uptimes don't rise above 1 second, this may indicate broken scripts that are continuously restarting.  In that case, start debugging by checking permissions.
           [root root]# qmailctl stat
 /service/qmail-send: up (pid 32700) 430 seconds
 /service/qmail-send/log: up (pid 32701) 430 seconds
@@ -735,7 +735,7 @@
 [postgres pgsql]$ cd /usr/local/src/postgresql-7.3.4/contrib/tsearch/
 [postgres tsearch]$ make
 sed 's,MODULE_PATHNAME,$libdir/tsearch,g' tsearch.sql.in >tsearch.sql
-/usr/bin/flex  -8 -Ptsearch_yy -o'parser.c' parser.l(many lines omitted)
+/usr/bin/flex  -8 -Ptsearch_yy -o'parser.c' parser.l(many lines omitted)
 rm -f libtsearch.so
 ln -s libtsearch.so.0.0 libtsearch.so
 [postgres tsearch]$ make install
@@ -1010,7 +1010,7 @@
           https.  These commands compile nsopenssl and install it,
           along with a tcl helper script to handle https connections.
           You will also need ssl certificates.  Because those should
-          be different for each server service, you won't need those instructions until
       later. 
       
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml,v
diff -u -N -r1.29.2.1 -r1.29.2.2
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml	28 Sep 2015 07:54:30 -0000	1.29.2.1
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml	23 Jun 2016 08:32:46 -0000	1.29.2.2
@@ -207,8 +207,8 @@
     
 
     
-      None of these locations are set in stone - they're simply
-      the values that we've chosen.  The values that you'll
+      None of these locations are set in stone - they're simply
+      the values that we've chosen.  The values that you'll
       probably want to change, such as service name, are
       marked like this.  The other
       values we recommend you leave unchanged unless you have a
@@ -230,8 +230,8 @@
     Getting Help during installation
 
     
-      We'll do our best to assure that following our instructions will get
-      you to the promised land. If something goes wrong, don't
+      We'll do our best to assure that following our instructions will get
+      you to the promised land. If something goes wrong, don't
       panic. There are plenty of ways to get help. Here are some tips:
     
 
@@ -248,20 +248,20 @@
 
       
         
-          We'll point out where the error logs for the various pieces of
-          software are. Output from those logs will help us help you. Don't
+          We'll point out where the error logs for the various pieces of
+          software are. Output from those logs will help us help you. Don't
           worry if you feel overwhelmed by all the information in the error
-          logs. Over time, you'll find that they make more and more
-          sense. Soon, you'll actually look forward to errors so that you
+          logs. Over time, you'll find that they make more and more
+          sense. Soon, you'll actually look forward to errors so that you
           can run to the log and diagnose the problem. 
         
       
 
       
         
           Search the forums at
-            openacs.org - you'll often find many people who have
-          struggled through the same spot that you're in.
+            openacs.org - you'll often find many people who have
+          struggled through the same spot that you're in.
         
       
 
@@ -276,7 +276,7 @@
       
         
           Ask questions at the irc channel on freenode.net
-          (#openacs). They're knowledgeable and quite friendly
+          (#openacs). They're knowledgeable and quite friendly
           if you can keep them on topic.
         
       
@@ -285,10 +285,10 @@
         
           Post a question on the forums. Make sure
-          you've done a search first. When you do post, be sure to include
+          you've done a search first. When you do post, be sure to include
           your setup information (OS, etc) as well as the exact commands
           that are failing with the accompanying error.  If
-          there's a SQL error in the Tcl error or in the log,
+          there's a SQL error in the Tcl error or in the log,
           post that too.
         
       
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/recovery.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/recovery.xml,v
diff -u -N -r1.17 -r1.17.6.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/recovery.xml	11 Dec 2010 23:36:32 -0000	1.17
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/recovery.xml	23 Jun 2016 08:32:46 -0000	1.17.6.1
@@ -234,7 +234,7 @@
           
             The --exclude clauses skips some daemontools files that
             are owned by root and thus cannot be backed up by the
-            service owner.  These files are autogenerated and we don't
+            service owner.  These files are autogenerated and we don't
             break anything by omitting them.
           
           
@@ -258,7 +258,7 @@
       
         
           Suffer a catastrophic failure on your production system
-          (We'll simulate this step)
+          (We'll simulate this step)
         
         [root root]# svc -d /service/$OPENACS_SERVICE_NAME
 [root root]# mv /var/lib/aolserver/$OPENACS_SERVICE_NAME/ /var/lib/aolserver/$OPENACS_SERVICE_NAME.lost
@@ -373,15 +373,15 @@
       
       
         
-        Set this file to run automatically by adding a line to root's crontab. (Typically, with export EDITOR=emacs; crontab -e.)  This example runs the backup script at 1:30 am every day.
+        Set this file to run automatically by adding a line to root's crontab. (Typically, with export EDITOR=emacs; crontab -e.)  This example runs the backup script at 1:30 am every day.
         30 1 * * *        sh /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/backup.sh
       
     
 
   
   
     Using CVS for backup-recovery
-    CVS-only backup is often appropriate for development sites.  If you are already using CVS and your data is not important, you probably don't
+    CVS-only backup is often appropriate for development sites.  If you are already using CVS and your data is not important, you probably don't
       need to do anything to back up your files.  Just make
       sure that your current work is checked into the system.
       You can then roll back based on date - note the
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/red-hat.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/red-hat.xml,v
diff -u -N -r1.9 -r1.9.14.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/red-hat.xml	17 Jul 2006 05:38:38 -0000	1.9
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/red-hat.xml	23 Jun 2016 08:32:47 -0000	1.9.14.1
@@ -15,7 +15,7 @@
     software.  You should do this section as-is if you have a machine
     you can reformat and you want to be sure that your installation
     works and is secure; it should take about an hour.  (In my
-    experience, it's almost always a net time savings of several hours
+    experience, it's almost always a net time savings of several hours
     to install a new machine from scratch compared to installing each
     of these packages installed independently.)
 
@@ -61,15 +61,15 @@
 
     
       Unplug the network cable from your
-          computer.  We don't want to connect to the network
-          until we're sure the computer is secure.  
+          computer.  We don't want to connect to the network
+          until we're sure the computer is secure.  
            
             security
             definition
           
   (Wherever you see
           the word secure, you should always read it as, "secure
-          enough for our purposes, given the amount of work we're
+          enough for our purposes, given the amount of work we're
           willing to exert and the estimated risk and
           consequences.")
       
@@ -81,7 +81,7 @@
           prompt, press Enter for a
           graphical install.  The text install is fairly different, so
           if you need to do that instead proceed with caution, because
-          the guide won't match the steps.
+          the guide won't match the steps.
       Checking the media is probably a waste of
           time, so when it asks press Tab and
           then Enter to skip it.
@@ -94,16 +94,16 @@
       Choose your mouse type and Click Next
 
       Red Hat has several templates for new
-          computers.  We'll start with the "Server" template and then
+          computers.  We'll start with the "Server" template and then
           fine-tune it during the rest of the install.  Choose
 	Server
 	and click
 	Next.
       
 
       
-        Reformat the hard drive.  If you know what you're doing,
-	do this step on your own.  Otherwise:  we're going to let the
+        Reformat the hard drive.  If you know what you're doing,
+	do this step on your own.  Otherwise:  we're going to let the
 	installer wipe out the everything on the main hard drive and then arrange things to
 	its liking.
         
@@ -123,32 +123,32 @@
             security
             firewall
           
-Again, if you know what you're doing, do this step
+Again, if you know what you're doing, do this step
           yourself, being sure to note the firewall holes. Otherwise,
           follow the instructions in this step to set up a computer directly connected to the internet with a dedicated IP address.
         
           DHCP is a system by which a computer that
 joins a network (such as on boot) can request a temporary IP address
 and other network information.  Assuming the machine has a dedicated
-IP address (if it doesn't, it will be tricky to access the OpenACS
-service from the outside world), we're going to set up that address.
-If you don't know your netmask, 255.255.255.0 is usually a pretty safe
+IP address (if it doesn't, it will be tricky to access the OpenACS
+service from the outside world), we're going to set up that address.
+If you don't know your netmask, 255.255.255.0 is usually a pretty safe
 guess.  Click Edit, uncheck Configure using DHCP
 and type in your IP and netmask.  Click Ok.
           
            Type in your host
 name, gateway, and DNS server(s).  Then click Next.
-          We're going to use the firewall template for high
-security, meaning that we'll block almost all incoming traffic.  Then
-we'll add a few holes to the firewall for services which we need and
+          We're going to use the firewall template for high
+security, meaning that we'll block almost all incoming traffic.  Then
+we'll add a few holes to the firewall for services which we need and
 know are secure.  Choose High
 security level. Check
 WWW,
 SSH, and
 Mail (SMTP).  In the Other ports
 box, enter 443, 8000, 8443.  Click
 Next.
-Port 443 is for https (http over ssl), and 8000 and 8443 are http and https access to the development server we'll be setting up.
+Port 443 is for https (http over ssl), and 8000 and 8443 are http and https access to the development server we'll be setting up.
           
         
       
@@ -162,15 +162,15 @@
       Type in a root
 password, twice.
       
-	On the Package selection page, we're going to
-uncheck a lot of packages that install software we don't need, and add
+	On the Package selection page, we're going to
+uncheck a lot of packages that install software we don't need, and add
 packages that have stuff we do need.  You should install everything
-we're installing here or the guide may not work for you; you can
+we're installing here or the guide may not work for you; you can
 install extra stuff, or ignore the instructions here to not install
-stuff, with relative impunity - at worst, you'll introduce a security
-risk that's still screened by the firewall, or a resource hog.  Just
-don't install a database or web server, because that would conflict
-with the database and web server we'll install later.
+stuff, with relative impunity - at worst, you'll introduce a security
+risk that's still screened by the firewall, or a resource hog.  Just
+don't install a database or web server, because that would conflict
+with the database and web server we'll install later.
 
 check Editors (this installs emacsemacsinstallation),
 click Details next to Text-based Internet, check lynx, and click OK;
@@ -188,7 +188,7 @@
 
   We need to fine-tune the exact list of packages.
 The same rules apply as in the last step - you can add more stuff, but
-you shouldn't remove anything the guide adds.  We're going to go
+you shouldn't remove anything the guide adds.  We're going to go
 through all the packages in one big list, so select
 Flat
 View and wait. In a minute, a
@@ -199,21 +199,21 @@
 uncheckisdn4k-utils (unless you are using isdn, this installs a useless daemon), 
 check mutt (a mail program that reads Maildir),
 uncheck nfs-utils (nfs is a major security risk), 
-uncheck pam-devel (I don't remember why, but we don't want this), 
+uncheck pam-devel (I don't remember why, but we don't want this), 
 uncheck portmap, 
-uncheck postfix (this is an MTA, but we're going to install qmail later), 
+uncheck postfix (this is an MTA, but we're going to install qmail later), 
 check  postgresql-devel,
 uncheck rsh (rsh is a security hole), 
-uncheck sendmail (sendmail is an insecure MTA; we're going to install qmail instead later),
+uncheck sendmail (sendmail is an insecure MTA; we're going to install qmail instead later),
 check tcl (we need tcl), and 
-uncheck xinetd (xinetd handles incoming tcp connections.  We'll install a different, more secure program, ucspi-tcp).
+uncheck xinetd (xinetd handles incoming tcp connections.  We'll install a different, more secure program, ucspi-tcp).
 Click Next
 
 
 
-  Red Hat isn't completely happy with the combination
-of packages we've selected, and wants to satisfy some dependencies.
-Don't let it.  On the next screen, choose
+  Red Hat isn't completely happy with the combination
+of packages we've selected, and wants to satisfy some dependencies.
+Don't let it.  On the next screen, choose
 Ignore Package
 Dependencies and click
 Next.
@@ -228,7 +228,7 @@
         If you know how to use it, create a boot
         disk.  Since you can also boot into recovery mode with the
         Install CDs, this is less useful than it used to be, and we
-        won't bother.  Select No,I do not want to create a boot disk and click Next.
+        won't bother.  Select No,I do not want to create a boot disk and click Next.
       
       Click Exit, remove the CD, and watch the
 computer reboot.
@@ -267,7 +267,7 @@
             emacs /etc/ssh/sshd_config
           
           
-	    Search for the word "root" by typing C-s (that's emacs-speak for control-s) and then root.
+	    Search for the word "root" by typing C-s (that's emacs-speak for control-s) and then root.
           
           
             Make the following changes:
@@ -291,18 +291,18 @@
       
        
        
-         Red Hat still installed a few services we don't need, and
+         Red Hat still installed a few services we don't need, and
          which can be security holes.  Use the service command to turn
          them off, and then use chkconfig to automatically edit the
          System V init directories to permanently (The System V init
          directories are the ones in /etc/rc.d.  They consist of a
          bunch of scripts for starting and stopping programs, and
          directories of symlinks for each system level indicating
          which services should be up and down at any given service
-         level.  We'll use this system for PostgreSQL, but we'll use
+         level.  We'll use this system for PostgreSQL, but we'll use
          daemontools to perform a similar function for AOLserver.
          (The reason for this discrepencies is that, while daemontools
-         is better, it's a pain in the ass to deal with and nobody's
+         is better, it's a pain in the ass to deal with and nobody's
          had any trouble leaving PostgreSQL the way it is.)
        
 [root root]# service pcmcia stop
@@ -322,11 +322,11 @@
       
       
         Verify that you have connectivity by going to another
-          computer and ssh'ing to
+          computer and ssh'ing to
           yourserver, logging in as
           remadmin, and promoting yourself to root:
 [joeuser@someotherserver]$  ssh remadmin@yourserver.test
-The authenticity of host 'yourserver.test (1.2.3.4)' can't be established.
+The authenticity of host 'yourserver.test (1.2.3.4)' can't be established.
 DSA key fingerprint is 10:b9:b6:10:79:46:14:c8:2d:65:ae:c1:61:4b:a5:a5.
 Are you sure you want to continue connecting (yes/no)? yes
 Warning: Permanently added 'yourserver.test (1.2.3.4)' (DSA) to the list of known hosts.
@@ -337,8 +337,8 @@
 [root root]#
       
       
-        If you didn't burn a CD of patches and use it, can still
-          download and install the necessary patches.  Here's how to
+        If you didn't burn a CD of patches and use it, can still
+          download and install the necessary patches.  Here's how to
           do it for the kernel; you should also check for other
           critical packages.
         Upgrade the kernel to fix a security hole.  The default
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/software.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/software.xml,v
diff -u -N -r1.26 -r1.26.2.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/software.xml	27 Oct 2014 16:39:31 -0000	1.26
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/software.xml	23 Jun 2016 08:32:47 -0000	1.26.2.1
@@ -216,7 +216,7 @@
             FreeBSD
             FreeBSD guide.  The OpenACS Reference Platform uses shell scripts written for bash, which is the
               standard Linux shell.  If you are using a different
-              shell, you will need to substitute your shell's
+              shell, you will need to substitute your shell's
               conventions for setting environment variables when
               appropriate, and install bash to work with the scripts. Substitute fetch when the instructions suggest you use 
               wget to download software.
@@ -355,7 +355,7 @@
       
 
       
-        It's also possible to download all the pieces and patches yourself:
+        It's also possible to download all the pieces and patches yourself:
       
       
       
@@ -369,7 +369,7 @@
               url="http://prdownloads.sourceforge.net/aolserver/nspostgres-3.5.tar.gz?download">SourceForge. If
               you do decide to use nspostgres.so, you have to remember to
               change the AOLserver config file to point to nspostgres.so
-              instead of postgres.so. This guide uses Mat Kovach's distro
+              instead of postgres.so. This guide uses Mat Kovach's distro
               (i.e. postgres.so)
 
           
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml,v
diff -u -N -r1.41 -r1.41.2.1
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml	27 Oct 2014 16:39:31 -0000	1.41
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml	23 Jun 2016 08:32:47 -0000	1.41.2.1
@@ -14,7 +14,7 @@
     Starting with Version 4.5, all OpenACS core packages support
     automatic upgrade.  That means that, if you have OpenACS 4.5
     or better, you should always be able to upgrade all of your core
-    packages automatically.  If you haven't changed anything, no
+    packages automatically.  If you haven't changed anything, no
     manual intervention should be required.  If you are running
     OpenACS prior to 4.5, upgrading will require manual effort.
     If all of these conditions are true:
@@ -50,7 +50,7 @@
         
       
        
 
-    It's always a good idea to precede an upgrade attempt with a snapshot backup.
+    It's always a good idea to precede an upgrade attempt with a snapshot backup.
     Assumptions in this section
@@ -83,7 +83,7 @@
         Linux/Unix
       
       The required platform for OpenACS 4.6 is the same as
-      4.5, with the exception of OpenFTS.  OpenACS 4.6 and later require OpenFTS 0.3.2 for full text search on PostGreSQL.  If you have OpenFTS 0.2, you'll need to upgrade.  
+      4.5, with the exception of OpenFTS.  OpenACS 4.6 and later require OpenFTS 0.3.2 for full text search on PostGreSQL.  If you have OpenFTS 0.2, you'll need to upgrade.  
       If upgrading from 4.4, you need to manually run acs-kernel/sql/postgres/upgrade-4.4-4.5.sql.  See Bug #632
       
         A computer with OpenACS 4.5.
@@ -140,7 +140,7 @@
               Select the packages you want to install.  This should
               be everything that says
               upgrade, plus any new
-              packages you want.  It's safest to upgrade the kernel by
+              packages you want.  It's safest to upgrade the kernel by
               itself, and then come back and upgrade the rest of the
               desired packages in a second pass.
             
@@ -197,7 +197,7 @@
           
         
             
-              Upgrade the kernel manually. (There is a script to do most of the rest: /contrib/misc/upgrade_4.6_to_5.0.sh on HEAD).  You'll still have to do a lot of stuff manually, but automated trial and error is much more fun.)
+              Upgrade the kernel manually. (There is a script to do most of the rest: /contrib/misc/upgrade_4.6_to_5.0.sh on HEAD).  You'll still have to do a lot of stuff manually, but automated trial and error is much more fun.)
               [root root]# su - $OPENACS_SERVICE_NAME
 [$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/ $OPENACS_SERVICE_NAME/packages/acs-kernel/sql/postgresql/upgrade
               
@@ -233,7 +233,7 @@
               psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-lang/sql/postgresql/acs-lang-create.sql $OPENACS_SERVICE_NAME
             
             
-              (This step may overlap with the two previous steps, but I think it's harmless?) Create a file which will be executed on startup which takes care of a few issues with authentication and internationalization: create $OPENACS_SERVICE_NAME/tcl/zzz-postload.tcl containing:
+              (This step may overlap with the two previous steps, but I think it's harmless?) Create a file which will be executed on startup which takes care of a few issues with authentication and internationalization: create $OPENACS_SERVICE_NAME/tcl/zzz-postload.tcl containing:
               if {![apm_package_installed_p acs-lang]} {
 apm_package_install -enable -mount_path acs-lang $::acs::rootdir/packages/acs-lang/acs-lang.info
 lang::catalog::import -locales [list "en_US"]
@@ -263,7 +263,7 @@
           See also these forum posts: Forum OpenACS Development: 4.6.3 upgrade to 5-HEAD: final results, OpenACS 5.0 Upgrade Experiences.
 
         
-          There are a few things you might want to do once you've
+          There are a few things you might want to do once you've
           upgraded. First, the acs-kernel parameters need to be set to
           allow HREF and IMG tags, if you want users who can edit HTML
           to be able to insert HREF and IMG tags. Also, you might need
@@ -406,21 +406,21 @@
 
               To get your OpenACS code into your local CVS
                 repository, you will set up a working CVS checkout of
-                OpenACS. When you want to update your site, you'll
+                OpenACS. When you want to update your site, you'll
                 update the working CVS checkout, import those changes
                 into your local CVS checkout, create a temporary CVS
                 checkout to merge your local changes, fix any
                 conflicts, commit your changes, and then update your
-                site. It sounds complicated, but it's not too bad, and
+                site. It sounds complicated, but it's not too bad, and
                 it is the best way to work around CVS's limitations.
               
               This part describes how to set up your working CVS
-        checkout. Once it is set up, you'll be able to update any
+        checkout. Once it is set up, you'll be able to update any
         packages using the existing working CVS checkout. We use one
         dedicated directory for each branch of OpenACS - if you are
         using OpenACS 5.1,x, you will need a 5.1 checkout. That will
         be good for 5.1, 5.11, 5.12, and so on. But when you want to
-        upgrade to OpenACS 5.2, you'll need to check out another
+        upgrade to OpenACS 5.2, you'll need to check out another
         branch.
               
               The openacs-5-1-compat tag identifies the latest released version of OpenACS 5.1 (ie, 5.1.3 or 5.1.4) and the latest compatible version of each package.  Each minor release of OpenACS since 5.0 has this tagging structure.  For example, OpenACS 5.1.x has openacs-5-1-compat.
@@ -437,7 +437,7 @@
 [$OPENACS_SERVICE_NAME aolserver]$ cd ../..
 [$OPENACS_SERVICE_NAME aolserver]$ mv openacs-4 openacs-5-1
 
-              Make sure your working CVS checkout doesn't have
+              Make sure your working CVS checkout doesn't have
               the entire CVS tree from OpenACS. A good way to check
               this is if it has a contrib directory. If it does, you
               probably checked out the entire tree. You might want to
@@ -496,7 +496,7 @@
             Create a new directory as temporary working space to
             reconcile conflicts between the new files and your current
             work.  The example uses the cvs keyword yesterday, making
-            the assumption that you haven't checked in new code to
+            the assumption that you haven't checked in new code to
             your local tree in the last day. This section should be
             improved to use tags instead of the keyword yesterday!
             [$OPENACS_SERVICE_NAME openacs-5.1]$  cd /var/lib/aolserver
@@ -507,11 +507,11 @@
           The file /var/tmp/openacs-upgrade/cvs.txt contains the
             results of the upgrade.  If you changed files that are
             part of the OpenACS tarball and those changes conflict,
-            you'll have to manually reconcile them.  Use the emacs
+            you'll have to manually reconcile them.  Use the emacs
             command M-x sort-lines
             (you may have to click Ctrl-space at the beginning of the
-            file, and go to the end, and then try M-x sort-lines) and then, for each line that starts with a C, open that file and manually resolve the conflict by deleting the excess lines.  When you're finished, or if there aren't any conflicts, save and exit.
-            Once you've fixed any conflicts, commit the new code
+            file, and go to the end, and then try M-x sort-lines) and then, for each line that starts with a C, open that file and manually resolve the conflict by deleting the excess lines.  When you're finished, or if there aren't any conflicts, save and exit.
+            Once you've fixed any conflicts, commit the new code
             to your local tree.  
             [$OPENACS_SERVICE_NAME tmp]$ cd $OPENACS_SERVICE_NAME-upgrade
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME-upgrade]$ cvs commit -m "Upgraded to 5.1"          
@@ -699,7 +699,7 @@
       function creation and at function calling, so they still match.
       But if you use a database created in 7.2 in 7.3, the function
       names in the database remain truncated but the function calls
-      are not, and so they don't match.  Also some functions use
+      are not, and so they don't match.  Also some functions use
       casting commands that no longer work in 7.3 and these functions
       must be recreated.
       
@@ -736,21 +736,21 @@
           installation location is different, and your startup script
           (/etc/init.d/postgres73 should be named differently. You
           might even need to edit that file to make the paths
-          correct). You'll also need to add export
+          correct). You'll also need to add export
           PGPORT=5434 to the .bashrc and/or
           .bash_profile for the postgres73 user.
            
         
         
           Install PostgreSQL 7.3.x. Note that you PostgreSQL
           must listen on a different port in order to work
-          correctly, so you'll need to edit the configuration file
+          correctly, so you'll need to edit the configuration file
           (/usr/local/pgsql73/data/postgresql.conf) and
           change the port (to 5433, say). create a second postgres
           user to differentiate between the two postgres
-          installs. When you do ./configure, you'll need to include
+          installs. When you do ./configure, you'll need to include
           --prefix=$HOME to ensure that it is installed in the
-          postgres73 user's home directory. 
+          postgres73 user's home directory. 
         
         
           Change the path in
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml,v
diff -u -N -r1.9 -r1.9.10.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml	29 Dec 2008 22:21:04 -0000	1.9
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml	23 Jun 2016 08:32:47 -0000	1.9.10.1
@@ -324,7 +324,7 @@
 instance.
 
 
        
       
       
      • 
 
    • 
 
      
-Steps to Reproduce. The events package does
-not allow users to register for new events.
        
+Steps to Reproduce. The events
+package does not allow users to register for new events.
          
 
        1. Go to the http://yourserver.net/events as a visitor (ie, log out
 and, if necessary, clear cookies). This in on a 4.6.3 site with
 events version 0.1d3.
        2. Select an available event
        3. A link such as Registration:
 Deadline is 03/15/2004 10:00am. » Login or sign up to
-register for this event. is visible. Click on "Login or sign
-up"
        4. Complete a new registration. Afterwards, you should be
+register for this event. is visible. Click on "Login or
+sign up"
        5. Complete a new registration. Afterwards, you should be
 redirected back to the same page.
          6. 
-
        Actual Results: The page says "You
-do not have permission to register for this event."
+
      Actual Results: The page says "You do not have permission to register for
+this event."
 
      Expected results: A link or form to sign up for the event is
 shown.
      
 
    • 
 
      
-Finding the problem. We start with the page
-that has the error. In the URL it's http://myserver.net/events/event-info.tcl,
+Finding the problem. We start with
+the page that has the error. In the URL it's http://myserver.net/events/event-info.tcl,
 so open the file /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/events/www/event-info.tcl.
 It contains this line:
       set can_register_p [events::security::can_register_for_event_p -event_id $event_id]
 
      We need to know what that procedure does, so go to /api-doc, paste
 events::security::can_register_for_event_p into the ACS Tcl API
 Search box, and click Feeling Lucky. The next pages shows the proc,
-and we click "show source" to see more information. The body of the
-proc is simply
      +and we click "show source" to see more information. The
+body of the proc is simply
       return [permission::permission_p -party_id $user_id -object_id $event_id -privilege write]
 
      This means that a given user must have the write privilige on
-the event in order to register. Let's assume that the priviliges
-inherit, so that if a user has the write privilige on the whole
-package, they will have the write privilege on the event.
      
+the event in order to register. Let's assume that the
+priviliges inherit, so that if a user has the write privilige on
+the whole package, they will have the write privilege on the
+event.
      
 
    • 
 
      
-Setting Permissions. A permission has three
-parts: the privilige, the object of the privilige, and the subject
-being granted the privilige. In this case the privilige is "write,"
-the object is the Events package, and the subject is all Registered
-Users.
        
+Setting Permissions. A permission
+has three parts: the privilige, the object of the privilige, and
+the subject being granted the privilige. In this case the privilige
+is "write," the object is the Events package, and the
+subject is all Registered Users.
          
 
        1. To grant permissions on a package, start at the site map. Find the event
 package and click "Set permissions".
        2. Click "Grant Permission"
        3. 
 
          Grant the write permission to Registered Users.
          
@@ -128,8 +129,8 @@
 

          
 
          4. 
 
        OpenACS 5.0 offers a prettier version at /admin/applications.
        
-
        Figure 4.3. Granting
-Permissions in 5.0
        Granting Permissions in 5.0
        
+
        Figure 4.3. Granting Permissions in
+5.0
        Granting Permissions in 5.0
        
 

        
 
 
    
Index: openacs-4/packages/acs-core-docs/www/how-do-I.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/how-do-I.html,v
diff -u -N -r1.27.2.10 -r1.27.2.11
--- openacs-4/packages/acs-core-docs/www/how-do-I.html	21 Jun 2016 07:44:36 -0000	1.27.2.10
+++ openacs-4/packages/acs-core-docs/www/how-do-I.html	23 Jun 2016 08:32:45 -0000	1.27.2.11
@@ -1,7 +1,7 @@
 
-How Do I?
    Alex logo
    Prev Chapter 4. Configuring a new OpenACS Site Next
    How Do I?
    How do I edit the front page of a new site through a web interface?
    The easiest way is to install the Edit-This-Page package.
    1. Log in to the web site as an administrator.
    2. Click on Admin > Install Software > Install from OpenACS Repository / Install new application
    3. Choose Edit This Page and install
    4. Follow the instructions within Edit This Page (the link will only work after Edit This Page is installed).
    How do I let anybody who registers post to a weblog?
    Go to /admin/permissions and grant Create to Registered Users
    How do I replace the front page of a new site with the front page of an application on that site
    Suppose you install a new site and install Weblogger, and you want all visitors to see weblogger automatically.
    1. On the front page, click the Admin button.
    2. On the administration page, click Parameters link.
    3. Change the parameter IndexRedirectUrl to be the URI of the desired application.  For a default weblogger installation, this would be weblogger/.  Note the trailing slash.
    How do I put custom functionality on front page of a new site?
    Every page within an OpenACS site is part of a subsite More information).  The home page of the entire site is the front page is a special, default instance of a subsite, served from /var/lib/aolserver/$OPENACS_SERVICE_NAME/www.  If an index page is not found there, the default index page for all subsites is used.  To customize the code on the front page, copy the default index page from the Subsite package to the Main site and edit it:
    1. cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-subsite/www/index* /var/lib/aolserver/$OPENACS_SERVICE_NAME/www
    2. Edit the new index.adp to change the text; you shouldn't need to edit index.tcl unless you are adding new functionality.
    How do I change the site-wide style?
    Almost all pages on an OpenACS site use ACS Templating, and so their appearance is driven by a layer of different files.  Let's examine how this works:
    • 
+How Do I?
      Alex logo
      Prev Chapter 4. Configuring a new OpenACS Site Next
      How Do I?
      How do I edit the front page of a new site through a web interface?
      The easiest way is to install the Edit-This-Page package.
      1. Log in to the web site as an administrator.
      2. Click on Admin > Install Software > Install from OpenACS Repository / Install new application
      3. Choose Edit This Page and install
      4. Follow the instructions within Edit This Page (the link will only work after Edit This Page is installed).
      How do I let anybody who registers post to a weblog?
      Go to /admin/permissions and grant Create to Registered Users
      How do I replace the front page of a new site with the front page of an application on that site
      Suppose you install a new site and install Weblogger, and you want all visitors to see weblogger automatically.
      1. On the front page, click the Admin button.
      2. On the administration page, click Parameters link.
      3. Change the parameter IndexRedirectUrl to be the URI of the desired application.  For a default weblogger installation, this would be weblogger/.  Note the trailing slash.
      How do I put custom functionality on front page of a new site?
      Every page within an OpenACS site is part of a subsite More information).  The home page of the entire site is the front page is a special, default instance of a subsite, served from /var/lib/aolserver/$OPENACS_SERVICE_NAME/www.  If an index page is not found there, the default index page for all subsites is used.  To customize the code on the front page, copy the default index page from the Subsite package to the Main site and edit it:
      1. cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-subsite/www/index* /var/lib/aolserver/$OPENACS_SERVICE_NAME/www
      2. Edit the new index.adp to change the text; you shouldn't need to edit index.tcl unless you are adding new functionality.
      How do I change the site-wide style?
      Almost all pages on an OpenACS site use ACS Templating, and so their appearance is driven by a layer of different files.  Let's examine how this works:
      • 
           A templated page uses an ADP/Tcl pair.  The first line in the ADP file is usually:
           
        <master>
        If it appears exactly like this, without any arguments, the template processer uses default-master for that subsite.  For pages in /var/lib/aolserver/$OPENACS_SERVICE_NAME/www, this is /var/lib/aolserver/$OPENACS_SERVICE_NAME/www/default-master.adp and the associated .tcl file.
           
      • The default-master is itself a normal ADP page.  It draws the subsite navigation elements and invokes site-master (/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/site-master.adp and .tcl)
      • The site-master draws site-wide navigation elements and invokes blank-master (/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/blank-master.adp and .tcl).  
      • Blank-master does HTML housekeeping and provides a framework for special sitewide navigation "meta" elements such as Translator widgets and Admin widgets.
      Figure 4.1. Site Templates
      Site Templates

      How do I diagnose a permissions problem?
      • Steps to Reproduce. The events package does not allow users to register for new events.
        1. Go to the http://yourserver.net/events as a visitor (ie, log out and, if necessary, clear cookies).  This in on a 4.6.3 site with events version 0.1d3.
        2. Select an available event
        3. A link such as Registration: Deadline is 03/15/2004 10:00am. 
 » Login or sign up to register for this event. is visible.  Click on "Login or sign up"
-          
        4. Complete a new registration.  Afterwards, you should be redirected back to the same page.
        Actual Results: The page says "You do not have permission to register for this event."
        Expected results: A link or form to sign up for the event is shown.
      • Finding the problem. We start with the page that has the error.  In the URL it's http://myserver.net/events/event-info.tcl, so open the file /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/events/www/event-info.tcl.  It contains this line:
        set can_register_p [events::security::can_register_for_event_p -event_id $event_id]
        We need to know what that procedure does, so go to /api-doc, paste events::security::can_register_for_event_p into the ACS Tcl API Search box, and click Feeling Lucky.  The next pages shows the proc, and we click "show source" to see more information.  The body of the proc is simply
        return [permission::permission_p -party_id $user_id -object_id $event_id -privilege write]
        This means that a given user must have the write privilige on the event in order to register.  Let's assume that the priviliges inherit, so that if a user has the write privilige on the whole package, they will have the write privilege on the event.
      • Setting Permissions. A permission has three parts: the privilige, the object of the privilige, and the subject being granted the privilige.  In this case the privilige is "write," the object is the Events package, and the subject is all Registered Users.
        1. To grant permissions on a package, start at the site map.  Find the event package and click "Set permissions".  
        2. Click "Grant Permission"
        3. Grant the write permission to Registered Users.
          Figure 4.2. Granting Permissions
          Granting Permissions

        OpenACS 5.0 offers a prettier version at /admin/applications.
        Figure 4.3. Granting Permissions in 5.0
        Granting Permissions in 5.0

      Prev Home Next
      Setting Permissions on an OpenACS package Up Chapter 5. Upgrading
      docs@openacs.org
      View comments on this page at openacs.org
      
+          
    • Complete a new registration.  Afterwards, you should be redirected back to the same page.
    Actual Results: The page says "You do not have permission to register for this event."
    Expected results: A link or form to sign up for the event is shown.
  • Finding the problem. We start with the page that has the error.  In the URL it's http://myserver.net/events/event-info.tcl, so open the file /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/events/www/event-info.tcl.  It contains this line:
    set can_register_p [events::security::can_register_for_event_p -event_id $event_id]
    We need to know what that procedure does, so go to /api-doc, paste events::security::can_register_for_event_p into the ACS Tcl API Search box, and click Feeling Lucky.  The next pages shows the proc, and we click "show source" to see more information.  The body of the proc is simply
    return [permission::permission_p -party_id $user_id -object_id $event_id -privilege write]
    This means that a given user must have the write privilige on the event in order to register.  Let's assume that the priviliges inherit, so that if a user has the write privilige on the whole package, they will have the write privilege on the event.
  • Setting Permissions. A permission has three parts: the privilige, the object of the privilige, and the subject being granted the privilige.  In this case the privilige is "write," the object is the Events package, and the subject is all Registered Users.
    1. To grant permissions on a package, start at the site map.  Find the event package and click "Set permissions".  
    2. Click "Grant Permission"
    3. Grant the write permission to Registered Users.
      Figure 4.2. Granting Permissions
      Granting Permissions

    OpenACS 5.0 offers a prettier version at /admin/applications.
    Figure 4.3. Granting Permissions in 5.0
    Granting Permissions in 5.0

    • Prev Home Next
    Setting Permissions on an OpenACS package Up Chapter 5. Upgrading
    docs@openacs.org
    View comments on this page at openacs.org
    
Index: openacs-4/packages/acs-core-docs/www/i18n-convert.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-convert.adp,v
diff -u -N -r1.1.2.13 -r1.1.2.14
--- openacs-4/packages/acs-core-docs/www/i18n-convert.adp	21 Jun 2016 07:44:36 -0000	1.1.2.13
+++ openacs-4/packages/acs-core-docs/www/i18n-convert.adp	23 Jun 2016 08:32:45 -0000	1.1.2.14
@@ -36,18 +36,19 @@
 files.     From the same Convert ADP ... page in /acs-admin/apm as in the last step, repeat
 the process but deselect Find human
 language text ... and select Replace <# ... #> tags ... and click
-OK. This step replaces all of the temporary tags with "short"
-message lookups, inserts the message keys into the database message
-catalog, and then writes that catalog out to an xml file.
  • 
+OK. This step replaces all of the temporary tags with
+"short" message lookups, inserts the message keys into
+the database message catalog, and then writes that catalog out to
+an xml file.