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 -r1.4 -r1.5 --- openacs-4/packages/acs-core-docs/www/acs-package-dev.html 14 Oct 2003 11:02:57 -0000 1.4 +++ openacs-4/packages/acs-core-docs/www/acs-package-dev.html 21 Oct 2003 10:04:47 -0000 1.5 @@ -2,4 +2,4 @@ This is the place to look if you want to extend OpenACS and build on top of what's already here. Here you can find out about the guts of the system. -

Table of Contents

10. Development Tutorial
Creating a Package
Setting Up Database Objects
Creating Web Pages
Debugging and Automated Testing
Advanced Topics
11. Development Reference
OpenACS 5.0.0a1 Packages
OpenACS Data Models and the Object System
The Request Processor
The OpenACS Database Access API
Using Templates in OpenACS 5.0.0a1
Groups, Context, Permissions
Writing OpenACS 5.0.0a1 Application Pages
Parties in OpenACS 5.0.0a1
OpenACS 4.x Permissions Tediously Explained
Object Identity
Programming with AOLserver
12. Engineering Standards
OpenACS Documentation Guide
Using PSGML mode in Emacs
Detailed Design Documentation Template
System/Application Requirements Template
Release Version Numbering
Constraint naming standard
ACS File Naming and Formatting Standards
PL/SQL Standards
A. Using CVS with an OpenACS Site
Add the Service to CVS - OPTIONAL
Prev Home Next
Install nsopenssl Up Chapter�10.�Development Tutorial
docs@openacs.org
View comments on this page at openacs.org
+

Table of Contents

10. Development Tutorial
Creating a Package
Setting Up Database Objects
Creating Web Pages
Debugging and Automated Testing
Advanced Topics
11. Development Reference
OpenACS 5.0.0a1 Packages
OpenACS Data Models and the Object System
The Request Processor
The OpenACS Database Access API
Using Templates in OpenACS 5.0.0a1
Groups, Context, Permissions
Writing OpenACS 5.0.0a1 Application Pages
Parties in OpenACS 5.0.0a1
OpenACS 4.x Permissions Tediously Explained
Object Identity
Programming with AOLserver
12. Engineering Standards
OpenACS Documentation Guide
Using PSGML mode in Emacs
Detailed Design Documentation Template
System/Application Requirements Template
Release Version Numbering
Constraint naming standard
ACS File Naming and Formatting Standards
PL/SQL Standards
A. Using CVS with an OpenACS Site
Add the Service to CVS - OPTIONAL
B. How to package and release OpenACS
Prev Home Next
Install nsopenssl Up Chapter�10.�Development Tutorial
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/acs-plat-dev.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/acs-plat-dev.html,v diff -u -r1.4 -r1.5 --- openacs-4/packages/acs-core-docs/www/acs-plat-dev.html 14 Oct 2003 11:02:57 -0000 1.4 +++ openacs-4/packages/acs-core-docs/www/acs-plat-dev.html 21 Oct 2003 10:04:47 -0000 1.5 @@ -1 +1 @@ -Part�IV.�For OpenACS Platform Developers
Prev Next

For OpenACS Platform Developers

Table of Contents

13. Kernel Documentation
Overview
OpenACS 4 Object Model Requirements
OpenACS 4 Object Model Design
OpenACS 4 Permissions Requirements
OpenACS 4 Permissions Design
OpenACS 4 Groups Requirements
OpenACS 4 Groups Design
OpenACS 4 Subsites Requirements
OpenACS 4 Subsites Design Document
OpenACS 5.0.0a1 Package Manager Requirements
OpenACS 5.0.0a1 Package Manager Design
Database Access API
OpenACS Internationalization Requirements
Internationalization
OpenACS 4 Security Requirements
OpenACS 4 Security Design
OpenACS 4 Security Notes
OpenACS 4 Request Processor Requirements
OpenACS 4 Request Processor Design
Documenting Tcl Files: Page Contracts and Libraries
Bootstrapping OpenACS
External Authentication Requirements
Prev Home Next
Add the Service to CVS - OPTIONAL Up Chapter�13.�Kernel Documentation
docs@openacs.org
View comments on this page at openacs.org
+Part�IV.�For OpenACS Platform Developers
Prev Next

For OpenACS Platform Developers

Table of Contents

13. Kernel Documentation
Overview
OpenACS 4 Object Model Requirements
OpenACS 4 Object Model Design
OpenACS 4 Permissions Requirements
OpenACS 4 Permissions Design
OpenACS 4 Groups Requirements
OpenACS 4 Groups Design
OpenACS 4 Subsites Requirements
OpenACS 4 Subsites Design Document
OpenACS 5.0.0a1 Package Manager Requirements
OpenACS 5.0.0a1 Package Manager Design
Database Access API
OpenACS Internationalization Requirements
Internationalization
OpenACS 4 Security Requirements
OpenACS 4 Security Design
OpenACS 4 Security Notes
OpenACS 4 Request Processor Requirements
OpenACS 4 Request Processor Design
Documenting Tcl Files: Page Contracts and Libraries
Bootstrapping OpenACS
External Authentication Requirements
Prev Home Next
Appendix�B.�How to package and release OpenACS Up Chapter�13.�Kernel Documentation
docs@openacs.org
View comments on this page at openacs.org
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 -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/apm-design.html 14 Oct 2003 11:02:57 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/apm-design.html 21 Oct 2003 10:04:47 -0000 1.13 @@ -88,7 +88,7 @@ packages for other ACS users to download and install.

For a simple illustration of the difference between ACS without APM (pre-3.3) and ACS with APM (3.3 and beyond), consider a hypothetical ACS installation that uses only two of the thirty-odd modules available circa ACS -3.2 (say, bboard and e-commerce):


[D]

APM itself is part of a package, the OpenACS Kernel, an OpenACS +3.2 (say, bboard and e-commerce):


[D]

APM itself is part of a package, the OpenACS Kernel, an OpenACS service that is the only mandatory component of an OpenACS installation.

Competitive Analysis

The OpenACS is a platform for web-based application software, and any software platform has the potential to develop problems like those described above. Fortunately, there are many precedents for systematic solutions, 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 -r1.5 -r1.6 --- openacs-4/packages/acs-core-docs/www/backup-recovery.html 14 Oct 2003 11:02:57 -0000 1.5 +++ openacs-4/packages/acs-core-docs/www/backup-recovery.html 21 Oct 2003 10:04:47 -0000 1.6 @@ -33,31 +33,31 @@ OpenACS installations comprise files and database contents. If you follow the reference install and put all files, including configuration files, in - /web/service0/, + /var/lib/aolserver/service0/, and back up the database nightly to a file in - /web/service0/database-backup, + /var/lib/aolserver/service0/database-backup, then you can apply standard file-based backup strategies to - /web/service0 + /var/lib/aolserver/service0

Snapshot backup and recovery

This section describes how to make a one-time backup of the files and database. This is useful for rolling back to known-good versions of a service, such as at initial installation and just before an upgrade.

Back up the file system

Here's a quick manual way to back up a reference install - it should be replaced by an automated script within OpenACS. The command excludes the auto-generated supervise directory, which is unneccesary and has complicated permissions. Make sure that you are using the cron job to back up the database to a file in - /web/service0/database-backup + /var/lib/aolserver/service0/database-backup so that the tar command will include the database.

In the tar command,

[root@yourserver root]# su - service0
-[service0@yourserver service0]$ tar -cpsj --exclude /web/service0/etc/daemontools/supervise --file /tmp/service0-backup.tar.bz2 /web/service0/ 
+[service0@yourserver service0]$ tar -cpsj --exclude /var/lib/aolserver/service0/etc/daemontools/supervise --file /tmp/service0-backup.tar.bz2 /var/lib/aolserver/service0/ 
 tar: Removing leading `/' from member names
 [service0@yourserver service0]$

Automated Backup (OPTIONAL)

Backup can encompass all files in - /web/service0. For a development + /var/lib/aolserver/service0. For a development server, putting the files in cvs, and backing up the database nightly, is sufficient. (It's important then to back up the cvs repository!)

Postgres automatic backup

Backing up the database consists of creating a file which is a picture of the database at a particular moment. Postgres can be backed up while running. A quick way to automate database backup is a cron job. This @@ -143,8 +143,8 @@ single nightly backup file which is then collected into a bigger backup file that includes the other parts of the service (web pages, content, code). To make a new file every - night, edit the crontab file for service0:

[service0@yourserver service0]$ export EDITOR=emacs;crontab -e

Add this line to the file. 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.

0 1 * * * /usr/local/pgsql/bin/pg_dump -f /web/service0/database-backup/service0_$(date +%Y-%m-%d).dmp service0

If you plan to back up the whole /web/service0 directory, then it would be redundant to keep a history of database backups. In that case, set up the cron job to overwrite the previous backup each time:

0 1 * * * /usr/local/pgsql/bin/pg_dump -f /web/service0/database-backup/service0_nightly.dmp service0

A full Backup/Recovery cycle

On a test service, make sure that your backup-recovery process work. After backing up the database and file system, delete the service as detailed below and then recover it.

Delete the Service

[root@yourserver root]# svc -d /service/service0
-[root@yourserver root]# mv /web/service0/ /web/service0.lost
+        night, edit the crontab file for service0:
[service0@yourserver service0]$ export EDITOR=emacs;crontab -e
Add this line to the file.  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.
0 1 * * * /usr/local/pgsql/bin/pg_dump -f /var/lib/aolserver/service0/database-backup/service0_`date +\%Y-\%m-\%d`.dmp service0
If you plan to back up the whole /var/lib/aolserver/service0 directory, then it would be redundant to keep a history of database backups.  In that case, set up the cron job to overwrite the previous backup each time:
0 1 * * * /usr/local/pgsql/bin/pg_dump -f /var/lib/aolserver/service0/database-backup/service0_nightly.dmp service0

A full Backup/Recovery cycle

On a test service, make sure that your backup-recovery process work. After backing up the database and file system, delete the service as detailed below and then recover it.

Delete the Service

[root@yourserver root]# svc -d /service/service0
+[root@yourserver root]# mv /var/lib/aolserver/service0/ /var/lib/aolserver/service0.lost
 [root@yourserver root]# rm /service/service0
 rm: remove symbolic link `/service/service0'? y
 [root@yourserver root]# ps -auxw | grep service0
