Index: src/documentation/code.dox
===================================================================
--- src/documentation/code.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/code.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -14,9 +14,12 @@
 
 /**
- * \page code "How to use the code"
+ * \page code How to use the code
  *
- * \li \subpage faq "Frequently Asked Questions"
- * \li \subpage constructs "List of various rigid constructs"
- * \li \subpage howto "Howtos for specific code constructs"
+ * \li \ref faq
+ * \li \ref constructs
+ * \li \ref howto
+ *
+ *
+ * \date 2011-10-31
  *
  */
Index: src/documentation/constructs/actions.dox
===================================================================
--- src/documentation/constructs/actions.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/constructs/actions.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -12,2 +12,41 @@
  *    Author: heber
  */
+
+/** \page actions Actions
+ *
+ *  Actions are Command patterns (http://en.wikipedia.org/wiki/Command_pattern)
+ *  to allow for undoing and redoing. Each specific Action derives from this
+ *  class to implement a certain functionality. There is a lot of preprocessor
+ *  magic implemented for making this as easy as possible. In effect you only
+ *  have to create three files of which only one actually contains more than a
+ *  few lines, namely the code of the Action itself.
+ *
+ *  Each Action has thus three types of functionalty: do, undo, and redo.
+ *
+ *  The ActionRegistry contains a prototype of each Action under its token
+ *  such that an instance can be retrieved by knowing this token.
+ *
+ *  Each Action obtains its parameter from a central ValueStorage such that
+ *  they are independent of where the parameter originated from: a command line
+ *  parameter, a value entered in a graphical dialog or given via the keyboard
+ *  in a terminal. That's why each begins with a function call to
+ *  getParametersfromValueStorage() to fill its internal Action::params
+ *  structure.
+ *
+ *  Also there is a regression test (\ref regression-test) for each Action to
+ *  check that it always behaves the same no matter how much the code
+ *  implementing actually has changed.
+ *
+ * \section actions-add To add a new action ...
+ *
+ *  The following steps have to be done for adding a new action:
+ *  -# Create three new files .cpp, .def, and .hpp
+ *  -# Add the files to \b src/Actions/Makefile.am.
+ *  -# Add the name of the Action to \b src/Actions/GlobalListOfActions.hpp
+ *    such that the ActionRegistry knows about it and can instantiate a
+ *    prototype.
+ *
+ *
+ *  \date 2011-10-31
+ *
+ */
Index: src/documentation/constructs/atoms.dox
===================================================================
--- src/documentation/constructs/atoms.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
+++ src/documentation/constructs/atoms.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -0,0 +1,60 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file atoms.dox
+ *
+ * Created on: Oct 31, 2011
+ *    Author: heber
+ */
+
+/**
+ * \page atoms Atoms
+ *
+ * Atoms are the central ingredient. They store the following information:
+ * - position, velocity, and force (over multiple time steps)
+ * - element
+ * - bond neighbours (over multiple time steps)
+ * - id
+ *
+ * \section atoms-structure
+ *
+ * The atom class has quite a complicated structure because an atoms has to
+ * fulfill various roles within this code:
+ * - atom
+ * - TesselPoint for Tesselation
+ * - Graph node for BondGraph
+ * - bonded particle
+ *
+ * There is an onion structure where additional information has been added
+ * as the layers of an onion via inheritance.
+ *
+ * We briefly want to explain the various elements of the inheritance
+ * - AtomObservable - contains notification channels enumeration and also all
+ *  interface function required by the Observable pattern.
+ * - AtomInfo - contains position, element and so on.
+ * - ParticleInfo - contains name and number of the atom
+ * - BondedParticle - contains all functions related to bonds
+ * - BondedParticleInfo - contains all member variables related to storing bond
+ *   information
+ * - GraphNode - contains all functions related to graphs
+ * - GraphNodeInfo - contains all member variables for graph information
+ * - TesselPoint - contains functions for considering the atom as a TesselPoint
+ *   in Tesselation (\ref tesselation)
+ *
+ * Member variables and functions have been split into class with and without
+ * added \a ...Info. ...Info classes that are required multiple times are
+ * inherited as virtual to guarantee that their members are unique (exist
+ * only once) within an instance.
+ *
+ * \note Atoms have a sort-of early serialization concept (\ref serialization)
+ * as AtomicInfo. \todo This could be refactored into a full serialization
+ * compatible implementation.
+ *
+ *
+ * \date 2011-10-31
+ */
Index: src/documentation/constructs/bondgraph.dox
===================================================================
--- src/documentation/constructs/bondgraph.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/constructs/bondgraph.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -12,2 +12,25 @@
  *    Author: heber
  */
+
+/** \page bondgraph BondGraph
+ *
+ * The BondGraph class contains the knowledge of when two atoms are bonded and
+ * when not. At this moment it either uses a sum of covalent bond radii or an
+ * externally given bond table that gives typical bond lengths per element.
+ *
+ * The BondGraph's main working horse is the BondGraph::CreateAdjacency()
+ * function. It is strongly connected to the following graph actions:
+ * - GraphCreateAdjacencyAction
+ * - GraphSubgraphDissectionAction
+ *
+ * Therein, the bond structure is recognized again from scratch or/and the
+ * molecules afterwards represent disconnected subgraphs.
+ *
+ * In terms of graph theory the bond graph is an undirected graph with the
+ * bond degree as its weight. Bonds are respresented by edges, the atoms
+ * represent nodes.
+ *
+ *
+ * \date 2011-10-31
+ *
+ */
Index: src/documentation/constructs/constructs.dox
===================================================================
--- src/documentation/constructs/constructs.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/constructs/constructs.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -7,5 +7,5 @@
 
 /**
- * \file constructs
+ * \file constructs.dox
  *
  * Created on: Oct 11, 2011
@@ -14,24 +14,29 @@
 
 
-/*
- * \page constructs "List of various rigid constructs"
+/**
+ * \page constructs List of various rigid constructs
  *
  * The following constructs are present and should be known to you as an alphabetical list:
  *
- *  \li \subpage actions
- *  \li \subpage linearalgebra
- *  \li \subpage bondgraph
- *  \li \subpage descriptors
- *  \li \subpage fragmentation
- *  \li \subpage observers
- *  \li \subpage parsers
- *  \li \subpage randomnumbers
- *  \li \subpage serialization
- *  \li \subpage shapes
- *  \li \subpage tesselation
- *  \li \subpage world
+ *  \li \ref actions
+ *  \li \ref atom
+ *  \li \ref linearalgebra
+ *  \li \ref bondgraph
+ *  \li \ref descriptors
+ *  \li \ref fragmentation
+ *  \li \ref molecule
+ *  \li \ref observers
+ *  \li \ref parsers
+ *  \li \ref randomnumbers
+ *  \li \ref serialization
+ *  \li \ref shapes
+ *  \li \ref tesselation
+ *  \li \ref world
  *
  *  Note that the most important construct is the \subpage world "World" whose functions
  *  should absolutely be known.
  *
+ *
+ * \date 2011-10-31
+ *
  */
Index: src/documentation/constructs/descriptors.dox
===================================================================
--- src/documentation/constructs/descriptors.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/constructs/descriptors.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -12,2 +12,65 @@
  *    Author: heber
  */
+
+/** \page descriptors Descriptors
+ *
+ * Descriptors help you to select a specific subset of a given array of
+ * elements. For the moment these elements are either instances of atom
+ * or molecule that the \ref world offers.
+ *
+ * They mostly work as an argument to either obtain a specific iterator
+ * over the elements (that silently skips all non-matching ones) or
+ * a subset.
+ *
+ * Note that the following boolean operators on descriptors work:
+ * - or
+ * - and
+ * - not
+ *
+ * Hence, these descriptors are very mighty. A typical use would be as follows:
+ * \code
+ * World::getInstance().getAllAtoms(AtomByType(1) && AtomByShape(Sphere(Vector(0,0,0), 2.)));
+ * \endcode
+ * which would return an AtomComposite of all hydrogen (Z=1) atoms within a
+ * sphere of radius 2. centered at (0,0,0).
+ *
+ * Or you may obtain iterators over a selection and use them in a loop as this:
+ * \code
+ * World::MoleculeIterator iter = World::getInstance().getMoleculeIter(MoleculeByFormula(Formula("H2O")));
+ * World::MoleculeIterator enditer = World::getInstance().moleculeEnd();
+ * std::cout << "List of all water molecules:" << std::endl;
+ * for (; iter != enditer; ++iter)
+ *  std:cout << (*iter)->getId() << std::endl;
+ * \endcode
+ *
+ * \note There is difference between Selection and Descriptor. A
+ * Descriptor is just a predicate() that selects among a given list. The current
+ * Selection (of atoms/molecules) is a Descriptor \a applied to a the total
+ * list of all atoms/molecules. Hence, a selection refers to a subset where
+ * the Descriptor is just the condition that selects such a subset.
+ *
+ * \subsection descriptors-atom Atom Descriptors
+ *
+ *  The following descriptors are present for atoms:
+ *  - by id: AtomById()
+ *  - of currently selected molecule(s): AtomsByMoleculeSelection()
+ *  - currently selected atoms: AtomsBySelection()
+ *  - within a Shape: AtomByShape()
+ *  - of specific element: AtomByType()
+ *
+ * \subsection descriptors-molecule Molecule Descriptors
+ *
+ *  The following descriptors are present for molecules:
+ *  - by formula: MoleculeByFormula()
+ *  - by id: MoleculeById()
+ *  - by name: MoleculeByName()
+ *  - of currently selected atoms: MoleculesByAtomSelection()
+ *  - by order of creation: MoleculeByOrder() (i.e. -1 is the last one, 1 is the
+ *    first ever created, ...)
+ *  - by pointer: MoleculeByPtr MoleculeByPtr()
+ *  - currently selected molecules: MoleculesBySelection()
+ *
+ *
+ * \date 2011-10-31
+ *
+ */
Index: src/documentation/constructs/fragmentation.dox
===================================================================
--- src/documentation/constructs/fragmentation.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/constructs/fragmentation.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -12,2 +12,24 @@
  *    Author: heber
  */
