first attemp to acceptable readme file

README.md

 
-LMGC90 project : user version
+# LMGC90 project: user version #
 
-Contains :
+Organization
+============
+
+Contains:
 
  * src : the sources of LMGC90 software
  * examples : the user examples going with the sources
- * manuals : a list of manuals/documentation for the software
+ * manuals : a list of manuals/documentation for the software in pdf format
+ * docs : the html documentation generated from the sources
+
+Update
+======
+
+To update to very last version from a terminal in current directory:
+```
+$> git pull origin master
+```
+
+To get as specific version, for example *rc2015a* :
+```
+$> git pull origin rc2015a
+```
+
+Compilation
+===========
+
+Pre-requisites
+--------------
+
+To compile you need:
+
+ * A fortran compiler (GNU, Intel or PGI)
+ * Lapack library
+ * CMake
+ * Swig
+ * Python and numpy
+
+For visualisation:
+
+ * Python VTK module
+ * Paraview
+
+To build the sphinx documentation:
+
+ * Latex distribution (with pdflatex utility)
+ * Sphinx and numpydoc
+ * Doxygen
+ * Graphviz
+ * dvipng
+ 
+On Ubuntu the list of package needed for compiling and using is:
+gfortran gcc g++ liblapack-dev python-dev python-numpy python-vtk swig cmake paraview
+
+For the doc you will also need:
+doxygen graphviz sphinx python-numpydoc texlive-latex-extra dvipng
+
 
+On MacOs using macports:
+gcc48 python27 py27-numpy swig vtk +python27 cmake
 
-Reminder for the new versions :
+Then you need to set the compiler and python as the default on your system :
+```
+sudo port select gcc mp-gcc48
+sudo port select python27
+```
+
+For the doc:
+doxygen graphvix py27-sphinx py27-pip texlive-latex-extra dvipng
+
+And with pip, install the following python package:
+numpydoc
+
+Building
+--------
+
+You have several commands to run. If you are not familiar with the terminal and compilation in general
+please read the output of each command carefully. And if an error occurs do not blindly run the next
+commands, but try to correct it first.
+
+If you are completely at loss
+In this directory run:
+
+```
+mkdir build
+cd build
+cmake ../src
+make
+```
+
+Installing
+----------
+
+Our policy is to not mess with default system paths. So instead we advise to
+use a environment variable to add to python the path to our build directory.
+In general adding the following lines to your *.bashrc* *.bash_profile* or *.profile*
+file does the trick. Of course you have to replace *mybuildpath* by the path to
+your own building directory. Basically it is what returns the command *pwd* when
+ran in the same directory you ran the commands *cmake* and *make*.
+
+```
+if [ -z ${PYTHONPATH} ]; then
+  export PYTHONPATH=mybuildpath
+else
+  export PYTHONPATH=${PYTHONPATH}:mybuildpath
+fi
+```
+
+---------------------------------------
+
+
+Reminder for the new versions:
+------------------------------
 
 To update a subtree directory :
-$> git subtree pull --prefix=src --squash remote\_name tag\_number
+
+```
+$> git subtree pull --prefix=src --squash remote_name tag_number
+```
 
 To add a new subtree directory :
-$> git remote add remote\_name remote\_url
-$> git fetch remote\_name
-$> git subtree add --prefix=src --squash remote\_name tag\_or\_branch\_to\_get
+
+```
+$> git remote add remote_name remote_url
+$> git fetch remote_name
+$> git subtree add --prefix=src --squash remote_name tag_or_branch_to_get
+```