@@ -170,24 +170,24 @@
 logout
 
 [root@yourserver root]# su - service0
-[service0@yourserver service0]$ cd /web
+[service0@yourserver service0]$ cd /var/lib/aolserver
 [service0@yourserver web]$ tar xjf /tmp/service0-backup.tar.bz2
 [service0@yourserver web]$ chmod -R 700 service0
 [service0@yourserver web]$ createdb service0
 CREATE DATABASE
-[service0@yourserver web]$ psql -f /web/service0/packages/acs-kernel/sql/postgresql/postgresql.sql service0
+[service0@yourserver web]$ psql -f /var/lib/aolserver/service0/packages/acs-kernel/sql/postgresql/postgresql.sql service0
 (many lines omitted)
-[service0@yourserver web]$ psql service0 < /web/service0/database-backup/database-backup.dmp
+[service0@yourserver web]$ psql service0 < /var/lib/aolserver/service0/database-backup/database-backup.dmp
 (many lines omitted)
 [service0@yourserver web]$ exit
-[root@yourserver root]# ln -s /web/service0/etc/daemontools /service/service0
+[root@yourserver root]# ln -s /var/lib/aolserver/service0/etc/daemontools /service/service0
 [root@yourserver root]# sleep 10
 [root@yourserver root]# svgroup web /service/service0
 [root@yourserver root]#

Other Backup Strategies

Earlier strategies, included here because this section hasn't been fully updated yet.

Set Up Nightly Oracle Exports

(This has not yet been updated to fit with the Reference install. To do so, edit the backup script to save the backup - file in /web/service0/database-backup). + file in /var/lib/aolserver/service0/database-backup). While you're working with Oracle, you should configure it to do automatic exports. An export is a separate backup copy of the database. This copy includes all of the database's state at the @@ -275,7 +275,7 @@ root:~# crontab -l | grep export-oracle 0 23 * * * /usr/sbin/export-oracle root:~# exit -; Logout

If you see the line, go ahead and log out.

Set up nightly Postgres exports

This is an alternate method to the crontab backup. +; Logout

If you see the line, go ahead and log out.

Set up nightly Postgres exports

This is an alternate method to the crontabls - backup. Dowload this script to /tmp. At the top of the script are several variables that you'll need to customize: @@ -304,7 +304,7 @@ midnight. Note that this script only backs up the database - not the OpenACS scripts and file content. 

-joeuser:~$ cp /tmp/acs-pgbackup-init.txt ~/web/birdnotes/tcl/acs-pgbackup-init.tcl
+joeuser:~$ cp /tmp/acs-pgbackup-init.txt ~/var/lib/aolserver/birdnotes/tcl/acs-pgbackup-init.tcl
 joeuser:~$ restart-aolserver birdnotes

That's it! The script will email you with each successful backup (or if it fails, it will send you an email with the reason) Index: openacs-4/packages/acs-core-docs/www/compatibility-matrix.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/compatibility-matrix.html,v diff -u -r1.4 -r1.5 --- openacs-4/packages/acs-core-docs/www/compatibility-matrix.html 14 Oct 2003 11:02:57 -0000 1.4 +++ openacs-4/packages/acs-core-docs/www/compatibility-matrix.html 21 Oct 2003 10:04:47 -0000 1.5 @@ -2,4 +2,4 @@ by Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Figure�3.1.�Compatibility Matrix

OpenACS Version3.2.54.54.64.6.14.6.24.6.3
AolServer3Verified�����
3.3+ad13�Verified
3.3oacs1����Verified
PostGreSQL7.0Verified���
7.2.x�Verified
7.3.2Not compatibleUntested
Oracle8.1.6�Verified
8.1.7�Verified
9iNo
Prev Home Next
Chapter�3.�Prerequisite Software Up Individual Programs
docs@openacs.org
View comments on this page at openacs.org
+

Figure�3.1.�Compatibility Matrix

OpenACS Version3.2.54.54.64.6.14.6.24.6.3
AolServer3Verified�����
3.3+ad13�Verified
3.3oacs1����Verified
PostGreSQL7.0Verified���
7.2.x�Verified
7.3.2Not compatibleUntested
Oracle8.1.6�Verified
8.1.7�Verified
9iNo
Prev Home Next
Chapter�3.�Prerequisite Software Up Individual Programs
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/cvs-service-import.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/cvs-service-import.html,v diff -u -r1.4 -r1.5 --- openacs-4/packages/acs-core-docs/www/cvs-service-import.html 14 Oct 2003 11:02:57 -0000 1.4 +++ openacs-4/packages/acs-core-docs/www/cvs-service-import.html 21 Oct 2003 10:04:47 -0000 1.5 @@ -1,4 +1,4 @@ -Add the Service to CVS - OPTIONAL
Prev Appendix�A.�Using CVS with an OpenACS Site Next

Add the Service to CVS - OPTIONAL

These steps take an existing OpenACS directory and add +Add the Service to CVS - OPTIONAL

Prev Appendix�A.�Using CVS with an OpenACS Site Next

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 repository.

    [root@yourserver root]# mkdir /cvsroot/service0
 [root@yourserver root]# chown service0.web /cvsroot/service0
@@ -47,4 +47,4 @@
 
    cd ..
 mv service0 service0.orig
 cvs checkout service0
-exit
Prev Home Next
Appendix�A.�Using CVS with an OpenACS Site Up Part�IV.�For OpenACS Platform Developers
docs@openacs.org
View comments on this page at openacs.org
+exit
Prev Home Next
Appendix�A.�Using CVS with an OpenACS Site Up Appendix�B.�How to package and release OpenACS
docs@openacs.org
View comments on this page at openacs.org
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 -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/docbook-primer.html 14 Oct 2003 11:02:58 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/docbook-primer.html 21 Oct 2003 10:04:47 -0000 1.15 @@ -31,7 +31,7 @@ In order to separate content and presentation, all OpenACS documentation will be marked up to conform to the DocBook XML DTD - + This enables us to publish in a variety of formats and relieves each contributor of the burden of presentation, freeing him to focus on content and sharing knowledge. @@ -52,7 +52,7 @@ 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 you remember to: - +

Headlines, Sections

- + Given that your job starts at the sect1-level, all your documents should open with a <sect1>-tag and end with the corresponding </sect1>.

- + You need to feed every <sect1> two attributes. The first attribute, 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 Section�, “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 other attribute is xreflabel. The value of this is the text that will appear as the link when referring to this sect1.

@@ -150,7 +150,7 @@ </sect1>

- + Inside this container your document will be split up into <sect2>'s, each with the same requirements - id and xreflabel @@ -159,7 +159,7 @@ 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

- + For displaying a snippet of code, a filename or anything else you just want to appear as a part of a sentence, we will use the tag <computeroutput>. @@ -169,12 +169,12 @@ <programlisting> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of automatically.

Links

- + 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:

+	  
Check out how I link to a subsection of the Developer's Guide:
 
 	    Put this in your XML:
 
@@ -212,7 +212,7 @@
 	    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 a little different @@ -233,7 +233,7 @@ do it, so if you want to start converting your documents right away, start out with the ones without graphics ;)

- + To insert a graphic we use the elements <mediaobject>, <imageobject>, @@ -259,7 +259,7 @@ Put your graphics in a separate directory ("images") and link to them only with relative paths.

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 @@ -304,7 +304,7 @@ </variablelist>

Tables

- + DocBook supports several types of tables, but in most cases, the <informaltable> is enough: @@ -341,7 +341,7 @@ <table> for an example.

Emphasis

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

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 -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 14 Oct 2003 11:02:58 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 21 Oct 2003 10:04:47 -0000 1.3 @@ -1,4 +1,4 @@ -External Authentication Requirements

Prev Chapter�13.�Kernel Documentation

External Authentication Requirements

Vision

People have plenty of usernames and passwords already, we +External Authentication Requirements

