Index: doc/userguide.xml
===================================================================
--- doc/userguide.xml	(revision 6a7f78c9ef6be7e9a26caa642d5bff5a83ae7493)
+++ doc/userguide.xml	(revision 6a7f78c9ef6be7e9a26caa642d5bff5a83ae7493)
@@ -0,0 +1,230 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<book version="5.0" xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      xmlns:svg="http://www.w3.org/2000/svg"
+      xmlns:m="http://www.w3.org/1998/Math/MathML"
+      xmlns:html="http://www.w3.org/1999/xhtml"
+      xmlns:db="http://docbook.org/ns/docbook">
+  <info>
+    <title>MoleCuilder - a Molecule Builder</title>
+
+    <author>
+      <personname><firstname>Frederik</firstname><surname>Heber</surname></personname>
+
+      <affiliation>
+        <orgname>heber@ins.uni-bonn.de</orgname>
+      </affiliation>
+    </author>
+
+    <pubdate>08/11/09</pubdate>
+  </info>
+
+  <chapter>
+    <title>Introduction</title>
+
+    <section>
+      <title>What is MoleCuilder?</title>
+
+      <para><command>MoleCuilder</command> allows to construct atomic and
+      molecular geometries by a simple point&amp;click approach, combined with
+      a powerful library of known structures. It is intended to be a
+      CAD-pendant on the nanoscale. Specific emphasis is placed on a
+      simple-to-use interface, allowing for the quick-and-dirty building of
+      molecular systems. </para>
+
+      <para>Geometries should henceforth be simulated with molecular dynamics
+      packages, that are either ab-initio or used specific empirical
+      potentials to simulate the acting quantum-mechanical forces.</para>
+
+      <section>
+        <title>Installation requirements</title>
+
+        <para>The following packages are required to build the executables
+        from its source code.</para>
+
+        <para><simplelist>
+            <member>C/C++ Compiler (such as GCC)</member>
+          </simplelist></para>
+
+        <para><simplelist>
+            <member>Gnu Scientific Library
+            (<uri>http://www.gnu.org/software/gsl/</uri>)</member>
+          </simplelist></para>
+
+        <para><simplelist>
+            <member>Qt3 (<uri>http://www.trolltech.com/</uri>)</member>
+          </simplelist>The code has been tested develeoped on Linux/GNU. It
+        was also tested with Win/Cygwin.</para>
+
+        <para>Note that there are two executables:
+        <command>molecuilder</command> and <command>molecuildergui</command>.
+        The former is the command-line interfaces which, if no commands are
+        given, launches a interactive menu in a terminal session. The latter
+        is the graphical user interface with the same functionality as the
+        command-line interface but in a different approach, explained in more
+        detail in the chapter on the <olink>GUI</olink>.</para>
+
+        <para><command>MoleCuilder</command> makes uses of GNU autotools to
+        allow for compilation on different platforms. Please be refered to the
+        INSTALL file that is included in the archive and the web
+        (<uri>http://www.gnu.org/software/autoconf</uri>).</para>
+      </section>
+
+      <section>
+        <title>License</title>
+
+        <para>As long as no other license statement is given, MoleCuilder is
+        free for user under the GNU Public License (GPL) Version 2 (see
+        <uri>www.gnu.de/documents/gpl-2.0.de.html</uri>).</para>
+      </section>
+    </section>
+  </chapter>
+
+  <chapter>
+    <title>Features</title>
+
+    <para>Basically, <command>MoleCuilder</command> parses geometries from
+    files, manipulates them and stores them again in files. The manipulation
+    can be done either via a command-line interface or via the graphical user
+    interface.</para>
+
+    <section>
+      <title>Concepts</title>
+
+      <para>In general, we divide the molecular systems into three different
+      components or scales.</para>
+
+      <orderedlist>
+        <listitem>
+          <para>Atoms</para>
+
+          <para>Atoms are the undividable objects of the molecular systems.
+          They have an element <quote>Z</quote> and three coordinates
+          <quote>(x,y,z)</quote>.</para>
+        </listitem>
+
+        <listitem>
+          <para>Molecules</para>
+
+          <para>Molecules are conglomeration of atoms, bound or unbound. They
+          contain a number of atoms and a specific center in the domain such
+          that its atoms are placed relative to this center.</para>
+        </listitem>
+
+        <listitem>
+          <para>Domain</para>
+
+          <para>The domain refers to the simulation domain. It is either
+          infinite or finite if periodic boundary conditions are to be
+          applied. In the latter case, atoms are always shifted back into the
+          domain periodically. A domain contains a number of molecules.</para>
+        </listitem>
+      </orderedlist>
+    </section>
+
+    <section>
+      <title>Command-line interface</title>
+
+      <para>The command-line interface reads options or command from the
+      command line and executes them sequentially. This may be for example:
+      Open an empty file, add 2 hydrogen at ... and add 1 oxygen at ...,
+      choose a simulation box, fill the box with this given "filler" molecule,
+      save the file. This enables the use of MoleCuilder in simple
+      script-files to create a whole range of geometries that only differ in a
+      few parameters automatically.</para>
+
+      <para>Traditionally, <command>MoleCuilder</command> operates on a single
+      configuration file which stores additional information to the pure
+      geometry such as parameters for the ab-initio computation. An example
+      for the above procedure is given below:</para>
+
+      <screen>./molecuilder sample.conf -e &lt;path_to_db&gt; -a H 0. 0. 0. -a H 0. 0.176 0. -a O 1. 0.176 0. ...
+</screen>
+
+      <para>The first argument is the executable itself, the second the
+      arbitrarilty named file <computeroutput>sample.conf</computeroutput>,
+      which may be empty, the third is the command -e immediately followed by
+      the path to the databases, then follow step by step each of the above
+      commands. A command is always introduced via a hyphen and a single
+      letter, e.g. -a for adding an atom to the system. It is followed by a
+      fixed number of options. </para>
+
+      <para><emphasis>Note that these first three arguments are always
+      mandatory.</emphasis> The databases are supplied with the archive and
+      usually installed in the same directory as the executables. The output
+      file on finish will be <computeroutput>sample.conf</computeroutput> and
+      various other formats desired.</para>
+
+      <para>Below we have divided the various features into distinct the
+      scales upon which the manipulation takes places - single atoms, multiple
+      atoms organised as molecules, and all atoms organised by their
+      containing domain - and explain in more detail.</para>
+
+      <section>
+        <title>Manipulate atoms</title>
+
+        <para>Here, we explain in detail how to add, remove atoms, change its
+        element type, scale the bond in between or measure the bond length or
+        angle.</para>
+      </section>
+
+      <section>
+        <title>Manipulate domain</title>
+
+        <para>Here, we elaborate on how to duplicate all the atoms inside the
+        domain, how the scale the coordinate system, how to center the atoms
+        with respect to certain points, how to realign them by given
+        constraints, how to mirror and most importantly how to specify the
+        domain.</para>
+      </section>
+
+      <section>
+        <title>Merge molecules</title>
+
+        <para>As we may create, add and remove molecules, there can be more
+        than one, joining of molecules into a single one can be done in a
+        number of ways which is explained in this section in greater
+        detail.</para>
+
+        <section>
+          <title>Editing molecules</title>
+
+          <para>In this category we explain how to create new empty molecules,
+          how to load them from file, how to change their names and filenames,
+          how to set them active and inactive, how to parse more atoms into a
+          given molecules and how to remove a molecule.</para>
+        </section>
+
+        <section>
+          <title>Merging molecules</title>
+
+          <para>As we may create, add and remove molecules, there can be more
+          than one, joining of molecules into a single one can be done in a
+          number of ways which is explained in this section in greater
+          detail.</para>
+        </section>
+      </section>
+    </section>
+
+    <section>
+      <title linkend="GUI">Graphical user interface</title>
+
+      <para>The main point of the GUI is that it renders the atoms and
+      molecules visually. These are either represented by the common
+      stick-and-ball-model or as tesselated molecular surfaces. 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.</para>
+
+      <para>This is mostly helpful to design more advanced structures that are
+      conceptually difficult to imagine without visual aid.</para>
+
+      <section>
+        <title>The interface sections</title>
+
+        <para></para>
+      </section>
+    </section>
+  </chapter>
+</book>
