Index: /NEMO/trunk/CHANGES.rst
===================================================================
--- /NEMO/trunk/CHANGES.rst	(revision 11723)
+++ /NEMO/trunk/CHANGES.rst	(revision 11723)
@@ -0,0 +1,7 @@
+*******
+Changes
+*******
+
+.. todo::
+
+   List the main additions of the the new release
Index: /NEMO/trunk/INSTALL.rst
===================================================================
--- /NEMO/trunk/INSTALL.rst	(revision 11722)
+++ /NEMO/trunk/INSTALL.rst	(revision 11723)
@@ -10,5 +10,5 @@
 
 | The NEMO source code is written in *Fortran 95* and
-  some of its prerequisite tools and libraries are already included in the ``./ext`` subdirectory.
+  some of its prerequisite tools and libraries are already included in the download.
 | It contains the AGRIF_ preprocessing program ``conv``; the FCM_ build system and
   the IOIPSL_ library for parts of the output.
@@ -40,258 +40,4 @@
    This will limit MPI features to those defined within the MPI-2 standard
    (but will lose some performance benefits).
-
-Specifics for NetCDF and HDF
-----------------------------
-
-NetCDF and HDF versions from .
-However access to all the options available with the XIOS IO-server will require
-the parallel IO support of these libraries which can be unavailable.
-
-| **To satisfy these requirements, it is common to have to compile from source
-  in this order HDF (C library) then NetCDF (C and Fortran libraries)**
-| It is also necessary to compile these libraries with the same version of the MPI implementation that
-  both NEMO and XIOS (see below) are compiled and linked with.
-
-.. hint::
-
-   | It is difficult to define the options for the compilation as
-     they differ from one architecture to another according to
-     the hardware used and the software installed.
-   | The following is provided without any warranty
-
-   .. code-block:: console
-
-      $ ./configure [--{enable-fortran,disable-shared,enable-parallel}] ...
-
-   It is recommended to build the tests ``--enable-parallel-tests`` and run them with ``make check``
-
-Particular versions of these libraries may have their own restrictions.
-State the following requirements for netCDF-4 support:
-
-.. caution::
-
-   | 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
-- *detached* - Every NEMO process runs as a XIOS client.
-  Output is collected and collated by external, stand-alone XIOS server processors.
-
-.. important::
-
-   In either case, 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:`XIOS wiki<wiki>`.
-
-.. hint::
-
-   It is recommended to use XIOS version 2.5.
-   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 https://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5
-
-Download the NEMO source code
-=============================
-
-.. code:: console
-
-   $ svn co https://forge.ipsl.jussieu.fr/nemo/svn/NEMO/trunk
-
-Description of directory tree
------------------------------
-
-+-----------+------------------------------------------------------------+
-| Folder    | Purpose                                                    |
-+===========+============================================================+
-| ``arch``  | Settings (per architecture-compiler pair)                  |
-+-----------+------------------------------------------------------------+
-| ``cfgs``  | :doc:`Reference configurations <configurations>`           |
-+-----------+------------------------------------------------------------+
-| ``doc``   | - ``latex``    : LaTex source code for ref. manuals        |
-|           | - ``namelists``: k start guide                             |
-|           | - ``rst``      : ReST files for quick start guide          |
-+-----------+------------------------------------------------------------+
-| ``ext``   | Dependencies included (``AGRIF``, ``FCM`` & ``IOIPSL``)    |
-+-----------+------------------------------------------------------------+
-| ``mk``    | Building  routines                                         |
-+-----------+------------------------------------------------------------+
-| ``src``   | Modelling routines                                         |
-|           |                                                            |
-|           | - ``ICE``: |NEMO-ICE| for sea ice                          |
-|           | - ``NST``: AGRIF for embedded zooms                        |
-|           | - ``OCE``: |NEMO-OCE| for ocean dynamics                   |
-|           | - ``TOP``: |NEMO-MBG| for tracers                          |
-+-----------+------------------------------------------------------------+
-| ``tests`` | :doc:`Test cases <test_cases>` (unsupported)               |
-+-----------+------------------------------------------------------------+
-| ``tools`` | :doc:`Utilities <tools>` to [pre|post]process data         |
-+-----------+------------------------------------------------------------+
-
-Setup your architecture configuration file
-==========================================
-
-All compiler options in NEMO are controlled using files in
-``./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
-==================================
-
-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:
-
-.. 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``   |                                                    |
-+------------+----------------------------------------------------+
-
-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 makenemo options
----------------------
-
-``makenemo`` has several other options that can control which source files are selected and
-the operation of the build process itself.
-These are::
-
-   Optional:
-      -d  Set of new sub-components (space separated list from ./src directory)
-      -e  Path for alternative patch  location (default: 'MY_SRC' in configuration folder)
-      -h  Print this help
-      -j  Number of processes to compile (0: no build)
-      -n  Name for new configuration
-      -s  Path for alternative source location (default: 'src' root directory)
-      -t  Path for alternative build  location (default: 'BLD' in configuration folder)
-      -v  Level of verbosity ([0-3])
-
-These options can be useful for maintaining several code versions with only minor differences but
-they should be used sparingly.
-Note however the ``-j`` option which should be used more routinely to speed up the build process.
-For example:
-
-.. code-block:: sh
-
-        ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE' -j 8
-
-which will compile up to 8 modules simultaneously.
-
-
-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.  If the –n option is not specified the last compiled configuration
-will be used.
-
-Tools used during the process
------------------------------
-
-*   functions.sh : bash functions used by makenemo, for instance to create the WORK directory
-*   cfg.txt : text list of configurations and source directories
-*   bld.cfg : FCM rules to compile
-
-Examples
---------
-
-.. code-block:: sh
-
-        echo "Example to install a new configuration MY_CONFIG";
-        echo "with OPA_SRC and LIM_SRC_2 ";
-        echo "makenemo -n MY_CONFIG -d \"OPA_SRC LIM_SRC_2\"";
-        echo "";
-        echo "Available configurations :"; cat ${CONFIG_DIR}/cfg.txt;
-        echo "";
-        echo "Available unsupported (external) configurations :"; cat ${CONFIG_DIR}/uspcfg.txt;
-        echo "";
-        echo "Example to remove bad configuration ";
-        echo "./makenemo -n MY_CONFIG clean_config";
-        echo "";
-        echo "Example to clean ";
-        echo "./makenemo clean";
-        echo "";
-        echo "Example to list the available keys of a CONFIG ";
-        echo "./makenemo list_key";
-        echo "";
-        echo "Example to add and remove keys";
-        echo "./makenemo add_key \"key_iomput key_mpp_mpi\" del_key \"key_agrif\" ";
-        echo "";
-        echo "Example to add and remove keys for a new configuration, and do not compile";
-        echo "./makenemo -n MY_CONFIG -j0 add_key \"key_iomput key_mpp_mpi\" del_key \"key_agrif\" ";
-
-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
-
-.. code-block:: sh
-
-        cd 'MY_CONFIG'/EXP00
-        mpirun -n $NPROCS ./opa    # $NPROCS is the number of processes ; mpirun is your MPI wrapper
-
-
-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:
-
-.. code-block:: sh
-
-        ./cfgs/'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.
-Note that most NEMO configurations will need to specify the following CPP keys:
-``key_iomput`` and ``key_mpp_mpi``
-
-.. Links and substitutions
 
 .. |OpenMPI| replace:: *OpenMPI*
