Revision History

Document Revision # Action Taken, Notes When? By Whom?

0.4

Revision History

Document Revision # Action Taken, Notes When? By Whom?

0.4 Fixed some typos. 8/3/2002 Vinod Kurup

0.3

Added OpenACS information, updated tools, added Index: openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html,v diff -u -N -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html 28 Jun 2003 05:07:01 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html 20 Aug 2003 16:20:16 -0000 1.12 @@ -18,7 +18,7 @@ http://oradoc.photo.net/ora81/DOC/server.815/a67779/ch4e.htm#8953. Note that we shortened all of the constraint abbrevations to two characters to save room. -

Constraint type	Abbreviation
references (foreign key)	fk
unique	un
primary key	pk
check	ck
not null	nn

Format of constraint name

Constraint type	Abbreviation
references (foreign key)	fk
unique	un
primary key	pk
check	ck
not null	nn

Format of constraint name

In reality, this won't be possible because of the character limitation on Index: openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 20 Aug 2003 16:20:16 -0000 1.1 @@ -0,0 +1,380 @@ + +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 +accounts for people. So we want them to be able to create just one +account on a central server (e.g. LDAP or RADIUS), and when they +log on to OpenACS, an account will automatically be created for +them here.

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

Design Goals

Transparent: Users don't have to do anything special to + get an account on the local OpenACS system, if they already have an + account on the external authentication server.
Fall-back: Users who don't have an account on the + external authentication server are still allowed to create a local + account on OpenACS. This could be for external students who should + have access to .LRN, but not to the rest of the university's + resources.
Authentication Client Only: We want OpenACS to be able to + authenticate by asking some remote authority to verify the user's + username/password combination. The goal is explicitly not (at this + point) to have OpenACS act as an authentication server for other + systems, although this could be easily added later. The goal is + also not to devise an infrastructure for letting OpenACS access + resources in various other systems on the user's behalf, such as + IMAP, iCalendar, SMB file servers, etc., although this is + definitely an interesting use-case.
Easy configuration: We would like people to be able to + configure this without having to write code. In particular, we want + to build drivers that know how to talk with LDAP, RADIUS, PAM, + etc., and which won't have to be locally modified. Only + configuration and policies should change, code should + not.
Usability: The solution must be easy to use for end users + and administrators alike. There's frequently a positive feedback + effect between usability and security, because when authentication + schemes have poor usability, users will think up ways to circumvent + them.
Open and modular: The design should be on the one hand + open to add other authentification mechanisms when needed and on + the other hand very modular to enable a start with minimal + requirements (driver implementations) as soon as + possible.

The problem can be split into several logically separate +parts. Each has a section below.

Terminology

Authority: The name of an authority trusted to authenticate + users.
Authentication Driver: An implementation of the + authentication service contract, which talks to an authentication + of a certain type, e.g. PAM, RADIUS, LDAP, or Active + Directory.
Authentication API: The API through which login pages and + applications talk to the authentication service. There's one and + only one implementation of the authentication API, namly the one + included in OpenACS Core.
Authentication Driver API: The service contract which + authentication drivers implement.

Conceptual Pictures

Authentication:

Account Management (NO PICTURE YET)

Batch Synchronization (NO PICTURE YET)

Requirements

New API

Feature	Status	Description
EXT-AUTH-01	A	Extend Authentication/Acct Status API
EXT-AUTH-03	A	Account Creation API
EXT-AUTH-05	A	Password Management API
EXT-AUTH-30	A	Authority Management API

Login

Feature	Status	Description
EXT-AUTH-04	A	Rewrite login, register, and admin pages to use APIs
EXT-AUTH-38	A	ad_form complain feature
EXT-AUTH-19	A	Rewrite password recovery to use API
EXT-AUTH-21	A	Rewrite email verification with API
EXT-AUTH-28	A	Username 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 +password column is used, or it can be some external authority, +which will be communicated with using some protocol, as implemented +by an authentication driver.

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

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

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

+Username:  ________
+Password:  ________
+Authority: [URZ   ]
+            Athena
+            Local
+
+[Forgot my password]
+[New user registration]
+

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

Configuration

Feature	Status	Description
EXT-AUTH-07	A	Admin pages to control Ext-Auth parameters

The site-wide systems administrator can configure the +authentication process from a page linked under /acs-admin.

Authorities - ordered list of authorities defined
Account Registration Allowed: Yes/No. Account + registration can be disabled altogether.
Registration authority - the authority in which accounts should + be created, using the relevant driver, if account registration is + allowed.
Username is email? - instead of asking for username, + we'll ask for email. And we'll store the value in both columns, + username and email. This is a setting that spans all authorities, and + is primarily meant for backwards compatibility with the old OpenACS + login process.

The local authority driver is an encapsulation of current + functionality within an driver matching a service contract. The + other drivers call external functions. The possible functions + for each authority are split into several drivers for convenience. + One driver handles authentication, one account creation, and one + changing passwords.

Feature	Status	Description
EXT-AUTH-16	A	Create service contract for Authentication
EXT-AUTH-17	A	Create service contract for Acct. Creation
EXT-AUTH-29	A	Create service contract for Passwd Management

Feature	Status	Description
EXT-AUTH-18	A	Authority configuration data model

Each authority is defined like this:

Authority pretty-name, e.g. "URZ"
Authentication Driver, e.g. "RADIUS". In practice, this + would be a reference to a service contract + implementation.
Authentication Driver configuration settings, e.g. host + name, port, etc., as required by the particular driver. Note that + this is per authority, not per driver, i.e., you can have multiple + authorities with the same driver but different configuration + options.
AuthenticationAllowed - true/false, so you can disable + login through some authority without having to delete the authority, and + hence also all the users who belong to that authority.
ForgottenPasswordUrl - a URL to redirect to instead of + trying to use the authentication driver's password management + features.
ChangePasswordUrl - a URL to redirect to instead of + trying to use the authentication driver's password management + features.
Account Creation Driver, e.g. "RADIUS". In practice, this + would be a reference to a service contract implementation. The + reason we have separate drivers for authentication and account + creation is that organizations are likely to have a home-grown + account registration process.
Account Creation Driver configuration settings, e.g. host + name, port, etc., as required by the particular driver. Note that + this is per authority, not per driver, i.e., you can have multiple + authorities with the same driver but different configuration + options.
RegistrationUrl - instead of registering using OpenACS, + redirect to a certain URL site for account registration.
RegistrationAllowed - true/false, so you can disable + registration using this account.
Sort order: Preference order of + authorities.
HelpContactText: Text or HTML to be displayed + when user has trouble authenticating with the authority. + Should include contact information such as a phone number or email.

Each authority driver will have a set of configuration options +dependent on the driver, such as host, port, etc. We will need to +find a mechanism for the driver to tell us which configuration +options are available, a way to set these, and a way for the driver +to access these settings.

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

Synchronizing +and Linking Users

Feature	Status	Description
EXT-AUTH-28	A	Create service contract for Batch Sync.
EXT-AUTH-38	A	Batch User Synchronization API
EXT-AUTH-38	A	IMS Synchronization driver
EXT-AUTH-08	A	Automation of batch Synchronization
EXT-AUTH-15	B	On-demand syncronization

Regardless of the login method, the user needs to have a row +in the OpenACS users table. This can happen through a batch job, in +real-time, or both in combination. We use the IMS Enterprise 1.1 specification.

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

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

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

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

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

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

Feature	Status	Description
EXT-AUTH-31	A	Upgrade user data model for ext-auth

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

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

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

Account +Registration

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

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

Required Fields: A list of fields which are + required.
Optional Fields: A list of fields which are + optional.

The fields to choose from are these:

Username
First names
Last name
Email
URL
Password
Secret question
Secret answer

It should return the following:

Creation status (OK, Try-Again, Fail)
Creation message: What went wrong, or a welcome + message.
Account status: Is the account ready for use?
User information: first_names, last_name, email, url, + password, password_hash, secret_question, secret_answer. The driver + only needs to return the columns which were changed or added + through the registration process. Typically, only the "local" + driver will return password and secret question/answer.

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

By default, a local account creation implementation is +provided, which will create a new OpenACS user, and, in addition to +the default local account creation above, also store the password +in hashed form.

Password +Management

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

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

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

Login Pages Over +HTTPS

Feature	Status	Description
EXT-AUTH-20	A	Login over HTTPS

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

Email +Verification

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

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

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

Other Items

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

Recommended: +Untrusted Logins and Login Levels

Feature	Status	Description
EXT-AUTH-33	A	Untrusted Logins

I like the idea of having multiple login levels:

Not logged in
Untrusted login: We'll show you un-sensitive personal + content, but won't let you modify anything or see personal data. A + normal login becomes untrusted after a certain amount of time, and + the user will have to re-enter his/her password in order to gain + access to personal data. Untrusted login never expires, unless + explicitly done so through either changing password or clicking a + special "expire all logins" link.
Normal login: The user is logged, and has type his + password sufficiently recently that we trust the login. All normal + operations are allowed. Will degrade to untrusted login after a + specified amount of time.
Secure login: The user is logged in over a secure + connection (HTTPS), potentially even using a special secure + password. This would be for sensitive actions, such as credit card + transactions.

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

The other advantage is that we can still offer certain +functionality to you, even when your login is not trusted. For +example, we could let you browse publically available forums, and +only when you want to post do you need to log in. This makes it +even more feasible to have a more secure login expiration +setting.

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

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

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

Recommended: +Make Non-Persistent Login Work

Feature	Status	Description
EXT-AUTH-34	A	Expire Logins

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

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

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

Recommended: +Single-Sign-On

Feature	Status	Description
EXT-AUTH-23		Single sign-on

Instead of redirecting to the login page, auth::require_login +can redirect to an authentication server, which can redirect back +to a page that logs the user in. This should be very easy to +implement.

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

Recommended: +Expire All Logins

Feature	Status	Description
EXT-AUTH-22	B	rewrite cookie handling

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

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

The implementation is simply to autogenerate some secret +token which is stored in the users table, and is also stored in the +cookie somehow. Then, whenever we want to expire all logins, we'll +just regenerate a new secret token, and the other cookies will be +void. Of course, we don't want to incur a DB hit on every request, +so we'll need to cache the secret token, or only check it when +refreshing the session cookie, which, I believe, normally happens +every 10 minutes or so.

Recommended: +Email account owner on password change

Feature	Status	Description
EXT-AUTH-24	A	Email on password change

As an additional security measure, we should email the +account's email address whenever the password is changed, so that +he/she is at least alerted to the fact.

Optional: +Password policy

Feature	Status	Description
EXT-AUTH-25	A	Implement password policy

Again, to increase security, we should add password policies, +such as passwords needing to be changed after a certain number of +days, change on next login (after a new random password has been +generated), or requiring that the password satisfies certain +complexity rules, i.e. both upper and lowercase characters, +numbers, special chars, etc.

It would good to extend the current maximum password length +from 10 to at least 32 characters.

Optional: +Login Without Explicit Authority

Feature	Status	Description
EXT-AUTH-26	B	Login without explicit domain

In order to make it easier for people, we've been toying with +the idea of a functionality like this:

If the user enters "foobar@ix.urz.uni-heidelberg.de", it + is translated to mean username = "foobar", authority = + "ix.urz.uni-heidelberg.de".
If the user enters "foobar", it's recognized to not + include any authority, and the default authority of + "ix.urz.uni-heidelberg.de" is used.
If the user enters "foo@bar.com", it's recognized as not + belonging to any known authority, and as such, it's translated to mean + username = "foo@bar.com", authority = "local".

If this is deemed desirable, a way to implement this would be +through these settings:

Split: A regexp which will split the user's entry into + username and authority parts. For example "^([^@]+)(@[^@]+)?$". An + easier to use but less flexible method would be that you simply + specify a certain character to split by, such as "@" or "\". If the + regexp doesn't match, or in the latter case, if there's more than + one occurrence of the specified character sequence, the split will + fail, signaling that the user's entry was not valid.
Default authority: The default authority will be the first one + in the sort order.

The relevant code in user-login.tcl would look like +this:

+if { ![auth::split_username -username_var username -authority_var authority] } {
+    # bounce back to the form with a message saying that the login wasn't valid.
+    ad_script_abort
+}
+
+# username will now contain username
+# authority will now contain authority
+

Optional: Who's +Online

Feature	Status	Description
EXT-AUTH-27	B	Who's online list

While we're touching the session handling code, anyway, it +would be nice to add a feature to show who's currently online, a +nice real-time collaboration feature frequently requested by +members of the community. This is particularly interesting when +integrated with a chat or instant messaging service like +Jabber.

What I'm concretely suggesting is that we keep a record of +which authenticated users have requested pags on the site in the +last x minutes (typically about 5), and thus are considered to be +currently online. There's nothing more to it. This lets us display +a list of "active users" somewhere on the site, and make their name +a link to a real-time chat service like Jabber.

We've already made the changes necessary to +security-procs.tcl to do this on an earlier project, but haven't +quite finished the work and put it back into the tree.

Optional: +Subsite-level configuration

Feature	Status	Description
EXT-AUTH-28		implement subsite-level config

If we want to, we could let subsite administrators configure +the login process for that particular subsite. This would probably +only entail letting the subsite admin leave out certain authorities +defined site-wide, and change the sort order.

I think we should leave this out until we have a use case for +it, someone who'd need it.

Future: +Making the Authentication API itself a service contract

Feature	Status	Description
EXT-AUTH-32	A	Parameters for Service Contract Implementation
EXT-AUTH-35	A	Make the Authentication API a service contract

For completely free-form authentication logic and mechanisms, +something like Andrew Grumet's +Pluggable +Authentication for OACS Draft is interesting. He's +proposing a scheme where the entire user interaction is +encapsulated in, and left entirely to, a service contract. This +certainly opens up more advanced possibilities, such as perhaps +smart cards, personal certificates, etc.

I have chosen not to go this route, because I think that most +people are going to want to use a username/password-based scheme, +and having easy configuration through a web UI is more important +than total flexibility at this point.

Besides, we can always do this in the future, by letting the +public Authentication API (auth::require_login +and auth::authenticate) be implemented through a +service contract.

Future: +Authenticating against multiple servers simultaneously

Feature	Status	Description
EXT-AUTH-36	A	Authenticate against multiple servers

Both OKI and OpenACS supports a form of stacking, where you +can be logged into multiple authorities at the same time. This is +useful if, for example, you need to get login tokens such as +Kerberos tickets for access to shared resources.

I can see the value in this, but for simplicity's sake, I'm +in favor of keeping this use-case out of the loop until we have +someone with a real requirement who could help us guide +development.

For now, OpenACS is still more of an integrated suite, it +doesn't access many outside applications. I think it would be +excellent for OpenACS to do so, e.g. by using an IMAP server to +store emails, an iCal server to store calendar appointments, LDAP +for user/group data and access control lists, SMB for file storage, +etc. But at the moment, we don't have any users of such things that +are ready. We have some who are on the steps, but let's wait till +they're there.

Implement +Specific Drivers

Feature	Status	Description
EXT-AUTH-09	A	Create Auth. drivers for Local Authority
EXT-AUTH-10	A	Create Acct. Creation driver for Local Authority
EXT-AUTH-11	A	Create Auth. driver for PAM
EXT-AUTH-12	X	Create Acct. Creation driver for PAM - this + functionality is explicitly excluded from PAM
EXT-AUTH-13	A	Create Acct. Creation driver for LDAP
EXT-AUTH-14	A	Create Auth. driver for LDAP

We'll need drivers for:

Operating system (Linux/Solaris) PAM: Delegate to the + operating system, which can then talk to RADIUS, LDAP, whatever. + This is convenient because there'll be plenty of drivers for the OS + PAM level, so we don't have to write them all ourselves. The + downside is that we can't do things like account creation, password + management, real-time account synchronization, etc., not supported + by PAM (I'm not entirely sure what is and is not + supported).
RADIUS
LDAP

RADIUS

RADIUS is a simple username/password-type authentication +server.

It also supports sending a challenge to which the user must +respond with the proper answer (e.g. mother's maiden name, or could +be additional password), but we will not support this +feature.

A RADIUS client +implementation +in Python can be found in the +exUserFolder +module for Zope +(documentation).

Feedback

We'd really appreciate feedback on this proposal. Please +follow up at +this +openacs.org forums thread.

References

IMS Enterprise
Threads +and links collected by Carl Blesius.
Solaris/Linux +PAM specification
Draft +Proposal by Andrew Grumet.
Yale +CAS, a centrl authentication service a' la + Passport.

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
1	Updated work-in-progress for consortium-sponsored ext-auth work at Collaboraid.	20 Aug 2003	Joel Aufrecht

Prev	Home
Bootstrapping OpenACS	Up

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/filename.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/filename.html,v diff -u -N -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/filename.html 28 Jun 2003 05:07:01 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/filename.html 20 Aug 2003 16:20:16 -0000 1.12 @@ -115,7 +115,7 @@ within the OpenACS, this section's details are likely to shift from UI specifics to template interface specifics.

Configuration/Parameters

- Under OpenACS 4.7.0d, parameters are set at two levels: at the global level by + Under OpenACS 5.0.0d, parameters are set at two levels: at the global level by the OpenACS-admin, and at the subsite level by a sub-admin. In this section, list and discuss both levels of parameters.

Future Improvements/Areas of Likely Change

@@ -136,4 +136,4 @@

System creator
System owner
Documentation author

Revision History

The revision history table below is for this template - modify it as needed for your actual design document. -

Document Revision #	Action Taken, Notes	When?	By Whom?
0.3	Edited further, incorporated feedback from Michael Yoon	9/05/2000	Kai Wu
0.2	Edited	8/22/2000	Kai Wu
0.1	Creation	8/21/2000	Josh Finkler, Audrey McLoghlin

($Id$)

Prev	Home	Next
Using PSGML mode in Emacs	Up	System/Application Requirements Template

docs@openacs.org

View comments on this page at openacs.org +

Document Revision #	Action Taken, Notes	When?	By Whom?
0.3	Edited further, incorporated feedback from Michael Yoon	9/05/2000	Kai Wu
0.2	Edited	8/22/2000	Kai Wu
0.1	Creation	8/21/2000	Josh Finkler, Audrey McLoghlin

($Id$)

Prev	Home	Next
Using PSGML mode in Emacs	Up	System/Application Requirements Template

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/groups-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-design.html,v diff -u -N -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/groups-design.html 28 Jun 2003 05:07:01 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/groups-design.html 20 Aug 2003 16:20:16 -0000 1.11 @@ -301,4 +301,4 @@

Rafael H. Schloming

Documentation author -

Mark Thomas

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/22/2000	Rafael H. Schloming
0.2	Initial Revision	08/30/2000	Mark Thomas
0.3	Additional revisions; tried to clarify membership/compostion	09/08/2000	Mark Thomas

Prev	Home	Next
OpenACS 4 Groups Requirements	Up	OpenACS 4 Subsites Requirements

docs@openacs.org

View comments on this page at openacs.org +

Mark Thomas

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/22/2000	Rafael H. Schloming
0.2	Initial Revision	08/30/2000	Mark Thomas
0.3	Additional revisions; tried to clarify membership/compostion	09/08/2000	Mark Thomas

Prev	Home	Next
OpenACS 4 Groups Requirements	Up	OpenACS 4 Subsites Requirements

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/groups-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-requirements.html,v diff -u -N -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/groups-requirements.html 28 Jun 2003 05:07:01 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/groups-requirements.html 20 Aug 2003 16:20:16 -0000 1.11 @@ -222,4 +222,4 @@ where clause, whatever mechanism is used to check membership in SQL should be fairly small and simple.

Requirements: User Interface

The user interface is a set of HTML pages that are used to drive the underlying API. The user interface may provide the following functions:

200.0 Create a party
210.0 View the attributes of a party
220.0 Update the attributes of a party
240.0 Delete a party
250.0 Add a party to a group
260.0 Remove a party from a group
270.0 Perform the membership and composition checks -outlined in 130.x to 165.x

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/16/2000	Rafael Schloming
0.2	Initial revision	08/19/2000	Mark Thomas
0.3	Edited and reviewed, conforms to requirements template	08/23/2000	Kai Wu
0.4	Further revised, added UI requirements	08/24/2000	Mark Thomas
0.5	Final edits, pending freeze	08/24/2000	Kai Wu
0.6	More revisions, added composition requirements	08/30/2000	Mark Thomas
0.7	More revisions, added composition requirements	09/08/2000	Mark Thomas

Prev	Home	Next
OpenACS 4 Permissions Design	Up	OpenACS 4 Groups Design

docs@openacs.org

View comments on this page at openacs.org +outlined in 130.x to 165.x

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/16/2000	Rafael Schloming
0.2	Initial revision	08/19/2000	Mark Thomas
0.3	Edited and reviewed, conforms to requirements template	08/23/2000	Kai Wu
0.4	Further revised, added UI requirements	08/24/2000	Mark Thomas
0.5	Final edits, pending freeze	08/24/2000	Kai Wu
0.6	More revisions, added composition requirements	08/30/2000	Mark Thomas
0.7	More revisions, added composition requirements	09/08/2000	Mark Thomas

Prev	Home	Next
OpenACS 4 Permissions Design	Up	OpenACS 4 Groups Design

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-requirements.html,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/i18n-requirements.html 28 Feb 2003 05:36:04 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/i18n-requirements.html 20 Aug 2003 16:20:16 -0000 1.2 @@ -1,21 +1,21 @@ -OpenACS 4.6 Internationalization Requirements

Prev	Chapter 9. Kernel Documentation	Next

OpenACS 4.6 Internationalization Requirements

+OpenACS Internationalization Requirements

Prev	Chapter�13.�Kernel Documentation	Next

OpenACS Internationalization Requirements

by Henry Minsky, Yon Feldman, Lars Pind, Peter Marklund, Christian Hvid, and others.
- OpenACS docs are written by the named authors, but may be edited + OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Introduction

This document describes the requirements for functionality in the OpenACS platform to support globalization of the core and optional modules. The goal is to make it possible to support delivery of applications which work properly in multiple locales with the lowest development and maintenance cost. -

Definitions

internationalization (i18n): +

Definitions

internationalization (i18n): The provision within a computer program of the capability of making itself adaptable to the requirements of different native languages, local customs and coded character sets. @@ -30,23 +30,23 @@ A product development approach which ensures that software products are usable in the worldwide markets through a combination of internationalization and localization. -

Vision Statement

The Mozilla project suggests keeping two catchy phrases in +

Vision Statement

The Mozilla project suggests keeping two catchy phrases in mind when thinking about globalization:

One code base for the world
English is just another language

Building an application often involves making a number of assumptions on the part of the developers which depend on their own culture. These include constant strings in the user interface and system error messages, names of countries, cities, order of given and family names for people, syntax of numeric and date strings and -collation order of strings.

The ACS should be able to operate in languages and regions -beyond US English. The goal of ACS Globalization is to provide a +collation order of strings.

The OpenACS should be able to operate in languages and regions +beyond US English. The goal of OpenACS Globalization is to provide a clean and efficient way to factor out the locale dependent functionality from our applications, in order to be able to easily swap in alternate localizations.

This in turn will reduce redundant, costly, and error prone rework when targeting the toolkit or applications built with the -toolkit to another locale.

The cost of porting the ACS to another locale without some +toolkit to another locale.

The cost of porting the OpenACS to another locale without some kind of globalization support would be large and ongoing, since without a mechanism to incorporate the locale-specific changes cleanly back into the code base, it would require making a new fork -of the source code for each locale.

System/Application Overview

A globalized application will perform some or all of the +of the source code for each locale.

System/Application Overview

A globalized application will perform some or all of the following steps to handle a page request for a specific locale:

Decide what the target locale is for an incoming page request
Decide which character set encoding the output should be @@ -71,15 +71,15 @@ Java which we will want to move to. So the design to meet the requirements will tend to rely on these capabilities, or close approximations to them where possible, in order to make it easier -to maintain Tcl and Java ACS versions.

Use-cases and User-scenarios

Here are the cases that we need to be able to handle +to maintain Tcl and Java OpenACS versions.

Use-cases and User-scenarios

Here are the cases that we need to be able to handle efficiently:

A developer needs to author a web site/application in a language besides English, and possibly a character set besides -ISO-8859-1. This includes the operation of the ACS itself, i.e., +ISO-8859-1. This includes the operation of the OpenACS itself, i.e., navigation, admin pages for modules, error messages, as well as additional modules or content supplied by the web site developer.
What do they need to modify to make this work? Can their localization work be easily folded in to future releases of -ACS?
A developer needs to author a web site which operates in +OpenACS?
A developer needs to author a web site which operates in multiple languages simultaneously. For example, arsDigita.com with content and navigation in English, German, and Japanese.
The site would have an end-user visible UI to support these languages, and the content management system must allow articles to @@ -92,12 +92,12 @@ for other locales. This would include support for creating resources such as message catalogs, non-text assets such as graphics, and use of templates which help to separate application -logic from presentation.

Competitive +logic from presentation.

Competitive Analysis

Other application servers: ATG Dyanmo, Broadvision, Vignette, -... ? Anyone know how they deal with i18n ?

Related +... ? Anyone know how they deal with i18n ?

Requirements

Because the requirements for globalization affect many areas +Registry of Character Sets

Test plan

Competitive system(s)

Requirements

Because the requirements for globalization affect many areas of the system, we will break up the requirements into phases, with a base required set of features, and then stages of increasing -functionality.

Locales

10.0

A standard representation of locale will be used throughout +functionality.

Locales

10.0

A standard representation of locale will be used throughout the system. A locale refers to a language and territory, and is uniquely identified by a combination of ISO language and ISO -country abbreviations.

See +country abbreviations.
See Content Repository Requirement 100.20
10.10 Provide a consistent representation and API for creating and referencing a locale
10.20 There will be a Tcl library of locale-aware formatting and parsing functions for numbers, dates and times. Note that Java has builtin support for these already.
10.30 For each locale there will be -default date, number and currency formats.
Associating a Locale with a Request
20.0
The request processor must have a mechanism for associating a +default date, number and currency formats. Currency i18n is +NOT IMPLEMENTED for 5.0.0.
10.40Administrators can upgrade their +servers to use new locales via the APM. NOT IMPLEMENTED in +5.0.0; current workaround is to get an xml file and load it +manually.

Associating a Locale with a Request

20.0

The request processor must have a mechanism for associating a locale with each request. This locale is then used to select the appropriate template for a request, and will also be passed as the locale argument to the message catalog or locale-specific -formatting functions.

20.10 The locale for a request should be +formatting functions.
20.10 The locale for a request should be computed by the following method, in descending order of priority:
get locale associated with subsite or package id
get locale from user preference
get locale from site wide default
20.20 An API will be provided for getting the current request locale from the -ad_conn structure.
Resource Bundles / Content Repository
30.0
A mechanism must be provided for a developer to group a set +ad_conn structure.

Resource Bundles / Content Repository

30.0

A mechanism must be provided for a developer to group a set of arbitrary content resources together, keyed by a unique identifier and a locale.

For example, what approaches could be used to implement a localizable nav-bar mechanism for a site? A navigation bar might be @@ -140,9 +144,9 @@ functionality might include using templates, Java ResourceBundles, content-item containers in the Content Repository, or some convention assigning a common prefix to key strings in the message -catalog.

Message Catalog for String Translation

40.0

A message catalog facility will provide a database of +catalog.

Message Catalog for String Translation

40.0

A message catalog facility will provide a database of translations for constant strings for multilingual applications. It -must support the following:

40.10 Each message will referenced via +must support the following:
40.10 Each message will referenced via unique a key.
40.20 The key for a message will have some hierarchical structure to it, so that sets of messages can be grouped with respect to a module name or package path.
40.30 The API for lookup of a message @@ -165,11 +169,7 @@ is modified, the other translations of that string can be flagged as needing update.
40.90 The message lookup must be as efficient as possible so as not to slow down the delivery of -pages.
Design question: Is there any reason to implement -the message catalog on top of the content repository as the -underlying storage and retrieval service, with a layer of caching -for performance? Would we get a nice user interface and version -control almost for free?
Character Set Encoding
Character Sets
50.0 A locale will have a primary +pages.

Character Set Encoding

Character Sets

50.0 A locale will have a primary associated character set which is used to encode text in the language. When given a locale, we can query the system for the associated character set to use.

The assumption is that we are going to use Unicode in our @@ -180,19 +180,11 @@ write other character sets. In particular, conversions to and from Unicode will need to be explicitly performed at the following times:

Loading source files (.tcl or .adp) or content files from the -filesystem
Accepting form input data from users
Delivering text output to a browser
Composing an email message
Writing data to the filesystem

Design question: Do we want to mandate that all -template files be stored in UTF8? I don't think so, because -most people don't have Unicode editors, or don't want to be -bothered with an extra step to convert files to UTF8 and back when -editing them in their favorite editor.

Same question for script and template files, how do -we know what language and character set they are authored in? -Should we overload the filename suffix (e.g., -'.shiftjis.adp', -'.ja_JP.euc.adp')?

The simplest design is probably just to assign a -default mapping from each locale to character a set: e.g. ja_JP --> ShiftJIS, fr_FR -> ISO-8859-1. +++ (see new ACS/Java -notes) +++ -

Tcl Source File Character Set

There are two classes of Tcl files loaded by the system; +filesystem
Accepting form input data from users
Delivering text output to a browser
Composing an email message
Writing data to the filesystem

Acs-templating does the following.

When the acs-templating package opens an an ADP or TCL file, it assumes the file is iso-8859-1. If the output charset (OutputCharset) in the AOLserver config file is set, then acs-templating assumes it's that charset. +Writing Files
When the acs-templating package writes an an ADP or + TCL file, it assumes the file is iso-8859-1. If the output + charset (OutputCharset) in the AOLserver config file is set, + then acs-templating assumes it's that charset.

Tcl Source File Character Set

There are two classes of Tcl files loaded by the system; library files loaded at server startup, and page script files, which are run on each page request.
Should we require all Tcl files be stored as UTF8? That seems too much of a burden on developers.
50.10 Tcl library files can be authored @@ -201,60 +193,63 @@ filename.
50.20 Tcl page script files can be authored in any character set. The system must have a way to determine the character set before loading the files, probably from - the filename.

Submitted Form Data Character Set

50.30 Data which is submitted with a + the filename.

Submitted Form Data Character Set

50.30 Data which is submitted with a HTTP request using a GET or POST method may be in any character set. The system must be able to determine the encoding of the form - data and convert it to Unicode on demand.

50.35 The developer must be able to + data and convert it to Unicode on demand.

50.35 The developer must be able to override the default system choice of character set when parsing - and validating user form data.

50.30.10 Extra hair: In Japan and some + and validating user form data. INCOMPLETE - form + widgets in acs-templating/tcl/date-procs.tcl are not + internationalized. Also, acs-templating's UI needs to be + internationalized by replacing all user-visible strings with + message keys.

50.30.10In Japan and some other Asian languages where there are multiple character set encodings in common use, the server may need to attempt to do an auto-detection of the character set, because buggy browsers may - submit form data in an unexpected alternate encoding.

Output Character Set

50.40 The output character set for a + submit form data in an unexpected alternate encoding.

Output Character Set

50.40 The output character set for a page request will be determined by default by the locale associated with the request (see requirement 20.0).
50.50 It must be possible for a developer to manually override the output character set encoding for a request using an API function. -

ACS Kernel Issues

60.10 All ACS error messages must use +

ACS Kernel Issues

60.10 All OpenACS error messages must use the message catalog and the request locale to generate error -message for the appropriate locale.
60.20 Web server error messages such as +message for the appropriate locale.NOT IMPLEMENTED for 5.0.0.
60.20 Web server error messages such as 404, 500, etc must also be delivered in the appropriate locale.
60.30 Where files are written or read from disk, their filenames must use a character set and character -values which are safe for the underlying operating system.

Templates

70.0 For a given abstract URL, the +values which are safe for the underlying operating system.

Templates

70.0 For a given abstract URL, the designer may create multiple locale-specific template files may be created (one per locale or language)
70.10 For a given page request, the system must be able to select an approprate locale-specific template file to use. The request locale is computed as per (see -requirement 20.0).
Design note: this would probably be implemented by -suffixing the locale or a locale abbreviation to the template -filename, such as foo.ja.adp or foo.en_GB.adp.
70.20A template file may be created for +requirement 20.0).
70.20A template file may be created for a partial locale (language only, without a territory), and the request processor should be able to find the closest match for the current request locale.
70.30 A template file may be created in any character set. The system must have a way to know which character set a template file contains, so it can properly process -it.

Formatting +it.

Formatting Datasource Output in Templates

70.50 The properties of a datasource column may include a datatype so that the templating system can format the output for the current locale. The datatype is defined -by a standard ACS datatype plus a format token or format string, +by a standard OpenACS datatype plus a format token or format string, for example: a date column might be specified as 'current_date:date LONG,' or 'current_date:date -"YYYY-Mon-DD"'

Forms

70.60 The forms API must support +"YYYY-Mon-DD"'

Forms

70.60 The forms API must support construction of locale-specific HTML form widgets, such as date entry widgets, and form validation of user input data for -locale-specific data, such as dates or numbers.
70.70 For forms which allow users to +locale-specific data, such as dates or numbers. NOT +IMPLEMENTED in 5.0.0.
70.70 For forms which allow users to upload files, a standard method for a user to indicate the charset of a text file being uploaded must be provided.
Design note: this presumably applies to uploading -data to the content repository as well

Sorting and Searching

80.10 Support API for correct collation +data to the content repository as well

Sorting and Searching

80.10 Support API for correct collation (sorting order) on lists of strings in locale-dependent way.
80.20 For the Tcl API, we will say that locale-dependent sorting will use Oracle SQL operations (i.e., we won't provide a Tcl API for this). We require a Tcl API function to return the correct incantation of NLS_SORT to use for a given locale with ORDER BY clauses in queries.
80.40 The system must handle full-text -search in any supported language.

Time Zones

90.10 Provide API support for specifying +search in any supported language.

Time Zones

90.10 Provide API support for specifying a time zone
90.20 Provide an API for computing time and date operations which are aware of timezones. So for example a calendar module can properly synchronize items inserted into a @@ -265,20 +260,39 @@ zone preference should be attached via a session or else UTC should be used to display every date and time.
90.60 The default if we can't determine a time zone is to display all dates and times in some -universal time zone such as GMT.

Database

100.10 Since UTF8 strings can use up to +universal time zone such as GMT.

Database

100.10 Since UTF8 strings can use up to three (UCS2) or six (UCS4) bytes per character, make sure that column size declarations in the schema are large enough to accomodate required data (such as email addresses in -Japanese).

Email and +Japanese). Since 5.0.0, this is covered in the database +install instructions for both PostGreSQL and Oracle.