+
+/** \page fragmentation Fragmentation
+ *
+ * Fragmentation contains all routines that are required to split a given
+ * molecular system into fragments. This is part of the so-called BOSSANOVA
+ * (Bond Order diSSection in an ANOVA-like fashion) approach to get linear
+ * scaling complexity for ab-initio quantum chemistry methods.
+ *
+ * The class Fragmentation contains with Fragmentation::FragmentMolecule()
+ * the main routine that dissect a given system and stores the fragments
+ * as configuration files.
+ *
+ * After these have been treated with a supported ab-initio solver, the
+ * energies and forces can be put together via \b joiner to approximation
+ * to the total energy and forces of the whole molecular system. Later,
+ * \b analyzer additionally gives data on how good this approximation has
+ * worked out in plotable format.
+ *
+ *
+ * \date 2011-10-31
+ *
+ */
Index: src/documentation/constructs/linearalgebra.dox
===================================================================
--- src/documentation/constructs/linearalgebra.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
+++ src/documentation/constructs/linearalgebra.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -0,0 +1,33 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file linearalgebra.dox
+ *
+ * Created on: Oct 31, 2011
+ *    Author: heber
+ */
+
+/**
+ * \page linearalgebra Linear Algebra submodule
+ *
+ * The Linear Algebra submodule wraps GSL functionality into C++ classes. It
+ * has its own documentation residing in the subfolder \b LinearAlgebra.
+ *
+ * Most important are the Vector and Matrix classes including operators to
+ * allow for easy algebra, e.g.
+ * \code
+ * Vector test(1,1,1);
+ * Matrix m(3,3);
+ * m.setIdentity();
+ * std::cout << "Vector " << test << " times the identity is " << test*m M << std::endl;
+ * \endcode
+ *
+ *
+ * \date 2011-10-31
+ *
+ */
Index: src/documentation/constructs/logger.dox
===================================================================
--- src/documentation/constructs/logger.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
+++ src/documentation/constructs/logger.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -0,0 +1,41 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file logger.dox
+ *
+ * Created on: Oct 31, 2011
+ *    Author: heber
+ */
+
+/**
+ * \page logger Logging
+ *
+ * In order to have conforming way of giving information about the current
+ * doings of the program, there is a logging faculty with varying degree.
+ *
+ * It used in the following way:
+ * \code
+ * LOG(<level>, <msg>);
+ * \endcode
+ * where \a <level> is the verbosity level above which the message should be
+ * given and <msg> is the message.
+ *
+ * Note that LOG() is just a define and \a <msg> may be a stream, hence
+ * \code "bla" << bla << ", more bla" is valid.
+ *
+ * For giving errors you may use:
+ * \code
+ * ELOG(<level>, <msg>);
+ * \endcode
+ * where the program will exit automatically if the \a <level> is either
+ * critical(0) or error(1). (2) emits a warning, all else should be ignorable.
+ *
+ *
+ * \date 2011-10-31
+ *
+ */
Index: src/documentation/constructs/molecules.dox
===================================================================
--- src/documentation/constructs/molecules.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
+++ src/documentation/constructs/molecules.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -0,0 +1,51 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file molecules.dox
+ *
+ * Created on: Oct 31, 2011
+ *    Author: heber
+ */
+
+/**
+ * \page molecules Molecules
+ *
+ * Molecule is the next important structure to atom.
+ *
+ * Molecule are especially important for \ref fragmentation and lots of
+ * their (old) code comes from this theme.
+ *
+ * Basically, a molecule is just a conglomerate of atoms whose nodes form a
+ * connected subgraph of the entire molecular system.
+ *
+ * A molecule has its own internal array of atoms that may be traversed.
+ * Similar concepts as with the World with regards to const and non-const
+ * traversal, the former involving an Observer mechanism, come into play here
+ * as well.
+ *
+ * \section molecules-formula Formula
+ *
+ * One important concept of molecules is the associated Formula. It, as well
+ * as the AtomCount, are implemented as Cachables, i.e. they are aware of
+ * changes to the contained atoms via the Observer mechanism but update
+ * themselves only when requested.
+ *
+ * Formulas are very powerful because they can also be used as a Descriptor
+ * (\ref descriptors) to access only a certain subsets of molecules, e.g.
+ * "H2O" selects all water molecules.
+ *
+ * \section molecules-bondgraph Notes on the BondGraph
+ *
+ * Note that molecules are very volatile: Changing the bond graph also changes
+ * most of the present molecules at this time as so far there is no update
+ * mechanism. Hence, be aware of it.
+ *
+ *
+ * \date 2011-10-31
+ *
+ */
Index: src/documentation/constructs/observers_observables.dox
===================================================================
--- src/documentation/constructs/observers_observables.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/constructs/observers_observables.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -12,2 +12,71 @@
  *    Author: heber
  */
+
+/** \page observers Observers and Observables
+ *
+ * The Observer/Observerable mechanism is crucial to let different and
+ * independent components know about changes among one another. E.g. when an
+ * the element of an atom changes, the GUI (\ref graphical) needs to know
+ * about this change to plot the atom with a different color or shape.
+ *
+ * The Observer/Observerable mechanism is basically just a call-back: A
+ * class announces itself as Observable with having a specific interface
+ * of functions. Observer may signOn() to this class and have a specific
+ * function (update()) be called whenever a change occurs in the Observable
+ * class.
+ *
+ * Note that additionally an Observable may have various \a channels and
+ * Observers may signOn() to just such a channel to get a very specific
+ * update. E.g. a LinkedCell class needs to know when the position of an
+ * atom changes but it does not need to know about changes of element or
+ * velocity, ... These updates are called \a Notifications.
+ *
+ * As an example:
+ * \code
+ * World::getInstance().signOn(this, World::getInstance().getChannel(World::AtomInserted));
+ * \endcode
+ * Here, in the constructor of GLWorldView the class signs on to atoms
+ * being inserted into the World such that it can add these onto the display
+ * as well. Notifications are received via recieveNotifications(), e.g.
+ * which you have to implement for an Observer class
+ * \code
+ *   switch (notification->getChannelNo()) {
+ *   case World::AtomInserted:
+ *   {
+ *     const atom *_atom = World::getInstance().lastChanged<atom>();
+ *     emit atomInserted(_atom);
+ *     break;
+ *   }
+ * \endcode
+ * Here, we just switch over all events that we process and care about (note
+ * that we only get called for those for which we have subscribed) and proceed.
+ *
+ * \note There is a complete logging mechanism available for this. However,
+ * it has to be compiled via a specific switch (\ref install). So, when
+ * you need to know why your function isn't notified, that's the way to
+ * find out.
+ *
+ * Be wary of where the update occurs: while the World tells you about new
+ * or destroyed atoms, only the atom itself tells you when its position has
+ * changed!
+ *
+ * \section observers-world Observers and the World
+ *
+ * The World, containing the arrays of all atoms and molecules, is a bit
+ * special with these observers. E.g. when you request a non-const array
+ * of atoms you receive an ObservedIterator. That is one where automatically
+ * it is assumed that you changed something and hence update() is called
+ * after you stepped over one of its elements.
+ *
+ * Thus, use const-iterators and arrays whenever possible, first to avoid
+ * this overhead, but second to avoid making pain-in-the-ass, hard-to-find
+ * mistakes.
+ *
+ * Also, the world stores specific information about what changed in the
+ * template function World::lastChanged() where it might contain reference
+ * to an atom that is about to be destroyed or just added.
+ *
+ *
+ * \date 2011-10-31
+ *
+ */
Index: src/documentation/constructs/parsers.dox
===================================================================
--- src/documentation/constructs/parsers.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/constructs/parsers.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -12,2 +12,84 @@
  *    Author: heber
  */
+
+/** \page parsers Format Parsers
+ *
+ *  Format Parsers load or save information about the World (i.e. all atoms,
+ *  contained bonds, ...) in a specific file format.
+ *
+ *  All parsers derive from FormatParser and all available instances of
+ *  FormatParser's are stored in a FormatParserStorage such that they can be
+ *  retrieved with simply knowing the associated token.
+ *
+ *  We have this storage as the FormatParser may also contain extra information
+ *  per atom (...AtomDataContainer or alikes) which should be copied when an
+ *  atom is copied. Hence, as soon as a FormatParser is accessed once it sits
+ *  in the Storage and accumulates all information. Therefore, every parser
+ *  instance is unique per type throughout the run of the program.
+ *
+ *  A specific parser can be obtained from the FormatParserStorage just by
+ *  knowing the correct keyword such as this:
+ *  \code
+ *  ParserTypes type = FormatParserStorage::getInstance().getTypeFromName("xyz");
+ *  FormatParserInterface &parser = FormatParserStorage::getInstance().get(type);
+ *  \endcode
+ *
+ *  Associated to the FormatParser's is also the ChangeTracker (\ref observers)
+ *  that observers the World and tells all parsers on program exit whether
+ *  to save or not (i.e. whether any changes occurred). FormatParser_common
+ *  makes sure that each FormatParser signUp()s to this ChangeTracker.
+ *
+ *  Important is also the concept of a Parameter here. A Parameter is a value
+ *  of a certain type with a given valid range or set of valid values. There
+ *  ContinuousValue and DiscreteValue template classes that are subsequently
+ *  joined with a name to give a ContinuousParameter and DiscreteParameter to
+ *  be stored via a unifying ParameterInterface into a ParameterStorage. Such
+ *  an instance each of the FormatParser's contains. Therein extra information
+ *  such as a basis set, unit length, energy cutoff or other parser-specific
+ *  parameters are stored.
+ *
+ *  Various actions (WorldInputAction, WorldOuputAction, AtomSaveSelectedAtomsAction,
+ *  MoleculeSaveSelectedAction) use the parser to load or store atoms or to
+ *  control the behavior of storage (ParserSetOutputFormatAction, ...)
+ *
+ * \section parsers-add To add a new parser ...
+ *
+ *  The following tasks are necessary:
+ *  -# think of unique brief name for your parser, e.g. "xyz" and add to
+ *  \b ParserTypes.def. This will inform FormatParserStorage of your new parser.
+ *  (Again there is some preprocessor magic for instanting all ...)
+ *  -# Implement a FormatParserTraits specialization with some common stuff to
+ *    your parsers
+ *  \code
+ *  template<>
+ *  struct FormatParserTrait<name>
+ *  {
+ *    //!> Name of the parser
+ *    static const std::string name;
+ *    //!> suffix of the files the parser understands to read and write
+ *    static const std::string suffix;
+ *    //!> ParserTypes enumeration for the parser
+ *    static const enum ParserTypes type;
+ *  };
+ *  \endcode
+ *  where \a name is the name unique name of your parser, e.g. \a xyz.
+ *  -# Create all these static variables with matching contents.
+ *  -# Implement a FormatParser specialization
+ *  \code
+ *  template <>
+ *  class FormatParser< name >  : virtual public FormatParserInterface, public FormatParser_common
+ *  {
+ *  ...
+ *  };
+ *  \endcode
+ *  where \a name is again the name of your parser. FormatParser_common
+ *  contains some functionality common to all Parsers where FormatParserInterface
+ *  is the interface where load() and save() are defined. This allows for storage
+ *  in FormatParserRegistry.
+ *  -# implement FormatParserInterface::load() and FormatParserInterface::save().
+ *  -# implement FormatParser_common::AtomInserted() and
+ *    FormatParser_common::AtomRemoved()
+ *
+ *
+ * \date 2011-10-31
+ */
Index: src/documentation/constructs/randomnumbers.dox
===================================================================
--- src/documentation/constructs/randomnumbers.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/constructs/randomnumbers.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -12,2 +12,38 @@
  *    Author: heber
  */