@@ -300,5 +46,221 @@
 .. _MPICH:   https://www.mpich.org
 .. |NetCDF|  replace:: *Network Common Data Form (NetCDF)*
-.. _NetCDF:  https://www.unidata.ucar.edu/downloads/netcdf
+.. _NetCDF:  https://www.unidata.ucar.edu
 .. |HDF|     replace:: *Hierarchical Data Form (HDF)*
-.. _HDF:     https://www.hdfgroup.org/downloads
+.. _HDF:     https://www.hdfgroup.org
+
+Specifics for NetCDF and HDF
+----------------------------
+
+NetCDF and HDF versions from official repositories may have not been compiled with MPI support.
+However access to all the options available with the XIOS IO-server will require
+the parallelism of these libraries.
+
+| **To satisfy these requirements, it is common to have to compile from source
+  in this order HDF (C library) then NetCDF (C and Fortran libraries)**
+| It is also necessary to compile these libraries with the same version of the MPI implementation that
+  both NEMO and XIOS (see below) have been compiled and linked with.
+
+.. hint::
+
+   | It is difficult to define the options for the compilation as
+     they differ from one architecture to another according to
+     the hardware used and the software installed.
+   | The following is provided without any warranty
+
+   .. code-block:: console
+
+      $ ./configure [--{enable-fortran,disable-shared,enable-parallel}] ...
+
+   It is recommended to build the tests ``--enable-parallel-tests`` and run them with ``make check``
+
+Particular versions of these libraries may have their own restrictions.
+State the following requirements for netCDF-4 support:
+
+.. caution::
+
+   | 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.
+It can be used in two different modes:
+
+:*attached*:  Every NEMO process also acts as a XIOS server
+:*detached*:  Every NEMO process runs as a XIOS client.
+  Output is collected and collated by external, stand-alone XIOS server processors.
+
+Instructions on how to install XIOS can be found on its :xios:`wiki<>`.
+
+.. hint::
+
+   It is recommended to use XIOS 2.5 release.
+   This version should be more stable (in terms of future code changes) than the XIOS trunk.
+   It is also the one 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 with:
+
+   .. code:: console
+
+      $ svn co https://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5
+
+Download and install the NEMO code
+==================================
+
+Checkout the NEMO sources
+-------------------------
+
+.. code:: console
+
+   $ svn co https://forge.ipsl.jussieu.fr/nemo/svn/NEMO/trunk
+
+Description of 1\ :sup:`st` level tree structure
+------------------------------------------------
+
++-----------+----------------------------------------+
+| ``arch``  | Compilation settings                   |
++-----------+----------------------------------------+
+| ``cfgs``  | :doc:`Reference configurations <cfgs>` |
++-----------+----------------------------------------+
+| ``doc``   | :doc:`Documentation <doc>`             |
++-----------+----------------------------------------+
+| ``ext``   | Dependencies included                  |
+|           | (``AGRIF``, ``FCM`` & ``IOIPSL``)      |
++-----------+----------------------------------------+
+| ``mk``    | Compilation scripts                    |
++-----------+----------------------------------------+
+| ``src``   | :doc:`Modelling routines <src>`        |
++-----------+----------------------------------------+
+| ``tests`` | :doc:`Test cases <tests>`              |
+|           | (unsupported)                          |
++-----------+----------------------------------------+
+| ``tools`` | :doc:`Utilities <tools>`               |
+|           | to {pre,post}process data              |
++-----------+----------------------------------------+
+
+Setup your architecture configuration file
+------------------------------------------
+
+All compiler options in NEMO are controlled using files in :file:`./arch/arch-'my_arch'.fcm` where
+``my_arch`` is the name of the computing architecture
+(generally following the pattern ``HPCC-compiler`` or ``OS-compiler``).
+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    /usr/local/path/to/netcdf
+   %HDF5_HOME    /usr/local/path/to/hdf5
+   %XIOS_HOME    /home/$( whoami )/path/to/xios-2.5
+   %OASIS_HOME   /home/$( whoami )/path/to/oasis
+
+Create and compile a new configuration
+======================================
+
+The main script to {re}compile and create executable is called ``makenemo`` located at
+the root of the working copy.
+It is used to identify the routines you need from the source code, to build the makefile and run it.
+As an example, compile a :file:`MY_GYRE` configuration from GYRE with 'my_arch':
+
+.. code-block:: sh
+
+   ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE'
+
+Then at the end of the configuration compilation,
+:file:`MY_GYRE` directory will have the following structure.
+
++------------+----------------------------------------------------------------------------+
+| Directory  | Purpose                                                                    |
++============+============================================================================+
+| ``BLD``    | BuiLD folder: target executable, headers, libs, preprocessed routines, ... |
++------------+----------------------------------------------------------------------------+
+| ``EXP00``  | Run   folder: link to executable, namelists, ``*.xml`` and IOs             |
++------------+----------------------------------------------------------------------------+
+| ``EXPREF`` | Files under version control only for :doc:`official configurations <cfgs>` |
++------------+----------------------------------------------------------------------------+
+| ``MY_SRC`` | New routines or modified copies of NEMO sources                            |
++------------+----------------------------------------------------------------------------+
+| ``WORK``   | Links to all raw routines from :file:`./src` considered                    |
++------------+----------------------------------------------------------------------------+
+
+After successful execution of ``makenemo`` command,
+the executable called `nemo` is available in the :file:`EXP00` directory
+
+More ``makenemo`` options
+-------------------------
+
+``makenemo`` has several other options that can control which source files are selected and
+the operation of the build process itself.
+
+.. literalinclude:: ../../../makenemo
+   :language: text
+   :lines: 119-143
+   :caption: Output of ``makenemo -h``
+
+These options can be useful for maintaining several code versions with only minor differences but
+they should be used sparingly.
+Note however the ``-j`` option which should be used more routinely to speed up the build process.
+For example:
+
+.. code-block:: sh
+
+        ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE' -j 8
+
+will compile up to 8 processes simultaneously.
+
+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.
+If the ``-n`` option is not specified the last compiled configuration will be used.
+
+Tools used during the process
+-----------------------------
+
+* ``functions.sh`` : bash functions used by ``makenemo``, for instance to create the WORK directory
+* ``cfg.txt`` : text list of configurations and source directories
+* ``bld.cfg`` : FCM rules to compile
+
+Examples
+--------
+
+.. literalinclude:: ../../../makenemo
+   :language: text
+   :lines: 146-153
+
+Running the model
+=================
+
+Once ``makenemo`` has run successfully,
+the ``nemo`` executable is available in ``./cfgs/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 needs other input files, they have to be placed here.
+
+.. code-block:: sh
+
+   cd 'MY_CONFIG'/EXP00
+   mpirun -n $NPROCS ./nemo   # $NPROCS is the number of processes
+                              # mpirun is your MPI wrapper
+
+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 :file:`./cfgs/'MYCONFIG'/cpp_MY_CONFIG.fcm`
+
+This text file can be edited by hand or with ``makenemo`` to change the list of active CPP keys.
+Once changed, one needs to recompile ``nemo`` in order for this change to be taken in account.
+Note that most NEMO configurations will need to specify the following CPP keys:
+``key_iomput`` for IOs and ``key_mpp_mpi`` for parallelism.
Index: /NEMO/trunk/README.rst
===================================================================
--- /NEMO/trunk/README.rst	(revision 11722)
+++ /NEMO/trunk/README.rst	(revision 11723)
@@ -20,5 +20,5 @@
 These physical core engines are described in
 their respective `reference publications <#project-documentation>`_ that