Email and Messaging

When sending an email message, just as when delivering the content in web page over an HTTP connection, it is necessary to be -able to specify what character set encoding to use.

110.10 The email message sending API +able to specify what character set encoding to use. +
110.10 The email message sending API will allow for a character set encoding to be specified.
110.20 The email accepting API will allow for character set to be parsed correctly (hopefully a well -formatted message will have a MIME character set content type header)
Implementation Notes
+formatted message will have a MIME character set content type header)

Mail is not internationalized. The following issues +must be addressed.

+ Six different functions currently call ns_sendmail. This + means that there are six different end points for sending + mail. This should be brought down to no more than two (one + for acs_mail and one for acs_mail_lite), and ideally just + one. Functions that currently call ns_sendmail directly + should instead call acs_mail_lite. +
+ Outgoing email functions (acs_mail and acs_mail_lite) must do + the following: 1) Determine the appropriate language or + languages to use for the message subject and message body. 2) + Encode the subject and body appropriately and set message + headers, in accordance with RFC 3282 + (http://www.ietf.org/rfc/rfc3282.txt) and other RFCs. +
Extreme Use case: Web site has a default language of Danish. A forum is set up for Swedes, so the forum has a package_id and a language setting of Swedish. A poster posts to the forum in Russian (is this possible?). A user is subscribed to the forum and has a language preference of Chinese. What should be in the message body and message subject? +INCOMPLETE - The mail functions in acs_mail and acs_mail_lite +are not internationalized.
Incoming mail should be localized.

Implementation Notes

Because globalization touches many different parts of the system, we want to reduce the implementation risk by breaking the implementation into phases. -

Revision History

Document Revision #

Action Taken, Notes

When?

By Whom?

0.4

converting from HTML to DocBook and importing the document to the OpenACS +

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
1	Updated with results of MIT-sponsored i18n work at Collaboraid.	14 Aug 2003	Joel Aufrecht
0.4	converting from HTML to DocBook and importing the document to the OpenACS kernel documents. This was done as a part of the internationalization of - OpenACS and .LRN for the Heidelberg University in Germany	12 September 2002	Peter Marklund
0.3	comments from Christian	1/14/2000	Henry Minsky
0.2	Minor typos fixed, clarifications to wording	11/14/2000	Henry Minsky
0.1	Creation	11/08/2000	Henry Minsky

Prev	Home	Next
OpenACS 4 Permissions Design	Up	OpenACS 4 Groups Requirements

rmello at fslc.usu.edu

vinod@kurup.com

View comments on this page at openacs.org + OpenACS and .LRN for the Heidelberg University in Germany

12 September 2002

Peter Marklund

0.3

comments from Christian

1/14/2000

Henry Minsky

0.2

Minor typos fixed, clarifications to wording

11/14/2000

Henry Minsky

0.1

Creation

11/08/2000

Henry Minsky

Prev	Home	Next
Database Access API	Up	Internationalization

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/i18n.html 28 Feb 2003 05:36:04 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/i18n.html 20 Aug 2003 16:20:16 -0000 1.3 @@ -1,84 +1,109 @@ -Internationalization

Prev	Chapter 6. OpenACS Developer's Guide	Next

Internationalization

+Internationalization

Prev	Chapter�13.�Kernel Documentation	Next

Internationalization

By Peter Marklund and Lars Pind

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

Introduction

- This document describes how to develop internationalized OpenACS packages. +

Introduction

+ This document describes how to develop internationalized OpenACS + packages, including writing new packages with + internationalization and converting old packages. Text that + users might see is "localizable text"; replacing monolingual text + and single-locale date/time/money functions with generic + functions is "internationalization"; translating first + generation text into a specific language is "localization." At + a minimum, all packages should be internationalized. If you do + not also localize your package for different locales, volunteers + may use a public "localization server" to submit suggested text. + Otherwise, your package will not be usable for all locales.

- At this point, we've only covered things that involve the - message catalog: Dynamically picking a chunk of text to spit out - based on the locale. + The main difference between monolingual and internationalized + packages is that all user-visible text in an internationalized + package are coded as "message keys." The message keys + correspond to a message catalog, which contains versions of the + text for each available language. Both script files + (ADP/TCL) and APM parameters are affected.

- Each section below consists on one part about how to write - new internationalized packages, and which explains the details - of how it works, and then another part that talks about the - process for internationalizing existing packages. -

Using the Message Catalog

- The following section will tell you how to deal with localizable - text in ADP files, in TCL files, and in APM Parameters. -

Template Files (ADP Files)

+ Other differences include: all dates read or written to the + database must use internationalized functions. All displayed + dates must use internationalized functions. All displayed + numbers must use internationalized functions. +

Using the Message Catalog

+ Localizable text must be handled in ADP files, in TCL files, and + in APM Parameters. OpenACS provides two approaches, message + keys and localized ADP files. For ADP pages which are mostly + code, replacing the message text with message key placeholders + is simpler. This approach also allows new translation in the + database, without affecting the file system. For ADP pages + 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)

Internationalizing templates is about replacing human readable - text in a certain language with intenral message keys, which - can then be dynamically replaced with real human language in the desired - locale. + text in a certain language with internal message keys, which + can then be dynamically replaced with real human language in + the desired locale. Message keys themselves should be in + ASCII English, as should all code. Three different syntaxes + are possible for message keys.

- There are 3 syntaxes to choose from: The short, the verbose, - and the temporary. Each offer different advantages, but - generally, what you want to do is use the short notation for - new packages and use the temporary notation for - internationalizing old packages, then have the APM translate - those into the short notation. -

- The short: - #message_key# + "Short" syntax is the recommended syntax and should be used + for new development. When internationalizing an existing + package, you can use the "temporary" syntax, which the APM can + use to auto-generate missing keys and automatically translate + to the short syntax. The "verbose" syntax is useful while + developing, because it allows default text so that the page is + usable before you have done + localization.
- + The short: + #package_key.message_key#
  The advantage of the short syntax is that it's short. It's - as simple as inserting the value of a variable. + as simple as inserting the value of a variable. Example: + #forum.title#
- - The verbose: <trn - key="message_key" + The verbose: <trn + key="package_key.message_key" locale="locale">default - text</trn> + text</trn>
  The verbose syntax allows you to specify a default text in a certain language. This syntax is not recommended anymore, but it can be convenient for development, because it still works even if you haven't created the message in the message catalog yet, because what it'll do is create the message key with the default text from the tag - as the localized message. + as the localized message. Example: <trn + key="forum.title" locale="en_US">Title</trn>
- - The temporary: - <#message_key original�text#> + The temporary: + <#message_key original�text#>
  This syntax has been designed to make it easy to internationalize existing pages. This is not a syntax that stays in the page. As you'll see later, it'll be replaced with the short syntax by a special feature of the APM. You may leave out the message_key by writing an underscore (_) character instead, in which case a message key will be - auto-generated by the APM. + auto-generated by the APM. Example: <_ Title>
We recommend the short notation for new package development. -

APM Parameters

Some parameters contain text that need to be localized. In this case, instead of storing the real text in the parameter, you should use message keys using the short notation above, - i.e. #message-key#. + i.e. #package_key.message_key#.

In order to avoid clashes with other uses of the hash character, you need to tell the APM that the parameter value needs to be localized when retrieving it. You do that by saying: - parameter::get -localize. + parameter::get -localize.

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

Table 6.1.

Parameter Name	Parameter 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 Name	Parameter 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 6.2.

Command used to retrieve Value	Retrieved Value
parameter::get -localize -parameter class_instances_pages_csv	Kurs Startseite,Simple 2-Column;Kalender,Simple 1-Column;Dateien,Simple 1-Column
parameter::get -localize -parameter departments_pretty_name	Abteilung
parameter::get -parameter departments_pretty_name	#departments_pretty_name#

Table�13.2.�

Command used to retrieve Value	Retrieved Value
parameter::get -localize -parameter class_instances_pages_csv	Kurs Startseite,Simple 2-Column;Kalender,Simple 1-Column;Dateien,Simple 1-Column
parameter::get -localize -parameter departments_pretty_name	Abteilung
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. @@ -87,30 +112,29 @@ the current request, i.e. lang::conn::locale or ad_conn locale.

- You're responsible for creating the keys in the message - catalog yourself. -

Dates, Times, and Numbers

- Let's deal with dates and times first. The way it works is as follows: + Developers are responsible for creating the keys in the message + catalog, which is available at /acs-lang/admin/ +

Dates, Times, and Numbers

+ Dates and times must be converted when stored in the database, + when retrieved from the database, and when displayed. All dates + are stored in the database in the server's timezone, which is an + APM Parameter set at + /acs-lang/admin/set-system-timezone + and readable at + lang::system::timezone.. When + retrieved from the database and displayed, dates and times must + be localized to the user's locale.

Get the date in ANSI format from the database (YYYY-MM-DD - HH24:MI:SS, the time portion is optional). Name the column - in the SQL statement something that ends in - "_ansi", such as - "posting_date_ansi". Example: - to_char(posting_date, 'YYYY-MM-DD - HH24:MI:SS') as posting_date_ansi -
- Use the Tcl command "lc_time_fmt" to format the - date in pretty format. There are a number of standard, - localizable formats to choose from (see below). Example: - set posting_date_pretty [lc_time_fmt - $posting_date_ansi "%q"] -
- Use the "*_pretty"-version in your ADP page. -

- Here's the list of standard date and time formats to choose - from: -

+ HH24:MI:SS; the time portion is optional). By convention, + we identify dates in ansi format by ending the column name + with _ansi. + Example:
```
select to_char(posting_date, 'YYYY-MM-DD HH24:MI:SS') as posting_date_ansi
+  from table
+
```
+ Use the Tcl command lc_time_fmt to format the + date in "pretty" format. Several standard formats localize automatically: +
- %c: Long date and time (Mon November 18, 2002 12:00 AM)
- %x: Short date (11/18/02) @@ -121,64 +145,106 @@
- %Q: Long date with weekday (Monday November 18, 2002)
- If the abbreviations seem a bit strange, it's because they - are. Most of them are standardized (see man - strftime for example). %q and %Q are our - proprietary additions, and 'q' was just about the only letter - left in the alphabet. -
- The command 'lc_fmt_time' allows you to pass in a specific date - and time format as well, but please don't, because the whole - point is to make it possible for administrators to change date - and time formats site-wide based on locales. -
- Numbers are very easy to format. Just say - lc_numeric $value, and it'll - format the number using the appropriate decimal point and - thousand separator for the locale. -

Internationalizing Existing Packages

Page Files (ADP and Tcl Files)

- We've created a couple of tools especially for - internationalizing the pages of existing packages. The tools can - be accessed from the "Manage Internationalization" - linked from the package manager page for a package. -

- The process consists of four steps: -

- Replace text with tags: - This is an automated process, which will try to - automatically locate chunks of translatable text, - auto-generate a reasonable message key, and surround the - text with the temporary <#...#> notation mentioned - above. -
- Manually verify each ADP - file. If necessary, you can add additional + The "q" format strings are OpenACS additions; the rest follow unix standards (see man + strftime). +
```
set posting_date_pretty [lc_time_fmt $posting_date_ansi "%q"]
```
+ 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 + internationalization. From + /acs-admin/apm/, select a + package and then click on + Internationalization, then + Convert ADP, Tcl, and SQL files to using the + message catalog..