Prev Chapter�13.�Kernel Documentation

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 @@ -44,7 +44,7 @@ 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:

    -

    Account Management (NO PICTURE YET)

    Batch Synchronization (NO PICTURE YET)

    Requirements

    New API

    FeatureStatusDescription
    EXT-AUTH-01AExtend Authentication/Acct Status API
    EXT-AUTH-03AAccount Creation API
    EXT-AUTH-05APassword Management API
    EXT-AUTH-30AAuthority Management API

    Login

    FeatureStatusDescription
    EXT-AUTH-04ARewrite login, register, and admin pages to use APIs
    EXT-AUTH-38Aad_form complain feature
    EXT-AUTH-19ARewrite password recovery to use API
    EXT-AUTH-21ARewrite email verification with API
    EXT-AUTH-28AUsername is email switch

    Users will log in using a username, a authority, and a +

    Account Management (NO PICTURE YET)

    Batch Synchronization (NO PICTURE YET)

    Requirements

    New API

    FeatureStatusDescription
    EXT-AUTH-01AExtend Authentication/Acct Status API
    EXT-AUTH-03AAccount Creation API
    EXT-AUTH-05APassword Management API
    EXT-AUTH-30AAuthority Management API

    Login

    FeatureStatusDescription
    EXT-AUTH-04ARewrite login, register, and admin pages to use APIs
    EXT-AUTH-38Aad_form complain feature
    EXT-AUTH-19ARewrite password recovery to use API
    EXT-AUTH-21ARewrite email verification with API
    EXT-AUTH-28AUsername is email switch

    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 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 -r1.4 -r1.5 --- openacs-4/packages/acs-core-docs/www/i18n.html 14 Oct 2003 11:02:58 -0000 1.4 +++ openacs-4/packages/acs-core-docs/www/i18n.html 21 Oct 2003 10:04:47 -0000 1.5 @@ -38,7 +38,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. -

    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 still processed.

    Message Keys in Template Files (ADP Files)

    +

    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 still processed.

    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 @@ -101,9 +101,9 @@

    Here are a couple of examples. Say we have the following two parameters, taken directly from the dotlrn package. -

    Table�13.1.�

    Parameter NameParameter Value
    class_instance_pages_csv#dotlrn.class_page_home_title#,Simple 2-Column;#dotlrn.class_page_calendar_title#,Simple 1-Column;#dotlrn.class_page_file_storage_title#,Simple 1-Column
    departments_pretty_name#departments_pretty_name#

    +

    Table�13.1.�

    Parameter NameParameter Value
    class_instance_pages_csv#dotlrn.class_page_home_title#,Simple 2-Column;#dotlrn.class_page_calendar_title#,Simple 1-Column;#dotlrn.class_page_file_storage_title#,Simple 1-Column
    departments_pretty_name#departments_pretty_name#

    Then, depending on how we retrieve the value, here's what we get: -

    Table�13.2.�

    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#departments_pretty_name#

    +

    Table�13.2.�

    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#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 for localization to happen you must use the -localize flag. @@ -151,7 +151,7 @@ Use the *_pretty version in your ADP page.

    To 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 Existing Packages

    Internationalize Message text in ADP and TCL

    Acs-lang includes tools to automate some +

    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 Existing Packages

    Internationalize Message text in ADP and TCL

    Acs-lang includes tools to automate some internationalization. From /acs-admin/apm/, select a package and then click on @@ -240,9 +240,9 @@ with the appropriate notation for the type of file, and store the text in the message catalog. You need to run the process twice, once for ADP files, and once for Tcl files. -

    Internationalize Package Parameters with visible messages

    +

    Internationalize Package Parameters with visible messages

    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" *
+

    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. 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 -r1.13 -r1.14 --- openacs-4/packages/acs-core-docs/www/index.html 17 Oct 2003 11:18:52 -0000 1.13 +++ openacs-4/packages/acs-core-docs/www/index.html 21 Oct 2003 10:04:47 -0000 1.14 @@ -1 +1 @@ -OpenACS Documentation

      Next

      OpenACS Documentation

      Table of Contents

      I. OpenACS For Everyone
      1. High level information: What is OpenACS?
      Overview
      OpenACS Release Notes
      II. Administrator's Guide
      2. Quick Install
      3. Prerequisite Software
      Compatibility Matrix
      Individual Programs
      4. Installing on Unix/Linux
      Overview
      Install Linux and supporting software
      Install Oracle 8.1.7
      Install PostGreSQL
      Install AOLserver 3.3oacs1
      Install OpenACS 5.0.0a1
      Credits
      5. Installing on Windows
      OpenACS Installation Guide for Windows2000
      6. Installing on a Macintosh
      OpenACS Installation Guide for Mac OS X
      7. Configuring a New Service
      8. Upgrading
      Support for upgrades.
      9. Maintenance
      Hosting Web Sites
      Database Management
      Backup and Recovery
      A. Install Red Hat 8.0
      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
      Install nsopenssl
      III. For OpenACS Package Developers
      10. Development Tutorial
      Creating a Package
      Setting Up Database Objects
      Creating Web Pages
      Debugging and Automated Testing
      Advanced Topics
      11. Development Reference
      OpenACS 5.0.0a1 Packages
      OpenACS Data Models and the Object System
      The Request Processor
      The OpenACS Database Access API
      Using Templates in OpenACS 5.0.0a1
      Groups, Context, Permissions
      Writing OpenACS 5.0.0a1 Application Pages
      Parties in OpenACS 5.0.0a1
      OpenACS 4.x Permissions Tediously Explained
      Object Identity
      Programming with AOLserver
      12. Engineering Standards
      OpenACS Documentation Guide
      Using PSGML mode in Emacs
      Detailed Design Documentation Template
      System/Application Requirements Template
      Release Version Numbering
      Constraint naming standard
      ACS File Naming and Formatting Standards
      PL/SQL Standards
      A. Using CVS with an OpenACS Site
      Add the Service to CVS - OPTIONAL
      B. How to package and release OpenACS
      IV. For OpenACS Platform Developers
      13. Kernel Documentation
      Overview
      OpenACS 4 Object Model Requirements
      OpenACS 4 Object Model Design
      OpenACS 4 Permissions Requirements
      OpenACS 4 Permissions Design
      OpenACS 4 Groups Requirements
      OpenACS 4 Groups Design
      OpenACS 4 Subsites Requirements
      OpenACS 4 Subsites Design Document
      OpenACS 5.0.0a1 Package Manager Requirements
      OpenACS 5.0.0a1 Package Manager Design
      Database Access API
      OpenACS Internationalization Requirements
      Internationalization
      OpenACS 4 Security Requirements
      OpenACS 4 Security Design
      OpenACS 4 Security Notes
      OpenACS 4 Request Processor Requirements
      OpenACS 4 Request Processor Design
      Documenting Tcl Files: Page Contracts and Libraries
      Bootstrapping OpenACS
      External Authentication Requirements

      List of Figures

      3.1. Compatibility Matrix
      4.1. Assumptions in this section
      8.1. Assumptions in this section
      10.1. Assumptions in this section
      10.2. Database Creation Script - master create file
      10.3. Database Creation Script - table
      10.4. Database Creation Script - functions
      10.5. Database deletion script

      List of Tables

      11.1.
      11.2.
      11.3.
      11.4.
      11.5.
      11.6.
      11.7.
      11.8.
      11.9.
      11.10.
      11.11.
      11.12.
      13.1.
      13.2.
      Next
      Part�I.�OpenACS For Everyone
      docs@openacs.org
      View comments on this page at openacs.org
      +OpenACS Documentation
      Next

      OpenACS Documentation

      Table of Contents

      I. OpenACS For Everyone
      1. High level information: What is OpenACS?
      Overview
      OpenACS Release Notes
      II. Administrator's Guide
      2. Quick Install
      3. Prerequisite Software
      Compatibility Matrix
      Individual Programs
      4. Installing on Unix/Linux
      Overview
      Install Linux and supporting software
      Install Oracle 8.1.7
      Install PostGreSQL
      Install AOLserver 3.3oacs1
      Install OpenACS 5.0.0a1
      Credits
      5. Installing on Windows
      OpenACS Installation Guide for Windows2000
      6. Installing on a Macintosh
      OpenACS Installation Guide for Mac OS X
      7. Configuring a New Service
      8. Upgrading
      Support for upgrades.
      9. Maintenance
      Hosting Web Sites
      Database Management
      Backup and Recovery
      A. Install Red Hat 8.0
      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
      Install nsopenssl
      III. For OpenACS Package Developers
      10. Development Tutorial
      Creating a Package
      Setting Up Database Objects
      Creating Web Pages
      Debugging and Automated Testing
      Advanced Topics
      11. Development Reference
      OpenACS 5.0.0a1 Packages
      OpenACS Data Models and the Object System
      The Request Processor
      The OpenACS Database Access API
      Using Templates in OpenACS 5.0.0a1
      Groups, Context, Permissions
      Writing OpenACS 5.0.0a1 Application Pages
      Parties in OpenACS 5.0.0a1
      OpenACS 4.x Permissions Tediously Explained
      Object Identity
      Programming with AOLserver
      12. Engineering Standards
      OpenACS Documentation Guide
      Using PSGML mode in Emacs
      Detailed Design Documentation Template
      System/Application Requirements Template
      Release Version Numbering
      Constraint naming standard
      ACS File Naming and Formatting Standards
      PL/SQL Standards
      A. Using CVS with an OpenACS Site
      Add the Service to CVS - OPTIONAL
      B. How to package and release OpenACS
      IV. For OpenACS Platform Developers
      13. Kernel Documentation
      Overview
      OpenACS 4 Object Model Requirements
      OpenACS 4 Object Model Design
      OpenACS 4 Permissions Requirements
      OpenACS 4 Permissions Design
      OpenACS 4 Groups Requirements
      OpenACS 4 Groups Design
      OpenACS 4 Subsites Requirements
      OpenACS 4 Subsites Design Document
      OpenACS 5.0.0a1 Package Manager Requirements
      OpenACS 5.0.0a1 Package Manager Design
      Database Access API
      OpenACS Internationalization Requirements
      Internationalization
      OpenACS 4 Security Requirements
      OpenACS 4 Security Design
      OpenACS 4 Security Notes
      OpenACS 4 Request Processor Requirements
      OpenACS 4 Request Processor Design
      Documenting Tcl Files: Page Contracts and Libraries
      Bootstrapping OpenACS
      External Authentication Requirements

      List of Figures

      3.1. Compatibility Matrix
      4.1. Assumptions in this section
      8.1. Assumptions in this section
      10.1. Assumptions in this section
      10.2. Database Creation Script - master create file
      10.3. Database Creation Script - table
      10.4. Database Creation Script - functions
      10.5. Database deletion script

      List of Tables

      11.1.
      11.2.
      11.3.
      11.4.
      11.5.
      11.6.
      11.7.
      11.8.
      11.9.
      11.10.
      11.11.
      11.12.
      13.1.
      13.2.
      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/install-cvs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-cvs.html,v diff -u -r1.4 -r1.5 --- openacs-4/packages/acs-core-docs/www/install-cvs.html 14 Oct 2003 11:02:58 -0000 1.4 +++ openacs-4/packages/acs-core-docs/www/install-cvs.html 21 Oct 2003 10:04:47 -0000 1.5 @@ -1,4 +1,4 @@ -Initialize CVS (OPTIONAL)
      Prev Appendix�B.�Install additional supporting software Next

      Initialize CVS (OPTIONAL)

      CVS is a source control system. Create and initialize a +Initialize CVS (OPTIONAL)

      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@yourserver tmp]# mkdir /cvsroot
 [root@yourserver tmp]# cvs -d /cvsroot init
 [root@yourserver tmp]#
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 -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/install-daemontools.html	14 Oct 2003 11:02:58 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/install-daemontools.html	21 Oct 2003 10:04:47 -0000	1.5
@@ -3,7 +3,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
        • Red Hat
          Make sure you have the source tarball in