-must be cited for any work related to their use (see :doc:`citations`).
+must be cited for any work related to their use (see :doc:`cite`).
 
 Assets and solutions
@@ -30,13 +30,13 @@
 - Create :doc:`embedded zooms<zooms>` seamlessly thanks to 2-way nesting package AGRIF_.
 - Opportunity to integrate an :doc:`external biogeochemistry model<tracers>`
-- Versatile :doc:`data assimilation<data_assimilation>`
-- Generation of :doc:`diagnostics<diagnostics>` through effective XIOS_ system
-- Roll-out Earth system modeling with :doc:`coupling interface<coupling>` based on OASIS_
+- Versatile :doc:`data assimilation<da>`
+- Generation of :doc:`diagnostics<diags>` through effective XIOS_ system
+- Roll-out Earth system modeling with :doc:`coupling interface<cplg>` based on OASIS_
 
-Several :doc:`built-in configurations<configurations>` are provided to
+Several :doc:`built-in configurations<cfgs>` are provided to
 evaluate the skills and performances of the model which
 can be used as templates for setting up a new configurations (:file:`./cfgs`).
 
-The user can also checkout available :doc:`idealized test cases<test_cases>` that
+The user can also checkout available :doc:`idealized test cases<tests>` that
 address specific physical processes (:file:`./tests`).
 
