Index: doc/userguide/userguide.xml
===================================================================
--- doc/userguide/userguide.xml	(revision 0014a436e03a48bf183ec1b1017d9bccc35047fe)
+++ doc/userguide/userguide.xml	(revision 5f869d731c0e018ae107f17a253937a99d0c6c9b)
@@ -100,6 +100,13 @@
             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>
+          <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 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>
@@ -110,7 +117,9 @@
         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, 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>
+        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>
       </section>
     </section>
@@ -313,6 +322,7 @@
       </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>
+        <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 receives an extra tab for indentation.</para>
       </note>
       <section xml:id="preliminaries">
@@ -726,4 +736,88 @@
           <para>This translates all selected shapes by 5 along the x
           axis.</para>
+        </section>
+      </section>
+      <section xml:id="geometry">
+        <title xml:id="geometry.title">Geometry Objects</title>
+        <para>Although we use the term geometry objects in the title, we 
+        actually mean vectors, i.e. a position or direction in the 
+        three-dimensional space. But maybe we have need for the more
+        general term in the future.</para>
+        <para>Vectors are required as input to many of the Actions further 
+        below: translating atoms, rotating atoms around a specific axis,
+        aligning a molecule with a vector, ...</para>
+        <para>Therefore, vectors can be stored and referenced using a given
+        name. This allows for a very powerful and handy manipulation of the
+       molecular system afterwards. And to give a concrete example, let's have
+       a look at translating a set of selected atoms. </para>
+       <programlisting>
+... --translate-atoms &quot;unitVectorX&quot;
+       </programlisting>
+       <para>This would use the automatically created reference 
+       &quot;unitVectorX&quot;, i.e. the vector with components (1,0,0) as
+       the translation vector for the given set of atoms. In other words, all
+       selected atoms get shifted by 1 unit (e.g. Angstr&ouml;m) in +X
+       direction.</para>
+       <para>We have the following automatically created geometry objects 
+       whose names are self-explanatory:</para>
+       <itemizedlist>
+        <listitem>zeroVector</listitem>
+        <listitem>unitVectorX</listitem>
+        <listitem>unitVectorY</listitem>
+        <listitem>unitVectorZ</listitem>
+       </itemizedlist>
+       <para>However, more vectors can be simply constructed from atomic 
+       positions, such as the position of an atom directly, the distance between 
+       two atoms (in case they are bonded, then this would be the bond vector) 
+       or from three atoms, defining a plane and giving its normal vector.
+       </para>
+       <remark>We have refrained from giving automated names to vectors and even
+       keeping them up-to-date automatically, i.e. the distance between two atoms
+       O1 and O2 could be named &quot;distance_O1_O2&quot; or similar. However, we want
+       the user to have full control and maybe come up with more suitable names 
+       such as &quot;rotation_axis&quot; in this case.</remark>
+       <warning>Note that names have to be unique and the Action will fail if
+       the name is already used.</warning>
+        <section xml:id="geometry.distance-to.vector">
+          <title xml:id="geometry.distance-to-vector.title">Atomic distance to stored vector</title>
+          <para>The distance between two selected atoms is stored as a vector as follows,</para>
+          <programlisting>
+  ... --distance-to-vector &quot;distance_vec&quot; \
+          </programlisting>
+          <para>where the distance vector can be referenced by &quot;distance_vec&quot; 
+          from then on in other Actions requiring a vector as input.</para>
+        </section>
+        <section xml:id="geometry.input-to.vector">
+          <title xml:id="geometry.input-to-vector.title">Coordinates to stored vector</title>
+          <para>We may also create a geometry vector simply by supplying the 
+          three coordinates of a vector.</para>
+          <programlisting>
+  ... --input-to-vector &quot;vector&quot; \
+      --position &quot;1,2,3&quot;
+          </programlisting>
+          <para>where the vector with components (1,2,3) can be referenced 
+          by &quot;vector&quot; .</para>
+        </section>
+        <section xml:id="geometry.plane-to.vector">
+          <title xml:id="geometry.plane-to-vector.title">Normal of plane to stored vector</title>
+          <para>Three positions in space (if they are not linear dependent)
+          define a plane in three-dimensional space.</para>
+          <para>Therefore, when exactly three atoms are selected, this Action
+          will construct the resulting plane and store its normal vector as a
+          geometry object for later reference.</para>
+          <programlisting>
+  ... --plane-to-vector &quot;planenormal&quot; \
+          </programlisting>
+          <para>where the plane's normal vector can be referenced by 
+          &quot;planenormal&quot;.</para>
+        </section>
+        <section xml:id="geometry.position-to.vector">
+          <title xml:id="geometry.position-to-vector.title">Atomic position to stored vector</title>
+          <para>Storing the position of a singly selected atom as a vector is simply done as follows,</para>
+          <programlisting>
+  ... --position-to-vector &quot;vector_O1&quot; \
+          </programlisting>
+          <para>where the vector can be referenced by &quot;vector_O1&quot; 
+          from then on.</para>
         </section>
       </section>
