Index: doc/userguide/userguide.xml
===================================================================
--- doc/userguide/userguide.xml	(revision 599b3232e65ac3b245869d9dd63c45d7e8f162f4)
+++ doc/userguide/userguide.xml	(revision d12d818e7c101fa705af778bca10771e52c18690)
@@ -1,5 +1,4 @@
-<?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" [
+<?xml version='1.0' encoding='UTF-8'?>
+<!-- This document was created with Syntext Serna Free. --><!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>
@@ -9,45 +8,32 @@
 <!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">
+<book 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" version="5.0">
   <info>
     <title>MoleCuilder - a Molecule Builder</title>
-
     <author>
-      <personname><firstname>Frederik</firstname><surname>Heber</surname></personname>
-
+      <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>
-
+      <title>MoleCuilder logo depicting a tesselated buckyball and a benzene molecule</title>
       <mediaobject>
         <imageobject>
-          <imagedata entityref="molecuilder_logo" scalefit="1" width="100%"/>
+          <imagedata width="100%" scalefit="1" entityref="molecuilder_logo"/>
         </imageobject>
       </mediaobject>
     </figure>
-
-    <section xml:id='whatis'>
-      <title  xml:id='whatis.title'>What is MoleCuilder?</title>
-
+    <section xml:id="whatis">
+      <title xml:id="whatis.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
@@ -59,5 +45,4 @@
       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
@@ -66,86 +51,64 @@
       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
+      molecular systems, and on scriptability. The last being important a eventually not a single, but
       many, related molecular systems have to be created.</para>
-
-      <section xml:id='installation'>
-        <title xml:id='installation.title'>Installation requirements</title>
-
+      <para>We hope you will enjoy using MoleCuilder as much as we had creating it and still continue extending it. It obtains its flexibility from the use of agile programming techniques and state-of-the-art libraries such as Boost. If you feel dissatiesfied with certain parts, please do not hesitate to give feedback (see below).</para>
+      <section xml:id="installation">
+        <title xml:id="installation.title">Installation requirements</title>
         <para>For installations requirements and instructions we refer to the
-        internal documentation of MoleCuilder, created via doxgen from the
+        internal documentation of MoleCuilder, created via <productname>doxygen</productname>. from the
         source code.</para>
       </section>
-
-      <section xml:id='license'>
-        <title xml:id='license.title'>License</title>
-
+      <section xml:id="license">
+        <title xml:id="license.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 xml:id='disclaimer'>
-        <title xml:id='disclaimer.title'>Disclaimer</title>
-
+      <section xml:id="disclaimer">
+        <title xml:id="disclaimer.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 xml:id='feedback'>
-        <title xml:id='feedback.title'>Feedback</title>
-
+        <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 &quot;as is&quot; 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 xml:id="feedback">
+        <title xml:id="feedback.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
+        error, saved &quot;session scripts&quot; (see below) and auxiliary files. Please
         mind sensible space restrictions of email attachments.</para>
       </section>
-
-      <section xml:id='notation'>
-        <title xml:id='notation.title'>Notation</title>
-
+      <section xml:id="notation">
+        <title xml:id="notation.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>
+            manipulating the molecular system. Here, atomic refers to indivisible and not to atoms. It is also referred to as a command.</para>
           </listitem>
-
           <listitem>
             <para>Selection refers to a subsets from the set of instances of a
-            particular type, e.g. atoms.</para>
+            particular type, e.g. atoms, molecules, shapes, ...</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>
+            spheres, cubes, or cylinders.</para>
           </listitem>
+          <listitem>World refers to the whole of the molecular system, i.e. all atoms with coordinates and element type (over all time steps), all bonds between pairs of atoms, the size of the simulation domain. This state is also referred to as the state.</listitem>
+          <listitem>Time step is the current discrete position in time. Molecular dynamics simulations are executed in discrete (but very small) time steps. Each atom has a distinct position per time step. The discrete positions over the discrete time steps samples its trajectory during a simulation.</listitem>
         </itemizedlist>
       </section>
-
-      <section xml:id='completeness'>
-        <title xml:id='completeness.title'>Completeness</title>
-
+      <section xml:id="completeness">
+        <title xml:id="completeness.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
+        probably not safe to use yet. If you nonetheless require them, you         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>
@@ -153,54 +116,40 @@
     </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
+    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 xml:id='concepts'>
-      <title xml:id='concepts.title'>Concepts</title>
-
+    <section xml:id="concepts">
+      <title xml:id="concepts.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
+          They have at least 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
+          number of atoms, i.e. by beginning at an arbitrary atom of the molecule and traversing its bond graph eventually all of the molecule&apos;s atoms are visited. Currently, a bond refers to a covalent bonding between atoms. Also, molecules 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>
+          system into distinct molecules on request.</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
+          <para>The domain refers to the simulation domain. It is the
           parallelepiped in <inlineequation>
               <m:math display="inline">
@@ -213,19 +162,15 @@
       </orderedlist>
     </section>
-
-    <section xml:id='interfaces'>
-      <title xml:id='interfaces.title'>Interfaces</title>
-
+    <section xml:id="interfaces">
+      <title xml:id="interfaces.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
+appending to the shell command a number of commands including all
+          required options that are then 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,
@@ -235,8 +180,6 @@
           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
@@ -244,18 +187,14 @@
           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
+          <para>The graphical interface is based on Qt. It features a full graphical, three-dimensional
+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
@@ -267,11 +206,8 @@
       </orderedlist>
     </section>
-
-    <section xml:id='fileformats'>
-      <title xml:id='fileformats.title'>Known File formats</title>
-
-      <para>We briefly the file formats MoleCuilder can parse and
-      store.</para>
-
+    <section xml:id="fileformats">
+      <title xml:id="fileformats.title">Known File formats</title>
+      <para>We briefly list the file formats MoleCuilder can parse and
+      store. We refer to external websites for more detailed information where appropriate.</para>
       <itemizedlist>
         <listitem>
@@ -280,15 +216,12 @@
           of lines and a comment line)</para>
         </listitem>
-
         <listitem>
-          <para><link xlink:href="http://www.mpqc.org/"><productname>MPQC
-          </productname></link>, <filename>.in</filename></para>
+          <para><link xlink:href="http://www.mpqc.org/">
+              <productname>MPQC </productname>
+            </link>, <filename>.in</filename></para>
         </listitem>
-
         <listitem>
-          <para><link xlink:href="http://www.pdb.org/">PDB</link>, <filename>
-          .pdb</filename></para>
+          <para><link xlink:href="http://www.pdb.org/">PDB</link>, <filename> .pdb</filename></para>
         </listitem>
-
         <listitem>
           <para><productname>ESPACK</productname>, <filename>.conf</filename>
@@ -296,15 +229,14 @@
           University of Bonn, code not in circulation)</para>
         </listitem>
-
         <listitem>
-          <para><link xlink:href="http://www.psicode.org/"><productname>PSI4
-          </productname></link>, <filename>.psi</filename></para>
+          <para><link xlink:href="http://www.psicode.org/">
+              <productname>PSI4 </productname>
+            </link>, <filename>.psi</filename></para>
         </listitem>
-
         <listitem>
-          <para><link xlink:href="http://www.tremolo-x.org/"><productname>
-          TREMOLO</productname></link>, <filename>.data</filename></para>
+          <para><link xlink:href="http://www.tremolo-x.org/">
+              <productname> TREMOLO</productname>
+            </link>, <filename>.data</filename></para>
         </listitem>