Index: MO/trunk/RELEASE_NOTES.rst
===================================================================
--- /NEMO/trunk/RELEASE_NOTES.rst	(revision 11722)
+++ 	(revision )
@@ -1,7 +1,0 @@
-*************
-Release Notes
-*************
-
-.. todo::
-
-   Complete "Release Notes"
Index: /NEMO/trunk/cfgs/AGRIF_DEMO/README.rst
===================================================================
--- /NEMO/trunk/cfgs/AGRIF_DEMO/README.rst	(revision 11722)
+++ /NEMO/trunk/cfgs/AGRIF_DEMO/README.rst	(revision 11723)
@@ -20,5 +20,5 @@
 ===========
 
-Activating AGRIF requires to append the cpp key ``key_agrif`` at compilation time: 
+Activating AGRIF requires to append the cpp key ``key_agrif`` at compilation time:
 
 .. code-block:: sh
@@ -54,5 +54,5 @@
 depends on the number of ghost cells as illustrated by the (attempted) drawing below for nbghostcells=1 and
 nbghostcells=3.
-The grid refinement is 3 and nxfin is the number of child grid points in i-direction.  
+The grid refinement is 3 and nxfin is the number of child grid points in i-direction.
 
 .. image:: _static/agrif_grid_position.jpg
@@ -62,5 +62,5 @@
 boundary data exchange and update being only performed between root and child grids.
 Use of east-west periodic or north-fold boundary conditions is not allowed in child grids either.