+ Replace text with tags: + Choose Find human language text and replace with <# ... #> tags. This automated process + automatically locates chunks of translatable text, + generates a reasonable message key, and replaces the text + with a "temporary" tag as described above. +
Any pieces of text found but not extractable -- for + example, pieces of text with embedded adp variables + (i.e. @var_name@) -- will be listed on the result + page. Make sure to take note of these texts and translate + them manually. Suppose for example that our script tells you + that it left the text "Manage forum @forum_name@" + untouched. What you should do then is to edit the + corresponding adp file and manually replace that text with + something like "<#manage_forum Manage forum @forum_name@#>" + (to save you from too much typing you may use the shorthand + <#_ Manage forum @forum_name@#>; an underscore key will + result in the script auto-generating a key for you based on + the text). After you have made all such manual edits you can + simply run the second action labeled "Replace tags with keys + and insert into catalog". +
Note: running this action will not find translatable text within HTML or adp tags on adp pages (i.e. text in alt tags of images), nor will it find translatable text in tcl files. Such texts will have to be found manually. If those texts are in adp files they are best replaced with the <#message_key text#> tags that can be extracted by the action described below. Here are some commands that we used on Linux to look for texts in adp pages not found by the script:
```
+# List image tags with alt attributes, look for alt attributes with literal text
+find -iname '*.adp'|xargs egrep -i '<img.*alt='
+# List submit buttons, look for text in the value attribute 
+find -iname '*.adp'|xargs egrep -i '<input[^>]*type="?submit'
+
```
+ When you run this step, any modified files are backed up in + a file with a ".orig" suffix. Those files are + never overwritten, though, so the .orig file will always be + the original page file, not the second-to-last file. Running + this action multiple times is harmless. +
+ Manually verify each ADP + file. If necessary, you can add additional <#...#> tags, or you can move or remove the ones set by the automated step.
- Manually mark up Tcl - files, marking up translatable text with the + Manually mark up Tcl + files, marking up translatable text with the <#...#> notation. -
- Replace tags with keys: +
Ttranslatable texts are often found in page titles, context bars, and form labels and options. Many times the texts are enclosed in double quotes. Use the following grep commands on Linux to highlight translatable text in tcl files for us:
```
# Find text in double quotes
+find -iname '*.tcl'|xargs egrep -i '"[a-z]'
+# Find untranslated text in form labels, options and values
+find -iname '*.tcl'|xargs egrep -i '\-(options|label|value)'|egrep -v '<#'|egrep -v '\-(value|label|options)[[:space:]]+\$[a-zA-Z_]+[[:space:]]*\\?[[:space:]]*$'
+# Find text in page titles and context bars
+find -iname '*.tcl'|xargs egrep -i 'set (title|page_title|context_bar) '|egrep -v '<#'
+# Find text in error messages
+find -iname '*.tcl'|xargs egrep -i '(ad_complain|ad_return_error)'|egrep -v '<#'
```
You may mark up translatable text in tcl library files and tcl pages with temporary tags (on the <#key text#> syntax mentioned previously). If you have a sentence or paragraph of text with variables and or procedure calls in it you should in most cases try to turn the whole text into one message in the catalog. In those cases, follow these steps:
1. For each message call in the text, decide on a variable + name and replace the procedure call with a variable + lookup on the syntax %var_name%. Remember to initialize + a tcl variable with the same name on some line above the + text.
2. If the text is in a tcl file you must replace + variable lookups (occurences of $var_name or + ${var_name}) with %var_name%
3. You are now ready to follow the normal procedure + and mark up the text using a tempoarary message tag (<#_ + text_with_percentage_vars#>) and run the action replace + tags with keys in the APM.
The variable values in the message are usually fetched with upvar, here is an example from dotlrn:
```
ad_return_complaint 1 "Error: A [parameter::get -parameter classes_pretty_name] 
+             must have no[parameter::get -parameter class_instances_pretty_plural] to be deleted"
+
```
was replaced by:
```
set subject [parameter::get -localize -parameter classes_pretty_name] 
+set class_instances [parameter::get -localize -parameter class_instances_pretty_plural]
+ad_return_complaint 1 [_ dotlrn.class_may_not_be_deleted]
+
+
```
This kind of interpolation also works in adp files where adp variable values will be inserted into the message.
Alternatively, you may pass in an array list of the variable values to be interpolated into the message so that our example becomes:
```
set msg_subst_list [list subject [parameter::get -localize -parameter classes_pretty_name] 
+                         class_instances [parameter::get -localize -parameter class_instances_pretty_plural]]
+
+ad_return_complaint 1 [_ dotlrn.class_may_not_be_deleted $msg_subst_list]
+
```
When we were done going through the tcl files we ran the following commands to check for mistakes: +
```
# Message tags should usually not be in curly braces since then the message lookup may not be
+# executed then (you can usually replace curly braces with the list command). Find message tags 
+# in curly braces (should return nothing, or possibly a few lines for inspection)
+find -iname '*.tcl'|xargs egrep -i '\{.*<#'
+# Check if you've forgotten space between default key and text in message tags (should return nothing)
+find -iname '*.tcl'|xargs egrep -i '<#_[^ ]'
+# Review the list of tcl files with no message lookups
+for tcl_file in $(find -iname '*.tcl'); do egrep -L '(<#|\[_)' $tcl_file; done
+
```
When you feel ready you may run the action "Replace tags with keys and insert into catalog" on the tcl files that you've edited to replace the temporary tags with calls to the message lookup procedure.
The acs-lang/bin/check-catalog.sh script checks that the set of keys used in message lookups in tcl, adp, and info files and the set of keys in the catalog file are identical. The scripts below assume that message lookups in adp and info files are on the format #package_key.message_key#, and that message lookups in tcl files are always done with the underscore procedure. The script assumes that you have perl installed and in your path. Run the script like this:
```
acs-lang/bin/check-catalog.sh package_key
```
where package_key is the key of the package that you want to test. If you don't provide the package_key argument then all packages with catalog files will be checked. The script will run its checks on en_US xml catalog files.
+ Replace tags with keys: This is an automated process, which will replace the temporary <#...#> notation in both ADP and Tcl files 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. -

Replace Text With Tags Step

- When you run this step, any modified files are backed up in - a file with a ".orig" suffix. Those files are - never overwritten, though, so the .orig file will always be - the original page file, not the second-to-last file. Running - this action multiple times is harmless. -

- The system will auto-generate suggested message keys. -

- ... (WRITE MORE HERE!) -

Replace Tags With Keys Step

- -

- Next step is to internationalize parameters that contain - localizable text. See the section Multilingual APM Parameters. -

Prev	Home	Next
Contributions	Up	Chapter 7. Other Developer Resources

rmello at fslc.usu.edu

vinod@kurup.com

View comments on this page at openacs.org +

Internationalize Package Parameters with visible messages

+ See Multilingual APM Parameters +

Internationalize Date and Time queries

Find datetime in .xql files. Use command line tools to find suspect SQL code:
```
grep -r "to_char.*H" *
+grep -r "to_date.*H" *
+
```
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
```
In TCL files where the date fields are used, convert the datetime from local server timezone, which is how it's stored in the database, to the user's timezone for display. Do this with the localizing function lc_time_system_to_conn:
```
+set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]
```
When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with lc_time_conn_to_system. +
When a datetime field will be displayed, format it using the localizing function lc_time_fmt. lc_time_fmt takes two parameters, datetime and format code. Several format codes are usable for localization; they are placeholders that format dates with the appropriate codes for the user's locale. These codes are: %x, %X, %q, %Q, and %c.
```
set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]
```

Design Notes

User locale is a property of ad_conn, ad_conn locale. The request processor sets this by calling lang::conn::locale, which looks for the following in order of precedence:

Use user preference for this package (stored in ad_locale_user_prefs)
Use system preference for the package (stored in apm_packages)
Use user's general preference (stored in user_preferences)
Use Browser header (Accept-Language HTTP header)
Use system locale (an APM parameter for acs_lang)
default to en_US

For ADP pages, message key lookup occurs in the templating engine. For TCL pages, message key lookup happens with the _ function. In both cases, if the requested locale is not found but a locale which is the default for the language which matches your locale's language is +found, then that locale is offered instead.

Prev	Home	Next
OpenACS Internationalization Requirements	Up	OpenACS 4 Security Requirements

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/index.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/index.html,v diff -u -N -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/index.html 28 Jun 2003 05:07:01 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/index.html 20 Aug 2003 16:20:16 -0000 1.11 @@ -1,2 +1,2 @@ -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 4.7.0d
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.
Upgrading OpenACS 4.5 to 4.6

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 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 4.7.0d Packages
OpenACS Data Models and the Object System
The Request Processor
The OpenACS Database Access API
Using Templates in OpenACS 4.7.0d
Groups, Context, Permissions
Writing OpenACS 4.7.0d Application Pages
Parties in OpenACS 4.7.0d
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

C. Using CVS with an OpenACS Site

Add the Service to CVS - OPTIONAL

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 4.7.0d Package Manager Requirements
OpenACS 4.7.0d Package Manager Design
Database Access API
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

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.

		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.0d
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 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.0d Packages
OpenACS Data Models and the Object System
The Request Processor
The OpenACS Database Access API
Using Templates in OpenACS 5.0.0d
Groups, Context, Permissions
Writing OpenACS 5.0.0d Application Pages
Parties in OpenACS 5.0.0d
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

C. Using CVS with an OpenACS Site

Add the Service to CVS - OPTIONAL

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.0d Package Manager Requirements
OpenACS 5.0.0d 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/individual-programs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/individual-programs.html,v diff -u -N -r1.3 -r1.4 --- openacs-4/packages/acs-core-docs/www/individual-programs.html 28 Jun 2003 05:07:01 -0000 1.3 +++ openacs-4/packages/acs-core-docs/www/individual-programs.html 20 Aug 2003 16:20:16 -0000 1.4 @@ -1,5 +1,5 @@ -Individual Programs

Prev	Chapter�3.�Prerequisite Software	Next

Individual Programs

OpenACS 4.7.0d.�The OpenACS tarball comprises the core packages and +Individual Programs
Prev Chapter�3.�Prerequisite Software Next
Individual Programs
- OpenACS 5.0.0d.�The OpenACS tarball comprises the core packages and many useful additional packages. This includes a full set of documentation. The tarball works with both PostGreSQL and Oracle.
- Operating System.�OpenACS is designed for a Unix-like system. It is @@ -31,7 +31,7 @@ distributions.
- TCL 8.3 development headers and libraries, OPTIONAL.� The site-wide-search service, OpenFTS, requires these to compile. (Debian users: apt-get install tcl8.3-dev). You need this - to install OpenFTS.
tDOM, REQUIRED.�OpenACS 4.7.0d stores + to install OpenFTS.

tDOM, REQUIRED.�OpenACS 5.0.0d stores queries in XML files, so we use an AOLserver module called tDOM to parse these files. (This replaces libxml2, which was used prior to 4.6.4.) tDOM is available from http://tdom.org).

Web Server.�The web server handles incoming HTTP requests, provides @@ -41,7 +41,7 @@ running Apache with mod_nsd - see this post.

AOLserver 3.3oacs1, REQUIRED.�Mat Kovach's source distribution of AOLserver, including all of the patches listed below.

Mat Kovach is graciously maintaining an AOLserver distribution that - includes all the patches and modules needed to run OpenACS 4.7.0d. These + includes all the patches and modules needed to run OpenACS 5.0.0d. These instructions will describe how to install using his source distribution. He also has binaries for SuSE 7.3 and OpenBSD 2.8 (and perhaps more to come), currently located at uptime.openacs.org. Index: openacs-4/packages/acs-core-docs/www/install-cvs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-cvs.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-cvs.html 28 Jun 2003 05:07:01 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-cvs.html 20 Aug 2003 16:20:16 -0000 1.3 @@ -1,5 +1,5 @@ -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 -N -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/install-daemontools.html	28 Jun 2003 05:07:01 -0000	1.2
+++ openacs-4/packages/acs-core-docs/www/install-daemontools.html	20 Aug 2003 16:20:16 -0000	1.3
@@ -4,7 +4,7 @@
       installed in /package.  These commands install daemontools and
       svgroup.  svgroup is a script for granting permissions, to allow
       users other than root to use daemontools for specific
-      services.
Install Daemontools
Red Hat
Make sure you have the source tarball in
+      services.
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 
@@ -31,7 +31,7 @@
 root     13294  0.0  0.1  1352  272 ?        S    09:51   0:00 svscan /service
 root     13295  0.0  0.0  1304  208 ?        S    09:51   0:00 readproctitle service errors: .......................................
 [root@yourserver root]#

Install a script to grant non-root users permission to - control daemontools services.

[root@yourserver root]# cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup + control daemontools services.

[root@yourserver root]# cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup
 [root@yourserver root]# chmod 755 /usr/local/bin/svgroup
-cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup 
+cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup 
 chmod 755 /usr/local/bin/svgroup

Prev	Home	Next
Add PSGML commands to emacs init file (OPTIONAL)	Up	Install qmail (OPTIONAL)

docs@openacs.org

View comments on this page at openacs.org 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 -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-full-text-search.html 28 Jun 2003 05:07:01 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-full-text-search.html 20 Aug 2003 16:20:16 -0000 1.3 @@ -1,5 +1,5 @@ -

Prev	Appendix�B.�Install additional supporting software	Next

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 +

Prev	Appendix�B.�Install additional supporting software	Next

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.

Install Tsearch. This is a PostGreSQL module that OpenFTS requires.

[root@yourserver root]# su - postgres
@@ -75,7 +75,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
@@ -90,7 +90,7 @@
 [service0@yourserver service0]$
 /usr/local/pgsql/bin/psql service0 -f /usr/local/src/postgresql-7.2.4/contrib/tsearch/tsearch.sql
 /usr/local/pgsql/bin/psql service0 -f /usr/local/src/postgresql-7.2.4/contrib/pgsql_contrib_openfts/openfts.sql

Enable OpenFTS in config.tcl

If you have installed OpenFTS, you can enable it for this service. Uncomment this line from config.tcl. (To uncomment a line in a tcl file, remove the # at the beginning of the line.)

#ns_param   nsfts           ${bindir}/nsfts.so

Install Full Text Search Engine

Click Package Manager on the right side of the default home page. If prompted, log in with the account and password you entered during install.
Click on the Install -packages link.
On the next screen, after it loads, click on Uncheck all boxes, then click the second checkbox next to OpenFTS Driver 4.2. This will automatically check the first box. Then click Next.
Click Install Packages

Restart the service.

[service0@yourserver service0]$ svc -t /service/service0
+packages link.

On the next screen, after it loads, click on Uncheck all boxes, then click the checkbox next to OpenFTS Driver 4.2. Then click Next.
Click Install Packages

Restart the service.

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

Wait a minute, then browse back to the home page.
Click on Site Map on the top right side of the screen.
Mount the OpenFTS Full Text Search Engine in the site map.
1. Click the new sub folder link on the "/" line, the first line under Main Site:/.
2. Type openfts and click New.
3. On the new openfts line, click the mount link.
4. Click OpenFTS Driver.
5. On the openfts line, click set parameters.
6. Change openfts_tcl_src_path to /usr/local/src/Search-OpenFTS-tcl-0.3.2/ and click Set Parameters Index: openacs-4/packages/acs-core-docs/www/install-nsopenssl.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-nsopenssl.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 28 Jun 2003 05:07:01 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 20 Aug 2003 16:20:16 -0000 1.3 @@ -4,7 +4,7 @@ along with a tcl helper script to handle https connections. You will also need ssl certificates. Because those should be different for each server service, you won't need those instructions until - later. You will need the unpacked Aolserver tarball in + later. You will need the unpacked Aolserver tarball in /usr/local/src/aolserver and the nsopenssl tarball in /tmp.
  Red Hat 9 note: see this Index: openacs-4/packages/acs-core-docs/www/install-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-overview.html,v diff -u -N -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/install-overview.html 28 Jun 2003 05:07:01 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/install-overview.html 20 Aug 2003 16:20:16 -0000 1.11 @@ -6,10 +6,10 @@
Purpose of this document
This document will describe how to install, configure, and - maintain an installation of OpenACS 4.7.0d on a Unix-like + maintain an installation of OpenACS 5.0.0d on a Unix-like system, including all supporting software. All examples - in this chapter are part of the OpenACS 4.7.0d-P or - OpenACS 4.7.0d-O Reference Platform, which use Red + in this chapter are part of the OpenACS 5.0.0d-P or + OpenACS 5.0.0d-O Reference Platform, which use Red Hat 8.0. Differences between the Reference Platform and common alternate platforms (Red Hat 9, Debian) are noted where known.
Requirements
@@ -45,7 +45,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
- This is text you will see on + PostgreSQL)
- Install a webserver (AOLServer)
- Copy the OpenACS files into place and start the OpenACS installer, which will configure a database instance.

How to use this guide

This is text you will see on screen, such as a Button or link in a radio button list or menu.
This is text that you will type.

This is text from a program or file which you may need to examine or edit:

if {$database == "oracle"} {
@@ -108,7 +108,7 @@
       better way. Well, not quite. Jonathan Marsden has created RPMs (at
       http://www.xc.org)
       for OpenACS 4.5 but there are not yet any for version
-      4.7.0d. There has been talk about automating the install process,
+      5.0.0d. There has been talk about automating the install process,
       but that hasn't happened yet. Stay tuned!

Where did this document come from?

Index: openacs-4/packages/acs-core-docs/www/install-qmail.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-qmail.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-qmail.html 28 Jun 2003 05:07:01 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-qmail.html 20 Aug 2003 16:20:16 -0000 1.3 @@ -22,7 +22,7 @@ tcpserver: usage: tcpserver [ -1UXpPhHrRoOdDqQv ] [ -c limit ] [ -x rules.cdb ] [ -B banner ] [ -g gid ] [ -u uid ] [ -b backlog ] [ -l localname ] [ -t timeout ] host port program [root@yourserver ucspi-tcp-0.88]# -

(I'm not sure if this next step is 100% necessary, but when I skip it I get problems. If you get the error 553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1) then you need to do this.) AOLServer sends outgoing mail via the ns_sendmail command, which pipes a command to the sendmail executable. Or, in our @@ -33,10 +33,10 @@ Unless this mail is addressed to the same machine, qmail thinks that it's an attempt to relay mail, and rejects it. So these two commands set up an exception so that any mail sent from 127.0.0.1 is allowed to -send outgoing mail.

[root@yourserver ucspi-tcp-0.88]# cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp +send outgoing mail.

[root@yourserver ucspi-tcp-0.88]# cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp
 [root@yourserver ucspi-tcp-0.88]# tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp
-cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp 
-tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp

Install Qmail.�

Download qmail, +

cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp 
+tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp

Install Qmail.�

Download qmail, set up the standard supporting users and build the binaries:

Red Hat 9.0: Put

#include <errno.h>

as the first line of @@ -75,7 +75,7 @@ useradd -g qmail -d /var/qmail qmailr useradd -g qmail -d /var/qmail qmails cd qmail-1.03 -make setup check

Replace sendmail with qmail's wrapper.

[root@yourserver qmail-1.03]# rm -f /usr/bin/sendmail /usr/sbin/sendmail
+make setup check

Replace sendmail with qmail's wrapper.

[root@yourserver qmail-1.03]# rm -f /usr/bin/sendmail /usr/sbin/sendmail
 [root@yourserver qmail-1.03]# ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail
 [root@yourserver qmail-1.03]#
 rm -f /usr/bin/sendmail /usr/sbin/sendmail
@@ -97,13 +97,13 @@
 cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root 
 chmod 644 ~alias/.qmail* 
 /var/qmail/bin/maildirmake ~alias/Maildir/ 
-chown -R alias.nofiles /var/qmail/alias/Maildir
Configure qmail to use the Maildir delivery format
+chown -R alias.nofiles /var/qmail/alias/Maildir

Configure qmail to use the Maildir delivery format (instead of mbox), and install a version of the qmail startup script modified to use Maildir.

[root@yourserver alias]# echo "./Maildir" > /var/qmail/bin/.qmail
-[root@yourserver alias]# cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc
+[root@yourserver alias]# cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc
 [root@yourserver alias]# chmod 755 /var/qmail/rc
 [root@yourserver alias]# 
 echo "./Maildir" > /var/qmail/bin/.qmail 
-cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc 
+cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc 
 chmod 755 /var/qmail/rc

Set up the skeleton directory so that new users will be configured for qmail.

[root@yourserver root]# /var/qmail/bin/maildirmake /etc/skel/Maildir
@@ -115,13 +115,13 @@
 [root@yourserver root]# mkdir -p /var/qmail/supervise/qmail-smtpd/log
 [root@yourserver root]# mkdir /var/log/qmail
 [root@yourserver root]# chown qmaill /var/log/qmail
-[root@yourserver root]# cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl
+[root@yourserver root]# cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl
 [root@yourserver root]# chmod 755 /var/qmail/bin/qmailctl
 [root@yourserver root]# ln -s /var/qmail/bin/qmailctl /usr/bin
-[root@yourserver root]# cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run 
-[root@yourserver root]# cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run
-[root@yourserver root]# cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run
-[root@yourserver root]# cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run
+[root@yourserver root]# cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run 
+[root@yourserver root]# cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run
+[root@yourserver root]# cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run
+[root@yourserver root]# cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run
 [root@yourserver root]# chmod 755 /var/qmail/supervise/qmail-send/run
 [root@yourserver root]# chmod 755 /var/qmail/supervise/qmail-send/log/run
 [root@yourserver root]# chmod 755 /var/qmail/supervise/qmail-smtpd/run
@@ -132,13 +132,13 @@
 mkdir -p /var/qmail/supervise/qmail-smtpd/log
 mkdir /var/log/qmail
 chown qmaill /var/log/qmail
-cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl
+cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl
 chmod 755 /var/qmail/bin/qmailctl
 ln -s /var/qmail/bin/qmailctl /usr/bin
-cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run
-cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run
-cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run
-cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run
+cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run
+cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run
+cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run
+cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run
 chmod 755 /var/qmail/supervise/qmail-send/run
 chmod 755 /var/qmail/supervise/qmail-send/log/run
 chmod 755 /var/qmail/supervise/qmail-smtpd/run
Index: openacs-4/packages/acs-core-docs/www/install-redhat.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-redhat.html,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/install-redhat.html	28 Jun 2003 05:07:01 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/install-redhat.html	20 Aug 2003 16:20:16 -0000	1.4
@@ -12,7 +12,7 @@
     of these packages installed independently.)
Unplug the network cable from your
           computer.  We don't want to connect to the network
           until we're sure the computer is secure.  
-
+
   (Wherever you see
           the word secure, you should always read it as, "secure
           enough for our purposes, given the amount of work we're
@@ -40,7 +40,7 @@
 Review (and modify if needed) the partitions created and click Next
On the pop-up window asking "Are you sure
 	  you want to do this?" click
 	  Yes
-	  IF YOU ARE WIPING YOUR HARD DRIVE.
Click Next on the boot loader screen

Configure Networking. + IF YOU ARE WIPING YOUR HARD DRIVE.

Click Next on the boot loader screen

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.

DHCP is a system by which a computer that @@ -61,7 +61,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 @@ -82,9 +82,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,
@@ -97,7 +97,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),�
@@ -125,7 +125,7 @@

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

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

Lock down SSH

+[root@yourserver root]#

Lock down SSH

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/kernel-doc.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-doc.html,v diff -u -N -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/kernel-doc.html 28 Jun 2003 05:07:01 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/kernel-doc.html 20 Aug 2003 16:20:16 -0000 1.11 @@ -1,2 +1,2 @@ -Chapter�13.�Kernel Documentation

Prev	Part�IV.�For OpenACS Platform Developers	Next

Prev	Home	Next
Part�IV.�For OpenACS Platform Developers	Up	Overview

docs@openacs.org

View comments on this page at openacs.org +Chapter�13.�Kernel Documentation

Prev	Part�IV.�For OpenACS Platform Developers	Next

Prev	Home	Next
Part�IV.�For OpenACS Platform Developers	Up	Overview

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/kernel-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-overview.html,v diff -u -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/kernel-overview.html 28 Jun 2003 05:07:01 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/kernel-overview.html 20 Aug 2003 16:20:16 -0000 1.8 @@ -1,31 +1,24 @@ -Overview

Prev	Chapter�13.�Kernel Documentation	Next

Overview

- Compared to its predecessors, version 4.7.0d of OpenACS has a much - more structured organization, i.e. the most - significant change is found at the system architecture level, - reflected in the following hierarchy: -

- The OpenACS 4.7.0d Kernel, which +Overview
Prev Chapter�13.�Kernel Documentation Next
Overview
- + The OpenACS Kernel, which handles system-wide necessities such as metadata, security, users and groups, subsites, and package management and deployment.
- - The OpenACS 4.7.0d Core, which + The OpenACS Core, which comprises all the other packages that ship with the kernel and are most frequently needed by users, such as templating, bboard, and user registration/management. The packages tend to be developed and distributed with the kernel.
- - OpenACS 4.7.0d Application - packages, which typically provide user-level + OpenACS Application packages, which typically provide user-level web services built on top of the Kernel and Core. Such packages include those built by ArsDigita as well as external contributors. Application packages are developed separately from the Kernel, and are typically released independently of it.
This document provides a high level overview of the kernel - package. Documentation for the other packages can be found - elsewhere. + package. Documentation for other packages on this server
Prev Home Next
Chapter�13.�Kernel Documentation Up OpenACS 4 Object Model Requirements
docs@openacs.org
View comments on this page at openacs.org 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 -N -r1.3 -r1.4 --- openacs-4/packages/acs-core-docs/www/linux-installation.html 28 Jun 2003 05:07:01 -0000 1.3 +++ openacs-4/packages/acs-core-docs/www/linux-installation.html 20 Aug 2003 16:20:16 -0000 1.4 @@ -3,9 +3,9 @@ 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 server

yourserver.test

name of administrative access account

remadmin

OpenACS service

service0

OpenACS service account

service0

OpenACS database name

service0

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 server	yourserver.test
name of administrative access account	remadmin
OpenACS service	service0
OpenACS service account	service0
OpenACS database name	service0
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-4.7.0d/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

+ files are located at:

/tmp/openacs-5.0.0d/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 the values that we've chosen. The values that you'll probably want to change, such as service name, are Index: openacs-4/packages/acs-core-docs/www/maintenance-web.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maintenance-web.html,v diff -u -N -r1.3 -r1.4 --- openacs-4/packages/acs-core-docs/www/maintenance-web.html 28 Jun 2003 05:07:02 -0000 1.3 +++ openacs-4/packages/acs-core-docs/www/maintenance-web.html 20 Aug 2003 16:20:16 -0000 1.4 @@ -161,7 +161,7 @@ able to exploit your web server to execute a command on your server, they would not be able to gain root access.

Running multiple services on one machine

Services on different ports.�To run a different service on another port but the same - ip, simply repeat Install OpenACS 4.7.0d replacing + ip, simply repeat Install OpenACS 5.0.0d replacing service0, and change the

set httpport              8000
 set httpsport             8443

Index: openacs-4/packages/acs-core-docs/www/maintenance.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/maintenance.html,v diff -u -N -r1.3 -r1.4 --- openacs-4/packages/acs-core-docs/www/maintenance.html 28 Jun 2003 05:07:02 -0000 1.3 +++ openacs-4/packages/acs-core-docs/www/maintenance.html 20 Aug 2003 16:20:16 -0000 1.4 @@ -1,2 +1,2 @@ -Chapter�9.�Maintenance

Prev	Part�II.�Administrator's Guide	Next

Chapter�9.�Maintenance

Table of Contents

Hosting Web Sites
Database Management
Backup and Recovery

Prev	Home	Next
Upgrading OpenACS 4.5 to 4.6	Up	Hosting Web Sites

docs@openacs.org

View comments on this page at openacs.org +Chapter�9.�Maintenance

Prev	Part�II.�Administrator's Guide	Next

Chapter�9.�Maintenance

Table of Contents

Hosting Web Sites
Database Management
Backup and Recovery

Prev	Home	Next
Support for upgrades.	Up	Hosting Web Sites

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/object-identity.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-identity.html,v diff -u -N -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/object-identity.html 28 Jun 2003 05:07:02 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/object-identity.html 20 Aug 2003 16:20:16 -0000 1.12 @@ -3,18 +3,18 @@ by Rafael H. Schloming
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

One of the major design features of OpenACS 4.7.0d is the explicit representation +

One of the major design features of OpenACS 5.0.0d is the explicit representation of object identity. The reason I say "explicit representation" is because the concept of object identity has been around forever. It is inherent to our problem domain. Consider the example of 3.x style scoping. The 3.x data models use the triple (user_id, group_id, -scope) to identify an object. In the 4.7.0d data model this +scope) to identify an object. In the 5.0.0d data model this object is explicitly represented by a single party_id.

Another good example of this is can be found in the user groups data model. The 3.x user groups data model contains another example of an implied identity. Every mapping between a user and a group could have an arbitrary number of attached values (user_group_member_fields, etc.). In this case it is the pair (group_id, user_id) that implicitly refers to an -object (the person's membership in a group). In the 4.7.0d data model this +object (the person's membership in a group). In the 5.0.0d data model this object identity is made explicit by adding an integer primary key to the table that maps users to groups.

Coming from a purely relational world, this might seem slightly weird at first. The pair (group_id, user_id) is sufficient to uniquely identify the Index: openacs-4/packages/acs-core-docs/www/object-system-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-design.html,v diff -u -N -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/object-system-design.html 28 Jun 2003 05:07:02 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/object-system-design.html 20 Aug 2003 16:20:16 -0000 1.11 @@ -84,7 +84,7 @@ that defines this table.

Object Context and Access Control

Until the implementation of the general permissions system, every OpenACS application had to manage access control to its data separately. Later on, a notion of "scoping" was introduced into the core data model.

"Scope" is a term best explained by example. Consider some -hypothetical rows in the address_book table:

... scope user_id group_id ...
... user 123 � ...
... group � 456 ...
... public � � ...

The first row represents an entry in User 123's personal address book, +hypothetical rows in the address_book table:

... scope user_id group_id ...
... user 123 � ...
... group � 456 ...
... public � � ...

The first row represents an entry in User 123's personal address book, the second row represents an entry in User Group 456's shared address book, and the third row represents an entry in the site's public address book.

In this way, the scoping columns identify the security context in which a @@ -861,5 +861,5 @@ type mechanism is a bit more complex, but in return it provides functionality on par with the old user/groups system in a more general way.

Future Improvements/Areas of Likely Change

Nothing here yet.

Authors

Pete Su generated this document from material culled from other documents by Michael Yoon, Richard Li and Rafael Schloming. But, any remaining lies -are his and his alone.

Revision History

Document Revision # Action Taken, Notes When? By Whom?

0.1 Creation 9/09/2000 Pete Su

0.2 Edited for ACS 4 Beta 9/30/2000 Kai Wu

0.3

Edited for ACS 4.0.1, fixed some mistakes, removed use of term +are his and his alone.

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	9/09/2000	Pete Su
0.2	Edited for ACS 4 Beta	9/30/2000	Kai Wu
0.3	Edited for ACS 4.0.1, fixed some mistakes, removed use of term "OM"	11/07/2000	Pete Su

Prev	Home	Next
OpenACS 4 Object Model Requirements	Up	OpenACS 4 Permissions Requirements

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/object-system-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-requirements.html,v diff -u -N -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/object-system-requirements.html 28 Jun 2003 05:07:02 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/object-system-requirements.html 20 Aug 2003 16:20:16 -0000 1.11 @@ -51,7 +51,7 @@ OpenACS application had to manage access control to its data separately. Later on, a notion of "scoping" was introduced into the core data model.

"Scope" is a term best explained by example. Consider some -hypothetical rows in the address_book table:

... scope user_id group_id ...
... user 123 � ...
... group � 456 ...
... public � � ...

The first row represents an entry in User 123's personal address book, +hypothetical rows in the address_book table:

... scope user_id group_id ...
... user 123 � ...
... group � 456 ...
... public � � ...

In this way, the scoping columns identify the security context in which a @@ -262,7 +262,7 @@ application's data model. In other words, it should be easy to "hook into" the object model, and that ability should not have a major impact on the application data model.

Note: Is the API the only way to obtain values? How does -this integrate with application level SQL queries?

Revision History

Document Revision # Action Taken, Notes When? By Whom?

0.1 Creation 08/10/2000 Bryan Quinn

0.2 Major re-write 08/11/2000 Pete Su

0.3 Draft completed after initial reviews 08/22/2000 Pete Su

0.4 Edited, updated to conform to requirements template, pending freeze 08/23/2000 Kai Wu

� Final edits before freeze 08/24/2000 Pete Su

0.5 Edited for consistency 08/27/2000 Kai Wu

0.6 Put Object ID stuff first, because it makes more sense 08/28/2000 Pete Su

0.7

Added requirement that knowledge-level objects must be moveable between +this integrate with application level SQL queries?

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/10/2000	Bryan Quinn
0.2	Major re-write	08/11/2000	Pete Su
0.3	Draft completed after initial reviews	08/22/2000	Pete Su
0.4	Edited, updated to conform to requirements template, pending freeze	08/23/2000	Kai Wu
�	Final edits before freeze	08/24/2000	Pete Su
0.5	Edited for consistency	08/27/2000	Kai Wu
0.6	Put Object ID stuff first, because it makes more sense	08/28/2000	Pete Su
0.7	Added requirement that knowledge-level objects must be moveable between databases.	08/29/2000	Richard Li
0.8	Rewrote intro to match language and concepts in the design document. Also cleaned up usage a bit in the requirements section. Added short vague requirements on relation types.	09/06/2000	Pete Su
0.9	Edited for ACS 4 Beta release.	09/30/2000	Kai Wu

Prev	Home	Next
Overview	Up	OpenACS 4 Object Model Design

docs@openacs.org

View comments on this page at openacs.org 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 -N -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/objects.html 28 Jun 2003 05:07:02 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/objects.html 20 Aug 2003 16:20:16 -0000 1.12 @@ -1,11 +1,11 @@ -OpenACS Data Models and the Object System

Prev	Chapter�11.�Development Reference	Next

OpenACS Data Models and the Object System

+OpenACS Data Models and the Object System

Prev	Chapter�11.�Development Reference	Next

OpenACS Data Models and the Object System

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

Overview

-Developing data models in OpenACS 4.7.0d is much like developing data models +Developing data models in OpenACS 5.0.0d is much like developing data models for OpenACS 3, save for the implementation. As usual, you need to examine how to model the information that the application must store and manipulate, and define a suitable set of SQL tables. In our Notes @@ -80,8 +80,8 @@

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

+when we created the package. Then, do the following: +

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  
@@ -141,7 +141,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

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 @@ -166,7 +166,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

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

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 @@ -317,7 +317,7 @@ models that are meant to be integrated with the OpenACS object system.

-There are two basic rules you should follow when designing OpenACS 4.7.0d data +There are two basic rules you should follow when designing OpenACS 5.0.0d data models: @@ -372,7 +372,7 @@ requires a good amount of thought at design time even for simple applications.

Summary

-Hooking into the OpenACS 4.7.0d object system brings the application developer +Hooking into the OpenACS 5.0.0d object system brings the application developer numerous benefits, and doing it involves only four easy steps: @@ -396,4 +396,4 @@ especially true for the context_id field.

($Id$)

Prev	Home	Next
OpenACS 4.7.0d Packages	Up	The Request Processor

docs@openacs.org

View comments on this page at openacs.org +

($Id$)

Prev	Home	Next
OpenACS 5.0.0d Packages	Up	The Request Processor

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/openacs-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-overview.html,v diff -u -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/openacs-overview.html 28 Jun 2003 05:07:02 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/openacs-overview.html 20 Aug 2003 16:20:16 -0000 1.8 @@ -40,10 +40,10 @@ to port ACS from Oracle to PostgreSQL, thus making it a fully open-source solution.

- OpenACS 4.7.0d is the next generation of the web toolkit. It's based on + OpenACS 5.0.0d is the next generation of the web toolkit. It's based on ACS 4, but no longer follows ArsDigita development. Unlike ACS (which required Oracle) and OpenACS 3.x (which required PostgreSQL), - OpenACS 4.7.0d allows you to use either database. It's also built in such + OpenACS 5.0.0d allows you to use either database. It's also built in such a way to allow enterprising hackers (in the good sense of the word) to extend it to other databases. Don Baccus leads the development and numerous developers and non-developers Index: openacs-4/packages/acs-core-docs/www/openacs-unpack.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-unpack.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/openacs-unpack.html 28 Jun 2003 05:07:02 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/openacs-unpack.html 20 Aug 2003 16:20:16 -0000 1.3 @@ -2,6 +2,6 @@ Unpack the OpenACS tarball

Prev	Appendix�B.�Install additional supporting software	Next

Unpack the OpenACS tarball

The OpenACS tarball contains sample configuration files for some of the packages listed below. In order to access those files, unpack the tarball now.

[root@yourserver root]# cd /tmp
-[root@yourserver tmp]# tar xzf openacs-4.7.0d.tgz
+[root@yourserver tmp]# tar xzf openacs-5.0.0d.tgz
 cd /tmp
-tar xzf openacs-4.7.0d.tgz

Prev	Home	Next
Appendix�B.�Install additional supporting software	Up	Initialize CVS (OPTIONAL)

docs@openacs.org

View comments on this page at openacs.org +tar xzf openacs-5.0.0d.tgz

Prev	Home	Next
Appendix�B.�Install additional supporting software	Up	Initialize CVS (OPTIONAL)

docs@openacs.org

View comments on this page at openacs.org 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 -N -r1.9 -r1.10 --- openacs-4/packages/acs-core-docs/www/openacs.html 28 Jun 2003 05:07:02 -0000 1.9 +++ openacs-4/packages/acs-core-docs/www/openacs.html 20 Aug 2003 16:20:16 -0000 1.10 @@ -1,5 +1,5 @@ -Install OpenACS 4.7.0d

Prev	Chapter�4.�Installing on Unix/Linux	Next

Install OpenACS 4.7.0d

+Install OpenACS 5.0.0d

Prev	Chapter�4.�Installing on Unix/Linux	Next

Install OpenACS 5.0.0d

by Vinod Kurup
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. @@ -31,7 +31,7 @@ of your site is one word, that would be a good choice. For example "service0" might be the service name for the service0.net - community.

For the 4.7.0d-P and 4.7.0d-O Reference Platform, + community.

For the 5.0.0d-P and 5.0.0d-O Reference Platform, we'll use a server named service0 and a user named service0. We'll leave the password blank for increased security. The only way to log in will be @@ -72,8 +72,8 @@ [root@yourserver root]#

Unpack the OpenACS tarball and rename it to service0. Secure the directory so that only the owner can access it. Check the permissions by listing the directory.

[root@yourserver root]# su - service0
 [service0@yourserver service0]$ cd /web
-[service0@yourserver web]$ tar xzf /tmp/openacs-4.7.0d.tgz
-[service0@yourserver web]$ mv openacs-4.7.0d service0
+[service0@yourserver web]$ tar xzf /tmp/openacs-5.0.0d.tgz
+[service0@yourserver web]$ mv openacs-5.0.0d service0
 [service0@yourserver web]$ chmod -R 700 service0
 [service0@yourserver web]$ ls -al
 total 3
@@ -86,8 +86,8 @@
 [root@yourserver root]#
 su - service0
 cd /web
-tar xzf /tmp/openacs-4.7.0d.tgz
-mv openacs-4.7.0d service0
+tar xzf /tmp/openacs-5.0.0d.tgz
+mv openacs-5.0.0d service0
 chmod -R 700 service0/
 exit

Add the Service to CVS (OPTIONAL)

(This step should be obsoleted by the 5.0.0 tarball, as these directories will be included in the tarball)Set up several additional directories in the service root: @@ -242,11 +242,11 @@ logout [root@yourserver root]#

Create a database with the same name as our service name, service0.

[root@yourserver root]# su - service0
-[service0@yourserver service0]$ createdb service0
+[service0@yourserver service0]$ createdb -E UNICODE service0
 CREATE DATABASE
 [service0@yourserver service0]$
 su - service0
-createdb service0

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

Add Full Text Search Support (OPTIONAL)

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

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

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

Add Full Text Search Support (OPTIONAL)

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

Configure an AOLserver Service for OpenACS

@@ -256,7 +256,7 @@ need to configure a virtual server. The Reference Platform uses a configuration file included in the OpenACS tarball, /web/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 /web/service0/etc
 [service0@yourserver etc]# emacs config.tcl
 

@@ -321,7 +321,7 @@

Automate AOLserver keepalive (OPTIONAL)

Configure a Service with the OpenACS Installer

Now that you've got AOLserver up and running, let's install OpenACS - 4.7.0d. + 5.0.0d.

You should see a page from the webserver titled OpenACS Installation: @@ -377,10 +377,10 @@ Give the server a few minutes to start up. Then reload the final page above. You should see the front page, with an area to login near the upper right. Congratulations, OpenACS - 4.7.0d is now up and running! + 5.0.0d is now up and running!
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/oracle.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/oracle.html,v diff -u -N -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/oracle.html 28 Jun 2003 05:07:02 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/oracle.html 20 Aug 2003 16:20:16 -0000 1.12 @@ -9,7 +9,7 @@
Note
- OpenACS 4.7.0d does not yet work with Oracle 9i + OpenACS 5.0.0d does not yet work with Oracle 9i
@@ -1271,7 +1271,7 @@
```
 SQL> drop tablespace table_space_name including contents cascade constraints;
```

For more information on Oracle, please consult the documentation. -

`Defaults`

We used the following defaults while installing Oracle.

Variable Value Reason

ORACLE_HOME /ora8/m01/app/oracle/product/8.1.7 This is the default Oracle installation directory.

ORACLE_SERVICE

ora8

The service name is a domain-qualified identifier for +

Defaults

We used the following defaults while installing Oracle.

Variable Value Reason

ORACLE_HOME /ora8/m01/app/oracle/product/8.1.7 This is the default Oracle installation directory.

ORACLE_SERVICE ora8 The service name is a domain-qualified identifier for your Oracle server.

ORACLE_SID ora8 This is an identifier for your Oracle server.

ORACLE_OWNER oracle The user who owns all of the oracle files.

ORACLE_GROUP

dba

The special oracle group. Users in the dba group are authorized to do a connect internal within Index: openacs-4/packages/acs-core-docs/www/packages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/packages.html,v diff -u -N -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/packages.html 28 Jun 2003 05:07:02 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/packages.html 20 Aug 2003 16:20:16 -0000 1.12 @@ -1,5 +1,5 @@ -OpenACS 4.7.0d Packages

Prev	Chapter�11.�Development Reference	Next

OpenACS 4.7.0d Packages

+OpenACS 5.0.0d Packages

Prev	Chapter�11.�Development Reference	Next

OpenACS 5.0.0d Packages

By Pete Su and Bryan Quinn
OpenACS docs are written by the named authors, and may be edited @@ -61,7 +61,7 @@ the pieces of each module are strewn all over the tree in at least 3 or 4 different areas.

- Here is how an OpenACS 4.7.0d server is laid out: + Here is how an OpenACS 5.0.0d server is laid out:

 
 ROOT/
@@ -125,7 +125,7 @@
       sends to our server to the right page in the appropriate
       package. While we're at it, this tool should also automate
       package installation, dependency checking, upgrades, and package
-      removal. In OpenACS 4.7.0d, this tool is called the APM.
+      removal. In OpenACS 5.0.0d, this tool is called the APM.

The APM

The APM is used to create, maintain, and install packages. It takes care of copying all of the files and registering the package in the @@ -147,7 +147,7 @@

The following sections will show you how to make a package for the Notes application. In addition, they will discuss some new site - management features in OpenACS 4.7.0d that take advantage of the APM's package + management features in OpenACS 5.0.0d that take advantage of the APM's package instance model. The two most important of these are subsites, and the site map tool, which can be used to map applications to one or more arbitrary URLs in a running site. @@ -218,7 +218,7 @@ All file locations are relative to the package root, which in this case is ROOT/packages/notes. The following table describes in detail what each of the files up in the diagram contain. -

File Type Its Use Naming Convention

Data Model Creation Script

File Type Its Use Naming Convention

Data Model Creation Script

Contains the SQL that creates the necessary data model and PL/SQL packages (or PL/pgSQL or whatever) to support the package. The name must match the convention below or the @@ -435,7 +435,7 @@ map content that lived outside the page root into the site, and it was also hard to map mulitiple URLs to the same place in the file system.

- In OpenACS 4.7.0d, administrators can define an arbitrary mapping between the + In OpenACS 5.0.0d, administrators can define an arbitrary mapping between the URLs the user types and the actual file in the file system that is served. This mapping is called the site map and entries in the site map are called site nodes. Each site node maps a URL to an @@ -450,7 +450,7 @@ of many indedendent applications that actually run on a single shared code base. The request-processor document shows you how OpenACS figures out which instance of your application was - requested by the user at any given time. The page development tutorial shows you how to use this + requested by the user at any given time. The page development tutorial shows you how to use this information in your user interface.

In order to make the new notes application visible to @@ -477,7 +477,7 @@ yet written Notes application at various places in the site. In a later document, we'll see how to write your application so that the code can detect from what URL it was invoked. This is the key - to supporting subsites. + to supporting subsites.

Summary

The APM performs the following tasks in an OpenACS site:

@@ -493,4 +493,4 @@
Writes out package distribution files for other people to download and install. We'll cover this later. -

Additional Reading

($Id$)

Prev	Home	Next
Chapter�11.�Development Reference	Up	OpenACS Data Models and the Object System

docs@openacs.org

View comments on this page at openacs.org +

Additional Reading

($Id$)

Prev	Home	Next
Chapter�11.�Development Reference	Up	OpenACS Data Models and the Object System

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/parties.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/parties.html,v diff -u -N -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/parties.html 28 Jun 2003 05:07:02 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/parties.html 20 Aug 2003 16:20:16 -0000 1.12 @@ -1,5 +1,5 @@ -Parties in OpenACS 4.7.0d

Prev	Chapter�11.�Development Reference	Next

Parties in OpenACS 4.7.0d

+Parties in OpenACS 5.0.0d

Prev	Chapter�11.�Development Reference	Next

Parties in OpenACS 5.0.0d

by Rafael H. Schloming
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. @@ -67,7 +67,7 @@ users) is that it is now possible to "nuke" a user from a live system by removing his entry from the users table, but leaving the rest of his information present (i.e. turning him from a user into a person). This is -because wherever possible the OpenACS 4.7.0d data model references the persons or +because wherever possible the OpenACS 5.0.0d data model references the persons or parties table, not the users table. If this feature is desired when extending the system, then the developers should be careful to only references the users table in situations where it is clear that the @@ -299,7 +299,7 @@ have a primary key that references the users table, thereby guaranteeing that each row in the mensa_users table has a corresponding row in each of the users, persons, parties, and acs_objects tables. This child table could then -store any extra information relevant to the MENSA community.

Specializing Groups

If one were to build an intranet application on top of the 4.7.0d party +store any extra information relevant to the MENSA community.

Specializing Groups

If one were to build an intranet application on top of the 5.0.0d party system, it is likely that one would want to take advantage of the systems efficient representation of sophisticated organizational structures, but there would be much more specialized information associated with each group. @@ -313,4 +313,4 @@ single integer primary key in what could be thought of as a pure relation. Because a membership relation is an ordinary acs object with object identity, it is as easy to extend the membership relation to store extra information as it is to extend the users -table or the groups table.

($Id$)

Prev	Home	Next
Writing OpenACS 4.7.0d Application Pages	Up	OpenACS 4.x Permissions Tediously Explained

docs@openacs.org

View comments on this page at openacs.org +table or the groups table.

($Id$)

Prev	Home	Next
Writing OpenACS 5.0.0d Application Pages	Up	OpenACS 4.x Permissions Tediously Explained

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/permissions-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-design.html,v diff -u -N -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/permissions-design.html 28 Jun 2003 05:07:02 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/permissions-design.html 20 Aug 2003 16:20:16 -0000 1.11 @@ -184,4 +184,4 @@

Rafael H. Schloming

Documentation author -

John Prevost

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	9/11/2000	John Prevost
0.2	Edited for ACS 4 Beta release	10/04/2000	Kai Wu

Prev	Home	Next
OpenACS 4 Permissions Requirements	Up	OpenACS 4 Groups Requirements

docs@openacs.org

View comments on this page at openacs.org +

John Prevost

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	9/11/2000	John Prevost
0.2	Edited for ACS 4 Beta release	10/04/2000	Kai Wu

Prev	Home	Next
OpenACS 4 Permissions Requirements	Up	OpenACS 4 Groups Requirements

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/permissions-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-requirements.html,v diff -u -N -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/permissions-requirements.html 28 Jun 2003 05:07:02 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/permissions-requirements.html 20 Aug 2003 16:20:16 -0000 1.11 @@ -88,5 +88,5 @@ on its own.

120.0 Ease of Use

Since most SQL queries will contain an allowed target check in the where clause, whatever mechanism is used to make checks in SQL should be fairly small and simple.

In particular, constraining a SELECT to return only rows the -current user has access to should not add more than one line to a query.

Revision History

Document Revision # Action Taken, Notes When? By Whom?

0.1 Creation 8/17/2000 John Prevost

0.2 Revised, updated with new terminology 8/25/2000 John Prevost

0.3

Edited, reformatted to conform to requirements template, pending +current user has access to should not add more than one line to a query.

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	8/17/2000	John Prevost
0.2	Revised, updated with new terminology	8/25/2000	John Prevost
0.3	Edited, reformatted to conform to requirements template, pending freeze.	8/26/2000	Kai Wu
0.4	Edited for ACS 4 Beta release.	10/03/2000	Kai Wu

Prev	Home	Next
OpenACS 4 Object Model Design	Up	OpenACS 4 Permissions Design

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html,v diff -u -N -r1.5 -r1.6 --- openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 28 Jun 2003 05:07:02 -0000 1.5 +++ openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 20 Aug 2003 16:20:16 -0000 1.6 @@ -1,5 +1,5 @@ -OpenACS 4.x Permissions Tediously Explained

Prev	Chapter�11.�Development Reference	Next

OpenACS 4.x Permissions Tediously Explained

+OpenACS 4.x Permissions Tediously Explained

Prev	Chapter�11.�Development Reference	Next

OpenACS 4.x Permissions Tediously Explained

by Vadim Nasardinov. Modified and converted to Docbook XML by Roberto Mello

Overview

The general permissions system has a relatively complex data model in OpenACS 4.x. @@ -86,7 +86,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_id	grantee_id	privilege
object_id_1	user_id_1	'read'
object_id_1	user_id_2	'read'
...
object_id_1	user_id_n	'read'
object_id_2	user_id_1	'read'
object_id_2	user_id_2	'read'
...
object_id_2	user_id_n	'read'
...
...
object_id_m	user_id_1	'read'
object_id_m	user_id_2	'read'
...
object_id_m	user_id_n	'read'

Table�11.1.�

object_id	grantee_id	privilege
object_id_1	user_id_1	'read'
object_id_1	user_id_2	'read'
...
object_id_1	user_id_n	'read'
object_id_2	user_id_1	'read'
object_id_2	user_id_2	'read'
...
object_id_2	user_id_n	'read'
...
...
object_id_m	user_id_1	'read'
object_id_m	user_id_2	'read'
...
object_id_m	user_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 @@ -101,7 +101,7 @@

Context Hierarchy

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

Table�11.2.�

object_id=10

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

Table�11.3.�

object_id	context_id
20	10
30	10
40	20
50	20
60	30

Table�11.3.�

object_id	context_id
20	10
30	10
40	20
50	20
60	30

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

object	grantee	privilege
A	Joe	read

Table�11.4.�

object	grantee	privilege
A	Joe	read

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

object	ancestor	n_generations
A	A	0
B	B	0
B	A	1
C	C	0
C	A	1
D	D	0
D	B	1
D	A	2
E	E	0
E	B	1
E	A	2
F	F	0
F	C	1
F	A	2

Table�11.5.�

object	ancestor	n_generations
A	A	0
B	B	0
B	A	1
C	C	0
C	A	1
D	D	0
D	B	1
D	A	2
E	E	0
E	B	1
E	A	2
F	F	0
F	C	1
F	A	2

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 @@ -204,7 +204,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.�

A
object_id=10
readable�by�Joe
@@ -232,7 +232,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, @@ -241,7 +241,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

create

delete

read

write

moderate forum

create category

create forum

create message

delete category

delete forum

delete message

read category

read forum

read message

write category

write forum

write message

Table�11.8.�

admin

create

delete

read

write

moderate forum

create category

create forum

create message

delete category

delete forum

delete message

read category

read forum

read message

write category

write forum

write message

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

@@ -287,7 +287,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
persons	groups
users

+    
Table�11.9.�
parties
persons groups
users
   create table parties (
       party_id
           not null
@@ -371,7 +371,7 @@
     

       The acs_rels 
       table entries would look like so: 
-    
Table�11.10.�
rel_type object_one object_two

+    
Table�11.10.�
rel_type object_one object_two

 	      membership_rel
 	    
 	      Pranksters
@@ -406,7 +406,7 @@
     
       The relevant entries in the 
       acs_rels look like so. 
-    
Table�11.11.�
rel_type object_one object_two

+    
Table�11.11.�
rel_type object_one object_two

 	      composition_rel
 	    
 	      Pranksters
@@ -617,7 +617,7 @@
     
       Note that in the above example, acs_permissions had only
       one entry that needed to be deleted: 
-    
Table�11.12.�
object_id grantee_id privilege

+    
Table�11.12.�
object_id grantee_id privilege

 	      default_context
 	    
 	      registered_users
@@ -690,4 +690,4 @@
   container_id
 from
   group_member_index;
-    
Prev Home  Next
Parties in OpenACS 4.7.0d Up  Object Identity
docs@openacs.org
View comments on this page at openacs.org
+    
Prev Home  Next
Parties in OpenACS 5.0.0d Up  Object Identity
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/permissions.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions.html,v
diff -u -N -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/permissions.html	28 Jun 2003 05:07:02 -0000	1.11
+++ openacs-4/packages/acs-core-docs/www/permissions.html	20 Aug 2003 16:20:16 -0000	1.12
@@ -1,9 +1,9 @@
 
-Groups, Context, PermissionsPrev Chapter�11.�Development Reference  Next
Groups, Context, Permissions
By Pete Su


+Groups, Context, PermissionsPrev Chapter�11.�Development Reference  Next
Groups, Context, Permissions
By Pete Su


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

-The OpenACS 4.7.0d Permissions system allows developers and administrators to
+The OpenACS 5.0.0d Permissions system allows developers and administrators to
 set access control policies at the object level, that is, any
 application or system object represented by a row in the
 acs_objects table can be access-controlled via a simple
@@ -14,7 +14,7 @@
 Although this may all sound easy and wonderful, no developer or
 administrator would want to explicitly set access control
 rights for every user and every object on a
-site. Therefore, OpenACS 4.7.0d has two auxiliary mechanisms for making this
+site. Therefore, OpenACS 5.0.0d has two auxiliary mechanisms for making this
 easier: First, the Groups system allows users to be grouped together
 in flexible ways. Second, the object model defines a notion of
 object context, which allows applications to group objects
@@ -26,7 +26,7 @@
 define simple groupings of users. Each group had a human readable name
 and unique ID, and there was a single mapping table that mapped users
 to groups. (The actual data model was more complicated because it
-contained a meta-data system much like the OpenACS 4.7.0d object type system,
+contained a meta-data system much like the OpenACS 5.0.0d object type system,
 but that's not relevant right now.)
 

 The 3.x groups system, while very useful, was limited in few ways. The
@@ -48,7 +48,7 @@
 member of Greenpeace, its members are not necessarily members of
 Greenpeace.
 

-OpenACS 4.7.0d solves both of these modeling problems by introducing a new
+OpenACS 5.0.0d solves both of these modeling problems by introducing a new
 abstraction called a party. Parties have a recursive
 definition, and we can illustrate how it works with the following
 simplified data model. First, we define the parties
@@ -114,18 +114,18 @@
 already know what parties and objects are, but we don't know what
 privileges are.
 

-In OpenACS 4.7.0d, a privilege models the right to perform some operation on
+In OpenACS 5.0.0d, a privilege models the right to perform some operation on
 some object. They are the basic units out of which we build access
 control policies.  For example, in the Unix filesystem we typically
 implement access control by granting users some combination of
-read. write or execute privileges on files and directories. In OpenACS 4.7.0d,
+read. write or execute privileges on files and directories. In OpenACS 5.0.0d,
 the table of privileges is organized hierarchically so that developers
 can define privileges that aggregate some set of privileges
 together. For example, if we have read, write, create and delete
 privileges, it might be convenient to combine them into a new privilege
 called "admin". Then if we grant a user this privilege she is
 automatically granted all the child privileges that the privilege
-contains. The OpenACS 4.7.0d kernel data model actually defines these
+contains. The OpenACS 5.0.0d kernel data model actually defines these
 privileges as follows:
 
 
@@ -165,11 +165,11 @@
 permissions to large groups of objects in the site, all at once. We
 use contexts to achieve this goal.
 
Object Context

-In OpenACS 4.7.0d, an object context is a generalization of the scoping
+In OpenACS 5.0.0d, an object context is a generalization of the scoping
 mechanism introduced in OpenACS 3.x.  "Scoping" and "scope" are terms best
 explained by example: consider some hypothetical rows in the
 address_book table:
-
... scope user_id group_id ...
... user 123 � ...
... group � 456 ...
... public � � ...

+
... scope user_id group_id ...
... user 123 � ...
... group � 456 ...
... public � � ...

 The first row represents an entry in User 123's personal address book,
 the second row represents an entry in User Group 456's shared address
 book, and the third row represents an entry in the site's public
@@ -180,7 +180,7 @@
 person or a group of people or the general public
 (itself a group of people).
 

-In OpenACS 4.7.0d, rather than breaking the world into a limited set of scopes,
+In OpenACS 5.0.0d, rather than breaking the world into a limited set of scopes,
 every object lives in a single context.  A context is just an
 another object that represents the security domain to which the object
 belongs. By convention, if an object A doesn't have any permissions
@@ -197,7 +197,7 @@
 application. With only row-level permissions it is not obvious how to
 reasonably initialize the access control list when creating a
 message. At best, we have to explicitly grant various read and write
-privileges whenever we create a message, which is tedious.  In OpenACS 4.7.0d,
+privileges whenever we create a message, which is tedious.  In OpenACS 5.0.0d,
 a reasonable thing to do is to create an object representing a forum,
 and point the context_id field of a new message at the
 forum. Then, suppose we grant every user in the system read-access to
@@ -331,7 +331,7 @@
 

 This displays the title of the note as either a link or plain text
 depending on whether or not we have write privileges on the object.
-The if tag is something that the OpenACS 4.7.0d template system
+The if tag is something that the OpenACS 5.0.0d template system
 defines for you to support conditional presentation. The templates developer guide provides more information about this.
 

 If you study the rest of the system, you will also notice that the
@@ -345,7 +345,7 @@
 permissions to notes that she wanted to make public or whatever. But
 that's beyond the scope of this example.
 
Summary

-OpenACS 4.7.0d defines three separate mechanisms for specifying access control
+OpenACS 5.0.0d defines three separate mechanisms for specifying access control
 in applications. The Groups data model allows you to define 
 hierarchical organizations of users and groups of users. The Permissions
 data model allows you to define a hierarchy of user rights. Finally,
@@ -355,4 +355,4 @@
 

 In the next section, we'll look at a more complex page for adding and
 editing notes, and discuss these issues further.
-
($Id$)
Prev Home  Next
Using Templates in OpenACS 4.7.0d Up  Writing OpenACS 4.7.0d Application Pages
docs@openacs.org
View comments on this page at openacs.org
+
($Id$)
Prev Home  Next
Using Templates in OpenACS 5.0.0d Up  Writing OpenACS 5.0.0d Application Pages
docs@openacs.org
View comments on this page at openacs.org
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 -N -r1.9 -r1.10
--- openacs-4/packages/acs-core-docs/www/postgres.html	28 Jun 2003 05:07:02 -0000	1.9
+++ openacs-4/packages/acs-core-docs/www/postgres.html	20 Aug 2003 16:20:16 -0000	1.10
@@ -3,14 +3,14 @@
 	by Vinod Kurup

           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Skip this section if you will run only Oracle.
OpenACS 4.7.0d will run with PostGreSQL 7.2.x or 7.3.2.  It
+        
Skip this section if you will run only Oracle.
OpenACS 5.0.0d will run with PostGreSQL 7.2.x or 7.3.2.  It
   has not been fully tested with 7.3.2; 7.2.4 is the recommended
   version of PostgreSQL to use.
Using the Red Hat RPM.�Red Hat users: If you install PostGreSQL 7.3.2 from the Red Hat 9 RPM, you
   can skip a few steps.  These shell commands add a link so that the
   data directory appears to be in the same place as in a source
   install; start the service; create a new group for web service
   users, and modify the postgres user's
-  environment (more
+  environment (more
   information):
[root@yourserver root]# ln -s /var/lib/pgsql/data /usr/local/pgsql/data
 [root@yourserver root]# service postgresql start
 Initializing database:
@@ -27,7 +27,7 @@
 echo "export LD_LIBRARY_PATH=/usr/local/pgsql/lib" >> ~postgres/.bash_profile
 echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bash_profile
 groupadd web
-su - postgres
... and then skip to 6.  Something similar may work for other binary packages as well.
Unpack PostGreSQL.�If you have not downloaded the postgresql tarball to
+su - postgres
... and then skip to 3.  Something similar may work for other binary packages as well.
Unpack PostGreSQL.�If you have not downloaded the postgresql tarball to
         /tmp/postgresql-7.2.4.tar.gz,
         get it.
[root@yourserver root]# cd /usr/local/src
 [root@yourserver src]# tar xzf /tmp/postgresql-7.2.4.tar.gz
@@ -64,7 +64,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
@@ -161,11 +161,11 @@
         state. Red Hat and Debian and SuSE each work a little
         differently.
 	
Red Hat RPM:
The init script is already installed; just turn it on for the appropriate run levels.
[root@yourserver root]# chkconfig --level 345 postgresql on
-[root@yourserver root]# 
Red Hat from source:
[root@yourserver src]# cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
+[root@yourserver root]# 
Red Hat from source:
[root@yourserver src]# cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
 [root@yourserver src]# chown root.root /etc/rc.d/init.d/postgresql
 [root@yourserver src]# chmod 755 /etc/rc.d/init.d/postgresql
 [root@yourserver src]# 
-cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
+cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
 chown root.root /etc/rc.d/init.d/postgresql
 chmod 755 /etc/rc.d/init.d/postgresql
Test the script.
[root@yourserver root]# service postgresql stop
 Stopping PostgreSQL: ok
@@ -184,11 +184,11 @@
 chkconfig --add postgresql
 chkconfig --level 345 postgresql on
 chkconfig --list postgresql
-service postgresql start
Debian:
root:~# cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
+service postgresql start
Debian:
root:~# cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
 root:~# chown root.root /etc/init.d/postgresql
 root:~# chmod 755 /etc/init.d/postgresql
 root:~# -cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
+cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
 chown root.root /etc/init.d/postgresql
 chmod 755 /etc/init.d/postgresql
Test the script
root:~# /etc/init.d/postgresql stop
 Stopping PostgreSQL: ok
@@ -216,7 +216,7 @@
             rc.d/ part in each of the
             following commands.
 
-          
root:~# cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/postgresql.txt /etc/rc.d/init.d/postgresql
+          
root:~# cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/postgresql.txt /etc/rc.d/init.d/postgresql
 root:~# chown root.root /etc/rc.d/init.d/postgresql
 root:~# chmod 755 /etc/rc.d/init.d/postgresql

 
Index: openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html,v
diff -u -N -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html	28 Jun 2003 05:07:02 -0000	1.11
+++ openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html	20 Aug 2003 16:20:16 -0000	1.12
@@ -42,7 +42,7 @@
 which runs frequently, don't use the -thread
 switch.
Note also that thread is initialized with a copy of what was
 installed during server startup, so if the procedure table have changed since
-startup (e.g. using the APM watch
+startup (e.g. using the APM watch
 facility), that will not be reflected in the scheduled
 thread.
Using return

 The return command in Tcl returns control to the caller procedure.
Index: openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html,v
diff -u -N -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html	28 Jun 2003 05:07:02 -0000	1.2
+++ openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html	20 Aug 2003 16:20:16 -0000	1.3
@@ -1,9 +1,9 @@
 
-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
       fixes the backspace -> help mis-mapping that often occurs in
-      terminals.
[root@yourserver tmp]# cp /tmp/openacs-4.7.0d/packages/acs-core-docs/www/files/emacs.txt /etc/skel/.emacs
+      terminals.
[root@yourserver tmp]# cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/emacs.txt /etc/skel/.emacs
 cp: overwrite `/etc/skel/.emacs'? y
 [root@yourserver tmp]# 
Prev Home  Next
Initialize CVS (OPTIONAL) Up  Install Daemontools (OPTIONAL)
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/psgml-mode.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-mode.html,v
diff -u -N -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/psgml-mode.html	28 Jun 2003 05:07:02 -0000	1.11
+++ openacs-4/packages/acs-core-docs/www/psgml-mode.html	20 Aug 2003 16:20:16 -0000	1.12
@@ -82,6 +82,6 @@
 top.xml, that the element in the parent that will enclose the
 current document is a book and that the current file's topmost
 element is a sect1.
How to use it
Of course, you should read the emacs texinfo pages that come with PSGML
-mode from start to finish. Barring that, here are some handy commands:
Key Command
C-c C-e Insert an element. Uses completion and only lets you insert elements that
+mode from start to finish. Barring that, here are some handy commands:
Key Command
C-c C-e Insert an element. Uses completion and only lets you insert elements that
 are valid
C-c C-a Edit attributes of enclosing element.
C-c C-x C-i Show information about the document's DTD.
C-c C-x C-e Describe element. Shows for one element which elements can be parents,
 what its contents can be and lists its attributes.
Further reading
Start with the OpenACS Documentation Guide
($Id$)
Prev Home  Next
OpenACS Documentation Guide Up  Detailed Design Documentation Template
docs@openacs.org
View comments on this page at openacs.org
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 -N -r1.1 -r1.2
--- openacs-4/packages/acs-core-docs/www/quick.html	28 Jun 2003 05:20:44 -0000	1.1
+++ openacs-4/packages/acs-core-docs/www/quick.html	20 Aug 2003 16:20:16 -0000	1.2
@@ -9,6 +9,223 @@
 	  installation in under an hour.  It excludes source control,
 	  full text search, ssl, managed services (daemontools),
 	  DocBook, and qmail.  
-	
For Red Hat 9
Install PostGreSQL 7.3.2 from RPM.  Select
+	
For Red Hat 9
Install PostGreSQL 7.3.2 from RPM.  Select
         Menu > System Settings > Add/Remove
-        Applications and select Database Server.
On the PostGreSQL page, do the Using the Red Hat RPM bullet point and step 6
On the Aolserver page, do steps 1, 2, and 3
In the section called “Set up the file system for an OpenACS Service” on the OpenACS page, do steps 1, 2, 3, and 4
In the section called “Prepare PostgreSQL for an OpenACS Service”, do steps 1, 2, and 5
In the section called “Configure an AOLserver Service for OpenACS”, do 1
Browse to http://localhost:8000.  If you see a page like this, proceed with Using the OpenACS Installer.  If not, look at 2 for troubleshooting information.
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
+        Applications and select Database Server.
Using the Red Hat RPM.�Red Hat users: If you install PostGreSQL 7.3.2 from the Red Hat 9 RPM, you
+  can skip a few steps.  These shell commands add a link so that the
+  data directory appears to be in the same place as in a source
+  install; start the service; create a new group for web service
+  users, and modify the postgres user's
+  environment (more
+  information):
Install Pl/pgSQL.�Set up plpgsq and allow your user to have
+	  access. Plpgsql is a PL/SQL-like language.  We add it to
+	  template1, which is the template from which all new
+	  databases are created.  We can verify that it was created
+	  with the createlang command in list mode.
[postgres@yourserver pgsql]$ createlang plpgsql template1
+[postgres@yourserver pgsql]$ createlang -l template1
+Procedural languages
+  Name   | Trusted?
+---------+----------
+ plpgsql | t
+(1 row)
+
+[postgres@yourserver pgsql]$
+createlang plpgsql template1
+createlang -l template1
Unpack the Aolserver tarball.�Download the aolserver tarball to /tmp/aolserver3.3oacs1.tar.gz.  As root, untar
+      aolserver3.3oacs1.tar.gz
+      into /usr/local/src.
+    
[root@yourserver root]# cd /usr/local/src
+[root@yourserver src]# tar xzf /tmp/aolserver3.3oacs1.tar.gz
+[root@yourserver src]#
+cd /usr/local/src
+tar xzf /tmp/aolserver3.3oacs1.tar.gz
Compile AOLserver.�Compile and install AOLserver.  First, prepare the installation directory and the source code.  The message about BUILD-MODULES can be ignored.
root@yourserver root]# mkdir -p /usr/local/aolserver
+[root@yourserver root]# cd /usr/local/src/aolserver
+[root@yourserver aolserver]# ./conf-clean
+cat: BUILD-MODULES: No such file or directory
+Done.
+[root@yourserver aolserver]#mkdir -p /usr/local/aolserver
+cd /usr/local/src/aolserver
+./conf-clean