-
         <listitem>
           <para>XML, <filename>.xml</filename> (XML as read by 
@@ -313,18 +245,14 @@
         </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
+      one into another (with possible loss of data outside of 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
+    <para>We will 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
@@ -332,10 +260,9 @@
     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:
+    (command-line, python) interfaces to use MoleCuilder to its full potential:
     The interactive interface gives you the immediate feedback in constructing
-    "synthesis" (build) chains (of commands) for constructing your specific
+    &quot;synthesis&quot; (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
@@ -343,213 +270,163 @@
     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 xml:id='command-line-interface'>
-      <title xml:id='command-line-interface.title'>Command-line interface</title>
-
+    in documentation your experiments and later on understanding of what has
+    been actually created by the prescribed commands, i.e. debugging.</para>
+    <section xml:id="command-line-interface">
+      <title xml:id="command-line-interface.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
+      Open an empty file, add 2 hydrogen atoms and add 1 oxygen atom, recognize the bond graph, choose a
+      simulation box, fill the box with this given &quot;filler&quot; 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
+      ab-initio computations. To some small extent <command>MoleCuilder</command> also allows manipulation of these paramters. An example for the above procedure is given
       below:</para>
-
       <programlisting>
-	./molecuilder \
-		-i sample.xyz \
-		--add-atom H \
-		--domain-position "0.,0.,0." \
-		...
-	</programlisting>
-
+ ./molecuilder \
+  -i sample.xyz \
+  --add-atom H \
+    --domain-position &quot;0.,0.,0.&quot; \
+  ...
+ </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 
+      slew of arguments -- one per line split with a backslash telling the comman 
       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 
+      the domain where to add the &quot;H&quot;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 
+      for its shortform, such as <emphasis role="bold"> -a</emphasis> 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>
+      and in this do not have to be specified.</para>
+      <formalpara><title>Invalid values</title><para>Certain options accept only very specific input. For example, the option value associated with <emphasis role="bold">add-atom</emphasis></para>, i.e. the chemical element, can only be one of the chemical symbols that exist and not any arbitrary string. Each option value is checked on parsing the command-line. If any value is not valid, an error message is given and none of the actions is executed.</formalpara>
+      <formalpara>
+        <title>Shortforms of Actions</title>
         <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>
+        command-line comprehendable to you in years to come.</para>
+      </formalpara>
+      <note>
+        <para>Note further that when placing a slew of commands in a script file it is generally recommended to use the above formatting: One command or option per line and each</para>
+        <para>option receives an extra tab for indentation.</para>
       </note>
-
-      <section xml:id='preliminaries'>
-        <title xml:id='preliminaries.title'>Preliminaries</title>
-
+      <section xml:id="preliminaries">
+        <title xml:id="preliminaries.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
+        <para>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>
-
+give the details on the manipulation ordered by the
+        scale they act upon - single atoms, multiple atoms organized as
+        molecules, and all atoms organized 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
+        procedure but just its necessary parts, i.e. &quot;...&quot; 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>
-
+        file, for storing the manipulated state of the molecular system. </para>
+        <para>So if we write</para>
+        <programlisting>... --help</programlisting>
+        <para>Then we actually mean you to write</para>
         <programlisting>./molecuilder --help</programlisting>
-
-        <para>will always give you a list of all available actions and also a
+        <para>Note that this specific exemplary command is very useful  as it 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>
-
+        &quot;add-atom&quot;,</para>
+        <programlisting>./molecuilder --help 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>
-
+        <programlisting>... --add-atom H --domain-position &quot;0,0,0&quot; --undo</programlisting>
         <para>and redo as follows</para>
-
-        <programlisting>... --add-atom H --domain-position "0,0,0" --undo --redo</programlisting>
-
+        <programlisting>... --add-atom H --domain-position &quot;0,0,0&quot; --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,
+        this should tell you that actions are placed internally in a queue, i.e. a history,
         that undo and redo manipulate.</para>
-      </section>
-
-      <section xml:id='fileparsers'>
-        <title xml:id='fileparsers.title'>File parsers</title>
-
+        <para>Due to a current limitation of the implementation each command can be used on the command-line only once. Note that this <emphasis role="italic">only</emphasis> applies to the command-line interface. All other interfaces, especially all interactive ones, do not have such a restriction. For the command-line interface there are several ways to work around it. Either by splitting the whole chain of commands into several chunks, each using only unique commands and using the input file (the state) to contain  and transport the intermediate stages as input for the next stage. Or to switch to other commands: often there are several possible ways of achieving a goal, especially when using selections.</para>
+        <para>Being done now with the preliminaries we now go through all available actions present in MoleCuilder.</para>
+      </section>
+      <section xml:id="fileparsers">
+        <title xml:id="fileparsers.title">File parsers</title>
         <para>We have already given a list of all known file formats, see
         <link linkend="fileformats">File formats</link>. Next, we explain how these
         file formats are picked and manipulated.</para>
-
-        <section xml:id='fileparsers.parsing'>
-          <title xml:id='fileparsers.parsing.title'>Parsing files</title>
-
+        <section xml:id="fileparsers.parsing">
+          <title xml:id="fileparsers.parsing.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,
+          into the state. Most importantly, 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
+          <filename>water</filename> as designated by the <emphasis role="bold">input</emphasis> command. 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 xml:id='fileparsers.set-output'>
-          <title xml:id='fileparsers.set-output.tile'>Adding output file 
-          formats</title>
-
+          have been used. This is the default behavior: any additional file format used in loading is registered internally and the output file will then be written in all registered formats on exit.</para>
+        </section>
+        <section xml:id="fileparsers.set-output">
+          <title xml:id="fileparsers.set-output.tile">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>
-
+          the molecular system is written to 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 xml:id='fileparsers.output-as'>
-          <title xml:id='fileparsers.output-as.title'>Output the current 
-          molecular system</title>
-
+          <productname>TREMOLO</productname> configuration file. See
+        <link linkend="fileformats">File formats</link> for the list of all file formats available.</para>
+        </section>
+        <section xml:id="fileparsers.output-as">
+          <title xml:id="fileparsers.output-as.title">Output the World</title>
           <para>This will store the current World, i.e. all its atoms, to a 
           given file, where the output format is determined from the file
           suffix.</para>
-
           <programlisting>... --output-as world.xyz</programlisting>
-        </section>
-
-        <section xml:id='fileparsers.save-selected-molecules'>
-          <title xml:id='fileparsers.save-selected-molecules.title'>Output 
-          the current molecular system</title>
-
+          <para>This will be automatically done on program exit, but in case an intermediate state is required (making sense for interactive and python interfaces), this command can be used.</para>
+        </section>
+        <section xml:id="fileparsers.save-selected-molecules">
+          <title xml:id="fileparsers.save-selected-molecules.title">Output the current molecular system</title>
           <para>This will store all atoms contained in the currently selected
-          molecules to file. This is different to "store-saturated-fragment"
+          molecules to file. This is different to<emphasis role="bold">store-saturated-fragment</emphasis>
           as it will not saturate dangling bonds because only whole molecules,
           i.e. whose bond graph is connected, will be stored.</para>
-
           <programlisting>... --save-selected-molecules waters.pdb
           </programlisting>
         </section>
-
-        <section xml:id='fileparsers.bond-file'>
-          <title xml:id='fileparsers.bond-file.title'>Load extra bond 
-          information</title>
-
-          <para>For some parsers bond information is stored not with the atoms
-          coordinates but in an extra file. This action parses such a file.</para>
-
-          <programlisting>... --bond-file water.dbond
-          </programlisting>
-        </section>
-      </section>
-
-      <section xml:id='selections'>
-        <title xml:id='selections.title'>Selections and unselections</title>
-
+      </section>
+      <section xml:id="selections">
+        <title xml:id="selections.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>
-
+        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. Essentially, it is just a filter.</para>
         <para>Selections either work on atoms, on molecules, or on shapes
-        (this we explain lateron). A given selection is maintained from the
+        (this we explain later on). 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
+        molecule, shape). Selections are not stored to file (i.e. do not belong to the state).</para>
+        <para>We only give here a brief list on the available kind of selections for each of the three  types they work on.
+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>
-
+        <para>i.e. they are prepended by either <emphasis role="bold">select</emphasis> or <emphasis role="bold">unselect</emphasis>.</para>
         <itemizedlist>
           <listitem>
             <para>Atoms</para>
-
             <itemizedlist>
               <listitem>
@@ -559,5 +436,4 @@
                 </programlisting>
               </listitem>
-
               <listitem>
                 <para>None</para>
@@ -569,5 +445,4 @@
                 </programlisting>
               </listitem>
-
               <listitem>
                 <para>Invert selection</para>
@@ -576,5 +451,4 @@
                 </programlisting>
               </listitem>
-
               <listitem>
                 <para>By Element (all hydrogen atoms, all sulphur atoms,
@@ -587,5 +461,4 @@
                 </programlisting>
               </listitem>
-
               <listitem>
                 <para>By Id (atom with id 76)</para>
@@ -597,5 +470,4 @@
                 </programlisting>
               </listitem>
-
               <listitem>
                 <para>By Order (the first (1), the second, ... the last 
@@ -608,7 +480,6 @@
                 </programlisting>
               </listitem>
-
               <listitem>
-                <para>By Shape (specific region of the domain)</para>
+                <para>By Shape (all atoms inside the volume specified by the currently selected shape)</para>
                 <programlisting>
                 ... --select-atom-inside-volume
@@ -618,5 +489,4 @@
                 </programlisting>
               </listitem>
-
               <listitem>
                 <para>By Molecule (all atoms belonging to currently selected
@@ -629,8 +499,7 @@
                 </programlisting>
               </listitem>
-
               <listitem>
                 <para>Push/Pop the current selection to/from a stack to store 
-		it momentarily and allow modifications in MakroActions.</para>
+  it momentarily and allow modifications in MakroActions (this is very specific and used mostly internally).</para>
                 <programlisting>
                 ... --push-atom-selection
@@ -642,8 +511,6 @@
             </itemizedlist>
           </listitem>
-
           <listitem>
             <para>Molecules</para>
-
             <itemizedlist>
               <listitem>
@@ -653,5 +520,4 @@
                 </programlisting>
               </listitem>
-
               <listitem>
                 <para>None</para>
@@ -663,5 +529,4 @@
                 </programlisting>
               </listitem>
-
               <listitem>
                 <para>Invert selection</para>
@@ -670,5 +535,4 @@
                 </programlisting>
               </listitem>
-
               <listitem>
                 <para>By Id (molecule with id 4)</para>
@@ -680,5 +544,4 @@
                 </programlisting>
               </listitem>
-
               <listitem>
                 <para>By Order (first created molecule, second created 
@@ -691,25 +554,22 @@
                 </programlisting>
               </listitem>
-
               <listitem>
                 <para>By Formula (molecule with H2O as formula)</para>
                 <programlisting>
-                ... --select-molecules-by-formula "H2O"
-                </programlisting>
-                <programlisting>
-                ... --unselect-molecules-by-formula "H2O"
+                ... --select-molecules-by-formula &quot;H2O&quot;
+                </programlisting>
+                <programlisting>
+                ... --unselect-molecules-by-formula &quot;H2O&quot;
                 </programlisting>
               </listitem>
-
               <listitem>
-                <para>By Name (molecule named "water4")</para>
-                <programlisting>
-                ... --select-molecules-by-name "water4"
-                </programlisting>
-                <programlisting>
-                ... --unselect-molecules-by-name "water4"
+                <para>By Name (all molecules named &quot;water4&quot;)</para>
+                <programlisting>
+                ... --select-molecules-by-name &quot;water4&quot;
+                </programlisting>
+                <programlisting>
+                ... --unselect-molecules-by-name &quot;water4&quot;
                 </programlisting>
               </listitem>
-
               <listitem>
                 <para>By Atom (all molecules for which at least one atom is
@@ -722,8 +582,7 @@
                 </programlisting>
               </listitem>
-
               <listitem>
                 <para>Push/Pop the current selection to/from a stack to store 
-		it momentarily and allow modifications in MakroActions.</para>
+  it momentarily and allow modifications in MakroActions.</para>
                 <programlisting>
                 ... --push-molecule-selection
@@ -735,8 +594,6 @@
             </itemizedlist>
           </listitem>
-
           <listitem>
             <para>Shapes</para>
-
             <itemizedlist>
               <listitem>
@@ -746,5 +603,4 @@
                 </programlisting>
               </listitem>
-
               <listitem>
                 <para>None</para>
@@ -753,23 +609,17 @@
                 </programlisting>
               </listitem>
-
               <listitem>
-                <para>By Name (shape name "sphere1")</para>
-                <programlisting>
-                ... --select-shape-by-name "sphere1"
-                </programlisting>
-                <programlisting>
-                ... --unselect-shape-by-name "sphere1"
+                <para>By Name (all shapes named &quot;sphere1&quot;)</para>
+                <programlisting>
+                ... --select-shape-by-name &quot;sphere1&quot;
+                </programlisting>
+                <programlisting>
+                ... --unselect-shape-by-name &quot;sphere1&quot;
                 </programlisting>
               </listitem>
             </itemizedlist>
           </listitem>
-
         </itemizedlist>
-
-        <remark>Note that an unselected instance (e.g. an atom) remains
-        unselected upon further unselection and vice versa with
-        selection.</remark>
-
+        <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
@@ -777,57 +627,53 @@
         selecting all atoms inside the shape and then removing them.</para>
       </section>
-
-      <section xml:id='shapes'>
-        <title xml:id='shapes.title'>Shapes</title>
-
+      <section xml:id="shapes">
+        <title xml:id="shapes.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
+        sphere, cylinder, the whole domain, or 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
+        combining a sphere with the negated (<emphasis role="italic">not</emphasis> operation) of a smaller sphere, we
         obtain a spherical surface of specific thickness.</para>
-
-        <section xml:id='shapes.create-shape'>
-          <title xml:id='shapes.create-shape.title'>Creating shapes</title>
-
+        <section xml:id="shapes.create-shape">
+          <title xml:id="shapes.create-shape.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>
-
+          <programlisting>
+  ... --create-shape \
+      --shape-type sphere \
+      --shape-name &quot;sphere1&quot; \
+      --stretch &quot;2,2,2&quot; \
+      --translation &quot;5,5,5&quot;
+   </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
+          with name &quot;sphere1&quot; that is centered at (5,5,5). Other primitives are
           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 xml:id='shapes.combine-shapes'>
-          <title xml:id='shapes.combine-shapes.title'>Combining shapes</title>
-
+          <programlisting><programlisting>
+  ... --create-shape \
+      --shape-type cuboid \
+      --shape-name &quot;box&quot; \
+      --stretch &quot;1,2,2&quot; \
+      --translation &quot;5,5,5&quot; \
+      --angle-x &quot;90&quot;
+   </programlisting>
+  ... --create-shape \
+      --shape-type cylinder \
+      --shape-name &quot;cylinder&quot; \
+      --stretch &quot;1,2,2&quot; \
+      --translation &quot;5,5,5&quot; \
+      --angle-y &quot;90&quot;
+   </programlisting>
+        </section>
+        <section xml:id="shapes.combine-shapes">
+          <title xml:id="shapes.combine-shapes.title">Combining shapes</title>
           <para>Any two shapes can be combined by boolean operations as follows</para>
-
-          <programlisting>
-		... --combine-shapes \
-		    --shape-name "combinedshape" \
-		    --shape-op "AND" \
-	  </programlisting>
-
-          <para>This will combine two currently selected shapes vis the "AND" operation
-          and create a new shape called "combinedshape". Note that the two old shapes
+          <programlisting>
+  ... --combine-shapes \
+      --shape-name &quot;combinedshape&quot; \
+      --shape-op &quot;AND&quot;
+   </programlisting>
+          <para>This will combine two currently selected shapes vis the &quot;AND&quot; operation
+          and create a new shape called &quot;combinedshape&quot;. Note that the two old shapes
           are still present after this operation. We briefly explain each operation:
           </para>
@@ -835,9 +681,9 @@
             <listitem>
               <para><emphasis>AND</emphasis> combines two currently selected shapes
-              into a new shape that only consists of the volume where shapes overlap.</para>
+              into a new shape that consists of only the volume where shapes overlap.</para>
             </listitem>
             <listitem>
               <para><emphasis>OR</emphasis> combines two currently selected shapes
-              into a new shape that consists of all the volume where that either shape
+              into a new shape that consists of all the volume that either shape
               occupies.</para>
             </listitem>
@@ -849,224 +695,163 @@
           </itemizedlist>
         </section>
-
-        <section xml:id='shapes.remove-shape'>
-          <title xml:id='shapes.remove-shape.title'>Removing shapes</title>
-
+        <section xml:id="shapes.remove-shape">
+          <title xml:id="shapes.remove-shape.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 xml:id='shapes.manipulation'>
-          <title xml:id='shapes.manipulation.title'>Manipulating shapes</title>
-
+          <para>This removes all currently selected shapes.</para>
+        </section>
+        <section xml:id="shapes.manipulation">
+          <title xml:id="shapes.manipulation.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>
-
+          this manipulation could have occurred already at creation but we may also
+do it           later on. As usual, we just list examples of the various manipulations
+          below, each of them works on the currently selected shapes.</para>
+          <programlisting>
+  ... --stretch-shapes &quot;1,1,2&quot; \
+      --stretch-center &quot;5,5,5&quot;
+   </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-shapes \
-		    --center "10,2,2" \
-		    --angle-x 90 \
-		    --angle-y 0 \
-		    --angle-z 0
-	  </programlisting>
-
+          <programlisting>
+  ... --rotate-shapes \
+      --center &quot;10,2,2&quot; \
+      --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>
-
+          <programlisting>... --translate-shapes &quot;5,0,0&quot; </programlisting>
           <para>This translates all selected shapes by 5 along the x
           axis.</para>
         </section>
       </section>
-
-      <section xml:id='randomization'>
-        <title xml:id='randomization.title'>Randomization</title>
-
+      <section xml:id="randomization">
+        <title xml:id="randomization.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 two parts: engine and distribution. The engine yields a <emphasis role="italic">uniform</emphasis> 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.
+        aforementioned filling of the domain (see below) 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
+        360 degrees and 0,1,2,3 act as divisor, hence rotation angle will then be 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>
-
+  ... --set-random-number-distribution &quot;uniform_int&quot; \
+      --random-number-distribution-parameters &quot;p=1&quot;
+ </programlisting>
+        <para>This changes the distribution to &quot;uniform_int&quot;, i.e. integer
+        numbers that are distributed uniformly.</para>
         <programlisting>
-		... --set-random-number-engine "mt19937" \
-		    --random-numner-engine-parameters "seed=10"
-	</programlisting>
-
+  ... --set-random-number-engine &quot;mt19937&quot; \
+      --random-numner-engine-parameters &quot;seed=10&quot;
+ </programlisting>
         <para>Specifying the seed allows you to obtain the same sequence of
         random numbers for testing purposes.</para>
       </section>
-
-      <section xml:id='atoms'>
-        <title xml:id='atoms.title'>Manipulate atoms</title>
-
+      <section xml:id="atoms">
+        <title xml:id="atoms.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 xml:id='atoms.add-atom'>
-          <title xml:id='atoms.add-atom.title'>Adding atoms</title>
-
+        <section xml:id="atoms.add-atom">
+          <title xml:id="atoms.add-atom.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>
-
+          <programlisting>
+  ... --add-atom O \
+      --domain-position &quot;2.,3.,2.35&quot;
+   </programlisting>
           <para>where the element is given via its chemical symbol and the
           vector gives the position within the domain</para>
         </section>
-
-        <section xml:id='atoms.remove-atom'>
-          <title xml:id='atoms.remove-atom.title'>Removing atoms</title>
-
+        <section xml:id="atoms.remove-atom">
+          <title xml:id="atoms.remove-atom.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 xml:id='atoms.saturate-atom'>
-          <title xml:id='atoms.saturate-atom.title'>Saturating atoms</title>
-
+        <section xml:id="atoms.saturate-atom">
+          <title xml:id="atoms.saturate-atom.title">Saturating atoms</title>
           <para>Newly instantiated atoms have no bonds to any other atom. If
           you want to fill up their valence by a slew of hydrogen atoms 
           residing on a sphere around this atom, use this action.</para>
-
-          <programlisting>
-		... --saturate-atoms
-	  </programlisting>
-
-          <para>A number of hydrogen atoms is added. The number corrresponding
-          to the valence of each selected atom. They are placed in the same
+          <programlisting>
+  ... --saturate-atoms
+   </programlisting>
+          <para>A number of hydrogen atoms is added around each selected atom corresponding to the valence of the chemical element. The hydrogen atoms are placed in the same
           distance to this atom and approximately with same distance to their
-	  nearest neighbors.</para>
-        </section>
-
-        <section xml:id='atoms.translate-atom'>
-          <title xml:id='atoms.translate-atom.title'>Translating atoms</title>
-
+   nearest neighbors. Already present bonds (i.e. the position of neighboring atoms) is taken into account.</para>
+        </section>
+        <section xml:id="atoms.translate-atom">
+          <title xml:id="atoms.translate-atom.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
+have to          specify a translation vector.</para>
+          <programlisting>
+  ... --translate-atoms &quot;-1,0,0&quot; \
+      --periodic 0
+   </programlisting>
+          <para>This translates all atoms by &quot;-1&quot; along the x axis and does not
+          mind the boundary conditions, i.e. it might shift atoms outside of the
           domain.</para>
         </section>
-
-        <section xml:id='atoms.mirror-atoms'>
-          <title xml:id='atoms.mirror-atoms.title'>Mirroring atoms</title>
-
+        <section xml:id="atoms.mirror-atoms">
+          <title xml:id="atoms.mirror-atoms.title">Mirroring atoms</title>
           <para>Present (and selected) atoms can be mirrored with respect to
           a certain plane. You have to specify the normal vector of the plane
           and the offset with respect to the origin as follows</para>
-
-          <programlisting>
-		... --mirror-atoms "1,0,0" \
+          <programlisting>
+  ... --mirror-atoms &quot;1,0,0&quot; \
                     --plane-offset 10.1 \
                     --periodic 0
-	  </programlisting>
-	</section>
-
-        <section xml:id='atoms.translate-to-origin'>
-          <title xml:id='atoms.translate-to-origin.title'>Translating atoms</title>
-
+   </programlisting>
+        </section>
+        <section xml:id="atoms.translate-to-origin">
+          <title xml:id="atoms.translate-to-origin.title">Translating atoms to origin</title>
           <para>The following Action is convenient to place a subset of atoms
-          at a known position, the origin, and then translate to some other
+          at a known position, the origin, and then translate them to some other
           absolute coordinate. It calculates the average position of the set
           of selected atoms and then translates all atoms by the negative of
-          this center, i.e. the center is afterwards at the origin.</para>
-
+          this center, i.e. the center over all selected atoms is afterwards at the origin.</para>
           <programlisting>... --translate-to-origin</programlisting>
-        </section>
-
-        <section xml:id='atoms.change-element'>
-          <title xml:id='atoms.change-element.title'>Changing an atoms element
-          </title>
-
+          <para>Note that this naturally does not heed the boundary conditions of the simulation domain.</para>
+        </section>
+        <section xml:id="atoms.change-element">
+          <title xml:id="atoms.change-element.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 xml:id='bond'>
-        <title xml:id='bond.title'>Bond-related manipulation</title>
-
+      <section xml:id="bond">
+        <title xml:id="bond.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
+        <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 xml:id='bond.create-adjacency'>
-          <title xml:id='bond.create-adjacency.title'>Creating a bond graph
-          </title>
-
+        <section xml:id="bond.create-adjacency">
+          <title xml:id="bond.create-adjacency.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>
-
+          i.e. if we look at two atoms indexed by &quot;a&quot; and &quot;b&quot;</para>
           <equation>
-            <title>V(a) + V(b) - \tau &lt; R_{ab} &lt; V(a) + V(b) +
-            \tau</title>
-
+            <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: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
@@ -1081,20 +866,13 @@
             </inlineequation>.</para>
         </section>
-
-        <section xml:id='bond.destroy-adjacency'>
-          <title xml:id='bond.destroy-adjacency.title'>Destroying the bond 
-          graph</title>
-
+        <section xml:id="bond.destroy-adjacency">
+          <title xml:id="bond.destroy-adjacency.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 xml:id='bond.correct-bonddegree'>
-          <title xml:id='bond.correct-bonddegree.title'>Correcting bond 
-          degrees</title>
-
-          <para>Typically, after loading an input file bond information, e.g.
+        <section xml:id="bond.correct-bonddegree">
+          <title xml:id="bond.correct-bonddegree.title">Correcting bond degrees</title>
+          <para>Typically, after loading an input file with bond information, e.g.
           a PDB file, the bond graph is complete but we lack the weights. That
           is we do not know whether a bond is single, double, triple, ...
@@ -1105,24 +883,18 @@
           atoms. Hence, for large systems this may take longer than expected.
           </para>
-
           <programlisting>... --correct-bonddegree</programlisting>
-        </section>
-
-        <section xml:id='bond.depth-first-search'>
-          <title xml:id='bond.depth-first-search.title'>Analysing a bond 
-          graph</title>
-
+          <para>However, in normal use scenarios the action is fast and linear scaling.</para>
+        </section>
+        <section xml:id="bond.depth-first-search">
+          <title xml:id="bond.depth-first-search.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 xml:id='bond.subgraph-dissection'>
-          <title xml:id='bond.subgraph-dissection.title'>Dissecting the 
-          molecular system into molecules</title>
-
+          <para>Note that this will only print some information and has no other impact on the state.</para>
+        </section>
+        <section xml:id="bond.subgraph-dissection">
+          <title xml:id="bond.subgraph-dissection.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
+          molecules 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
@@ -1130,89 +902,69 @@
           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 xml:id='bond.update-molecules'>
-          <title xml:id='bond.update-molecules.title'>Updating molecule 
-          structure</title>
-
+          <para>This analyses the bond graph, removes all currently present molecules and creates new molecules that each contain a single connected
+          subgraph, hence the naming of the Action.</para>
+        </section>
+        <section xml:id="bond.update-molecules">
+          <title xml:id="bond.update-molecules.title">Updating molecule structure</title>
           <para>When the bond information has changed, new molecules might 
           have formed, this action updates all the molecules by scanning
-          the connectedness of the bond grapf of the molecular system.
+          the connectedness of the bond graph of the molecular system.
           </para>
-
           <programlisting>... --update-molecules</programlisting>
         </section>
-
-        <section xml:id='bond.adds-bond'>
-          <title xml:id='bond.adds-bond.title'>Adding a bond manually</title>
-
+        <section xml:id="bond.adds-bond">
+          <title xml:id="bond.adds-bond.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.
           </para>
-
           <programlisting>... --add-bonds</programlisting>
-
-	  <para>If two atoms are selected, the single bond in between, if not
-	  present, is added. If more than two atoms are selected, than the
-	  bond between any pair of these is added.</para>
-	 <note><para>This is especially useful in conjunction with the
-	  fragmentation scheme. If you want to know the contribution from
-	  certain fragments whose subgraph is not connected you can simply
-	  make the associated subset of atoms connected by selecting all
-	  bonds and adding the bonds.</para>
-	 </note>
-        </section>
-
-        <section xml:id='bond.remove-bonds'>
-          <title xml:id='bond.remove-bonds.title'>Removing a bond manually
-          </title>
-
+          <para>If two atoms are selected, the single bond in between is added, if not
+already    present. If more than two atoms are selected, than the
+   bond between any pair of these is added.</para>
+          <note>
+            <para>This is especially useful in conjunction with the
+   fragmentation scheme (explained later on). If you want to know the contribution from
+   certain fragments whose subgraph is not connected, you can simply
+   make the associated subset of atoms connected by selecting all
+   bonds and adding the bonds.</para>
+          </note>
+        </section>
+        <section xml:id="bond.remove-bonds">
+          <title xml:id="bond.remove-bonds.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-bonds</programlisting>
-
-	  <para>Similarly, if more than two atoms are selected, then all bonds
-	  found between any pair of these is removed.</para>
-        </section>
-
-        <section xml:id='bond.save-bonds'>
-          <title xml:id='bond.save-bonds.title'>Saving bond information
-          </title>
-
-          <para>Bond information can be saved to a file in <link 
-          xlink:href="http://www.molecuilder.com/"><productname>TREMOLO
-          </productname></link>'s dbond style.</para>
-
+          <para>Similarly, if more than two atoms are selected, then all bonds
+   found between any pair of these is removed.</para>
+        </section>
+        <section xml:id="bond.save-bonds">
+          <title xml:id="bond.save-bonds.title">Saving bond information </title>
+          <para>Bond information can be saved to a file in <link xlink:href="http://www.molecuilder.com/">
+              <productname>TREMOLO </productname>
+            </link>&apos;s dbond style.</para>
           <programlisting>... --save-bonds system.dbonds</programlisting>
-          
           <para>Similarly is the following Action which saves the bond
           information as a simple list of one atomic id per line and in
           the same line, separated by spaces, the ids of all atoms connected
           to it.</para>
-          
           <programlisting>... --save-adjacency system.adj</programlisting>
-          
-        </section>
-
-        <section xml:id='bond.stretch-bond'>
-          <title xml:id='bond.stretch-bond.title'>Stretching a bond</title>
-
+          <para>This corresponds to the <emphasis role="bold">bond-file</emphasis> Action.</para>
+        </section>
+        <section xml:id="fileparsers.bond-file">
+          <title xml:id="fileparsers.bond-file.title">Load extra bond information</title>
+          <para>The reverse Action of <emphasis role="bold">save-bonds</emphasis> is the following which loads bond information from the file <emphasis role="bold">water.dbond</emphasis>.</para>
+          <programlisting>... --bond-file water.dbond</programlisting>
+          <para>Note that because of the use of ids the bond file is intimately connected to the associated input file containing the atomic coordinates and thus both should parsed right after another and to the very beginning of any sequence of Actions.</para>
+        </section>
+        <section xml:id="bond.stretch-bond">
+          <title xml:id="bond.stretch-bond.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
@@ -1220,79 +972,57 @@
           </warning>
         </section>
-
-        <section xml:id='bond.change-bond-angle'>
-          <title xml:id='bond.change-bond-angle.title'>Changing a bond angle
-          </title>
-
+        <section xml:id="bond.change-bond-angle">
+          <title xml:id="bond.change-bond-angle.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
+          <para>This will change the angle from its value to 90 degrees 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 xml:id='molecule'>
-        <title xml:id='molecule.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.
+          to both other atoms serves as rotation joint).</para>
+        </section>
+      </section>
+      <section xml:id="molecule">
+        <title xml:id="molecule.title">Manipulate molecules</title>
+        <para>Molecules are agglomerations of atoms that are (covalently) 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
+some or even        all bonds in between. The Actions below mostly deal with copying
+        molecules. Removing of molecules is done via selecting the molecule&apos;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="fragmentation">Dissecting the 
-          molecular system into molecules</link></para>
+          information, see <link linkend="fragmentation">Dissecting the molecular system into molecules</link></para>
         </note>
-
-        <section xml:id='molecule.copy'>
-          <title xml:id='molecule.copy.title'>Copy molecules</title>
-
+        <section xml:id="molecule.copy">
+          <title xml:id="molecule.copy.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>
-
+          <programlisting>
+  ... --copy-molecule \
+      --position &quot;10,10,10&quot;
+   </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
+          position (10,10,10) in the domain with respect to the molecule&apos;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 xml:id='molecule.change-molname'>
-          <title xml:id='molecule.change-molname.title'>Change a molecules 
-          name</title>
-
+        <section xml:id="molecule.change-molname">
+          <title xml:id="molecule.change-molname.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>
-
+          <programlisting>... -change-molname &quot;test</programlisting>
           <para>This will change the name of the (only) selected molecule to
-          "test".</para>
-
+          &quot;test&quot;.</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>
-
+          <para>This will change the default name of new molecules to
+          &quot;test&quot;.</para>
           <note>
             <para>Note that a molecule loaded from file gets the filename
@@ -1300,96 +1030,63 @@
           </note>
         </section>
-
-        <section xml:id='molecule.remove-molecule'>
-          <title xml:id='molecule.remove-molecule.title'>Remove molecules
-	  </title>
-
+        <section xml:id="molecule.remove-molecule">
+          <title xml:id="molecule.remove-molecule.title">Remove molecules </title>
           <para>This removes one or multiple selected molecules.</para>
-
           <programlisting>... -remove-molecule</programlisting>
-
-          <para>This essentially just removes all of the molecules' atoms
+          <para>This essentially just removes all of the molecules&apos; atoms
           which in turn also causes the removal of the molecule.</para>
         </section>
-
-        <section xml:id='molecule.translate-molecules'>
-          <title xml:id='molecule.translate-molecules.title'>Translate molecules
-	  </title>
-
+        <section xml:id="molecule.translate-molecules">
+          <title xml:id="molecule.translate-molecules.title">Translate molecules </title>
           <para>This translates one or multiple selected molecules by a
-	  specific offset..</para>
-
+   specific offset..</para>
           <programlisting>... -translate-molecules</programlisting>
-
-          <para>This essentially translates all of the molecules' atoms.</para>
-        </section>
-
-        <section xml:id='molecule.rotate-around-self'>
-          <title xml:id='molecule.rotate-around-self.title'>Rotate around self
-          </title>
-
+          <para>As before, this is actually just an operation on all of the molecule&apos;s atoms, namely translating them.</para>
+        </section>
+        <section xml:id="molecule.rotate-around-self">
+          <title xml:id="molecule.rotate-around-self.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>
-
+          <programlisting>
+  ... --rotate-around-self &quot;90&quot; \
+      --axis &quot;0,0,1&quot;
+   </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 xml:id='molecule.rotate-around-origin'>
-          <title xml:id='molecule.rotate-around-origin.title'>Rotate around 
-          origin</title>
-
+          if the origin were at its wn center of origin.</para>
+        </section>
+        <section xml:id="molecule.rotate-around-origin">
+          <title xml:id="molecule.rotate-around-origin.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>
-
+          <programlisting>
+  ... --rotate-around-origin 90 \
+      --position &quot;0,0,1&quot;\
+   </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 xml:id='molecule.rotate-to-principal-axis-system'>
-          <title xml:id='molecule.rotate-to-principal-axis-system.title'>
-          Rotate to principal axis system</title>
-
+        <section xml:id="molecule.rotate-to-principal-axis-system">
+          <title xml:id="molecule.rotate-to-principal-axis-system.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
+          matches the molecules shape. The principal axis system can be
           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"
+          do as follows</para>
+          <programlisting>... --rotate-to-principal-axis-system &quot;0,0,1&quot;
           </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 xml:id='molecule.verlet-integration'>
-          <title xml:id='molecule.verlet-integration.title'>Perform verlet 
-          integration</title>
-
+          largest axis is aligned with the z axis. <remark>Note that &quot;0,0,-1&quot; would align anti-parallel.</remark></para>
+        </section>
+        <section xml:id="molecule.verlet-integration">
+          <title xml:id="molecule.verlet-integration.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 step. Velocity verlet is an often employed time
           integration algorithm in molecular dynamics simulations.</para>
-
-          <programlisting>
-		... --verlet-integration \
-		    --deltat 0.1 \
-		    --keep-fixed-CenterOfMass 0
-	  </programlisting>
-
+          <programlisting>
+  ... --verlet-integration \
+      --deltat 0.1 \
+      --keep-fixed-CenterOfMass 0
+   </programlisting>
           <para>This will integrate with a timestep of <inlineequation>
               <m:math display="inline">
@@ -1399,19 +1096,14 @@
           the sum over all atoms is zero.</para>
         </section>
-
-        <section xml:id='molecule.force-annealing'>
-          <title xml:id='molecule.force-annealing.title'>Anneal the atomic 
-          forces</title>
-
+        <section xml:id="molecule.force-annealing">
+          <title xml:id="molecule.force-annealing.title">Anneal the atomic forces</title>
           <para>This will shift the atoms in a such a way as to decrease (or
           anneal) the forces acting upon them.</para>
-
           <para>Forces may either be already present for the set of atoms by
           some other way (e.g. from a prior fragmentation calculation) or,
-          as shown here, from an external file. We anneal the forces for
+          as shown here, loaded from an external file. We anneal the forces for
           one step with a certain initial step width of 0.5 atomic time
           units and do not create a new timestep for each optimization
           step.</para>
-
           <programlisting>
           ... --force-annealing \
@@ -1422,19 +1114,14 @@
           </programlisting>
         </section>
-
-        <section xml:id='molecule.linear-interpolation-of-trajectories'>
-          <title xml:id='molecule.linear-interpolation-of-trajectories.title'>
-          Linear interpolation between configurations</title>
-
-          <para>This is similar to verlet-integration, only that it performs
+        <section xml:id="molecule.linear-interpolation-of-trajectories">
+          <title xml:id="molecule.linear-interpolation-of-trajectories.title"> Linear interpolation between configurations</title>
+          <para>This is similar to verlet integration, only that it performs
           a linear integration irrespective of the acting atomic forces.
           </para>
-
           <para>The following call will produce an interpolation between the
           configurations in time step 0 and time step 1 with 98 intermediate
           steps, i.e. current step 1 will end up in time step 99. In this
-          case an idential mapping is used to associated atoms in start and
+          case an identity mapping is used to associated atoms in start and
           end configuration.</para>
-
           <programlisting>
           ... --linear-interpolation-of-trajectories \
@@ -1446,101 +1133,71 @@
         </section>
       </section>
-
-      <section xml:id='domain'>
-        <title xml:id='domain.title'>Manipulate domain</title>
-
+      <section xml:id="domain">
+        <title xml:id="domain.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
+        domain, how to 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 xml:id='domain.change-box'>
-          <title xml:id='domain.change-box.title'>Changing the domain</title>
-
+        <section xml:id="domain.change-box">
+          <title xml:id="domain.change-box.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>
-
+          <programlisting>... change-box &quot;20,0,20,0,0,20&quot;</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 xml:id='domain.bound-in-box'>
-          <title xml:id='domain.bound-in-box.title'>Bound atoms inside box
-          </title>
-
+          specify it. We have to give the six components of the lower triangle           matrix. Here, we change the box to a cuboid of equal edge length of
+          20.<warning>
+              <para>In case of the python interface an upper triangle matrix is given. Hence, the above would read &quot;20,0,0,20,0,20&quot;.</para>
+            </warning></para>
+        </section>
+        <section xml:id="domain.bound-in-box">
+          <title xml:id="domain.bound-in-box.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 xml:id='domain.center-in-box'>
-          <title xml:id='domain.center-in-box.title'>Center atoms inside the 
-          domain</title>
-
+        <section xml:id="domain.center-in-box">
+          <title xml:id="domain.center-in-box.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 xml:id='domain.center-edge'>
-          <title xml:id='domain.center-edge.title'>Center the atoms at an 
-          edge</title>
-
+          <programlisting>... --center-in-box &quot;20,0,20,0,0,20&quot;</programlisting>
+        </section>
+        <section xml:id="domain.center-edge">
+          <title xml:id="domain.center-edge.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 xml:id='domain.add-empty-boundary'>
-          <title xml:id='domain.add-empty-boundary.title'>Extending the 
-          boundary by adding an empty boundary</title>
-
+        <section xml:id="domain.add-empty-boundary">
+          <title xml:id="domain.add-empty-boundary.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>
-
+          thickness. This applies to either side, i.e. left and right, top and bottom, front and back.</para>
+          <programlisting>... --add-empty-boundary &quot;5,5,5&quot;</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 xml:id='domain.scale-box'>
-          <title xml:id='domain.scale-box.title'>Scaling the box</title>
-
+        <section xml:id="domain.scale-box">
+          <title xml:id="domain.scale-box.title">Scaling the box</title>
           <para>You can enlarge the domain by simple scaling factors.</para>
-
-          <programlisting>... --scale-box "1,1,2.5"</programlisting>
-
+          <programlisting>... --scale-box &quot;1,1,2.5&quot;</programlisting>
           <para>Here, the domain is stretched in the z direction by a factor
           of 2.5.</para>
         </section>
-
-        <section xml:id='domain.repeat-box'>
-          <title xml:id='domain.repeat-box.title'>Repeating the box</title>
-
+        <section xml:id="domain.repeat-box">
+          <title xml:id="domain.repeat-box.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
+          periodic cell is stored. E.g. for a crystallic system this minimal cell is all that&apos;s needed to completely specify a larger body. 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>
-
+          <programlisting>... --repeat-box &quot;1,2,2&quot;</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
@@ -1548,9 +1205,6 @@
           them.</para>
         </section>
-        
-        <section xml:id='domain.set-boundary-conditions'>
-          <title xml:id='domain.set-boundary-conditions.title'>Change the 
-          boundary conditions</title>
-
+        <section xml:id="domain.set-boundary-conditions">
+          <title xml:id="domain.set-boundary-conditions.title">Change the boundary conditions</title>
           <para>Various boundary conditions can be applied that affect how
           certain Actions work, e.g. translate-atoms. We briefly give a list
@@ -1572,170 +1226,132 @@
             </listitem>
           </itemizedlist>
-          
           <para>The following will set the boundary conditions to periodic.
           </para>
-
-          <programlisting>... --set-boundary-conditions "Wrap Wrap Wrap"
-          </programlisting>
-        </section>
-      </section>
-
-      <section xml:id='filling'>
-        <title xml:id='filling.title'>Filling</title>
-        
-          <para>Filling a specific part of the domain with one type of
+          <programlisting>... --set-boundary-conditions &quot;Wrap Wrap Wrap&quot;</programlisting>
+          <para>Note that boundary conditions are not enforced unless explicitly requested, e.g. by the <emphasis role="bold">bound-in-box</emphasis> action</para>
+        </section>
+      </section>
+      <section xml:id="filling">
+        <title xml:id="filling.title">Filling</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 of a molecule (see copy-molecule) and we need several 
+          copying of a molecule (see <emphasis role="bold">copy-molecule</emphasis>) and for this we need several 
           ingredients.</para>
-
-          <para>First, we need to specify the part of the domain. This is done
+        <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 three types of filling, domain, volume, and 
+        <para>Then, there are three types of filling: domain, volume, and 
           surface. The domain is filled with a regular grid of fill-in points.
           A volume and a surface are filled by a set of equidistant points
           distributed within the volume or on the surface of a selected
-          shape. Molecules will then 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
+          shape. The latter is closed connected to the respective shape selected. Molecules will then be copied and translated points when they
+          &quot;fit&quot;. Note that not only primitive shape can be used for filling in molecules inside their volume or on their surface but also any kind of combined shape. </para>
+        <remark>Note however that not all combinations may already be fully working.</remark>
+        <para>The filler procedure checks each fill-in point whether there
+          is enough space for the set of atoms. To this end, we require a cluster
+          instead of a molecule. A cluster is more general than a molecule as it is not restricted to a connected subgraph with respect to the bond graph. A cluster 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
+          its minimal volume. I.e. we need such a 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
+          automatically by which it is checked whether sufficient space is available at the fill-in point.</para>
+        <para>On top of that, molecules can be selected whose volume is
           additionally excluded from the filling region.</para>
-
-        <section xml:id='filling.fill-regular-grid'>
-          <title xml:id='filling.fill-regular-grid.title'>Fill the domain with 
-          molecules</title>
-
+        <section xml:id="filling.fill-regular-grid">
+          <title xml:id="filling.fill-regular-grid.title">Fill the domain with molecules</title>
           <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
+          <programlisting>
+  ... --fill-regular-grid \
+      --mesh-size &quot;5,5,5&quot; \
+      --mesh-offset &quot;.5,.5,.5&quot; \
+      --DoRotate 1 \
+      --min-distance 1. \
+      --random-atom-displacement 0.05 \
+      --random-molecule-displacement 0.4 \
+      --tesselation-radius 2.5
+   </programlisting>
+          <para>This generates a cardinal grid of 5x5x5 fill-in points within the
+          sphere that are offset such as to lie centered within the sphere, defined by a relative offset per axis in [0,1]. Hence, with an offset of &quot;0&quot; we have the points left-aligned, with &quot;0.5&quot; centered, and with &quot;1&quot; right-aligned. Additionally, each molecule is rotated
+          by a random rotation matrix, each atom is translated randomly by at
+          most 0.05, each molecule&apos;s center similarly but at most by 0.4. The selected
+          molecules&apos; 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="randomization">Randomization</link>for details on 
-          changing the randomness.</para>
-        </section>
-
-        <section xml:id='filling.fill-volume'>
-          <title xml:id='filling.fill-volume.title'>Fill a shape's volume 
-          with molecules</title>
-          
+          changing the randomness and obtaining some extra flexibility thereby.</para>
+        </section>
+        <section xml:id="filling.fill-volume">
+          <title xml:id="filling.fill-volume.title">Fill a shape&apos;s volume with molecules</title>
           <para>More specifically than filling the whole domain with molecules,
           maybe except areas where other molecules already are, we also can
           fill only specific parts by selecting a shape and calling upon
           the following action:</para>
-
-          <programlisting>
-		... --fill-volume \
-		    --counts 12 \
-		    --min-distance 1. \
-		    --DoRotate 1 \
-		    --random-atom-displacement 0.05 \
-		    --random-molecule-displacement 0.4 \
-		    --tesselation-radius 2.5
-	  </programlisting>
-        </section>
-          
-        <section xml:id='filling.fill-surface'>
-          <title xml:id='filling.fill-surface.title'>Fill a shape's surface 
-          with molecules</title>
-
-		  <para>Filling a surface is very similar to filling its volume.
-		  Again the number of equidistant points has to be specified.
-		  However, randomness is constrained as the molecule is be aligned
-		  with the surface in a specific manner. The alignment axis refers
-		  to the largest principal axis of the filler molecule and will
-		  be aligned parallel to the surface normal at the fill-in point.
-		  </para>
-
-		  <para>The call below fill in 12 points with a minimum distance
-		  between the instances of 1 angstroem. We allow for certain random
-		  displacements and use the z-axis for aligning the molecules on
-		  the surface.</para>
-
-          <programlisting>
-		... --fill-surface \
-		    --counts 12 \
-		    --min-distance 1. \
-		    --DoRotate 1 \
-		    --random-atom-displacement 0.05 \
-		    --random-molecule-displacement 0.4 \
-		    --Alignment-Axis "0,0,1"
-	  </programlisting>
-        </section>
-
-        <section xml:id='filling.suspend-in-molecule'>
-          <title xml:id='filling.suspend-in-molecule.title'>Suspend in molecule
-          </title>
-
+          <programlisting>
+  ... --fill-volume \
+      --counts 12 \
+      --min-distance 1. \
+      --DoRotate 1 \
+      --random-atom-displacement 0.05 \
+      --random-molecule-displacement 0.4 \
+      --tesselation-radius 2.5
+   </programlisting>
+          <para>The specified option all have the same function as before. Here, we specified to generate 12 points inside the volume of the selected shape.</para>
+        </section>
+        <section xml:id="filling.fill-surface">
+          <title xml:id="filling.fill-surface.title">Fill a shape&apos;s surface with molecules</title>
+          <para>Filling a surface is very similar to filling its volume.
+    Again the number of equidistant points has to be specified.
+    However, randomness is constrained as the molecule has to be aligned
+    with the surface in a specific manner. The idea is to have the molecules point away from the surface in a similar way. This is done by aligning an axis with the surface normal. The alignment axis refers
+    to the largest principal axis of the filler molecule and will
+    be aligned parallel to the surface normal at the fill-in point.
+This is the same syntax as with <emphasis role="bold">rotate-around-self</emphasis>.   </para>
+          <para>The call below will fill in 12 points with a minimum distance
+    between the instances of 1 angstroem. We allow for certain random
+    displacements and use the z-axis for aligning the molecules on
+    the surface.</para>
+          <programlisting>
+  ... --fill-surface \
+      --counts 12 \
+      --min-distance 1. \
+      --DoRotate 1 \
+      --random-atom-displacement 0.05 \
+      --random-molecule-displacement 0.4 \
+      --Alignment-Axis &quot;0,0,1&quot;
+   </programlisting>
+        </section>
+        <section xml:id="filling.suspend-in-molecule">
+          <title xml:id="filling.suspend-in-molecule.title">Suspend in molecule </title>
           <para>Add a given molecule in the simulation domain in such a way
           that the total density is as desired.</para>
-
-          <programlisting>
-		... --suspend-in-molecule 1.
-	      </programlisting>
-        </section>
-
-        <section xml:id='filling.fill-molecule'>
-          <title xml:id='filling.fill-molecule.title'>Fill in molecule</title>
-
+          <programlisting>
+  ... --suspend-in-molecule 1.
+       </programlisting>
+        </section>
+        <section xml:id="filling.fill-molecule">
+          <title xml:id="filling.fill-molecule.title">Fill in molecule</title>
           <para>This action will be soon be removed.</para>
-
-          <programlisting>
-		... --fill-molecule
-	      </programlisting>
-        </section>
-
-        <section xml:id='filling.fill-void'>
-          <title xml:id='filling.fill-void.title'>Fill void with molecule
-          </title>
-
+          <programlisting>
+  ... --fill-molecule
+       </programlisting>
+        </section>
+        <section xml:id="filling.fill-void">
+          <title xml:id="filling.fill-void.title">Fill void with molecule </title>
           <para>This action will be soon be removed.</para>
-
-          <programlisting>
-		... --fill-void
-	      </programlisting>
-        </section>
-      </section>
-
-      <section xml:id='analysis'>
-        <title xml:id='analysis.title'>Analysis</title>
-
-		<para></para>
-
-        <section xml:id='analysis.pair-correlation'>
-          <title xml:id='analysis.pair-correlation.title'>Pair Correlation
-          </title>
-          
-          <para>Pair correlation checks for two given elements on the typical 
-          distance they can be found with respect to one another. E.g. for 
+          <programlisting>
+  ... --fill-void
+       </programlisting>
+        </section>
+      </section>
+      <section xml:id="analysis">
+        <title xml:id="analysis.title">Analysis</title>
+        <para>If atoms are manipulated and molecules are filled in, it is also a good idea to check on the manner of the filling. This can be done by for example looking at the pair correlation or angular correlation function. This may be useful in checking what is the mean distance between water molecules and how they are aligned with respect to each other.</para>
+        <section xml:id="analysis.pair-correlation">
+          <title xml:id="analysis.pair-correlation.title">Pair Correlation </title>
+          <para>For two given elements Pair correlation checks on the typical 
+          distance in which they can be found with respect to one another. E.g. for 
           water one might be interested what is the typical distance for
           hydrogen and oxygen atoms.</para>
-
           <programlisting>
           ... --pair-correlation \
@@ -1748,15 +1364,11 @@
               --periodic 0
           </programlisting>
-          
           <para>This will compile a histogram for the interval [0,10] in steps
           of 0.7 and increment a specific bin if the distance of one such pair
           of a hydrogen and an oxygen atom can be found within its distance
-          interval.</para>
-        </section>
-
-        <section xml:id='analysis.dipole-correlation'>
-          <title xml:id='analysis.dipole-correlation.title'>Dipole Correlation
-          </title>
-          
+          interval. These data files can be used for plotting the distribution right away in order to check on the correlation between the elements.</para>
+        </section>
+        <section xml:id="analysis.dipole-correlation">
+          <title xml:id="analysis.dipole-correlation.title">Dipole Correlation </title>
           <para>The dipole correlation is similar to the pair correlation, only
           that it correlates the orientation of dipoles in the molecular
@@ -1764,5 +1376,4 @@
           <para>Note that the dipole correlation works on the currently 
           selected molecules, e.g. all water molecules if so selected.</para>
-
           <programlisting>
           ... --dipole-correlation \
@@ -1774,10 +1385,8 @@
               --periodic 0
           </programlisting>
-        </section>
-
-        <section xml:id='analysis.dipole-angular-correlation'>
-          <title xml:id='analysis.dipole-angular-correlation.title'>Dipole 
-          Angular Correlation</title>
-          
+          <para>Hence, instead of calculating a function of the distance in [0,infinity), it calculates the angular histogram in [0,2pi).</para>
+        </section>
+        <section xml:id="analysis.dipole-angular-correlation">
+          <title xml:id="analysis.dipole-angular-correlation.title">Dipole Angular Correlation</title>
           <para>The dipole angular correlation looks at the angles of a
           dipole over time. It takes the orientation of a certain time step
@@ -1790,5 +1399,4 @@
           might change.
           </para>
-
           <programlisting>
           ... --dipole-angular-correlation H2O \
@@ -1802,17 +1410,13 @@
           </programlisting>
         </section>
-
-        <section xml:id='analysis.point-correlation'>
-          <title xml:id='analysis.point-correlation.title'>Point Correlation
-          </title>
-          
+        <section xml:id="analysis.point-correlation">
+          <title xml:id="analysis.point-correlation.title">Point Correlation </title>
           <para>Point correlation is very similar to pair correlation, only
           that it correlates not positions of atoms among one another but
           against a fixed, given point.</para>
-
           <programlisting>
           ... --point-correlation \
               --elements 1 8 \
-              --position "0,0,0" \
+              --position &quot;0,0,0&quot; \
               --bin-start 0 \
               --bin-width 0.7 \
@@ -1822,16 +1426,11 @@
               --periodic 0
           </programlisting>
-          
           <para>This would calculate the correlation of all hydrogen and
           oxygen atoms with respect to the origin.</para>
         </section>
-
-        <section xml:id='analysis.surface-correlation'>
-          <title xml:id='analysis.surface-correlation.title'>Surface 
-          Correlation</title>
-          
+        <section xml:id="analysis.surface-correlation">
+          <title xml:id="analysis.surface-correlation.title">Surface Correlation</title>
           <para>The surface correlation calculates the distance of a set
           of atoms with respect to a tesselated surface.</para>
-
           <programlisting>
           ... --surface-correlation \
@@ -1845,44 +1444,32 @@
           </programlisting>
         </section>
-
-        <section xml:id='analysis.molecular-volume'>
-          <title xml:id='analysis.molecular-volume.title'>Molecular Volume
-          </title>
-          
+        <section xml:id="analysis.molecular-volume">
+          <title xml:id="analysis.molecular-volume.title">Molecular Volume </title>
           <para>This simply calculates the volume that a selected molecule
           occupies. For this the molecular surface is determined via a
-          tesselation. Note that this surface is minimal is that aspect
+(convex)           tesselation of its surface. Note that this surface is minimal is that aspect
           that each node of the tesselation consists of an atom of the
           molecule.</para>
-
           <programlisting>... --molecular-volume</programlisting>
         </section>
-
-        <section xml:id='analysis.average-molecule-force'>
-          <title xml:id='analysis.average-molecule-forcetitle'>Average force
-          acting on a molecule</title>
-          
+        <section xml:id="analysis.average-molecule-force">
+          <title xml:id="analysis.average-molecule-forcetitle">Average force acting on a molecule</title>
           <para>This sums up all the forces of each atom of a currently 
           selected molecule and returns the average force vector. This should
           give you the general direction of acceleration of the molecule.
           </para>
-
           <programlisting>... --molecular-volume</programlisting>
         </section>
-
-      </section>
-
-      <section xml:id='fragmentation'>
-        <title xml:id='fragmentation.title'>Fragmentation</title>
-
+      </section>
+      <section xml:id="fragmentation">
+        <title xml:id="fragmentation.title">Fragmentation</title>
         <para>Fragmentation refers to a so-called linear-scaling method called
-        "Bond-Order diSSection in an ANOVA-like fashion" (BOSSANOVA),
+        &quot;Bond-Order diSSection in an ANOVA-like fashion&quot; (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
+        number of vertices, namely a fixed number of 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
@@ -1891,5 +1478,4 @@
         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
@@ -1902,13 +1488,11 @@
               <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
+          </inlineequation>. In general, this cost is prohibitive for calculating ground state energies and forces (required for molecular dynamics simulations) for larger molecules such as bio proteins. By fragmenting the molecular system and looking at fragments of fixed size, calculating the ground state energy of a
+        number of fragment molecules becomes a linear scaling operation with the number of atoms. 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
+        <para>Long-range interactions (e.g. Coulomb or van-der-Waals interactions) are artificially truncated, however,
+        with this fragmentation 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
@@ -1916,6 +1500,6 @@
         <productname>vmg</productname> by Julian Iseringhausen that is
         contained in the <link xlink:href="http://www.scafacos.org/">
-        <productname>ScaFaCoS</productname></link>.</para>
-
+            <productname>ScaFaCoS</productname>
+          </link>. This enhancement is currently implemented via another program package named <productname>JobMarket</productname> that is at the moment not available publicly (contact the author Frederik Heber if interested).</para>
         <para>Note that we treat hydrogen special (but can be switched off) as
         fragments are calculated as closed shell (total spin equals zero).
@@ -1923,26 +1507,23 @@
         bonds are cut when fragmenting a molecule (this, too, can be switched
         off).</para>
-
-        <section xml:id='fragmentation.fragment-molecule'>
-          <title xml:id='fragmentation.fragment-molecule.title'>Fragmenting a 
-          molecular system</title>
-
+        <para>Eventually, the goal of fragmentation is to yield an energy and gradients with respect to nuclear positions per atom for each fragment. These forces can be used for molecular dynamics simulations, for structure optimization or for fitting empirical potential functions. The underlying operation consists of three parts. The first part is always the act of splitting up the selected atoms in the molecular system into fragments. The energies of the fragments are calculated in the second part via an external ab-initio solver, where the actual solver used is arbitrary and to some extent up to the user (<productname>MPQC </productname> is used by default). The second part of the fragmentation is to combine fragment results to energy and gradients for the total molecular system.</para>
+        <para>Note that the molecular system itself is not touched in any way by this fragmentation. </para>
+        <section xml:id="fragmentation.fragment-molecule">
+          <title xml:id="fragmentation.fragment-molecule.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>
-
+          <programlisting>
+  ... --fragment-molecule &quot;BondFragment&quot; \
+      --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
+          the vertex/atom indices per fragment and so on. These files are used when re-performing the fragmentation on a slightly modified state (e.g. after a time integration step with essentially the same bond graph) for faster operation. These files all need
+          a common prefix, here &quot;BondFragment&quot;. 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,
@@ -1955,5 +1536,5 @@
               </m:math>
             </inlineequation>) in systems with many interconnected aromatic
-          rings, such as graphene. Next, we give a distance cutoff of 3 used
+          rings, such as graphene. Next, we give a distance cutoff of 3 angstroem 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
@@ -1962,5 +1543,5 @@
           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
+          Poisson equation with a multigrid solver -- however, this requires the <productname>JobMarket</productname> package. As input the solver
           requires the density which is sampled on a cartesian grid whose
           resolution these parameter defines (<inlineequation>
@@ -1970,10 +1551,9 @@
             </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
+          configuration (prefix is &quot;BondFragment&quot;, 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="fileparsers">Parsers</link> above 
-          on how to change the parameters of the ab-initio calculation.</para>
-
+          discussion of the <link linkend="fileparsers">Parsers</link>  
+          on how to change the parameters of the ab-initio calculation. That is to the extent implemented in Molecuilder the created configuration files for the specific solver are manipulated with the options also manipulating the state file written on program exit.</para>
           <para>After having written all fragment configuration files, you
           need to calculate each fragment, grab the resulting energy (and
@@ -1983,11 +1563,8 @@
           on.</para>
         </section>
-
-        <section xml:id='fragmentation.fragment-automation'>
-          <title xml:id='fragmentation.fragment-automation.title'>Calculating 
-          fragment energies automatically</title>
-
+        <section xml:id="fragmentation.fragment-automation">
+          <title xml:id="fragmentation.fragment-automation.title">Calculating fragment energies automatically</title>
           <para>Another way of doing this is enabled if you have
-          <productname>JobMarket</productname> package. JobMarket implements a
+the           <productname>JobMarket</productname> package. Initially, the package was required but now it is only recommended as then calculations can be performed in parallel or arbitrarily many cores (and also the long-range calculation are only available then). 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),
@@ -1996,29 +1573,23 @@
           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.
+          calculation a number of values, likewise 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
+          from MoleCuilder once they are done. This essentially describes 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="fragmentation.fragment-molecule">Fragmenting a molecule
-          </link>.</para>
-
-          <programlisting>
-		... --parse-fragment-jobs \
-		    --fragment-jobs "BondFragment00.in" "BondFragment01.in" \
-		    --fragment-path "./" \
-		    --grid-level 5
-	  </programlisting>
-
+          the effect of having output-types specified in <link linkend="fragmentation.fragment-molecule">Fragmenting a molecule </link>.</para>
+          <programlisting>
+  ... --parse-fragment-jobs \
+      --fragment-jobs &quot;BondFragment00.in&quot; &quot;BondFragment01.in&quot; \
+      --fragment-path &quot;./&quot; \
+      --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
+          &quot;./&quot;, 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
@@ -2026,27 +1597,23 @@
           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
+          <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&apos;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
+          a client to JobMarket&apos;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
@@ -2054,9 +1621,8 @@
             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
+          grid, i.e. not core electrons and the nuclei charges are reduced
+suitably. 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
@@ -2065,25 +1631,19 @@
           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 xml:id='fragmentation.analyse-fragment-results'>
-          <title xml:id='fragmentation.analyse-fragment-results.title'>
-          Analyse fragment results</title>
-
+          JobMarket server, namely it address and its port. If the JobMarket package is not available, then these option values cannot be given. Instead the solver is called internally on the same machine and one fragment energy is calculated after the other.</para>
+        </section>
+        <section xml:id="fragmentation.analyse-fragment-results">
+          <title xml:id="fragmentation.analyse-fragment-results.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>
-
+          <programlisting>
+  ... --analyse-fragment-results \
+      --fragment-prefix &quot;BondFragment&quot; \
+      --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
@@ -2092,8 +1652,7 @@
           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
+          even gigabytes as currently the densities are stored on the full cartesian grid). 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 
@@ -2101,14 +1660,6 @@
           is possible afterwards.</para>
         </section>
-        
-        <section xml:id='fragmentation.store-saturated-fragment'>
-          <title xml:id='fragmentation.store-saturated-fragment.title'>Store 
-          a saturated fragment</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>
-
+        <section xml:id="fragmentation.store-saturated-fragment">
+          <title xml:id="fragmentation.store-saturated-fragment.title">Store a saturated fragment</title>
           <para>This will store the currently selected atoms as a fragment
           where all dangling bonds (by atoms that are connected in the bond
@@ -2116,30 +1667,25 @@
           additional hydrogen atoms. The output formats are set to just xyz.
           </para>
-
-          <programlisting>
-		... --store-saturated-fragment \
-		    --DoSaturate 1 \
-		    --output-types xyz
-	      </programlisting>
-        </section>
-      </section>
-
-      <section xml:id='homology'>
-        <title xml:id='homology.title'>Homologies</title>
-
+          <programlisting>
+  ... --store-saturated-fragment \
+      --DoSaturate 1 \
+      --output-types xyz
+       </programlisting>
+        </section>
+      </section>
+      <section xml:id="homology">
+        <title xml:id="homology.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
+        to do with the results? The forces can be used for time integration and structure optimization but what about
         the energies? The energy value is basically the function evaluation of
-        the Born-Oppenheimer surface. For molecular dynamics simulations
+        the Born-Oppenheimer surface of the molecular system. For molecular dynamics simulations
         continuous ab-initio calculations to evaluate the Born-Oppenheimer
-        surface is not feasible. Instead usually empirical potential functions
+        surface, especially the gradient at the current position of the molecular system&apos;s configuration, 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
+        <para>One frequently employed method is the many-body expansion of said surface
+        which is basically nothing else than the fragmentation 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
@@ -2148,65 +1694,50 @@
         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
+        regression procedure. That is, we want to tune the parameters 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
+        the same function evaluation as the ab-initio calculation did using 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
+        <para>Homologies -- in the sense used here -- 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>
-
+        varying nuclear coordinates of the same fragment, i.e. same atoms with identical bonding).</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
+        <filename>homologies.dat</filename> and <emphasis role="italic">appends</emphasis> them to the homology
         container.</para>
-
         <programlisting>... --save-homologies homologies.dat</programlisting>
-
         <para>Complementary, this stores the current contents of the homology
-        container, overwriting the file
+        container, <emphasis role="italic">overwriting</emphasis> the file
         <filename>homologies.dat</filename>.</para>
       </section>
-
-      <section xml:id='potentials'>
-        <title xml:id='potentials.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
+      <section xml:id="potentials">
+        <title xml:id="potentials.title">Potentials</title>
+        <para>In much the same manner as we asked before: what are homology
+        files or containers good for? However, taking into account what we have just explained, it
         should be clear: We fit potential function to these function
-        evaluation of terms of the many-body expansion of the Born-Oppenheimer
+        evaluations of terms of the many-body expansion of the Born-Oppenheimer
         surface of the full system.</para>
-
-        <section xml:id='potentials.fit-potential'>
-          <title xml:id='potentials.fit-potential.title'>Fitting empirical 
-          potentials</title>
-
-          <para>Let's take a look at an exemplary call to the fit potential
+        <section xml:id="potentials.fit-potential">
+          <title xml:id="potentials.fit-potential.title">Fitting empirical potentials</title>
+          <para>Let&apos;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>
-
+          <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
+          molecules, consisting of a single oxygen (8) and two hydrogen atoms (1).
+          Next, we specify the chemical element type of the potential, here a potential between oxygen (8) and hydrogen (1). 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
+          or two nuclear coordinates and the distance taken between the two. Finally, we state that the non-linear regression should be
+          done with five random starting positions, i.e. five individual minimizations, and the set of parameters
           with the smallest L2 norm wins.</para>
-
           <note>
             <para>Due to translational and rotational degrees of freedom for
@@ -2215,45 +1746,37 @@
             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
+            angular potential and the then required three charges/elements, &quot;8 1 1&quot;, 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>
+            a fragment of order 1, e.g. a single hydrogen atom. Essentially, this captures the atomic energy that is not associated to any bonding interactions.</para>
           </note>
         </section>
-
-        <section xml:id='potentials.fit-compound-potential'>
-          <title xml:id='potentials.fit-compound-potential.title'>Fitting
-          many empirical potentials simultaneously</title>
-
-
+        <section xml:id="potentials.fit-compound-potential">
+          <title xml:id="potentials.fit-compound-potential.title">Fitting many empirical potentials simultaneously</title>
           <para>Another way is using a file containing a specific set of
           potential functions, possibly even with initial values.</para>
-
-          <programlisting>
-		... --fit-compound-potential \
-		    --fragment-charges 8 1 1 \
-		    --potential-file water.potentials \
-		    --set-threshold 1e-3 \
-		    --training-file test.dat
-	  </programlisting>
-
+          <programlisting>
+  ... --fit-compound-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
+          These are now fitted simultaneously. For example, let&apos;s say 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 the angle between hydrogen, oxygen, and hydrogen atom. Then, we would
+          fit a function consisting of the sum of the two potentials functions in order to approximate the energy of a single
+          water molecule (actually, it&apos;s the sum of three potentials. As mentioned before, a constant potential is always added to compensate non-bonding energies, i.e. not depending on interatomic distances). Here, the threshold criterion takes the place of the
+<emphasis role="bold"> take-best-of</emphasis> option. Here, the minimization is reiterated so often on random (but to some extent chosen from a sensible range) starting parameters until the final L2 error is 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>
-
+          <filename>test.dat</filename>. This allows for graphical representation or other
+way of analysis, e.g. for a Morse potential between oxygen and hydrogen the bonding energy can be plotted as a one-dimensional function and compared to the &quot;point cloud&quot; of sample points from the fragment term of Born-Oppenheimer surface. It is this point cloud, i.e. the training data, that is written to the file
+          <filename>test.dat</filename>.</para>
           <para>Note that you can combine the two ways, i.e. start with a
           fit-potential call but give an empty potential file. The resulting
@@ -2263,69 +1786,47 @@
           with this file.</para>
         </section>
-
-	
-        <section xml:id='potentials.parse-potential'>
-          <title xml:id='potentials.parse-potential.title'>Parsing an
-          empirical potentials file</title>
-
-          <para>Responsible for the compound potential is every potential
+        <section xml:id="potentials.parse-potential">
+          <title xml:id="potentials.parse-potential.title">Parsing an empirical potentials file</title>
+          <para>Taking part in the compound potential is every potential
           function whose signature matches with the designated fragment-charges
-          and who is currently known to an internal instance called the
-          PotentialRegistry.</para>
-
-          <para>More potentials can be registered (fit-potential will also
+          and who is currently known to MoleCuilder.</para>
+          <para>More potentials can be registered (<emphasis role="bold">fit-potential</emphasis> will also
           register the potential it fits) by parsing them from a file.</para>
-
-          <programlisting>
-		... --parse-potentials water.potentials
-	  </programlisting>
-
-          <note>Currently, only <productname>TREMOLO</productname> potential
-          files are understood and can be parsed.</note>
-        </section>
-
-        <section xml:id='potentials.save-potential'>
-          <title xml:id='potentials.save-potential.title'>Saving an
-          empirical potentials file</title>
-
-          <para>The opposite to parse-potentials is save-potentials that writes
-          every potential currently known to the PotentialRegistry to the given
+          <programlisting>
+  ... --parse-potentials water.potentials
+   </programlisting>
+          <note>Currently, only <productname>TREMOLO</productname>potential files are understood and can be parsed.</note>
+        </section>
+        <section xml:id="potentials.save-potential">
+          <title xml:id="potentials.save-potential.title">Saving an empirical potentials file</title>
+          <para>The opposite to <emphasis role="bold">parse-potentials</emphasis> is to save all currently registered potential functions to the given
           file along with the currently fitted parameters</para>
-
-          <programlisting>
-		... --save-potentials water.potentials
-	  </programlisting>
-
-          <note>Again, only the <productname>TREMOLO</productname> potential
-          format is understood currently and is written.</note>
-        </section>
-
-        <section xml:id='potentials.fit-particle-charges'>
-          <title xml:id='potentials.fit-particle-charges.title'>Fitting 
-          particle charges</title>
-
+          <programlisting>
+  ... --save-potentials water.potentials
+   </programlisting>
+          <note>Again, only the <productname>TREMOLO</productname>potential format is understood currently and is written.</note>
+        </section>
+        <section xml:id="potentials.fit-particle-charges">
+          <title xml:id="potentials.fit-particle-charges.title">Fitting particle 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
+          behavior in the molecular fragment, namely the (covalently) bonded interaction.
+          In order to model the Coulomb long-range interaction as well without solving
           for the electronic ground state in each time step, particle 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">Fragmentation
-          </link>) must have been given. With these sampled charge density and 
+          <para>Note that so far the placement of partial charges is restricted to the position of nuclei in the molecular system. There are more complex ways of placing partial charges, e.g. as employed in higher TIP water molecules, that also use anti-bonding potentials. This is so far not implemented.</para>
+          <para>To allow least-squares regression of these partial charges, we
+          need the results of long-range calculations and the <emphasis role="bold">store-grids</emphasis>
+          option (see above under <link linkend="fragmentation">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-particle-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
+          <programlisting>
+  ... --fit-particle-charges \
+      --fragment-charges 8 1 1 \
+      --potential-file water.potentials \
+      --radius 0.2
+   </programlisting>
+          <para>This will again use a water molecule as homologous fragment
+          &quot;key&quot; to request all configurations of this type from the homologies container. Results are
           stored in <filename>water.potentials</filename>. The radius is used
           to mark the region directly around the nuclei from the fit
@@ -2336,66 +1837,59 @@
         </section>
       </section>
-
-      <section xml:id='dynamics'>
-        <title xml:id='dynamics.title'>Dynamics</title>
-
-        <para>For fitting potentials or charges we need many homologuous but
+      <section xml:id="dynamics">
+        <title xml:id="dynamics.title">Dynamics</title>
+        <para>For fitting potentials or charges we need many homologous but
         different fragments, i.e. atoms with slightly different positions.
         How can we generate these?</para>
-
         <para>One possibility is to use molecular dynamics. With the 
         aforementioned fragmentation scheme we can quickly calculate not only 
         energies but also forces if the chosen solver, such as 
-        <link xlink:href="http://www.mpqc.org/"><productname>MPQC
-        </productname></link>, supports it. Integrating these forces 
+        <link xlink:href="http://www.mpqc.org/">
+            <productname>MPQC </productname>
+          </link>, supports it. Integrating these forces 
         discretely over time  gives insight into vibrational features of a 
-        molecular system and allows to generate those positions for fitting 
+        molecular system close to the equilibrium and allows to generate those positions for fitting 
         potentials that describe these vibrations.</para>
-
-        <section xml:id='dynamics.molecular-dynamics'>
-          <title xml:id='dynamics.molecular-dynamics.title'>Molecular dynamics
-          </title>
-
+        <section xml:id="dynamics.molecular-dynamics">
+          <title xml:id="dynamics.molecular-dynamics.title">Molecular dynamics </title>
           <para>The molecular dynamics action is a so-called macro Action, 
           i.e. it combines several other Actions into one, namely:</para>
-		  <itemizedlist>
+          <itemizedlist>
             <listitem>
-              <para>--verlet-integration</para>
+              <para>--<emphasis role="bold">verlet-integration</emphasis></para>
             </listitem>
             <listitem>
-              <para>--output</para>
+              <para>--<emphasis role="bold">output</emphasis></para>
             </listitem>
             <listitem>
-              <para>--clear-fragment-results</para>
+              <para>--<emphasis role="bold">clear-fragment-results</emphasis></para>
             </listitem>
             <listitem>
-              <para>--destroy-adjacency</para>
+              <para>--<emphasis role="bold">destroy-adjacency</emphasis></para>
             </listitem>
             <listitem>
-              <para>--create-adjacency</para>
+              <para>--<emphasis role="bold">create-adjacency</emphasis></para>
             </listitem>
             <listitem>
-              <para>--update-molecules</para>
+              <para>--<emphasis role="bold">update-molecules</emphasis></para>
             </listitem>
             <listitem>
-              <para>--fragment-molecule</para>
+              <para>--<emphasis role="bold">fragment-molecule</emphasis></para>
             </listitem>
             <listitem>
-              <para>--fragment-automation</para>
+              <para>--<emphasis role="bold">fragment-automation</emphasis></para>
             </listitem>
             <listitem>
-              <para>--analyse-fragment-results</para>
+              <para>--<emphasis role="bold">analyse-fragment-results</emphasis></para>
             </listitem>
-		  </itemizedlist>
-		  
-		  <para>The following will perform a molecular dynamics simulation
-		  for 100 time steps, each time step combining 0.5 atomic time units,
-		  i.e. 1.2 1e-17 s. The other options listed below will seem familiar
-		  to you if you have read about the other Actions listed above. Below
-		  we will not keep the bondgraph, i.e bonds and molecules may change
-		  over the simulation and hence also the created fragments per time
-		  step.
-		  </para>
-
+          </itemizedlist>
+          <para>The following command will perform a molecular dynamics simulation
+    for 100 time steps, each time step continuing over <emphasis role="bold">deltat</emphasis> equal to 0.5 atomic time units,
+    i.e. 1.2e-17 s. Some of the other options listed below, such as <emphasis role="bold">order</emphasis>, <emphasis role="bold">distance</emphasis>, or <emphasis role="bold">fragment-executable</emphasis>, will seem familiar
+    to you if you have read in this guide about the fragmentation actions. Look at the list above to see that they are a part of the makro action that performs molecular dynamics simulations. Below
+    we will not keep the bond graph, i.e bonds and molecules may change
+    over the simulation and hence also the created fragments per time
+    step.
+Furthermore, the forces are corrected such that the force add up to zero.    </para>
           <programlisting>
           ... --molecular-dynamics \
@@ -2408,20 +1902,17 @@
           --fragment-executable mpqc \
           </programlisting>
-        </section>
-
-        <section xml:id='dynamics.optimize-structure'>
-          <title xml:id='dynamics.optimize-structure.title'>Structure 
-          optimization</title>
-
-		  <para>Structure optimization is also a macro Action, it basically
-		  combines the same Actions as molecular-dynamics does. However, it
-		  uses force-annealing instead of verlet-integration.</para>
-
-		  <para>The following performs a structure optimization of the 
-		  currently selected atoms (may also be a subset) for up to 100 time
-		  steps, where each time step ist 0.5 atomic time units. The time
-		  step here is the initial step with for annealing.
-		  </para>
-
+          <para>Keeping the bond graph is useful when simulating close to the equilibrium and no bond breaking or forming should occur. Note that in general the BOSSANOVA fragmentation scheme is discontinuous with respect to the formation of bonds in the energy. This discontinuity arrises because of the threshold criterion used for detecting the bond graph. After each simulation step the bond graph is recreated (if <emphasis role="bold">keep-bondgraph</emphasis> is switched off) to accomodate for any structural changes. If bonds are added because two atoms are suddenly within the required distance which before was not the case, additional fragments are generated, calculated, and added to the approximation of the whole system. As the addition of these contributions is sudden -- in general, they will already be non-zero when the bonds are detected -- a slight jump in the total energy of the system can be expected.</para>
+          <para>To sum it up, the use of the BOSSANOVA scheme in bond breaking/forming scenarios is in general not recommended. That&apos;s why keeping the bond graph is always sensible. However, if potential energies are too far away from equilibrium the simulation may still produce unphysical results.</para>
+        </section>
+        <section xml:id="dynamics.optimize-structure">
+          <title xml:id="dynamics.optimize-structure.title">Structure optimization</title>
+          <para>Structure optimization is also a macro Action, it basically
+    combines the same Actions as <emphasis role="bold">molecular-dynamics</emphasis> does. However, it
+    uses the <emphasis role="bold">force-annealing</emphasis> action instead of <emphasis role="bold">verlet-integration</emphasis>.</para>
+          <para>The command below performs a structure optimization of the 
+    currently selected atoms (may also be a subset) for up to 100 time
+    steps, where each time step is again 0.5 atomic time units. The time
+    step here serves as the initial step width for annealing.
+    </para>
           <programlisting>
           ... --optimize-structure \
@@ -2435,82 +1926,59 @@
           --fragment-executable mpqc \
           </programlisting>
-
-  		  <para>Note that output-every-step will allow you to watch the 
-	  	  optimization as each step is placed into a distinct time step.
-		  Otherwise only two time steps would be created: the initial and
-		  the final one containing the optimized structure.</para>
-        </section>
-
-        <section xml:id='dynamics.set-world-time'>
-          <title xml:id='dynamics.set-world-time.title'>Set the world's time 
-          step</title>
-
-		  <para>In order to inspect or manipulate atoms and molecules at a
-		  certain time step, the World's time has to be set with the following
-		  Action.
-		  </para>
-		  
-		  <para>This will set the World's time to the fifth step (counting
-		  starts at zero).</para>
-
+          <para>Note that <emphasis role="bold">output-every-step</emphasis> will allow you to watch the 
+      optimization as each step is placed into a distinct time step.
+    Otherwise only two time steps would be created: the initial and
+    the final one containing the optimized structure.</para>
+        </section>
+        <section xml:id="dynamics.set-world-time">
+          <title xml:id="dynamics.set-world-time.title">Set the world&apos;s time step</title>
+          <para>In order to inspect or manipulate atoms and molecules at a
+    certain time step, the World&apos;s time has to be set with the following
+    Action.
+    </para>
+          <para>This will set the World&apos;s time to the fifth step (counting
+    starts at zero).</para>
           <programlisting>... --set-world-time 4</programlisting>
-        </section>
-
-        <section xml:id='dynamics.save-temperature'>
-          <title xml:id='dynamics.save-temperature.title'>Save the 
-          temperature information</title>
-
-		  <para>For each time step the temperature (i.e. the average velocity
-		  per atom times its mass) will be stored to a file.</para>
-
-          <programlisting>
-          ... --save-temperature temperature.dat \
-          </programlisting>
-        </section>
-      </section>
-    
-      <section xml:id='dynamics.tesselation'>
-        <title xml:id='dynamics.tesselation.title'>Tesselations</title>
-
-        <para>Tesselations obtain molecular surfaces (and volumes) by rolling
-        a virtual sphere of a certain radii on a molecule until a closed 
+          <para>Note that each atom has its own tracjectory storage and manages it in a clever way. That&apos;s why subsets of atoms may be time-integrated, while the other atoms will not get taken over on the time axis. They simply remain frozen during the integration.</para>
+        </section>
+        <section xml:id="dynamics.save-temperature">
+          <title xml:id="dynamics.save-temperature.title">Save the temperature information</title>
+          <para>For each present time step the temperature (i.e. the average velocity
+    per atom multiplied with its mass) will be stored to a file.</para>
+          <programlisting>          ... --save-temperature temperature.dat</programlisting>
+          <para>That is <emphasis role="italic">temperature.dat</emphasis> contains two columns: the first contains the time step and the second column contains the temperature of the system in atomic units.</para>
+        </section>
+      </section>
+      <section xml:id="dynamics.tesselation">
+        <title xml:id="dynamics.tesselation.title">Tesselations</title>
+        <para>A tesselation is a set of triangles that form a closed surface. They are used to obtain molecular surfaces (and volumes) by rolling
+        a virtual sphere of a certain radii on a molecule such that it always rests on at least three atoms. From such a resting position the sphere is rolled over all of its three sides until it rests again. This is continued until the closed 
         surface of connected triangles is created.</para>
-
-        <section xml:id='dynamics.tesselation.nonconvex-envelope'>
-          <title xml:id='dynamics.tesselation.nonconvex-envelope.title'>
-          Non-convex envelope</title>
-          
+        <para>Note that tesselations are used internally by the graphical interface in order to show molecules by their surface. This is in general faster than displaying them as a ball-stick model consisting of spheres and cylinders.</para>
+        <section xml:id="dynamics.tesselation.nonconvex-envelope">
+          <title xml:id="dynamics.tesselation.nonconvex-envelope.title"> Non-convex envelope</title>
           <para>This will create a non-convex envelope for a molecule and store
           it to a file for viewing with external programs.</para>
-
           <programlisting>
           ... --nonconvex-envelope 6. \
           --nonconvex-file nonconvex.dat
           </programlisting>
-
           <para>This tesselation file can be conveniently viewed with 
           <productname>TecPlot</productname> or with one of the Tcl script 
-          in the util folder with <productname>VMD</productname>. Also,
-          still pictures can be produced with <productname>Raster3D
-          </productname>.
-          <note>The required file header.r3d can be found in a subfolder of
-          the util folder.</note>
+          in the <emphasis role="italic">util</emphasis> folder with <productname>VMD</productname>. Also,
+          still pictures can be produced with <productname>Raster3D </productname>.
+          <note>The required file header.r3d can be found in a subfolder of the util folder.</note>
           </para>
         </section>
-
-        <section xml:id='dynamics.tesselation.convex-envelope'>
-          <title xml:id='dynamics.tesselation.convex-envelope.title'>Convex 
-          envelope</title>
-          
+        <section xml:id="dynamics.tesselation.convex-envelope">
+          <title xml:id="dynamics.tesselation.convex-envelope.title">Convex envelope</title>
           <para>This will create a convex envelope for a molecule and give the
           volumes of both the non-convex and the convex envelope. This is good
           for measuring the space a molecule takes up, e.g. when filling a 
           domain and taking care of correct densities.</para>
-
           <programlisting>
           ... --convex-envelope 6. \
           --convex-file convex.dat
           </programlisting>
-
           <para>This tesselation file can be likewise viewed with 
           <productname>TecPlot</productname> or with one of the Tcl script 
@@ -2518,213 +1986,156 @@
         </section>
       </section>
-
-      <section xml:id='various'>
-        <title xml:id='various.title'>Various commands</title>
-
+      <section xml:id="various">
+        <title xml:id="various.title">Various commands</title>
         <para>Here, we gather all commands that do not fit into one of above
         categories for completeness.</para>
-
-        <section xml:id='various.verbose'>
-          <title xml:id='various.verbose.title'>Changing verbosity</title>
-
+        <section xml:id="various.verbose">
+          <title xml:id="various.verbose.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>
-
+          <para>This command below sets the verbosity from default of 2 to 4,</para>
           <programlisting>... --verbose 4</programlisting>
-
           <para>or shorter,</para>
-
           <programlisting>... -v 4</programlisting>
         </section>
-        
-	<section xml:id='various.dry-run'>
-          <title xml:id='various.dry-run.title'>Dry runs</title>
-
-          <para>A "dry run" refers to a test run where commands are not 
-	  actually executed. You may bracket a certain set of actions by
-	  putting --dry-run before and --no-dry-run afterwards. Then, all
-	  action in between will be looked at but not executed, i.e. they
-	  make it to the history but nothing is changed in the World.</para>
-
-	  <para>As an example, the following listing contains the adding of a
-	  hydrogen atom at position (5,5,5) inside the aforementioned dry run
-	  statements. Hence, no hydrogen atom is added but the add action is
-	  stored in the history and will make it to a stored session.</para>
-
-          <programlisting>
-	  ... --dry-run \
-	  --add-atom 1 --domain-position "5,5,5"
-	  --no-dry-run
-	  </programlisting>
-
-	</section>
-
-        <section xml:id='various.element-db'>
-          <title xml:id='various.element-db.title'>Loading an element 
-          database</title>
-
+        <section xml:id="various.dry-run">
+          <title xml:id="various.dry-run.title">Dry runs</title>
+          <para>A &quot;dry run&quot; refers to a test run where commands are not 
+   actually executed. You may bracket a certain set of actions by
+   putting --<emphasis role="bold">dry-run</emphasis> before and --<emphasis role="bold">no-dry-run</emphasis> afterwards. Then, all
+   actions in between will be looked at but not executed, i.e. they
+   make it to the history but nothing is changed in the World.</para>
+          <para>As an example, the following listing contains the adding of a
+   hydrogen atom at position (5,5,5) inside the aforementioned dry run
+   statements. Hence, no hydrogen atom is added but the <emphasis role="bold">add-atom</emphasis> action is
+   stored in the history and will make it to a stored session.</para>
+          <programlisting>   ... --dry-run \
+   --add-atom 1 --domain-position &quot;5,5,5&quot;
+   --no-dry-run</programlisting>
+          <para>This is useful for converting shell commands into python scripts. Commands are not executed but all are eventually found in the written pyrthon file.</para>
+        </section>
+        <section xml:id="various.element-db">
+          <title xml:id="various.element-db.title">Loading an element database</title>
           <para>Element databases contain information on valency, van der
           Waals-radii and other information for each element.</para>
-
           <para>This loads all element database from the current folder (in a
           unix environment):</para>
-
           <programlisting>... --element-db ./</programlisting>
-
-        </section>
-
-        <section xml:id='various.fastparsing'>
-          <title xml:id='various.fastparsing.title'>Fast parsing</title>
-
+        </section>
+        <section xml:id="various.fastparsing">
+          <title xml:id="various.fastparsing.title">Fast parsing</title>
           <para>Parsing all time steps from a given input file can take a 
           while, especially for larger systems. If fast parsing is activated,
           only the first time step is loaded, all other are ignored.</para>
-
           <programlisting>... --fastparsing 1</programlisting>
         </section>
-
-        <section xml:id='various.version'>
-          <title xml:id='various.version.title'>Giving the version of the 
-          program</title>
-
+        <section xml:id="various.version">
+          <title xml:id="various.version.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 xml:id='various.warranty'>
-          <title xml:id='various.warranty.title'>Giving warranty 
-          information</title>
-
+        <section xml:id="various.warranty">
+          <title xml:id="various.warranty.title">Giving warranty information</title>
           <para>As follows warranty information is given,</para>
-
           <programlisting>... --warranty</programlisting>
         </section>
-
-        <section xml:id='various.help-redistribute'>
-          <title xml:id='various.help-redistribute.title'>Giving 
-          redistribution information</title>
-
+        <section xml:id="various.help-redistribute">
+          <title xml:id="various.help-redistribute.title">Giving redistribution information</title>
           <para>This gives information on the license and how to redistribute
           the program and its source code</para>
-
           <programlisting>... --help-redistribute</programlisting>
         </section>
       </section>
-
-      <section xml:id='sessions'>
-        <title xml:id='sessions.title'>Sessions</title>
-
+      <section xml:id="sessions">
+        <title xml:id="sessions.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
+        actions in the queue) this may be seen as a clever way of storing
+        the state and history of a molecular system manipulation session. 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 xml:id='sessions.store-session'>
-          <title xml:id='sessions.store-session.title'>Storing a session
-          </title>
-
+        <para>Note only that but stored session used in the graphical interface may safe a lot of repetitive pointing and clicking. On top of that if the python session file is called <emphasis role="italic">molecuilder.py</emphasis> and resides in the folder you start MoleCuilder from, then it will be executed automatically and even before creating the graphical interface (i.e. it is also faster).</para>
+        <section xml:id="sessions.store-session">
+          <title xml:id="sessions.store-session.title">Storing a session </title>
           <para>Storing sessions is simple,</para>
-
-          <programlisting>
-		  ... --store-session "session.py" \
-		      --session-type python
-	      </programlisting>
-
+          <programlisting>
+    ... --store-session &quot;session.py&quot; \
+        --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
+&quot;     cli&quot; for storing in the manner of the command-line interface, i.e. just as our example code snippets throughout this guide). 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 xml:id='sessions.load-session'>
-          <title xml:id='sessions.load-session.title'>Loading a session</title>
-
-          <para>Loading a session only works for python scripts. This actually
+          (that however requires the so-called <emphasis role="italic">pyMoleCuilder</emphasis> module).</para>
+        </section>
+        <section xml:id="sessions.load-session">
+          <title xml:id="sessions.load-session.title">Loading a session</title>
+          <para>Loading a session only works for python scripts, i.e. only for session type python and not for type cli. This actually
           blurs the line between the command-line interface and the python
-          interface a bit. But even more, MoleCuilder automatically executes a
+          interface a bit. Again, 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>
-
+          <programlisting>... --load-session &quot;session.py&quot;</programlisting>
           <para>This will execute every action with its options contained in the
           script <filename>session.py</filename>.</para>
         </section>
       </section>
-
-      <section xml:id='various-specific'>
-        <title xml:id='various-specific.title'>Various specific commands
-        </title>
-        
+      <section xml:id="various-specific">
+        <title xml:id="various-specific.title">Various specific commands </title>
         <para>In this (final) section of the action description we list a number
         Actions that are very specific to some purposes (or other programs).
         </para>
-        
-        <section xml:id='various-specific.save-selected-atoms-as-exttypes'>
-          <title xml:id='various-specific.save-selected-atoms-as-exttypes.title'>
-          Saving exttypes of a set of atoms</title>
-          
+        <section xml:id="various-specific.save-selected-atoms-as-exttypes">
+          <title xml:id="various-specific.save-selected-atoms-as-exttypes.title"> Saving exttypes of a set of atoms</title>
           <para>This saves the atomic ids of all currently selected atoms in a 
-           <link xlink:href="http://www.tremolo-x.com/"><productname>TREMOLO
-           </productname></link> exttypes file with the given name.</para>
-
+           <link xlink:href="http://www.tremolo-x.com/">
+              <productname>TREMOLO </productname>
+            </link> exttypes file with the given name.</para>
           <programlisting>
           ... --save-selected-atoms-as-exttypes \
           --filename test.exttypes </programlisting>
         </section>
-        
-        <section xml:id='various-specific.set-parser-parameters'>
-          <title xml:id='various-specific.set-parser-parameters.title'>Setting 
-          parser specific parameters</title>
-
-          <para>You can also tweak the parameters stored in this file easily.
+        <section xml:id="various-specific.set-parser-parameters">
+          <title xml:id="various-specific.set-parser-parameters.title">Setting parser specific parameters</title>
+          <para>You can tweak the parameters stored in files associated to specific ab initio programs to some extent.
           For example, <productname>MPQC</productname> stores various
-          parameters modifying the specific ab-initio calculation performed.
-          For <link xlink:href="http://www.mpqc.org/"><productname>MPQC
-          </productname></link> and 
-          <link xlink:href="http://www.psicode.org/"><productname>Psi4
-          </productname></link> this can be modified as follows.</para>
-
-          <programlisting>
-		... --set-parser-parameters mpqc \
-		    --parser-parameters "theory=CLHF;basis=6-31*G;"
+          parameters modifying the specific ab-initio calculation performed, e.g. the basis set used, the level of theory, whether gradients are calculated.
+          For <link xlink:href="http://www.mpqc.org/">
+              <productname>MPQC </productname>
+            </link> and 
+          <link xlink:href="http://www.psicode.org/">
+              <productname>Psi4 </productname>
+            </link> this can be modified as follows.</para>
+          <programlisting>
+  ... --set-parser-parameters mpqc \
+      --parser-parameters &quot;theory=CLHF;basis=6-31*G;&quot;
           </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 xml:id='various-specific.set-tremolo-atomdata'>
-          <title xml:id='various-specific.set-tremolo-atomdata.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
+          and the basis set to 6-31*G. Note the specific &quot;key=value;&quot; system. That is a key such as &quot;theory&quot; is followed by an equivalent sign and by a value, here &quot;CLHF&quot; for closed-shell Hartree-Fock, and finally a semicolon to separate the key-value pairs. Please avoid any unnecessary white spaces. Note that the implementation is probably not complete, hence do check the
+          <productname>MPQC</productname> manual on further supported values that must be added by hand. We list below the currently implementd list of keys and their values.</para>
+          <itemizedlist>
+            <listitem>theory</listitem>
+            <listitem>basis</listitem>
+          </itemizedlist>
+        </section>
+        <section xml:id="various-specific.set-tremolo-atomdata">
+          <title xml:id="various-specific.set-tremolo-atomdata.title">Tremolo specific options and potential files</title>
+          <para><productname>TREMOLO</productname>&apos;s configuration files start
+          with a specific line telling the amount of information that is contained in the
+          file. This line 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>
-
+          <programlisting>
+  ... --set-tremolo-atomdata &quot;ATOM id element u=3 v=3 F=3&quot; \
+      --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
+          <para>One further specific action is required when loading certain
           <productname>TREMOLO</productname> configuration files. These
           contain element notations that refer to parameterized names used in
@@ -2732,23 +2143,18 @@
           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>
-
+          so-called potentials 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>
+          <para>Note that this is the same format as written by the fitting actions. However, apart from this the Actions are not related, i.e. <emphasis role="bold">parse-potentials</emphasis> will not also load these element descriptions. If this is desired, the above Action has to be used.</para>
         </section>
       </section>
     </section>
-
-    <section xml:id='textmenu-interface'>
-      <title xml:id='textmenu-interface.title'>Text menu</title>
-
+    <section xml:id="textmenu-interface">
+      <title xml:id="textmenu-interface.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>
-
+      command-line interface. However, 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
@@ -2757,62 +2163,44 @@
       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>
+      as the command-line interface above. It differs by being interactive, i.e. when using an external viewer on the state file and saving it after an Action has been performed, output can be checked. However, you may work in this way also directly by using the graphical interface.</para>
     </section>
-
-    <section xml:id='graphical-user-interface'>
-      <title xml:id='graphical-user-interface.title'>Graphical user interface
-      </title>
-
+    <section xml:id="graphical-user-interface">
+      <title xml:id="graphical-user-interface.title">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
+      stick-and-ball-model by default. For faster rendering, molecules can also be visualized by the a non-convex envelope, see Tesselations. 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
+      <para>This interface is most helpful in designing more advanced structures that are
+      conceptually difficult to imagine without visual aid. Results can be inspected directly and, if unsuitable, can be undone and reperformed with tweaked parameters. At the end, a
+file containing the      session may be stored and this script can then be used to construct
       various derived or slightly modified structures.</para>
-
-      <section xml:id='graphical-user-interface.basic-view'>
-        <title xml:id='graphical-user-interface.basic-view.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>
-
+      <section xml:id="graphical-user-interface.basic-view">
+        <title xml:id="graphical-user-interface.basic-view.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>
-
+          <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%"/>
+              <imagedata width="100%" scalefit="1" entityref="example_basic_view"/>
             </imageobject>
           </mediaobject>
         </figure>
-
-        <section xml:id='graphical-user-interface.3d-view'>
-          <title xml:id='graphical-user-interface.3d-view.title'>3D view
-          </title>
-
+        <section xml:id="graphical-user-interface.3d-view">
+          <title xml:id="graphical-user-interface.3d-view.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 xml:id='graphical-user-interface.information-tabs'>
-          <title xml:id='graphical-user-interface.information-tabs.title'>
-          Information Tabs</title>
-
-          <para>Beneath this 3D view that you can rotate at will your mouse
+          of the water molecules, the &quot;dreibein&quot; giving the positive axis
+          directions and the slightly translucent cuboid of the domain on a black background.</para>
+        </section>
+        <section xml:id="graphical-user-interface.information-tabs">
+          <title xml:id="graphical-user-interface.information-tabs.title"> Information Tabs</title>
+          <para>Beneath this 3D view that you can rotate at will with 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
+          (although it&apos;s also an oxygen atom and should be colored 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
@@ -2820,18 +2208,12 @@
           molecule this specific atom belongs to.</para>
         </section>
-
-        <section xml:id='graphical-user-interface.shape'>
-          <title xml:id='graphical-user-interface.shape.title'>Shape section
-          </title>
-
+        <section xml:id="graphical-user-interface.shape">
+          <title xml:id="graphical-user-interface.shape.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 xml:id='graphical-user-interface.timeline'>
-          <title xml:id='graphical-user-interface.timeline.title'>Timeline
-          </title>
-
+select them by clicking on them, which lets their surface appear in the 3D view, and          manipulate them via the buttons beneath this list. Note that the calculation of the shape&apos;s surface may take up to a few seconds, so don&apos;t get itchy right away when nothing seems to happen for a moment.</para>
+        </section>
+        <section xml:id="graphical-user-interface.timeline">
+          <title xml:id="graphical-user-interface.timeline.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
@@ -2841,37 +2223,26 @@
           file.</para>
         </section>
-
-        <section xml:id='graphical-user-interface.tables'>
-          <title xml:id='graphical-user-interface.tables.title'>Selection 
-          tables</title>
-
+        <section xml:id="graphical-user-interface.tables">
+          <title xml:id="graphical-user-interface.tables.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
+          the molecular system in a tree 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>
-
+          to the GUI). Also, if you tick the box the visibility of the specific molecules is changed: it switches between being displayed as either ball-and-stick, for manipulating its individual atoms, or as a molecular surface for (un)selecting it as a whole.</para>
           <para>The next tab enumerates all elements known to MoleCuilder
-          where the ones are greyed out that are not present in the molecular
+          where the ones are grayed 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
+          <para>Subsequently 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 xml:id='graphical-user-interface.selections'>
-        <title xml:id='graphical-user-interface.selections.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
+          graphical depiction (via QWT), again if present.</para>
+        </section>
+      </section>
+      <section xml:id="graphical-user-interface.selections">
+        <title xml:id="graphical-user-interface.selections.title">Selections </title>
+        <para>Selections work generally always by calling a selection action from the pull-down menu and filling it with required parameters.</para>
+        <para>With the GUI 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
@@ -2879,106 +2250,76 @@
         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
+        <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
+        them will 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 xml:id='graphical-user-interface.dialogs'>
-        <title xml:id='graphical-user-interface.dialogs.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
+        right now and not suited to complex shapes. (This is in contrast to the molecular surfaces which are actually cheaper than the ball-and-stick presentation).</para>
+      </section>
+      <section xml:id="graphical-user-interface.dialogs">
+        <title xml:id="graphical-user-interface.dialogs.title">Dialogs</title>
+        <para>Most essential to the GUI are dialogs. Many action
+        calls forth such a dialog. A dialog         consists of a list of queries for a particular option value, one below the other. 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
+          <para>Each dialog&apos;s okay button is grayed out until all entered option values
           are valid.</para>
         </note>
-
-        <section xml:id='graphical-user-interface.dialogs.domain'>
-          <title xml:id='graphical-user-interface.dialogs.domain.title'>Domain 
-          query</title>
-
+        <section xml:id="graphical-user-interface.dialogs.domain">
+          <title xml:id="graphical-user-interface.dialogs.domain.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%"/>
+                <imagedata width="100%" scalefit="1" entityref="dialog_box"/>
               </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
+            specified a cube of edge length 8. The okay button will be grayed
             out if the matrix is either singular or not symmetric.</para>
           </figure>
         </section>
-
-        <section xml:id='graphical-user-interface.dialogs.element'>
-          <title xml:id='graphical-user-interface.dialogs.element.title'>
-          Element query</title>
-
+        <section xml:id="graphical-user-interface.dialogs.element">
+          <title xml:id="graphical-user-interface.dialogs.element.title"> Element query</title>
           <figure>
-            <title>Screenshot the add atom action containing an element
-            query</title>
-
+            <title>Screenshot the add atom action containing an element query</title>
             <mediaobject>
               <imageobject>
-                <imagedata entityref="dialog_add-atom_tooltip" scalefit="1" width="100%"/>
+                <imagedata width="100%" scalefit="1" entityref="dialog_add-atom_tooltip"/>
               </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 xml:id='graphical-user-interface.dialogs.action'>
-          <title xml:id='graphical-user-interface.dialogs.action.title'>
-          Complex query</title>
-
+        <section xml:id="graphical-user-interface.dialogs.action">
+          <title xml:id="graphical-user-interface.dialogs.action.title"> Complex query</title>
           <figure>
-            <title>Screenshot of a complex dialog consisting of multiple
-            queries</title>
-
+            <title>Screenshot of a complex dialog consisting of multiple queries</title>
             <mediaobject>
               <imageobject>
-                <imagedata entityref="dialog_complex" scalefit="1" width="100%"/>
+                <imagedata width="100%" scalefit="1" entityref="dialog_complex"/>
               </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
+            booleans and for files (the &quot;choose&quot; buttons opens a file
             dialog).</para>
           </figure>
         </section>
-
-        <section xml:id='graphical-user-interface.dialogs.exit'>
-          <title xml:id='graphical-user-interface.dialogs.exit.title'>Exit 
-          query</title>
-
+        <section xml:id="graphical-user-interface.dialogs.exit">
+          <title xml:id="graphical-user-interface.dialogs.exit.title">Exit query</title>
           <figure>
             <title>Screenshort showing the exit dialog</title>
-
             <mediaobject>
               <imageobject>
-                <imagedata entityref="dialog_exit" scalefit="1" width="100%"/>
+                <imagedata width="100%" scalefit="1" entityref="dialog_exit"/>
               </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
@@ -2990,42 +2331,30 @@
       </section>
     </section>
-
-    <section xml:id='python-interface'>
-      <title xml:id='python-interface.title'>Python interface</title>
-
+    <section xml:id="python-interface">
+      <title xml:id="python-interface.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
+      was created with. More generally, MoleCuilder&apos;s Actions can be executed within arbitrary python
+      scripts where prior to its execution a specific module has to be loaded, enabling access to MoleCuilder&apos;s actions from inside the
       script.</para>
-
-      <para>MoleCuilder's python module is called pyMoleCuilder. it is
+      <para>MoleCuilder&apos;s python module is called <emphasis role="italic">pyMoleCuilder</emphasis>. 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>
+      have added the containing folder 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
+      <para>This will list all of MoleCuilder&apos;s actions with their function
+      signatures within python as contained in the module <emphasis role="italic">pyMoleCuilder</emphasis> named
+      as <emphasis role="bold">mol</emphasis> 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>
-
+      <computeroutput>WorldChangeBox(...)</computeroutput> or alike. However, they are related by a certain naming system. The first word is identical to the menu name it resides in the text or graphical interface. Then its followed by the actual name of the action that is similar to the command-line token.</para>
+      <para>Let&apos;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
@@ -3033,26 +2362,18 @@
     </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/">MoleCuilder's website</link>.
+    <para>Tutorials and more information is available online, see <link xlink:href="http://www.molecuilder.com/">MoleCuilder&apos;s website</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>
-
+    understand what&apos;s going wrong if something&apos;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>
+      me sit next to her while riding ten hours in a bus to Berlin as I was writing the very first version of this guide.</para>
     </section>
   </chapter>