-Defining for instance a circumpolar zoom in a global model is therefore not possible. 
+Defining for instance a circumpolar zoom in a global model is therefore not possible.
 
 Preprocessing
@@ -92,16 +92,15 @@
 	   rn_sponge_dyn = 2880.   !  coefficient for dynamics sponge layer [m2/s]
 	   ln_chk_bathy  = .false. !  =T  check the parent bathymetry
-	/             
+	/
 
 where sponge layer coefficients have to be chosen according to the child grid mesh size.
 The sponge area is hard coded in NEMO and applies on the following grid points:
-2 x refinement factor (from i=1+nbghostcells+1 to i=1+nbghostcells+sponge_area) 
+2 x refinement factor (from i=1+nbghostcells+1 to i=1+nbghostcells+sponge_area)
 
-References
-==========
+.. rubric:: References
 
 .. bibliography:: zooms.bib
-	:all:
-	:style: unsrt
-	:labelprefix: A
-	:keyprefix: a-
+   :all:
+   :style: unsrt
+   :labelprefix: A
+   :keyprefix: a-
Index: /NEMO/trunk/cfgs/README.rst
===================================================================
--- /NEMO/trunk/cfgs/README.rst	(revision 11722)
+++ /NEMO/trunk/cfgs/README.rst	(revision 11723)
@@ -296,11 +296,8 @@
 while lateral boundary conditions for dynamical fields have 3 days time frequency.
 
-References
-==========
-
-.. bibliography:: configurations.bib
+.. rubric:: References
+
+.. bibliography:: cfgs.bib
    :all:
    :style: unsrt
    :labelprefix: C
-
-.. Links and substitutions
Index: /NEMO/trunk/src/TOP/README.rst
===================================================================
--- /NEMO/trunk/src/TOP/README.rst	(revision 11722)
+++ /NEMO/trunk/src/TOP/README.rst	(revision 11723)
@@ -208,5 +208,5 @@
 
 The overall data structure (Fortran type) is based on the general one defined for NEMO core in the SBC component