+          If you are using Oracle, edit
+          conf-db and change
+          postgresql to
+          oracle, or to the word
+          both if you want both drivers
+          installed.  In order to get nsoracle to compile, you may
+          need to su - oracle, and then su (without the -) root to set
+          the environment variables properly.
+        
conf-inst should contain the
+          location where AOLserver is to be installed.  Overwrite the
+          tarball's default value with our default value, /usr/local/aolserver:
[root@yourserver aolserver]# echo "/usr/local/aolserver" > conf-inst
+[root@yourserver aolserver]#
conf-make should contain the
+          name of the GNU Make command on your system. It defaults to
+          gmake.
Set an environment variable that the nspostgres driver
+      Makefile needs to compile correctly and run
+          conf, which compiles
+          AOLserver, the default modules, and the database driver, and
+          installs them.
(Debian Users working with AOLserver 3.3+ad13 and
+          postgresql from apt-get may need to
+          make these symlinks: ln -s
+          /usr/include/postgresql/ /usr/include/pgsql
+          and ln -s /usr/lib/postgresql /usr/local/pgsql)
[root@yourserver aolserver]# export POSTGRES=/usr/local/pgsql; ./conf
+Building in /usr/local/aolserver
+with the following modules:
+aolserver
+nscache
+nsrewrite
+nssha1
+nsxml
+pgdriver
+==================================================================
+Starting Build Sat Mar  8 10:28:26 PST 2003
+Running gmake in aolserver/; output in log/aolserver.log
+(several minute delay here)
+Running gmake in nscache/; output in log/nscache.log
+Running gmake in nsrewrite/; output in log/nsrewrite.log
+Running gmake in nssha1/; output in log/nssha1.log
+Running gmake in nsxml/; output in log/nsxml.log
+Running gmake in nspostgres/; output in log/nspostgres.log
+Creating  ...
+==================================================================
+Done Building Sat Mar  8 10:31:35 PST 2003
+[root@yourserver aolserver]# 

+          This takes about 5 minutes. It builds aolserver, several modules, and the database driver.  (Upgraders, note that the postgres database driver has changed from postgres.so to nspostgres.so).  All of the results are logged to files in /usr/local/src/aolserver/log.  If you run into problems running AOLserver, check these files for build errors.
Add a database-specific wrapper script.�This script
+	  sets database environment variables before starting
+	  AOLserver; this allows the AOLserver instance can
+	  communicate with the database.  There is one script each for
+	  Oracle and PostGreSQL.  They don't conflict, so if you plan
+	  to use both databases, install both.
Oracle
[root@yourserver aolserver]# cd /usr/local/aolserver/bin
+[root@yourserver bin]# cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle
+[root@yourserver bin]# chmod 750 nsd-oracle
+[root@yourserver bin]#
+cd /usr/local/aolserver/bin
+cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle
+chmod 750 nsd-oracle
PostGreSQL
[root@yourserver aolserver]# cd /usr/local/aolserver/bin
+[root@yourserver bin]# cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres
+[root@yourserver bin]# chmod 755 nsd-postgres
+[root@yourserver bin]#
+cd /usr/local/aolserver/bin
+cp /tmp/openacs-5.0.0d/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres
+chmod 755 nsd-postgres
The reference install stores all OpenACS services in
+      /web, with one subdirectory per
+      service.  The first time you install a service, you must create
+      that directory and set its permissions:
[root@yourserver root]# mkdir /web
+[root@yourserver root]# chgrp web /web
+[root@yourserver root]# chmod 770 /web
+[root@yourserver root]#
+mkdir /web
+chgrp web /web
+chmod 770 /web
You should already have downloaded the OpenACS tarball
+      to the /tmp directory.  If
+      not, download the OpenACS
+      tarball and save it in
+      /tmp and proceed:
Set up your user account.

+      AOLserver needs to be started as the root user if you want to use
+      port 80. Once it starts, though, it will drop the root privileges and
+      run as another user, which you must specify on the command line. It's
+      important that this user has as few privileges as possible. Why?
+      Because if an intruder somehow breaks in through AOLserver, you don't
+      want her to have any ability to do damage to the rest of your
+      server.
At the same time, AOLserver needs to have write access to
+      some files on your system in order for OpenACS to function
+      properly. So, we'll run AOLserver with a different user account
+      for each different service.  A service name should be a single
+      word, letters and numbers only. If the name
+      of your site is one word, that would be a good choice. For
+      example "service0" might be the service name for the
+      service0.net
+      community.
For the 5.0.0d-P and 5.0.0d-O Reference Platform,
+      we'll use a server named service0 and
+      a user named service0.  We'll leave the password
+      blank for increased security.  The only way to log in will be
+      with ssh certificates.  The only people who should log in are
+      developers for that specific instance.  Add this user, and put
+      it in the web group so that it
+      can use database commands associated with that group.
+    
[root@yourserver root]# useradd -g web service0 -d /home/service0
+[root@yourserver root]#
Set up database environment variables.  They are
+	necessary for working with the database.  
+
[root@yourserver root]# su - service0
+[service0@yourserver service0]$ emacs .bashrc
Put in the appropriate lines for the database you are running.  If you will use both databases, put in both sets of lines.
PostGreSQL:
export LD_LIBRARY_PATH=LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib
+export PATH=$PATH:/usr/local/pgsql/bin
Oracle.  These environment variables are specific for a local Oracle
+      installation communicating via IPC. If you are connecting to a remote
+      Oracle installation, you'll need to adjust these appropriately. Also,
+      make sure that the '8.1.7' matches your Oracle version.
+
export ORACLE_BASE=/ora8/m01/app/oracle
+export ORACLE_HOME=$ORACLE_BASE/product/8.1.7
+export PATH=$PATH:$ORACLE_HOME/bin
+export LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib
+export ORACLE_SID=ora8
+export ORACLE_TERM=vt100
+export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data
Test this by logging out and back in as
+	service0 and checking the paths.
[service0@yourserver service0]$ exit
+logout
+[root@yourserver src]# su - service0
+[postgres@yourserver pgsql]$ env | grep PATH
+
For PostGreSQL, you should see:
+LD_LIBRARY_PATH=LD_LIBRARY_PATH=:/usr/local/pgsql/lib
+PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin/X11:/usr/X11R6/bin:/root/bin:/usr/local/pgsql/bin:/usr/local/pgsql/bin
For Oracle:
ORACLE_BASE=/ora8/m01/app/oracle
+ORACLE_HOME=/ora8/m01/app/oracle/product/8.1.7
+PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin/X11:/usr/X11R6/bin:/root/bin:/ora8/m01/app/oracle/product/8.1.7/bin
+LD_LIBRARY_PATH=/ora8/m01/app/oracle/product/8.1.7/lib:/lib:/usr/lib
+ORACLE_SID=ora8
+ORACLE_TERM=vt100
+ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data
[service0@yourserver service0]$ exit
+logout
+
+[root@yourserver root]#
Unpack the OpenACS tarball and rename it to service0.  Secure the directory so that only the owner can access it.  Check the permissions by listing the directory.
[root@yourserver root]# su - service0
+[service0@yourserver service0]$ cd /web
+[service0@yourserver web]$ tar xzf /tmp/openacs-5.0.0d.tgz
+[service0@yourserver web]$ mv openacs-5.0.0d service0
+[service0@yourserver web]$ chmod -R 700 service0
+[service0@yourserver web]$ ls -al
+total 3
+drwxrwx---    3 root     web          1024 Mar 29 16:41 .
+drwxr-xr-x   25 root     root         1024 Mar 29 16:24 ..
+drwx------    7 service0 web          1024 Jan  6 14:36 service0
+[service0@yourserver web]$ exit
+logout
+
+[root@yourserver root]#
+su - service0
+cd /web
+tar xzf /tmp/openacs-5.0.0d.tgz
+mv openacs-5.0.0d service0
+chmod -R 700 service0/
+exit
Create a user in the database matching the service name.
[root@yourserver root]# su - postgres
+[postgres@yourserver pgsql]$ createuser service0
+Shall the new user be allowed to create databases? (y/n) y
+Shall the new user be allowed to create more new users? (y/n) y
+CREATE USER
+[postgres@yourserver pgsql]$ exit
+logout
+
+[root@yourserver root]#
Create a database with the same name as our service name, service0.
[root@yourserver root]# su - service0
+[service0@yourserver service0]$ createdb -E UNICODE service0
+CREATE DATABASE
+[service0@yourserver service0]$
+su - service0
+createdb -E UNICODE service0
[service0@yourserver service0]$ exit
+logout
+
+[root@yourserver root]# 

+	  Kill any current running AOLserver processes and start a new
+	  one.  If you are using Oracle, rather than PostgreSQL, replace
+	  nsd-postgres with
+	  nsd-oracle).
If you want to use port 80, there are complications.
+	  First, Aolserver must be root to use system ports such as
+	  80, but refuses to run as root for security reasons.  Thus
+	  you must start as root and specify a non-root user ID and
+	  Group ID which Aolserver will switch to after claiming the
+	  port.  To do so, find the UID and GID of the
+	  service0 user via
+	  grep service0
+	  /etc/passwd and then put those numbers into
+	  the command line via -u
+	  501 -g
+	  502.  Second, if you are root then killall will affect all OpenACS services on the machine, so if there's more than one you'll have to do ps -auxw | grep
+	  nsd and selectively kill by job number.
[service0@yourserver etc]$ killall nsd
+nsd: no process killed
+[service0@yourserver service0]$ /usr/local/aolserver/bin/nsd-postgres -t /web/service0/etc/config.tcl
+[service0@yourserver service0]$ [08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: starting to read config file...
+[08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: finished reading config file.
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 -N -r1.14 -r1.15
--- openacs-4/packages/acs-core-docs/www/release-notes.html	28 Jun 2003 05:07:02 -0000	1.14
+++ openacs-4/packages/acs-core-docs/www/release-notes.html	20 Aug 2003 16:20:16 -0000	1.15
@@ -12,10 +12,10 @@
   

 	You may want to begin by reading our installation documentation for
 	Chapter�4.  Note that the Windows documentation is
-	not current for OpenACS 4.7.0d, but an alternative is to use John
+	not current for OpenACS 5.0.0d, but an alternative is to use John
 	Sequeira's Oasis VM
 	project.
   

 	After installation, the full documentation set can be found by visiting
 	http://[your-host]/doc.
-  
($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 -N -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/request-processor.html	28 Jun 2003 05:07:02 -0000	1.11
+++ openacs-4/packages/acs-core-docs/www/request-processor.html	20 Aug 2003 16:20:16 -0000	1.12
@@ -5,29 +5,29 @@
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
Overview

-This document is a brief introduction to the OpenACS 4.7.0d Request Processor;
+This document is a brief introduction to the OpenACS 5.0.0d Request Processor;
 more details can be found in the OpenACS 4 Request Processor Design. Here we cover the high level concepts behind the
 system, and implications and usage for the application developer.
 
Request Processor

-The 4.7.0d Request Processor is a global filter and set of Tcl procs that
+The 5.0.0d Request Processor is a global filter and set of Tcl procs that
 respond to every incoming URL reaching the server. The following
 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
 physical directory in the filesystem, from which to serve content.  We
 do this by searching the site map data model (touched on in the Packages, and further
-discussed in the section called “Writing OpenACS 4.7.0d Application Pages”). This data model maps URLs to objects representing
+discussed in the section called “Writing OpenACS 5.0.0d Application Pages”). This data model maps URLs to objects representing
 content, and these objects are typically package instances. 
 

 After looking up the appropriate object, the RP stores the URL, the ID
 of the object it found, and the package and package instance the
 object belongs to into the environment of the connection.  This
 environment can be queried using the ad_conn procedure,
-which is described in detail in OpenACS 4 Request Processor Design. The page
+which is described in detail in OpenACS 4 Request Processor Design. The page
 development tutorial shows you how to use this interface to make
 your pages aware of which instance was requested.
 
Stage 2: Authentication

@@ -38,7 +38,7 @@
 extracts or sets up new session tokens for the user.
 
Stage 3: Authorization

 Next, the Request Processor checks if the user has appropriate access
-privileges to the requested part of the site. In OpenACS 4.7.0d, access control
+privileges to the requested part of the site. In OpenACS 5.0.0d, access control
 is dictated by the permissions system. In
 this case, the RP checks if the user has "read" priviledges on the
 object in the site map specified by the URL. This object is typically
Index: openacs-4/packages/acs-core-docs/www/requirements-template.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/requirements-template.html,v
diff -u -N -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/requirements-template.html	28 Jun 2003 05:07:02 -0000	1.11
+++ openacs-4/packages/acs-core-docs/www/requirements-template.html	20 Aug 2003 16:20:16 -0000	1.12
@@ -61,7 +61,7 @@
 	  

       For guidelines writing requirements, take a 
       look
-	at the quality standards, along with a good example, such as OpenACS 4.7.0d Package Manager Requirements.
+	at the quality standards, along with a good example, such as OpenACS 5.0.0d Package Manager Requirements.
     

       Besides writing requirements in natural language, consider using the
       following techniques as needed:
@@ -81,4 +81,4 @@
 	pre-existing system or prototype first, and thus you may want to write
 	some thoughts on implementation, for aiding and guiding yourself or
 	other programmers.  
-    
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.3 Edited further, incorporated feedback from Michael Yoon 9/05/2000 Kai Wu
0.2 Edited 8/22/2000 Kai Wu
0.1 Created 8/21/2000 Josh Finkler, Audrey McLoghlin
($Id$)
Prev Home  Next
Detailed Design Documentation Template Up  Release Version Numbering
docs@openacs.org
View comments on this page at openacs.org
+    
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.3 Edited further, incorporated feedback from Michael Yoon 9/05/2000 Kai Wu
0.2 Edited 8/22/2000 Kai Wu
0.1 Created 8/21/2000 Josh Finkler, Audrey McLoghlin
($Id$)
Prev Home  Next
Detailed Design Documentation Template Up  Release Version Numbering
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/rp-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-design.html,v
diff -u -N -r1.10 -r1.11
--- openacs-4/packages/acs-core-docs/www/rp-design.html	28 Jun 2003 05:07:02 -0000	1.10
+++ openacs-4/packages/acs-core-docs/www/rp-design.html	20 Aug 2003 16:20:16 -0000	1.11
@@ -13,7 +13,7 @@
 connecting user, and make sure that he is authorized to perform the given
 request. If these steps succeed, then the request processor must locate the
 file that is associated with the specified URL, and serve the content it
-provides to the browser.
Related Systems
OpenACS 4.7.0d Package Manager Design
Terminology

+provides to the browser.
Related Systems
OpenACS 5.0.0d Package Manager Design
Terminology

 pageroot -- Any directory that contains scripts and/or
 static files intended to be served in response to HTTP requests. A typical
 OpenACS installation is required to serve files from multiple pageroots.
global pageroot
@@ -93,7 +93,7 @@
 the ad_conn procedure. The following variables are available for public use.
 If the ad_conn procedure doesn't recognize a variable being passed to it
 for a lookup, it tries to get a value using ns_conn. This guarantees that
-ad_conn subsumes the functionality of ns_conn.
Request processor
[ad_conn urlv] A list containing each element of the URL
[ad_conn url] The URL associated with the request.
[ad_conn file] The filepath including filename of the file being served
[ad_conn request] The number of requests since the server was last started
[ad_conn start_clicks] The system time when the RP starts handling the request
�
Session System Variables: set in
+ad_conn subsumes the functionality of ns_conn.
Request processor
[ad_conn urlv] A list containing each element of the URL
[ad_conn url] The URL associated with the request.
[ad_conn file] The filepath including filename of the file being served
[ad_conn request] The number of requests since the server was last started
[ad_conn start_clicks] The system time when the RP starts handling the request
�
Session System Variables: set in
 sec_handler, check security with ad_validate_security_info
[ad_conn session_id] The unique session_id coming from the sequence
 sec_id_seq
[ad_conn user_id] User_id of a person if the person is logged in. Otherwise, it is
 blank
[ad_conn sec_validated] This becomes "secure" when the connection uses SSL
�
Database API
[ad_conn db,handles] What are the list of handles available to AOL?
[ad_conn db,n_handles_used] How many database handles are currently used?
[ad_conn db,last_used] Which database handle did we use last?
[ad_conn db,transaction_level,$db] Specifies what transaction level we are in
[ad_conn db,db_abort_p,$dbh] Whether the transaction is aborted
�
APM
[ad_conn xml_loaded_p] Checks whether the XML parser is loaded so that it only gets loaded once.
Index: openacs-4/packages/acs-core-docs/www/security-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-design.html,v
diff -u -N -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/security-design.html	28 Jun 2003 05:07:02 -0000	1.11
+++ openacs-4/packages/acs-core-docs/www/security-design.html	20 Aug 2003 16:20:16 -0000	1.12
@@ -43,7 +43,7 @@
 for a secure authentication token. However, the basic architecture here lays
 the foundation for a secure system and can be easily adapted to a more secure
 authentication system by forcing all logins to occur over HTTPS.
Details
The authentication system issues up to four signed cookies (see below),
-with each cookie serving a different purpose. These cookies are:
name value max-age secure?
ad_session_id session_id,user_id SessionTimeout no
ad_user_login user_id Infinity no
ad_user_login_secure user_id,random Infinity yes
ad_secure_token session_id,user_id,random SessionLifetime yes
ad_session_id
reissued on any hit separated by more than SessionRenew seconds from the
+with each cookie serving a different purpose. These cookies are:
name value max-age secure?
ad_session_id session_id,user_id SessionTimeout no
ad_user_login user_id Infinity no
ad_user_login_secure user_id,random Infinity yes
ad_secure_token session_id,user_id,random SessionLifetime yes
ad_session_id
reissued on any hit separated by more than SessionRenew seconds from the
 previous hit that received a cookie
is valid only for SessionTimeout seconds
is the canonical source for the session ID in ad_conn
ad_user_login
is used for permanent logins
ad_user_login_secure
is used for permanent secure logins
contains random garbage (ns_time) to prevent attack against the secure
 hash
ad_secure_token
 
is a session-level cookie from the browser's standpoint
its signature expires in SessionLifetime seconds
contains random garbage (ns_time) to prevent attack against the secure
@@ -86,7 +86,7 @@
 immediately
nothing: if the cookie is present, it remains

 The current state of the permanent login cookies is not taken into account
 when determining the appropriate action. 
-
previous login state permanent login requested secure connection action on insecure action on secure
other y y set set
same y y set set
other y n set delete
same y n set nothing
same n y nothing delete
other n y delete delete
other n n delete delete
same n n delete delete
ad_user_login
+
previous login state permanent login requested secure connection action on insecure action on secure
other y y set set
same y y set set
other y n set delete
same y n set nothing
same n y nothing delete
other n y delete delete
other n n delete delete
same n n delete delete
ad_user_login
 callssec_setup_session which actually calls
 sec_generate_session_id_cookie to generate the
 new cookie with refer to the appropriate user_id. If the connection is secure
Index: openacs-4/packages/acs-core-docs/www/security-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-requirements.html,v
diff -u -N -r1.10 -r1.11
--- openacs-4/packages/acs-core-docs/www/security-requirements.html	28 Jun 2003 05:07:02 -0000	1.10
+++ openacs-4/packages/acs-core-docs/www/security-requirements.html	20 Aug 2003 16:20:17 -0000	1.11
@@ -1,5 +1,5 @@
 
-OpenACS 4 Security Requirements
Prev Chapter�13.�Kernel Documentation  Next
OpenACS 4 Security Requirements

+OpenACS 4 Security Requirements
Prev Chapter�13.�Kernel Documentation  Next
OpenACS 4 Security Requirements

 by Richard Li

           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
@@ -45,4 +45,4 @@
 AOLserver for each step of the login process (e.g., by a load balancer).
12.4 Secure The security system should not store
 passwords in clear text in the database.
13.0 SSL Hardware The system must work when the SSL
 processing occurs outside of the web server (in specialized hardware, in a
-firewall, etc.).
Prev Home  Next
Database Access API Up  OpenACS 4 Security Design
docs@openacs.org
View comments on this page at openacs.org
+firewall, etc.).
Prev Home  Next
Internationalization Up  OpenACS 4 Security Design
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/subsites-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-design.html,v
diff -u -N -r1.10 -r1.11
--- openacs-4/packages/acs-core-docs/www/subsites-design.html	28 Jun 2003 05:07:02 -0000	1.10
+++ openacs-4/packages/acs-core-docs/www/subsites-design.html	20 Aug 2003 16:20:17 -0000	1.11
@@ -1,5 +1,5 @@
 
-OpenACS 4 Subsites Design DocumentPrev Chapter�13.�Kernel Documentation  Next
OpenACS 4 Subsites Design Document

+OpenACS 4 Subsites Design Document
Prev Chapter�13.�Kernel Documentation  Next
OpenACS 4 Subsites Design Document

 by Rafael H. Schloming

           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
@@ -210,4 +210,4 @@
 a particular configuration of site nodes/packages. As we build more
 fundamental applications that can be applied in more general areas, this
 feature will become more and more in demand since more problems will be
-solvable by configuration instead of coding.
Authors
rhs@mit.edu
Prev Home  Next
OpenACS 4 Subsites Requirements Up  OpenACS 4.7.0d Package Manager Requirements
docs@openacs.org
View comments on this page at openacs.org
+solvable by configuration instead of coding.
Authors
rhs@mit.edu
Prev Home  Next
OpenACS 4 Subsites Requirements Up  OpenACS 5.0.0d Package Manager Requirements
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/subsites-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-requirements.html,v
diff -u -N -r1.10 -r1.11
--- openacs-4/packages/acs-core-docs/www/subsites-requirements.html	28 Jun 2003 05:07:03 -0000	1.10
+++ openacs-4/packages/acs-core-docs/www/subsites-requirements.html	20 Aug 2003 16:20:17 -0000	1.11
@@ -55,4 +55,4 @@
 package and make it available at a URL underneath the subsite.
20.20.0 Package deactivation
20.20.1 The administrator should be able to deactivate
 any package, causing it to be inaccessible to users.
20.20.5 Deactivating a package makes the package no
 longer accessible, but it does not remove data created within the context of
-that package.
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 08/18/2000 Dennis Gregorovic
0.2 Edited, reviewed 08/29/2000 Kai Wu
Prev Home  Next
OpenACS 4 Groups Design Up  OpenACS 4 Subsites Design Document
docs@openacs.org
View comments on this page at openacs.org
+that package.
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 08/18/2000 Dennis Gregorovic
0.2 Edited, reviewed 08/29/2000 Kai Wu
Prev Home  Next
OpenACS 4 Groups Design Up  OpenACS 4 Subsites Design Document
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/subsites.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites.html,v
diff -u -N -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/subsites.html	28 Jun 2003 05:07:03 -0000	1.11
+++ openacs-4/packages/acs-core-docs/www/subsites.html	20 Aug 2003 16:20:17 -0000	1.12
@@ -1,5 +1,5 @@
 
-Writing OpenACS 4.7.0d Application PagesPrev Chapter�11.�Development Reference  Next
Writing OpenACS 4.7.0d Application Pages

+Writing OpenACS 5.0.0d Application Pages
Prev Chapter�11.�Development Reference  Next
Writing OpenACS 5.0.0d Application Pages

 By Rafael H. Schloming 
 and Pete Su
 


@@ -8,15 +8,15 @@
         
Overview

 In this document, we'll examine the user interface pages of the Notes
 application in more detail, covering two separate aspects of page
-development in OpenACS 4.7.0d. First, we'll talk about the code needed to make
+development in OpenACS 5.0.0d. First, we'll talk about the code needed to make
 your pages aware of which application instance they are running
 in. Second, we'll talk about using the form builder to develop
-form-based user interfaces in OpenACS 4.7.0d. While these seem like unrelated
+form-based user interfaces in OpenACS 5.0.0d. While these seem like unrelated
 topics, they both come up in the example page that we are going to
 look at, so it makes sense to address them at the same time.
 
Application Instances and Subsites

-As you will recall from the packages tutorial, the Request
-Processor (RP) and Package Manager (APM) in OpenACS 4.7.0d allow site
+As you will recall from the packages tutorial, the Request
+Processor (RP) and Package Manager (APM) in OpenACS 5.0.0d allow site
 administrators to define an arbitrary mapping from URLs in the site to
 objects representing content. These objects may represent single
 files, or entire applications. The APM uses the site map to map
@@ -257,15 +257,15 @@
 visible to that user. The end result is a site where users can come
 and write notes to themselves.
 

-This is a good example of the leverage available in the OpenACS 4.7.0d
+This is a good example of the leverage available in the OpenACS 5.0.0d
 system. The code that we have written for Notes is not at all more
 complex than a similar application without access control or site map
 awareness. By adding a small amount of code, we have taken a small,
 simple, and special purpose application to something that has the
 potential to be a very useful, general-purpose tool, complete with
 multi-user features, access control, and centralized administration.
 
Summary

-In OpenACS 4.7.0d, application pages and scripts can be aware of the package
+In OpenACS 5.0.0d, application pages and scripts can be aware of the package
 instance, or subsite in which they are executing. This is a powerful
 general purpose mechanism that can be used to structure web services
 in very flexible ways.
@@ -277,4 +277,4 @@
 

 We also saw how to use the templating system's forms API in a simple
 way, to create forms based pages with minimal duplication of code.
-
($Id$)
Prev Home  Next
Groups, Context, Permissions Up  Parties in OpenACS 4.7.0d
docs@openacs.org
View comments on this page at openacs.org
+
($Id$)
Prev Home  Next
Groups, Context, Permissions Up  Parties in OpenACS 5.0.0d
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/templates.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/templates.html,v
diff -u -N -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/templates.html	28 Jun 2003 05:07:03 -0000	1.11
+++ openacs-4/packages/acs-core-docs/www/templates.html	20 Aug 2003 16:20:17 -0000	1.12
@@ -1,9 +1,9 @@
 
-Using Templates in OpenACS 4.7.0dPrev Chapter�11.�Development Reference  Next
Using Templates in OpenACS 4.7.0d
By Pete Su


+Using Templates in OpenACS 5.0.0dPrev Chapter�11.�Development Reference  Next
Using Templates in OpenACS 5.0.0d
By Pete Su


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

-The OpenACS 4.7.0d Template System (ATS) is designed to allow developers to
+The OpenACS 5.0.0d Template System (ATS) is designed to allow developers to
 cleanly separate application logic from display
 logic. The intent is to have all of the logic related to
 manipulating the database and other application state data in one
@@ -160,7 +160,7 @@
 
Summary

 Templates separate application logic from display logic by requiring
 the developer to write pages in two stages, one file for database
-queries and application logic, and another for display. In OpenACS 4.7.0d, the
+queries and application logic, and another for display. In OpenACS 5.0.0d, the
 logic part of the page is just a .tcl that sets up
 data sources that are used by the display part of the page. The
 display part of the page is an .adp file with some
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 -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/tutorial-advanced.html	28 Jun 2003 05:07:03 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/tutorial-advanced.html	20 Aug 2003 16:20:17 -0000	1.4
@@ -3,15 +3,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 
APM package dependencies
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.
 
@@ -71,7 +71,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
@@ -92,13 +92,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 -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/tutorial-database.html	28 Jun 2003 05:07:03 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/tutorial-database.html	20 Aug 2003 16:20:17 -0000	1.4
@@ -3,7 +3,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
@@ -40,7 +40,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
@@ -50,7 +50,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
@@ -93,7 +93,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
@@ -188,7 +188,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 -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/tutorial-debug.html	28 Jun 2003 05:07:03 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/tutorial-debug.html	20 Aug 2003 16:20:17 -0000	1.4
@@ -3,7 +3,7 @@
     by Joel Aufrecht

           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Debugging
PostgreSQL.�You can work directly with the database to do debugging
+        
Debugging
PostgreSQL.�You can work directly with the database to do debugging
           steps like looking directly at tables and testing stored
           procedures.  Start emacs.  Type
             M-x sql-postgres.  Press enter for
@@ -19,10 +19,10 @@
 ?�searches�backward�

 /�searches�forward.�

 ����������

-        
Manual testing
Make a list of basic tests to make sure it works

+       
+         Document Revision #
+         Action Taken, Notes
+         When?
+         By Whom?
+      
+
+      
+        1
+        Updated work-in-progress for consortium-sponsored ext-auth work at Collaboraid.
+        20 Aug 2003
+        Joel Aufrecht
+      
+        
+      
+    
+  
+  
+
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/groups-design.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/groups-design.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/kernel/groups-design.xml	10 Aug 2002 19:34:42 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/groups-design.xml	20 Aug 2003 16:20:19 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 OpenACS 4 Groups Design
 
@@ -733,8 +739,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/groups-requirements.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/groups-requirements.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/kernel/groups-requirements.xml	10 Aug 2002 19:34:42 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/groups-requirements.xml	20 Aug 2003 16:20:19 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 OpenACS 4 Groups Requirements
 
@@ -701,8 +707,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/i18n-requirements.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/i18n-requirements.xml,v
diff -u -N -r1.1 -r1.2
--- openacs-4/packages/acs-core-docs/www/xml/kernel/i18n-requirements.xml	1 Oct 2002 09:42:47 -0000	1.1
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/i18n-requirements.xml	20 Aug 2003 16:20:19 -0000	1.2
@@ -1,5 +1,11 @@
+
+
+%myvars;
+]>
 