+
+/** \page randomnumbers Random Number Generation
+ *
+ * There is a factory for random number generators present. This implementation
+ * has been necessary due to lack of a common interface on the side of the
+ * boost::random programmer. Hence, we added a RandomNumberInterface for both
+ * engine and distribution and a factory for both and finally the conglomerate
+ * for combining both into a single RandomNumberGenerator.
+ *
+ * Whereever random numbers should be picked with a varying distribution or
+ * even better a user-controlled one, this RandomNumberGenerator should be
+ * used, e.g. as this
+ * \code
+ * RandomNumberGenerator &random = RandomNumberGeneratorFactory::getInstance().makeRandomNumberGenerator();
+ * const double rng_min = random.min();
+ * const double rng_max = random.max();
+ * \endcode
+ * This returns a reference to a random number generator instance. And also we obtain
+ * its RandomNumberGenerator::min() and RandomNumberGenerator::max() values.
+ * Then, we may create random values as simple as this:
+ * \code
+ * double random_value = (random()/((rng_max-rng_min)/2.) - 1.);
+ * \endcode
+ * which creates a random value within [-1,1]. Note that random() here is
+ * RandomNumberGenerator::operator() and not some global function.
+ *
+ * \note Do not necessarily use the random number generation when just a uniform
+ * distribution is required. The implementation is especially designed to allow
+ * the user control over the random number distribution. E.g. when filling the void
+ * space in a simulation box with molecules he may choose a discrete distribution
+ * with a small number of values to have a few, but random orientations of the
+ * molecules (MoleculeFillVoidWithMoleculeAction()).
+ *
+ * \date 2011-10-31
+ *
+ */
Index: src/documentation/constructs/serialization.dox
===================================================================
--- src/documentation/constructs/serialization.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/constructs/serialization.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -14,2 +14,105 @@
  *    Author: heber
  */
+
+/** \page serialization Serialization
+ *
+ *  Serialization is a mighty concept. The is only possible within an object-
+ *  oriented framework. The member variables of a class make up its internal
+ *  state. By storing this state, creating another instance and restoring
+ *  the variables to this state, we may in essence clone the instance. However,
+ *  we obtain additional control as to the moment of restoration because the
+ *  internal state is stored temporarily. To allow for this storage all of
+ *  these variables have to be \e serialized.
+ *
+ *  Serialization refers to putting one after another into a writable form
+ *  (e.g. convert to string and write into a stringstream) and eventually
+ *  in reverse order to read them one by one from this writable form and
+ *  cast them back into their original type.
+ *
+ *  Here, this is done via boost::serialization.
+ *
+ *  \attention The serialization headers do not mingle well with \b MemDebug.hpp.
+ *  Hence, place them before MemDebug.hpp as they do funny stuff with the
+ *  new() operator.
+ *
+ *  Serialization is so powerful because the stored state can be stored to
+ *  disk, transfered to another thread or even to another computer. If received
+ *  by a compatible code, the instance is recreated and computation can be
+ *  continued elsewhere.
+ *
+ *  For the moment we use it for creating an undo state within the Action's.
+ *  I.e. we store the state of all instances that are modified by an Action's
+ *  doings and may in Action::performUndo() just re-create the unmodified
+ *  instance by loading them from the serializing archive.
+ *
+ *  \section serialization-add How to make your class serializable.
+ *
+ *  \subsection serialization-add-simple The simple case
+ *
+ *  All you need to do with your newly created class foo is this:
+ *  \code
+ *  class foo {
+ *  ...
+ *  private:
+ *    friend class boost::serialization::access;
+ *    template<class Archive>
+ *    void serialize(Archive & ar, const unsigned int version) const
+ *    {
+ *      ar & content;
+ *    }
+ *    ...
+ *    double content;
+ *  };
+ *  \endcode
+ *  This will implement a serialization function for both directions for the
+ *  member variable content. I.e. we may now store a class instance as this:
+ *  \code
+ *  #include <boost/archive/text_oarchive.hpp>
+ *  std::stringstream stream;
+ *  boost::archive::text_oarchive oa(stream);
+ *  oa << diagonal;
+ *  \endcode
+ *  This will store the state of the class in the stringstream \a stream.
+ *  Getting the instance back is then as easy as
+ *  \code
+ *  #include <boost/archive/text_iarchive.hpp>
+ *  boost::archive::text_iarchive ia(stream);
+ *  RealSpaceMatrix *newm;
+ *  ia >> newm;
+ *  \endcode
+ *
+ *  \subsection serialization-add-complicated The more complicated case
+ *
+ *  It gets trickier when load and store need to be done differently, e.h.
+ *  \code
+ *  class foo {
+ *  ...
+ *  private:
+ *    friend class boost::serialization::access;
+ *    // serialization
+ *    template<class Archive>
+ *    void save(Archive & ar, const unsigned int version) const
+ *    {
+ *      ar & content;
+ *    }
+ *    template<class Archive>
+ *    void load(Archive & ar, const unsigned int version)
+ *    {
+ *      ar & content;
+ *      createViews();
+ *    }
+ *    BOOST_SERIALIZATION_SPLIT_MEMBER()
+ *    ...
+ *  }
+ *  \endcode
+ *  Here, we split serialize() function into distinct load() and save() because
+ *  we have to call an additional function to fully re-store the instance, i.e.
+ *  it creates some internal reference arrays (Views) in a specific manner.
+ *
+ *  The serialize functions can also be added externally, i.e. outside of the
+ *  scope of the class, but can then access only public members (except we
+ *  again make it a friend).
+ *
+ *
+ * \date 2011-10-31
+ */
Index: src/documentation/constructs/shapes.dox
===================================================================
--- src/documentation/constructs/shapes.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/constructs/shapes.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -12,2 +12,40 @@
  *    Author: heber
  */
+
+/** \page shapes Shapes
+ *
+ * Shapes are present for denoting a specific region of the simulation domain.
+ * There are three types present:
+ *  - Sphere
+ *  - Ellipsoid
+ *  - Cuboid
+ *
+ * Note that both may be modified (shrink/grow, rotate, morph) via an arbitrary
+ * matrix.
+ *
+ * The shapes are for the moment only used within \ref descriptors to specify
+ * a specific subset of atoms, here that reside in a certain region of the
+ * simulation domain.
+ *
+ * \todo There is a certain relation between Tesselation and Shape. Hence, later
+ * Tesselation shall itself be a Shape, i.e. that describes a certain region in
+ * space, here via a tesselated mesh.
+ *
+ * Again, Shapes can be joined via boolean operators:
+ * - add
+ * - or
+ * - not
+ *
+ * And thus are a very powerful concept.
+ *
+ * E.g. a shape can be used like this
+ * \code
+ * Cuboid(Vector(0,0,0), Vector(2,2,2)) && !Sphere(Vector(1,1,1), 1.)
+ * \endcode
+ * which would be match any object within the cuboid from (0,0,0) to (2,2,2)
+ * that is not in the unit sphere at (1,1,1).
+ *
+ *
+ * \date 2011-10-31
+ *
+ */
Index: src/documentation/constructs/tesselation.dox
===================================================================
--- src/documentation/constructs/tesselation.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/constructs/tesselation.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -12,2 +12,37 @@
  *    Author: heber
  */