-(see details in ``SBC`` Chapter of :doc:`Reference Manual <citations>` on Input Data specification).
+(see details in ``SBC`` Chapter of :doc:`Reference Manual <cite>` on Input Data specification).
 
 Input fields are prescribed within ``&namtrc_dta`` (with ``sn_trcdta`` structure),
@@ -230,5 +230,5 @@
 Note that, the Lateral Open Boundaries conditions are applied on
 the segments defined for the physical core of NEMO
-(see ``BDY`` description in the :doc:`Reference Manual <citations>`).
+(see ``BDY`` description in the :doc:`Reference Manual <cite>`).
 
 :file:`namelist_trc`
@@ -286,5 +286,5 @@
 :file:`trcwri_my_trc.F90`
    This routine performs the output of the model tracers (only those defined in ``&namtrc``) using
-   IOM module (see chapter “Output and Diagnostics” in the :doc:`Reference Manual <citations>`).
+   IOM module (see chapter “Output and Diagnostics” in the :doc:`Reference Manual <cite>`).
    It is possible to place here the output of additional variables produced by the model,
    if not done elsewhere in the code, using the call to ``iom_put``.
Index: /NEMO/trunk/tests/README.rst
===================================================================
--- /NEMO/trunk/tests/README.rst	(revision 11722)
+++ /NEMO/trunk/tests/README.rst	(revision 11723)
@@ -13,5 +13,5 @@
 
 .. contents::
-	:local:
+   :local:
 
 Procedure
@@ -34,5 +34,5 @@
 ------------------------------
 
-There no requirement of specific input file for the test_cases presented here. The XIOS xml input files and namelist are already setup correctly. 
+There no requirement of specific input file for the test_cases presented here. The XIOS xml input files and namelist are already setup correctly.
 For detailed description and Jupyter notebook, the reader is directed on
 the `NEMO test cases repository <http://github.com/NEMO-ocean/NEMO-examples>`_
@@ -42,8 +42,8 @@
 ICE_AGRIF
 =========
-  
+
   This test case illustrates the advection of an ice patch across an East/West and North/South periodic channel
   over a slab ocean (i.e. one ocean layer), and with an AGRIF zoom (1:3) in the center
-  The purpose of this configuration is to test the advection of the ice patch in  
+  The purpose of this configuration is to test the advection of the ice patch in
   and across the AGRIF boundary
   One can either impose ice velocities or ice-atm. stresses and let rheology define velocities
@@ -54,13 +54,13 @@
 VORTEX
 ======
-  
+
   This test case illustrates the propagation of an anticyclonic eddy over a Beta plan and a flat bottom.
   It is implemented here with an online refined subdomain (1:3) out of which the vortex propagates.
   It serves as a benchmark for quantitative estimates of nesting errors as in Debreu et al. (2012) :cite:`DEBREU2012`,
   Penven et al. (2006) :cite:`PENVEN2006` or Spall and Holland (1991) :cite:`SPALL1991`.
-  
+
   The animation below (sea level anomaly in meters) illustrates with two 1:2 successively nested grids how
   the vortex smoothly propagates out of the refined grids.
-  
+
   .. image:: _static/VORTEX_anim.gif
 
@@ -69,7 +69,7 @@
 
   The purpose of this test case is to evaluate the impact of various schemes and new development with the iceshelf cavities circulation and melt.
-  This configuration served as initial assesment of the ice shelf module in Losh et al. (2008) :cite:`LOSCH2008` and Mathiot et al. (2017) :cite:`MATHIOT2017`. 
+  This configuration served as initial assesment of the ice shelf module in Losh et al. (2008) :cite:`LOSCH2008` and Mathiot et al. (2017) :cite:`MATHIOT2017`.
   The default setup is the one described `here <http://staff.acecrc.org.au/~bkgalton/ISOMIP/test_cavities.pdf>`_.