-  OpenACS &version; Internationalization Requirements
+  OpenACS Internationalization Requirements
 
   
       by Henry Minsky, 
@@ -96,8 +102,8 @@
 and family names for people, syntax of numeric and date strings and
 collation order of strings.
 
-The ACS should be able to operate in languages and regions
-beyond US English. The goal of ACS Globalization is to provide a
+The OpenACS should be able to operate in languages and regions
+beyond US English. The goal of OpenACS Globalization is to provide a
 clean and efficient way to factor out the locale dependent
 functionality from our applications, in order to be able to easily
 swap in alternate localizations.
@@ -106,7 +112,7 @@
 rework when targeting the toolkit or applications built with the
 toolkit to another locale.
 
-The cost of porting the ACS to another locale without some
+The cost of porting the OpenACS to another locale without some
 kind of globalization support would be large and ongoing, since
 without a mechanism to incorporate the locale-specific changes
 cleanly back into the code base, it would require making a new fork
@@ -185,7 +191,7 @@
 Java which we will want to move to. So the design to meet the
 requirements will tend to rely on these capabilities, or close
 approximations to them where possible, in order to make it easier
-to maintain Tcl and Java ACS versions.
+to maintain Tcl and Java OpenACS versions.
 
 Use-cases and User-scenarios
 
@@ -196,14 +202,14 @@
 
 A developer needs to author a web site/application in a
 language besides English, and possibly a character set besides
-ISO-8859-1. This includes the operation of the ACS itself, i.e.,
+ISO-8859-1. This includes the operation of the OpenACS itself, i.e.,
 navigation, admin pages for modules, error messages, as well as
 additional modules or content supplied by the web site
 developer.
 
 What do they need to modify to make this work? Can their
 localization work be easily folded in to future releases of
-ACS?
+OpenACS?
 
 
 
@@ -245,24 +251,25 @@
 documentation for this software is linked off of
 
 
-
-Design document
-
-
-
-Developer's guide
-
-
-
-User's guide
-
-
-
-Other-cool-system-related-to-this-one
-documentLI18NUX
+      
+        Design document
+      
+      
+      
+        Developer's guide
+      
+      
+      
+        User's guide
+      
+      
+      
+        Other-cool-system-related-to-this-one
+document
+LI18NUX
 2000 Globalization Specification:
 http://www.li18nux.net/
-
+        
 Mozilla
 i18N Guidelines:
 http://www.mozilla.org/docs/refList/i18n/l12yGuidelines.html
@@ -318,7 +325,15 @@
 already.
 
 10.30 For each locale there will be
-default date, number and currency formats.
+default date, number and currency formats. Currency i18n is
+NOT IMPLEMENTED for 5.0.0.
+
+      10.40Administrators can upgrade their
+servers to use new locales via the APM. NOT IMPLEMENTED in
+5.0.0; current workaround is to get an xml file and load it
+manually.
+
+
 
 
 Associating a Locale with a Request
@@ -424,11 +439,6 @@
 efficient as possible so as not to slow down the delivery of
 pages.
 
-Design question: Is there any reason to implement
-the message catalog on top of the content repository as the
-underlying storage and retrieval service, with a layer of caching
-for performance? Would we get a nice user interface and version
-control almost for free?
 
 
 Character Set Encoding
@@ -470,25 +480,20 @@
 Writing data to the filesystem
 
 
+Acs-templating does the following.
+
+        
+          When the acs-templating package opens an an ADP or TCL file, it assumes the file is iso-8859-1.  If the output charset (OutputCharset) in the AOLserver config file is set, then acs-templating assumes it's that charset.  
+Writing Files
+        
+        
+          When the acs-templating package writes an an ADP or
+          TCL file, it assumes the file is iso-8859-1.  If the output
+          charset (OutputCharset) in the AOLserver config file is set,
+          then acs-templating assumes it's that charset.  
+        
+      
 
-Design question: Do we want to mandate that all
-template files be stored in UTF8? I don't think so, because
-most people don't have Unicode editors, or don't want to be
-bothered with an extra step to convert files to UTF8 and back when
-editing them in their favorite editor.
-
-Same question for script and template files, how do
-we know what language and character set they are authored in?
-Should we overload the filename suffix (e.g.,
-'.shiftjis.adp',
-'.ja_JP.euc.adp')?
-
-The simplest design is probably just to assign a
-default mapping from each locale to character a set: e.g. ja_JP
--> ShiftJIS, fr_FR -> ISO-8859-1. +++ (see new ACS/Java
-notes) +++
-
-
   
     Tcl Source File Character Set
     
@@ -518,13 +523,18 @@
       50.30 Data which is submitted with a
          HTTP request using a GET or POST method may be in any character
          set. The system must be able to determine the encoding of the form
-         data and convert it to Unicode on demand.
+         data and convert it to Unicode on demand.  
 
         50.35 The developer must be able to
           override the default system choice of character set when parsing
-          and validating user form data.
+          and validating user form data. INCOMPLETE - form
+          widgets in acs-templating/tcl/date-procs.tcl are not
+          internationalized.  Also, acs-templating's UI needs to be
+          internationalized by replacing all user-visible strings with
+          message keys.
 
-       50.30.10 Extra hair: In Japan and some
+
+       50.30.10In Japan and some
            other Asian languages where there are multiple character set
            encodings in common use, the server may need to attempt to do an 
            auto-detection of the character set, because buggy browsers may
@@ -552,9 +562,9 @@
 ACS Kernel Issues
 
 
-60.10 All ACS error messages must use
+60.10 All OpenACS error messages must use
 the message catalog and the request locale to generate error
-message for the appropriate locale.
+message for the appropriate locale.NOT IMPLEMENTED for 5.0.0.
 
 60.20 Web server error messages such as
 404, 500, etc must also be delivered in the appropriate
@@ -577,10 +587,6 @@
 template file to use. The request locale is computed as per (see
 requirement 20.0).
 
-Design note: this would probably be implemented by
-suffixing the locale or a locale abbreviation to the template
-filename, such as foo.ja.adp or foo.en_GB.adp.
-
 70.20A template file may be created for
 a partial locale (language only, without a territory), and the
 request processor should be able to find the closest match for the
@@ -597,7 +603,7 @@
 70.50 The properties of a datasource
 column may include a datatype so that the templating system can
 format the output for the current locale. The datatype is defined
-by a standard ACS datatype plus a format token or format string,
+by a standard OpenACS datatype plus a format token or format string,
 for example: a date column might be specified as
 'current_date:date LONG,' or 'current_date:date
 "YYYY-Mon-DD"'
@@ -608,7 +614,8 @@
 70.60 The forms API must support
 construction of locale-specific HTML form widgets, such as date
 entry widgets, and form validation of user input data for
-locale-specific data, such as dates or numbers.
+locale-specific data, such as dates or numbers.  NOT
+IMPLEMENTED in 5.0.0.
 
 70.70 For forms which allow users to
 upload files, a standard method for a user to indicate the charset
@@ -669,15 +676,17 @@
 three (UCS2) or six (UCS4) bytes per character, make sure that
 column size declarations in the schema are large enough to
 accomodate required data (such as email addresses in
-Japanese).
+Japanese).  Since 5.0.0, this is covered in the database
+install instructions for both PostGreSQL and Oracle.
 
 
 Email and
 Messaging
 
 When sending an email message, just as when delivering the
 content in web page over an HTTP connection, it is necessary to be
-able to specify what character set encoding to use.
+able to specify what character set encoding to use.
+
 
 
 110.10 The email message sending API
@@ -688,6 +697,38 @@
 formatted message will have a MIME character set content type header) 
 
 
