Index: WAeUP_Doc/ExtendedInstructions/1InstallingZope.rst
===================================================================
--- WAeUP_Doc/ExtendedInstructions/1InstallingZope.rst	(revision 1617)
+++ WAeUP_Doc/ExtendedInstructions/1InstallingZope.rst	(revision 1617)
@@ -0,0 +1,596 @@
+============================================
+Installing Zope (for training purposes only)
+============================================
+-----------------------
+A [not so] Quick Primer
+-----------------------
+
+To deploy the WAeUP Student Registration Portal on your computer, you
+first have to set up a running Zope instance. These are installation
+instructions for Windows and Linux. Please note, that the recommended
+platform for production use is Linux due to advanced security and
+availability of service. However for testing you can freely use the
+operating system you like.
+
+General Remarks
+---------------
+
+Any running Zope installation consists of at least an installed Zope
+binary and a Zope instance. It is important to distinguish Zope
+installations from Zope instances. Usually, you only have *one
+installation of a certain Zope version* installed (in case of WAeUP:
+version 2.9.3), while there might be *several Zope instances* installed
+based on the one Zope installation, but located at different locations
+in the filesystem.
+
+A special case, common on Windows but unusual on Unix-machines, is, to
+install an instance of Zope in the same directory, where the mean Zope
+installation is located. For the Zope-administrator it is then
+difficult to see a difference between the Zope installation and the
+Zope instance, but the difference indeed exists.
+
+Further complications arise from the fact, that the term
+'install/start/stop/use Zope' often really means a Zope instance, but
+only speaks of 'Zope' in general. You might keep in mind, that after
+installing Zope instances and going into production use, you rarely
+handle with Zope installations, but mostly with Zope instances. The
+thing you start, when you start 'a Zope' is technically a Zope
+instance, which in turn deploys a Zope installation. Also the thing,
+which answers HTTP-Requests in a running 'Zope-System' is an Zope
+instance. Have a look at the following figure:
+
+  .. image:: ./zinstancesetup.png
+
+*Fig. 1: Zope Overload*
+
+A (obviously overloaded) system with two Zope versions installed and
+five instances, which listen on five different ports. A browser is
+connected to port 8082, which is served by the 'waeup'-instance, which
+in turn deploys a Zope 2.9.3 installation (sharing it with two other
+instances).
+
+
+Installing Zope on Windows
+---------------------------
+
+TODO
+
+Installing Zope on Linux
+------------------------
+
+Zope can be installed and instances be run by any user, who has access
+to the system. The highly recommended kind of Zope-install on Linux is
+to grab the source code and build the installation on your system
+directly.
+
+The install is not as complicated, as the length of this document
+might suggest. The length is a result of the authors logorrhoea, not
+of overwhelming complexity of the topic.
+
+If you are in a hurry and only want the short version, here are the
+essential steps. Log into your system as a normal user, go to your
+home directory and do:
+
+  ::
+
+    ~$ wget http://www.zope.org/Products/Zope/2.9.3/Zope-2.9.3.tgz
+    ~$ mkdir -p zope/base zope/build zope/pkgs zope/instances
+    ~$ cp Zope-2.9.3.tgz zope/build
+    ~$ mv Zope-2.9.3.tgz zope/pkgs   
+    ~$ cd zope/build
+    ~/zope/build$ tar -xzf Zope-2.9.3.tgz
+    ~/zope/build$ cd Zope-2.9.3
+    ~/zope/build/Zope-2.9.3$ ./configure --prefix=/home/user/zope/base/2_9_3
+    ~/zope/build/Zope-2.9.3$ make
+    ~/zope/build/Zope-2.9.3$ make install
+    ~/zope/build/Zope-2.9.3$ /home/user/zope/base/2_9_3/bin/mkzopeinstance.py -d /home/user/zope/instances/myinstance1 -u user:secret
+    ~/zope/build/Zope-2.9.3$ /home/user/zope/instances/myinstance1/bin/zopectl start
+
+  *Fig. 2: Zope install on Linux / Short version*
+
+This should work on most systems. However, there are many error
+sources and if something goes wrong, you have to understand what is
+happening in each of steps. Explaining this is something, long
+versions are made for.
+
+
+  1. *Get the sources*
+
+     Get the Zope sources from http://www.zope.org/. For the
+     WAeUP-portal you currently need the 2.9.3 version of Zope, which can
+     be found here: http://www.zope.org/Products/Zope/2.9.3/Zope-2.9.3.tgz
+
+     Using the commandline you might change to your home directory ('cd') and
+     do (the dollar-sign here and elsewhere denotes the commandline
+     prompt, the tilde in front of the dollar sign means: 'home directory'):
+
+       ::
+
+	 ~$ cd
+         ~$ wget http://www.zope.org/Products/Zope/2.9.3/Zope-2.9.3.tgz
+         --16:03:00--  http://www.zope.org/Products/Zope/2.9.3/Zope-2.9.3.tgz
+               => `Zope-2.9.3.tgz'
+         Resolving www.zope.org... 63.240.213.171
+         Connecting to www.zope.org|63.240.213.171|:80... connected.
+         HTTP request sent, awaiting response... 200 OK
+         Length: 8,010,113 (7.6M) [application/x-gzip]
+
+         100%[====================================>] 8,010,113    203.30K/s    ETA 00:00
+
+         16:03:50 (156.42 KB/s) - `Zope-2.9.3.tgz' saved [8010113/8010113]
+
+
+  2. *Create a Zope directory tree*
+
+     If you did not do already, it is adviceable to create a directory
+     structure which enables you to find all your Zope installations
+     and instances at a well defined place. Otherwise you might get
+     lost in the many directories and subdirectories usually created
+     by Zope.
+
+     You can indeed use the tool of your choice for creating
+     directories. For example the file-manager of your favourite window
+     manager. Note however, that on many servers, you might going to
+     administer on the internet later on, there is no such thing like
+     a GUI installed (for good reason: GUIS on servers are
+     unneccessary performance killers). I therefore, in the following
+     example, show, how to create the directory structure on the
+     commandline.
+
+     We create the following directory structure:
+
+     .. image:: ./zopedirtree1.png
+
+     The directory tree contains a common subdirectory 'zope/' to keep
+     all Zope related stuff apart from other user related data. It
+     ends up in four leafs, which purposes are as follows:
+
+       * *base/ -- The Zope installation directory*
+
+         This directory holds the finished (compiled etc.) Zope
+         installations (*not* the instances which have got their own
+         directory). It will later on contain one subtree for each
+         Zope version installed.
+
+       * *build/ -- Helper directory for building Zope from source*
+
+         This directory will be the place, where we start the
+         installation. Its purpose is to have a place, where we can
+         build (compile etc.) Zope, without having too much unused
+         files laying around. Strictly speaking, after having built
+         and installed Zope once, there is no need to keep the
+         building directory and you might remove it afterwards.
+
+       * *pkgs/ -- Repository for packages downloaded*
+
+         Also this directory is not neccessary, to build
+         Zope. It is a place to store packages, downloaded from the
+         internet, especially Zope products or Zope
+         source-tarballs. It comes in handy, if you want to keep
+         packages for later use. We will use it to keep a backup of
+         the Zope sources and CPS products, so we do not have to
+         download them from internet everytime we create a new
+         instance. 
+
+       * *instances/ -- The Zope instances directory*
+
+         The most important directory in daily use. Here we create our
+         Zope instances and here we will spend the most time, once,
+         one or more insances are created and run.
+
+     As you might already guessed, there is no need to create such a
+     directory structure. Furthermore you can give the directories
+     other names, whatever you like. In daily work it turned out, that
+     such a directory tree is very handy and it tends to be a kind of
+     best practice, to use it.
+
+     On the commandline the directory tree is created like so:
+
+       ::
+
+         ~$ mkdir zope
+         ~$ mkdir zope/base zope/build zope/pkgs zope/instances
+
+  3. *Unpack the sources*
+
+     The sources are packed in a so-called 'tarball', which is denoted
+     by the file extension 'tgz', a short form of 'tar.gz'.
+
+     Now, as we freshly created a directory for building, we first copy
+     the downloaded tarball containing the Zope sources to the build
+     directory: 
+
+       ::
+
+         ~$ cp Zope-2.9.3.tgz zope/build
+
+     Afterwards we put the sources into the pkgs-directory to keep it
+     for later use (and remove it from our home directory):
+
+       ::
+
+         ~$ mv Zope-2.9.3.tgz zope/pkgs
+
+     The command 'mv' *moves* a file to a different location, thereby
+     deleting the old file.
+
+     Now we can change to the build-directory and unpack the sources:
+
+       ::
+
+         ~$ cd zope/build
+         ~/zope/build$ tar -xzf Zope-2.9.3.tgz
+
+     The commandline options 'xzf' mean: e(x)tract the file, un(z)ip the
+     file and do the whole operation on the (f)ile Zope-2.9.3.tgz.
+
+     This creates a new subdirectory 'Zope-2.9.3' with all required
+     sources.
+
+  4. *Build Zope base*
+
+     Change to the sources directory:
+
+       ::
+
+         ~/zope/build$ cd Zope-2.9.3
+
+     Here you can find a file configure, which is most important, to
+     get all compile time options, supported by your Zope version. You
+     can view them by calling './configure --help':
+
+       ::
+
+         ~/zope/build/Zope-2.9.3$ ./configure --help
+
+         configure [--help] [--quiet] [--with-python=path] [--prefix=path]
+
+         Create a Makefile suitable for building Zope
+
+         Options:
+          --help              shows usage and quits
+          --quiet             suppress nonessential output
+          --with-python       specify a path to a Python interpreter to use
+          --prefix            specify an installation path for binary data
+
+         Given no options, configure will search your PATH for a suitable
+         Python interpreter and use '/usr/local/Zope-2.9.3' as a prefix.
+
+     Basically, it tells you, that you can give a special Python
+     version to build Zope and an installation path. Usually, it is
+     best to let the configure script look for an appropriate Python
+     interpreter.
+
+     Note, that for building Zope you not only have to provide a
+     running Python interpreter (preferably version 2.4.3), but also
+     the header files and related developer files of your Python
+     installation. Usually on Linux those packages are called
+     python-dev or similar. The exact package name depends on your
+     distribution. 
+
+     On Debian/Ubuntu based systems you can install the package
+     'python2.4-dev', which has to be done as superuser (denoted by
+     the '#'-sign in the follwing):
+
+       ::
+
+         ~# apt-get install python2.4-dev
+
+     While the Python developer files are rarely installed on usual
+     end-user systems (except Zope users), the most systems already
+     have a C-compiler (most common on Linx: gcc) installed, which you
+     need too to build Zope. If Zope complains while building about
+     unknown files or similar, make sure you have intalled the 'gcc'
+     and the Python developer files. Consult your distributions'
+     documentation to learn, how to do this.
+
+     To start the real built, we give the 'configure'-script a
+     prefix-option, which tells, that we want to have installed Zope
+     in the base/ directory:
+
+       ::
+
+         ~/zope/build/Zope-2.9.3$ ./configure --prefix=/home/user/zope/base/2_9_3
+
+     Here we want Zope to be installed in
+     /home/user/zope/base/2_9_3. Note, that the path
+     /home/user/zope/base/ must already exist before executing the
+     above command, while the subdirectory '2_9_3' (yes, its a
+     diretory name) should be created by the build process.
+
+     You can however use any name you want for your Zope installation,
+     for example 'zope293' or something similar. Just change the
+     prefix-parameter in that case accordingly.
+
+     If everthing went well, you got the following (or similar) output:
+
+       ::
+
+         Configuring Zope installation
+         
+         Testing for an acceptable Python interpreter...
+         
+         Python version 2.4.3 found at /usr/bin/python
+         
+         The optimum Python version (2.4.3) was found at /usr/bin/python.
+
+     In case of errors, you might provide a --with-python option.
+
+     The Zope package is now configured and ready to be built. We
+     start the process by doing:
+
+       ::
+ 
+         ~/zope/build/Zope-2.9.3$ make
+
+     and, if everything worked fine:
+
+       ::
+
+         ~/zope/build/Zope-2.9.3$ make install
+
+     The first step, the call of 'make', takes the biggest amount of
+     time and is the crucial part of the whole installation process.
+
+     The make command may raise some compiler warnings (complaining
+     about eventually uninitialized variables), especially, if using
+     the up-to-date version of gcc. You can safely ignore them.
+
+     But if you get real error messages (not only warnings) something is
+     seriously wrong and you have to resolve this problems before
+     proceeding. In most cases it is a matter of (not) installed Python/gcc
+     packages and depends on your system. There is a very high
+     probability, that you can find some hints regarding your issues
+     using Google or other internet ressources.
+
+     If no serious errors occured: congratulations! You finally
+     installed your first Zope.
+
+     If you are short of disk space, you can now safely remove the
+     complete directory tree in the 'build/' directory. All needed
+     software is now installed in the base/ directory.
+
+
+  5. *Install a Zope instance*
+
+     We can now change to our freshly created Zope installation:
+
+       ::
+
+         ~$ cd /home/user/zope/base/2_9_3
+
+     Instead of '2_9_3' you must use the name given to the prefix
+     option of the 'configure'-script above.
+
+     Here you can find some subdirectories of which for now only the
+     bin-directory is of interest:
+
+       ::
+
+         ~/zope/base/2_9_3$ ls
+	 bin  include  lib  skel  zopeskel
+         ~/zope/base/2_9_3$ cd bin
+         ~/zope/base/2_9_3/bin$ ls
+         analyze.py        fstail.py           requestprofiler.py   zeoctl.py
+         checkbtrees.py    fstest.py           runzeo.py            zeopack.py
+         check_catalog.py  load_site.py        simul.py             zeopasswd.py
+         compilezpy.py     migrate.py          space.py             zeoqueue.py
+         copyzopeskel.py   mkzeoinstance.py    stats.py             zeoreplay.py
+         copyzopeskel.pyc  mkzeoinst.py        test.py              zeoserverlog.py
+         decompilezpy.py   mkzopeinstance.py   timeout.py           zeoup.py
+         fsdump.py         netspace.py         zconfig              zodbload.py
+         fsoids.py         parsezeolog.py      zconfig_schema2html  zopetest
+         fsrefs.py         reindex_catalog.py  zdctl.py             zpasswd.py
+         fsstats.py        repozo.py           zdrun.py
+
+    Almost all of these files are executables, i.e. programs, you
+    might need in your further work with Zope. Most Zope
+    administrators, however, know only the script 'mkzopeinstance.py',
+    which creates a new Zope instance. We will use it too. First we
+    call it with the '--help' option, to see, what the script can do
+    for us:
+
+      ::
+
+        ~/zope/base/2_9_3/bin$ ./mkzopeinstance.py --help
+        mkzopeinstance.py:  Create a Zope instance home.
+
+        usage:  mkzopeinstance.py [options]
+
+        Options:
+         -h/--help -- print this help text
+         -d/--dir  -- the dir in which the instance home should be created
+         -u/--user NAME:PASSWORD -- set the user name and password of the initial user
+         -s/--skelsrc -- the dir from which skeleton files should be copied
+
+        When run without arguments, this script will ask for the information necessary
+        to create a Zope instance home.
+
+    Note: On UN*X systems the '--help' switch is very common. Most programs
+    support it.
+
+    The help message displayed tells us, that we can name a directory
+    to specify, where the instance should be created and a
+    username/password pair for the initial login. That is, what we are
+    going to do. As path for the instance we choose a (yet not
+    existing) directory in the 'instances'-directory, say
+    'myinstance1'. The user/password values for our first local tries
+    can be kept simple:
+
+      ::
+
+        ~/zope/base/2_9_3/bin$ ./mkzopeinstance.py -d /home/user/zope/instances/myinstance1 -u user:secret
+
+    This takes only about one second. If you do not give a username
+    and password via parameters, you will be prompted for the data.
+
+  6. *Configure and start your new instance*
+
+    Change to the instances directory, to see, whether your new Zope
+    instance was created:
+
+      ::
+
+        ~$ cd /home/user/zope/instances
+        ~/zope/instances$ ls
+        myinstance1
+
+    Okay, the instance exists, so go in and have a look:
+
+      ::
+
+        ~/zope/instances$ cd myinstance1
+        ~/zope/instances/myinstance1$ ls
+        bin  etc  Extensions  import  inituser  lib  log  Products  README.txt  var
+
+    Here we see the main directories for the further work with
+    Zope. The most important directories:
+
+      * *bin -- Executables to start/stop your instance*
+
+        This directory contains the programs to start or stop your
+        Zope instance. You can do much more with them, but we refer to
+        the extended possibilities later on.
+
+      * *etc -- Configuration of your instance*
+
+        This directory holds the important configuration file of your
+        Zope instance. Chances are, that you do not need to change the
+        default configuration, but we will take a look into it anyway.
+
+      * *log -- Logfiles of your instance*
+
+        Here you can find the logs of your instance. Namely the access
+        logfile 'Z2.log' and an error log called 'event.log'. The
+        event log saves all Zope specific events, not only errors.
+
+      * *Products -- 3rd-party products repository*
+
+        Here can install all products, like CPS or the WAeUP SRP
+        product. They are generally installed on a per-instance basis.
+
+      * *var -- The data directory*
+
+        In this directory will Zope save all runtime information,
+        i.e. the Z Object DataBase (ZODB) and other temporary
+        data. The ZODB will be held in a file called Data.fs, which
+        contains all the data you entered into the running Zope
+        system. If it gets corrupted, the whole instance is lost. In
+        special cases (ZEO setup etc.) the Data.fs can be shared
+        amongst several Zope instances and reside at another place.
+
+    Before starting the instance, first have a look at the
+    configuration file 'zope.conf' which can be found in the
+    etc-directory of your instance.
+
+    With growing version numbers of Zope also the Zope configuration
+    file grows larger and larger. For version 2.9.3 there are too many
+    options available in zope.conf, to discuss every single option
+    herein.
+
+    One option, however, is of special interest: the port number,
+    where the Zope instance will listen to requests.
+
+    'zope.conf' is a simple plain text file, which you can edit with
+    any text editor (please do not use something like OpenOffice or
+    Word to edit a plain text file: it won't be plain text any
+    more). To view its content you can use the command 'less' on
+    UN*X.
+
+    In the zope.conf you will find (near the end of file) a section
+    called 'http-server', which looks like this:
+
+      ::
+
+        #
+        #     An HTTP server starts on port 8080.
+
+        <http-server>
+        # valid keys are "address" and "force-connection-close"
+          address 8080
+          # force-connection-close on
+        </http-server>
+
+    This means, Zope will listen on port 8080. This is okay, if there
+    is no other process still listening on port 8080 (note for geeks:
+    you can use the 'netstat' tool to check, which ports are already
+    in use). But if you want to run several Zope instances in
+    parallel, you must set the listening port to another value.
+
+    We assume, port 8080 is not in use and simply start the Zope
+    instance in the foreground for the first time:
+
+      ::
+
+        ~/zope/instances/myinstance1$ ./bin/runzope
+
+    You will get some DeprecationWarnings and a message about a
+    installed sighandler. This means, Zope has started and you should
+    be able to use your Browser and browse to
+
+      http://localhost:8080/
+
+    Note the portnumber in the URL:
+
+      .. image:: ./snapshot1.png
+
+    If you can see the Zope Quick Start screen, everything is fine and
+    you can stop the Zope instance on the console by typing CTRL-C.
+
+    We used the 'runzope' script to start Zope in the foreground. This
+    is a recommended way to start freshly created instances, because
+    problems occurring during the startup process will be displayed
+    directly on the screen (in the shell).
+
+    For long-term use this is not an option, because you want to run
+    Zope as a server, which runs in the background and continues to
+    run, when you log out. To start Zope in background use the
+    'zopectl' command. It requires a parameter, which specifies the
+    action to be taken:
+
+      ::
+
+        zopectl start|stop|restart
+
+    There are other possible actions as well, but for the beginning we
+    start with 'start':
+
+      ::
+
+        ~/zope/instances/myinstance1$ ./bin/zopectl start
+        . . . daemon process started, pid=457
+
+    You now have Zope running in regular mode. Check it by visiting
+    the Quick Start Page.
+
+    If everything went fine, you can see the startup messages in the
+    logfiles in the log directory of your instance.
+
+    You can also enter the Zope Management Interface (ZMI), by adding
+    '/manage' to the URL:
+
+      http://localhost:8080/manage
+
+    This requires to enter the credentials, you gave during
+    installation of the instance.
+
+      .. image:: ./snapshot2.png
+
+    After successfull authorization you should be able to see the ZMI:
+
+      .. image:: ./snapshot3.png
+
+That's it. You installed Zope successfully. Congratulations! To
+stop your running instance, you can go to the control panel in the
+ZMI and shutdown by mouse-click, or, on the commandline, do
+
+  ::
+
+    ~/zope/instances/myinstance1$ ./bin/zopectl stop
+
+You can play a bit with your instance and then try to do the other
+steps to run a fully working version of the WAeUP SRP.
+
+*Have fun!*
+
+*Uli Fouquet*
Index: WAeUP_Doc/ExtendedInstructions/Makefile
===================================================================
--- WAeUP_Doc/ExtendedInstructions/Makefile	(revision 1617)
+++ WAeUP_Doc/ExtendedInstructions/Makefile	(revision 1617)
@@ -0,0 +1,14 @@
+
+# keep .html files up to date (requires GNU make):
+
+
+SOURCES=$(wildcard *.rst)
+TARGETS=$(subst .rst,.html, $(SOURCES))
+
+
+all: ${TARGETS}
+
+
+%.html: %.rst
+	python rst2html.py $< > $@
+
Index: WAeUP_Doc/ExtendedInstructions/rst2html.py
===================================================================
--- WAeUP_Doc/ExtendedInstructions/rst2html.py	(revision 1617)
+++ WAeUP_Doc/ExtendedInstructions/rst2html.py	(revision 1617)
@@ -0,0 +1,25 @@
+#!/usr/bin/env python
+
+# Author: David Goodger
+# Contact: goodger@python.org
+# Revision: $Revision: 3901 $
+# Date: $Date: 2005-09-25 17:49:54 +0200 (Sun, 25 Sep 2005) $
+# Copyright: This module has been placed in the public domain.
+
+"""
+A minimal front end to the Docutils Publisher, producing HTML.
+"""
+
+try:
+    import locale
+    locale.setlocale(locale.LC_ALL, '')
+except:
+    pass
+
+from docutils.core import publish_cmdline, default_description
+
+
+description = ('Generates (X)HTML documents from standalone reStructuredText '
+               'sources.  ' + default_description)
+
+publish_cmdline(writer_name='html', description=description)
Index: WAeUP_Doc/Readme.txt
===================================================================
--- WAeUP_Doc/Readme.txt	(revision 1517)
+++ WAeUP_Doc/Readme.txt	(revision 1617)
@@ -1,11 +1,27 @@
-The documentation is written in restructured text format. Restructured Text (also reStructuredText or rst) is a simple markup language. Actually it's plain text with only a few style elements. For a full list of restructured text rules and examples see the Quick reStructuredText documentation:
+The documentation is written in restructured text format. Restructured
+Text (also reStructuredText or rst) is a simple markup
+language. Actually it's plain text with only a few style elements. For
+a full list of restructured text rules and examples see the Quick
+reStructuredText documentation:
 
 http://docutils.sourceforge.net/docs/user/rst/quickref.html
 
-Unfortunately, there is no Windows programme to transform rst code directly into html. To see the html result on Windows computers, Python has to be installed first. Then the docutils-0.4.zip must be downloaded from:
+Unfortunately, there is no Windows programme to transform rst code
+directly into html. To see the html result on Windows computers,
+Python has to be installed first. Then the docutils-0.4.zip must be
+downloaded from:
 
 http://waeup.org/Members/henrik/docutils-0.4/view  (1.7 MB)
 
-Unzip the file first. The docutils library is installed by executing the 'python install.py' command within the docutils-0.4 directory. Finally the command 'rst2html [rst filename without extension]' will produce the html file which can be seen in any browser.
+Unzip the file first. The docutils library is installed by executing
+the 'python install.py' command within the docutils-0.4
+directory. Finally the command 'rst2html [rst filename without
+extension]' will produce the html file which can be seen in any
+browser.
+
+On Un*x systems like Linux all the HTML-files can be automatically
+generated by entering this directory on the commandline and doing:
+
+	  make
 
 Henrik Bettermann