+
+/** \page tesselation Tesselation
+ *
+ * Tesselation is a first step towards recognizing molecular surfaces.
+ *
+ * Within the code it is used for calculating correlation functions with regard
+ * to such a surface.
+ *
+ * \section tesselation-procedure
+ *
+ * In the tesselation all atoms act as possible hindrance to a rolling sphere
+ * that moves in from infinity. whenever it rests uniquely on three distinct
+ * points (atoms) a triangle is created. The algorithm continues by flipping the
+ * sphere over one of the triangle's edges to eventually obtain a closed,
+ * tesselated surface of the molecule.
+ *
+ * \note This mesh is different to the usual sense of a molecular surface as
+ * atoms are directly located on it. Normally, one considers a so-called
+ * Van-der-Waals sphere around the atoms and tesselates over these. However,
+ * the mesh can easily be modified and even expanded to match the other
+ * (although the code for that is not yet fully implemented).
+ *
+ * \section tesselation-extension
+ *
+ * The main problem for extending the mesh to match with the normal sense is
+ * that triangles may suddenly intersect others when we have the case of a non-
+ * convex mesh (which is rather the normal case). And this has to be
+ * specifically treated. Also, it is not sure whether the procedure of
+ * expanding our current surface is optimal and one should not start on a
+ * different set of nodes created from virtual points resting on the
+ * van-der-Waals spheres.
+ *
+ * \date 2011-10-31
+ *
+ */
Index: src/documentation/constructs/world.dox
===================================================================
--- src/documentation/constructs/world.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
+++ src/documentation/constructs/world.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -0,0 +1,113 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file world.dox
+ *
+ * Created on: Oct 31, 2011
+ *    Author: heber
+ */
+
+/**
+ * \page world World
+ *
+ * The World is a singleton instance that can be obtained from everywhere.
+ * It stores information that globally need to be accessible but in a controlled
+ * manner. Therefore, the World is also an Observable that gives specific
+ * information when atoms or molecules have changed.
+ *
+ * The World is the one most important class of molecule. It contains the
+ * following important structures:
+ * - list of all atoms in the World, accessible via various functions
+ * - list of all molecules, likewise accessible via various functions
+ * - access to the Domain instance
+ * - access to the BondGraph instance
+ * - access to the config instance
+ * - access to the periodentafel instance
+ * - access to Thermostat instances
+ * - setting and getting of the ExitFlag (number returned on program exit)
+ * - access to WorldTime to setting the active time step
+ *
+ * I.e. whenever you need to do something with atoms, the World instance is
+ * involved.
+ *
+ * \section world-usage Howto use the World?
+ *
+ * Usage is a simple as:
+ * -# include the header \b World.hpp
+ * -# get an instance via
+ * \code
+ * World::getInstance()
+ * \endcode
+ *
+ * \section world-standard-procedures Standard Procedures
+ *
+ * In this section we explain various standard procedures wherein the World is
+ * involved.
+ *
+ * \note Accesssing molecules is very similar to accessing atoms, hence we only
+ * give the details for atoms here.
+ *
+ * \subsection world-standard-procedures-atom-const_iteration Iterating over all atoms
+ *
+ * When you want to iterate over all atoms, but only need const access, do this:
+ * \code
+ * for(World::internal_AtomIterator iter = World::getInstance().getAtomIter_internal();
+ *    iter != World::getInstance().atomEnd_internal();
+ *    ++iter) {
+ *   ...access *iter ...
+ * }
+ * \endcode
+ * However, these internal routines are protected. Hence, not every class may access
+ * them. Another variant is therefor to obtain a copy array:
+ * \code
+ * const World::AtomComposite atoms = World::getInstance().getAllAtoms();
+ * for(World::AtomComposite::const_iterator iter = atoms.begin();
+ *     iter != atoms.end();
+ *     ++iter) {
+ *   ...access *iter ...
+ * }
+ * \endcode
+ *
+ * \subsection world-standard-procedures-atom-iteration Iterating over all atoms
+ *
+ * When you want to iterate over all atoms, but only need const access, do this:
+ * \code
+ * for(World::AtomIterator iter = World::getInstance().getAtomIter();
+ *    iter != World::getInstance().atomEnd();
+ *    ++iter) {
+ *   ...access *iter ...
+ * }
+ * \endcode
+ * However, there we obtain an observed iterator. I.e. accessing *iter always
+ * calls forth an OBSERVE mechanism. Another variant is therefore to obtain a copy
+ * array:
+ * \code
+ * World::AtomComposite atoms = World::getInstance().getAllAtoms();
+ * for(World::AtomComposite::iterator iter = atoms.begin();
+ *     iter != atoms.end();
+ *     ++iter) {
+ *   ...access *iter ...
+ * }
+ * \endcode
+ *
+ * \subsection world-standard-procedures-atom-subset-iteration Iterating over subset of atoms
+ *
+ * Iterating over a subset involves giving a specific descriptor to either
+ * World::getAtomIter() or World::getAllAtoms() such as this:
+ * \code
+ * World::AtomIterator iter = World::getInstance().getAtomIter(AtomsBySelection());
+ * \endcode
+ * \code
+ * World::AtomComposite atoms = World::getInstance().getAllAtoms(AtomByType(1));
+ * \endcode
+ * respectively.
+ *
+ *
+ * \date 2011-10-31
+ *
+ */
Index: src/documentation/copyright.dox
===================================================================
--- src/documentation/copyright.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
+++ src/documentation/copyright.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -0,0 +1,38 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file copyright.dox
+ *
+ * Created on: Oct 31, 2011
+ *    Author: heber
+ */
+
+/**
+ * \page copyright Copyright notice
+ *
+ *  \e MoleCuilder - to create and alter molecular systems.
+ *
+ *  MoleCuilder has been developed at the Institute for Numerical Simulation.
+ *
+ *  \section contributors Contributors
+ *
+ *  Main developers of the code are:
+ *  - Tillmann Crueger
+ *  - Frederik Heber
+ *
+ *  The following persons have contributed to the code (in alphabetical order):
+ *  - Daniel Dueck
+ *  - Saskia Metzler
+ *  - Christian Neuen
+ *
+ *
+ *  Copyright (C) 2007-2011  University Bonn. All rights reserved.
+ *
+ * \date 2011-10-31
+ *
+ */
Index: src/documentation/faq.dox
===================================================================
--- src/documentation/faq.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/faq.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -16,7 +16,10 @@
 
 /**
- * \page faq "Frequently Asked Questions"
+ * \page faq Frequently Asked Questions
  *
  *  TODO: Documentation - add FAQ
  *
+ *
+ * \date 2011-10-31
+ *
  */
