Index: NEMO/trunk/INSTALL.rst
===================================================================
--- NEMO/trunk/INSTALL.rst	(revision 10279)
+++ NEMO/trunk/INSTALL.rst	(revision 10557)
@@ -6,22 +6,77 @@
 	:local:
       
-Dependencies
-============
-
-| 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)
-
-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.
-
-- `HDF5`_   (C library)
-- `NetCDF`_ (C and Fortran libraries)
-
-Extract the source code
-=======================
-
-Download the source code
-------------------------
+Prerequisites
+=============
+
+- The NEMO source code is written in Fortran 95 and some of its prerequisite
+  tools and libraries are already included in the (``./ext``) subdirectory. These
+  include: the AGRIF preprocessing program "conv"; the FCM build system and the 
+  IOIPSL library for parts of the output.
+|
+- Other requirements that your system needs to provide include: a Perl 5 interpreter; a modern
+  Fortran compiler (ifort, gfortran, pgfortran, ...) and (in most cases) a MPI library
+  (e.g. OpenMPI or MPICH). The latter is not strictly essential since it is possible
+  to compile and run NEMO on a single processor. However most realistic configurations
+  will require the parallel capabilities of NEMO and these use the Message Passing
+  Interface (MPI) library. NEMO v4.0, by default, uses some MPI features introduced
+  into the MPI-3 standard. On older systems, that do not support these features, 
+  the key_mpi2 preprocessor key should be used at compile time. This will limit MPI
+  features to those defined within the MPI-2 standard (but will lose some performance
+  benefits).
+|
+The following prerequisites may already be installed or be available from the
+official repositories of your Linux distribution. However access to all the
+options available with the XIOS IO-server will require the parallel form of the
+netcdf4 library and its underlying HDF5 library. It is also necessary to compile
+these libraries with the same version of the MPI library that both NEMO and XIOS
+(see below) are compiled and linked with. To satisfy these requirements, it is common 
+to have to compile the following from source.
+
+- `HDF5`_   (C library) (use: --enable-fortran --enable-parallel with configure)
+- `NetCDF4`_ (C and Fortran libraries)
+
+Note that particular versions of these libraries may have their own
+restrictions. For example, the latest versions of the netCDF libraries:
+netcdf-c-4.6.2 and netcdf-fortran-4.4.4, state the following requirements for netCDF-4 support:
+
+* HDF5 1.8.9 or later.
+* HDF5 1.10.1 or later.
+* zlib 1.2.5 or later (for netCDF-4 compression)
+* curl 7.18.0 or later (for DAP remote access client support)
+
+|
+`Important Note: When building netCDF-C library versions older than 4.4.1,
+use only HDF5 1.8.x versions. Combining older netCDF-C versions with newer
+HDF5 1.10 versions will create superblock 3 files that are not readable by
+lots of older software.`
+
+Extract and install XIOS
+========================
+
+With the sole exception of running NEMO in mono-processor mode (in which case
+output options are limited to those supported by the IOIPSL library), diagnostic
+outputs from NEMO are handled by the third party XIOS library. This can be used
+in two different modes:
+
+* attached - Every NEMO process also acts as a XIOS server
+* dettached - Every NEMO process runs as a XIOS client. Output is collected and collated by external,
+  stand-alone XIOS server processors.
+
+In either case, it is important to note that XIOS needs to be compiled before
+NEMO, since the libraries are needed to successfully create the NEMO executable.
+
+Instructions on how to obtain and install the software can be found on the `XIOS Wiki`_ .
+
+It is recommended to use XIOS version 2.5 with NEMOv4.0. This version should be more stable (in terms of 
+future code changes) than the XIOS trunk. It is also the version used by the NEMO system team when 
+testing all developments and new releases. This particular version has its own branch and can be 
+checked out and downloaded with:
+
+.. code:: console
+
+        $ svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5
+
+Download the NEMO source code
+=============================
 
 .. code:: console
@@ -52,5 +107,5 @@
 |           | - ``NST``: AGRIF for embedded zooms                        |
 |           | - ``OCE``: |OPA| for ocean dynamics                        |
-|           | - ``MBG``: |TOP| for tracers                               |
+|           | - ``TOP``: |TOP| for tracers                               |
 +-----------+------------------------------------------------------------+
 | ``tests`` | :doc:`Test cases <test_cases>` (unsupported)               |
@@ -58,29 +113,22 @@
 | ``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.
-
-Important notice: XIOS needs to be compiled before NEMO, since the libraries are needed to successfully create NEMO executable.
-Instructions on how to obtain and install the software, see Users/Model Interfacing/Inputs Outputs.
-
-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)
-    for nemo_v3_6_STABLE only: you can add key_xios2 if you wish to use the most recent XIOS2 release of XIOS. Doing so, you will have to change the xml files used as input for XIOS : in this release, the xml files are only XIOS1 compatible. If you add key_xios2 you can use xml files located in GYRE_XIOS/EXP00 as first templates. In future releases of NEMO XIOS2 will be the default XIOS release in use. 
 
 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.
-It is recommended to copy and rename an configuration file from an architecture similar to your owns. You will need to set appropriate values for all of the variables in the file. In particular the FCM variables %NCDF_HOME, %HDF5_HOME and %XIOS_HOME should be set to the installation directories used for XIOS installation.
-
-%NCDF_HOME           /opt/local
-%HDF5_HOME           /opt/local
-%XIOS_HOME           /Users/$( whoami )/xios-1.0
-%OASIS_HOME          /not/defined
+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.  It is recommended to copy and rename an configuration file from
+an architecture similar to your owns. You will need to set appropriate values
+for all of the variables in the file. In particular the FCM variables:
+``%NCDF_HOME``; ``%HDF5_HOME`` and ``%XIOS_HOME`` should be set to the
+installation directories used for XIOS installation.
+
+.. code-block:: sh
+
+        %NCDF_HOME           /opt/local
+        %HDF5_HOME           /opt/local
+        %XIOS_HOME           /Users/$( whoami )/xios-2.5
+        %OASIS_HOME          /not/defined
 
 Compile and create NEMO executable
@@ -115,4 +163,9 @@
 Folder intended to contain your customised routines (modified from initial ones or new entire routines)
 
+When you compile NEMO you will need to specify the following CPP keys:
+
+*   key_iomput
+*   key_mpp_mpi
+
 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
@@ -179,3 +232,5 @@
 
 .. _HDF5:   http://www.hdfgroup.org/downloads/hdf5
-.. _NetCDF: http://www.unidata.ucar.edu/downloads/netcdf
+.. _NetCDF4: http://www.unidata.ucar.edu/downloads/netcdf
+.. _XIOS Wiki:    http://forge.ipsl.jussieu.fr/ioserver/wiki/documentation
+.. _XIOSSRC: http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5