+    Mail is not internationalized.  The following issues
+must be addressed.
+    
+      
+        Six different functions currently call ns_sendmail.  This
+        means that there are six different end points for sending
+        mail.  This should be brought down to no more than two (one
+        for acs_mail and one for acs_mail_lite), and ideally just
+        one.  Functions that currently call ns_sendmail directly
+        should instead call acs_mail_lite.
+      
+      
+        Outgoing email functions (acs_mail and acs_mail_lite) must do
+        the following: 1) Determine the appropriate language or
+        languages to use for the message subject and message body.  2)
+        Encode the subject and body appropriately and set message
+        headers, in accordance with RFC 3282
+        (http://www.ietf.org/rfc/rfc3282.txt) and other RFCs.
+
+      
+      
+        Extreme Use case: Web site has a default language of Danish.  A forum is set up for Swedes, so the forum has a package_id and a language setting of Swedish.  A poster posts to the forum in Russian (is this possible?).  A user is subscribed to the forum and has a language preference of Chinese.  What should be in the message body and message subject?
+INCOMPLETE - The mail functions in acs_mail and acs_mail_lite
+are not internationalized.
+      
+      Incoming mail should be localized.
+      
+    
+
+
+
+
 
 
   Implementation Notes
@@ -712,6 +753,13 @@
       
 
       
+        1
+        Updated with results of MIT-sponsored i18n work at Collaboraid.
+        14 Aug 2003
+        Joel Aufrecht
+      
+
+      
         0.4
         converting from HTML to DocBook and importing the document to the OpenACS
                kernel documents. This was done as a part of the internationalization of
@@ -748,3 +796,5 @@
 
 
 
+
+
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/object-system-design.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/object-system-design.xml,v
diff -u -N -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/xml/kernel/object-system-design.xml	10 Aug 2002 19:34:42 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/object-system-design.xml	20 Aug 2003 16:20:19 -0000	1.5
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 OpenACS 4 Object Model Design
 
@@ -1515,8 +1521,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/object-system-req.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/object-system-req.xml,v
diff -u -N -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/xml/kernel/object-system-req.xml	10 Aug 2002 19:34:42 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/object-system-req.xml	20 Aug 2003 16:20:19 -0000	1.5
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 OpenACS 4 Object Model Requirements
 
@@ -807,8 +813,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-design.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-design.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-design.xml	10 Aug 2002 19:34:42 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-design.xml	20 Aug 2003 16:20:19 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 OpenACS 4 Permissions Design
 
@@ -496,8 +502,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-requirements.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-requirements.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-requirements.xml	10 Aug 2002 19:34:42 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-requirements.xml	20 Aug 2003 16:20:19 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 OpenACS 4 Permissions Requirements
 
@@ -284,8 +290,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/rp-design.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/rp-design.xml,v
diff -u -N -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/xml/kernel/rp-design.xml	10 Aug 2002 19:34:42 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/rp-design.xml	20 Aug 2003 16:20:19 -0000	1.5
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 OpenACS 4 Request Processor Design
 
@@ -374,8 +380,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/rp-requirements.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/rp-requirements.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/kernel/rp-requirements.xml	10 Aug 2002 19:34:42 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/rp-requirements.xml	20 Aug 2003 16:20:19 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 OpenACS 4 Request Processor Requirements
 
@@ -127,8 +133,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/security-design.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/security-design.xml,v
diff -u -N -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/xml/kernel/security-design.xml	10 Aug 2002 19:34:42 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/security-design.xml	20 Aug 2003 16:20:19 -0000	1.5
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 OpenACS 4 Security Design
 
@@ -878,8 +884,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/security-notes.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/security-notes.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/kernel/security-notes.xml	10 Aug 2002 19:34:42 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/security-notes.xml	20 Aug 2003 16:20:19 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 OpenACS 4 Security Notes
 
@@ -89,8 +95,3 @@
 ($Id$)
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/security-requirements.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/security-requirements.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/kernel/security-requirements.xml	10 Aug 2002 19:34:42 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/security-requirements.xml	20 Aug 2003 16:20:19 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 OpenACS 4 Security Requirements
 
@@ -112,8 +118,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/subsites-design.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/subsites-design.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/kernel/subsites-design.xml	10 Aug 2002 19:34:42 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/subsites-design.xml	20 Aug 2003 16:20:19 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 OpenACS 4 Subsites Design Document
 
@@ -367,8 +373,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/subsites-requirements.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/subsites-requirements.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/kernel/subsites-requirements.xml	10 Aug 2002 19:34:42 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/subsites-requirements.xml	20 Aug 2003 16:20:19 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 OpenACS 4 Subsites Requirements
 
@@ -225,8 +231,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/tcl-doc.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/tcl-doc.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/kernel/tcl-doc.xml	10 Aug 2002 19:34:42 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/tcl-doc.xml	20 Aug 2003 16:20:19 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 Documenting Tcl Files: Page Contracts and Libraries
 
@@ -344,8 +350,3 @@
 ($Id$)
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/non-xml/release-notes-4-5.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/non-xml/release-notes-4-5.html,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-core-docs/www/xml/non-xml/release-notes-4-5.html	20 Aug 2003 16:20:19 -0000	1.1
@@ -0,0 +1,173 @@
+
+
+
+
+
+
+OpenACS 4.5 Release Notes
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+OpenACS 4.5 Release Notes
+
+
+
+
+
+	  by 
+Don Baccus
+ and
+	  
+Vinod Kurup
+
+

+		  OpenACS docs are written by the named authors, but may be edited
+		  by OpenACS documentation staff.
+		
+
+
+
+	This is the official OpenACS 4.5 release.  This release has been subjected
+	to an organized test effort, but please bear in mind that we are still
+	in the process of developing testing tools, methodology, and scripts.
+  
+
+
+	Please report bugs using our
+	
+
+	  Software Development Manager
+ at the 
+OpenACS website
+.  The latest
+	information on installing this alpha release under Oracle 8.1.6/7
+	or PostgreSQL 7.1.* can be found there as well.  Currently the
+	toolkit will not install under Oracle 9i due to Oracle having made
+	"delete" an illegal name for PL/SQL procedures and functions.
+  
+
+
+        Some users have reported success running OpenACS 4.5 under PostgreSQL 7.2, but
+        there may still be some undetected problems with this platform.
+  
+
+
+	You may want to begin by reading our installation documentation for
+	
+Installing on Unix/Linux
+ or 
+Installing on Windows
+.  Note
+	that the Windows documentation is not current for OpenACS 4.5,
+	but an alternative is to use John Sequeira's 
+Oasis VM
+	project
+.
+  
+
+
+	After installation, the full documentation set can be found by visiting
+	http://[your-host]/doc. Not all pieces are updated for OpenACS 4.5 at
+	this moment.
+  
+
+
+
+
+
+
+Site Wide Searching
+
+
+
+
+	  If you're using Oracle 8.1.6 or 8.1.7 Enterprise Edition you may want
+	  to uncomment the SQL that causes InterMedia to keep online searching
+	  online while indexing.  The feature doesn't exist in Standard Edition
+	  and OpenACS 4.5 now defaults to being loadable in SE.  Just grep for
+	  'sync' to find the code.  
+	
+
+
+	  Also be sure to read the documentation in the Site Wide Search
+	  package's sql/oracle directory.  The APM doesn't execute the SQL for
+	  this package, in part due to the fact that some steps need to be run
+	  as the Oracle user 'ctxsys'.
+	
+
+
+	  If you're using PostgreSQL be sure to read the documentation on
+	  installing the Open FTS driver for OpenACS.  It's included in the
+	  package as a text file and is also summarized at the end of the
+	  installation documentation in the section, 
+Set Up OpenFTS
+.  As with the Oracle version, there
+	  are steps you must take manually in order to get this feature
+	  working.
+	
+
+
+
+
+
+
+
+Testing Notes
+
+
+
+
+
+

+We now maintain our
+
+test results
+
+using a custom OpenACS 4.5 package developed by
+
+OpenMSG
+.   As can be seen from the notes, there are
+still some serious outstanding bugs in this release.   If you don't like this state of affairs consider
+volunteering to help out.  Just drop the 
+project manager
+ a
+quick note and you'll be signed up more quickly than you can say "wait! I've changed my mind!"
+	
+
+
+
+
($Id: release-notes-4-5.html,v 1.1 2003/08/20 16:20:19 joela Exp $)
+
+
+
+
+
+
+rmello at fslc.usu.edu
+
+
+
+			vinod@kurup.com
+		  
+
+
+
+
+
Index: openacs-4/packages/acs-core-docs/www/xml/non-xml/release-notes-4-6-2.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/non-xml/release-notes-4-6-2.html,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-core-docs/www/xml/non-xml/release-notes-4-6-2.html	20 Aug 2003 16:20:19 -0000	1.1
@@ -0,0 +1,67 @@
+
+OpenACS 4.6.2 Release Notes4.6.x DRAFT IN PROGRESS
OpenACS 4.6.2 Release Notes

+	  by Don Baccus

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

+	This is a final release of OpenACS 4.6.2.  This release has been subjected
+	to an organized test effort, but please bear in mind that we are still
+	in the process of developing testing tools, methodology, and scripts.
+  

+	Please report bugs using our
+	
+	  Bug Tracker at the OpenACS website.   This version
+        of the OpenACS Toolkit supports PostgreSQL 7.2.3 and 7.3.2, and
+        Oracle 8i.  It will not work with Oracle 9i (support is planned for
+        OpenACS 4.7.)
+  

+        Upgrading from OpenACS 4.6.1
+  

+        OpenACS 4.6.2 includes key datamodel changes to acs-kernel and other
+        packages.  Your first step after downloading OpenACS 4.6.2 and restarting
+        AOLserver should be to visit the Package Manager, click on the "install
+        packages" link, and select the checkbox to upgrade acs-kernel.  After
+        acs-kernel has been upgraded, return to the "install packages" page and
+        select the checkboxes for all other packages you have installed that
+        need upgrading (they are marked "upgrade" rather than "new install") and
+        perform the upgrade step.
+  

+        After packages have been upgraded, your installation should run without
+        problems.
+  

+	You may want to begin by reading our installation documentation for
+	Chapter 3.  Note that the Windows documentation is
+	not current for OpenACS 4.6.2, but an alternative is to use John
+	Sequeira's Oasis VM
+	project.
+  

+	After installation, the full documentation set can be found by visiting
+	http://[your-host]/doc. Not all pieces are updated for OpenACS 4.6.2 at
+	this moment.
+  
Site Wide Searching

+	  If you're using Oracle 8.1.6 or 8.1.7 Enterprise Edition you may want
+	  to uncomment the SQL that causes InterMedia to keep online searching
+	  online while indexing.  The feature doesn't exist in Standard Edition
+	  and OpenACS 4.6.2 now defaults to being loadable in SE.  Just grep for
+	  'sync' to find the code.  
+	

+	  Also be sure to read the documentation in the Site Wide Search
+	  package's sql/oracle directory.  The APM doesn't execute the SQL for
+	  this package, in part due to the fact that some steps need to be run
+	  as the Oracle user 'ctxsys'.
+	

+	  If you're using PostgreSQL be sure to read the documentation on
+	  installing the Open FTS driver for OpenACS.  It's included in the
+	  package as a text file and is also summarized at the end of the
+	  installation documentation in the section, 4.  As with the Oracle version, there
+	  are steps you must take manually in order to get this feature
+	  working.
+	
Testing Notes

+
+	  OpenMSG has organized the
+	  OpenACS 4.6.2 testing process with test servers provided by
+	  Hub.org. Visit the acceptance test server to
+	  see the current status of various packages. This may not be a
+	  permanent link. If it's not working, do a search of the OpenACS forums.
+
+    
($Id: release-notes-4-6-2.html,v 1.1 2003/08/20 16:20:19 joela Exp $)
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/xml/non-xml/release-notes-4-6-3.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/non-xml/release-notes-4-6-3.html,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-core-docs/www/xml/non-xml/release-notes-4-6-3.html	20 Aug 2003 16:20:19 -0000	1.1
@@ -0,0 +1,181 @@
+
+
+
+
+
+
+OpenACS 4.6.3 Release Notes
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+OpenACS 4.6.3 Release Notes
+
+
+
+
+
+	  by 
+Don Baccus
+
+

+          OpenACS docs are written by the named authors, and may be edited
+          by OpenACS documentation staff.
+        
+
+
+
+	This is a final release of OpenACS 4.6.3.  This release has been subjected
+	to an organized test effort, but please bear in mind that we are still
+	in the process of developing testing tools, methodology, and scripts.
+  
+
+
+	Please report bugs using our
+	
+
+	  Bug Tracker
+ at the 
+OpenACS website
+.   This version
+        of the OpenACS Toolkit supports PostgreSQL 7.2.3 and 7.3.2, and
+        Oracle 8i.  It will not work with Oracle 9i (support is planned for
+        OpenACS 4.7.)
+  
+
+
+        
+
+Upgrading from OpenACS 4.x
+
+
+  
+
+
+        OpenACS 4.6.3 includes key datamodel changes to acs-kernel and other
+        packages.  Your first step after downloading OpenACS 4.6.3 and restarting
+        AOLserver should be to visit the Package Manager, click on the "install
+        packages" link, and select the checkbox to upgrade acs-kernel.  After
+        acs-kernel has been upgraded, return to the "install packages" page and
+        select the checkboxes for all other packages you have installed that
+        need upgrading (they are marked "upgrade" rather than "new install") and
+        perform the upgrade step.
+  
+
+
+        After packages have been upgraded, your installation should run without
+        problems.
+  
+
+	Upgrade Instructions
+
+
+	You may want to begin by reading our installation documentation for
+	
+Unix, Windows, and Mac OS X.
+  
+
+
+	After installation, the full documentation set can be found by visiting
+	http://[your-host]/doc. Installation and maintenance documents are current for 4.6.3 but other documentation may lag behind.
+  
+
+
+
+
+
+
+Site Wide Searching
+
+
+
+
+	  If you're using Oracle 8.1.6 or 8.1.7 Enterprise Edition you may want
+	  to uncomment the SQL that causes InterMedia to keep online searching
+	  online while indexing.  The feature doesn't exist in Standard Edition
+	  and OpenACS 4.6.3 now defaults to being loadable in SE.  Just grep for
+	  'sync' to find the code.  
+	
+
+
+	  Also be sure to read the documentation in the Site Wide Search
+	  package's sql/oracle directory.  The APM doesn't execute the SQL for
+	  this package, in part due to the fact that some steps need to be run
+	  as the Oracle user 'ctxsys'.
+	
+
+
+	  If you're using PostgreSQL be sure to read the documentation on
+	  installing the Open FTS driver for OpenACS.  It's included in the
+	  package as a text file and is also summarized at the end of the
+	  installation documentation in the section, 
+4
+.  As with the Oracle version, there
+	  are steps you must take manually in order to get this feature
+	  working.
+	
+
+
+
+
+
+
+
+Testing Notes
+
+
+
+
+          dotLRN 1.0 is an e-learning solution
+          from MIT based on OpenACS 4.6.3 
+          The 
+dotLRN 1.0
+          testing effort
+ was organized by Bart
+          Teeuwisse and made use of 
+the OpenACS Bug
+          Tracker
+ and 
+OpenACS test
+          servers
+ hosted by 
+Collaboraid
+.
+        
+
+
+($Id: release-notes-4-6-3.html,v 1.1 2003/08/20 16:20:19 joela Exp $)
+
+
+
+
+
+
+docs@openacs.org
+
+
+
+
+
+
+View comments on this page at openacs.org
+
+
+
+
Index: openacs-4/packages/acs-core-docs/www/xml/non-xml/release-notes-4-6.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/non-xml/release-notes-4-6.html,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-core-docs/www/xml/non-xml/release-notes-4-6.html	20 Aug 2003 16:20:19 -0000	1.1
@@ -0,0 +1,206 @@
+
+OpenACS 4.6 Release Notes
OpenACS 4.6 Release Notes

+	  by Don Baccus

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

+	This is a final release of OpenACS 4.6.  This release has been subjected
+	to an organized test effort, but please bear in mind that we are still
+	in the process of developing testing tools, methodology, and scripts.
+  

+	Please report bugs using our
+	
+	  Software Development Manager at the OpenACS website.  The latest
+	information on installing this release under Oracle 8.1.6/7
+	or PostgreSQL 7.1.* can be found there as well.  Currently the
+	toolkit will not install under Oracle 9i due to Oracle having made
+	"delete" an illegal name for PL/SQL procedures and functions.
+  

+	You may want to begin by reading our installation documentation for
+	Installing on Unix/Linux or Installing on Windows.  Note
+	that the Windows documentation is not current for OpenACS 4.6,
+	but an alternative is to use John Sequeira's Oasis VM
+	project.
+  

+	After installation, the full documentation set can be found by visiting
+	http://[your-host]/doc. Not all pieces are updated for OpenACS 4.6 at
+	this moment.
+  
Site Wide Searching

+	  If you're using Oracle 8.1.6 or 8.1.7 Enterprise Edition you may want
+	  to uncomment the SQL that causes InterMedia to keep online searching
+	  online while indexing.  The feature doesn't exist in Standard Edition
+	  and OpenACS 4.6 now defaults to being loadable in SE.  Just grep for
+	  'sync' to find the code.  
+	

+	  Also be sure to read the documentation in the Site Wide Search
+	  package's sql/oracle directory.  The APM doesn't execute the SQL for
+	  this package, in part due to the fact that some steps need to be run
+	  as the Oracle user 'ctxsys'.
+	

+	  If you're using PostgreSQL be sure to read the documentation on
+	  installing the Open FTS driver for OpenACS.  It's included in the
+	  package as a text file and is also summarized at the end of the
+	  installation documentation in the section, Set Up OpenFTS.  As with the Oracle version, there
+	  are steps you must take manually in order to get this feature
+	  working.
+	
Testing Notes

+	  Here are some notes from our testing group.  While not quite up to
+	  date it should give you some ideas of where things stand.
+	
+ Summarised Testing Status
+
+Skin
+Minimal
+Release w/caution
+Comments:
+
+Package: Page
+Test Coverage: Minimal
+Release w/caution
+Comments:
+
+Package: Bboard
+Test Coverage: Reasonable
+Suggested Status: Alpha
+Comments:
+
+Package: Static Pages
+Test Coverage: Minimal
+Suggested Status: Release w/caution
+Comments:
+
+Package: Ticket Tracker
+Test Coverage: Reasonable
+Suggested Status: Alpha
+Comments: Don tested personally
+
+Package: Ticket Tracker Lite
+Test Coverage: Unknown
+Suggested Status: 
+Comments:
+
+Package: Acs-lang
+Test Coverage: Reasonable
+Suggested Status: Alpha
+Comments: Oracle only
+
+Package: Simple-survey
+Test Coverage: Reasonable
+Suggested Status: Alpha
+Comments:
+
+Package: Portal
+Test Coverage: Extensive
+Suggested Status: Alpha
+Comments:
+
+Package: Notes
+Test Coverage: Extensive
+Suggested Status: Alpha
+Comments:
+
+Package: Bookmarks
+Test Coverage: Extensive
+Suggested Status: Alpha
+Comments:
+
+Package: Clickthrough
+Test Coverage: Extensive
+Suggested Status: Alpha
+Comments:
+
+Package: Acs-mail
+Test Coverage: Reasonable
+Suggested Status: Release w/caution
+Comments:
+
+Package: Acs-messaging
+Test Coverage: Reasonable
+Suggested Status: Release w/caution
+Comments:
+
+Package: File manager
+Test Coverage: Minimal
+Suggested Status: Release w/caution
+Comments:
+
+Package: File Storage
+Test Coverage: Minimal
+Suggested Status: Release w/caution
+Comments:
+
+Package: Site-wide-search
+Test Coverage: Minimal
+Suggested Status: Release w/caution
+Comments:
+
+Package: General Comments
+Test Coverage: Extensive
+Suggested Status: Alpha
+Comments:
+
+Package: Acs-events
+Test Coverage: None
+Suggested Status: 
+Comments: Automated Testing
+
+Package: Acs-datetime
+Test Coverage: None
+Suggested Status: 
+Comments: Automated Testing
+
+Package: Acs-tcl
+Test Coverage: Reasonable
+Suggested Status: Release w/caution
+Comments: Automated Testing
+
+Package: Acs-templating
+Test Coverage: Reasonable
+Suggested Status: Release w/caution
+Comments: Automated Testing
+
+Package: Acs-util
+Test Coverage: Reasonable
+Suggested Status: Release w/caution
+Comments: Automated Testing
+
+Package: Acs-Content-repository
+Test Coverage: Minimal
+Suggested Status: Release w/caution
+Comments: Automated Testing
+
+Package: Acs-content
+Test Coverage: Minimal
+Suggested Status: Release w/caution
+Comments: Automated Testing
+
+Package: Acs-kernel
+Test Coverage: Reasonable
+Suggested Status: Alpha
+Comments: Automated Testing
+
+Package: Acs-subsite
+Test Coverage: Reasonable
+Suggested Status: Alpha
+Comments: 
+
+Package: Acs-bootstrap-installer
+Test Coverage: Extensive
+Suggested Status: Alpha
+Comments: Developers have used this extensively
+
+Package: Acs-api-browser
+Test Coverage: Minimal
+Suggested Status: Release w/caution
+Comments: Automated Testing
+
+Package: Acs-workflow
+Test Coverage: Minimal
+Suggested Status: Release w/caution
+Comments: 
+
+Package: calendar
+Test Coverage: Minimal
+Suggested Status: Alpha
+Comments: Don tested personally
+	
($Id: release-notes-4-6.html,v 1.1 2003/08/20 16:20:19 joela Exp $)
rmello at fslc.usu.edu
vinod@kurup.com
View comments on this page at openacs.org
Test Num Action Expected Result
001 Browse to the index page while not logged in and
+        
Manual testing
Make a list of basic tests to make sure it works
Test Num Action Expected Result
001 Browse to the index page while not logged in and
             while one or more notes exist. No edit or delete or add links should appear.
002 Browse 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
(Forthcoming.)
Prev Home  Next
Creating Web Pages Up  Advanced Topics
docs@openacs.org
View comments on this page at openacs.org
+        Search for a note.
Write automated tests
(Forthcoming.)
Prev Home  Next
Creating Web Pages Up  Advanced Topics
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html	28 Jun 2003 05:07:03 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html	20 Aug 2003 16:20:17 -0000	1.4
@@ -3,19 +3,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 4.7.0d distribution.
-	  
Figure�10.1.�Assumptions in this section
Fully qualified domain name of your server yourserver.test
URL of your server http://yourserver.test:8000
Name of development account service0
New Package key samplenote
Use the APM to initialize a new package
We use the ACS Package Manager (APM) to add, remove, and
+standard OpenACS 5.0.0d distribution.
+	  
Figure�10.1.�Assumptions in this section
Fully qualified domain name of your server yourserver.test
URL of your server http://yourserver.test:8000
Name of development account service0
New Package key samplenote
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
@@ -43,7 +43,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
@@ -65,7 +65,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
@@ -115,7 +115,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 -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/tutorial-pages.html	28 Jun 2003 05:07:03 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/tutorial-pages.html	20 Aug 2003 16:20:17 -0000	1.4
@@ -3,7 +3,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
@@ -70,7 +70,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

@@ -86,7 +86,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 
 
@@ -95,7 +95,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 the section called “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 the section called “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
@@ -174,7 +174,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/unix-install.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/unix-install.html,v
diff -u -N -r1.10 -r1.11
--- openacs-4/packages/acs-core-docs/www/unix-install.html	28 Jun 2003 05:07:03 -0000	1.10
+++ openacs-4/packages/acs-core-docs/www/unix-install.html	20 Aug 2003 16:20:17 -0000	1.11
@@ -1,2 +1,2 @@
 
-Chapter�4.�Installing on Unix/LinuxPrev Part�II.�Administrator's Guide  Next
Chapter�4.�Installing on Unix/Linux
Table of Contents
Overview
Install Linux and supporting software
Install Oracle 8.1.7
Install PostGreSQL
Install AOLserver 3.3oacs1
Install OpenACS 4.7.0d
Credits
Prev Home  Next
Individual Programs Up  Overview
docs@openacs.org
View comments on this page at openacs.org
+Chapter�4.�Installing on Unix/LinuxPrev Part�II.�Administrator's Guide  Next
Chapter�4.�Installing on Unix/Linux
Table of Contents
Overview
Install Linux and supporting software
Install Oracle 8.1.7
Install PostGreSQL
Install AOLserver 3.3oacs1
Install OpenACS 5.0.0d
Credits
Prev Home  Next
Individual Programs Up  Overview
docs@openacs.org
View comments on this page at openacs.org
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 -N -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/upgrade-detail.html	28 Jun 2003 05:07:03 -0000	1.5
+++ openacs-4/packages/acs-core-docs/www/upgrade-detail.html	20 Aug 2003 16:20:17 -0000	1.6
@@ -1,5 +1,5 @@
 
-Support for upgrades.Prev Chapter�8.�Upgrading  Next
Support for upgrades.

+Support for upgrades.
Prev Chapter�8.�Upgrading  Next
Support for upgrades.

     by Joel Aufrecht

           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
@@ -8,4 +8,93 @@
     or better, you should always be able to upgrade all of your core
     packages automatically.  If you haven't changed anything, no
     manual intervention should be required.  If you are running
-    OpenACS prior to 4.5, upgrading will require manual effort.
Prev Home  Next
Chapter�8.�Upgrading Up  Upgrading OpenACS 4.5 to 4.6
docs@openacs.org
View comments on this page at openacs.org
+    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.
A computer with OpenACS 4.5.
OpenACS 4.6 tarball
Required for Full Text Search on PostGreSQL: OpenFTS 0.3.2
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 user nsadmin
OpenACS server name openacs-dev
Root of OpenACS file tree /web/openacs-dev
Database backup directory /backup/openacs/
Upgrading on Linux/Unix
Make a Backup.�Back up the database and file system (see the section called “Snapshot backup and recovery”).
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.
+
Uninstall the old OpenFTS Engine
Browse to http://yourserver/openfts.
+
Click Administration.
Click Drop OpenFTS Engine
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/
+tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz
+chown -R root.root Search-OpenFTS-tcl-0.3.2/
+cd Search-OpenFTS-tcl-0.3.2/
+./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver --with-tcl=/usr/lib/
+cd aolserver/
+make
+

+Back up the old fts driver as a precaution and install the newly
+compiled one
mv /usr/local/aolserver/bin/nsfts.so /usr/local/aolserver/bin/nsfts-0.2.so 
+cp nsfts.so /usr/local/aolserver/bin
+
Build and install the postgres code
cd /usr/local/src/Search-OpenFTS-tcl-0.3.2/
+cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.2.3/contrib /usr/local/src/postgresql-7.2.3/contrib/pgsql_contrib_openfts
+make
+su - postgres
+cd tsearch/
+make
+make install
+exit
In order for the OpenACS 4.6 OpenFTS Engine to use the OpenFTS 0.3.2 driver, we need some commands added to the database.
[root@localhost root]# su - nsadmin
+[nsadmin@localhost dev]$ psql openacs-dev -f /usr/local/pgsql/share/contrib/openfts.sql
+CREATE
+CREATE
+[nsadmin@localhost dev]$ psql openacs-dev -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql
+BEGIN
+CREATE
+(~30 more lines)
+[nsadmin@localhost dev]$ exit
+[root@localhost root]# 
+su - nsadmin
+psql openacs-dev -f /usr/local/pgsql/share/contrib/openfts.sql
+psql openacs-dev -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql
+exit
Stop the server.�
[root@localhost root]# svc -d /service/openacs-dev
Upgrade the file tree.�If you are using CVS, you will unpack the OpenACS 4.6 tarball into a working directory and then import that directory into cvs.  If you have changed files in the core packages, cvs will attempt to merge your changes.  You may have to manually merge some conflicts.  When that's finished, you can update your normal development checkout directory and the new files will appear.  If you aren't using CVS, you can unpack the tarball on top of your existing tree, but any customizations you've made to the kernel or core packages will be erased.
Upgrading files without CVS.�Unpack the tarball into a new directory and copy its contents on top of your working directory.
[root@localhost root]# su - nsadmin
+[nsadmin@localhost aolserver]$ cd /web
+[nsadmin@localhost web]$ tar xzf /tmp/openacs-4-6.tgz
+[nsadmin@localhost web]$ cp -r openacs-4-6/* openacs-4
+[nsadmin@localhost openacs-upgrade]$ exit
+[root@localhost root]#
+su - nsadmin
+cd /web
+tar xzf /tmp/openacs-4-6.tgz
+cp -r openacs-4-6/* openacs-4
+exit
Upgrading files with CVS.�
Unpack the new files into a working directory.
[root@localhost root]# su - nsadmin
+[nsadmin@localhost aolserver]$ cd /tmp
+[nsadmin@localhost tmp]$ tar xzv openacs-4-6.tgz
+[nsadmin@localhost tmp]$ cd openacs-4.6
+
Import the new files into your cvs repository; where they match existing files, they will become the new version of the file.
[nsadmin@localhost openacs-4.6]$  cvs import -m "upgrade to OpenACS 4.6" openacs 
+OpenACS openacs-4-6
Create a new directory as temporary working space to reconcile conflicts between the new files and your current work.  The example uses the cvs keyword yesterday, making the assumption that you haven't checked in new code to your local tree in the last day.
[nsadmin@localhost openacs-4.6]$  cd /web
+[nsadmin@localhost tmp]$ mkdir openacs-upgrade
+[nsadmin@localhost tmp]$ cvs checkout -d openacs-upgrade -jOpenACS:yesterday -jOpenACS openacs > cvs.txt 2>&1
+(CVS feedback here)
+su - nsadmin
+cd /tmp
+tar xzv openacs-4-6.tgz
+cd openacs-4.6
+cvs import -m "upgrade to OpenACS 4.6" openacs OpenACS openacs-4-6
+cd /tmp
+mkdir openacs-upgrade
+cvs checkout -d openacs-upgrade -jOpenACS:yesterday -jOpenACS openacs > cvs.txt 2>&1
+
The file /tmp/openacs-upgrade/cvs.txt contains the results of the upgrade.  If you changed files that are part of the OpenACS tarball and those changes conflict with the 4.5-4.6 upgrade, you'll have to manually reconcile them.  Use the emacs command M-x sort-lines and then, for each line that starts with a C, open that file and manually resolve the conflict by deleting the excess lines.  When you're finished, or if there aren't any conflicts, save and exit.
Once you've fixed any conflicts, commit the new code
+        to your local tree.  
[nsadmin@localhost tmp]$ cd openacs-upgrade
+[nsadmin@localhost openacs-upgrade]$ cvs commit -m "Upgraded to 4.6"
+cd openacs-upgrade
+cvs commit -m "Upgraded to 4.6"
Update your working tree with the new
+                files.  The CVS flags ensure that new directories are created and pruned directories destroyed.
+[nsadmin@localhost openacs-upgrade]$ cd /web/openacs-dev
+[nsadmin@localhost openacs-dev]$ cvs up -Pd
+(CVS feedback)
+[nsadmin@localhost openacs-dev]$ exit
+[root@localhost root]#
+cd /web/openacs-dev
+cvs up -Pd
+exit
Start the server.�
[root@localhost root]# svc -u /service/openacs-dev
Use APM to upgrade the database.�
Browse to the package manager, http://yourserver/acs-admin/apm.
Click Install packages.
Select the packages you want to install.  This should
+          be everything that says
+          upgrade, plus any new
+          packages you want.  It's safest to upgrade the kernel by
+          itself, and then come back and upgrade the rest of the
+          desired packages in a second pass.
On the next screen, click Install Packages
When prompted, restart the server:
[root@localhost root]# restart-aolserver openacs-dev
Wait a minute, then browse to the package manager, http://yourserver/acs-admin/apm.
Check that the kernel upgrade worked by clicking All and making sure that acs-kernel version is 5.0.0d.
OPTIONAL: Install the new OpenFTS Engine.�If you want to upgrade the OpenFTS Engine, do these
+          steps.  (You must have already upgraded the OpenFTS driver to
+          0.3.2.)
Browse to http://yourserver/admin/site-map
On the openfts line, click on set parameters.
Change the value of openfts_tcl_src_path from /usr/local/src/Search-OpenFTS-tcl-0.2/ to /usr/local/src/Search-OpenFTS-tcl-0.3.2/
Click Set Parameters
[root@localhost root]# restart-aolserver openacs-dev
Browse to http://yourserver/openfts
Click Administration.
Click Initialize OpenFTS Engine
Rollback.�If anything goes wrong, roll back to the backup snapshot.
($Id$)
Prev Home  Next
Chapter�8.�Upgrading Up  Chapter�9.�Maintenance
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/upgrade.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade.html,v
diff -u -N -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/upgrade.html	28 Jun 2003 05:07:03 -0000	1.5
+++ openacs-4/packages/acs-core-docs/www/upgrade.html	20 Aug 2003 16:20:17 -0000	1.6
@@ -1,2 +1,2 @@
 
-Chapter�8.�UpgradingPrev Part�II.�Administrator's Guide  Next
Chapter�8.�Upgrading
Table of Contents
Support for upgrades.
Upgrading OpenACS 4.5 to 4.6
Prev Home  Next
Chapter�7.�Configuring a New Service Up  Support for upgrades.
docs@openacs.org
View comments on this page at openacs.org
+Chapter�8.�UpgradingPrev Part�II.�Administrator's Guide  Next
Chapter�8.�Upgrading
Table of Contents
Support for upgrades.
Prev Home  Next
Chapter�7.�Configuring a New Service Up  Support for upgrades.
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/win2k-installation.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/win2k-installation.html,v
diff -u -N -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/win2k-installation.html	28 Jun 2003 05:07:03 -0000	1.11
+++ openacs-4/packages/acs-core-docs/www/win2k-installation.html	20 Aug 2003 16:20:17 -0000	1.12
@@ -4,7 +4,7 @@
           by OpenACS documentation staff.
         
NOTE: These instructions were
     valid for ACS v4, but have not been tested with OpenACS. Currently
-    (8/2002), the best option to get OpenACS 4.7.0d running on Windows
+    (8/2002), the best option to get OpenACS 5.0.0d running on Windows
     is to use VMware and John
     Sequeira's Oasis VM
     distribution
Index: openacs-4/packages/acs-core-docs/www/images/ext-auth.png
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/ext-auth.png,v
diff -u -N
Binary files differ
Index: openacs-4/packages/acs-core-docs/www/xml/Makefile
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/Makefile,v
diff -u -N -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/xml/Makefile	24 Jun 2003 03:37:04 -0000	1.5
+++ openacs-4/packages/acs-core-docs/www/xml/Makefile	20 Aug 2003 16:20:18 -0000	1.6
@@ -22,10 +22,15 @@
 
 prelim:
 	cp -u images/*.{pdf,png,gif,jpg} ../images/
+
+# put all non-regenerated html in a sub-dir so that we can delete html
+# in the main directory and regenerate
+	cp -u non-xml/*.html ../
+
 	cp -u openacs.css ..
 
 html: prelim
-	cd .. ; $(XSLTPROC) xml/openacs.xsl xml/index.xml
+	cd .. ; $(XSLTPROC) --xinclude xml/openacs.xsl xml/index.xml
 
 pdf: html
 #	$(HTMLDOC) --batch ../for-everyone.book ../for-admins.book ../for-developers.book
Index: openacs-4/packages/acs-core-docs/www/xml/index.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/index.xml,v
diff -u -N -r1.14 -r1.15
--- openacs-4/packages/acs-core-docs/www/xml/index.xml	28 Jun 2003 05:07:06 -0000	1.14
+++ openacs-4/packages/acs-core-docs/www/xml/index.xml	20 Aug 2003 16:20:18 -0000	1.15
@@ -1,94 +1,10 @@
 
 
+
+%myvars;
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
 ]>
 
 
@@ -176,50 +92,95 @@
 	    free to ask a question, post ideas or whatever.
 	  
       
-      &release-notes;
+      
+        Section Missing
+      
     
   
   
   
     Administrator's Guide
-    &quick-install;
-    &software;
+    
+      Section Missing
+    
+ 
+    
+      Section Missing
+    
+ 
     
       Installing on Unix/Linux
-      &install-overview;
-      &operating-system;
-      &oracle;
-      &postgres;
-      &aolserver;
-      &openacs;
-      &credits;
+      
+      Section Missing
+    
+ 
+      
+      Section Missing
+    
+ 
+      
+      Section Missing
+    
+ 
+      
+      Section Missing
+    
+ 
+      
+      Section Missing
+    
+ 
+      
+      Section Missing
+    
+ 
+      
+      Section Missing
+    
+ 
     
     
       Installing on Windows
-      &win2k;
+      
+        Section missing
+       
     
     
       Installing on a Macintosh
-      &mac;
+      
+Section missing
+       
     
-
+    
     
       Configuring a New Service
       Placeholder 
     
 
     
-      Upgrading
-      &upgrade;
-    
+          Upgrading
+          
+Section missing
+       
+        
     
-      Maintenance
-      &maintenance;
-      &database-maintenance;
-      &recovery;
+          Maintenance
+          
+Section missing
+       
+      
+Section missing
+       
+      
+Section missing
+       
     
-    &redhat;
-    &other-software;
+    
+Section missing
+       
+    
+Section missing
+       
   
 
   
@@ -234,69 +195,113 @@
 
     
       Development Tutorial
-      &tutorial-newpackage;
-      &tutorial-database;
-      &tutorial-pages;
-      &tutorial-debug;
-      &tutorial-advanced;
+      
+Section missing
+       
+      
+Section missing
+       
+      
+Section missing
+       
+      
+Section missing
+       
+      
+Section missing
+       
     
 
     
       Development Reference
-      &packages;
-      &objects;
-      &rp;
-      &api;
-      &templates;
-      &permissions;
-      &subsites;
-      &parties;
-      &permissions-tedious;
-      &object-identity;
-      &programming-aolserver;
+      
+Section missing
+       
+      
+Section missing
+       
+      
+Section missing
+       
+      
+Section missing
+       
+      
+Section missing
+       
+      
+Section missing
+       
+      
+Section missing
+       
+      
+Section missing
+       
+      
+        Section missing
+      
+      
+Section missing
+       
+      
+Section missing
+       
     
 
     
       Engineering Standards
 
-      &dbprimer;
-      &psgml-mode;
-      &design-template;
-      &requirements-template;
-      &versioning;
-      &constraint-naming;
-      &filenaming;
-      &plsql-standards;
+      
+Section missing
+       
+      
+Section missing
+       
+      
+Section missing
+       
+      
+Section missing
+       
+      
+Section missing
+       
+      
+Section missing
+       
+      
+Section missing
+       
+      
+Section missing
+       
     
-      &cvs;
+    
+Section missing
+       
   
-
+  
   
     For OpenACS Platform Developers
     
       Kernel Documentation
 
       
         Overview
-        
-	  Compared to its predecessors, version &version; of OpenACS has a much
-	  more structured organization, i.e. the most
-	  significant change is found at the system architecture level,
-	  reflected in the following hierarchy:
-        
         
 	
 	  
             
-              The OpenACS &version; Kernel, which
+              The OpenACS Kernel, which
 	      handles system-wide necessities such as metadata,
 	      security, users and groups, subsites, and package
 	      management and deployment.
 	    
           
 	  
             
-              The OpenACS &version; Core, which
+              The OpenACS Core, which
 	      comprises all the other packages that ship with the
 	      kernel and are most frequently needed by users, such as
 	      templating, bboard, and user
@@ -306,8 +311,7 @@
           
 	  
             
-              OpenACS &version; Application
-	      packages, which typically provide user-level
+              OpenACS Application packages, which typically provide user-level
 	      web services built on top of the Kernel and Core.  Such
 	      packages include those built by ArsDigita as well as
 	      external contributors.  Application packages are
@@ -318,30 +322,76 @@
 	
 	
 	  This document provides a high level overview of the kernel
-	  package. Documentation for the other packages can be found
-	  elsewhere.
+	  package. Documentation for other packages on this server
 	
       
 
-      &objects-req;
-      &objects-design;
-      &permissions-req;
-      &permissions-design;
-      &groups-req;
-      &groups-design;
-      &subsites-req;
-      &subsites-design;
-      &apm-req;
-      &apm-design;
-      &db-api;
-      &security-req;
-      &security-design;
-      &security-notes;
-      &rp-req;
-      &rp-design;
-      &tcl-doc;
-      &bootstrap-acs;
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
+      
+        Section missing
+       
 
     
+
   
+
 
Index: openacs-4/packages/acs-core-docs/www/xml/openacs.xsl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/openacs.xsl,v
diff -u -N -r1.9 -r1.10
--- openacs-4/packages/acs-core-docs/www/xml/openacs.xsl	20 Jul 2003 06:00:23 -0000	1.9
+++ openacs-4/packages/acs-core-docs/www/xml/openacs.xsl	20 Aug 2003 16:20:18 -0000	1.10
@@ -7,20 +7,16 @@
 
   
 
-
 
-
+
 
-
+  0
 
 
-  
+  
 
 
 
@@ -330,4 +326,88 @@
 
 
 
+
+
+
+  
+    
+      
+      
+    
+  
+
+  

+    
+
+    
+      
+        
+      
+      
+        
+      
+      
+        
+      
+      
+        
+      
+      
+        
+      
+    
+  
+
+
+
+  
+    
+      
+      
+    
+  
+
+  
+    
+      
+      
+    
+  
+
+  
+
+  
+  
+    
+      
+        
+      
+    
+    
+      
+        
+      
+    
+    
+      
+        
+          
+          
+        
+        
+      
+    
+    
+      
+    
+  Feature Status Description

+
+
+
+
 
+
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/cvs.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/cvs.xml,v
diff -u -N -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/cvs.xml	28 Jun 2003 05:07:06 -0000	1.2
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/cvs.xml	20 Aug 2003 16:20:18 -0000	1.3
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
   
     Using CVS with an OpenACS Site
     
@@ -83,8 +89,3 @@
     
   
   
-
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/db-api.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/db-api.xml,v
diff -u -N -r1.7 -r1.8
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/db-api.xml	24 Jun 2003 03:37:04 -0000	1.7
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/db-api.xml	20 Aug 2003 16:20:18 -0000	1.8
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
   The OpenACS Database Access API
 
@@ -1097,8 +1103,3 @@
   
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml,v
diff -u -N -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml	28 Feb 2003 05:26:59 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml	20 Aug 2003 16:20:18 -0000	1.5
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
   Internationalization
 
@@ -13,70 +19,102 @@
     Introduction
 
     
-      This document describes how to develop internationalized OpenACS packages.
+      This document describes how to develop internationalized OpenACS
+      packages, including writing new packages with
+      internationalization and converting old packages.  Text that
+      users might see is "localizable text"; replacing monolingual text
+      and single-locale date/time/money functions with generic
+      functions is "internationalization"; translating first
+      generation text into a specific language is "localization."  At
+      a minimum, all packages should be internationalized.  If you do
+      not also localize your package for different locales, volunteers
+      may use a public "localization server" to submit suggested text.
+      Otherwise, your package will not be usable for all locales.
     
 
     
-      At this point, we've only covered things that involve the
-      message catalog: Dynamically picking a chunk of text to spit out
-      based on the locale. 
+      The main difference between monolingual and internationalized
+      packages is that all user-visible text in an internationalized
+      package are coded as "message keys."  The message keys
+      correspond to a message catalog, which contains versions of the
+      text for each available language.  Both script files
+      (ADP/TCL) and APM parameters are affected.
     
-    
+
     
-      Each section below consists on one part about how to write
-      new internationalized packages, and which explains the details
-      of how it works, and then another part that talks about the
-      process for internationalizing existing packages.
-    
+      Other differences include: all dates read or written to the
+      database must use internationalized functions.  All displayed
+      dates must use internationalized functions.  All displayed
+      numbers must use internationalized functions.
+
+
   
 
   
 
     Using the Message Catalog
 
     
-      The following section will tell you how to deal with localizable
-      text in ADP files, in TCL files, and in APM Parameters.
+      Localizable text must be handled in ADP files, in TCL files, and
+      in APM Parameters.  OpenACS provides two approaches, message
+      keys and localized ADP files.  For ADP pages which are mostly
+      code, replacing the message text with message key placeholders
+      is simpler.  This approach also allows new translation in the
+      database, without affecting the file system.  For ADP pages
+      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.
     
 
-    
-      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 intenral message keys, which
-        can then be dynamically replaced with real human language in the desired
-        locale.
+        text in a certain language with internal message keys, which
+        can then be dynamically replaced with real human language in
+        the desired locale.  Message keys themselves should be in
+        ASCII English, as should all code.  Three different syntaxes
+        are possible for message keys.
       
       
       
-        There are 3 syntaxes to choose from: The short, the verbose,
-        and the temporary. Each offer different advantages, but
-        generally, what you want to do is use the short notation for
-        new packages and use the temporary notation for
-        internationalizing old packages, then have the APM translate
-        those into the short notation.
-      
+        "Short" syntax is the recommended syntax and should be used
+        for new development.  When internationalizing an existing
+        package, you can use the "temporary" syntax, which the APM can
+        use to auto-generate missing keys and automatically translate
+        to the short syntax.  The "verbose" syntax is useful while
+        developing, because it allows default text so that the page is
+        usable before you have done
+        localization.      
       
       
 
         
           
             The short:
-            #message_key#
+            #package_key.message_key#
           
           
             The advantage of the short syntax is that it's short. It's
-            as simple as inserting the value of a variable.
+            as simple as inserting the value of a variable.  Example:
+            #forum.title#
           
         
 
         
           
-            The verbose: <trn
-            key="message_key"
+            The verbose: <trn
+            key="package_key.message_key"
             locale="locale">default
-            text</trn>
+            text</trn>
           
           
             The verbose syntax allows you to specify a default text in
@@ -85,14 +123,15 @@
             it still works even if you haven't created the message
             in the message catalog yet, because what it'll do is
             create the message key with the default text from the tag
-            as the localized message.
+            as the localized message.  Example: <trn
+            key="forum.title" locale="en_US">Title</trn>
           
         
 
         
           
             The temporary:
-            <#message_key original text#>
+            <#message_key original text#>
           
           
             This syntax has been designed to make it easy to
@@ -101,7 +140,7 @@
             with the short syntax by a special feature of the APM. You
             may leave out the message_key by writing an underscore (_)
             character instead, in which case a message key will be
-            auto-generated by the APM.
+            auto-generated by the APM.  Example: <_ Title>
           
         
 
@@ -122,7 +161,7 @@
         this case, instead of storing the real text in the parameter,
         you should use message keys using the short notation above,
         i.e.  #message-key#.
+        role="strong">#package_key.message_key#.
       
 
       
@@ -204,8 +243,8 @@
       
       
       
-        You're responsible for creating the keys in the message
-        catalog yourself.
+        Developers are responsible for creating the keys in the message
+        catalog, which is available at /acs-lang/admin/
       
 
     
@@ -218,46 +257,36 @@
     Dates, Times, and Numbers
 
     
-      Let's deal with dates and times first. The way it works is as follows:
+      Dates and times must be converted when stored in the database,
+      when retrieved from the database, and when displayed.  All dates
+      are stored in the database in the server's timezone, which is an
+      APM Parameter set at
+      /acs-lang/admin/set-system-timezone
+      and readable at
+      lang::system::timezone..  When
+      retrieved from the database and displayed, dates and times must
+      be localized to the user's locale.
     
 
     
 
       
         
           Get the date in ANSI format from the database (YYYY-MM-DD
-          HH24:MI:SS, the time portion is optional). Name the column
-          in the SQL statement something that ends in
-          "_ansi", such as
-          "posting_date_ansi". Example:
-          to_char(posting_date, 'YYYY-MM-DD
-          HH24:MI:SS') as posting_date_ansi
-        
+          HH24:MI:SS; the time portion is optional).  By convention,
+          we identify dates in ansi format by ending the column name
+          with _ansi.
+          Example:
+        select to_char(posting_date, 'YYYY-MM-DD HH24:MI:SS') as posting_date_ansi
+  from table
+
       
 
       
         
-          Use the Tcl command "lc_time_fmt" to format the
-          date in pretty format. There are a number of standard,
-          localizable formats to choose from (see below). Example:
-          set posting_date_pretty [lc_time_fmt
-          $posting_date_ansi "%q"]
-        
-      
-
-      
-        
-          Use the "*_pretty"-version in your ADP page.
-        
-      
-
-    
-
-    
-      Here's the list of standard date and time formats to choose
-      from:
-    
-
+          Use the Tcl command lc_time_fmt to format the
+          date in "pretty" format.  Several standard formats localize automatically:
+
     
 
       
@@ -291,62 +320,90 @@
       
 
     
-    
-    
-      If the abbreviations seem a bit strange, it's because they
-      are. Most of them are standardized (see man
-      strftime for example). %q and %Q are our
-      proprietary additions, and 'q' was just about the only letter
-      left in the alphabet.
+
+        
+      The "q" format strings are OpenACS additions; the rest follow unix standards (see man
+      strftime).
     
+        
+        set posting_date_pretty [lc_time_fmt $posting_date_ansi "%q"]
+        
+      
+      
+      
+        
+          Use the *_pretty version in your ADP page.
+        
+      
+      
+    
 
     
-      The command 'lc_fmt_time' allows you to pass in a specific date
-      and time format as well, but please don't, because the whole
-      point is to make it possible for administrators to change date
-      and time formats site-wide based on locales.
+      To internationalize numbers, use lc_numeric $value, which formats the number using the appropriate decimal point and thousand separator for the locale.
     
     
-    
-      Numbers are very easy to format. Just say
-      lc_numeric $value, and it'll
-      format 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
 
-    
-      Page Files (ADP and Tcl Files) 
-    
-      
-        We've created a couple of tools especially for
-        internationalizing the pages of existing packages. The tools can
-        be accessed from the "Manage Internationalization"
-        linked from the package manager page for a package.
-      
-  
-      
-        The process consists of four steps:
-      
-  
-      
-  
-        
-          
+    
+        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
+        Internationalization, then
+        Convert ADP, Tcl, and SQL files to using the
+        message catalog..
+        
+          
+            
             Replace text with tags:
-            This is an automated process, which will try to
-            automatically locate chunks of translatable text,
-            auto-generate a reasonable message key, and surround the
-            text with the temporary <#...#> notation mentioned
-            above.
+            Choose Find human language text and replace with <# ... #> tags.  This automated process
+            automatically locates chunks of translatable text,
+            generates a reasonable message key, and replaces the text
+            with a "temporary" tag as described above.
           
+          Any pieces of text found but not extractable -- for
+          example, pieces of text with embedded adp variables
+          (i.e. @var_name@) --  will be listed on the result
+          page. Make sure to take note of these texts and translate
+          them manually. Suppose for example that our script tells you
+          that it left the text "Manage forum @forum_name@"
+          untouched. What you should do then is to edit the
+          corresponding adp file and manually replace that text with
+          something like "<#manage_forum Manage forum @forum_name@#>"
+          (to save you from too much typing you may use the shorthand
+          <#_ Manage forum @forum_name@#>; an underscore key will
+          result in the script auto-generating a key for you based on
+          the text). After you have made all such manual edits you can
+          simply run the second action labeled "Replace tags with keys
+          and insert into catalog".
+
+Note: running this action will not find translatable text within HTML or adp tags on adp pages (i.e. text in alt tags of images), nor will it find translatable text in tcl files. Such texts will have to be found manually. If those texts are in adp files they are best replaced with the <#message_key text#> tags that can be extracted by the action described below. Here are some commands that we used on Linux to look for texts in adp pages not found by the script:
+          
+# List image tags with alt attributes, look for alt attributes with literal text
+find -iname '*.adp'|xargs egrep -i '<img.*alt='
+# List submit buttons, look for text in the value attribute 
+find -iname '*.adp'|xargs egrep -i '<input[^>]*type="?submit'
+
+
+        
+          When you run this step, any modified files are backed up in
+          a file with a ".orig" suffix. Those files are
+          never overwritten, though, so the .orig file will always be
+          the original page file, not the second-to-last file. Running
+          this action multiple times is harmless.
+        
+
         
   
         
@@ -364,6 +421,78 @@
             files, marking up translatable text with the
             <#...#> notation.
           
+          Ttranslatable texts are often found in page titles, context bars, and form labels and options. Many times the texts are enclosed in double quotes. Use the following grep commands on Linux to highlight translatable text in tcl files for us:
+
+          # Find text in double quotes
+find -iname '*.tcl'|xargs egrep -i '"[a-z]'
+# Find untranslated text in form labels, options and values
+find -iname '*.tcl'|xargs egrep -i '\-(options|label|value)'|egrep -v '<#'|egrep -v '\-(value|label|options)[[:space:]]+\$[a-zA-Z_]+[[:space:]]*\\?[[:space:]]*$'
+# Find text in page titles and context bars
+find -iname '*.tcl'|xargs egrep -i 'set (title|page_title|context_bar) '|egrep -v '<#'
+# Find text in error messages
+find -iname '*.tcl'|xargs egrep -i '(ad_complain|ad_return_error)'|egrep -v '<#'
+
+          You may mark up translatable text in tcl library files and tcl pages with temporary tags (on the <#key text#> syntax mentioned previously). If you have a sentence or paragraph of text with variables and or procedure calls in it you should in most cases try to turn the whole text into one message in the catalog. In those cases, follow these steps:
+
+          
+            
+                            For each message call in the text, decide on a variable
+              name and replace the procedure call with a variable
+              lookup on the syntax %var_name%. Remember to initialize
+              a tcl variable with the same name on some line above the
+              text.
+            
+            
+              If the text is in a tcl file you must replace
+              variable lookups (occurences of $var_name or
+              ${var_name}) with %var_name%
+            
+            
+              You are now ready to follow the normal procedure
+              and mark up the text using a tempoarary message tag (<#_
+              text_with_percentage_vars#>) and run the action replace
+              tags with keys in the APM.
+            
+          
+          The variable values in the message are usually fetched with upvar, here is an example from dotlrn:
+
+          ad_return_complaint 1 "Error: A [parameter::get -parameter classes_pretty_name] 
+             must have no[parameter::get -parameter class_instances_pretty_plural] to be deleted"
+
+was replaced by:
+
+          set subject [parameter::get -localize -parameter classes_pretty_name] 
+set class_instances [parameter::get -localize -parameter class_instances_pretty_plural]
+ad_return_complaint 1 [_ dotlrn.class_may_not_be_deleted]
+
+
+          This kind of interpolation also works in adp files where adp variable values will be inserted into the message.
+
+          Alternatively, you may pass in an array list of the variable values to be interpolated into the message so that our example becomes:
+
+          set msg_subst_list [list subject [parameter::get -localize -parameter classes_pretty_name] 
+                         class_instances [parameter::get -localize -parameter class_instances_pretty_plural]]
+
+ad_return_complaint 1 [_ dotlrn.class_may_not_be_deleted $msg_subst_list]
+
+          When we were done going through the tcl files we ran the following commands to check for mistakes:
+
+          # Message tags should usually not be in curly braces since then the message lookup may not be
+# executed then (you can usually replace curly braces with the list command). Find message tags 
+# in curly braces (should return nothing, or possibly a few lines for inspection)
+find -iname '*.tcl'|xargs egrep -i '\{.*<#'
+# Check if you've forgotten space between default key and text in message tags (should return nothing)
+find -iname '*.tcl'|xargs egrep -i '<#_[^ ]'
+# Review the list of tcl files with no message lookups
+for tcl_file in $(find -iname '*.tcl'); do egrep -L '(<#|\[_)' $tcl_file; done
+
+          When you feel ready you may run the action "Replace tags with keys and insert into catalog" on the tcl files that you've edited to replace the temporary tags with calls to the message lookup procedure.
+          The acs-lang/bin/check-catalog.sh script checks that the set of keys used in message lookups in tcl, adp, and info files and the set of keys in the catalog file are identical. The scripts below assume that message lookups in adp and info files are on the format #package_key.message_key#, and that message lookups in tcl files are always done with the underscore procedure. The script assumes that you have perl installed and in your path. Run the script like this:
+
+          acs-lang/bin/check-catalog.sh package_key
+
+          where package_key is the key of the package that you want to test. If you don't provide the package_key argument then all packages with catalog files will be checked. The script will run its checks on en_US xml catalog files. 
+
         
   
         
@@ -376,53 +505,61 @@
             process twice, once for ADP files, and once for Tcl files.
           
         
-  
-      
-      
-      
-        Replace Text With Tags Step
+        
 
-        
-          When you run this step, any modified files are backed up in
-          a file with a ".orig" suffix. Those files are
-          never overwritten, though, so the .orig file will always be
-          the original page file, not the second-to-last file. Running
-          this action multiple times is harmless.
-        
+    
+    
+      Internationalize Package Parameters with visible messages
+      
+      See 
+    
+    
 
-        
-          The system will auto-generate suggested message keys. 
-        
+    
+      Internationalize Date and Time queries
+      
+        
+          Find datetime in .xql files.  Use command line tools to find suspect SQL code:
+          grep -r "to_char.*H" *
+grep -r "to_date.*H" *
+
+        
+        
+          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
+        
 
-        
-          ... (WRITE MORE HERE!)
-        
-
-      
-
-      
-        Replace Tags With Keys Step
-
-        
-          
-        
-
-      
-
+        
+          In TCL files where the date fields are used, convert the datetime from local server timezone, which is how it's stored in the database, to the user's timezone for display.  Do this with the localizing function lc_time_system_to_conn:
+
+set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]
+          When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with lc_time_conn_to_system.
+
+        
+        
+          When a datetime field will be displayed, format it using the localizing function lc_time_fmt. lc_time_fmt takes two parameters, datetime and format code.  Several format codes are usable for localization; they are placeholders that format dates with the appropriate codes for the user's locale.  These codes are: %x, %X, %q, %Q, and %c.
+          set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]
+        
+      
     
+  
 
-    
-      Next step is to internationalize parameters that contain
-      localizable text. See the section .
-    
-
+  
+    Design Notes
+    User locale is a property of ad_conn, ad_conn locale.  The request processor sets this by calling lang::conn::locale, which looks for the following in order of precedence:
+    
+      Use user preference for this package (stored in ad_locale_user_prefs)
+      Use system preference for the package (stored in apm_packages)
+      
+      Use user's general preference (stored in user_preferences)
+      Use Browser header (Accept-Language HTTP header)
+      Use system locale (an APM parameter for acs_lang)
+default to en_US
+    
+    For ADP pages, message key lookup occurs in the templating engine.  For TCL pages, message key lookup happens with the _ function.  In both cases, if the requested locale is not found but a locale which is the default for the language which matches your locale's language is
+found, then that locale is offered instead.
   
 
-
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/object-identity.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/object-identity.xml,v
diff -u -N -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/object-identity.xml	10 Aug 2002 19:45:14 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/object-identity.xml	20 Aug 2003 16:20:18 -0000	1.5
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 Object Identity
 
@@ -50,8 +56,3 @@
 ($Id$)
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/objects.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/objects.xml,v
diff -u -N -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/objects.xml	4 Nov 2002 22:13:33 -0000	1.5
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/objects.xml	20 Aug 2003 16:20:18 -0000	1.6
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 OpenACS Data Models and the Object System
 
@@ -556,8 +562,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml,v
diff -u -N -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml	10 Aug 2002 19:45:14 -0000	1.5
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/packages.xml	20 Aug 2003 16:20:18 -0000	1.6
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
   OpenACS &version; Packages
 
@@ -842,8 +848,3 @@
   
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/parties.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/parties.xml,v
diff -u -N -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/parties.xml	10 Aug 2002 19:45:14 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/parties.xml	20 Aug 2003 16:20:18 -0000	1.5
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 Parties in OpenACS &version;
 
@@ -475,8 +481,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions-tediously-explained-es.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions-tediously-explained-es.xml,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions-tediously-explained-es.xml	20 Aug 2003 16:20:18 -0000	1.1
@@ -0,0 +1,623 @@
+
+
+%myvars;
+]>
+
+ Sistema de Permisos de OpenACS Tediosamente Explicado
+	
+  
+    por Vadim Nasardinov. Modificado y convertido a Docbook XML por Roberto Mello. Traducido por David Arroyo.
+  
+
+    
+
+      Introducción
+
+      En OpenACS 3.x se consiguió tener un sistema reutilizable de control de permisos y poder contestar a la pregunta clave quié puede hacer qué en tal objeto. Sin embargo, no se consiguió que este control de permisos estuviera realmente unificado. En ocasiones, el control de permisos se construía en base a cada módulo/paquete, ó incluso en base a cada p´gina. De este modo, algunos módulos usaban "roles" y otros no. Otros módulos hacían todo el control de acceso basándose en simples reglas de código.
+
+      Los problemas resultantes de esto fueron sobre todo inconsistencias y código redundante. De este modo, en OpenACS 4 se busca proporcionar un unificado y consistente sistema de permisos para que tanto programadores y administradores puedan usarlo de manera amigable.
+
+      En OpenACS 4 la pregunta quién puede hacer qué en tal objeto, el "quién" se responde a través de la jerarquía de party (la generalización de personas, usuarios, miembros de un grupo, etc.), el "tal objeto" también se establece a través de la jerarquía de objetos y por último el "qué" se establece a travé de una jerarquía de posibles acciones. Ahora iremos aclarando todos estos conceptos.
+
+      En el corazón del sistema de permisos tenemos dos tablas: acs_privileges y acs_permissions:
+
+      
+  create table acs_privileges (
+      privilege           varchar2(100) not null
+          constraint acs_privileges_pk primary key,
+      pretty_name         varchar2(100),
+      pretty_plural       varchar2(100)
+  );
+      
+
+      
+   create table acs_permissions (
+      object_id
+          not null
+          constraint acs_permissions_on_what_id_fk references acs_objects (object_id),
+      grantee_id
+          not null
+          constraint acs_permissions_grantee_id_fk references parties (party_id),
+      privilege
+          not null
+          constraint acs_permissions_priv_fk references acs_privileges (privilege),
+      constraint acs_permissions_pk
+          primary key (object_id, grantee_id, privilege)
+  );
+      
+
+      La tabla acs_privileges almacena el propio nombre de los privilegios como leer, escribir, borrar, crear y administrar.
+
+      La tabla acs_permissions responde a la ya famosa pregunta clave quién (grantee_id) puede hacer qué (privilege) en tal objeto (object_id).
+
+      Ahora vamos a profundizar cómo funciona el sistema de permisos a través de la jerarquía de objetos, de parties y de privilegios.
+
+    
+
+    
+      Jerarquía de Objetos
+
+      La tabla acs_objects se crea de la siguiente manera:
+
+      
+   create table acs_objects (
+      object_id             integer
+          not null
+          constraint acs_objects_pk primary key,
+      object_type
+          not null
+          constraint acs_objects_object_type_fk references acs_object_types (object_type),
+      context_id
+          constraint acs_objects_context_id_fk references acs_objects(object_id),
+	  security_inherit_p  char(1) default 't'
+          not null,
+      constraint acs_objects_sec_inherit_p_ck
+          check (security_inherit_p in ('t', 'f')),
+      creation_user         integer,
+      creation_date         date default sysdate not null,
+      creation_ip           varchar2(50),
+      last_modified         date default sysdate not null,
+      modifying_user        integer,
+      modifying_ip          varchar2(50),
+      constraint acs_objects_context_object_un
+          unique (context_id, object_id) disable
+   );
+	
+
+      De este modo, supongámos que los objetos A, B, ..., F tienen la siguiente jerarquía:
+
+      
+	
+	
+	  
+	    
+	    
+	    
+	      
+		Aobject_id=10
+	      
+	      
+		Bobject_id=20
+		Cobject_id=30
+	      
+	      
+		Dobject_id=40
+		Eobject_id=50
+		Fobject_id=60
+	      
+	    
+
+	  
+
+	
+
+	Esto podría ser representado en  de la siguiente manera:
+
+	
+	  
+	  
+	    
+	      
+		object_id
+		context_id
+	      
+	    
+	    
+	      
+		20
+		10
+	      
+	      
+		30
+		10
+	      
+	      
+		40
+		20
+	      
+	      
+		50
+		20
+	      
+	      
+		60
+		30
+	      
+	    
+	  
+	

+
+	Así se expresa que el objeto 20 es descendiente del objeto 10 y que el objeto 40 es descendiente del objeto 10, etc. Mediante una consulta CONNECT BY es posible computar que el objeto 40 es descendiente de segunda generación del objeto 10. Con esto en mente si nosotros queremos grabar que Juan tiene permisos de lectura en los objetos A,...,F, solo necesitamos introducir el siguiente registro en la tabla .
+
+	
+	  Instancia en acs_permissions
+	  
+	    
+	      
+		object
+		grantee
+		privilege
+	      
+	    
+	    
+	      
+		A
+		Juan
+		read
+	      
+	    
+	  
+	

+
+	El hecho de Juan también puede leer B,C,...,F puede ser deducido determinando que estos objetos son hijos de A en la jerarquía de objetos. El coste computacional de estas consultas en la jerarquía es bastante costoso. Una manera de solucionar esto podría ser una delgada vista del árbol de contexto como esto:
+
+	
+	  
+	  
+	    
+	      
+		object
+		ancestor
+		n_generations
+	      
+	    
+	    
+	      
+		A
+		A
+		0
+	      
+	      
+		B
+		B
+		0
+	      
+	      
+		C
+		C
+		0
+	      
+	      
+		C
+		A
+		1
+	      
+	      
+		D
+		D
+		0
+	      
+	      
+		D
+		B
+		1
+	      
+	      
+		D
+		A
+		2
+	      
+	      
+		E
+		E
+		0
+	      
+	      
+		E
+		B
+		1
+	      
+	      
+		E
+		A
+		2
+	      
+	      
+		F
+		F
+		0
+	      
+	      
+		F
+		C
+		1
+	      
+	      
+		F
+		A
+		2
+	      
+	    
+	  
+	

+
+	La solución de crear una vista tampoco es válida debido a que crece exponecialmente con respecto a la profundidad del árbol de contexto, dando graves problemas de almacenamiento y mantenimiento.
+
+	Finalmente, el árbol de contexto es almacenado en la tabla acs_object_context_index:
+
+	
+create table acs_object_context_index (
+      object_id
+          not null
+          constraint acs_obj_context_idx_obj_id_fk references (object_id),
+      ancestor_id
+          not null
+          constraint acs_obj_context_idx_anc_id_fk references (object_id),
+	  n_generations    integer
+          not null
+          constraint acs_obj_context_idx_n_gen_ck check (n_generations >= 0),
+      constraint acs_object_context_index_pk
+          primary key (object_id, ancestor_id)
+  ) organization index;
+
+	
+
+	Esta tabla se sincroniza con  mediante triggers como este:
+
+	
+create or replace trigger acs_objects_context_id_in_tr
+after insert on acs_objects
+for each row
+begin
+    insert into acs_object_context_index
+     (object_id, ancestor_id, n_generations)
+    values
+     (:new.object_id, :new.object_id, 0);
+
+    if :new.context_id is not null and :new.security_inherit_p = 't' then
+      insert into acs_object_context_index
+       (object_id, ancestor_id,
+        n_generations)
+      select
+       :new.object_id as object_id, ancestor_id,
+       n_generations + 1 as n_generations
+      from acs_object_context_index
+      where object_id = :new.context_id;
+    elsif :new.object_id != 0 then
+      -- 0 is the id of the security context root object
+      insert into acs_object_context_index
+       (object_id, ancestor_id, n_generations)
+      values
+       (:new.object_id, 0, 1);
+    end if;
+end;
+	
+
+	Para finalizar con  tan solo decir que si configuramos un objeto con el campo security_inherit_p a 'f', de ese modo no hay herencia de permisos de unos objetos a otros.
+      
+
+      
+	Jerarquía de Privilegios
+
+	Los privilegios también son organizados jerárquicamente. Además de los cinco principales privilegios de sistema definidos en el ACS Kernel Data Model, los desarrolladores de aplicaciones pueden definir los suyos propios.
+
+	Gracias al modelo de datos de OpenACS es sencillo para los desarrolladores administrar permisos. Por ejemplo, para darle a un usuario privilegios de lectura, escritura, creación y borrado en un objeto, basta con darle a un usuario el privilegio administración (admin)y los otros cuatro privilegios le serán dados automáticamente. Por ejemplo, la estructura de privilegios de los foros es la siguiente: 
+
+	
+	  Jerarquía de privilegios de los foros
+	  
+	    
+	    
+	    
+	    
+	    
+	    
+	    
+	    
+	    
+	    
+	    
+	    
+	    
+	    
+	      
+		admin
+	      
+	      
+		create
+		delete
+		read
+		write
+		moderate forum
+	      
+	      
+		create category
+		create forum
+		create message
+		delete category
+		delete forum
+		delete message
+		read category
+		read forum
+		read message
+		write category
+		write forum
+		write message
+	      
+	    
+	  
+	
+
+	Al igual que en la jerarquía de objetos, es bueno tener una representación integrada de la estructura jerárquica. Esto se consigue definiendo la siguiente vista:
+
+	
+  create or replace view acs_privilege_descendant_map
+  as
+  select
+    p1.privilege,
+    p2.privilege as descendant
+  from
+     p1,
+     p2,
+  where
+    p2.privilege in 
+      (select
+         child_privilege
+       from
+         
+       start with
+         privilege = p1.privilege
+       connect by
+         prior child_privilege = privilege
+      )
+    or p2.privilege = p1.privilege;
+
+	
+
+	Como el número esperado de privilegios en el sistema es razonablemente pequeño una vista funciona bien.
+
+      
+
+      
+	Jerarquía de parties
+
+	Veamos ahora la tercera jerarquía que juega un papel importante en el sistema de permisos. El modelo de datos de parties es el siguiente:
+
+	
+	  
+	  
+	    
+	    
+	    
+	      
+		parties
+	      
+	      
+		persons
+		groups
+	      
+	      
+		users
+	      
+	    
+	  
+	
+
+	
+  create table parties (
+      party_id
+          not null
+          constraint parties_party_id_fk references acs_objects (object_id)
+          constraint parties_pk primary key,
+      email               varchar2(100)
+          constraint parties_email_un unique,
+      url                 varchar2(200)
+  );
+	
+
+	
+  create table persons (
+      person_id
+          not null
+          constraint persons_person_id_fk references parties (party_id)
+          constraint persons_pk primary key,
+      first_names          varchar2(100)
+          not null,
+      last_name            varchar2(100)
+          not null
+  );
+	
+
+	
+  create table users (
+      user_id
+          not null
+          constraint users_user_id_fk references persons (person_id)
+          constraint users_pk primary key,
+      password        char(40),
+      -- other attributes
+  );
+	
+
+	
+  create table groups (
+      group_id
+          not null
+          constraint groups_group_id_fk references parties (party_id)
+          constraint groups_pk primary key,
+      group_name           varchar2(100) not null
+  );
+	
+
+	Recuerda que el campo grantee_id de la tabla  referencia a parties.party_id. Esto significa que tu puedes dar privilegios en un objeto a una party, persona, usuario, o grupo. Los grupos representan agregaciones de parties. En general, los grupos son una colección de usuarios, aunque podemos tener colecciones de personas, grupos, parties, ó cualquier mezcla entre unos y otros.
+
+	Dado que el uso más común de los grupos es para hacer conjuntos de usuarios ¿cómo construiremos los grupos?. Para entender esto debemos echar un rápido vistazo a lo ya explicado en el  y recordar que la manera en que se relacionan objetos es mediante acs_rels. La relación que utilizaremos será la de membresía. Si tenemos un grupo llamado Papiroflexia, podemos asingnarle los miembros Pedro, María y Sara. El hecho de que estos usuarios son miembros de Papiroflexia será almacenada en las tablas membership_rels y acs_rels:
+
+	
+  create table acs_rels (
+      rel_id
+          not null
+          constraint acs_rels_rel_id_fk references (object_id)
+          constraint acs_rels_pk primary key,
+      rel_type
+          not null
+          constraint acs_rels_rel_type_fk references acs_rel_types (rel_type),
+      object_id_one
+          not null
+          constraint acs_object_rels_one_fk references  (object_id),
+      object_id_two
+          not null
+          constraint acs_object_rels_two_fk references  (object_id),
+      constraint acs_object_rels_un
+          unique (rel_type, object_id_one, object_id_two)
+  );
+
+	
+
+	
+  create table membership_rels (
+      rel_id
+          constraint membership_rel_rel_id_fk references  (rel_id)
+          constraint membership_rel_rel_id_pk primary key,
+      -- null means waiting for admin approval
+      member_state         varchar2(20)
+          constraint membership_rel_mem_ck
+           check (member_state in ('approved', 'banned', 'rejected', 'deleted'))
+  );
+	
+
+	Las entradas en la tabla  serían de la siguiente manera:
+
+	
+	  Instancia en acs_rel
+	  
+	    
+	      
+		rel_type
+		object_one
+		object_two
+	      
+	    
+	    
+	      
+		membership_rel
+		Papiroflexia
+		Pedro
+	      
+	      
+		membership_rel
+		Papiroflexia
+		María
+	      
+	      
+		membership_rel
+		Papiroflexia
+		Sara
+	      
+	    
+	  
+	

+
+    Otra manera de crear grupos es añadiendo subgrupos. Supón que nosotros definimos Papiroflexia China y Papiroflexia Japonesa como subgrupos de Papiroflexia. Esta información es guardada en las tablas  y composition_rels:
+
+    
+create table composition_rels (
+    rel_id
+	  constraint composition_rel_rel_id_fk references  (rel_id)
+        constraint composition_rel_rel_id_pk primary key
+);
+    
+
+    Las entradas que nos interesan serían de la siguiente manera:
+
+    
+	  Instancia en acs_rel
+	  
+	    
+	      
+		rel_type
+		object_one
+		object_two
+	      
+	    
+	    
+	      
+		composition_rel
+		Papiroflexia
+		Papiroflexia China
+	      
+	      
+		composition_rel
+		Papiroflexia
+		Papiroflexia Japonesa
+	      
+	    
+	  
+    

+
+    El significado de la relación de composición implica que si añdimos a Marcos, Teresa y Pablo a Papiroflexia China también los añdimos a Papiroflexia. Así, el modo de determinar si un usuario es miembro de un grupo es similar al problema de determinar si un objeto a un determinado contexto en la jerarquía. La relación de composición puede formar jerarquías entre los grupos debido a que esta es transitiva.
+
+    De nuevo, las búsquedas jeráquicas son costosas. En este caso lo mejor es hacer una cache de resultados de consultas mediante una tabla mantenida por triggers de la misma manera que lo hicimos en la jerarquía de objetos y contextos. El modelo de datos de Open ACS 4.X define las siguientes tablas:
+
+    
+  create table group_component_index (
+          group_id        not null
+                          constraint group_comp_index_group_id_fk
+	                  references  (group_id),
+          component_id    not null
+                          constraint group_comp_index_comp_id_fk
+	                  references  (group_id),
+          rel_id          not null
+                          constraint group_comp_index_rel_id_fk
+	                  references  (rel_id),
+          container_id    not null
+                          constraint group_comp_index_cont_id_ck
+	                  references  (group_id),
+          constraint group_component_index_ck
+          check (group_id != component_id),
+          constraint group_component_index_pk
+          primary key (group_id, component_id, rel_id)
+  ) organization index;
+
+    
+
+    
+  create table group_member_index (
+      group_id
+          not null
+          constraint group_member_index_grp_id_fk 
+          references  (group_id),
+      member_id
+          not null
+          constraint group_member_index_mem_id_fk 
+	  references  (party_id),
+      rel_id
+          not null
+          constraint group_member_index_rel_id_fk 
+	  references  (rel_id),
+      container_id
+          not null
+          constraint group_member_index_cont_id_fk 
+	  references  (group_id),
+      constraint group_member_index_pk
+          primary key (member_id, group_id, rel_id)
+  ) organization index;
+    
+  
+  
+
+
+
+
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions-tediously-explained.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions-tediously-explained.xml,v
diff -u -N -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions-tediously-explained.xml	16 Jan 2003 13:30:55 -0000	1.2
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions-tediously-explained.xml	20 Aug 2003 16:20:18 -0000	1.3
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
  
   OpenACS 4.x Permissions Tediously Explained
   
@@ -1390,5 +1396,6 @@
     
 
   
+
 
 
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml,v
diff -u -N -r1.6 -r1.7
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml	22 Sep 2002 01:01:52 -0000	1.6
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml	20 Aug 2003 16:20:18 -0000	1.7
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 Groups, Context, Permissions
 
@@ -553,8 +559,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/programming-with-aolserver.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/programming-with-aolserver.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/programming-with-aolserver.xml	10 Aug 2002 19:45:14 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/programming-with-aolserver.xml	20 Aug 2003 16:20:18 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 Programming with AOLserver
 
@@ -323,8 +329,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml,v
diff -u -N -r1.6 -r1.7
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml	24 Jun 2003 03:37:04 -0000	1.6
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml	20 Aug 2003 16:20:18 -0000	1.7
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 
 The Request Processor
@@ -232,8 +238,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/submissions.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/submissions.xml,v
diff -u -N -r1.1 -r1.2
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/submissions.xml	28 Feb 2003 05:26:59 -0000	1.1
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/submissions.xml	20 Aug 2003 16:20:18 -0000	1.2
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
   Contributions
 
@@ -15,8 +21,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/subsites.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/subsites.xml,v
diff -u -N -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/subsites.xml	10 Aug 2002 19:45:14 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/subsites.xml	20 Aug 2003 16:20:18 -0000	1.5
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
  
 Writing OpenACS &version; Application Pages
 
@@ -434,8 +440,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/templates.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/templates.xml,v
diff -u -N -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/templates.xml	30 Nov 2002 17:16:52 -0000	1.5
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/templates.xml	20 Aug 2003 16:20:18 -0000	1.6
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 Using Templates in OpenACS &version;
 
@@ -238,8 +244,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml,v
diff -u -N -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml	24 Jun 2003 03:37:04 -0000	1.2
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml	20 Aug 2003 16:20:18 -0000	1.3
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
   Advanced Topics
   
@@ -170,8 +176,3 @@
       
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml,v
diff -u -N -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml	24 Jun 2003 03:37:04 -0000	1.2
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml	20 Aug 2003 16:20:18 -0000	1.3
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
   
     Setting Up Database Objects
     
@@ -291,8 +297,4 @@
       Once both scripts are working without errors, run the create script one last time and proceed.
     
   
-  
+  
\ No newline at end of file
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-debug.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-debug.xml,v
diff -u -N -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-debug.xml	24 Jun 2003 03:37:04 -0000	1.2
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-debug.xml	20 Aug 2003 16:20:18 -0000	1.3
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
   Debugging and Automated Testing
   
@@ -79,8 +85,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-pages.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-pages.xml,v
diff -u -N -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-pages.xml	24 Jun 2003 03:37:04 -0000	1.2
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-pages.xml	20 Aug 2003 16:20:18 -0000	1.3
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
   
   Creating Web Pages
   
@@ -311,8 +317,3 @@
     
   
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml,v
diff -u -N -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml	24 Jun 2003 03:37:04 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml	20 Aug 2003 16:20:18 -0000	1.5
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
   
     Creating a Package
     
@@ -278,8 +284,3 @@
 [service0@yourserver samplenote]$
     
   
-
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/constraint-naming.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/constraint-naming.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/constraint-naming.xml	10 Aug 2002 19:39:41 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/constraint-naming.xml	20 Aug 2003 16:20:18 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
  
 Constraint naming standard
 
@@ -194,8 +200,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/design-template.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/design-template.xml,v
diff -u -N -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/design-template.xml	17 Jan 2003 17:58:01 -0000	1.5
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/design-template.xml	20 Aug 2003 16:20:18 -0000	1.6
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
   Detailed Design Documentation Template
 
@@ -400,8 +406,3 @@
   
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml,v
diff -u -N -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml	15 Jan 2003 09:46:44 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml	20 Aug 2003 16:20:18 -0000	1.9
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
   OpenACS Documentation Guide
 
@@ -802,8 +808,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/eng-standards-versioning.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/eng-standards-versioning.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/eng-standards-versioning.xml	10 Aug 2002 19:39:42 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/eng-standards-versioning.xml	20 Aug 2003 16:20:18 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 Release Version Numbering
  
@@ -165,8 +171,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/filenaming.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/filenaming.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/filenaming.xml	10 Aug 2002 19:39:42 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/filenaming.xml	20 Aug 2003 16:20:18 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 ACS File Naming and Formatting Standards
 
@@ -450,8 +456,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/plsql.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/plsql.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/plsql.xml	10 Aug 2002 19:39:42 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/plsql.xml	20 Aug 2003 16:20:18 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 PL/SQL Standards
 
@@ -233,8 +239,3 @@
  
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/psgml-mode.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/psgml-mode.xml,v
diff -u -N -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/psgml-mode.xml	10 Aug 2002 19:39:42 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/psgml-mode.xml	20 Aug 2003 16:20:18 -0000	1.5
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 Using PSGML mode in Emacs
 
@@ -220,8 +226,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/requirements-template.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/requirements-template.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/requirements-template.xml	10 Aug 2002 19:39:42 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/requirements-template.xml	20 Aug 2003 16:20:18 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
   System/Application Requirements Template
 
@@ -245,8 +251,3 @@
   
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/for-everyone/acs-faq.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/for-everyone/acs-faq.xml,v
diff -u -N -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/xml/for-everyone/acs-faq.xml	30 Nov 2002 17:17:29 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/xml/for-everyone/acs-faq.xml	20 Aug 2003 16:20:18 -0000	1.5
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 Open Architecture Community System FAQ
 
@@ -333,8 +339,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml,v
diff -u -N -r1.6 -r1.7
--- openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml	24 Jun 2003 03:37:04 -0000	1.6
+++ openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml	20 Aug 2003 16:20:18 -0000	1.7
@@ -1,3 +1,10 @@
+
+
+%myvars;
+]>
 
   OpenACS Release Notes
   
@@ -97,8 +104,3 @@
   
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/images/ext-auth.dia
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/images/ext-auth.dia,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-core-docs/www/xml/images/ext-auth.dia	20 Aug 2003 16:20:18 -0000	1.1
@@ -0,0 +1,17 @@
+��\[s�F~ϯ`ȫ�h���&�3�4Ӵ/}a�X�Z!QI�q��{V�c���&n-�I&aѧ��s�s���|Z&��:/�,=b�:��Y��χ�����~s���,_��y.pEZ���e�z5]__���,GI�F��&I8����W��2���2���R�p�χ�0�s�g�t��"ʒ,|���˫�5]�ݻ�j�t�EY��"���f�����{�T�J:�x�N���_ַݼ�J�r��8���:L�G!����1u��8��`��d��e��g�e����׺-T�	��qp[���,�&)�¤hctO���e�ǳJ����u<+�O�����1.�i��2�i��B��]�3]�����+������k�HkIx��
+طw�6���F���f�?tTn��>ɮ�E������٧�+'ǳ�����G���^ewۍ%�w&���==7�n�'*�t��-"�&|L}�=�#�i���DY�ni��%� +�HQ
+��H�emMQ��z���uf�U8�51�|[�R*���҃�<ޞO�y���7?dE��W�y������e�܀,aZEyc�l����l�ǠJ-�����H�>�FK��Jygau�B��pǯ^mQ��ӥ��N������5u�)lKSQ�"�-X�IQDx(pL(R��b��!�.��(+>�O��(j��
+��#�{z���I`��½&'bKNYmw�MG*81�C�ܳ5�C��A�#� �Q�t�#SE� }��'�����x�}��?���Y�����s�-�p���\0�1g��1&@Txn��Z�#�#�%�N����U�&�,���
+�j�ABD�&=�QO�.�^�w�ݟ��0z��S�@A�Ĕp�8Ȍ�Ċ�
+�
+d5]:�|��ÜАD�<5qj�o�I�0*{UG����j��9'Y���j眅EX�mɌ���pu�h�(8�E.'`#�m��T�Cp�姠�v  Z��vF@��aQ�/���wd/�Q�D@NkB}��5�z�F�=���4�1뚙AI1q3��,������`��br���@����,��bcz�غ�ͳd`*
+j���cOs�}�ە�>�ӽ�׽��E���o]��n�7�ȿL��
+oCvq��KĴ*� �|L�}���H��m/���$�wo/����
+a��$bJ	��)4l=K$���{�Q�b�P��C%�c`����$
+T�j��͜i�P��@����{[����bS]tk��
+k }&�Ӫ��걜��م9��j�*�:��W��u��z8��Ty9vU[7 Y��\�	�����S��������l��-�f[P_��8�R.U�Dw�4�Fd�4�)0��C~⮑m/�i�������u��I����1?�����T�m%��Oh^���Q��X
\ No newline at end of file
Index: openacs-4/packages/acs-core-docs/www/xml/images/ext-auth.png
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/images/ext-auth.png,v
diff -u -N
Binary files differ
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml,v
diff -u -N -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml	20 Jul 2003 06:00:23 -0000	1.11
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml	20 Aug 2003 16:20:18 -0000	1.12
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
   Install AOLserver 3.3oacs1
 
@@ -328,8 +334,3 @@
   ($Id$)
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/compatibility.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/Attic/compatibility.xml,v
diff -u -N -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/compatibility.xml	28 Jun 2003 05:07:07 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/compatibility.xml	20 Aug 2003 16:20:18 -0000	1.5
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
   Compatibility for required software
   
@@ -75,8 +81,3 @@
   ($Id$)
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml,v
diff -u -N -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml	24 Jun 2003 03:37:04 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml	20 Aug 2003 16:20:18 -0000	1.9
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
   Credits
 
@@ -60,8 +66,3 @@
   ($Id$)
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/macinstall.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/macinstall.xml,v
diff -u -N -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/macinstall.xml	30 Mar 2003 05:56:18 -0000	1.2
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/macinstall.xml	20 Aug 2003 16:20:18 -0000	1.3
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 OpenACS Installation Guide for Mac OS X
   There are several resources for installing on OS X.
@@ -13,8 +19,3 @@
 
   
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml	28 Jun 2003 05:07:07 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml	20 Aug 2003 16:20:18 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
   Hosting Web Sites
     
@@ -427,8 +433,4 @@
     ($Id$)
   
   
-  
+  
\ No newline at end of file
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml,v
diff -u -N -r1.9 -r1.10
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml	28 Jun 2003 05:07:07 -0000	1.9
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml	20 Aug 2003 16:20:18 -0000	1.10
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 Install OpenACS &version;
 
@@ -357,11 +363,11 @@
       
 	Create a database with the same name as our service name, service0.
     [root@yourserver root]# su - service0
-[service0@yourserver service0]$ createdb service0
+[service0@yourserver service0]$ createdb -E UNICODE service0
 CREATE DATABASE
 [service0@yourserver service0]$
 su - service0
-createdb service0
+createdb -E UNICODE service0
       
       
         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.
@@ -654,8 +660,3 @@
 
   ($Id$)
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/oracle.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/oracle.xml,v
diff -u -N -r1.10 -r1.11
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/oracle.xml	28 Jun 2003 05:07:07 -0000	1.10
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/oracle.xml	20 Aug 2003 16:20:18 -0000	1.11
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
   Install Oracle 8.1.7
 
@@ -2117,8 +2123,3 @@
   ($Id$)
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml,v
diff -u -N -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml	24 Jun 2003 03:37:05 -0000	1.8
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml	20 Aug 2003 16:20:18 -0000	1.9
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
   Install Linux and supporting software
   
@@ -130,8 +136,3 @@
   ($Id$)
   
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml	22 Jul 2003 02:54:20 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml	20 Aug 2003 16:20:18 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
   
     Install additional supporting software
 
@@ -639,8 +645,3 @@
     
   
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml,v
diff -u -N -r1.10 -r1.11
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml	28 Jun 2003 05:07:07 -0000	1.10
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml	20 Aug 2003 16:20:18 -0000	1.11
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
   Overview
 
@@ -469,8 +475,3 @@
   ($Id$)
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/postgres.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/postgres.xml,v
diff -u -N -r1.10 -r1.11
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/postgres.xml	28 Jun 2003 05:07:07 -0000	1.10
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/postgres.xml	20 Aug 2003 16:20:18 -0000	1.11
@@ -1,3 +1,10 @@
+
+
+%myvars;
+]>
+
 
   Install PostGreSQL
 
@@ -20,7 +27,7 @@
   data directory appears to be in the same place as in a source
   install; start the service; create a new group for web service
   users, and modify the postgres user's
-  environment (more
+  environment (more
   information):
       
   [root@yourserver root]# ln -s /var/lib/pgsql/data /usr/local/pgsql/data
@@ -461,8 +468,4 @@
   ($Id$)
 
 
-
+
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/quick.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/quick.xml,v
diff -u -N -r1.1 -r1.2
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/quick.xml	28 Jun 2003 05:07:07 -0000	1.1
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/quick.xml	20 Aug 2003 16:20:19 -0000	1.2
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
   Quick Install
 
@@ -23,35 +29,27 @@
         Menu > System Settings > Add/Remove
         Applications and select Database Server.
       
-      On the PostGreSQL page, do the  bullet point and step 
-      On the Aolserver page, do steps , , and 
       
-        In  on the OpenACS page, do steps , , , and 
+          
       
-      
-        In , do steps , , and 
-      
-      
-        In , do 
-      
-      
-        Browse to .  If you see a page like this, proceed with .  If not, look at  for troubleshooting information.
-      
+
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
     
   
     
-    After completing installation and restarting the server, go to  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.
+    After completing installation and restarting the server, go to  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$)
 
 
-
-
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/recovery.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/recovery.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/recovery.xml	28 Jun 2003 05:07:07 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/recovery.xml	20 Aug 2003 16:20:19 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
   
     Backup and Recovery
     
@@ -517,8 +523,4 @@
     ($Id$)
 
     
-  
+  
\ No newline at end of file
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/red-hat.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/red-hat.xml,v
diff -u -N -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/red-hat.xml	24 Jun 2003 03:37:05 -0000	1.2
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/red-hat.xml	20 Aug 2003 16:20:19 -0000	1.3
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
   
     Install Red Hat 8.0
 
@@ -289,8 +295,3 @@
     
   
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/software.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/software.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/software.xml	28 Jun 2003 05:07:07 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/software.xml	20 Aug 2003 16:20:19 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
   
     Prerequisite Software
     
@@ -468,8 +474,4 @@
     ($Id$)
     
   
-  
+  
\ No newline at end of file
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml,v
diff -u -N -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml	24 Jun 2003 03:37:05 -0000	1.5
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml	20 Aug 2003 16:20:19 -0000	1.6
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
     Support for upgrades.
   
@@ -9,11 +15,9 @@
     packages automatically.  If you haven't changed anything, no
     manual intervention should be required.  If you are running
     OpenACS prior to 4.5, upgrading will require manual effort.
-
 
-
-  Upgrading OpenACS 4.5 to 4.6
-  Checklist
+  
+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.
@@ -308,8 +312,3 @@
   ($Id$)
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/win2kinstall.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/win2kinstall.xml,v
diff -u -N -r1.6 -r1.7
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/win2kinstall.xml	30 Nov 2002 17:17:46 -0000	1.6
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/win2kinstall.xml	20 Aug 2003 16:20:19 -0000	1.7
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 OpenACS Installation Guide for Windows2000
 
@@ -493,8 +499,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/apm-design.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/apm-design.xml,v
diff -u -N -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/xml/kernel/apm-design.xml	10 Aug 2002 19:34:42 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/apm-design.xml	20 Aug 2003 16:20:19 -0000	1.5
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 OpenACS &version; Package Manager Design
 
@@ -1082,8 +1088,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml,v
diff -u -N -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml	10 Aug 2002 19:34:42 -0000	1.5
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml	20 Aug 2003 16:20:19 -0000	1.6
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 OpenACS &version; Package Manager Requirements
 
@@ -1013,8 +1019,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/bootstrap-acs.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/bootstrap-acs.xml,v
diff -u -N -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/kernel/bootstrap-acs.xml	10 Aug 2002 19:34:42 -0000	1.3
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/bootstrap-acs.xml	20 Aug 2003 16:20:19 -0000	1.4
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 Bootstrapping OpenACS
 
@@ -149,8 +155,3 @@
 ($Id$)
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/db-api.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/db-api.xml,v
diff -u -N -r1.7 -r1.8
--- openacs-4/packages/acs-core-docs/www/xml/kernel/db-api.xml	10 Aug 2002 19:34:42 -0000	1.7
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/db-api.xml	20 Aug 2003 16:20:19 -0000	1.8
@@ -1,3 +1,9 @@
+
+
+%myvars;
+]>
 
 Database Access API
 
@@ -1265,8 +1271,3 @@
 
 
 
-
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/ext-auth.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/ext-auth.xml,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/ext-auth.xml	20 Aug 2003 16:20:19 -0000	1.1
@@ -0,0 +1,933 @@
+
+
+%myvars;
+]>
+
+
+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
+accounts for people. So we want them to be able to create just one
+account on a central server (e.g. LDAP or RADIUS), and when they
+log on to OpenACS, an account will automatically be created for
+them here.
+    Finally, security is increased with fewer passwords, since
+users generally can't remember all those passwords, so they tend to
+keep them all the same and never change them.
+  
+  Design Goals
+    
+      Transparent: Users don't have to do anything special to
+        get an account on the local OpenACS system, if they already have an
+        account on the external authentication server.
+      Fall-back: Users who don't have an account on the
+        external authentication server are still allowed to create a local
+        account on OpenACS. This could be for external students who should
+        have access to .LRN, but not to the rest of the university's
+        resources.
+      Authentication Client Only: We want OpenACS to be able to
+        authenticate by asking some remote authority to verify the user's
+        username/password combination. The goal is explicitly not (at this
+        point) to have OpenACS act as an authentication server for other
+        systems, although this could be easily added later. The goal is
+        also not to devise an infrastructure for letting OpenACS access
+        resources in various other systems on the user's behalf, such as
+        IMAP, iCalendar, SMB file servers, etc., although this is
+        definitely an interesting use-case.
+      Easy configuration: We would like people to be able to
+        configure this without having to write code. In particular, we want
+        to build drivers that know how to talk with LDAP, RADIUS, PAM,
+        etc., and which won't have to be locally modified. Only
+        configuration and policies should change, code should
+        not.
+      Usability: The solution must be easy to use for end users
+        and administrators alike. There's frequently a positive feedback
+        effect between usability and security, because when authentication
+        schemes have poor usability, users will think up ways to circumvent
+        them.
+      Open and modular: The design should be on the one hand
+        open to add other authentification mechanisms when needed and on
+        the other hand very modular to enable a start with minimal
+        requirements (driver implementations) as soon as
+        possible.
+    
+    The problem can be split into several logically separate
+parts. Each has a section below.
+  
+
+  Terminology
+    
+      Authority: The name of an authority trusted to authenticate
+        users.
+      
+      Authentication Driver: An implementation of the
+        authentication service contract, which talks to an authentication
+        of a certain type, e.g. PAM, RADIUS, LDAP, or Active
+        Directory.
+      Authentication API: The API through which login pages and
+        applications talk to the authentication service. There's one and
+        only one implementation of the authentication API, namly the one
+        included in OpenACS Core.
+      Authentication Driver API: The service contract which
+        authentication drivers implement.
+    
+  
+
+  Conceptual Pictures
+    Authentication:
+    
+          
+        
+ 
+Account Management (NO PICTURE YET)
+Batch Synchronization (NO PICTURE YET)
+  
+
+  Requirements
+
+  
+  New API
+    
+      
+        
+          EXT-AUTH-01
+          A
+          Extend Authentication/Acct Status API
+        
+        
+          EXT-AUTH-03
+          A
+          Account Creation API
+        
+        
+          EXT-AUTH-05
+          A
+          Password Management API
+        
+        
+          EXT-AUTH-30
+          A
+          Authority Management API
+        
+      
+    
+
+    Login
+      
+        
+        
+          EXT-AUTH-04
+          A
+          Rewrite login, register, and admin pages to use APIs
+        
+        
+          EXT-AUTH-38
+          A
+          ad_form complain feature
+        
+        
+          EXT-AUTH-19
+          A
+          Rewrite password recovery to use API
+        
+        
+          EXT-AUTH-21
+          A
+          Rewrite email verification with API
+          
+        
+          EXT-AUTH-28
+          A
+          Username 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
+password column is used, or it can be some external authority,
+which will be communicated with using some protocol, as implemented
+by an authentication driver.
+      Username will be separate from email address. It can be an
+email address, it can look like an email address but not be the
+name of an actual email mailbox, or it can be something else
+entirely.
+      We're assuming that user information (name, email, etc.) will
+either already be in the users table through a batch
+synchronization job, or that the relevant authentication
+implementation supports real-time synchronization of user data.
+Specifically, if you want remote users who haven't yet logged in to
+OpenACS to show up in user searches, you'll have to do the batch
+synchronization.
+      All in all, the login box will be an includeable template and
+look like this:
+      
+Username:  ________
+Password:  ________
+Authority: [URZ   ]
+            Athena
+            Local
+
+[Forgot my password]
+[New user registration]
+
+ 
+     
+      If there's only one active authority, we don't display the
+authority drop-down element at all.
+    
+
+    Configuration
+      
+        
+        
+          EXT-AUTH-07
+          A
+          Admin pages to control Ext-Auth parameters
+        
+      
+      The site-wide systems administrator can configure the
+authentication process from a page linked under /acs-admin.
+      
+        Authorities - ordered list of authorities defined
+        Account Registration Allowed: Yes/No. Account
+          registration can be disabled altogether.
+        Registration authority - the authority in which accounts should
+          be created, using the relevant driver, if account registration is
+          allowed.
+        Username is email? - instead of asking for username,
+          we'll ask for email. And we'll store the value in both columns,
+          username and email. This is a setting that spans all authorities, and
+          is primarily meant for backwards compatibility with the old OpenACS
+          login process.
+      
+      The local authority driver is an encapsulation of current
+      functionality within an driver matching a service contract.  The
+      other drivers call external functions.  The possible functions
+      for each authority are split into several drivers for convenience.
+      One driver handles authentication, one account creation, and one
+      changing passwords.
+    
+
+      
+        
+        
+          EXT-AUTH-16
+          A
+          Create service contract for Authentication
+        
+        
+          EXT-AUTH-17
+          A
+          Create service contract for Acct. Creation
+        
+        
+          EXT-AUTH-29
+          A
+          Create service contract for Passwd Management
+        
+      
+      
+      
+        
+        
+          EXT-AUTH-18
+          A
+          Authority configuration data model
+          
+      
+      Each authority is defined like this:
+      
+        Authority pretty-name, e.g. "URZ"
+        Authentication Driver, e.g. "RADIUS". In practice, this
+          would be a reference to a service contract
+          implementation.
+        Authentication Driver configuration settings, e.g. host
+          name, port, etc., as required by the particular driver. Note that
+          this is per authority, not per driver, i.e., you can have multiple
+          authorities with the same driver but different configuration
+          options.
+        AuthenticationAllowed - true/false, so you can disable
+          login through some authority without having to delete the authority, and
+          hence also all the users who belong to that authority.
+        ForgottenPasswordUrl - a URL to redirect to instead of
+          trying to use the authentication driver's password management
+          features.
+        ChangePasswordUrl - a URL to redirect to instead of
+          trying to use the authentication driver's password management
+          features.
+        Account Creation Driver, e.g. "RADIUS". In practice, this
+          would be a reference to a service contract implementation. The
+          reason we have separate drivers for authentication and account
+          creation is that organizations are likely to have a home-grown
+          account registration process.
+        Account Creation Driver configuration settings, e.g. host
+          name, port, etc., as required by the particular driver. Note that
+          this is per authority, not per driver, i.e., you can have multiple
+          authorities with the same driver but different configuration
+          options.
+        RegistrationUrl - instead of registering using OpenACS,
+          redirect to a certain URL site for account registration.
+        RegistrationAllowed - true/false, so you can disable
+          registration using this account.
+        Sort order: Preference order of
+        authorities.
+        HelpContactText: Text or HTML to be displayed
+        when user has trouble authenticating with the authority.
+        Should include contact information such as a phone number or email.
+      
+      Each authority driver will have a set of configuration options
+dependent on the driver, such as host, port, etc. We will need to
+find a mechanism for the driver to tell us which configuration
+options are available, a way to set these, and a way for the driver
+to access these settings.
+      OpenACS will come pre-configured with one authority, which is
+the "local" authority, meaning we'll authenticate as normal using the
+local users table. This will, just like any other authority, be
+implemetned using a service contract.
+    
+
+    Synchronizing
+and Linking Users
+      
+        
+        
+          EXT-AUTH-28
+          A
+          Create service contract for Batch Sync.
+        
+        
+          EXT-AUTH-38
+          A
+          Batch User Synchronization API
+        
+
+        
+          EXT-AUTH-38
+          A
+          IMS Synchronization driver
+        
+        
+          EXT-AUTH-08
+          A
+          Automation of batch Synchronization
+        
+        
+          EXT-AUTH-15
+          B
+          On-demand syncronization
+        
+      
+      
+      Regardless of the login method, the user needs to have a row
+in the OpenACS users table. This can happen through a batch job, in
+real-time, or both in combination.  We use the IMS Enterprise 1.1 specification. 
+      Batch job means that we do a synchronization (import new
+users, modify changed, purge deleted) on a regular interval, e.g.
+every night. You can also decide to have a monthly full
+synchronization, plus daily incremental ones. That's up to you. The
+advantage is that you have all users in OpenACS, so when you search
+for a user, you'll see all the organization's users, not just those
+who happen to have used the OpenACS-based system. The down-side is
+that it takes some time for user information to propagate. This can
+be remedied by using the real-time solution.  The batch job will also
+require error logging and an admin interface to view logs.
+      If an email already belongs to some
+other user, we log it as an error.
+      A user will always belong to exactly one authority, which can be
+either the "local" authority or some other. Thus, the OpenACS user's
+table will have to be augmented with the following columns:
+      
+        Authority. Reference to the site-wide authorities list. The
+          authority which can authenticate this user.
+        Authority-specific username.
+      
+      Real-time means that the first time the user logs into
+OpenACS, we'll query the authority that authenticated him
+for information about this user. That authentication authority will
+then give us at least first names, last name and email. The pros
+and cons are the opposite of batch jobs. Using both in combination
+is ideal.
+      Note: One solution to the "two users from different authorities
+have the same email" problem above would be to allow users to
+belong to multiple authorities. Then we would notice that the email
+already exists, ask the user if he thinks he's the same person, and
+if so, ask him to prove so by authenticating using the other
+authority. Thus he'll have just authenticated in two different
+authorities, and we can record that this is the same person. We'd still
+have a problem if there was an email conflict between two accounts
+on the same authority. Hm. I don't think it's worth spending too much
+time trying to solve this problem through software.
+      
+        
+        
+          EXT-AUTH-31
+          A
+          Upgrade user data model for ext-auth
+          
+      
+      After having authenticated using the relevant authority driver,
+we'll look for the username/authority pair in the users table.
+      If we don't find any, that means that we're either not doing
+batch synchronizing, or that the user has been added since the last
+sync. In that case, we'll try to do a real-time synchronization, if
+the driver supports it. If it does, it'll return email,
+first_names, last_name, and other relevant information, and we'll
+create a row in the local users table using that
+information.
+      If that doesn't work, we'll tell the user that their account
+isn't yet available, and the driver will supply a message for us,
+which could say "The account should be available tomorrow. If not,
+contact X."
+    
+
+    Account
+Registration
+      If a user doesn't have an account, the site-wide
+configuration can allow the user to register for one, as defined in
+the configuration discussed above. This section is about normal
+account registration through a authority driver.
+      The account creation service contract implementation will
+need to tell us which information to ask the user for:
+      
+        Required Fields: A list of fields which are
+          required.
+        Optional Fields: A list of fields which are
+          optional.
+      
+      The fields to choose from are these:
+      
+        Username
+        First names
+        Last name
+        Email
+        URL
+        Password
+        Secret question
+        Secret answer
+      
+      It should return the following:
+      
+        Creation status (OK, Try-Again, Fail)
+        Creation message: What went wrong, or a welcome
+          message.
+        Account status: Is the account ready for use?
+        User information: first_names, last_name, email, url,
+          password, password_hash, secret_question, secret_answer. The driver
+          only needs to return the columns which were changed or added
+          through the registration process. Typically, only the "local"
+          driver will return password and secret question/answer.
+      
+      After creating the remote account, a local account is created
+with the information gathered through the form/returned by the
+driver.
+      By default, a local account creation implementation is
+provided, which will create a new OpenACS user, and, in addition to
+the default local account creation above, also store the password
+in hashed form.
+    
+
+    Password
+Management
+      Password management is about changing password, retrieving
+password, and resetting password.
+      It's up to the authority driver implementation to decide whether
+to support any or all of these features, and to say so using the
+CanXXX methods (see driver API below).
+      Additionally, the authority can be configured with a URL to
+redirect to in the case of forgotten passwords, or when the user
+desires to change password.
+    
+
+    Login Pages Over
+HTTPS
+      
+        
+        
+          EXT-AUTH-20
+          A
+          Login over HTTPS
+          
+      
+      Login pages must be able to be sent over a secure connection
+(https), so your password won't get sent over the wire in
+cleartext, while leaving the rest of the site non-secure (http). I
+believe that this requires some (minor) changes to the current
+session handling code.
+    
+
+    Email
+Verification
+      Email verification needs to be handled both at registration
+and at login.
+      In both cases, it'll be handled by the driver sending
+automatically sending the email containing a link for the user to
+verify his account. Then the driver will return an account status
+of "closed,temporary", and a message that says ""Check your inbox
+and click the link in the email".
+      OpenACS will have a page which receives the email
+verification, for use by local accounts. Other authorities will
+have to implement their own page, most likely on the authority's
+own server.
+    
+
+  Other Items
+    There are a number of items which touch on external
+authentication and session management. And even though they're not
+directly linked to external authentication, I would recommend that
+we handle a number of them, either because they're important for
+security, or because it makes sense to fix them while we're messing
+with this part of the codebase anyway.
+
+
+    Recommended:
+Untrusted Logins and Login Levels
+      
+        
+        
+          EXT-AUTH-33
+          A
+          Untrusted Logins
+        
+      
+      I like the idea of having multiple login levels:
+      
+        Not logged in
+        Untrusted login: We'll show you un-sensitive personal
+          content, but won't let you modify anything or see personal data. A
+          normal login becomes untrusted after a certain amount of time, and
+          the user will have to re-enter his/her password in order to gain
+          access to personal data. Untrusted login never expires, unless
+          explicitly done so through either changing password or clicking a
+          special "expire all logins" link.
+        Normal login: The user is logged, and has type his
+          password sufficiently recently that we trust the login. All normal
+          operations are allowed. Will degrade to untrusted login after a
+          specified amount of time.
+        Secure login: The user is logged in over a secure
+          connection (HTTPS), potentially even using a special secure
+          password. This would be for sensitive actions, such as credit card
+          transactions.
+        
+      There are two advantages to this. First, when people's login
+expires, we can ask them to re-enter only their password, and not
+both username and password, since we'll still remember who they
+were the last time their login was valid. This is a much faster
+operation (the password input field will be focused by default, so
+you just type your password and hit Return) that typing both
+username and password, which will make it practical to have your
+site configured to expire people's login after e.g. 2, 4, or 8
+hours.
+      The other advantage is that we can still offer certain
+functionality to you, even when your login is not trusted. For
+example, we could let you browse publically available forums, and
+only when you want to post do you need to log in. This makes it
+even more feasible to have a more secure login expiration
+setting.
+      By default, auth::require_login would
+bounce to the login page if the user is only logged in at the
+untrusted level. Only if you explicitly say
+auth::require_login -untrusted will we give you
+the user_id of a user who's only logged in in untrusted
+mode.
+      Similarly, ad_conn user_id will continue
+to return 0 (not logged in) when the user is only logged in
+untrusted, and we'll supply another variable, ad_conn
+untrusted_user_id, which wlll be set to the user_id for
+all login levels.
+      This should ensure that we get full access to the new
+feature, while leaving all current code just as secure as it was
+before.
+    
+
+    Recommended:
+Make Non-Persistent Login Work
+      
+        
+        
+          EXT-AUTH-34
+          A
+          Expire Logins
+        
+      
+      Currently, OpenACS is unusable in practice without persistent
+login. The login will expire after just a few minutes of
+inactivity, and you'll get bounced to the login page where you have
+to enter both email and password again. Unacceptable in
+practice.
+      We should change the default, so a non-persistent login
+doesn't expire until you either close your browser, or a few hours
+have elapsed. Even if you are constantly active, the login should
+still expire after at most x number of hours. We can still make the
+login expire after a period of inactivity, but the amount of time
+should be configurable and default to something reasonable like an
+hour or so.
+      This will require looking into and changing the design of the
+current session handling code.
+    
+
+    Recommended:
+Single-Sign-On
+      
+        
+        
+          EXT-AUTH-23
+          
+          Single sign-on
+          
+      
+      Instead of redirecting to the login page, auth::require_login
+can redirect to an authentication server, which can redirect back
+to a page that logs the user in. This should be very easy to
+implement.
+      Alternatively, if you want to combine this with fallback to
+OpenACS accounts, we would instead present the normal login screen,
+but put a button which says "Login using X", where X is the
+redirection-based external authority.
+    
+
+    Recommended:
+Expire All Logins
+      
+        
+        
+          EXT-AUTH-22
+          B
+          rewrite cookie handling
+          
+      
+      Currently, if you've ever left a permanent login cookie on
+someone elses machine, that person will be forever logged in until
+he/she explicitly logs out. You can change your password, you can
+do anything you want, but unless a logout is requested from that
+particular browser, that browser will be logged in forever.
+      I want to change our session handling code so that old login
+cookies can be expired. This would be done automatically whenever
+you change your password, and we could also offer a link which does
+this without changing passwords. It's an important security
+measure.
+      The implementation is simply to autogenerate some secret
+token which is stored in the users table, and is also stored in the
+cookie somehow. Then, whenever we want to expire all logins, we'll
+just regenerate a new secret token, and the other cookies will be
+void. Of course, we don't want to incur a DB hit on every request,
+so we'll need to cache the secret token, or only check it when
+refreshing the session cookie, which, I believe, normally happens
+every 10 minutes or so.
+    
+
+    Recommended:
+Email account owner on password change
+      
+        
+        
+          EXT-AUTH-24
+          A
+          Email on password change
+          
+      
+      As an additional security measure, we should email the
+account's email address whenever the password is changed, so that
+he/she is at least alerted to the fact.
+    
+
+    Optional:
+Password policy
+      
+        
+        
+          EXT-AUTH-25
+          A
+          Implement password policy
+          
+      
+      Again, to increase security, we should add password policies,
+such as passwords needing to be changed after a certain number of
+days, change on next login (after a new random password has been
+generated), or requiring that the password satisfies certain
+complexity rules, i.e. both upper and lowercase characters,
+numbers, special chars, etc.
+      It would good to extend the current maximum password length
+from 10 to at least 32 characters.
+    
+
+    Optional:
+Login Without Explicit Authority
+      
+        
+        
+          EXT-AUTH-26
+          B
+          Login without explicit domain
+          
+      
+      In order to make it easier for people, we've been toying with
+the idea of a functionality like this:
+      
+        If the user enters "foobar@ix.urz.uni-heidelberg.de", it
+          is translated to mean username = "foobar", authority =
+          "ix.urz.uni-heidelberg.de".
+        If the user enters "foobar", it's recognized to not
+          include any authority, and the default authority of
+          "ix.urz.uni-heidelberg.de" is used.
+        If the user enters "foo@bar.com", it's recognized as not
+          belonging to any known authority, and as such, it's translated to mean
+          username = "foo@bar.com", authority = "local".
+      
+      If this is deemed desirable, a way to implement this would be
+through these settings:
+      
+        Split: A regexp which will split the user's entry into
+          username and authority parts. For example "^([^@]+)(@[^@]+)?$". An
+          easier to use but less flexible method would be that you simply
+          specify a certain character to split by, such as "@" or "\". If the
+          regexp doesn't match, or in the latter case, if there's more than
+          one occurrence of the specified character sequence, the split will
+          fail, signaling that the user's entry was not valid.
+        Default authority: The default authority will be the first one
+          in the sort order.
+      
+      The relevant code in user-login.tcl would look like
+this:
+      
+if { ![auth::split_username -username_var username -authority_var authority] } {
+    # bounce back to the form with a message saying that the login wasn't valid.
+    ad_script_abort
+}
+
+# username will now contain username
+# authority will now contain authority
+
+
+    
+
+    Optional: Who's
+Online
+      
+        
+        
+          EXT-AUTH-27
+          B
+          Who's online list
+          
+      
+      While we're touching the session handling code, anyway, it
+would be nice to add a feature to show who's currently online, a
+nice real-time collaboration feature frequently requested by
+members of the community. This is particularly interesting when
+integrated with a chat or instant messaging service like
+Jabber.
+      What I'm concretely suggesting is that we keep a record of
+which authenticated users have requested pags on the site in the
+last x minutes (typically about 5), and thus are considered to be
+currently online. There's nothing more to it. This lets us display
+a list of "active users" somewhere on the site, and make their name
+a link to a real-time chat service like Jabber.
+      We've already made the changes necessary to
+security-procs.tcl to do this on an earlier project, but haven't
+quite finished the work and put it back into the tree.
+    
+
+    Optional:
+Subsite-level configuration
+      
+        
+        
+          EXT-AUTH-28
+          
+          implement subsite-level config
+          
+      
+      If we want to, we could let subsite administrators configure
+the login process for that particular subsite. This would probably
+only entail letting the subsite admin leave out certain authorities
+defined site-wide, and change the sort order.
+      I think we should leave this out until we have a use case for
+it, someone who'd need it.
+    
+
+    Future:
+Making the Authentication API itself a service contract
+      
+        
+        
+          EXT-AUTH-32
+          A
+          Parameters for Service Contract Implementation
+        
+        
+          EXT-AUTH-35
+          A
+          Make the Authentication API a service contract
+        
+      
+      For completely free-form authentication logic and mechanisms,
+something like Andrew Grumet's
+Pluggable
+Authentication for OACS Draft is interesting. He's
+proposing a scheme where the entire user interaction is
+encapsulated in, and left entirely to, a service contract. This
+certainly opens up more advanced possibilities, such as perhaps
+smart cards, personal certificates, etc.
+      I have chosen not to go this route, because I think that most
+people are going to want to use a username/password-based scheme,
+and having easy configuration through a web UI is more important
+than total flexibility at this point.
+      Besides, we can always do this in the future, by letting the
+public Authentication API (auth::require_login
+and auth::authenticate) be implemented through a
+service contract.
+    
+
+    Future:
+Authenticating against multiple servers simultaneously
+      
+        
+        
+          EXT-AUTH-36
+          A
+          Authenticate against multiple servers
+        
+      
+      Both OKI and OpenACS supports a form of stacking, where you
+can be logged into multiple authorities at the same time. This is
+useful if, for example, you need to get login tokens such as
+Kerberos tickets for access to shared resources.
+      I can see the value in this, but for simplicity's sake, I'm
+in favor of keeping this use-case out of the loop until we have
+someone with a real requirement who could help us guide
+development.
+      For now, OpenACS is still more of an integrated suite, it
+doesn't access many outside applications. I think it would be
+excellent for OpenACS to do so, e.g. by using an IMAP server to
+store emails, an iCal server to store calendar appointments, LDAP
+for user/group data and access control lists, SMB for file storage,
+etc. But at the moment, we don't have any users of such things that
+are ready. We have some who are on the steps, but let's wait till
+they're there.
+    
+    
+      Implement
+Specific Drivers
+      
+        
+        
+          EXT-AUTH-09
+          A
+          Create Auth. drivers for Local Authority
+        
+        
+          EXT-AUTH-10
+          A
+          Create Acct. Creation driver for Local Authority
+        
+        
+          EXT-AUTH-11
+          A
+          Create Auth. driver for PAM
+        
+        
+            EXT-AUTH-12
+            X
+            Create Acct. Creation driver for PAM - this
+          functionality is explicitly excluded from PAM
+        
+        
+          EXT-AUTH-13
+          A
+          Create Acct. Creation driver for LDAP
+        
+        
+          EXT-AUTH-14
+          A
+          Create Auth. driver for LDAP
+        
+      
+      We'll need drivers for:
+      
+        Operating system (Linux/Solaris) PAM: Delegate to the
+          operating system, which can then talk to RADIUS, LDAP, whatever.
+          This is convenient because there'll be plenty of drivers for the OS
+          PAM level, so we don't have to write them all ourselves. The
+          downside is that we can't do things like account creation, password
+          management, real-time account synchronization, etc., not supported
+          by PAM (I'm not entirely sure what is and is not
+          supported).
+        RADIUS
+        LDAP
+      
+      RADIUS
+        RADIUS is a simple username/password-type authentication
+server.
+        It also supports sending a challenge to which the user must
+respond with the proper answer (e.g. mother's maiden name, or could
+be additional password), but we will not support this
+feature.
+        A RADIUS client
+implementation
+in Python can be found in the
+exUserFolder
+module for Zope
+(documentation).
+      
+    
+  
+
+  Feedback
+    We'd really appreciate feedback on this proposal. Please
+follow up at
+this
+openacs.org forums thread.
+  
+
+  References
+    
+      
+              IMS Enterprise
+      
+      Threads
+and links collected by Carl Blesius.
+      Solaris/Linux
+PAM specification
+      Draft
+Proposal by Andrew Grumet.
+      Yale
+CAS, a centrl authentication service a' la
+        Passport.
+    
+    
+  
+  Revision History
+
+   
+     
+

Prev		Next

Prev		Next

Prev		Next

Prev		Next

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

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

Prev	Part�III.�For OpenACS Package Developers	Next

a1	b1	c1
a2	b2	c2
a3	b3	c3

a1	b1	c1
a2	b2	c2
a3	b3	c3

Prev	Home
Documenting Tcl Files: Page Contracts and Libraries	Up

OpenACS Version		3.2.5	4.5	4.6	4.6.1	4.6.2	4.6.3
AolServer	3	Verified	�	�	�	�	�
	3.3+ad13	�	Verified
	3.3oacs1	�	�	�	�	Verified
PostGreSQL	7.0	Verified	�	�	�
	7.2.x	�	Verified
	7.3.2	Not compatible					Untested
Oracle	8.1.6	�	Verified
	8.1.7	�	Verified
	9i	No

Administrator's Guide

Administrator's Guide

For OpenACS Platform Developers

For OpenACS Platform Developers

Install AOLserver 3.3oacs1

Install AOLserver 3.3oacs1

OpenACS 4.7.0d Package Manager Design

OpenACS 5.0.0d Package Manager Design

Essentials

Essentials

Competitive Analysis

Authors

Revision History

Revision History

OpenACS 4.7.0d Package Manager Requirements

OpenACS 5.0.0d Package Manager Requirements

Revision History

Revision History

A full Backup/Recovery cycle

Delete the Service

A full Backup/Recovery cycle

Delete the Service

Bootstrapping OpenACS

Bootstrapping OpenACS

Credits

Credits

Add the Service to CVS - OPTIONAL

Add the Service to CVS - OPTIONAL

Database Access API

Database Access API

The OpenACS Database Access API

The OpenACS Database Access API

Chapter�11.�Development Reference

Chapter�11.�Development Reference

Overview of OpenACS 4.7.0d Documentation

Overview of OpenACS 5.0.0d Documentation

Headlines, Sections

Code

Links

Lists

Tables

Emphasis

Revision History

Revision History

Format of constraint name

Format of constraint name

External Authentication Requirements

Vision

Design Goals

Terminology

Conceptual Pictures

Requirements

New API

Login

Configuration

Synchronizing +and Linking Users

Account +Registration

Password +Management

Login Pages Over +HTTPS

Email +Verification

Other Items

Recommended: +Untrusted Logins and Login Levels

Recommended: +Make Non-Persistent Login Work

Recommended: +Single-Sign-On

Recommended: +Expire All Logins

Recommended: +Email account owner on password change

Optional: +Password policy

Optional: +Login Without Explicit Authority

Optional: Who's +Online

Optional: +Subsite-level configuration

Future: +Making the Authentication API itself a service contract

Future: +Authenticating against multiple servers simultaneously

Implement +Specific Drivers

RADIUS

Feedback

References

Revision History

Configuration/Parameters

Future Improvements/Areas of Likely Change

Revision History