This is my (Joel Aufrecht's) list of everything that needs to be fixed or checked in the current documentation. I'm doing it as a flat page instead of in the bug system because the extra overhead of bugs seems unwarranted. Similarly I'm not tracking submitter names to save time. So a big thank you to everybody who sends documentation fixes!

>Hi this is from the tutorial.
>
>http://openacs.org/doc/openacs-HEAD/tutorial-newpackage.html
>
>I can't find any package-document-tempate.xml anywhere in my installation
>or openacs.org/cvs.
>
>I'm pretty sure you don't mean xml/docs/xml, I wonder if the name of the
>file is also wrong?
>
>Dave also thinks we want to promote a simpler template.

----------------------------------------------------------------------

broken in debian sid:

openfts install
nsopenssl compile
psql tuning (server won't start after tuning) [JCD: I think I fixed this 
  on 7.3 the wal_files parameter went away ... I removed it from the docs]

----------------------------------------------------------------------

Add automated testing documentation

----------------------------------------------------------------------

tDOM 0.7.8 doesn't compile (reported by dirkgomez)

----------------------------------------------------------------------

http://openacs.org/doc/openacs-HEAD/aolserver.html should have a 
backslash after --with-aolserver=$aolsrc 

----------------------------------------------------------------------

Steal http://rubick.com:8002//openacs/content_repository for the advanced tutorial

----------------------------------------------------------------------

Add stuff from http://openacs.org/forums/message-view?message_id=105075 for developer notes

----------------------------------------------------------------------

     I've just upgraded my Openssl to 0.97b and nsopenssl 2.1a. The change
(which was in threads.c NOT nsopenssl.h - my apology) is no longer necessary as
Openssl have reverted to THREADS.
Unfortunately, Scott's latest driver assumes OPENSSL_THREADS, and this now has
to change back!!

(can't compile with 0.9.7a and 2.1, stock.)

----------------------------------------------------------------------

-g/web/service0/etc/analog.cfg should be +g? (no)

daemontools run must be edited with service name

----------------------------------------------------------------------
cvs checkout -d openacs-upgrade -jOpenACS:yesterday -jOpenACS openacs < 
cvs.txt 2<&1

Should be

cvs checkout -d openacs-upgrade -jOpenACS:yesterday -jOpenACS openacs > 
cvs.txt 2>&1
----------------------------------------------------------------------

In the advanced section there's a bit about adding comments to the notes
themselves. This part of the document references certain notes scripts that
weren't mentioned (notes.tcl, notes.adp, notes.xql) in the rest of the
tutorial. I managed to create the scripts myself, and modify the index scripts
to link the title of the notes to the view page. I can post those scripts if
you want to include/modify them.


After I added the links to comments though, I could no longer delete the notes
due to a foreign key reference (my guess is the comments linked to the note
required the note to exist...). Anyways, the constraint that postgresql
complained about was acs_obj_context_idx_anc_id_fk. If you want I can post the
full error message.

----------------------------------------------------------------------

In http://openacs.org/doc/openacs-4-6-2/tutorial-newpackage.html in
> "Write the Requirements and Design Specs" chapter, it's said that the
> documentation template would be in
> /web/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-
> documentation-template.xml.
>
> However, it seems to be in
> /web/openacs-4.6.2/packages/acs-core-docs/www/xml/files/package-
> documentation-template.xml

----------------------------------------------------------------------

cvs cleanup tasks:

Make sure that all of the following behave as expected when checking
out HEAD or post-4.6.3 tags:

/etc/ should have files in it

/packages/acs-core-docs/www/xml/files shouldn't exist

/packages/acs-core-docs/www/files/samplenote should exist and have
files (these are missing now - might be in the CVS Attic for
/packages/acs-core-docs/www/files/samplenote files)

/packages/acs-core-docs/www/files/package-documentation-template.xml

Fixed in HEAD June 2003:

----------------------------------------------------------------------

tdom link on software page points to libxml

----------------------------------------------------------------------

>http://openacs.org/doc/openacs-4-6-2/postgres.html
>
>For installing init scripts on Red Hat, you may have to add the scripts
>to the right runlevels, which would require(note the second command):
>
>
>chkconfig --add postgresql
>chkconfig --level 35 postgresql on
>chkconfig --list postgresql
>
>This was the case, at least, when using the Red Hat RPM version of
>postgres.

----------------------------------------------------------------------
Typo: echo "export LD_LIBRARY_PATH=LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib" >> ~postgres/.bashrc

extra LD_LIBRARY_PATH

----------------------------------------------------------------------

Remove inline functions from tutorial db create scripts:

  This methodology is unfortunately also being promulgated in the
  development tutorial for oacs here. There is generally little reason
  to create an inline function if it already exists and can be called
  directly as demonstrated by Jeff in his photo-album as you point out
  and by Lars in lars-blogger just to name two examples.

----------------------------------------------------------------------

Tutorial:
> Found something amiss on http://aufrecht.org/doc/tutorial-database.html,
> the 'select define_function_args' for samplenote__new has one fewer
> args than the actual function (it's missing 'body')

----------------------------------------------------------------------

triple-underscore ___ in several function calls in tutorial-db should be __

----------------------------------------------------------------------

Detail how to Connect to a remote PostGres database
Edit the file /usr/local/pgsql/data/postgresql.conf
and change 
#tcpip_socket = false 
to  
tcpip_socket = true
and restart postgresql (service postgres restart)
----------------------------------------------------------------------

Solve this in xml build: 
  Writing upgrade-detail.html for sect1(upgrade-detail)
  No template matches a in para.
----------------------------------------------------------------------

Some of the links to "view comments on this at openacs" and to post
comments are "File not found" from the 4.6.2 Development Tutorial in
the "Creating a Package"  section. Also from the "Full Index" the
"Upgrading OpenACS 4.5 to 4.6" section gives "File not found."
----------------------------------------------------------------------

explain the tar options in backup-recovery.html

in openacs.html, near "If you are using port 80, you must be root for
this step."
  first, shouldn't do killall nsd because it could stomp on other

  servers
  second, if running root, need -u and -g flags, so probably put them
  all in
----------------------------------------------------------------------


This was a bit astonishing, why is there a difference:

debian:/usr/local/aolserver/bin# chmod 750 nsd-oracle
debian:/usr/local/aolserver/bin# chmod 755 nsd-postgres

----------------------------------------------------------------------
add ns_param   .doc               application/vnd.ms-word
to config.tcl

----------------------------------------------------------------------
Should add the maintenance guide to the shortlist in index.adp

----------------------------------------------------------------------

Joel, I just noticed that your revised Oracle install docs:
  

don't seem to say to use UTF8 rather than ASCII7 for the database
character set.  You definitely want that.  I added a comment here:

  

And you can also find more info in my install notes here:

  

This is the info:


Running dbassist (use UTF8 !):

VERY IMPORTANT!
Run dbassit to prepare to create a database, per the OpenACS
instructions.  But at the screen where you enter "ora8" for the
"Global Database Name", also click "Change Character Set" and
select "UTF8".  I don't know what the significance of
"Character Set" vs. "National Character Set" is, so I just picked UTF8
for both.

----------------------------------------------------------------------

Add more links to acs-core-docs/www/index.adp so that it can also be the index page of openacs.org/doc, replacing the current etp.  This will make it easier to maintain a constant link (openacs.org/doc) for current documentation.

http://openacs.org/forums/message-view?message_id=105795

----------------------------------------------------------------------

Also, in the config section which is added to the aolserver config, I had to change the

ns_section "ns/server/{$servername}/module/nssopenssl"

to

ns_section "ns/server/{$server}/module/nssopenssl"
----------------------------------------------------------------------

Add a hint to upgrade to upgrade the kernel first and then go back and do the rest.


----------------------------------------------------------------------

I just installed aolserver on my Debian woody laptop. Here's the amendments
for :

http://openacs.org/doc/openacs-4-6-2/aolserver.html

I took stock AOLserver 3.3+ad13 and the makefiles make some assumptions about
include and bin file locations that are not correct on Debian. I rather use
symbolic links than mess around with the makefiles:

You need this to make the pgdriver compile:

debian:# ln -s /usr/include/postgresql/ /usr/include/pgsql

The nsd-postgres makes assumptions where the bin and the lib dir are. You need
this symbolic link if you don't want to change it:

debian:# ln -s /usr/lib/postgresql /usr/local/pgsql

----------------------------------------------------------------------

consolidate all old release notes in one html doc

----------------------------------------------------------------------

update the compatibility matrix with notes from the forum post

----------------------------------------------------------------------

create /doc/oldversions (is now
http://openacs.org/projects/openacs/doc-project/olddocs)

----------------------------------------------------------------------

added restart-aolserver for daemontools

----------------------------------------------------------------------

get docs to run qmail supervised

----------------------------------------------------------------------

Check the bug system for doc bugs.

debian nsopenssl - fixed
openacs.xml should point to aolserver.com/docs/admin/config.html - fixed

----------------------------------------------------------------------

in debian, create user with useradd -g web -d /web/service0 service0

----------------------------------------------------------------------

put in dummy files for these: 

ns_param   NotFoundResponse     "/global/file-not-found.html"
ns_param   ServerBusyResponse   "/global/busy.html"
ns_param   ServerInternalErrorResponse "/global/error.html"
ns_param   ForbiddenResponse    "/global/forbidden.html"
ns_param   UnauthorizedResponse "/global/unauthorized.html"

----------------------------------------------------------------------

Make a quick start guide