Index: src/documentation/fileformats.dox
===================================================================
--- src/documentation/fileformats.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
+++ src/documentation/fileformats.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -0,0 +1,29 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file fileformats.dox
+ *
+ * Created on: Oct 31, 2011
+ *    Author: heber
+ */
+
+/**
+ * \page fileformats Known File Types
+ *
+ * The supported output formats right now are:
+ *  -# mpqc: Configuration files of the Massively Parallel Quantum Chemistry package (Sandia labs)
+ *  -# pcp: Configuration files of the Parallel Car-Parrinello program (Institute for Numerical Simulation)
+ *  -# pdp: Configuration files of the Protein Data Base
+ *  -# psi3: Configuration files of the Psi3 package
+ *  -# tremolo: Configuration files of TREMOLO (Institute for Numerical Simulation)
+ *  -# xyz: the most basic format for the 3d arrangement of atoms consisting of a list of element and 3 coordinates.
+ *
+ *
+ * \date 2011-10-31
+ *
+ */
Index: src/documentation/howtos/action.dox
===================================================================
--- src/documentation/howtos/action.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
+++ src/documentation/howtos/action.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -0,0 +1,277 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file action.dox
+ *
+ * Created on: Oct 31, 2011
+ *    Author: heber
+ */
+
+/**
+ * \page howto-action Action Howto
+ *
+ * \section howto-action-introduction Introduction
+ *
+ * Actions are used in object oriented design as a replacement for callback functions.
+ * In most ways Actions can be used in the same way that callbacks were used in non
+ * OO-Systems, but can contain support for several extra mechanism such as undo/redo
+ * or progress indicators.
+ *
+ * The main purpose of an action class is to contain small procedures, that can be repeatedly
+ * called. These procedures can also be stored, passed around, so that the execution of an
+ * action can happen quite far away from the place of creation. For a detailed description of
+ * the Action pattern see GOF:1996.
+ *
+ * \subsection howto-action-usage How to use an action
+ *
+ * The process of using an action is as easy as calling the call() method of the action. The
+ * action will then do whatever it is supposed to do. If it is an action that can be undone, it
+ * will also register itself in the history to make itself available for undo. To undo the last
+ * action, you can either use the undoLast() method inside the ActionHistory class or call the
+ * UndoAction also provided by the ActionHistory. If an action was undone it will be available for
+ * redo, using the redoLast() method of the ActionHistory or the RedoAction also provided by this
+ * class. To check whether undo/redo is available at any moment you can use the hasUndo() or
+ * hasRedo() method respectively.
+ *
+ * Note that an Action always has two functions createDialog() and performCall(). The former
+ * returns a Dialog filled with query...() functions for all information that we need from the
+ * user. The latter must not contain any interaction but just uses these values (which are
+ * temporarily stored by class ValueStorage) to perform the Action.
+ *
+ * Furthermore, there is a global action function that makes the action callable with already
+ * present parameters (i.e. without user interaction and for internal use within the code only).
+ * This function is basically just a macro, that puts the parameters into the ValueStorage and
+ * calls Action::call(Action::NonInteractive).
+ *
+ * Actions can be set to be active or inactive. If an action is set to inactive it is signaling, that
+ * some condition necessary for this action to be executed is not currently met. For example the
+ * UndoAction will set itself to inactive, when there is no action at that time that can be undone.
+ * Using call() on an inactive Action results in a no-op. You can query the state of an action using
+ * the isActive() method.
+ *
+ * The undo capabilities of actions come in three types as signaled by two boolean flags (one
+ * combination of these flags is left empty as can be seen later).
+ * \li The first flag indicates if the undo mechanism for this action should be considered at all, i.e.
+ *   if the state of the application changes in a way that needs to be reverted. Actions that should
+ *   consider the undo mechanism are for example adding a molecule, moving atoms, changing
+ *   the name of a molecule etc. Changing the View-Area on the other hand should be an action that
+ *   does not consider the undo mechanism. This flag can be queried using the shouldUndo() method.
+ *
+ * \li The second flag indicates whether the changes can be undo for this action. If this flag is true
+ *   the action will be made available for undo using the ActionHistory class and the actions of this
+ *   class. If this flag is false while the shoudlUndo() flag is true this means that this action
+ *   changes the state of the application changes in a way that cannot be undone, but might cause
+ *   the undo of previous actions to fail. In this case the whole History is cleared, as to keep
+ *   the state of the application intact by avoiding dangerous undos. This flag can be queried
+ *   using the canUndo() method.
+ *
+ * Each action has a name, that can be used to identify it throughout the run of the application.
+ * This name can be retrieved using the getName() method. Most actions also register themselves with
+ * a global structure, called the ActionRegistry. Actions that register themselves need to have a
+ * unique name for the whole application. If the name is known these actions can be retrieved from
+ * the registry by their name and then be used as normal.
+ *
+ * \section howto-action-add Building your own actions
+ *
+ * Building actions is easy. Each specific ...Action is derived from the base class Action.
+ * In order to create all the reoccuring stuff, macros have been created which you can simply
+ * include and then don't need to worry about it.
+ * There are three major virtual functions: performCall(), performUndo(), performRedo() which
+ * you have to write, to equip your action with some actual capabilities.
+ * Each Action definition and implementation consists of of three files:
+ * -# cpp: contains performX() which you have to write, also some boilerplate functions which are
+ *         constructed automatically when including your def and "Actions/action_impl_pre.hpp"
+ * -# hpp: boilerplate definitions created simply by including your def and
+ *         "Actions/action_impl_header.hpp"
+ * -# def: macro definitions of all your parameters and additional variables needed for the state,
+ *         also name and category and token of your action.
+ *
+ * Best thing to do is look at one of the already present triples and you should soon understand
+ * what you have to add:
+ * -# pick the right category, i.e. the right folder in src/Actions
+ * -# pick the right name
+ * -# decide which parameters your actions need and what the type, the variable name and the token
+ *    to reference it from the command-line should be. Check whether already present and fitting
+ *    tokens exists, e.g. "position" as token for a Vector representing a position.
+ * -# consider which additional information you need to undo your action
+ * -# don't forget to include your .def file followed by "action_impl_pre.hpp" in .cpp or
+ *    "action_impl_header.hpp" in the .hpp
+ * -# continue to write the functionality of your action in performCall(), undo and redo in performUndo()
+ *    and performRedo().
+ * -# You should indicate whether the action supports undo by implementing the shouldUndo() and
+ *    canUndo() methods to return the appropriate flags.
+ *
+ * \subsection howto-action-add-notes Specific notes on the macros
+ *
+ * The following functions are created by the macros, i.e. you don't need to worry about it:
+ *
+ * Any user interaction should be placed into the dialog returned by fillDialog().
+ *
+ * Also, create the global function to allow for easy calling of your function internally (i.e.
+ * without user interaction). It should have the name of the Action class without the suffix Action.
+ *
+ * The constructor of your derived class also needs to call the Base constructor, passing it the
+ * name of the Action and a flag indicating whether this action should be made available in the
+ * registry. WARNING: Do not use the virtual getName() method of the derived action to provide the
+ * constructor with the name, even if you overloaded this method to return a constant. Doing this
+ * will most likely not do what you think it does (see: http://www.parashift.com/c++-faq-lite/strange-inheritance.html#faq-23.5
+ * if you want to know why this wont work)
+ *
+ * \subsection howto-action-add-undo Interfacing your Action with the Undo mechanism
+ *
+ * The performX() methods need to comply to a simple standard to allow for undo and redo. The first
+ * convention in this standard concerns the return type. All methods that handle calling, undoing
+ * or redoing return an object of Action::state_ptr. This is a smart pointer to a State object, that
+ * can be used to store state information that is needed by your action for later redo. A rename
+ * Action for example would need to store which object has been renamed and what the old name was.
+ * A move Action on the other hand would need to store the object that has been moved as well as the
+ * old position. If your Action does not need to store any kind of information for redo you can
+ * simply return Action::success and skip the rest of this paragraph. If your action has been
+ * abborted you can return Action::failure, which indicates to the history mechanism that this
+ * action should not be stored.
+ *
+ * If your Action needs any kind of information to undo its execution, you need to store this
+ * information in the state that is returned by the performCall() method. Since no assumptions
+ * can be made on the type or amount of information the ActionState base class is left empty.
+ * To use this class you need to derive a YourActionState class from the ActionState base class
+ * adding your data fields and accessor functions. Upon undo the ActionState object produced
+ * by the corresponding performCall() is then passed to the performUndo() method which should
+ * typecast the ActionState to the appropriate sub class, undo all the changes and produce
+ * a State object that can be used to redo the action if neccessary. This new state object is
+ * then used if the redo mechanism is invoked and passed to the performRedo() function, which
+ * again produces a State that can be used for performUndo().
+ *
+ * \section howto-action-implementation Outline of the implementation of Actions
+ *
+ * To sum up the actions necessary to build actions here is a brief outline of things methioned
+ * in the last paragraphs:
+ *
+ * \subsection howto-action-implementation-notes Specific notes on the macros
+ *
+ *  \li create parameter tupels (type, token, reference), put into def. Access them later in
+ *        the performX() via the structure params.###.
+ *  \li think of name, category and token for your action, put into def
+ *  \li create additional state variables tupels (type, reference) for storing extra information
+ *        that you need for undo/redo in the ActionState. You can always access the parameters
+ *        of your Action by state.params.### (i.e. they are copied to the state by default).
+ *  \li implement performCall(), first line should be calling of getParametersfromValueStorage().
+ *  \li performUndo(), performRedo()
+ *  \li implement the functions that return the flags for the undo mechanism, i.e. true/false.
+ *
+ * \subsection howto-action-implementation-perform-x Implementing performX() methods
+ *
+ *  \li performCall():
+ *   -# first line should be calling of getParametersfromValueStorage().
+ *   -# Access your parameters by the structure params.### (where ### stands for the reference/
+ *         variable name chosen in the tupel).
+ *   -# do whatever is needed to make the action work
+ *   -# if the action was abborted return Action::failure
+ *   -# if the action needs to save a state return a custom state object
+ *   -# otherwise return Action::success
+ *  \li performUndo():
+ *   -# typecast the ActionState pointer to a Pointer to YourActionState if necessary
+ *   -# undo the action using the extra information and the Action's parameters in the state
+ *   -# produce a new state that can be used for redoing and return it
+ *  \li performRedo():
+ *   -# take the ActionState produced by performUndo and typecast it to a pointer to YourActionState if necessary
+ *   -# redo the undone action using the extra information and the Action's parameters in the state
+ *   -# produce a new state that can be used by performUndo() and return it
+ *
+ * \section howto-action-advanced Advanced techniques
+ *
+ * \subsection howto-action-advanced-predefined Predefined Actions
+ *
+ * To make construction of actions easy there are some predefined actions. Namely these are
+ * the MethodAction and the ErrorAction.
+ *
+ * The method action can be used to turn any function with empty arguments and return type void
+ * into an action (also works for functors with those types). Simply pass the constructor for the
+ * MethodAction a name to use for this action, the function to call inside the performCall()
+ * method and a flag indicating if this action should be made retrievable inside the registry
+ * (default is true). MethodActions always report themselves as changing the state of the
+ * application but cannot be undone. i.e. calling MethodActions will always cause the ActionHistory
+ * to be cleared.
+ *
+ * ErrorActions can be used to produce a short message using the Log() << Verbose() mechanism of
+ * the molecuilder. Simply pass the constructor a name for the action, the message to show upon
+ * calling this action and the flag for the registry (default is again true). Error action
+ * report that they do not change the state of the application and are therefore not considered
+ * for undo.
+ *
+ * \subsection howto-action-advanced-sequences Sequences of Actions and MakroActions
+ *
+ * \paragraph howto-action-advanced-sequences-add Building sequences of Actions
+ *
+ * Actions can be chained to sequences using the ActionSequence class. Once an ActionSequence is
+ * constructed it will be initially empty. Any Actions can then be added to the sequence using the
+ * addAction() method of the ActionSequence class. The last added action can be removed using the
+ * removeLastAction() method. If the construction of the sequence is done, you can use the
+ * callAll() method. Each action called this way will register itself with the History to allow
+ * separate undo of all actions in the sequence.
+ *
+ * \paragraph howto-action-advanced-sequences-build-larger Building larger Actions from simple ones
+ *
+ * Using the pre-defined class MakroAction it is possible to construct bigger actions from a sequence
+ * of smaller ones. For this you first have to build a sequence of the actions using the ActionSequence
+ * as described above. Then you can construct a MakroAction passing it a name, the sequence to use
+ * and as usual a flag for the registry. You can then simply call the complete action-sequence through
+ * this makro action using the normal interface. Other than with the direct use of the action sequence
+ * only the complete MakroAction is registered inside the history, i.e. the complete sequence can be
+ * undone at once. Also there are a few caveats you have to take care of when using the MakroAction:
+ *  -# All Actions as well as the sequence should exclusively belong to the MakroAction. This
+ *        especially means, that the destruction of these objects should be handled by the MakroAction.
+ *  -# none of the Actions inside the MakroAction should be registered with the registry, since the
+ *        registry also assumes sole ownership of the actions.
+ *  -# Do not remove or add actions from the sequence once the MakroAction has been constructed, since this
+ *        might brake important assumptions for the undo/redo mechanism
+ *
+ * \section howto-action-special Special kinds of Actions
+ *
+ * To make the usage of Actions more versatile there are two special kinds of actions defined,
+ * that contain special mechanisms. These are defined inside the class Process, for actions that
+ * take some time and indicate their own progress, and in the class Calculations for actions that
+ * have a retrievable result.
+ *
+ * \subsection howto-action-special-process Processes
+ *
+ * Processes are Actions that might take some time and therefore contain special mechanisms
+ * to indicate their progress to the user. If you want to implement a process you can follow the
+ * guidelines for implementing actions. In addition to the normal Action constructor parameters,
+ * you also need to define the number of steps the process takes to finish (use 0 if that number is
+ * not known upon construction). At the beginning of your process you then simply call start() to
+ * indicate that the process is taking up its work. You might also want to set the number of steps it
+ * needs to finish, if it has changed since the last invocation/construction. You can use the
+ * setMaxSteps() method for this. Then after each finished step of calulation simply call step(),
+ * to let the indicators know that it should update itself. If the number of steps is not known
+ * at the time of calculation, you should make sure the maxSteps field is set to 0, either through
+ * the constructor or by using setMaxSteps(0). Indicators are required to handle both processes that
+ * know the number of steps needed as well as processes that cannot predict when they will be finished.
+ * Once your calculation is done call stop() to let every indicator know that the process is done with
+ * the work and to let the user know.
+ *
+ * Indicators that want to know about processes need to implement the Observer class with all the
+ * methods defined there. They can then globally sign on to all processes using the static
+ * Process::AddObserver() method and remove themselves using the Process::RemoveObserver()
+ * methods. When a process starts it will take care that the notification for this process
+ * is invoked at the right time. Indicators should not try to observe a single process, but rather
+ * be ready to observe the status of any kind of process using the methods described here.
+ *
+ * \subsection howto-action-special-calculation Calculations
+ *
+ * Calculations are special Actions that also return a result when called. Calculations are
+ * always derived from Process, so that the progress of a calculation can be shown. Also
+ * Calculations should not contain side-effects and not consider the undo mechanism.
+ * When a Calculation is called using the Action mechanism this will cause it to calculate
+ * the result and make it available using the getResult() method. Another way to have a Calculation
+ * produce a result is by using the function-call operator. When this operator is used, the Calculation
+ * will try to return a previously calculated and cached result and only do any actuall calculations
+ * when no such result is available. You can delete the cached result using the reset() method.
+ *
+ *
+ * \date 2011-10-31
+ */
Index: src/documentation/howtos/howtos.dox
===================================================================
--- src/documentation/howtos/howtos.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
+++ src/documentation/howtos/howtos.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -0,0 +1,24 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file howtos.dox
+ *
+ * Created on: Oct 31, 2011
+ *    Author: heber
+ */
+
+/**
+ * \page howto Collection of all howtos
+ *
+ * The following Howtos are available:
+ * - \ref howto-action
+ *
+ *
+ * \date 2011-10-31
+ *
+ */
Index: src/documentation/install.dox
===================================================================
--- src/documentation/install.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/install.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -13,15 +13,123 @@
  */
 