-  
+
   The figure below (meridional overturning circulation) illustrates the circulation generated after 10000 days by the ice shelf melting (ice pump).
 
@@ -82,5 +82,5 @@
   by Haidvogel and Beckmann (1999) :cite:`HAIDVOGEL1999` for testing advection schemes in ocean circulation models.
   It has been used by several authors including Burchard and Bolding (2002) :cite:`BURCHARD2002` and Ilicak et al. (2012) :cite:`ILICAK2012`.
-  The LOCK EXCHANGE experiment can in particular illustrate the impact of different choices of numerical schemes 
+  The LOCK EXCHANGE experiment can in particular illustrate the impact of different choices of numerical schemes
   and/or subgrid closures on spurious interior mixing.
 
@@ -92,7 +92,7 @@
 ========
 
-  The OVERFLOW experiment illustrates the impact of different choices of numerical schemes 
-  and/or subgrid closures on spurious interior mixing close to bottom topography. 
-  The OVERFLOW experiment is adapted from the non-rotating overflow configuration described 
+  The OVERFLOW experiment illustrates the impact of different choices of numerical schemes
+  and/or subgrid closures on spurious interior mixing close to bottom topography.
+  The OVERFLOW experiment is adapted from the non-rotating overflow configuration described
   in Haidvogel and Beckmann (1999) :cite:`HAIDVOGEL1999` and further used by Ilicak et al. (2012) :cite:`ILICAK2012`.
   Here we can assess the behaviour of the second-order tracer advection scheme FCT2 and fortht-order FCT4, z-coordinate and sigma coordinate (...).
@@ -105,7 +105,7 @@
 ===
 
-  A set of simple closed basin geometries for testing the Wetting and drying capabilities. 
+  A set of simple closed basin geometries for testing the Wetting and drying capabilities.
   Examples range from a closed channel with EW linear bottom slope to a parabolic EW channel with a Gaussian ridge.
-  
+
   Below the animation of the test case 7. This test case is a simple linear slope with a mid-depth shelf with an open boundary forced with a sinusoidally varying ssh.
   This test case has been introduced to emulate a typical coastal application with a tidally forced open boundary with an adverse SSH gradient that, when released, creates a surge up the slope.
@@ -123,5 +123,5 @@
 ICE_ADV2D
 =========
-  
+
   This test case illustrates the advection of an ice patch across an East/West and North/South periodic channel
   over a slab ocean (i.e. one ocean layer).
@@ -130,9 +130,9 @@
   (for now, Prather and Ultimate-Macho from 1st to 5th order),
   especially the occurence of overshoots in ice thickness
-  
+
 
 ICE_ADV1D
 =========
-  
+
   This experiment is the classical Schar & Smolarkiewicz (1996) test case :cite:`SCHAR1996`,
   which has been used in :cite:`LIPSCOMB2004`,
@@ -141,11 +141,10 @@
   The purpose of this configuration is to test the caracteristics of advection schemes available in the sea-ice code
   (for now, Prather and Ultimate-Macho from 1st to 5th order),
-  especially the constitency between concentration, thickness and volume, and the preservation of initial shapes.  
+  especially the constitency between concentration, thickness and volume, and the preservation of initial shapes.
 
-References
-==========
+.. rubric:: References
 
-.. bibliography:: test_cases.bib
-	:all:
-	:style: unsrt
-	:labelprefix: T
+.. bibliography:: tests.bib
+   :all:
+   :style: unsrt
+   :labelprefix: T
Index: /utils/build/makenemo
===================================================================
--- /utils/build/makenemo	(revision 11722)
+++ /utils/build/makenemo	(revision 11723)
@@ -52,7 +52,7 @@
 # - TOOLS_DIR   :   "    "    "
 # - NEMO_DIR    :   "    "    "
-# - REMOTE_CTL  : URL link to a remote resource list for an external configuration 
+# - REMOTE_CTL  : URL link to a remote resource list for an external configuration
 #                 which is not part of the reference suite
