Index: NEMO/branches/UKMO/dev_r10037_GPU/INSTALL.rst
===================================================================
--- NEMO/branches/UKMO/dev_r10037_GPU/INSTALL.rst	(revision 10842)
+++ NEMO/branches/UKMO/dev_r10037_GPU/INSTALL.rst	(revision 10843)
@@ -1,38 +1,64 @@
-Install the modelling framework (NEMO and XIOS)
+*********************
+Install the framework
+*********************
 
-Last edition: 2018-02-14 21:32 CET by nicolasmartin
+.. contents::
+	:local:
+      
+Dependencies
+============
 
-    Extract the NEMO code
-        Description of NEMOGCM directory tree
-    Extract and install XIOS
-    Setup your architecture configuration file
-    Compile and create NEMO executable
-        More options
-        Default behaviour
-        Tools used during the process
-        Examples
-    Running the model
-    Viewing and changing list of active CPP keys
+| The NEMO source code is written in Fortran 95 and part of its dependencies are already included (``./ext``):
+  AGRIF preprocessing program "conv", FCM build system and IOIPSL library for outputs.
+| And some Perl 5, Fortran compiler (ifort, gfortran, pgfortran, ...), MPI library (Open MPI or MPICH)
 
-Extract the NEMO code
+But The following dependencies should be from the official repositories of your Linux distribution but
+you will probably have to compile them from source for enabling parallel I/O support.
 
-Using your account registered here ('my_login' with password)
+- `HDF5`_   (C library)
+- `NetCDF`_ (C and Fortran libraries)
+
+Extract the source code
+=======================
+
+Download the source code
+------------------------
 
 .. code:: console
-svn --username 'mylogin' co http://forge.ipsl.jussieu.fr/nemo/svn/branches/2015/nemo_v3_6_STABLE/NEMOGCM
 
-Description of NEMOGCM directory tree
+	$ svn co http://forge.ipsl.jussieu.fr/nemo/svn/NEMO/releases/release-4.0
 
-The image below shows the directory tree:
+Description of directory tree
+-----------------------------
 
-simple table:
-    ARCH    Compilation option files, with format arch_compiler.fcm, the compiler name has to be provided with –m option
-    CONFIG	All configurations and a cpp.fcm file containing the list of CPP keys to each configuration
-    EXTERNAL    Package to implement an embedded model (AGRIF)
-    NEMO    FORTRAN source codes in several sub-directories
-    SETTE    Package to make tests to ensure the reproducibility and restartability of the code after changes
-    TOOLS    Useful softwares to different utilities
++-----------+------------------------------------------------------------+
+| Folder    | Purpose                                                    |
++===========+============================================================+
+| ``arch``  | Settings (per architecture-compiler pair)                  |
++-----------+------------------------------------------------------------+
+| ``cfgs``  | :doc:`Reference configurations <configurations>`           |
++-----------+------------------------------------------------------------+
+| ``doc``   | - ``latex``: reference manuals for |OPA|, |SI3| & |TOP|    |
+|           | - ``namelists``: k start guide                             |
+|           | - ``rst``:   quick start guide                             |
++-----------+------------------------------------------------------------+
+| ``ext``   | Dependencies included (AGRIF, FCM & IOIPSL)                |
++-----------+------------------------------------------------------------+
+| ``mk``    | Building  routines                                         |
++-----------+------------------------------------------------------------+
+| ``src``   | Modelling routines                                         |
+|           |                                                            |
+|           | - ``ICE``: |SI3| for sea ice                               |
+|           | - ``NST``: AGRIF for embedded zooms                        |
+|           | - ``OCE``: |OPA| for ocean dynamics                        |
+|           | - ``MBG``: |TOP| for tracers                               |
++-----------+------------------------------------------------------------+
+| ``tests`` | :doc:`Test cases <test_cases>` (unsupported)               |
++-----------+------------------------------------------------------------+
+| ``tools`` | :doc:`Utilities <tools>` to [pre|post]process data         |
++-----------+------------------------------------------------------------+
 
 Extract and install XIOS
+========================
 
 Diagnostic outputs from NEMO are handled by the third party XIOS library.
@@ -42,5 +68,5 @@
 
 When you compile NEMO you will need to specify the following CPP keys:
-
+  
     key_iomput
     key_mpp_mpi (if you want to run with multiple processes and/or use "detached mode" for the IOs system XIOS)
@@ -48,4 +74,5 @@
 
 Setup your architecture configuration file
+==========================================
 
 All compiler options in NEMO are controlled using files in NEMOGCM/ARCH/arch-'my_arch'.fcm where 'my_arch' is the name of the computing architecture.
@@ -58,59 +85,42 @@
 
 Compile and create NEMO executable
+==================================
 
 The main script to compile and create executable is called makenemo and located in the CONFIG directory, it is used to identify the routines you need from the source code, to build the makefile and run it.
 As an example, compile GYRE with 'my_arch' to create a 'MY_GYRE' configuration:
 