+      services.
          1. Install Daemontools
            • Red Hat
              Make sure you have the source tarball in
           /tmp, or download it.  (The -p
               flag in mkdir causes all implied directories in the path
               to be made as well.)
              (Red Hat 9.0: put 
Index: openacs-4/packages/acs-core-docs/www/install-full-text-search.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/install-full-text-search.html,v
diff -u -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/install-full-text-search.html	14 Oct 2003 11:02:58 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/install-full-text-search.html	21 Oct 2003 10:04:47 -0000	1.5
@@ -1,4 +1,4 @@
-Install Full Text Search
              Prev Appendix�B.�Install additional supporting software Next
              Install Full Text Search
              Install OpenFTS 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 Full Text Search
              Prev Appendix�B.�Install additional supporting software Next
              Install Full Text Search
              Install OpenFTS 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 openfts
       tarball in /tmp.
              1. Install Tsearch.  This is a PostGreSQL module that
 	  OpenFTS requires.
                [root@yourserver root]# su - postgres
@@ -74,7 +74,7 @@
 make
 su postgres
 make install
-exit

    Install OpenFTS prerequisites in PostGreSQL instance

    If you are installing Full Text Search, add required +exit

    Install OpenFTS prerequisites in PostGreSQL instance

    If you are installing Full Text Search, add required packages to the new database. (In order for full text search to work, you must also install the PostGreSQL OpenFTS module and prerequisites.)

    [service0@yourserver service0]$ /usr/local/pgsql/bin/psql service0 -f /usr/local/src/postgresql-7.2.4/contrib/tsearch/tsearch.sql
@@ -113,4 +113,4 @@
 line, click
 Install.

  • Restart the service.

    [service0@yourserver service0]$ svc -t /service/service0
-[service0@yourserver service0]$

  • Test FTS. (INCOMPLETE). Add a package that supports search,like "note," add some content, and search for it.

    • Prev Home Next
    Installing LDAP support Up Install nsopenssl
    docs@openacs.org
    View comments on this page at openacs.org
    +[service0@yourserver service0]$

  • Test FTS. (INCOMPLETE). Add a package that supports search,like "note," add some content, and search for it.

    • Prev Home Next
    Configure Batch Synchronization Up Install nsopenssl
    docs@openacs.org
    View comments on this page at openacs.org
    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 -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/install-overview.html 14 Oct 2003 11:02:58 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/install-overview.html 21 Oct 2003 10:04:47 -0000 1.13 @@ -44,7 +44,7 @@

    Steps involved

    The basic steps to getting OpenACS up and running are:

    1. Install an OS

    2. Install a database (Oracle or - PostgreSQL)

    3. Install a webserver (AOLServer)

    4. Copy the OpenACS files into place and start the OpenACS installer, which will configure a database instance.

    How to use this guide

    How to use this guide

  • 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 dedicated IP address.

    1. DHCP is a system by which a computer that @@ -60,7 +60,7 @@ 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.

  • 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.

  • Select any additional languages you want the computer to support and then click Next

  • Choose your time zone and click Next.

  • Type in a root password, twice. To @@ -81,9 +81,9 @@ 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),
    +

    check�Editors�(this�installs�emacs),
    click�Details�next�to�Text-based�Internet,�check�lynx,�and�click�OK;
    -check�Authoring�and�Publishing�(this�installs�docbook),
    +check�Authoring�and�Publishing�(this�installs�docbook),
    uncheck�Server�Configuration�Tools,
    uncheck�Web�Server,
    uncheck�Windows�File�Server,
    @@ -96,7 +96,7 @@ 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,�
    +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),�
    @@ -124,7 +124,7 @@

  • After it finishes rebooting and shows the login prompt, log in:

    yourserver login: root
 Password:
-[root@yourserver root]#

  • Lock down SSH

    1. +[root@yourserver root]#

    2. Lock down SSH

      1. SSH is the protocol we use to connect securely to the computer (replacing telnet, which is insecure). sshd is the daemon that listens for incoming Index: openacs-4/packages/acs-core-docs/www/linux-installation.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/linux-installation.html,v diff -u -r1.5 -r1.6 --- openacs-4/packages/acs-core-docs/www/linux-installation.html 14 Oct 2003 11:02:58 -0000 1.5 +++ openacs-4/packages/acs-core-docs/www/linux-installation.html 21 Oct 2003 10:04:47 -0000 1.6 @@ -2,7 +2,7 @@ by Joel Aufrecht
        OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

      Paths and Users

      Figure�4.1.�Assumptions in this section

      Fully qualified domain name of your serveryourserver.test
      name of administrative access accountremadmin
      OpenACS serviceservice0
      OpenACS service accountservice0
      OpenACS database nameservice0
      Root of OpenACS service file tree/web/service0
      Location of source code tarballs for new software/tmp
      The OpenACS tarball contains some files which +

      Paths and Users

      Figure�4.1.�Assumptions in this section

      Fully qualified domain name of your serveryourserver.test
      name of administrative access accountremadmin
      OpenACS serviceservice0
      OpenACS service accountservice0
      OpenACS database nameservice0
      Root of OpenACS service file tree/web/service0
      Location of source code tarballs for new software/tmp
      The OpenACS tarball contains some files which are useful while setting up other software. Those files are located at:/tmp/openacs-5.0.0a1/packages/acs-core-docs/www/files
      Database backup directory/web/service0/database-backup
      Service config files/web/service0/etc
      Service log files/web/service0/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 Index: openacs-4/packages/acs-core-docs/www/objects.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/objects.html,v diff -u -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/objects.html 14 Oct 2003 11:02:58 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/objects.html 21 Oct 2003 10:04:47 -0000 1.15 @@ -80,7 +80,7 @@ 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: -

      Describe the new type to the type system

      +

      Describe the new type to the type system

      First, add an entry to the acs_object_types table with the following PL/SQL call: 

       begin  
@@ -140,7 +140,7 @@
 because the new type note is a subtype of
 acs_object, it will inherit these attributes, so there is
 no need for us to define them.
-

      Define a table in which to store your objects

      +

      Define a table in which to store your objects

      The next thing we do is make a small modification to the data model to reflect the fact that each row in the notes table represents something that is not only an object of type @@ -165,7 +165,7 @@ use the acs_objects table to find objects will transparently find any objects that are instances of any subtype of acs_objects. -

      Define a package for type specific procedures

      +

      Define a package for type specific procedures

      The next step is to define a PL/SQL package for your new type, and write some basic procedures to create and delete objects. Here is a package definition for our new type: @@ -213,7 +213,7 @@ 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 procedures

      +

      Define a package body for type specific procedures

      The PL/SQL package body contains the implementations of the procedures defined above. The only subtle thing going on here is that we must use acs_object.new to insert a row into Index: openacs-4/packages/acs-core-docs/www/openacs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs.html,v diff -u -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/openacs.html 14 Oct 2003 11:02:58 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/openacs.html 21 Oct 2003 10:04:47 -0000 1.12 @@ -244,7 +244,7 @@ CREATE DATABASE [service0@yourserver service0]$ 

      su - service0
-createdb -E UNICODE service0

    3. 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.

      [service0@yourserver service0]$ export EDITOR=emacs;crontab -e

      Add this line to the file. 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.

      0 1 * * * /usr/local/pgsql/bin/vacuumdb --analyze service0

    4. Add Full Text Search Support (OPTIONAL)

    5. [service0@yourserver service0]$ exit
+createdb -E UNICODE service0

    6. 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.

      [service0@yourserver service0]$ export EDITOR=emacs;crontab -e

      Add this line to the file. 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.

      0 1 * * * /usr/local/pgsql/bin/vacuumdb --analyze service0

    7. Add Full Text Search Support (OPTIONAL)

    8. [service0@yourserver service0]$ exit
 logout
 
 [root@yourserver root]#

      9. Configure an AOLserver Service for OpenACS

      1. @@ -254,7 +254,7 @@ need to configure a virtual server. The Reference Platform uses a configuration file included in the OpenACS tarball, /var/lib/aolserver/service0/etc/config.tcl. - Open it in an editor to adjust the parameters.

        [root@yourserver root]# su - service0