-/* \page install Installation
+/**
+ *  \page install Installation
  *
- *  Installation should without problems succeed as follows:
- *  -# ./configure (or: mkdir build;mkdir run;cd build; ../configure --bindir=../run)
- *  -# make
- *  -# make install
+ * \section install-compiling Compiling the Code
+ *
+ * After you obtained the code, you do the following:
+ *
+ * \code
+ * ./bootstrap
+ * \endcode
+ *
+ * This creates the necessary autoconf and automake files.
+ *
+ * After this,
+ *
+ * \code
+ * mkdir build
+ * cd build
+ * ../configure --prefix=`pwd`
+ * \endcode
+ *
+ * which will run the configure script that checks whether you have a current
+ * version of the following required packages
+ *
+ * -# 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>)
+ * -# CPPUnit framework (--with-cppunit-prefix=<dir>)
+ * -# CodePatterns (--with-codepatterns=<dir>)
+ *
+ * \a --prefix is the argument to tell configure where all program code should go
+ * to (pwd is the unix command for the current working directory). There are
+ * others, see
+ *
+ * \code
+ * ../configure --help
+ * \endcode
+ *
+ * and some enable/disable switches you should check out:
+ *
+ * - \a --enable-ecut - says that the TestRunner, comprising all unit tests in one
+ *  exectuable, shall make use of the Eclipse CppUnitTest (ECUT). If this is
+ *  started within eclipse with this plugin installed, a shiny interface will tell
+ *  you what failed and what not.
+ * - \a --enable-debug - activates many internal asserts, memory debugger and more
+ *  (makes code a lot slower but gives information in case something fails)
+ *
+ * \note A note about configure: If one library is found only under some specific path, you
+ * can add CFLAGS, CPPFLAGS, LDFLAGS, ... to the configure call, like this
+ * \code
+ * ../configure --prefix=`pwd` --enable-hydrogen CFLAGS="-Wall -g3" CXXFLAGS="-Wall -g3"
+ * \endcode
+ * which enables all compiler warnings and full debugging of the code without any
+ * optimization. configure saves these variables, too, such that when it is called
+ * to re-configure it will still make use of them from its cache file.
+ *
+ * There are several flags that change the way molecuilder is compiled and probably
+ * make it run faster, more unsafe, ...
+ * -# \a -DLOG_OBSERVER,  What the Observers do is logged, the log is printed on exit
+ * -# \a -DNO_MEMDEBUG,   MemDebug (memory debugger) is disabled
+ * -# \a -DNO_CACHING,  Cachable are short-wired, i.e. always recalculate, this slows
+ *  down the code a lot
+ * -# \a -DNDEBUG,  include NO_MEMDEBUG, also ASSERTs are not checked, this speeds up
+ *  the code by a factor of 5
+ *
+ * \section install-install Installing
+ *
+ * Now, we are ready to compile and install.
+ *
+ * \code
+ * make
+ * make install
+ * \endcode
+ *
+ * \attention If you have a multi-core system, it is highly recommended to use the
+ * \a -j option of make to allow for multiple threads to work on compiling or
+ * checking the codfe simultaneously.
+ *
+ * And if everything went well, you should launch the unit tests and the testsuite
+ * by (see section \ref tests on how to launch the tests individually)
+ *
+ * \code
+ * make check
+ * \endcode
+ *
+ * If everything is OK, you have a working version of MoleCuilder in form of the
+ * executables \b bin/molecuilder and \b bin/molecuildergui.
+ *
+ * If you have to delete all compiled stuff, enter
+ *
+ * \code
+ * make clean
+ * \endcode
+ *
+ * or
+ *
+ * \code
+ * make distclean
+ * \endcode
+ *
+ * which will also delete all autoconf stuff for configure.
+ *
+ * distclean is at times necessary when stuff does not compile and there's
+ * seemingly no logic behind it, i.e. especially when paths of modules have
+ * changed. To recover your configure options, either look at \b config.log in
+ * the build directory or enter
+ *
+ * \code
+ * ./config.status --version
+ * \endcode
  *
  *  Further useful commands are
- *  -# make clean uninstall: deletes .o-files and removes executable from the given binary directory\n
- *  -# make doxygen-doc: Creates these html pages out of the documented source
- *  -# make check: Runs an extensive set of unit tests and a testsuite which also gives a good overview on the set of
- *                 functions.
+ *  -# make clean uninstall: deletes .o-files and removes executable from the given
+ *    binary directory
+ *  -# make doc: Creates these html pages out of the documented source
+ *  -# make check: Runs an extensive set of unit tests and a testsuite which also gives
+ *    a good overview on the set of functions.
+ *
+ * \date 2011-10-31
  */
Index: src/documentation/launch.dox
===================================================================
--- src/documentation/launch.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/launch.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -13,24 +13,28 @@
  */
 
-/*
- * \subpage launch Running the code
+/**
+ * \page launch Running the code
  *
- *  The program can be executed by running: ./molecuilder
+ *  Before you have done
+ *  \code
+ *  make install
+ *  \endcode
+ *  The executables are in the \b src folder of your build directory. There are
+ *  two variants:
+ *  - molecuilder (contains command line and text interface)
+ *  - molecuildergui (contains graphical user interface)
  *
- *  MoleCuilder has three interfaces at your disposal:
- *  -# Textmenu: A simple interactive console-based menu, where awaits your choices and inputs in order to set atoms
- *               as you like
- *  -# CommandLineUI: Every command can also be chained up as a sequence of actions on the command line to be executed
- *               with any user interaction.
- *  -# GraphicalUI: A graphical user interface that also display the molecular structure being built and lots of other
- *               informations to ease the construction of bigger geometries.
+ *  The programs can be executed by running:
+ *  - Text menu: Launching molecuilder with no options always gives the text menu.
+ *    \code ./molecuilder \endcode
+ *  - Command line menu: Depends on what you want, but an exemplary call is
+ *    \code ./molecuilder -i test.xyz -o tremolo xyz -v 3 --add-atom H --position "0,0,0"\endcode
+ *  - Graphical menu
+ *    \code ./molecuildergui \endcode
  *
- *  The supported output formats right now are:
- *  -# mpqc: Configuration files of the Massively Parallel Quantum Chemistry package (Sandia labs)
- *  -# pcp: Configuration files of the Parallel Car-Parrinello program (Institute for Numerical Simulation)
- *  -# tremolo: Configuration files of TREMOLO (Institute for Numerical Simulation)
- *  -# xyz: the most basic format for the 3d arrangement of atoms consisting of a list of element and 3 coordinates.
+ * The user interface are explained in greater detail in \ref userinterfaces.
  *
- *  \section
+ *
+ * \date 2011-10-31
  *
  */
Index: src/documentation/mainpage.dox
===================================================================
--- src/documentation/mainpage.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/mainpage.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -22,27 +22,54 @@
  */
 
-/*! \mainpage MoleCuilder - a molecular set builder
+/** \mainpage MoleCuilder - a molecular set builder
  *
- * This introductory shall briefly make acquainted with the program, helping in installing and a first run.
+ * This is the main page of the Doxygen documentation of \e MoleCuilder. We give
+ * a brief description what the program is intended to do and then branch via
+ * the contents of this documentation into various topics.
  *
  * \section about About the Program
  *
- *  MoleCuilder is a program, written entirely in C++, that enables the construction of a coordinate set for the
- *  atoms making up an molecule. It allows for both building of simple molecules by adding atom-wise giving bond
- *  angles and distances or absolute coordinates, but also using them as templates. Regions can be specified and
- *  ordered to be filled with a molecule in a certain manner. Greater conglomerations of molecules can be tesselated
- *  and recognized as a region themselves to be subsequently surrounded by other (surface solvated) molecules.
- *  In the end, MoleCuilder allows the construction of arbitrary nano structures, whether they be crystalline or
- *  amorphic in nature.
+ *  MoleCuilder is a program, written entirely in C++, that enables the
+ *  construction of a coordinate set for the atoms making up an molecule. It
+ *  allows for both building of simple molecules by adding atom-wise giving bond
+ *  angles and distances or absolute coordinates, but also using them as
+ *  templates. Regions can be specified and ordered to be filled with a molecule
+ *  in a certain manner. Greater conglomerations of molecules can be tesselated
+ *  and recognized as a region themselves to be subsequently surrounded by other
+ *  (surface solvated) molecules. In the end, MoleCuilder allows the construction
+ *  of arbitrary nano structures, whether they be crystalline or amorphic in
+ *  nature.
  *
- *  For copyright see \subpage copyright.
+ *  For copyright see \ref copyright.
  *
- * \section Contents
+ * \section idea The central idea behind the program
+ *
+ * What are the central ideas?
+ *
+ * - Testedness: See \ref tests-policy which is meant \e seriously. Nothing is
+ *   worse than one version behaving different to the next with respect to
+ *   output.
+ * - Re-usability: Every piece of functionality should be easy to re-use at
+ *   someplace else. Say no to specialized one-purpose scripts, say yes to
+ *   a LEGO-like system of building your world.
+ * - Extendability: It's easy to add a new piece to the code. And it is even
+ *   more so, if you have read this documentation and know what's all already
+ *   in place.
+ * - Userfriendliness: Every Action can be undone, every Action gives lots
+ *   of output (if desired) to tell you what's going on. It's easy to save
+ *   files in between. There are also three kinds of GUIs, each of which
+ *   have the same functionality.
+ *
+ * \section contents Contents
  *
  * This manual is divided into the following sections:
- * \li \subpage install "Installation Instructions"
- * \li \subpage test "Automated testing"
- * \li \subpage launch "Launching the Code"
- * \li \subpage code "How to the use and extend the code"
+ * \li \ref install
+ * \li \ref tests
+ * \li \ref launch
+ * \li \ref debug
+ * \li \ref code
+ * \li \ref fileformats
+ *
+ * \date 2011-10-31
  *
  */
Index: src/documentation/tests/code-tests.dox
===================================================================
--- src/documentation/tests/code-tests.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/tests/code-tests.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -22,10 +22,12 @@
  * -# Every .cpp files must include \b config.h and \b CodePatterns/MemDebug.hpp
  * -# Every .hpp files must include \b config.h
+ * -# Every .dox file contains a (correctly formatted: YYYY-MM-DD) date stamp.
  *
  * These make sure that the memory debugger is catching every movement on the
