Documentation update

docs/source/index.rst

@@ -8,6 +8,8 @@ Contents:
 
    install/index.rst
    design/planning.rst
+   manual/index.rst
+   reference/index.rst
 
 
 

docs/source/manual/index.rst

@@ -0,0 +1,73 @@
+User manual
+###########
+
+Using BAM is easy and fun! Provided that:
+
+- you know how to use the command line of your os
+- have some experience of how versioning systems work
+
+Actually, this is not true, and in this guide we will explain to use BAM client from scracth.
+
+.. hint:: Do not try to follow this page as a step-by-step tutorial, since its content might 
+    be not completely coherent. The purpose of this manual is simply to explain the bam 
+    workflow from the artist point of view.
+
+
+Project Initialization
+======================
+
+In order to start working, we need to initialize a *project folder*. This operation should
+be done only once. To create a project folder we need to open our terminal, and go to the
+location where we want to store the project folder. Then we can type::
+
+    bam init http://bam:5000/gooseberry
+
+This command creates a ``gooseberry`` folder, containing information about the project. If
+we enter the folder and use the ``ls`` comand command, we notice that it is empty, but if
+we use the ``bam ls`` command we see a directory listing. This listing is provided by the
+project server on the fly and it allows us to browse its content without having a local copy
+on our machine.
+
+The project folder can be moved anywhere, at any time. The exact ``bam init`` syntax is
+available in the reference section.
+
+
+Session creation
+================
+
+Once the project has been initialized and we are able to browse it remotely, we can proceed
+checking out a file from it. For example we can type::
+
+    bam co libs/envs/jungle/jungle_opening.blend
+
+This creates a ``jungle_opening`` folder inside of our ``gooseberry`` project folder, which
+will contain the ``jungle_opening.blend``, along with all its dependencies (library files,
+textures, etc.) organized as follows. ::
+
+    jungle_opening.blend
+    relative/maps/path/map.png
+    _absolute/maps/path/map.png
+
+As we can see, folders starting with the ``_`` character map to an absolute path on the server,
+while the other folders are relative to the file that was used to create the session.
+
+
+Editing
+=======
+
+At this point we can edit any file in the session, and the system will keep track of our changes.
+Currently we can:
+
+- add new files to the session
+- delete files
+- edit files
+
+We can not:
+
+- rename files
+
+In order to check what is the status of our edits, we can use ``bam st``, which will print a list
+of edited, added and deleted files.
+
+.. note:: Sessions are meant to create a contained and controlled working environment. We should
+    never, ever refer to content that is outside of a session folder.

docs/source/reference/index.rst

@@ -0,0 +1,7 @@
+Client Reference
+################
+
+Here is a reference of all the BAM cli commands.
+
+bam init
+   Initializes a Project. Available in a few variations.