-# - LOCAL_REF   : Nearest reference configuration to an external configuration 
+# - LOCAL_REF   : Nearest reference configuration to an external configuration
 #                 which is not part of the reference suite
 #                 (used to populate work directories if remote access is not available)
@@ -119,32 +119,35 @@
 Usage:
 ------
-./makenemo -[aru] CONFIG -m ARCH [-[dehjntv] ...] [{list_key,clean,clean_config}] [{add_key,del_key} ...]
-
-Mandatory:
-   -m   Computing architecture (./arch), FCM file describing the compilation settings
+./makenemo -[aru] CONFIG -m ARCH [-[dehjntv] ...] [{list_key,clean,clean_config}]
+                                                  [{add_key,del_key} ...]
+
+Mandatory
+   -m    Computing architecture (./arch), FCM file describing the compilation settings
+
    and one of the following option (use 'all' arg to list available items)
-   -r   Reference configuration (./cfgs), proven with long-term support until the EOL of the release
-   -a   Academic test case (./tests), ready to use at the release start without guarantee or support over time
-   -u   Scripted remote configuration (see ./tests/rmt_cfgs.txt)
-
-Optional:
-   -d   New set of sub-components (list from ./src directory)
-   -e   Path for alter patch  location (default: 'MY_SRC' in configuration folder)
-   -h   Print this help
-   -j   Number of processes to compile (0: dry run with no build)
-   -n   Name for new configuration
-   -s   Path for alter source location (default: 'src' root directory)
-   -t   Path for alter build  location (default: 'BLD' in configuration folder)
-   -v   Level of verbosity ([0-3])
-
-Examples:
+
+   -r    Reference configuration (./cfgs), proven with long-term support
+   -a    Academic test case (./tests), ready-to-use configuration with no support over time
+   -u    Scripted remote configuration (see ./tests/rmt_cfgs.txt)
+
+Optional
+   -d    New set of sub-components (subfolders from ./src directory)
+   -e    Path for alter patch  location (default: 'MY_SRC' in configuration folder)
+   -h    Print this help
+   -j    Number of processes to compile (0: dry run with no build)
+   -n    Name for new configuration
+   -s    Path for alter source location (default: 'src' root directory)
+   -t    Path for alter build  location (default: 'BLD' in configuration folder)
+   -v    Level of verbosity ([0-3])
+
+Examples
    ¤ Configuration creation
-        Build          : ./makenemo -[aru] ... [...]
+        Build          : ./makenemo         -[aru] ... [...]
         Copy           : ./makenemo -n ...  -[aru] ... [...]
    ¤ Configuration management
-        List CPP keys  : ./makenemo [...] list_key
-        Add-Remove keys: ./makenemo [...] add_key '...' del_key '...'
-        Fresh start    : ./makenemo [...] clean
-        Erasure        : ./makenemo [...] clean_config
+        List CPP keys  : ./makenemo -n ... list_key
+        Add-Remove keys: ./makenemo -n ... add_key '...' del_key '...'
+        Fresh start    : ./makenemo -n ... clean
+        Removal        : ./makenemo -n ... clean_config
 EOF
 				exit 0       ;;
@@ -258,5 +261,5 @@
 else
 
-	## Reuse a working cfg	
+	## Reuse a working cfg
 	if [[ -f ${CONFIG_DIR}/work_cfgs.txt && $( grep "${TML_CONF} " ${CONFIG_DIR}/work_cfgs.txt ) ]]; then
 		conf_file=work_cfgs.txt
@@ -362,5 +365,5 @@
 
 	## if AGRIF we do a first preprocessing
-	if [[ ${#x_c} -eq 0 && "$AGRIFUSE" -eq 1 ]]; then 
+	if [[ ${#x_c} -eq 0 && "$AGRIFUSE" -eq 1 ]]; then
 		fcm build --ignore-lock -j 1 ${COMPIL_DIR}/bld_preproagr.cfg ||{ cd - ; exit 1 ;}
 		echo ''