- * heap and that every module knows about the behavior controling defines that
- * are checked by autoconf and written to \b config.h in the build directory.
+ * heap and that every module knows about the behavior controling \e #define's that
+ * are checked by autoconf and written to \b config.h in the build directory. And
+ * also that for every documentation file it is known when it was current.
  *
- * \section Directory structure
+ * \section codetest-structure Directory structure
  *
  * The code tests are contained in \b tests/CodeChecks. Therein are all test
@@ -33,15 +35,66 @@
  * Mostly, these look through files
  *
- * \section Launching all tests
+ * \section codetest-launch-all Launching all tests
  *
- *  TODO: Documentation - explain how to launch all code tests.
+ *  In order to launch all tests, simply do:
+ *  -# Enter \b tests/CodeChecks in your build directory
+ *  -# Run
+ *    \code make check \endcode
+ *    there
  *
- * \section Launching some tests
+ * \section codetest-launch-some Launching some tests
  *
- *  TODO: Documentation - explain how to launch some code tests
+ *  Launching a single or just some of the tests is only a little bit more
+ *  complicated. Proceed as follows:
+ *  -# Enter \b tests/CodeChecks in your build directory
+ *  -# Run
+ *  \code ../../../tests/CodeChecks/testsuite <option> AUTOTEST_PATH="<buildpath>/src" \endcode,
+ *  where \a <option> is explained in the subsections below and \a <buildpath> is
+ *  the build path (i.e. the variable \a AUTOTEST_PATH should contain the path to
+ *  the executable).
  *
- * \section Inspecting results
+ *  \subsection regressiontest-launch-by-number ... by number
  *
- *  TODO: Documentation - explain how to inspect code test results.
+ *    Tests can be launched by specifying their test number, e.g. then \a <option>
+ *    might be \a 1 or \a 1-2 or just nothing for all of them.
+ *
+ *  \subsection regressiontest-launch-by-keyword .. by keyword
+ *
+ *    Tests may as well be launched by some keywords, e.g. each code check has
+ *    a specific keyword which is given via \b AT_KEYWORD directive of Autotest.
+ *    I.e. we may launch the test on \b config.h presence via the \a <option>
+ *    \a -k \a config_h. Also multiple keywords may be given.
+ *
+ * \section codetest-results Inspecting results
+ *
+ *  The testsuite can be launched with the additional option of \a -d which leaves the
+ *  directory of the test present even though the test has passed for inspection.
+ *
+ *  If a test fails, in whatever way it was launched, will leave in the build directory
+ *  a folder \b tests/CodeChecks/testsuite.dir/<nr> where \a <nr> is the number of the
+ *  test (padded maybe with some zeros).
+ *
+ *  In the current state tests will fail because one file does not include \b
+ *  config.h or \b MemDebug.hpp. Hence, check the testsuite's log to get the file
+ *  name of the culprit at its very bottom.
+ *
+ * \section unittest-add Adding new tests
+ *
+ *  \attention Name convention of files, (no spaces, use underscore) e.g.
+ *  \b testsuite-config_h.at
+ *  - the test script file should be called as follows:
+ *    -# testsuite-...
+ *    -# followed by the construct that is tested.
+ *
+ *  In order to add a new test, you have to do the following:
+ *  -# Add a new \b testsuite-....at script to the folder \b tests/CodeChecks
+ *    (have a look at the present ones and see above for help on the commands
+ *    recognized by Autotest. \e Mind \e giving it a suitable \e keyword!).
+ *  -# Add the file to Makefile.am such that the testsuite is re-created when
+ *    you change the test script.
+ *  -# Add the file as an \e m4_include directive to testsuite.at.
+ *
+ *
+ * \date 2011-10-31
  *
  */
Index: src/documentation/tests/regression-tests.dox
===================================================================
--- src/documentation/tests/regression-tests.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/tests/regression-tests.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -25,5 +25,5 @@
  * regression tests.
  *
- * \section Directory structure
+ * \section regressiontest-structure Directory structure
  *
  * They are contained in the source folder \b tests/regression. There are
@@ -36,5 +36,64 @@
  *  named test script one directory level higher.
  *
