Index: main/waeup.aaua/trunk/INSTALL.txt
===================================================================
--- main/waeup.aaua/trunk/INSTALL.txt	(revision 11380)
+++ main/waeup.aaua/trunk/INSTALL.txt	(revision 11381)
@@ -1,57 +1,46 @@
-Installation of Kofa on Linux production system
-###############################################
-
-.. note:: `waeup.kofa` and its custom packages
-          might not work with Python > 2.7
-          currently. Use of Python 2.7 is recommended.
-          The installation is described for Linux-based computers.
-
-Part 1: Deploying Kofa as a single Zope client install
-******************************************************
+Installation of Kofa
+####################
+
+These are generic installation instructions for the WAeUP_ ``Kofa``
+student information portal and customized versions thereof.
+
+For specific aspects of this package please refer to the local README
+file.
+
+Please note, that **only Linux-based installs** are described and actively
+supported. We recommend use of Debian_ / Ubuntu_.
+
+.. note:: This means we do not actively support Windows(tm)!
+
 
 Prerequisites
-=============
-
-The Kofa packages are based on `Grok`_, which is a Python
-framework for agile webapplication development. Grok itself is based
+*************
+
+The Kofa packages are based on `Grok`_, which is a Python_
+framework for agile webapplication development. Grok_ itself is based
 on `Zope`_.
 
-.. _Grok: http://grok.zope.org/
-
-.. _Zope: http://www.zope.org/
-
-Both, Grok and Zope, are written in Python (with parts written in
-C). You therefore need `Python`_ installed.
-
-.. _Python: http://www.python.org/
-
-Note, that you also need the Python header files and a compiler to
-compile the parts written in C.
-
-To deploy Kofa most easily, we use `zc.buildout`_
-
-.. _zc.buildout: http://cheeseshop.python.org/pypi/zc.buildout
-
-
-Preparing the system
+Both, Grok_ and Zope_, are written in the `Python`_ programming
+language (with parts written in C). You therefore have to have
+`Python`_ installed (including `Python`_ headers).
+
+
+Preparing the System
 ====================
 
-To create a working copy of Kofa we recommend use of
-`virtualenv`. You, however, need also some basic libraries, a C
-compiler and some things more.
+For a `Kofa` install we need of course `Python`_ installed as well as
+some standard developer tools like C compilers, C libraries, etc.
 
 What you need (Debian/Ubuntu package names in brackets):
 
-* Python 2.7 (python2.7)
-
-* Python 2.7 development files (python2.7-dev)
-
-* A C-Compiler (gcc)
-
-* The C library development files (libc6-dev)
-
-* A subversion client (svn)
-
-* enscript (enscript) [optional]
+* Python 2.7 (``python2.7``)
+
+* Python 2.7 development files (``python2.7-dev``)
+
+* A C-Compiler with basic C developer libraries (``build-essential``)
+
+* A subversion client (``svn``)
+
+* enscript (``enscript``) [optional]
 
   This is only needed if you want test coverage reports.
@@ -59,6 +48,6 @@
 All these packages can be installed on Debian systems like this::
 
-  # apt-get install python2.7 python2.7-dev python2.7-dbg \
-                    gcc libc6-dev svn enscript
+  $ sudo apt-get install python2.7 python2.7-dev svn \
+                         build-essential enscript
 
 Afterwards you should be able to enter::
@@ -66,5 +55,5 @@
   $ python2.7
 
-at the commandline and get a Python prompt. Quit the interpreter
+at the commandline and get a Python_ prompt. Quit the interpreter
 pressing <CTRL-D>.
 
@@ -73,5 +62,5 @@
 =======================
 
-We recommend use of `virtualenv` to create Python sandboxes where you
+We recommend use of `virtualenv`_ to create Python_ sandboxes where you
 can run your code without touching any other installations.
 
@@ -159,4 +148,13 @@
   (sandbox27)$ cd kofa-trunk
 
+
+You can run ``Kofa`` with a single client (useful for evaluation,
+development, etc.) or with multiple clients running in parallel. The
+latter setup is useful in productive environments with many thousands
+users. We will cover both setup types one after another.
+
+
+Part 1: Single Client Setup
+***************************
 
 Preparing the build
@@ -394,2 +392,11 @@
 regular non-ZEO kofactl might not make to much sense. Therefore all
 this might be subject to changes.
+
+.. _Debian: http://www.debian.org/
+.. _Grok: http://grok.zope.org/
+.. _Python: http://www.python.org/
+.. _Ubuntu: http://www.ubuntu.com/
+.. _virtualenv: http://www.virtualenv.org/en/latest/
+.. _WAeUP: https://www.waeup.org/
+.. _Zope: http://www.zope.org/
+.. _zc.buildout: http://cheeseshop.python.org/pypi/zc.buildout