-   cd NEMOGCM/CONFIG; ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE'
+.. code-block:: sh
+
+	./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE'
 
 The image below shows the structure and some content of "MY_CONFIG" directory from the launching of the configuration creation (directories and fundamental files created by makenemo).
 
-	
++------------+----------------------------------------------------+
+| Folder     | Purpose                                            |
++============+====================================================+
+| ``BLD``    |                                                    |
++------------+----------------------------------------------------+
+| ``EXP00``  |                                                    |
++------------+----------------------------------------------------+
+| ``EXPREF`` |                                                    |
++------------+----------------------------------------------------+
+| ``MY_SRC`` |                                                    |
++------------+----------------------------------------------------+
+| ``WORK``   |                                                    |
++------------+----------------------------------------------------+
 
-    WORK
-
-	
-
-    Folder with the symbolic links to all unpreprocessed routines considered in the configuration
-
-    BLD
-
-	
-
-    Compilation folder (executables, headers files, libraries, preprocessed routines, flags, …)
-
-    EXP00
-
-	
-
-    Computation folder for running the model (namelists, xml, executables and inputs-outputs)
-
-    MY_SRC
-
-	
-
-    Folder intended to contain your customized routines (modified from initial ones or new entire routines)
+Folder with the symbolic links to all unpreprocessed routines considered in the configuration
+Compilation folder (executables, headers files, libraries, preprocessed routines, flags, …)
+Computation folder for running the model (namelists, xml, executables and inputs-outputs)
+Folder intended to contain your customised routines (modified from initial ones or new entire routines)
 
 After successful execution of makenemo command, the executable called opa is created in the EXP00 directory (in the example above, the executable is created in CONFIG/MY_GYRE/EXP00).
 More options
 
-        echo "Usage      : "${b_n} \
-            " [-h] [-n name] [-m arch] [-d "dir1 dir2"] [-r conf] [-u conf] [-s Path] [-e Path] [-j No] [-v No] [-k 0/1]";
-        echo " -h               : help";
-        echo " -h institute : specific help for consortium members";
-        echo " -n name      : config name, [-n help] to list existing configurations";
-        echo " -m arch      : choose compiler, [-m help] to list existing compilers";
-        echo " -d dir       : choose NEMO sub-directories";
-        echo " -r conf      : choose reference configuration";
-        echo " -u conf      : choose an unsupported (external) configuration";
-        echo " -s Path      : choose alternative location for NEMO main directory";
-        echo " -e Path      : choose alternative location for MY_SRC directory";
-        echo " -j No        : number of processes used to compile (0=nocompilation)";
-        echo " -v No        : set verbosity level for compilation [0-3]";
-        echo " -k 0/1       : used cpp keys check (default = 1 -> check activated)";
-        echo " -t dir       : temporary directory for compilation"
-        echo "";
+..
+	.. literalinclude::
 
 Default behaviour
+-----------------
 
     At the first use, you need the -m option to specify the architecture configuration file (compiler and its options, routines and libraries to include), then for next compilation, it is assumed you will be using the same compiler.
@@ -118,4 +128,5 @@
 
 Tools used during the process
+-----------------------------
 
     functions.sh : bash functions used by makenemo, for instance to create the WORK directory
@@ -124,4 +135,5 @@
 
 Examples
+--------
 
         echo "Example to install a new configuration MY_CONFIG";
@@ -149,7 +161,8 @@
 
 Running the model
+=================
 
-Once makenemo has run successfully, the opa executable is available in CONFIG/"MY_CONFIG"/EXP00
-For the reference configurations, the EXP00 folder also contains the initial input files (namelists, *xml files for the IOs…). If the configuration also needs NetCDF input files, this should be downloaded here from the corresponding tar file, see Users/Reference Configurations
+Once makenemo has run successfully, the opa executable is available in ``CONFIG/MY_CONFIG/EXP00``
+For the reference configurations, the EXP00 folder also contains the initial input files (namelists, \*xml files for the IOs…). If the configuration also needs NetCDF input files, this should be downloaded here from the corresponding tar file, see Users/Reference Configurations
 
    cd 'MY_CONFIG'/EXP00
@@ -157,8 +170,12 @@
 
 Viewing and changing list of active CPP keys
+============================================
 
-For a given configuration (here called MY_CONFIG), the list of active CPP keys can be found in
+For a given configuration (here called MY_CONFIG), the list of active CPP keys can be found in::
 
-   NEMOGCM/CONFIG/'MYCONFIG'/cpp_'MY_CONFIG'.fcm
+	NEMOGCM/CONFIG/'MYCONFIG'/cpp_'MY_CONFIG'.fcm
 
 This text file can be edited to change the list of active CPP keys. Once changed, one needs to recompile opa executable using makenemo command in order for this change to be taken in account.
+
+.. _HDF5:   http://www.hdfgroup.org/downloads/hdf5
+.. _NetCDF: http://www.unidata.ucar.edu/downloads/netcdf
