Index: doc/userguide/Makefile.am
===================================================================
--- doc/userguide/Makefile.am	(revision 6029a669c919139fdd1b0addd74222bb7f5b554d)
+++ doc/userguide/Makefile.am	(revision 6029a669c919139fdd1b0addd74222bb7f5b554d)
@@ -0,0 +1,4 @@
+EXTRA_DIST = \
+	pictures \
+	userguide.xml
+
Index: doc/userguide/catalog.xml.in
===================================================================
--- doc/userguide/catalog.xml.in	(revision 6029a669c919139fdd1b0addd74222bb7f5b554d)
+++ doc/userguide/catalog.xml.in	(revision 6029a669c919139fdd1b0addd74222bb7f5b554d)
@@ -0,0 +1,23 @@
+<?xml version="1.0"?>
+<!DOCTYPE catalog PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
+        "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
+
+<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
+        <nextCatalog catalog="@XML_CATALOG@"/>
+
+        @CAT_ENTRY_START@
+        <uri name="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"
+                uri="@DOCBOOK_ROOT@/fo/docbook.xsl"/>
+        @CAT_ENTRY_END@
+
+	<rewriteURI
+		uriStartString="pictures/"
+		rewritePrefix="@top_srcdir@/doc/userguide/pictures/" />
+
+        <uri name="pictures/molecuilder_logo.png" uri="@top_srcdir@/doc/userguide/pictures/molecuilder_logo.png"/>
+        <uri name="pictures/example_basic_view.png" uri="@top_srcdir@/doc/userguide/pictures/example_basic_view.png"/>
+        <uri name="pictures/dialog_box.png" uri="@top_srcdir@/doc/userguide/pictures/dialog_box.png"/>
+        <uri name="pictures/dialog_add-atombox_tooltip.png" uri="@top_srcdir@/doc/userguide/pictures/dialog_add-atom_tooltip.png"/>
+        <uri name="pictures/dialog_complex.png" uri="@top_srcdir@/doc/userguide/pictures/dialog_complex.png"/>
+        <uri name="pictures/dialog_exit.png" uri="@top_srcdir@/doc/userguide/pictures/dialog_exit.png"/>
+</catalog>
Index: doc/userguide/createguide.sh
===================================================================
--- doc/userguide/createguide.sh	(revision 6029a669c919139fdd1b0addd74222bb7f5b554d)
+++ doc/userguide/createguide.sh	(revision 6029a669c919139fdd1b0addd74222bb7f5b554d)
@@ -0,0 +1,4 @@
+#!/bin/bash
+
+xsltproc /usr/share/xml/docbook/stylesheet/docbook-xsl/fo/docbook.xsl userguide.xml >userguide.fo
+fop -fo userguide.fo -pdf userguide.pdf
Index: doc/userguide/css/html.css
===================================================================
--- doc/userguide/css/html.css	(revision 6029a669c919139fdd1b0addd74222bb7f5b554d)
+++ doc/userguide/css/html.css	(revision 6029a669c919139fdd1b0addd74222bb7f5b554d)
@@ -0,0 +1,325 @@
+body {
+    font-family: sans-serif;
+    font-size: 10pt;
+    color: black;
+    background-color: white;
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+    color: #394986;
+    font-height: bold;
+    margin-top: 1.33ex;
+    margin-bottom: 1.33ex;
+}
+
+h1 {
+    font-size: 1.8em;
+}
+
+h2 {
+    font-size: 1.6em;
+}
+
+h3 {
+    font-size: 1.4em;
+}
+
+h4 {
+    font-size: 1.2em;
+}
+
+h5,
+h6 {
+    font-size: 1em;
+}
+
+table {
+    border-spacing: 0;
+    font-size: 1em;
+}
+
+thead,
+tfoot {
+    background-color: #EEEEEE;
+}
+
+th,
+td {
+    padding: 0 0.5ex;
+}
+
+blockquote {
+    margin-top: 1.33ex 4ex;
+}
+
+p,
+th,
+td,
+li,
+dt,
+dd {
+    font-size: 1em;
+}
+
+p,
+pre,
+ol,
+dl,
+ul,
+table {
+    margin-top: 1.33ex;
+    margin-bottom: 1.33ex;
+}
+
+code,
+kbd,
+tt,
+pre {
+    font-family: monospace;
+    font-size: 90%;
+}
+
+pre {
+    white-space: pre;
+    background-color: #EEEEEE;
+    border: 1px solid #C0C0C0;
+    padding: 1ex;
+}
+
+li {
+    margin-top: 1.33ex;
+    margin-bottom: 1.33ex;
+}
+
+*[compact] > li {
+    margin-top: 0;
+    margin-bottom: 0;
+}
+
+dt {
+    margin-top: 1.33ex;
+    margin-bottom: 0;
+}
+
+dd {
+    margin-top: 0;
+    margin-bottom: 1.33ex;
+}
+
+*[compact] > dt {
+    margin-top: 0;
+}
+
+*[compact] > dd {
+    margin-bottom: 0;
+}
+
+div.toc,
+div.index,
+div.list-of-figures,
+div.list-of-tables,
+div.list-of-examples,
+div.list-of-equations,
+div.list-of-procedures {
+    margin-top: 1.33ex;
+    margin-bottom: 1.33ex;
+}
+
+div.toc dl,
+div.index dl,
+div.list-of-figures dl,
+div.list-of-tables dl,
+div.list-of-examples dl,
+div.list-of-equations dl,
+div.list-of-procedures dl {
+    margin-top: 0;
+    margin-bottom: 0;
+}
+
+div.toc dt,
+div.index dt,
+div.list-of-figures dt,
+div.list-of-tables dt,
+div.list-of-examples dt,
+div.list-of-equations dt,
+div.list-of-procedures dt {
+    margin-top: 0.25ex;
+    margin-bottom: 0.25ex;
+}
+
+div.toc dd,
+div.index dd,
+div.list-of-figures dd,
+div.list-of-tables dd,
+div.list-of-examples dd,
+div.list-of-equations dd,
+div.list-of-procedures dd {
+    margin-top: 0;
+    margin-bottom: 0;
+}
+
+div.toc span.part,
+div.toc span.chapter,
+div.toc span.appendix {
+    font-weight: bold;
+}
+
+div.attribution {
+    text-align: right;
+}
+
+div.sidebar {
+    background-color: #EEEEFF;
+    border: 1px solid #C0C0DD;
+    padding: 1ex;
+    margin-top: 1.33ex;
+    margin-bottom: 1.33ex;
+}
+
+div.sidebar > p.title {
+    margin-top: 0.33ex;
+}
+
+div.example > p.title,
+div.figure > p.title,
+div.table > p.title,
+div.procedure > p.title,
+div.equation > p.title {
+    color: #394986;
+    font-weight: bold;
+}
+
+div.orderedlist,
+div.calloutlist {
+    margin-top: 1.33ex;
+    margin-bottom: 1.33ex;
+}
+
+div.orderedlist > table,
+div.calloutlist > table {
+    margin: 0;
+}
+
+div.orderedlist > table td,
+div.calloutlist > table td {
+    vertical-align: baseline;
+}
+
+div.footnote {
+    font-size: 0.9em;
+}
+
+a:link:hover,
+a:visited:hover {
+    text-decoration: underline;
+}
+
+a:link {
+    text-decoration: none;
+    color: #004668;
+}
+
+a:visited {
+    text-decoration: none;
+    color: #135678;
+}
+
+span.term {
+    font-weight: bold;
+}
+
+abbr,
+acronym {
+    font-weight: bold;
+}
+
+span.keycap,
+span.keycode,
+span.keysym,
+span.mousebutton {
+    font-family: monospace;
+    font-size: 90%;
+    background-color: #EEEEEE;
+    padding: 0.2ex;
+}
+
+span.guimenu,
+span.guisubmenu,
+span.guimenuitem,
+span.guibutton,
+span.guiicon,
+span.interface,
+span.guilabel {
+    font-weight: bold;
+}
+
+a img {
+    border-style: none;
+}
+
+hr.footnote-hr {
+    width: 100px;
+    margin-left: 0;
+    text-align: left;
+}
+
+/* ------------------------------------------------------------------------
+ | Syntax highlighting
+ +------------------------------------------------------------------------- */
+
+.hl-keyword {
+    font-weight: bold;
+    color: #602060;
+}
+
+.hl-string {
+    color: #A00000;
+}
+
+.hl-number {
+    color: #B08000;
+}
+
+.hl-comment {
+    font-style: italic;
+    color: #808080;
+}
+
+.hl-doccomment {
+    color: #008080;
+}
+
+.hl-directive {
+    color: #00A000;
+}
+
+.hl-annotation {
+    font-weight: bold;
+    color: #808080;
+}
+
+/*
+ * XML
+ */
+
+.hl-tag {
+    font-weight: bold;
+    color: #602060;
+}
+
+.hl-attribute {
+    color: #0050A0;
+}
+
+.hl-value {
+    color: #A00000;
+}
+
+.hl-doctype {
+    color: #008080;
+}
Index: doc/userguide/userguide.xml
===================================================================
--- doc/userguide/userguide.xml	(revision 6029a669c919139fdd1b0addd74222bb7f5b554d)
+++ doc/userguide/userguide.xml	(revision 6029a669c919139fdd1b0addd74222bb7f5b554d)
@@ -0,0 +1,2043 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY molecuilder_logo SYSTEM "pictures/molecuilder_logo.png" NDATA PNG>
+<!ENTITY dialog_box SYSTEM "pictures/dialog_box.png" NDATA PNG>
+<!ENTITY dialog_add-atom_tooltip SYSTEM "pictures/dialog_add-atom_tooltip.png" NDATA PNG>
+<!ENTITY dialog_complex SYSTEM "pictures/dialog_complex.png" NDATA PNG>
+<!ENTITY dialog_exit SYSTEM "pictures/dialog_exit.png" NDATA PNG>
+<!ENTITY example_basic_view SYSTEM "pictures/example_basic_view.png" NDATA PNG>
+]>
+<book version="5.0" xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      xmlns:svg="http://www.w3.org/2000/svg"
+      xmlns:m="http://www.w3.org/1998/Math/MathML"
+      xmlns:html="http://www.w3.org/1999/xhtml"
+      xmlns:db="http://docbook.org/ns/docbook">
+  <info>
+    <title>MoleCuilder - a Molecule Builder</title>
+
+    <author>
+      <personname><firstname>Frederik</firstname><surname>Heber</surname></personname>
+
+      <affiliation>
+        <orgname>heber@ins.uni-bonn.de</orgname>
+      </affiliation>
+    </author>
+
+    <pubdate>07/03/14</pubdate>
+  </info>
+
+  <chapter>
+    <title>Introduction</title>
+
+    <figure>
+      <title>MoleCuilder logo depicting a tesselated buckyball and a benzene
+      molecule</title>
+
+      <mediaobject>
+        <imageobject>
+          <imagedata entityref="molecuilder_logo" scalefit="1" width="100%"/>
+        </imageobject>
+      </mediaobject>
+    </figure>
+
+    <section>
+      <title>What is MoleCuilder?</title>
+
+      <para>In Short,<command> MoleCuilder</command> is a concatenation of
+      molecule and builder.</para>
+
+      <para>In more words, molecular dynamics simulations are frequently
+      employed to simulate material behavior under stress, chemical reactions
+      such as of cementitious materials, or folding pathways and docking
+      procedures of bio proteins. Even if the computational load, due to the
+      large number of atoms, is very demanding, nonetheless they may serve as
+      a starting point, e.g. extracting parameters for a coarser model.
+      However, what is on the other hand the starting point of molecular
+      dynamics simulations? It is the coordinate and element of each atom
+      combined with potential functions that model the interactions.</para>
+
+      <para>MoleCuilder allows to fully construct such a starting point:
+      letting the user construct atomic and molecular geometries by a simple
+      point&amp;click approach, a CAD-pendant on the nanoscale. Creating
+      suitable empirical potentials by fitting parameters to ab-initio
+      calculations within hours. Specific emphasis is placed on a
+      simple-to-use interface, allowing for the quick-and-dirty building of
+      molecular systems, and on scriptability. Eventually, not a single, but
+      many, related molecular systems have to be created.</para>
+
+      <section>
+        <title>Installation requirements</title>
+
+        <para>For installations requirements and instructions we refer to the
+        internal documentation of MoleCuilder, created via doxgen from the
+        source code.</para>
+      </section>
+
+      <section>
+        <title>License</title>
+
+        <para>As long as no other license statement is given, MoleCuilder is
+        free for user under the GNU Public License (GPL) Version 2 (see
+        <uri>www.gnu.de/documents/gpl-2.0.de.html</uri>).</para>
+      </section>
+
+      <section>
+        <title>Disclaimer</title>
+
+        <para>We quote section 11 from the GPLv2 license:</para>
+
+        <remark>Because the program is licensed free of charge, there is not
+        warranty for the program, to the extent permitted by applicable law.
+        Except when otherwise stated in writing in the copyright holders
+        and/or other parties provide the program "as is" without warranty of
+        any kind, either expressed or implied. Including, but not limited to,
+        the implied warranties of merchantability and fitness for a particular
+        purpose. The entire risk as to the quality and performance of the
+        program is with you. Should the program prove defective, you assume
+        the cost of all necessary servicing, repair, or correction.</remark>
+      </section>
+
+      <section>
+        <title>Feedback</title>
+
+        <para>If you encounter any bugs, errors, or would like to submit
+        feature request, please use the email address provided at the very
+        beginning of this user guide. The author is especially thankful for
+        any description of all related events prior to occurrence of the
+        error, saved "session scripts" (see below) and auxiliary files. Please
+        mind sensible space restrictions of email attachments.</para>
+      </section>
+
+      <section>
+        <title>Notation</title>
+
+        <para>We briefly explain a few specific wordings associated with the
+        program:</para>
+
+        <itemizedlist>
+          <listitem>
+            <para><emphasis>Action</emphasis> is a command that allows for
+            undoing and redoing, i.e. a single atomic procedure for
+            manipulating the molecular system.</para>
+          </listitem>
+
+          <listitem>
+            <para>Selection refers to a subsets from the set of instances of a
+            particular type, e.g. atoms.</para>
+          </listitem>
+
+          <listitem>
+            <para>Shape means a specific region of the domain that can be
+            described in the way of constructive geometry, i.e. as the
+            intersection, negation, and combination of primitives such as
+            spheres or cylinders.</para>
+          </listitem>
+        </itemizedlist>
+      </section>
+
+      <section>
+        <title>Completeness</title>
+
+        <para>This documentation takes quite some effort to write. Hence, the
+        described features and especially the actions herein are settled with
+        respect to their functionality, while newer features or actions are
+        probably missing. This should be a clear sign to you that these are
+        probably not safe to use yet. If you nonetheless require them and thus
+        should acquire some familiarity with the code itself. This suggests
+        changing to the developer documentation which is maintained along with
+        the source code with <productname>doxygen</productname>.</para>
+      </section>
+    </section>
+  </chapter>
+
+  <chapter>
+    <title>Features</title>
+
+    <para>Basically, <command>MoleCuilder</command> parses geometries from
+    files, manipulates them and stores them again in files. The manipulation
+    can be done either via a command-line interface or via the graphical user
+    interface.</para>
+
+    <section>
+      <title>Concepts</title>
+
+      <para>In general, we divide the molecular systems into three different
+      components or scales.</para>
+
+      <orderedlist>
+        <listitem>
+          <para>Atoms</para>
+
+          <para>Atoms are the undividable objects of the molecular systems.
+          They have an element <quote>Z</quote> and three coordinates
+          <quote>(x,y,z)</quote>.</para>
+        </listitem>
+
+        <listitem>
+          <para>Molecules</para>
+
+          <para>Molecules are bound conglomeration of atoms. They contain a
+          number of atoms and a specific center in the domain such that its
+          atoms are placed relative to this center. Also, they may have a
+          bounding box, i.e. a subdomain that contains all of the atoms in the
+          molecule.</para>
+
+          <para>Note that the molecular structure of the system, i.e. the
+          bonding graph, is determined by MoleCuilder and used to dissect the
+          system into distinct molecules automatically.</para>
+        </listitem>
+
+        <listitem>
+          <para>Clusters</para>
+
+          <para>Clusters are unbound conglomeration of atoms. Clusters serves
+          as groups of atoms for specific operations that would be to
+          restricted if they worked on just molecules.</para>
+        </listitem>
+
+        <listitem>
+          <para>Domain</para>
+
+          <para>The domain refers to the simulation domain. It is
+          parallelepiped in <inlineequation>
+              <m:math display="inline">
+                <m:mi>\mathbb{R}^3</m:mi>
+              </m:math>
+            </inlineequation>where either periodic, wrapped, or open boundary
+          conditions apply. The domain contains all atoms, i.e. the box
+          containing all atoms.</para>
+        </listitem>
+      </orderedlist>
+    </section>
+
+    <section>
+      <title>Interfaces</title>
+
+      <para>MoleCuilder has four different interfaces: Command-line, text
+      menu, graphical user interface, and python interface.</para>
+
+      <orderedlist>
+        <listitem>
+          <para>Command-Line</para>
+
+          <para>The command-line interface allows to use MoleCuilder
+          non-interactively via a terminal session. The program is executed by
+          expanding the shell command with a number of commands including all
+          required options that are executed one after the other. After
+          execution of the last command, the program quits. The command-line
+          interface usually works on a specific file that is given as input,
+          manipulated, analysed, ... via the sequence of commands and
+          eventually all changes are stored in the this file. Hence, the input
+          file acts as the state of the starting configuration that is
+          modified via MoleCuilder.</para>
+        </listitem>
+
+        <listitem>
+          <para>Text menu</para>
+
+          <para>The text-menu is similar to the command-line interface with
+          the exception that it allows for interactive sessions. Commands are
+          chosen from a text menu and executed directly after selection by the
+          user.</para>
+        </listitem>
+
+        <listitem>
+          <para>Graphical interface</para>
+
+          <para>The graphical interface is based on Qt. It features a full
+          graphical representation of the simulation domain with atoms and
+          their bonds. It allows manipulation in point&amp;click fashion.
+          Commands are selected from pull-down menus and dialogs are used to
+          query the user for all required parameters to such a command.</para>
+        </listitem>
+
+        <listitem>
+          <para>Python interface</para>
+
+          <para>The last interface is accessible only within the python
+          programming language. MoleCuilder can be loaded as a module and its
+          commands can be executed with either the python interpreter
+          interactively or via python scripts non-interactively. Note that
+          this allows auxiliary calculations to be performed in pythons whose
+          results may be used as parameters in subsequent commands.</para>
+        </listitem>
+      </orderedlist>
+    </section>
+
+    <section>
+      <title>Known File formats</title>
+
+      <para>We briefly the file formats MoleCuilder can parse and
+      store.</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>XYZ, <filename>.xyz</filename> (simplest of all formats,
+          line-wise element and three coordinates with two line header, number
+          of lines and a comment line)</para>
+        </listitem>
+
+        <listitem>
+          <para><productname>MPQC</productname>, <filename>.in</filename>
+          (<link xlink:href="???">http://www.mpqc.org/</link>)</para>
+        </listitem>
+
+        <listitem>
+          <para>PDB, <filename>.pdb</filename> (<link
+          xlink:href="???">http://www.pdb.org/</link>)</para>
+        </listitem>
+
+        <listitem>
+          <para><productname>ESPACK</productname>, <filename>.conf</filename>
+          (electronic structure package by Institute for Numerical Simulation,
+          University of Bonn, code not in circulation)</para>
+        </listitem>
+
+        <listitem>
+          <para><productname>PSI4</productname>, <filename>.psi</filename>
+          (<link xlink:href="???">http://www.psicode.org/</link>)</para>
+        </listitem>
+
+        <listitem>
+          <para><productname>TREMOLO</productname>, <filename>.data</filename>
+          (<link xlink:href="???">http://www.tremolo-x.org/</link>)</para>
+        </listitem>
+
+        <listitem>
+          <para>XML, <filename>.xml</filename> (XML as read by scafacos
+          project, <link
+          xlink:href="???">http://www.scafacos.org</link>/)</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>These are identified via their suffixes and can be converted from
+      one into another (with loss of all data not in the intersection of
+      stored properties of the two involved file formats).</para>
+    </section>
+  </chapter>
+
+  <chapter>
+    <title>Interfaces</title>
+
+    <para>In this chapter, we explain the intention and use of the four
+    interfaces.</para>
+
+    <para>We give the most extensive explanation of the command-line
+    interface, all subsequent interfaces are explained in highlighting their
+    differences with respect to the command-line interface. This is because
+    the command-line lends itself very well to representation in this textual
+    user guide. Although some images of the graphical interface are given
+    below, they would blow the size of the guide out of proportion.</para>
+
+    <para>In any case, you should make yourself familiar with at least one of
+    the interactive (text menu, GUI) and one of the non-interactive
+    (command-line, python) interfaces to use MoleCuilder to is full potential:
+    The interactive interface gives you the immediate feedback in constructing
+    "synthesis" (build) chains (of commands) for constructing your specific
+    molecular system in the computer. The non-interactive interface lends
+    itself to quick creation of related systems that differ only by specific
+    parameters you have modified in the script (command-line can be used in
+    shell scripts, python itself is a scripted language). Also, the
+    non-interactive interfaces are used for storing sessions which helps you
+    in documentation your experiments and lateron understanding of what has
+    been done.</para>
+
+    <section>
+      <title>Command-line interface</title>
+
+      <para>The command-line interface reads options and commands from the
+      command line and executes them sequentially. This may be for example:
+      Open an empty file, add 2 hydrogen atoms and add 1 oxygen atom, choose a
+      simulation box, fill the box with this given "filler" molecule, save the
+      file. This enables the use of MoleCuilder in simple script-files to
+      create a whole range of geometries that only differ in a few parameters
+      automatically.</para>
+
+      <para>Traditionally, <command>MoleCuilder</command> operates on a single
+      configuration file - the state - which may also store additional
+      information depending on the chosen file format such as parameters for
+      ab-initio computations. An example for the above procedure is given
+      below:</para>
+
+      <programlisting>
+	./molecuilder \
+		-i sample.xyz \
+		--add-atom H \
+		--domain-position "0.,0.,0." \
+		...
+	</programlisting>
+
+      <para>The first argument is the executable itself. Second, there is a
+      slew of arguments -- one per line split with a backslash telling the 
+      shell that the line still continues -- consisting of the input action and 
+      an arbitrarily named file <filename>sample.xyz</filename>, which may be 
+      empty and whose file format is chosen by the given extension. The third 
+      is the add-atom action following by an option that gives the position in 
+      the domain where to add the "H"ydrogen atom. An action is always 
+      introduced via a double hyphen and its full name (containing just 
+      non-capital letters and hyphens) or a single hyphen and a single letter 
+      for its shortform, e.g. -a for adding an atom to the system. It is 
+      followed by a fixed number of options. Most of these have default values 
+      and in this do not have to be specified. If not enough options are given 
+      or invalid values have been entered, an error message is printed stating 
+      the name of the first missing or invalid option value.</para>
+
+      <note>
+        <para>Note that not all action have shortforms and it is best practice
+        to have the full action name instead of its shortform to make the
+        command-line understable to you in years to come.</para>
+      </note>
+
+      <section>
+        <title>Preliminaries</title>
+
+        <para>Some preliminary remarks are in order which we have gathered
+        here on how these actions work in general.</para>
+
+        <para>Below we first delve into some details about secondary structure
+        such as selections, shapes, and randomization required to specify
+        subsets of atoms and molecules you wish to manipulate. Then, we have
+        ordered the subsequent details on the manipulation depending on the
+        scale they act upon - single atoms, multiple atoms organised as
+        molecules, and all atoms organised by their containing domain.</para>
+
+        <para>In the following we will always give a command to illustrate the
+        procedure but just the necessary parts, i.e. "..." implies to prepend
+        it with the executable and input command for a specific configuration
+        file, for storing the manipulated state of the molecular system. Note
+        that</para>
+
+        <programlisting>./molecuilder --help</programlisting>
+
+        <para>will always give you a list of all available actions and also a
+        brief explanation on how to properly enter values of a specific type,
+        e.g. an element, a vector, or a list of numbers. Details to a specific
+        action can be requested when its full name is known, e.g. for
+        "add-atom",</para>
+
+        <programlisting>./molecuilder --help --actionname add-atom</programlisting>
+
+        <para>which fills you in on each option to the action: its full name,
+        its expected type, and a possibly present default value, and a brief
+        description of the option.</para>
+
+        <para>An Action can be undone and redone, e.g. undo adding an atom as
+        follows,</para>
+
+        <programlisting>... --add-atom H --domain-position "0,0,0" --undo</programlisting>
+
+        <para>and redo as follows</para>
+
+        <programlisting>... --add-atom H --domain-position "0,0,0" --undo --redo</programlisting>
+
+        <para>With the non-interactive interfaces this may seem rather
+        superfluous but it comes in very handy in the interactive ones. Also
+        this tells you that actions are placed in a queue, i.e. a history,
+        that undo and redo manipulate.</para>
+      </section>
+
+      <section>
+        <title>File parsers</title>
+
+        <para>We have already given a list of all known file formats, see
+        <link linkend="???">File formats</link>. Next, we explain how these
+        file formats are picked and manipulated.</para>
+
+        <section>
+          <title>Parsing files</title>
+
+          <para>We already discussed that the command-line interface works
+          state-based and hence you should supply it with a file to work
+          on.</para>
+
+          <programlisting>... --input water.data</programlisting>
+
+          <para>This will load all information, especially atoms with their
+          element and position, from the file <filename>water.data</filename>
+          into the state. All changes will eventually be stored to this file,
+          or to files with the prefix <filename>water</filename> and suffixes
+          of desired file formats, e.g. <filename>water.in</filename> if you
+          specified <productname>MPQC</productname>.</para>
+
+          <programlisting>... --load morewater.xyz</programlisting>
+
+          <para>This will load another file <filename>water.xyz</filename>,
+          however changes will still be written to files prefixed with
+          <filename>water</filename>. Note that now already two state files
+          will stored, <filename>water.data</filename> and
+          <filename>water.xyz</filename> as these two different file formats
+          have been used.</para>
+        </section>
+
+        <section>
+          <title>Adding output file formats</title>
+
+          <para>We already know that loading a file also picks a file format
+          by its suffix. We may add further file formats to which the state of
+          the molecular system on program exit.</para>
+
+          <programlisting>... --set-output mpqc tremolo</programlisting>
+
+          <para>This will store the final state of the molecular systems as
+          <productname>MPQC</productname> and as
+          <productname>TREMOLO</productname> configuration file.</para>
+        </section>
+
+        <section>
+          <title>Setting parser specific parameters</title>
+
+          <para>You can also tweak the parameters stored in this file easily.
+          For example, <productname>MPQC</productname> stores various
+          parameters modifying the specific ab-initio calculation performed.
+          For <productname>MPQC</productname> and 
+          <productname>Psi4</productname> this can be modified as 
+          follows.</para>
+
+          <programlisting>
+		... --set-parser-parameters mpqc \
+		    --parser-parameters "theory=CLHF;basis=6-31*G;"
+          </programlisting>
+
+          <para>This sets the ab-initio theory to closed-shell Hartree-Fock
+          and the basis set to 6-31*G. Please check the
+          <productname>MPQC</productname> manual on specific
+          parameters.</para>
+        </section>
+
+        <section>
+          <title>Tremolo specific options and potential files</title>
+
+          <para><productname>TREMOLO</productname>'s configuration files start
+          with a specific line telling the amount of information stored in the
+          file. This file can be modified, e.g. to enforce storing of
+          velocities and forces as well as the atoms positions and
+          element.</para>
+
+          <programlisting>
+		... --set-tremolo-atomdata "ATOM id element u=3 v=3 F=3" \
+		    --reset 1
+	  </programlisting>
+
+          <para>This will not append but reset the old line and fill it with
+          the given string.</para>
+
+          <para>One specific action is required when loading certain
+          <productname>TREMOLO</productname> configuration files. These
+          contain element notations that refer to parameterized names used in
+          empirical potentials and molecular dynamics simulations and not the
+          usual chemical symbols, such as H or O. We may load an auxiliary
+          file that gives the required conversion from OH1 to H, which is the
+          so-called potential file.</para>
+
+          <programlisting>... --parse-tremolo-potentials water.potentials</programlisting>
+
+          <para>This parses the lookup table from the file
+          <filename>water.potentials</filename> and it can be used in
+          following load actions.</para>
+        </section>
+      </section>
+
+      <section>
+        <title>Selections and unselections</title>
+
+        <para>In order to tell MoleCuilder on what subset of atoms a specific
+        Action is to be performed, there are <emphasis>selection
+        actions</emphasis>. Note that a selection per se does not change
+        anything in the state of the molecular system in any way.</para>
+
+        <para>Selections either work on atoms, on molecules, or on shapes
+        (this we explain lateron). A given selection is maintained from the
+        execution of the selection action to the end of program or until
+        modified by another selection applied on the same type (atom,
+        molecule, shape).</para>
+
+        <para>We only give a brief list on the kind of selections per type,
+        each action is executed either as follows, exemplified by selecting
+        all atoms.</para>
+
+        <programlisting>.... --select-all-atoms</programlisting>
+
+        <para>or, exemplified by unselecting the last molecule,</para>
+
+        <programlisting>... --unselect-molecule-by-order -1</programlisting>
+
+        <itemizedlist>
+          <listitem>
+            <para>Atoms</para>
+
+            <itemizedlist>
+              <listitem>
+                <para>By Element (all hydrogen atoms, all sulphur atoms,
+                ...)</para>
+              </listitem>
+
+              <listitem>
+                <para>By Id (atom with id 76)</para>
+              </listitem>
+
+              <listitem>
+                <para>By Order (the first (1), the second, ... the last, the
+                last but one)</para>
+              </listitem>
+
+              <listitem>
+                <para>By Shape (specific region of the domain)</para>
+              </listitem>
+
+              <listitem>
+                <para>By Molecule (all atoms belonging to currently selected
+                molecules)</para>
+              </listitem>
+            </itemizedlist>
+          </listitem>
+
+          <listitem>
+            <para>Molecules</para>
+
+            <itemizedlist>
+              <listitem>
+                <para>By Id (molecule with id 4)</para>
+              </listitem>
+
+              <listitem>
+                <para>By Order (first molecule, second molecule, ...)</para>
+              </listitem>
+
+              <listitem>
+                <para>By Name (molecule named "water4"</para>
+              </listitem>
+
+              <listitem>
+                <para>By Atom (all molecules for which at least one atom is
+                currently selected)</para>
+              </listitem>
+            </itemizedlist>
+          </listitem>
+        </itemizedlist>
+
+        <itemizedlist>
+          <listitem>
+            <para>Shapes</para>
+
+            <itemizedlist>
+              <listitem>
+                <para>By Name (shape name "sphere1")</para>
+              </listitem>
+            </itemizedlist>
+          </listitem>
+
+          <listitem>
+            <para>All</para>
+
+            <itemizedlist>
+              <listitem>
+                <para>All (selects or unselects all instances of the
+                type)</para>
+              </listitem>
+
+              <listitem>
+                <para>Clear (clears the current selection)</para>
+              </listitem>
+            </itemizedlist>
+          </listitem>
+        </itemizedlist>
+
+        <para>Furthermore, a selection can be imverted, e.g. inverting the
+        current selection of atoms.</para>
+
+        <programlisting>... --invert-atoms</programlisting>
+
+        <remark>Note that an unselected instance (e.g. an atom) remains
+        unselected upon further unselection and vice versa with
+        selection.</remark>
+
+        <para>These above selections work then in conjunction with other
+        actions and make them very powerful, e.g. you can remove all atoms
+        inside a sphere by a selecting the spherical shape and subsequently
+        selecting all atoms inside the shape and then removing them.</para>
+      </section>
+
+      <section>
+        <title>Shapes</title>
+
+        <para>Shapes are specific regions of the domain. There are just a few
+        so-called <emphasis>primitive</emphasis> shapes such as cuboid,
+        sphere, cylinder, the whole domain, none of it. However, these can be
+        combined via boolean operations such as and, or, and not. This
+        approach is called <emphasis>constructive geometry</emphasis>. E.g. by
+        combining a sphere with the negated (not) of a smaller sphere, we
+        obtain a spherical surface of specific thickness.</para>
+
+        <section>
+          <title>Creating shapes</title>
+
+          <para>Primitive shapes can be created as follows,</para>
+
+          <programlisting>
+		... --create-shape \
+		    --shape-type sphere \
+		    --shape-name "sphere1" \
+		    --stretch "2,2,2" \
+		    --translation "5,5,5"
+	  </programlisting>
+
+          <para>This will create a sphere of radius 2 (initial radius is 1)
+          with name "sphere1" that is centered at (5,5,5). Other primitives at
+          cuboid and cylinder, where a rotation can be specified as
+          follows.</para>
+
+          <programlisting>
+		... --create-shape \
+		    --shape-type cuboid \
+		    --shape-name "box" \
+		    --stretch "1,2,2" \
+		    --translation "5,5,5" \
+		    --angle-x "90"
+	  </programlisting>
+        </section>
+
+        <section>
+          <title>Removing shapes</title>
+
+          <para>Removing a shape is as simple as removing an atom.</para>
+
+          <programlisting>... --remove-shape </programlisting>
+
+          <para>This removes the currently selected shapes.</para>
+        </section>
+
+        <section>
+          <title>Manipulating shapes</title>
+
+          <para>Shapes can be stretched, scaled, rotated, and translated to
+          modify primitives or combined primitive shapes. As you have seen
+          this manipulation could have occurred already at creation but also
+          later on. We just the list examples of the various manipulations
+          below, each works on the currently selected shapes.</para>
+
+          <programlisting>
+		... --stretch-shapes "1,1,2" \
+		    --stretch-center "5,5,5"
+	  </programlisting>
+
+          <para>This stretches the shapes relative to the center at (5,5,5)
+          (default is origin) by a factor of 2 in the z direction.</para>
+
+          <programlisting>
+		... --rotate-shape \
+		    --center "10,2,2" \
+		    --angle-x 90 \
+		    --angle-y 0 \
+		    --angle-z 0
+	  </programlisting>
+
+          <para>This way all selected shapes are rotated by 90 degrees around
+          the x axis with respect to the center at (10,2,2).</para>
+
+          <programlisting>... --translate-shapes "5,0,0" </programlisting>
+
+          <para>This translates all selected shapes by 5 along the x
+          axis.</para>
+        </section>
+      </section>
+
+      <section>
+        <title>Randomization</title>
+
+        <para>Some operations require randomness as input, e.g. when filling a
+        domain with molecules these may be randomly translated and rotated.
+        Random values are obtained by a random number generator that consists
+        of two parts: engine and distribution. The engine yields a uniform set
+        of random numbers in a specific interval, the distribution modifies
+        them, e.g. to become gaussian.</para>
+
+        <para>There are several Actions to modify the specific engine and
+        distribution and their parameters. One example usage is that with the
+        aforementioned filling of the domain molecules are rotated randomly.
+        If you specify a random number generator that randomly just spills out
+        values 0,1,2,3, then the randomness is just the orientation of the
+        molecule with respect to a specific axis: x,y,z. (rotation is at most
+        360 degrees and 0,1,2,3 act as divisor, hence rotation angle is always
+        a multiple of 90 degrees).</para>
+
+        <programlisting>
+		... --set-random-number-distribution "uniform_int" \
+		    --random-number-distribution-parameters "p=1"
+	</programlisting>
+
+        <para>This changes the distribution to "uniform_int", i.e. integer
+        numbers distributed uniformly.</para>
+
+        <programlisting>
+		... --set-random-number-engine "mt19937" \
+		    --random-numner-engine-parameters "seed=10"
+	</programlisting>
+
+        <para>Specifying the seed allows you to obtain the same sequence of
+        random numbers for testing purposes.</para>
+      </section>
+
+      <section>
+        <title>Manipulate atoms</title>
+
+        <para>Here, we explain in detail how to add, remove atoms, change its
+        element type, scale the bond in between or measure the bond length or
+        angle.</para>
+
+        <section>
+          <title>Adding atoms</title>
+
+          <para>Adding an atom to the domain requires the element of the atom
+          and its coordinates as follows,</para>
+
+          <programlisting>
+		... --add-atom O \
+		    --domain-position "2.,3.,2.35"
+	  </programlisting>
+
+          <para>where the element is given via its chemical symbol and the
+          vector gives the position within the domain</para>
+        </section>
+
+        <section>
+          <title>Removing atoms</title>
+
+          <para>Removing atom(s) does not need any option and operates on the
+          currently selected ones.</para>
+
+          <programlisting>... --remove-atom</programlisting>
+        </section>
+
+        <section>
+          <title>Translating atoms</title>
+
+          <para>In order to translate the current selected subset of atoms you
+          specify a translation vector.</para>
+
+          <programlisting>
+		... --translate-atoms "-1,0,0" \
+		    --periodic 0
+	  </programlisting>
+
+          <para>This translate all atoms by "-1" along the x axis and does not
+          mind the boundary conditions, i.e. might shift atoms outside of the
+          domain.</para>
+        </section>
+
+        <section>
+          <title>Changing an atoms element</title>
+
+          <para>You can easily turn lead or silver into gold, by selecting the
+          silver atom and calling the change element action.</para>
+
+          <programlisting>... --change-element Au</programlisting>
+        </section>
+      </section>
+
+      <section>
+        <title>Bond-related manipulation</title>
+
+        <para>Atoms can also be manipulated with respect to the bonds.
+        <remark>Note that with bonds we always mean covalent bonds.</remark>
+        First, we explain how to modify the bond structure itself, then we go
+        in the details of using the bond information to change bond distance
+        and angles.</para>
+
+        <section>
+          <title>Creating a bond graph</title>
+
+          <para>In case you have loaded a configuration file with no bond
+          information, e.g. XYZ, it is necessary to create the bond graph.
+          This is done by a heuristic distance criterion.</para>
+
+          <programlisting>... --create-adjacency</programlisting>
+
+          <para>This uses by default a criterion based on van-der-Waals radii,
+          i.e. if we look at two atoms indexed by "a" and "b"</para>
+
+          <equation>
+            <title>V(a) + V(b) - \tau &lt; R_{ab} &lt; V(a) + V(b) +
+            \tau</title>
+
+            <m:math display="block">
+              <m:mi>where V(.) is the lookup table for the radii for a given
+              element and \tau is a threshold value, set to 0.4.</m:mi>
+            </m:math>
+          </equation>
+
+          <para>As a second option, you may load a file containing bond table
+          information.</para>
+
+          <programlisting>... --bond-table table.dat</programlisting>
+
+          <para>which would parse a file <filename>table.dat</filename> for a
+          table giving typical bond distances between elements a and b. These
+          are used in the above criterion as <inlineequation>
+              <m:math display="inline">
+                <m:mi>V(a,b)</m:mi>
+              </m:math>
+            </inlineequation> in place of <inlineequation>
+              <m:math display="inline">
+                <m:mi>V(a)+V(b)</m:mi>
+              </m:math>
+            </inlineequation>.</para>
+        </section>
+
+        <section>
+          <title>Destroying the bond graph</title>
+
+          <para>The bond graph can be removed completely (and all bonds along
+          with it).</para>
+
+          <programlisting>... --destroy-adjacency</programlisting>
+        </section>
+
+        <section>
+          <title>Analysing a bond graph</title>
+
+          <para>You can perform a depth-first search analysis that reveals
+          cycles and other graph-related information.</para>
+
+          <programlisting>... --depth-first-search</programlisting>
+        </section>
+
+        <section>
+          <title>Dissecting the molecular system into molecules</title>
+
+          <para>The bond graph information can be used to recognize the
+          molecule within the system. Imagine you have just loaded a PDB file
+          containing bond information. However, initially all atoms are dumped
+          into the same molecule. Before you can start manipulating, you need
+          to dissect the system into individual molecules. Note that this is
+          just structural information and does not change the state of the
+          system.</para>
+
+          <programlisting>... --subgraph-dissection</programlisting>
+
+          <para>This analyses the bond graph and splits the single molecule up
+          into individual (new) ones that each contain a single connected
+          subgraph, hence the naming.</para>
+        </section>
+
+        <section>
+          <title>Adding a bond manually</title>
+
+          <para>When the automatically created adjacency or bond graph
+          contains faulty bonds or lacks some, you can add them manually.
+          First, you must have selected two atoms.</para>
+
+          <programlisting>... --add-bond</programlisting>
+        </section>
+
+        <section>
+          <title>Removing a bond manually</title>
+
+          <para>In much the same way as adding a bond, you can also remove a
+          bond.</para>
+
+          <programlisting>... --remove-bond</programlisting>
+        </section>
+
+        <section>
+          <title>Stretching a bond</title>
+
+          <para>Stretching a bond actually refers to translation of the
+          associated pair of atoms. However, this action will keep the rest of
+          the molecule to which both atoms belong to invariant as well.</para>
+
+          <programlisting>... --stretch-bond 1.2</programlisting>
+
+          <para>This scales the original bond distance to the new bond
+          distance 1.2, shifting the right hand side and the left hand side of
+          the molecule accordingly.</para>
+
+          <warning>
+            <para>this fails with aromatic rings (but you can always
+            undo).</para>
+          </warning>
+        </section>
+
+        <section>
+          <title>Changing a bond angle</title>
+
+          <para>In the same way as stretching a bond, you can change the angle
+          in between two bonds. This works if exactly three atoms are selected
+          and two pairs are bonded.</para>
+
+          <programlisting>... --change-bond-angle 90</programlisting>
+
+          <para>This will change the angle from its value to 90 degree by
+          translating the two outer atoms of this triangle (the atom connected
+          to both others is the axis of the rotation).</para>
+        </section>
+      </section>
+
+      <section>
+        <title>Manipulate molecules</title>
+
+        <para>Molecules are agglomerations of atoms that are bonded. Hence,
+        the actions working on molecules differ from those working on atoms.
+        Joining two molecules can only be accomplished by adding a bond in
+        between, and in the reverse fashion splitting a molecule by removing
+        all bonds in between. Actions below mostly deal with copying
+        molecules. Removing of molecules is done via selecting the molecule's
+        atoms and removing them, which removes the atoms as well.</para>
+
+        <note>
+          <para>Initially when you load a file via the input action all atoms
+          are placed in a single molecule despite any present bond
+          information, see <link linkend="???">Dissecting the molecular system
+          into molecules</link></para>
+        </note>
+
+        <section>
+          <title>Copy molecules</title>
+
+          <para>A basic operation is to duplicate a molecule. This works on a
+          single, currently selected molecule. Afterwards, we elaborate on a
+          more complex manner of copying, filling a specific shape with
+          molecules.</para>
+
+          <programlisting>
+		... --copy-molecule \
+		    --position "10,10,10"
+	  </programlisting>
+
+          <para>This action copies the selected molecule and inserts it at the
+          position (10,10,10) in the domain with respect to the molecule's
+          center. In effect, it copies all the atoms of the original molecule
+          and adds new bonds in between these copied atoms such that their
+          bond subgraphs are identical.</para>
+        </section>
+
+        <section>
+          <title>Fill a domain section with molecules</title>
+
+          <para>Filling a specific part of the domain with one type of
+          molecule, e.g. a water molecule, is the more advanced type of
+          copying and we need several ingredients.</para>
+
+          <para>First, we need to specify the part of the domain. This is done
+          via a shape. We have already learned how to create and select
+          shapes. The currently selected shape will serve as the fill-in
+          region.</para>
+
+          <para>Then, they are two types of filling, volume and surface. The
+          volume is filled with a regular grid of fill-in points, and in the
+          same manner is the surface filled with a regular grid of points.
+          Molecules will be copied and translated points when they
+          "fit".</para>
+
+          <para>The filler procedure checks each fill-in point whether there
+          is enough space for the molecule. To know this, we require a cluster
+          instead of a molecule. This is just a general agglomeration of atoms
+          combined with a bounding box that contains all of them and serves as
+          its minimal volume. I.e. we need this cluster. For this a number of
+          atoms have to be specified, the minimum bounding box is generated
+          automatically.</para>
+
+          <para>On top of that molecules can be selected whose volume is
+          additionally excluded from the filling region.</para>
+
+          <para>The call to fill the volume of the selected shape with the
+          selected atoms is then as follows,</para>
+
+          <programlisting>
+		... --fill-regular-grid \
+		    --mesh-size "5,5,5" \
+		    --mesh-offset ".5,.5,.5" \
+		    --DoRotate 1 --min-distance 1. \
+		    --random-atom-displacement 0.05 \
+		    --random-molecule-displacement 0.4 \
+		    --tesselation-radius 2.5
+	  </programlisting>
+
+          <para>This generates a grid of 5x5x5 fill-in points within the
+          sphere that are offset such as to lay centered within the sphere
+          (offset per axis in [0,1]). Additionally, each molecule is rotated
+          by random rotation matrix, each atom is translated randomly by at
+          most 0.05, each molecule's center at most by 0.4. The selected
+          molecules' volume is obtained by tesselating their surface and
+          excluding every fill-in point whose distance to this surface does
+          not exceed 1. We refer to our comments in <link linkend="???">1.4
+          Randomization </link>for details on changing the randomness.</para>
+        </section>
+
+        <section>
+          <title>Change a molecules name</title>
+
+          <para>You can change the name of a molecule which is important for
+          selection.</para>
+
+          <programlisting>... -change-molname "test</programlisting>
+
+          <para>This will change the name of the (only) selected molecule to
+          "test".</para>
+
+          <para>Connected with this is the default name an unknown molecule
+          gets.</para>
+
+          <programlisting>... --default-molname test</programlisting>
+
+          <para>This will change the default name of a molecule to
+          "test".</para>
+
+          <note>
+            <para>Note that a molecule loaded from file gets the filename
+            (without suffix) as its name.</para>
+          </note>
+        </section>
+
+        <section>
+          <title>Rotate around self</title>
+
+          <para>You can rotate a molecule around its own axis.</para>
+
+          <programlisting>
+		... --rotate-around-self "90" \
+		    --axis "0,0,1"
+	  </programlisting>
+
+          <para>This rotates the molecule around the z axis by 90 degrees as
+          if the origin were at its center of origin.</para>
+        </section>
+
+        <section>
+          <title>Rotate around origin</title>
+
+          <para>In the same manner the molecule can be rotated around an
+          external origin.</para>
+
+          <programlisting>
+		... --rotate-around-origin 90 \
+		    --position "0,0,1"\
+	  </programlisting>
+
+          <para>This rotates the molecule around an axis from the origin to
+          the position (0,0,1), i.e. around the z axis, by 90 degrees.</para>
+        </section>
+
+        <section>
+          <title>Rotate to principal axis system</title>
+
+          <para>The principal axis system is given by an ellipsoid that mostly
+          matches the molecules shape. The principal axis system can be just
+          simply determined by</para>
+
+          <programlisting>... --principal-axis-system</programlisting>
+
+          <para>To rotate the molecule around itself to align with this system
+          do as follows.</para>
+
+          <programlisting>... --rotate-to-principal-axis-system "0,0,1"</programlisting>
+
+          <para>This rotates the molecule in such a manner that the ellipsoids
+          largest axis is aligned with the z axis. <remark>Note that "0,0,-1"
+          would align anti-parallel.</remark></para>
+        </section>
+
+        <section>
+          <title>Perform verlet integration</title>
+
+          <para>Atoms not only have a position, but each instance also stores
+          velocity and a force vector. These can be used in a velocity verlet
+          integration step. Velocity verlet is a often employed time
+          integration algorithm in molecular dynamics simulations.</para>
+
+          <programlisting>
+		... --verlet-integration \
+		    --deltat 0.1 \
+		    --keep-fixed-CenterOfMass 0
+	  </programlisting>
+
+          <para>This will integrate with a timestep of <inlineequation>
+              <m:math display="inline">
+                <m:mi>\Delta_t = 0.1</m:mi>
+              </m:math>
+            </inlineequation>and correcting forces and velocities such that
+          the sum over all atoms is zero.</para>
+        </section>
+      </section>
+
+      <section>
+        <title>Manipulate domain</title>
+
+        <para>Here, we elaborate on how to duplicate all the atoms inside the
+        domain, how the scale the coordinate system, how to center the atoms
+        with respect to certain points, how to realign them by given
+        constraints, how to mirror and most importantly how to specify the
+        domain.</para>
+
+        <section>
+          <title>Changing the domain</title>
+
+          <para>The domain is specified by a symmetric 3x3 matrix. The
+          eigenvalues (diagonal entries in case of a diagonal matrix) give the
+          length of the edges, additional entries specify transformations of
+          the box such that it becomes a more general parallelepiped.</para>
+
+          <programlisting>... change-box "20,0,20,0,0,20"</programlisting>
+
+          <para>As the domain matrix is symmetric, six values suffice to fully
+          specify it. We have to give the six components of the lower diagonal
+          matrix. Here, we change the box to a cuboid of equal edge length of
+          20.</para>
+        </section>
+
+        <section>
+          <title>Bound atoms inside box</title>
+
+          <para>The following applies the current boundary conditions to the
+          atoms. In case of periodic or wrapped boundary conditions the atoms
+          will be periodically translated to be inside the domain
+          again.</para>
+
+          <programlisting>... --bound-in-box</programlisting>
+        </section>
+
+        <section>
+          <title>Center atoms inside the domain</title>
+
+          <para>This is a combination of changing the box and bounding the
+          atoms inside it.</para>
+
+          <programlisting>... --center-in-box "20,0,20,0,0,"</programlisting>
+        </section>
+
+        <section>
+          <title>Center the atoms at an edge</title>
+
+          <para>MoleCuilder can calculate the minimum box (parallel to the
+          cardinal axis) all atoms would fit in and translate all atoms in
+          such a way that the lower, left, front edge of this minimum is at
+          the origin (0,0,0).</para>
+
+          <programlisting>... --center-edge</programlisting>
+        </section>
+
+        <section>
+          <title>Extending the boundary by adding an empty boundary</title>
+
+          <para>In the same manner as above a minimum box is determined that
+          is subsequently expanded by a boundary of the given additional
+          thickness. This applies to either side.</para>
+
+          <programlisting>... --add-empty-boundary "5,5,5"</programlisting>
+
+          <para>This will enlarge the box in such a way that every atom is at
+          least by a distance of 5 away from the boundary of the domain (in
+          the infinity norm).</para>
+        </section>
+
+        <section>
+          <title>Scaling the box</title>
+
+          <para>You can enlarge the domain by simple scaling factors.</para>
+
+          <programlisting>... --scale-box "1,1,2.5"</programlisting>
+
+          <para>Here, the domain is stretched in the z direction by a factor
+          of 2.5.</para>
+        </section>
+
+        <section>
+          <title>Repeating the box</title>
+
+          <para>Under periodic boundary conditions often only the minimal
+          periodic cell is stored. If need be, multiple images can be easily
+          added to the current state of the system by repeating the box, i.e.
+          the box along with all contained atoms is copied and placed
+          adjacently.</para>
+
+          <programlisting>... --repeat-box "1,2,2"</programlisting>
+
+          <para>This will create a 2x2 grid of the current domain, replicating
+          it along the y and z direction along with all atoms. If the domain
+          contained before a single water molecule, we will now have four of
+          them.</para>
+        </section>
+      </section>
+
+      <section>
+        <title>Fragmentation</title>
+
+        <para>Fragmentation refers to a so-called linear-scaling method called
+        "Bond-Order diSSection in an ANOVA-like fashion" (BOSSANOVA),
+        developed by <personname>Frederik Heber</personname>. In this section
+        we briefly explain what the method does and how the associated actions
+        work.</para>
+
+        <para>The central idea behind the BOSSANOVA scheme is to fragment the
+        graph of the molecular system into connected subgraphs of a certain
+        number of vertices (atoms). To give an example, loading a ethane atom
+        with the chemical formula C2H6, fragmenting the molecule up to order 1
+        means creating two fragments, both methane-like from either carbon
+        atom including surrounding hydrogen atoms. Fragmenting up to order 2
+        would return both the methane fragments and additionally the full
+        ethane molecule as it resembles a fragment of order 2, namely
+        containing two (non-hydrogen) atoms.</para>
+
+        <para>The reason for doing this is that usual ab-initio calculations
+        of molecular systems via methods such as Density Functional Theory or
+        Hartree-Fock scale at least as <inlineequation>
+            <m:math display="inline">
+              <m:mi>{\cal O}(M^3}</m:mi>
+            </m:math>
+          </inlineequation>with the number of atoms <inlineequation>
+            <m:math display="inline">
+              <m:mi>M</m:mi>
+            </m:math>
+          </inlineequation>. Hence, calculating the ground state energy of a
+        number of fragment molecules scaling linearly with the number of atoms
+        yields a linear-scaling methods. In the doctoral thesis of Frederik
+        Heber, it is explained why this is a sensible ansatz mathematically
+        and shown that it delivers a very good accuracy if electrons (and
+        hence interactions) are in general localized.</para>
+
+        <para>Long-range interactions are artificially truncated, however,
+        with this fragment ansatz. It can be obtained in a perturbation manner
+        by sampling the resulting electronic and nuclei charge density on a
+        grid, summing over all fragments, and solving the associated Poisson
+        equation. Such a calculation is implemented via the solver
+        <productname>vmg</productname> by Julian Iseringhausen that is
+        contained in the <productname>ScaFaCoS</productname> package (<link
+        xlink:href="???">http://www.scafacos.org/</link>).</para>
+
+        <para>Note that we treat hydrogen special (but can be switched off) as
+        fragments are calculated as closed shell (total spin equals zero).
+        Also, we use hydrogen to saturate any dangling bonds that occur as
+        bonds are cut when fragmenting a molecule (this, too, can be switched
+        off).</para>
+
+        <section>
+          <title>Fragmenting a molecular system</title>
+
+          <para>For the current selection of atoms, all fragments consisting
+          of these (sub)set of atoms are created in the following
+          manner.</para>
+
+          <programlisting>
+		... --fragment-molecule "BondFragment" \
+		    --DoCyclesFull 1 \
+		    --distance 3. \
+		    --order 3 \
+		    --grid-level 5 \
+		    --output-types xyz mpqc
+	  </programlisting>
+
+          <para>We go through each of the options one after the other. During
+          fragmentation some files are created storing state information, i.e.
+          the vertex/atom indices per fragment and so on. These files all need
+          a common prefix, here "BondFragment". Then, we specify that cycles
+          should be treated fully. This compensates for electrons in aromatic
+          rings being delocalized over the ring. If cycles in the graph,
+          originating from aromatic rings, are always calculated fully, i.e.
+          the whole ring becomes a fragment, we partially overcome these
+          issues. This does however not work indefinitely and accuracy of the
+          approximation is limited (<inlineequation>
+              <m:math display="inline">
+                <m:mi>&gt;10^{-4}</m:mi>
+              </m:math>
+            </inlineequation>) in systems with many interconnected aromatic
+          rings, such as graphene. Next, we give a distance cutoff of 3 used
+          in bond graph creation. Then, we specify the maximum order, i.e. the
+          maximum number of (non-hydrogen) atoms per fragment, here 3. The
+          higher this number the more expensive the calculation becomes
+          (because substantially more fragments are created) but also the more
+          accurate. The grid level refers to the part where long-range Coulomb
+          interactions are calculated. This is done via solving the associated
+          Poisson equation with a multigrid solver. As input the solver
+          requires the density which is sampled on a cartesian grid whose
+          resolution these parameter defines (<inlineequation>
+              <m:math display="inline">
+                <m:mi>2^{\mathrm{level}}</m:mi>
+              </m:math>
+            </inlineequation>). And finally, we give the output file formats,
+          i.e. which file formats are used for writing each fragment
+          configuration (prefix is "BondFragment", remember?). Here, we use
+          XYZ (mainly for checking the configurations visually) and MPQC,
+          which is a very robust Hartree-Fock solver. We refer to the
+          discussion of the <link linkend="???">Parsers</link> above on how to
+          change the parameters of the ab-initio calculation.</para>
+
+          <para>After having written all fragment configuration files, you
+          need to calculate each fragment, grab the resulting energy (and
+          force vectors) and place them into a result file manually. This at
+          least is necessary if you have specified output-types above. If not,
+          the fragments are not written to file but stored internally. Read
+          on.</para>
+        </section>
+
+        <section>
+          <title>Calculating fragment energies automatically</title>
+
+          <para>Another way of doing this is enabled if you have
+          <productname>JobMarket</productname> package. JobMarket implements a
+          client/server ansatz, i.e. two (or more) independent programs are
+          running (even on another computer but connected via an IP network),
+          namely a server and at least one client. The server receives
+          fragment configurations from MoleCuilder and assigns these to a
+          client who is not busy. The client launches an executable that is
+          specified in the work package he is assigned and gathers after
+          calculation a number of values, samewise specified in the package.
+          The results are gathered together by the server and can be requested
+          from MoleCuilder once they are done. This essentially describe what
+          is happening during the execution of this action.</para>
+
+          <para>Stored fragment jobs can also be parsed again, i.e. reversing
+          the effect of having output-types specified in <link
+          linkend="???">Fragmenting a molecule</link>.</para>
+
+          <programlisting>
+		... --parse-fragment-jobs \
+		    --fragment-jobs "BondFragment00.in" "BondFragment01.in" \
+		    --fragment-path "./" \
+		    --grid-level 5
+	  </programlisting>
+
+          <para>Here, we have specified two files, namely
+          <filename>BondFragment00.in</filename> and
+          <filename>BondFragment01.in</filename>, to be parsed from the path
+          "./", i.e. the current directory. Also, we have specified to sample
+          the electronic charge density obtained from the calculated ground
+          state energy solution with a resolution of 5 (see fragment molecule
+          and also below).</para>
+
+          <para>This allows for automated and parallel calculation of all
+          fragment energies and forces directly within MoleCuilder. The
+          FragmentationAutomation action takes the fragment configurations
+          from an internal storage wherein they are placed if in
+          FragmentMolecule no output-types have been specified.</para>
+
+          <programlisting>
+		... --fragment-automation \
+		    --fragment-executable mpqc \
+		    --fragment-resultfile BondFragment_results.dat \
+		    --DoLongrange 1 \
+		    --DoValenceOnly 1 \
+		    --grid-level 5 \
+		    --interpolation-degree 3 \
+		    --near-field-cells 4 \
+		    --server-address 127.0.0.1 \
+		    --server-port 1025
+	  </programlisting>
+
+          <para>Again, we go through each of the action's options step by
+          step.</para>
+
+          <para>The executable is required if you do not have a patched
+          version of <productname>MPQC</productname> that may directly act as
+          a client to JobMarket's server. All calculated results are placed in
+          the result file. If none is given, they are instead again placed in
+          an internal storage for later access.</para>
+
+          <note>
+            <para>Long-calculations are only possible with a client that knows
+            how to handle VMG jobs. If you encounter failures, then it is most
+            likely that you do not have a suitable client.</para>
+          </note>
+
+          <para>In the next line, we have all options related to calculation
+          of long-range interactions. We only sample valence charges on the
+          grid, i.e. not core electrons and the nuclei charge is reduces
+          respectively. This avoids problems with sampling highly localized
+          charges on the grid and is in general recommended. Next, there
+          follow parameters for the multi grid solver, namely the resolution
+          of the grid, see under fragmenting the molecule, the interpolation
+          degree and the number of near field cells. A grid level of 6 is
+          recommended but costly in terms of memory, the other values are at
+          their recommend values.</para>
+
+          <para>In the last line, parameters are given on how to access the
+          JobMarket server, namely it address and its port.</para>
+        </section>
+
+        <section>
+          <title>Analyse fragment results</title>
+
+          <para>After the energies and force vectors of each fragment have
+          been calculated, they need to be summed up to an approximation for
+          the energy and force vectors of the whole molecular system. This is
+          done by calling this action.</para>
+
+          <programlisting>
+		... --analyse-fragment-results \
+		    --fragment-prefix "BondFragment" \
+		    --fragment-resultfile BondFragment_results.dat \
+		    --store-grids 1
+	  </programlisting>
+
+          <para>The purpose of the prefix should already be known to you, same
+          with the result file that is the file parsed by MoleCuilder. The
+          last option states that the sampled charge densities and the
+          calculated potential from the long-range calculations should be
+          stored with the summed up energies and forces. Note that this makes
+          the resulting files substantially larger (Hundreds of megabyte or
+          even gigabytes). Fragment energies and forces are stored in
+          so-called internal homology containers. These are explained in the
+          next section.</para>
+
+          <para>Note that this action sets the force vector if these have been
+          calculated for the fragment. Hence, a <link linkend="???">verlet
+          integration</link> is possible afterwards.</para>
+        </section>
+      </section>
+
+      <section>
+        <title>Homologies</title>
+
+        <para>After a fragmentation procedure has been performed fully, what
+        to do with the results? The forces can be used already but what about
+        the energies? The energy value is basically the function evaluation of
+        the Born-Oppenheimer surface. For molecular dynamics simulations
+        continuous ab-initio calculations to evaluate the Born-Oppenheimer
+        surface is not feasible. Instead usually empirical potential functions
+        are fitted as to resemble the Born-Oppenheimer surface to a sufficient
+        degree.</para>
+
+        <para>One frequent method is the many-body expansion of said surface
+        which is basically nothing else than the fragment ansatz described
+        above. Potential functions resemble a specific term in this many-body
+        expansion. These are discussed in the next section.</para>
+
+        <para>For each of these terms all homologous fragments (i.e. having
+        the same atoms with respect to the present elements and bonded in the
+        same way), differing only in the coordinate of each atom, are just a
+        sampling or a function evaluation of this term of the many-body
+        expansion with respect to varying nuclei coordinates. Hence, it is
+        appropriate to use these function evaluations in a non-linear
+        regression procedure. That is, we want to tune the parameter of the
+        empirical potential function in such a way as to most closely obtain
+        the same function evaluation as the ab-initio calculation did with the
+        same nuclear coordinates. Usually, this is done in a least-square
+        sense, minimising the euclidean norm.</para>
+
+        <para>Homologies are then nothing else but containers for a specific
+        type of fragment of all the different, calculated configurations (i.e.
+        varying nuclear coordinates of the same fragment).</para>
+
+        <para>Now, we explain the actions that parse and store
+        homologies.</para>
+
+        <programlisting>... --parse-homologies homologies.dat</programlisting>
+
+        <para>This parses the all homologies contained in the file
+        <filename>homologies.dat</filename> and appends them to the homology
+        container.</para>
+
+        <programlisting>... --store-homologies homologies.dat</programlisting>
+
+        <para>Complementary, this stores the current contents of the homology
+        container, overwriting the file
+        <filename>homologies.dat</filename>.</para>
+      </section>
+
+      <section>
+        <title>Potentials</title>
+
+        <para>In much the same manner, we would now ask what are homology
+        files or containers good for but with the just had explanation it
+        should be clear: We fit potential function to these function
+        evaluation of terms of the many-body expansion of the Born-Oppenheimer
+        surface of the full system.</para>
+
+        <section>
+          <title>Fitting empirical potentials</title>
+
+          <para>Let's take a look at an exemplary call to the fit potential
+          action.</para>
+
+          <programlisting>
+		... --fit-potential \
+		    --fragment-charges 8 1 1 \
+		    --potential-charges 8 1 \
+		    --potential-type morse \
+		    --take-best-of 5
+	  </programlisting>
+
+          <para>Again, we look at each option in turn. The first is the
+          charges or elements specifying the set of homologous fragments that
+          we want to look at. Here, obviously we are interested in water
+          molecules, consisting of a single oxygen and two hydrogen atoms.
+          Next, we specify the nuclei coordinates of the potential. We give
+          the type of the potential as morse, which requires a single distance
+          or two nuclear coordinates, here between an oxygen and a hydrogen
+          atom. Finally, we state that the non-linear regression should be
+          done with five random starting positions and the set of parameters
+          with the smallest L2 norm wins.</para>
+
+          <note>
+            <para>Due to translational and rotational degrees of freedom for
+            fragments smaller than 7 atoms, it is appropriate to look at the
+            pair-wise distances and not at the absolute coordinates. Hence,
+            the two atomic positions, here for oxygen and hydrogen, are
+            converted to a single distance. If we had given an harmonic
+            angular potential and three charges/element, 8 1 1, i.e. oxygen
+            and two hydrogens, we would have obtained three distances.</para>
+
+            <para>MoleCuilder always adds a so-called constant potential to
+            the fit containing only a single parameter, the energy offset.
+            This offset compensates for the interaction energy associated with
+            a fragment of order 1, e.g. a single hydrogen atom.</para>
+          </note>
+
+          <para>Another way is using a file containing a specific set of
+          potential functions, possibly even with initial values.</para>
+
+          <programlisting>
+		... --fit-potential \
+		    --fragment-charges 8 1 1 \
+		    --potential-file water.potentials \
+		    --set-threshold 1e-3 \
+		    --training-file test.dat
+	  </programlisting>
+
+          <para>Now, all empirical potential functions are summed up into a
+          so-called compound potential over the combined set of parameters.
+          These are now fitted simultaneously. For example, if the potential
+          file <filename>water.potentials</filename> contains a harmonic bond
+          potential between oxygen and hydrogen and another angular potential
+          for the angle between hydrogen, oxygen, and hydrogen atom we would
+          fit a still simple function approximating the energy of a single
+          water molecule. Here, the threshold takes the place of the
+          take-best-of option. Here, random starting parameters are used as
+          long as the final L2 error is not below 1e-3. Also, all data used
+          for training, i.e. the tuples consisting of the fragments nuclei
+          coordinates and the associated energy value are written to the file
+          <filename>test.dat</filename>. This allows for graphical or other
+          type of analysis.</para>
+
+          <para>Note that you can combine the two ways, i.e. start with the
+          first but give an empty potential file. The resulting parameters are
+          stored in this way. Fit other potentials and give different file
+          names for each. Eventually, you have to combine the file in a text
+          editor at the moment.</para>
+        </section>
+
+        <section>
+          <title>Fitting partial charges</title>
+
+          <para>The above empirical potential just model the short-range
+          behavior in the molecular fragment, namely the bonded interaction.
+          In order to model the long-range interaction as well without solving
+          for the electronic ground state in each time step, partial charges
+          are used that capture to some degree the created dipoles due to
+          charge transfer from one atom to another when bonded.</para>
+
+          <para>To allow least-squares regression of these partial charges we
+          need the results of long-range calculations and the store-grids
+          option (see above under <link linkend="???">Fragmentation</link>)
+          must have been given. With these sampled charge density and Coulomb
+          potential stored in the homology containers, we call this action as
+          follows.</para>
+
+          <programlisting>
+		... --fit-partial-charges \
+		    --fragment-charges 8 1 1 \
+		    --potential-file water.potentials \
+		    --radius 0.2
+	  </programlisting>
+
+          <para>This will again use water molecule as homologous fragment
+          "key" to request configurations from the container. Results are
+          stored in <filename>water.potentials</filename>. The radius is used
+          to mark the region directly around the nuclei from the fit
+          procedure. As here the charges of the core electrons and the nuclei
+          itself dominate, we however are only interested in a good
+          approximation to the long-range potential, this mask radius allows
+          to give the range of the excluded zone.</para>
+        </section>
+      </section>
+
+      <section>
+        <title>Various commands</title>
+
+        <para>Here, we gather all commands that do not fit into one of above
+        categories for completeness.</para>
+
+        <section>
+          <title>Changing verbosity</title>
+
+          <para>The verbosity level is the amount of stuff printed to screen.
+          This information will in general help you to understand when
+          something does not work. Mind the <emphasis>ERROR</emphasis> and
+          <emphasis>WARNING</emphasis> messages in any case.</para>
+
+          <para>This sets the verbosity from default of 2 to 4,</para>
+
+          <programlisting>... --verbose 4</programlisting>
+
+          <para>or shorter,</para>
+
+          <programlisting>... -v 4</programlisting>
+        </section>
+
+        <section>
+          <title>Giving the version of the program</title>
+
+          <para>This prints the version information of the code, especially
+          important when you request the fixing of bugs or implementation of
+          features.</para>
+
+          <programlisting>... --version</programlisting>
+        </section>
+
+        <section>
+          <title>Giving warranty information</title>
+
+          <para>As follows warranty information is given,</para>
+
+          <programlisting>... --warranty</programlisting>
+        </section>
+      </section>
+
+      <section>
+        <title>Sessions</title>
+
+        <para>A session refers to the queue of actions you have executed.
+        Together with the initial configuration (and all files required for
+        actions in the queue) this might be seen as a clever way of storing
+        the state of a molecular system. When proceeding in a try&amp;error
+        fashion to construct a certain system, it is a good idea, to store the
+        session at the point where your attempts start to deviate from one
+        another.</para>
+      </section>
+
+      <section>
+        <title>Storing a session</title>
+
+        <para>Storing sessions is simple,</para>
+
+        <programlisting>
+		... --store-session "session.py" \
+		    --session-type python
+	</programlisting>
+
+        <para>Here, the session type is given as python (the other option is
+        cli for in the manner of the command-line interface) and the written
+        python script <filename>session.py</filename> can even be used with
+        the python interface described below, i.e. it is a full python script
+        (that however requires the so-called pyMoleCuilder module).</para>
+      </section>
+
+      <section>
+        <title>Loading a session</title>
+
+        <para>Loading a session only works for python scripts. This actually
+        blurs the line between the command-line interface and the python
+        interface a bit. But even more, MoleCuilder automatically executes a
+        script called <filename>molecuilder.py</filename> if such a file is
+        contained in the current directory.</para>
+
+        <programlisting>... --load-session "session.py"</programlisting>
+
+        <para>This will execute every action with its options contained in the
+        script <filename>session.py</filename>.</para>
+      </section>
+    </section>
+
+    <section>
+      <title>Text menu</title>
+
+      <para>We now discuss how to use the text menu interface.</para>
+
+      <para>The text menu is very much the interface counterpart to the
+      command-line interface. Both work in a terminal session.</para>
+
+      <para>In the text menu, actions can be selected from hierarchical lists.
+      Note that the menus for the graphical interface are organized in the
+      exactly same way. After an action has been chosen, the option values
+      have to be entered one after the other. After the last option value has
+      been given, the action is executed and the result printed to the
+      screen.</para>
+
+      <para>With regards to the other functionality, it is very much the same
+      as the command-line interface above.</para>
+    </section>
+
+    <section>
+      <title linkend="GUI">Graphical user interface</title>
+
+      <para>The main point of the GUI is that it renders the atoms and
+      molecules visually. These are represented by the common
+      stick-and-ball-model. Single or multiple atoms and molecules can easily
+      be accessed, activated and manipulated via tables. Changes made in the
+      tables cause immediate update of the visual representation. Under the
+      hood each of these manipulations is nothing but the call to an action,
+      hence is fully undo- and redoable.</para>
+
+      <para>This is mostly helpful to design more advanced structures that are
+      conceptually difficult to imagine without visual aid. At the end, a
+      session may be stored and this script can then be used to construct
+      various derived or slightly modified structures.</para>
+
+      <section>
+        <title>Basic view</title>
+
+        <para>Let us first give an impression of the basic view of the gui
+        after a molecule has been loaded.</para>
+
+        <figure>
+          <title>Screenshot of the basic view of the GUI after loading a file
+          with eight water molecules.</title>
+
+          <mediaobject>
+            <imageobject>
+              <imagedata entityref="example_basic_view" scalefit="1" width="100%"/>
+            </imageobject>
+          </mediaobject>
+        </figure>
+
+        <section>
+          <title>3D view</title>
+
+          <para>In the above figure, you see the stick-and-ball representation
+          of the water molecules, the dreibein giving the positive axis
+          direction and the cuboidal domain on a black background.</para>
+        </section>
+
+        <section>
+          <title>Information Tabs</title>
+
+          <para>Beneath this 3D view that you can rotate at will your mouse
+          and zoom in and out with your scroll wheel, you find to the right a
+          part containing two tabs named Atom and Molecule. Look at where the
+          mouse pointer is. It has colored the atom underneath in cyan
+          (although it's also an oxygen atom and should bne coloured in rose
+          as the rest). You can inspect its properties in the tab Atom: Name,
+          element, mass, charge, position and number of bonds. If you switch
+          to the Molecule tab, you would see the properties of the water
+          molecule this specific atom belongs to.</para>
+        </section>
+
+        <section>
+          <title>Shape section</title>
+
+          <para>Beneath these information tabs you find the shape sections.
+          There you find a list of all currently created shapes and you can
+          manipulate them via the buttons beneath this list.</para>
+        </section>
+
+        <section>
+          <title>Timeline</title>
+
+          <para>Directly below the 3D view there is a long slider. If a loaded
+          file has multiple time step entries, this slider allows you to
+          smoothly select one time frame after another. Sliding it with the
+          mouse from left to right will reveal the animation that is hidden
+          behind the distinct snapshots stored in the configuration
+          file.</para>
+        </section>
+
+        <section>
+          <title>Selection tables</title>
+
+          <para>Underneath the time line there is another place for
+          tabs.</para>
+
+          <para>The first is on molecules, listing all present molecules of
+          the molecular system in a list view. If you click on a specific
+          molecule, the one will get selected or unselected depending on its
+          current selection state (see below for details on this with respect
+          to the GUI).</para>
+
+          <para>The next tab enumerates all elements known to MoleCuilder
+          where the ones are greyed out that are not present in the molecular
+          system. Clicking on a present element will select all atoms of this
+          specific element. A subsequent click unselects again.</para>
+
+          <para>Subsequent follow tabs on enumerating the fragments and their
+          fragment energies if calculated and the homologies along with
+          graphical depiction (via QWT) if present.</para>
+        </section>
+      </section>
+
+      <section>
+        <title>Selections</title>
+
+        <para>Selections work generally always by selecting the respective
+        action from the pull-down menu.</para>
+
+        <para>However, it may also be accessed directly. The row of icons
+        above the 3D view has two icons depicting the selection of individual
+        atoms or molecules. If either of them is selected, clicking with the
+        left mouse button on an atom will either (un)select the atom or its
+        associated molecule. Multiple atoms can be selected in this
+        manner.</para>
+
+        <para>Also the selection tabs may be used by clicking on the name of a
+        molecule as stated above or at an element.</para>
+
+        <para>Similarly, if shapes are present in the shape section, clicking
+        them with select them and also cause a translucent visualization to
+        appear in the 3D view. Note that this visualization is quite costly
+        right now and not suited to complex shapes.</para>
+      </section>
+
+      <section>
+        <title>Dialogs</title>
+
+        <para>Most essential, however, to the GUI are the dialogs. Each action
+        calls forth such a dialog even if no options are required (the
+        execution of the action has at least to be confirmed). Each dialog
+        consisting of queries for a particular option value. As each option
+        value has a specific type, we briefly go into the details of how these
+        queries look like.</para>
+
+        <note>
+          <para>Each dialog's Ok is greyed out until all entered option values
+          are valid.</para>
+        </note>
+
+        <section>
+          <title>Domain query</title>
+
+          <figure>
+            <title>Screenshot of a dialog showing a domain query</title>
+
+            <mediaobject>
+              <imageobject>
+                <imagedata entityref="dialog_box" scalefit="1" width="100%"/>
+              </imageobject>
+            </mediaobject>
+
+            <para>In the domain query a 3x3 symmetric matrix has to be
+            entered. In the above screenshots you notice that the only
+            non-zero entries are on the main diagonal. Here, we have simply
+            specified a cube of edge length 8. The ok button will be greyed
+            out if the matrix is either singular or not symmetric.</para>
+          </figure>
+        </section>
+
+        <section>
+          <title>Element query</title>
+
+          <figure>
+            <title>Screenshot the add atom action containing an element
+            query</title>
+
+            <mediaobject>
+              <imageobject>
+                <imagedata entityref="dialog_add-atom_tooltip" scalefit="1" width="100%"/>
+              </imageobject>
+            </mediaobject>
+
+            <para>Elements are picked from a pull-down box where all known
+            elements are listed.</para>
+
+            <para>In this dialog you also notice that a tooltip is given,
+            briefly explaining what the action does.</para>
+          </figure>
+        </section>
+
+        <section>
+          <title>Complex query</title>
+
+          <figure>
+            <title>Screenshot of a complex dialog consisting of multiple
+            queries</title>
+
+            <mediaobject>
+              <imageobject>
+                <imagedata entityref="dialog_complex" scalefit="1" width="100%"/>
+              </imageobject>
+            </mediaobject>
+
+            <para>Here we show a more complex dialog. It queries for strings,
+            for integer values (see the increase/decrease arrows), for
+            booleans and for files (the "choose" buttons opens a file
+            dialog).</para>
+          </figure>
+        </section>
+
+        <section>
+          <title>Exit query</title>
+
+          <figure>
+            <title>Screenshort showing the exit dialog</title>
+
+            <mediaobject>
+              <imageobject>
+                <imagedata entityref="dialog_exit" scalefit="1" width="100%"/>
+              </imageobject>
+            </mediaobject>
+
+            <para>Finally, we show the dialog that will pop up when exiting
+            the graphical interface. It will ask whether it should store the
+            current state of the system in the input file or not. You may
+            cancel the exit, close without saving or save the current
+            state.</para>
+          </figure>
+        </section>
+      </section>
+    </section>
+
+    <section>
+      <title>Python interface</title>
+
+      <para>Last but not least we elaborate on the python interface. We have
+      already discusses this interface to some extent. The current session,
+      i.e. the queue of actions you have executed, can be stored as a python
+      script and subsequently executed independently of the user interface it
+      was created with. More general, MoleCuilder can execute arbitrary python
+      scripts where prior to its execution a specific module is loaded by
+      default enabling access to MoleCuilder's actions from inside the
+      script.</para>
+
+      <para>MoleCuilder's python module is called pyMoleCuilder. it is
+      essentially a library that can be imported into python just as any other
+      module. Let us assume you have started the python interpreter and you
+      have added the destination of the <filename>pyMoleCuilder</filename>
+      library to the <varname>PYTHONPATH</varname> variable.</para>
+
+      <programlisting>import pyMoleCuilder as mol</programlisting>
+
+      <para>Subsequently, you can access the help via</para>
+
+      <programlisting>help(mol)</programlisting>
+
+      <para>This will list all of MoleCuilder's actions with their function
+      signatures within python as contained in the module pyMoleCuilder named
+      as mol in the scope of the currently running interpreter. Note that the
+      function names are not the names you know from the command-line
+      interface, they might be called
+      <computeroutput>WorldChangeBox(...)</computeroutput> or alike.</para>
+
+      <para>Let's try it out.</para>
+
+      <programlisting>print mol.CommandVersion()</programlisting>
+
+      <para>This will state the current version of the library.</para>
+
+      <para>Go ahead and try out other commands. Refer to the documentation
+      under the command-line interface and look up the function name via
+      help.</para>
+    </section>
+  </chapter>
+
+  <chapter>
+    <title>Conclusions</title>
+
+    <para>This ends this user guide.</para>
+
+    <para>We have given you a brief introduction to the aim of the program and
+    how each of the four interfaces are to be used. The rest is up to
+    you.</para>
+
+    <para>Tutorials and more information is available online, see <link
+    xlink:href="???">http://www.molecuilder.com/</link>.</para>
+
+    <para>Be aware that in general knowing how the code works allows you to
+    understand what's going wrong if something's going wrong.</para>
+
+    <section>
+      <title>Thanks</title>
+
+      <para>Huge thanks go out to Saskia Metzler who was patient enough to let
+      me sit next to her while riding ten hours in a bus to Berlin.</para>
+    </section>
+  </chapter>
+</book>