+	   Open it in an editor to adjust the parameters.
        [root@yourserver root]# su - service0
 [service0@yourserver service0]$ cd /var/lib/aolserver/service0/etc
 [service0@yourserver etc]# emacs config.tcl
 
        
@@ -378,7 +378,7 @@
 		  5.0.0a1 is now up and running!

      2. Install Full Text Search (OPTIONAL). If you have installed OpenFTS and enabled OpenFTS, you can now install the OpenFTS Driver package and - Full Text Search Engine package in the OpenACS service.

      Next Steps

      • This is a good time to make a backup of your service. If this is a + Full Text Search Engine package in the OpenACS service.

      Next Steps

      • This is a good time to make a backup of your service. If this is a production site, you should set up automatic nightly backups.

      • If you want traffic reports, set up analog or another log processing program.

      • Follow the instruction on the home page to change the appearance of your service or add more 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 -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 14 Oct 2003 11:02:58 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 21 Oct 2003 10:04:48 -0000 1.8 @@ -85,7 +85,7 @@ to store permission information explicitly about every object, i.e. if the system has 100,000 and 1,000 users who have the read privilege on all objects, then we would need to store 100,000,000 entries of the form: -

        Table�11.1.�

        object_idgrantee_idprivilege
        object_id_1user_id_1'read'
        object_id_1user_id_2'read'
        ...
        object_id_1user_id_n'read'
        object_id_2user_id_1'read'
        object_id_2user_id_2'read'
        ...
        object_id_2user_id_n'read'
        ...
        ...
        object_id_muser_id_1'read'
        object_id_muser_id_2'read'
        ...
        object_id_muser_id_n'read'

        +

        Table�11.1.�

        object_idgrantee_idprivilege
        object_id_1user_id_1'read'
        object_id_1user_id_2'read'
        ...
        object_id_1user_id_n'read'
        object_id_2user_id_1'read'
        object_id_2user_id_2'read'
        ...
        object_id_2user_id_n'read'
        ...
        ...
        object_id_muser_id_1'read'
        object_id_muser_id_2'read'
        ...
        object_id_muser_id_n'read'

        Although quite feasible, this approach fails to take advantage of the fact that objects in the system are commonly organized hierarchally, and permissions usually follow the hierarchical structure, so that if user @@ -100,7 +100,7 @@

      Context Hierarchy

      Suppose objects A, B, ..., and F form the following hierarchy. -

      Table�11.2.�

      A

      +

      Table�11.2.�

      A

      object_id=10

      B

      object_id=20 @@ -116,23 +116,23 @@ This can be represented in the acs_objects table by the following entries: -

      Table�11.3.�

      object_idcontext_id
      2010
      3010
      4020
      5020
      6030

      +

      Table�11.3.�

      object_idcontext_id
      2010
      3010
      4020
      5020
      6030

      The first entry tells us that object 20 is the descendant of object 10, and the third entry shows that object 40 is the descendant of object 20. By running a CONNECT BY query, we can compute that object 40 is the second-generation descendant of object 10. With this in mind, if we want to record the fact that user Joe has the read privilege on objects A, ..., F, we only need to record one entry in the acs_permissions table. -

      Table�11.4.�

      objectgranteeprivilege
      AJoeread

      +

      Table�11.4.�

      objectgranteeprivilege
      AJoeread

      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.

      One way to solve this problem is to cache a flattened view of the context tree like so: -

      Table�11.5.�

      objectancestorn_generations
      AA0
      BB0
      BA1
      CC0
      CA1
      DD0
      DB1
      DA2
      EE0
      EB1
      EA2
      FF0
      FC1
      FA2

      +

      Table�11.5.�

      objectancestorn_generations
      AA0
      BB0
      BA1
      CC0
      CA1
      DD0
      DB1
      DA2
      EE0
      EB1
      EA2
      FF0
      FC1
      FA2

      Note that the number of entries in the flattened view grows exponentially with respect to the depth of the context tree. For instance, if you have a fully populated binary tree with a depth of n, then the number of entries @@ -203,7 +203,7 @@ 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. -

      Table�11.6.�


      +

      Table�11.6.�


      A
      object_id=10
      readable�by�Joe
      @@ -231,7 +231,7 @@ Privileges are also organized hierarchically. In addition to the five main system privileges defined in the ACS Kernel data model, application developers may define their own. For instance, the Bboard package defines the following privileges: -

      Table�11.7.�

      privilege
      create_category
      create_forum
      create_message
      delete_category
      delete_forum
      delete_message
      moderate_forum
      read_category
      read_forum
      read_message
      write_category
      write_forum
      write_message

      +

      Table�11.7.�

      privilege
      create_category
      create_forum
      create_message
      delete_category
      delete_forum
      delete_message
      moderate_forum
      read_category
      read_forum
      read_message
      write_category
      write_forum
      write_message

      By defining parent-child relationship between privileges, the OpenACS data model makes it easier for developers to manage permissions. Instead of granting a user explicit read, write, delete, @@ -240,7 +240,7 @@ privilege to which the first four privileges are tied. To give a more detailed example, the Bboard privileges are structured as follows. -

      Table�11.8.�

      admin
      createdeletereadwritemoderate forum
      create categorycreate forumcreate messagedelete categorydelete forumdelete messageread categoryread forumread messagewrite categorywrite forumwrite message

      +

      Table�11.8.�

      admin
      createdeletereadwritemoderate forum
      create categorycreate forumcreate messagedelete categorydelete forumdelete messageread categoryread forumread messagewrite categorywrite forumwrite message

      The parent-child relationship between privileges is represented in the acs_privilege_hierarchy table: 

      @@ -286,7 +286,7 @@

      Party Hierarchy

      Now for the third hierarchy playing a promiment role in the permission system. The party data model is set up as follows. -

      Table�11.9.�

      parties
      personsgroups
      users
      +    
      Table�11.9.�
      parties
      personsgroups
      users
         create table parties (
       party_id
           not null
@@ -370,7 +370,7 @@
     
      
       The acs_rels 
       table entries would look like so: 
-    
      Table�11.10.�
      rel_typeobject_oneobject_two
      
+    
      Table�11.10.�
      rel_typeobject_oneobject_two
      
 	      membership_rel
 	    
 	      Pranksters
@@ -405,7 +405,7 @@
     
      
       The relevant entries in the 
       acs_rels look like so. 
-    
      Table�11.11.�
      rel_typeobject_oneobject_two
      
+    
      Table�11.11.�
      rel_typeobject_oneobject_two
      
 	      composition_rel
 	    
 	      Pranksters
@@ -616,7 +616,7 @@
     
      
       Note that in the above example, acs_permissions had only
       one entry that needed to be deleted: 
-    
      Table�11.12.�
      object_idgrantee_idprivilege
      
+    
      Table�11.12.�
      object_idgrantee_idprivilege
      
 	      default_context
 	    
 	      registered_users
Index: openacs-4/packages/acs-core-docs/www/postgres.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/postgres.html,v
diff -u -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/postgres.html	14 Oct 2003 11:02:58 -0000	1.11
+++ openacs-4/packages/acs-core-docs/www/postgres.html	21 Oct 2003 10:04:48 -0000	1.12
@@ -63,7 +63,7 @@
 	  Change to the postgres user and run ./configure to set the compilation options automatically. This is the point at which you can
 	  configure PostgreSQL in various ways. For example, if you want to
 	  enable
-	  Unicode support, add the flags --enable-locale and --enable-multibyte. If you want to see what the other possibilities are, run ./configure --help.
+	  Unicode support, add the flags --enable-locale and --enable-multibyte. If you want to see what the other possibilities are, run ./configure --help.
 	
      [root@yourserver src]# su - postgres
 [postgres@yourserver pgsql]$ cd /usr/local/src/postgresql-7.2.4
 [postgres@yourserver postgresql-7.2.4]$ ./configure
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 -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html	14 Oct 2003 11:02:59 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html	21 Oct 2003 10:04:48 -0000	1.5
@@ -1,4 +1,4 @@
-Add PSGML commands to emacs init file (OPTIONAL)
      Prev Appendix�B.�Install additional supporting software Next
      Add PSGML commands to emacs init file (OPTIONAL)
      
+Add PSGML commands to emacs init file (OPTIONAL)
      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/quick.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/quick.html,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/quick.html	14 Oct 2003 11:02:59 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/quick.html	21 Oct 2003 10:04:48 -0000	1.4
@@ -8,6 +8,6 @@
 	  installation in under an hour.  It excludes source control,
 	  full text search, ssl, managed services (daemontools),
 	  DocBook, and qmail.  
-	
      For Red Hat 9
      1. Install PostGreSQL 7.3.2 from RPM.  Select
+	
      For Red Hat 9
      1. Install PostGreSQL 7.3.2 from RPM.  Select
         Menu > System Settings > Add/Remove
         Applications and select Database Server.
      After completing installation and restarting the server, go to http://localhost:8000 for configuration and customization instructions.  You can upgrade a Quick Install with source control, full text search, backup/recovery, and other production features by walking through the Installation documentation and doing the steps marked OPTIONAL.
      ($Id$)
      Prev Home Next
      Part�II.�Administrator's Guide Up Chapter�3.�Prerequisite Software
      docs@openacs.org
      View comments on this page at openacs.org
      
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 -r1.16 -r1.17
--- openacs-4/packages/acs-core-docs/www/release-notes.html	14 Oct 2003 11:02:59 -0000	1.16
+++ openacs-4/packages/acs-core-docs/www/release-notes.html	21 Oct 2003 10:04:48 -0000	1.17
@@ -83,4 +83,4 @@
           Who's online feature.
         
    9. 
           Spell checking.
-        
      10. ($Id$)
      Version 4.6.3
      Release Notes for 4.6.3
      Version 4.6.2
      Release Notes for 4.6.2
      Version 4.6
      Release Notes for 4.6
      Version 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$)
      Version 4.6.3
      Release Notes for 4.6.3
      Version 4.6.2
      Release Notes for 4.6.2
      Version 4.6
      Release Notes for 4.6
      Version 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/request-processor.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/request-processor.html,v