- *  \section Adding a new test
+ *  \section regressiontest-launch-all Launching all tests
+ *
+ *  Launching all regression tests is as simple as:
+ *  -# Enter the build directory
+ *  -# There, enter \b tests/regression
+ *  -# Run
+ *  \code make check \endcode
+ *  (at you liberty with option \a -j8 or similar for running the tests in
+ *  parallel.
+ *
+ *  \section regressiontest-launch-some Launching a specific tests
+ *
+ *  Launching a single or just some of the tests is only a little bit more
+ *  complicated. There are two options: either by the test number which however
+ *  changes when new tests are added, and by keywords.
+ *
+ *  Then proceed as follows:
+ *  -# Enter the build directory
+ *  -# There, enter \b tests/regression
+ *  -# Run
+ *  \code ../../../tests/regression/testsuite <option> AUTOTEST_PATH="<buildpath>/src" \endcode,
+ *  where \a <option> is explained in the subsections below and \a <buildpath>
+ *  is the build path (i.e. the variable \a AUTOTEST_PATH should contain the
+ *  path to the executable).
+ *
+ *  \subsection regressiontest-launch-by-number ... by number
+ *
+ *    Tests can be launched by specifying their test number, e.g. then \a <option>
+ *    might be \a 283 or \a 283-284 or \a 283,285-286 or alike
+ *
+ *  \subsection regressiontest-launch-by-keyword .. by keyword
+ *
+ *    Tests may as well be launched by some keywords, e.g. each Action has a
+ *    specific token which is also one of its keyword (see above for the
+ *    policy). I.e. we may launch the test on fill-void via the \a <option>
+ *    \a -k \a fill-void. Also multiple keywords may be given.
+ *
+ * \section regressiontest-results Inspecting test results
+ *
+ *  The testsuite can be launched with the additional option of \a -d which
+ *  leaves the directory of the test present even though the test has passed
+ *  for inspection.
+ *
+ *  If a test fails, in whatever way it was launched, will leave in the build
+ *  directory a folder \b tests/regression/testsuite.dir/<nr> where \a <nr> is
+ *  the number of the test (padded maybe with some zeros).
+ *
+ * \section regressiontest-add Adding a new test
+ *
+ *  \attention Name convention of files and directories, e.g.
+ *  \b tests/regression/Parser/Pdb with \b testsuite-parser-pdb-save.at
+ *  - the test directory should either be called as the token of the Action it
+ *    tests or a unique and brief description but with no spaces, no dashes,
+ *    but CamelCase (i.e. Capitalize each new word)
+ *  - the test script file should be called as follows:
+ *    -# testsuite-...
+ *    -# ...each directory (non-capital letters) with a dash...
+ *    -# ..the name of the test directory...
+ *    -# a further description of there are multiple test scripts in the
+ *      test directory.
  *
  *  Adding a new regression tests consists of the following items:
@@ -51,47 +110,6 @@
  *  testsuite is automatically re-compiled when one of the test files has changed.
  *
- *  \section Launching all tests
  *
- *  Launching all regression tests is as simple as:
- *  -# Enter the build directory
- *  -# There, enter \b tests/regression
- *  -# Run
- *  \code make check \endcode
- *  (at you liberty with option \a -j8 or similar for running the tests in parallel.
- *
- *  \section Launching a specific tests
- *
- *  Launching a single or just some of the tests is only a little bit more complicated.
- *  There are two options: either by the test number which however changes when new
- *  tests are added, and by keywords.
- *
- *  Then proceed as follows:
- *  -# Enter the build directory
- *  -# There, enter \b tests/regression
- *  -# Run
- *  \code ../../../tests/regression/testsuite <option> AUTOTEST_PATH="<buildpath>/src" \endcode,
- *  where \a <option> is explained in the subsections below and \a <buildpath> is the build
- *  path (i.e. the variable \a AUTOTEST_PATH should contain the path to the executable).
- *
- *  \subsection ... by number
- *
- *    Tests can be launched by specifying their test number, e.g. then \a <option>
- *    might be \a 283 or \a 283-284 or \a 283,285-286 or alike
- *
- *  \subsection .. by keyword
- *
- *    Tests may as well be launched by some keywords, e.g. each Action has a specific
- *    token which is also one of its keyword (see above for the policy). I.e. we may
- *    launch the test on fill-void via the \a <option> \a -k \a fill-void. Also
- *    multiple keywords may be given.
- *
- * \section Inspecting test results
- *
- *  The testsuite can be launched with the additional option of \a -d which leaves the
- *  directory of the test present even though the test has passed for inspection.
- *
- *  If a test fails, in whatever way it was launched, will leave in the build directory
- *  a folder \b tests/regression/testsuite.dir/<nr> where \a <nr> is the number of the
- *  test (padded maybe with some zeros).
+ * \date 2011-10-31
  *
  */
Index: src/documentation/tests/tests.dox
===================================================================
--- src/documentation/tests/tests.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/tests/tests.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -25,17 +25,20 @@
  * testing. Tests are regarded here as a kind of contract. The code itself is
  * just one hand in two hands shaking, the other hand is resembled by the tests
- * that checks whether the code does exactly what it's supposed to do. Without
- * testing a larger project is impossible because it cannot evolve. With
- * increasing size, a project must be refactored
- * (http://en.wikipedia.org/wiki/Code_refactoring) such that new code does not
- * have to wiggle itself around the same old issues that are present from the
- * start. Before one starts refactoring, it must be assured by some means that
- * the code before and after behaves the same with respect to its intended
- * functionality. These means are the tests.
+ * that check whether the code does exactly what it's supposed to do. Without
+ * testing a larger project is impossible because it cannot evolve: The old
+ * addage and compromises grow and grow. With increasing size, a project must be
+ * refactored (http://en.wikipedia.org/wiki/Code_refactoring) such that new code
+ * does not have to wiggle itself around the same old issues that are
+ * inadvertently and unavoidably present from the start. Before one starts
+ * refactoring, it must be assured by some means that the code before and after
+ * behaves the same with respect to its intended functionality. These means are
+ * the tests.
  *
- * Unit tests (http://en.wikipedia.org/wiki/Unit_testing) tests single
- * components (e.g. classes), dependencies on other classes are often just
- * mimicked via so-called stubs. These test whether a component always behaves
- * as desired.
+ * Unit tests (http://en.wikipedia.org/wiki/Unit_testing) check on single
+ * components (e.g. classes), dependencies of the components on other classes
+ * with the test frame are often just mimicked via so-called stubs (sort of
+ * dummy components that don't calculate or do anything but return an expected
+ * result suitable for this test only, see http://en.wikipedia.org/wiki/Test_stubs).
+ * These test whether a component always behaves as desired.
  *
  * Regression test (http://en.wikipedia.org/wiki/Regression_testing) on the other
@@ -45,9 +48,11 @@
  * has not changed the outcome of older functions.
  *
+ * \section tests-launch-all Launching all tests
+ *
  * Note that all tests can be launched via
  * \code make check \endcode
  * in the top build directory.
  *
- * \section Policy on launching tests
+ * \section tests-policy Policy on launching tests
  *
  * Note that the above run of \e all \e tests \e should \e pass for each and
@@ -60,3 +65,5 @@
  * runs fine and produces a distributable archive.
  *
+ * \date 2011-10-31
+ *
  */
Index: src/documentation/tests/unit-tests.dox
===================================================================
--- src/documentation/tests/unit-tests.dox	(revision 19bc7497091ba44d7d2c52ee7ba0f5997f9f291e)
+++ src/documentation/tests/unit-tests.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -18,5 +18,5 @@
  * Unit tests are done via the CppUnit framework (http://cppunit.sourceforge.net/doc/1.8.0/).
  *
- * \section Directory structure
+ * \section unittest-structure Directory structure
  *
  *  Unit tests are always located in a subfolder \b unittests of the component
@@ -24,9 +24,5 @@
  *  resides in \b src/Parser/unittests.
  *
- * \section Adding new tests
- *
- *  TODO: Documentation - explain how to add tests.
- *
- * \section Launching all tests
+ * \section unittest-launch-all Launching all tests
  *
  *  All unit tests can be launched as follows:
@@ -39,5 +35,5 @@
  * This will run all present unit tests one after the other.
  *
- * \section Launching some tests
+ * \section unittest-launch-some Launching some tests
  *
  *  If only some of the tests should be checked, then they have to be launched by
@@ -56,8 +52,52 @@
  *  libraries, which have not been installed so far, are found.
  *
- * \section Inspecting results
+ * \section unittest-results Inspecting results
  *
  *  Results of the test are shown during run. An \a Ok(2) indicates that
  *  two tests for the single launched testsuite passed.
  *
+ * \section unittest-add Adding new tests
+ *
+ *  \attention Name convention of files, (no spaces, use CamelCase) e.g.
+ *  \b AnalysisBondsUnitTest
+ *  - the unit test module should be called as follows:
+ *    -# either the name of the component or the module
+ *    -# followed by UnitTest.
+ *  - the test class should be called as follows:
+ *    -# the name of the class it tests
+ *    -# followed by Test.
+ *
+ *  Adding a new test is as easy as this:
+ *  -# Create a new module for declaration and definition of the unit test
+ *    in a suitable \b unittests subfolder (see above on policy and naming).
+ *    Check out one of the present unit tests and rename, but beware of
+ *    copy&paste errors!
+ *  -# Add the test to the \b Makefile.am contained in \b unittests.
+ *
+ *  If there is not yet a \b unittests folder:
+ *  -# Create a new \b Makefile.am, check out one of the present ones to get
+ *    an idea, below is a small list of contained elements. Note that the
+ *    variable must begin with a unique name as all Makefile.am on unit tests
+ *    are included into one big Makefile.am in \b src/unittests.
+ *  -# Add your ...SOURCES and ...HEADERS to TESTSOURCES and TESTHEADERS.
+ *  -# Add an include directive to \b src/unittests/Makefile.am of this
+ *    newly created \b Makefile.am.
+ *
+ *  What's contained in the \b Makefile.am:
+ *  -# ...SOURCES and ...HEADERS gathering all source and header files in this
+ *    \b unittests folder (this is needed for the test program that contains
+ *    all unit test in one executable).
+ *  -# ...TESTS gathering all test programs in this \b unittests folder.
+ *  -# ...TESTS is added to TESTS, check_PROGRAMS, noinst_PROGRAMS such that
+ *    it is known that they are just tests, programs for \a make \a check and
+ *    are not to be installed.
+ *  -# ...LIBS gathers general libs that all of the tests in this \b unittests
+ *    folder share.
+ *  -# for each unit test:
+ *    -# ...SOURCES gathers all source files that are required for the test.
+ *    -# ...LDADD gathers all libs that are required for compilation.
+ *
+ *
+ * \date 2011-10-31
+ *
  */
Index: src/documentation/userinterfaces/commandline.dox
===================================================================
--- src/documentation/userinterfaces/commandline.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
+++ src/documentation/userinterfaces/commandline.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -0,0 +1,38 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file commandline.dox
+ *
+ * Created on: Oct 31, 2011
+ *    Author: heber
+ */
+
+/**
+ * \page commandline Command Line Interface
+ *
+ * The command line interface allows for using MoleCuilder within scripts such
+ * system with only slightly varying parameters can be built in a straight-
+ * forward way.
+ *
+ * Commands are parsed via the CommandLineParser with uses boost::program_options
+ * to recognize the given options. ActionRegistry and OptionRegistry are used
+ * to distinguish Option's from Action's. A specific type per option is expected
+ * and the ValueStorage assures that only the correct type is parsed.
+ *
+ * So far the sequence of the Option's is not really important but for the
+ * Action's the ordering counts: first come, first serve.
+ *
+ * Undoing is possible as well. But is so far only used in the regression test
+ * to test its functionality. This will become more usefull when the
+ * ActionHistory is stored to file and past session can be re-enacted by loading
+ * simply it. Their undo would allow for traversing back in this history.
+ *
+ *
+ * \date 2011-10-31
+ *
+ */
Index: src/documentation/userinterfaces/graphical.dox
===================================================================
--- src/documentation/userinterfaces/graphical.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
+++ src/documentation/userinterfaces/graphical.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -0,0 +1,55 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file graphical.dox
+ *
+ * Created on: Oct 31, 2011
+ *    Author: heber
+ */
+
+/**
+ * \page graphical Graphical User Interface
+ *
+ * The GUI is based on Qt4. It used Qt3D for displaying the GlWorldView and
+ * allowing for easy selecting of atoms and molecules.
+ *
+ * The GUI consists of the following parts:
+ * - a menu created in a likewise as the one for the \ref textmenu.
+ * - a world view, implemented in GLWorldView, displaying atoms and bonds
+ *   and allowing for selecting them.
+ * - A list of all currently selected molecules.
+ * - A list of all currently present molecules.
+ *
+ * \section graphical-query Queries in the graphical interface.
+ *
+ * As all Action always instantiate a Dialog which behaves differently for
+ * each of the three user interface, we give a brief description of what it
+ * does here.
+ *
+ * Each of the query implementations receives a reference to a QLayout where
+ * it just adds its own query, e.g. for a double or a list of strings.
+ * Eventually, this concatenated dialog is presented to the user -- it might
+ * be empty though as well -- he enters all values and clicks accept (even
+ * in case of an empty dialog). These values are passed via a Pipe mechanism
+ * (this is a workaround as Qt's moc does not liked nested classes) to the
+ * ValueStorage.
+ *
+ * \section graphical-world_view How the World view works ...
+ *
+ * GLWorldView handles the Observer translation to Qt's own mechanism. Also, it
+ * contains an instance of the GLWorldScene. This instance knows about all
+ * atoms and bonds present in this scene, i.e. it has lists on them and handles
+ * adding and removing. Objects in this scene are GLMoleculeObject's which
+ * are either .._atom (clickable) or .._bond (non-clickable). Also,
+ * GLMoleculeObject implements all transformation routines because atom and
+ * bond just differ in being a sphere or a cylinder.
+ *
+ *
+ * \date 2011-10-31
+ *
+ */
Index: src/documentation/userinterfaces/textmenu.dox
===================================================================
--- src/documentation/userinterfaces/textmenu.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
+++ src/documentation/userinterfaces/textmenu.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -0,0 +1,32 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file textmenu.dox
+ *
+ * Created on: Oct 31, 2011
+ *    Author: heber
+ */
+
+/**
+ * \page textmenu Text Menu Interface
+ *
+ *  The textmenu mimicks the graphical interface in having the very same menu
+ *  with actions at the same positions. Only visual output can only be obtained
+ *  by saving the world at intervals and inspecting the outcome. This is a sort
+ *  of lowman's way to a graphical interface but can be done via a remote
+ *  machine if its filesystem is mountable.
+ *
+ *  \note The textmenu interface is the least maintained part of the user
+ *  interfaces, so be cautious in using it. However, it also has the smallest
+ *  impact in terms of code lines. In effect it may work just as well as the
+ *  others.
+ *
+ *
+ *  \date 2011-10-31
+ *
+ */
Index: src/documentation/userinterfaces/userinterfaces.dox
===================================================================
--- src/documentation/userinterfaces/userinterfaces.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
+++ src/documentation/userinterfaces/userinterfaces.dox	(revision 750cff3758142eb977ca963eb8ede4200620a15e)
@@ -0,0 +1,43 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file userinterfaces.dox
+ *
+ * Created on: Oct 31, 2011
+ *    Author: heber
+ */
+
+/**
+ * \page userinterfaces User Interfaces
+ *
+ *  MoleCuilder has three interfaces at your disposal:
+ *  -# \ref textmenu  A simple interactive console-based menu, where awaits your choices and inputs in order to set atoms
+ *               as you like
+ *  -# \ref commandline Every command can also be chained up as a sequence of actions on the command line to be executed
+ *               with any user interaction.
+ *  -# \ref graphical A graphical user interface that also display the molecular structure being built and lots of other
+ *               informations to ease the construction of bigger geometries.
+ *
+ *  Note that all user interfaces are created via a common way that is
+ *  controlled via the Action's \b .def files. Therein menu position, name
+ *  and so forth are given. Hence, the same menus are created for both the
+ *  text and the graphical user interface.
+ *
+ *  \section userinterfaces-query Making queries to the user
+ *
+ *  The passing of values from the user to the code is done via a Query class
+ *  which each of the interfaces implements for each of the required types.
+ *
+ *  \section userinterfaces-menu Menu structure
+ *
+ *  \sa Menu for information on how the menu structure is done.
+ *
+ *
+ * \date 2011-10-31
+ *
+ */
