Index: src/documentation/install.dox
===================================================================
--- src/documentation/install.dox	(revision 0a783477d66226c273578ea2e52416327e199337)
+++ src/documentation/install.dox	(revision 6752dc828fcabcc74aaeb4c2eee3e8ccbef34d70)
@@ -16,4 +16,125 @@
  *  \page install Installation
  *
+ * \section install-prerequisites Prerequisites
+ *
+ * Several packages are required or advised for compilation of the code.
+ * The code has been developed under ubuntu 10.04 and 12.04, so in the
+ * following we concentrate on these systems.
+ *
+ * A specific section will be added when (cross-)compilation for Windows
+ * has succeeded. Note that compiling without Qt under GNU/Cygwin is
+ * relatively straight-forward along the lines of the required packages
+ * for Ubuntu.
+ *
+ * \subsection install-prerequisites-ubuntu ... for Ubuntu
+ *
+ *  Under Ubuntu 12.04 the following packages are required:
+ *  -# C++ compiler: e.g. g++
+ *  -# LAPACK: liblapack-dev
+ *  -# GSL: libgsl0-dev
+ *  -# BLAS: e.g. libopenblas-dev or libatlas-base-dev
+ *  -# Many Boost Libraries: libboost1.48-all-dev
+ *  -# gawk: gawk
+ *  -# pkg-config: pkg-config
+ *  -# CodePatterns: see below for instructions
+ *
+ *  The following packages are optional. Note however that certain features
+ *  are not available when these packages are missing:
+ *  -# MoleCuilder scripting and start scripts
+ *    -# Python:  python, python-dev
+ *  -# Documentation generated from source code:
+ *    -# doxygen: doxygen
+ *    -# GraphViz: dot
+ *  -# Unit tests
+ *    -# CppUnit: libcppunit-dev
+ *  -# Graphical User Interface
+ *    -# Qt: qt4-dev-tools libqt4-core qt4-qmake
+ *    -# Qt3D: see below for instructions
+ *  -# BOSSANOVA scheme
+ *    -# JobMarket: see below for instructions
+ *    -# MPQC: see below for instructions
+ *    -# ScaFaCoS: see below for instructions
+ *
+ *  If you are programming with or for MoleCuilder, the following packages are
+ *  advised to use:
+ *  -# ccache: ccache
+ *  -# git: git
+ *  -# autotools: autoconf automake autoheader autoconf libtool
+ *
+ * \subsection install-prerequisites-other Other packages
+ *
+ *  Here, we want to give some advice on how we managed to compile packages that
+ *  don't come as a Debian/Ubuntu package:
+ *
+ *  \subsubsection install-prerequisites-other-codepatterns CodePatterns
+ *
+ *   CodePatterns are some general object oriented patterns implemented in C++
+ *   which are a sort of novice attempt to what some of the boost libraries can
+ *   do. E.g. a thread-safe singleton pattern.
+ *
+ *   Refer to the project's webpage for further instructions.
+ *
+ *  \subsubsection install-prerequisites-other-qt3d Qt3D
+ *
+ *   The graphical user interface heavily relies on Qt3D to display atoms and
+ *   their bonds and to allow for selections. As the GUI has been developed with
+ *   Qt4.8 where Qt3D is not yet implemented - this has been done with Qt5 --
+ *   Qt3D has to be compiled and installed manually. Required for compilation
+ *   are the complete dev-tools of Qt4. Then, obtain the code from the repository
+ *   as described here: http://doc-snapshot.qt-project.org/qt3d-1.0/qt3d-building.html
+ *   Make sure that the branch \b qt4 is checked out.
+ *   Afterwards, create the Makefiles (check that qt4's qmake is used!), compile, and
+ *   install via
+ *   \code
+ *   qmake-qt4 quick3d.pro
+ *   sudo make
+ *   sudo make install
+ *   \endcode
+ *   Note that I had to manually create \b /usr/include/qt4/Qt3D to pass
+ *   compilation and installation with error.
+ *
+ *   Furthermore, we require a Qt3D pkg-config file, which is sadly not created.
+ *   This can be easily created by copying e.g. QtOpenGl.pc and search&replacing
+ *   OpenGl to Qt3D (check for double QtQt appearances).
+ *
+ *  \subsubsection install-prerequisites-other-jobmarket JobMarket
+ *
+ *   JobMarket is a package for allowing a server to give wrapped-up jobs to
+ *   clients which work on the given job and return some wrapped-up results.
+ *   This has been implemented with boost::asio.
+ *
+ *   The package is private property of Frederik Heber. Contact the author for
+ *   further information on how to obtain the code and installation instructions.
+ *
+ *  \subsubsection install-prerequisites-other-scafacos ScaFaCoS
+ *
+ *  ScaFaCoS is a library of fast Coulomb solvers, created by the same-named BMBF
+ *  funded project. The library contains Versatile MultiGrid (vmg) as one of its
+ *  solvers which is used in the BOSSANOVA scheme for the calculation of
+ *  long-range forces.
+ *
+ *  ScaFaCoS requires the following packages to compile:
+ *  -# MPI: mpi-default-dev libopenmpi-dev
+ *  -# F2C: libf2c2-dev
+ *  -# Fortran compiler: gfortan
+ *  Compilation additionally required use of
+ *  \code CPPFLAGS="-fPIC" \endcode
+ *  to generate position-independent code. This is because ScaFaCoS so far does
+ *  not use libtool which would otherwise take care of this and created shared
+ *  libraries. Note that VMG is the only required solver, others are not used, e.g.
+ *  for a debug compile you might want to use:
+ *  \code
+ *  ../configure -C --prefix=<path> --enable-shared BSPLINE_DEG=3 MPICC=mpicc.openmpi
+ *  MPICXX=mpicxx.openmpi MPIEXEC=mpirun.openmpi CPPFLAGS="-Wall -g3 -O0 -ggdb -fPIC"
+ *  --enable-mpi --with-boost-libdir=/usr/lib --with-boost=/usr --enable-fcs-solvers=vmg
+ *  \endcode
+ *
+ *  \subsubsection install-prerequisites-other-mpqc MPQC
+ *
+ *  Massively Parallel Quantum Chemistry (http://www.mpqc.org/) is a Hartree-Fock
+ *  solver with emphasis on concurrency. We, however, require only the solver part.
+ *  The code base has been adapted a bit to allow use within JobMarket.
+ *  Also, it uses the ScaFaCoS package to calculate long-range forces.
+ *
  * \section install-compiling Compiling the Code
  *
@@ -34,11 +155,11 @@
  * \endcode
  *
- * which will run the configure script that checks whether you have a current
- * version of the following required packages:
- *
+ * which will run the configure script that checks whether you meet all the
+ * requirements. Note that you may supply system-specific paths as follows:
  * -# GNU Scientific Library (specify via LDFLAGS, ...)
  * -# Qt4 framework (--with-Qt=<dir> or --with-Qt-include-dir, --with-Qt-bin-dir,
  *  --with-Qt-lib-dir and --with-Qt-lib)
- * -# Boost library 1.40 or newer with program_options and threads (--with-boost=<dir>)
+ * -# Boost library 1.40 or newer with program_options and threads (--with-boost=<dir>,
+ * --with-boost-lib=<path>)
  * -# CPPUnit framework (--with-cppunit-prefix=<dir>)
  * -# CodePatterns (--with-codepatterns=<dir>)
@@ -94,4 +215,13 @@
  *  the code by a factor of 5
  *
+ * \subsection install-difficulties  Difficulties
+ *
+ *  You might encounter some problems along the way, which we list up here:
+ *  -# Switching from Lucid Lynx to Precise Pangolin, libtool has been patched to
+ *  \b link_all_deplibs=no which causes linking to fail. A temporary way around it
+ *  is to seek&replace all instances in your build directory (replace no with
+ *  unknown). The more general way is to replace packaged and patched libtool
+ *  with an unpatched version you have to compile yourself.
+ *
  * \section install-install Installing
  *