diff -u -r1.13 -r1.14
--- openacs-4/packages/acs-core-docs/www/request-processor.html	14 Oct 2003 11:02:59 -0000	1.13
+++ openacs-4/packages/acs-core-docs/www/request-processor.html	21 Oct 2003 10:04:48 -0000	1.14
@@ -13,7 +13,7 @@
 diagram summarizes the stages of the request processor assuming a URL
 request like http://someserver.com/notes/somepage.adp.
 
-

      [D]
      
+

      [D]
      
 
 
      Stage 1: Search Site Map
      
 The first thing the RP does is to map the given URL to the appropriate
Index: openacs-4/packages/acs-core-docs/www/tutorial-advanced.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-advanced.html,v
diff -u -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/tutorial-advanced.html	14 Oct 2003 11:02:59 -0000	1.5
+++ openacs-4/packages/acs-core-docs/www/tutorial-advanced.html	21 Oct 2003 10:04:48 -0000	1.6
@@ -2,15 +2,15 @@
     by Joel Aufrecht
      
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
      Overview
      This tutorial covers topics which are not essential to
+        
      Overview
      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.
      • 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 make your package send email notifications
      • How to prepare pagelets for inclusion in other pages
      • How and when to put procedures in a tcl procedure library
      • How to add general_comments to your pages
      • More on ad_form - data validation, other stuff.
       (plan to draw from Jon Griffin's doc)
      • How and when to implement caching
      • partialquery in xql
      • How to use the html/text entry widget to get the
-      "does this look right" confirm page 
      • APM package dependencies
      Delete with confirmation
      We need a way to delete records.  We'll create a
+      "does this look right" confirm page 
    10. APM package dependencies
      11. Delete with confirmation
      We need a way to delete records.  We'll create a
     recursive confirmation page.
      Add this column to the table_def in index.tcl
      {delete "" {} {<td><a href="note-delete?note_id=$note_id">Delete</a></td>}}
      Create the delete confirmation/execution page.
      [service0@yourserver www]$ emacs note-delete.tcl
      ad_page_contract {
     A page that gets confirmation and then delete notes.
 
@@ -70,7 +70,7 @@
 <formtemplate id="note-del-confirm"></formtemplate>
 </form>
      The ADP is very simple.  The
 formtemplate tag outputs the HTML
-form generated by the ad_form command with the matching name.  Test it by adding the new files in the APM and then deleting a few samplenotes.
      General_comments
      You can track comments for any ACS Object.  Here we'll track
+form generated by the ad_form command with the matching name.  Test it by adding the new files in the APM and then deleting a few samplenotes.
      General_comments
      You can track comments for any ACS Object.  Here we'll track
     comments for notes.  On the notes.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
@@ -91,13 +91,13 @@
     there are comments. Then you pass the note id, which is also the
     acs_object id.
      We put our two new variables in the notes.adp
     page.
      <a href="@comment_add_url@">Add a comment</a>
-@comments_html@
      Prepare the package for distribution.
      Browse to the package manager.  Click on
+@comments_html@
      Prepare the package for 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
-        /tmp.
      
+        /tmp.
      
 
      Prev Home Next
      Debugging and Automated Testing 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-database.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-database.html,v
diff -u -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/tutorial-database.html	14 Oct 2003 11:02:59 -0000	1.5
+++ openacs-4/packages/acs-core-docs/www/tutorial-database.html	21 Oct 2003 10:04:48 -0000	1.6
@@ -2,7 +2,7 @@
       by Joel Aufrecht
      
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
      Code the data model
      We create all database objects with scripts in the
+        
      Code the data model
      We create all database objects with scripts in the
       samplenote/sql/ directory.  All
       database scripts are database-specific and are thus in either
       the samplenote/sql/oracle or
@@ -39,7 +39,7 @@
       @author which will be picked up
       by the API browser.  The string
       $Id$ will automatically be
-      expanded when the file is checked in to cvs.
      [service0@yourserver postgresql]$ emacs samplenote-create.sql
      Paste this into the file and save and close.
      Figure�10.2.�Database Creation Script - master create file
      --
+      expanded when the file is checked in to cvs.
      [service0@yourserver postgresql]$ emacs samplenote-create.sql
      Paste this into the file and save and close.
      Figure�10.2.�Database Creation Script - master create file
      --
 -- packages/samplenote/sql/postgresql/samplenote-create.sql
 --
 -- @author rhs@mit.edu
@@ -49,7 +49,7 @@
 --
 
 \i samplenote-table-create.sql
-\i samplenote-functions-create.sql
      Create the file to create the database table.
      [service0@yourserver postgresql]$ emacs samplenote-table-create.sql
      Paste this into the file and save and close.
      Figure�10.3.�Database Creation Script - table
      --
+\i samplenote-functions-create.sql
      Create the file to create the database table.
      [service0@yourserver postgresql]$ emacs samplenote-table-create.sql
      Paste this into the file and save and close.
      Figure�10.3.�Database Creation Script - table
      --
 -- packages/samplenote/sql/postgresql/samplenote-table-create.sql
 --
 -- @author rhs@mit.edu
@@ -92,7 +92,7 @@
 	null,				        -- type_extension_table
 	''samplenote__name'' 			-- name_method
 	);
-
      Create the file to create the functions used to manipulate records.
      [service0@yourserver postgresql]$ emacs samplenote-functions-create.sql
      Paste this into the file and save and close.
      Figure�10.4.�Database Creation Script - functions
      --
+
      Create the file to create the functions used to manipulate records.
      [service0@yourserver postgresql]$ emacs samplenote-functions-create.sql
      Paste this into the file and save and close.
      Figure�10.4.�Database Creation Script - functions
      --
 -- packages/samplenote/sql/postgresql/samplenote-functions-create.sql
 --
 -- @author rhs@mit.edu
@@ -187,7 +187,7 @@
 end;
 ' language 'plpgsql';
 
      Create a database file to drop everything if the package
-        is uninstalled.
      [service0@yourserver postgresql]$ emacs samplenote-drop.sql
      Figure�10.5.�Database deletion script
      -- packages/samplenote/sql/samplenote-drop.sql
+        is uninstalled.
      [service0@yourserver postgresql]$ emacs samplenote-drop.sql
      Figure�10.5.�Database deletion script
      -- packages/samplenote/sql/samplenote-drop.sql
 -- drop script
 --
 -- @author rhs@mit.edu
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 -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/tutorial-debug.html	14 Oct 2003 11:02:59 -0000	1.5
+++ openacs-4/packages/acs-core-docs/www/tutorial-debug.html	21 Oct 2003 10:04:48 -0000	1.6
@@ -2,7 +2,7 @@
     by Joel Aufrecht
      
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
      Debugging
      Developer Support.�The Developer Support package adds several goodies: debug
+        
      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
@@ -24,17 +24,17 @@
 ?�searches�backward�
      
 /�searches�forward.�
      
 ����������
      
-        
      Manual testing
      Make a list of basic tests to make sure it works
      Test NumActionExpected Result
      001Browse to the index page while not logged in and
+        
      Manual testing
      Make a list of basic tests to make sure it works
      Test NumActionExpected Result
      001Browse to the index page while not logged in and
             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.
      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
      
+        Search for a note.
      Write automated tests
      
       by Simon Carstensen
      
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
      It seems to me that a lot of
+        
      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
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 -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html	14 Oct 2003 11:02:59 -0000	1.5
+++ openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html	21 Oct 2003 10:04:48 -0000	1.6
@@ -2,19 +2,19 @@
       by Joel Aufrecht
      
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
      Overview
      To start developing new code in OpenACS, we build a new
+        
      Overview
      To start developing new code in OpenACS, we build a new
     package.  A package is a a discrete collection of web
     pages, tcl code, and database tables and procedures.  A package
     can be installed, upgraded, and removed.  It communicates with
     other packages through an API.  This chapter walks you through the
     minimum steps to create a useful package, including writing
       documentation, setting up database tables and procedures,
       writing web pages, debugging, and automatic regression testing.
-
      Before you begin
      You will need:
      • A computer with a working installation of OpenACS
+
      Before you begin
      You will need:
      • A computer with a working installation of OpenACS
 	    4.6.  If you don't have this, see Installation Overview.
 	  
      • Example files, which are included in the
 standard OpenACS 5.0.0a1 distribution.
-	  
      Figure�10.1.�Assumptions in this section
      Fully qualified domain name of your serveryourserver.test
      URL of your serverhttp://yourserver.test:8000
      Name of development accountservice0
      New Package keysamplenote
      Use the APM to initialize a new package
      We use the ACS Package Manager (APM) to add, remove, and
+	  
      Figure�10.1.�Assumptions in this section
      Fully qualified domain name of your serveryourserver.test
      URL of your serverhttp://yourserver.test:8000
      Name of development accountservice0
      New Package keysamplenote
      Use the APM to initialize a new package
      We use the ACS Package Manager (APM) to add, remove, and
     upgrade packages.  It handles package meta-data, such as lists of
     files that belong in the package.  Each package is uniquely
     identified by a package key.  To start developing a new
@@ -42,7 +42,7 @@
         
      This creates a package rooted at
           /web/service0/packages/samplenote.
           This is the "home directory" of our new package, and all
-          files in the package will be within this directory.
      Mount the package in the site map
      In order to see your work in progress, you must create a
+          files in the package will be within this directory.
      Mount the package in the site map
      In order to see your work in progress, you must create a
       map between the URL space of incoming requests and the package.
       You do this by mounting the package in the Site Map.  This
       creates a link between the incoming URL and an
@@ -64,7 +64,7 @@
 click New.
 
      By mounting the package, we've caused all requests to
       http://yourserver.test:8000/note
-      to be satisfied from the files at /web/service0/packages/samplenote/www.
      Write the Requirements and Design Specs
      It's time to document.  For the tutorial we'll use
+      to be satisfied from the files at /web/service0/packages/samplenote/www.
      Write the Requirements and Design Specs
      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
 	/web/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml
@@ -114,7 +114,7 @@
 Writing bi01.html for bibliography
 Writing index.html for book
 [service0@yourserver xml]$
      Verify that the documentation was generated and reflects
-      your changes by browsing to http://yoursite:8000/samplenote/doc
      Add the new package to CVS
      Before you do any more work, make sure that your work is
+      your changes by browsing to http://yoursite:8000/samplenote/doc
      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
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 -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/tutorial-pages.html	14 Oct 2003 11:02:59 -0000	1.5
+++ openacs-4/packages/acs-core-docs/www/tutorial-pages.html	21 Oct 2003 10:04:48 -0000	1.6
@@ -2,7 +2,7 @@
     by Joel Aufrecht
      
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
      Build the "Index" page
      Each user-visible page in your package has, typically,
+        
      Build the "Index" page
      Each user-visible page in your package has, typically,
       three parts.  The xql file contains any database queries, the
       tcl file holds the procedural logic for the page and does things
       like check permissions, invoke the database queries, and modify
@@ -69,7 +69,7 @@
 </queryset>
      Create the user-visible page.
      [service0@yourserver www]$ emacs index.adp
      The first line indicates that this page should be rendered within the the master template, which defaults to /web/service0/www/default-master.  The second line passes a title variable to the master template.  The third line inserts the contents of the variable table_html.  The last line is a link to a page we haven't created yet.
      <master>
 <property name="title">Sample Notes</property>
 @table_html@
-<p><a href="note-edit">Add a note</a></p>
      Making the APM load your files
      Before we can test these files, we have to notify the
+<p><a href="note-edit">Add a note</a></p>
      Making the APM load your files
      Before we can test these files, we have to notify the
       package manager that they exist.  (More precisely, the tcl and
       adp will work fine as-is, but the xql file will not be
       recognized until we tell the APM about it.).
      •  Go to http://yourserver.test:8000/acs-admin/apm
      • Click on the samplenote link
      • Click Manage file information
      • 
@@ -85,7 +85,7 @@
             to load the contents of the XQL into memory so that it can
             be used, and to reload it whenever the file is changed.
             The watch will last until the server is restarted.
-          
      Now that the APM is aware of your files, check to make sure that the self-documenting code is working.
      • Browse to http://yourserver.test:8000/api-doc/
      • Click Notes 0.1d
      • Click Content Pages
      • Click index.tcl and examine the results.
      Test the index page
      Go to http://yourserver.test:8000/note/.  You should see this:
      +          
      Now that the APM is aware of your files, check to make sure that the self-documenting code is working.
      • Browse to http://yourserver.test:8000/api-doc/
      • Click Notes 0.1d
      • Click Content Pages
      • Click index.tcl and examine the results.
      Test the index page
      Go to http://yourserver.test:8000/note/.  You should see this:
       Sample Notes
 Your Workspace : Main Site : Sample Note 
 
@@ -94,7 +94,7 @@
 Add a note.
 
 foo@yourserver.test
-
      Since our table is empty, it's a pretty boring page.  So next we'll make it possible to add records. 
      If you get any other output, such as an error message, skip to Section�, “Debugging and Automated Testing”.
      Add the add/edit page
      We'll create a single page to handle both adding and
+
      Since our table is empty, it's a pretty boring page.  So next we'll make it possible to add records. 
      If you get any other output, such as an error message, skip to Section�, “Debugging and Automated Testing”.
      Add the add/edit page
      We'll create a single page to handle both adding and
       editing records.  In this recursive approach, the same tcl
       function can present a blank HTML form, present the same form
       pre-loaded with an existing record, and handle the resulting
@@ -173,7 +173,7 @@
       title, for both variables but
       wrap it in curly brackets for context so that the spaces aren't
       interpreted separators.  The formtemplate tag outputs the form
-      html with the matching name.
      Go to the APM as before and reload.  Then test all this by going to the package home page and adding and editing a few records.
      Adding files to cvs
      Put your new work into source control.
      [service0@yourserver www]$ cvs add *.adp *.tcl *.xql
+      html with the matching name.
      Go to the APM as before and reload.  Then test all this by going to the package home page and adding and editing a few records.
      Adding files to cvs
      Put your new work into source control.
      [service0@yourserver www]$ cvs add *.adp *.tcl *.xql
 cvs add: cannot add special file `CVS'; skipping
 cvs add: doc/CVS already exists
 cvs add: scheduling file `index.adp' for addition
Index: openacs-4/packages/acs-core-docs/www/upgrade-detail.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/upgrade-detail.html,v
diff -u -r1.7 -r1.8
--- openacs-4/packages/acs-core-docs/www/upgrade-detail.html	14 Oct 2003 11:02:59 -0000	1.7
+++ openacs-4/packages/acs-core-docs/www/upgrade-detail.html	21 Oct 2003 10:04:48 -0000	1.8
@@ -9,13 +9,13 @@
     manual intervention should be required.  If you are running
     OpenACS prior to 4.5, upgrading will require manual effort.
      Checklist
      The required platform for OpenACS 4.6 is the same as
     4.5, with the excepion of OpenFTS.  You now need OpenFTS 0.3.2, not 0.2.
-    OpenACS 4.6 does not support PostGreSQL 7.3.
      Overview
      OpenACS consists of files and a database schema.  The files
+    OpenACS 4.6 does not support PostGreSQL 7.3.
      Overview
      OpenACS consists of files and a database schema.  The files
     in the OpenACS 4.6 tarball include database upgrade scripts.  To start the
     upgrade, replace your existing files with the new files and
     then restart the server.  Then, browse to the APM, which will
     detect the new packages and offer to run the appropriate database upgrade
     scripts.  After restarting the server again, the upgrade is
-    complete.
      Figure�8.1.�Assumptions in this section
      name of OpenACS usernsadmin
      OpenACS server nameopenacs-dev
      Root of OpenACS file tree/web/openacs-dev
      Database backup directory/backup/openacs/
      Upgrading on Linux/Unix
      1. Make a Backup.�Back up the database and file system (see Section�, “Snapshot backup and recovery”).
      2. OPTIONAL: Upgrade OpenFTS.�OpenACS Full Text Search requires several pieces: the OpenFTS code, some database functions, and the OpenFTS Engine.  If you have OpenFTS 0.2, you'll need to upgrade to to OpenFTS 0.3.2.  This is backwards-compatible -
+    complete.
        Figure�8.1.�Assumptions in this section
        name of OpenACS usernsadmin
        OpenACS server nameopenacs-dev
        Root of OpenACS file tree/web/openacs-dev
        Database backup directory/backup/openacs/
      Upgrading on Linux/Unix
      1. Make a Backup.�Back up the database and file system (see Section�, “Snapshot backup and recovery”).
      2. OPTIONAL: Upgrade OpenFTS.�OpenACS Full Text Search requires several pieces: the OpenFTS code, some database functions, and the OpenFTS Engine.  If you have OpenFTS 0.2, you'll need to upgrade to to OpenFTS 0.3.2.  This is backwards-compatible -
         completing this step will not break a working OpenFTS Engine from 4.5.
 
        1. Uninstall the old OpenFTS Engine
          1. Browse to http://yourserver/openfts.
 
          2. Click Administration.
          3. Click Drop OpenFTS Engine
        2. Build and install the new OpenFTS driver and supporting tcl procedures.  (This section of shell code is not fully documented; please exercise care.)
          cd /usr/local/src/
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 -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/recovery.xml	20 Aug 2003 16:20:19 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/recovery.xml	21 Oct 2003 10:04:49 -0000	1.5
@@ -58,11 +58,11 @@
         OpenACS installations comprise files and database contents.
         If you follow the reference install and put all files,
         including configuration files, in
-        /web/service0/,
+        /var/lib/aolserver/service0/,
         and back up the database nightly to a file in
-        /web/service0/database-backup,
+        /var/lib/aolserver/service0/database-backup,
         then you can apply standard file-based backup strategies to
-        /web/service0
+        /var/lib/aolserver/service0
 
     
     
@@ -80,14 +80,14 @@
             Create a backup file and verify that it was created and has a reasonable size (several megabytes).
           
           [root@localhost root]# su - service0
-[service0@localhost service0]$ pg_dump -f /web/service0/database-backup/before_upgrade_to_4.6.dmp service0
-[service0@localhost service0]$ ls -al /web/service0/database-backup/before_upgrade_to_4.6.dmp 
--rw-rw-r-x    1 service0  service0   4005995 Feb 21 18:28 /web/service0/database-backup/before_upgrade_to_4.6.dmp
+[service0@localhost service0]$ pg_dump -f /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp service0
+[service0@localhost service0]$ ls -al /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp 
+-rw-rw-r-x    1 service0  service0   4005995 Feb 21 18:28 /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp
 [service0@localhost service0]$ exit
 [root@localhost root]#
 su - service0
-pg_dump -f /web/service0/database-backup/before_upgrade_to_4.6.dmp openacs-dev
-ls -al /web/service0/database-backup/before_upgrade_to_4.6.dmp
+pg_dump -f /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp openacs-dev
+ls -al /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp
 exit
         
         
@@ -100,10 +100,10 @@
               current system time, down to the minute.  For maximum
               safety, you can apply a tag to your current
               files.
-            Note that, if you did the CVS options in this document, the /web/service0/etc directory is not included in cvs and you may want to add it.
+            Note that, if you did the CVS options in this document, the /var/lib/aolserver/service0/etc directory is not included in cvs and you may want to add it.
             
             [root@localhost root]# su - service0
-[service0@localhost service0]$ cd /web/service0
+[service0@localhost service0]$ cd /var/lib/aolserver/service0
 [service0@localhost service0]$ cvs commit -m "last-minute commits before upgrade to 4.6"
 cvs commit: Examining .
 cvs commit: Examining bin
@@ -116,17 +116,17 @@
 [service0@localhost service0]$ exit
 [root@localhost root]# 
 su - service0
-cd /web/service0
+cd /var/lib/aolserver/service0
 cvs commit -m "last-minute commits before upgrade to 4.6"
 cvs tag before_upgrade_to_4_6
 exit
           To restore files from a cvs tag such as the one used above:
           [root@localhost root]# su - service0
-[service0@localhost service0]$ cd /web/service0
+[service0@localhost service0]$ cd /var/lib/aolserver/service0
 [service0@localhost service0]$ cvs up -r current
 [service0@localhost service0]$ exit
 su - service0
-cd /web/service0
+cd /var/lib/aolserver/service0
 cvs up -r current
           
           
@@ -135,16 +135,16 @@
               If you don't use cvs, you may want to back up the working directory.  The simplest way is just to copy it.
             
             [root@localhost root]# su - service0
-[service0@localhost service0]$ cp -r /web/service0 /web/service0-before-upgrade-to-4.6
+[service0@localhost service0]$ cp -r /var/lib/aolserver/service0 /var/lib/aolserver/service0-before-upgrade-to-4.6
 [service0@localhost service0]$ exit
 [root@localhost root]# 
 su - service0
-cp -r /web/service0 /web/service0-before-upgrade-to-4.6
+cp -r /var/lib/aolserver/service0 /var/lib/aolserver/service0-before-upgrade-to-4.6
 exit
           To restore the files, copy the directory back (do this while the service is stopped):
           [root@localhost root]# su - service0
-[service0@localhost service0]$ mv /web/service0 /web/openacs-failed-upgrade
-[service0@localhost service0]$ mv /web/service0-before-upgrade-to-4.6 /web/service0
+[service0@localhost service0]$ mv /var/lib/aolserver/service0 /var/lib/aolserver/openacs-failed-upgrade
+[service0@localhost service0]$ mv /var/lib/aolserver/service0-before-upgrade-to-4.6 /var/lib/aolserver/service0
 [service0@localhost service0]$ exit
 [root@localhost root]#
         
@@ -166,7 +166,7 @@
 common procedures before running the restore usually addresses this.
 You will see a number of "already exists" errors when you run the
 database restore; these can be ignored.  This forum thread has more information.
-[service0@localhost service0]$ psql -f /web/service0/packages/acs-kernel/sql/postgresql/postgresql.sql service0
+[service0@localhost service0]$ psql -f /var/lib/aolserver/service0/packages/acs-kernel/sql/postgresql/postgresql.sql service0
 [service0@localhost service0]$ psql service0 < /backup/openacs/openacs_dev_before_upgrade_to_4.6.dmp
 [service0@localhost service0]$ svc -u /service/service0
 [service0@localhost service0]$ exit
@@ -175,8 +175,8 @@
 svc -d /service/service0
 dropdb service0
 createdb service0
-psql -f /web/service0/packages/acs-kernel/sql/postgresql/postgresql.sql service0
-psql service0 < /web/service0/database-backup/before_upgrade_to_4.6.dmp
+psql -f /var/lib/aolserver/service0/packages/acs-kernel/sql/postgresql/postgresql.sql service0
+psql service0 < /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp
 svc -u /service/service0
 exit
         
@@ -191,7 +191,7 @@
       supervise directory, which is
       unneccesary and has complicated permissions.  Make sure that you
       are using the cron job to back up the database to a file in
-      /web/service0/database-backup
+      /var/lib/aolserver/service0/database-backup
       so that the tar command will include the database.
       In the tar command,
       
@@ -221,21 +221,21 @@
         
         
           The last clause,
-          /web/service0/,
+          /var/lib/aolserver/service0/,
           specifies the starting point for backup.  Tar defaults to
           recursive backup.
         
       
       [root@yourserver root]# su - service0
-[service0@yourserver service0]$ tar -cpsj --exclude /web/service0/etc/daemontools/supervise --file /tmp/service0-backup.tar.bz2 /web/service0/ 
+[service0@yourserver service0]$ tar -cpsj --exclude /var/lib/aolserver/service0/etc/daemontools/supervise --file /tmp/service0-backup.tar.bz2 /var/lib/aolserver/service0/ 
 tar: Removing leading `/' from member names
 [service0@yourserver service0]$
     
 
   
     Automated Backup (OPTIONAL)
     Backup can encompass all files in
-    /web/service0.  For a development
+    /var/lib/aolserver/service0.  For a development
     server, putting the files in cvs, and backing up the database nightly, is sufficient.  (It's important then to back up the cvs repository!)
       
         Postgres automatic backup
@@ -254,9 +254,9 @@
         night, edit the crontab file for service0:
     [service0@yourserver service0]$ export EDITOR=emacs;crontab -e
     Add this line to the file.  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.
-    0 1 * * * /usr/local/pgsql/bin/pg_dump -f /web/service0/database-backup/service0_$(date +%Y-%m-%d).dmp service0
-    If you plan to back up the whole /web/service0 directory, then it would be redundant to keep a history of database backups.  In that case, set up the cron job to overwrite the previous backup each time:
-    0 1 * * * /usr/local/pgsql/bin/pg_dump -f /web/service0/database-backup/service0_nightly.dmp service0
+    0 1 * * * /usr/local/pgsql/bin/pg_dump -f /var/lib/aolserver/service0/database-backup/service0_`date +\%Y-\%m-\%d`.dmp service0
+    If you plan to back up the whole /var/lib/aolserver/service0 directory, then it would be redundant to keep a history of database backups.  In that case, set up the cron job to overwrite the previous backup each time:
+    0 1 * * * /usr/local/pgsql/bin/pg_dump -f /var/lib/aolserver/service0/database-backup/service0_nightly.dmp service0
       
     
     
@@ -265,7 +265,7 @@
       
         Delete the Service
       [root@yourserver root]# svc -d /service/service0
-[root@yourserver root]# mv /web/service0/ /web/service0.lost
+[root@yourserver root]# mv /var/lib/aolserver/service0/ /var/lib/aolserver/service0.lost
 [root@yourserver root]# rm /service/service0
 rm: remove symbolic link `/service/service0'? y
 [root@yourserver root]# ps -auxw | grep service0
@@ -302,17 +302,17 @@
 logout
 
 [root@yourserver root]# su - service0
-[service0@yourserver service0]$ cd /web
+[service0@yourserver service0]$ cd /var/lib/aolserver
 [service0@yourserver web]$ tar xjf /tmp/service0-backup.tar.bz2
 [service0@yourserver web]$ chmod -R 700 service0
 [service0@yourserver web]$ createdb service0
 CREATE DATABASE
-[service0@yourserver web]$ psql -f /web/service0/packages/acs-kernel/sql/postgresql/postgresql.sql service0
+[service0@yourserver web]$ psql -f /var/lib/aolserver/service0/packages/acs-kernel/sql/postgresql/postgresql.sql service0
 (many lines omitted)
-[service0@yourserver web]$ psql service0 < /web/service0/database-backup/database-backup.dmp
+[service0@yourserver web]$ psql service0 < /var/lib/aolserver/service0/database-backup/database-backup.dmp
 (many lines omitted)
 [service0@yourserver web]$ exit
-[root@yourserver root]# ln -s /web/service0/etc/daemontools /service/service0
+[root@yourserver root]# ln -s /var/lib/aolserver/service0/etc/daemontools /service/service0
 [root@yourserver root]# sleep 10
 [root@yourserver root]# svgroup web /service/service0
 [root@yourserver root]#
@@ -331,7 +331,7 @@
         
       (This has not yet been updated to fit with the Reference
       install.  To do so, edit the backup script to save the backup
-      file in /web/service0/database-backup).
+      file in /var/lib/aolserver/service0/database-backup).
       While you're working with Oracle, you should configure it to do
       automatic exports. An export is a separate backup copy of the
       database.  This copy includes all of the database's state at the
@@ -463,7 +463,7 @@
   
     Set up nightly Postgres exports
 
-    This is an alternate method to the crontab backup.
+    This is an alternate method to the crontabls - backup.
       Dowload this script
       to /tmp. At the top of the script
       are several variables that you'll need to customize:
@@ -510,7 +510,7 @@
     
 
     
-joeuser:~$ cp /tmp/acs-pgbackup-init.txt ~/web/birdnotes/tcl/acs-pgbackup-init.tcl
+joeuser:~$ cp /tmp/acs-pgbackup-init.txt ~/var/lib/aolserver/birdnotes/tcl/acs-pgbackup-init.tcl
 joeuser:~$ restart-aolserver birdnotes