Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/CHANGES.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/CHANGES.rst	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/CHANGES.rst	(revision 11954)
@@ -0,0 +1,7 @@
+*******
+Changes
+*******
+
+.. todo::
+
+   List the main additions of the the new release
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/CONTRIBUTING.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/CONTRIBUTING.rst	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/CONTRIBUTING.rst	(revision 11954)
@@ -3,6 +3,10 @@
 ************
 
+.. todo::
+
+
+
 .. contents::
-	:local:
+   :local:
 
 Sending feedbacks
@@ -17,7 +21,7 @@
 - You have a question: create a topic in the appropriate :forge:`discussion <forum>`
 - You would like to raise and issue: open a new ticket of the right type depending of its severity
-  
+
   - "Unavoidable" :forge:`newticket?type=Bug       <bug>`
-    
+
   - "Workable"    :forge:`newticket?type=Defect <defect>`
 
@@ -27,5 +31,5 @@
 ===============
 
-You have build a development relevant for NEMO shared reference: an addition of the source code,  
+You have build a development relevant for NEMO shared reference: an addition of the source code,
 a full fork of the reference, ...
 
@@ -34,5 +38,5 @@
 
 The proposals for developments to be included in the shared NEMO reference are first examined by NEMO Developers
-Committee / Scientific Advisory Board. 
+Committee / Scientific Advisory Board.
 The implementation of a new development requires some additionnal work from the intial developer.
 These tasks will need to be scheduled with NEMO System Team.
@@ -42,7 +46,7 @@
 ----
 
-You only would like to inform NEMO community about your developments. 
+You only would like to inform NEMO community about your developments.
 You can promote your work on NEMO forum gathering  the contributions fromof the community by creating
-a specific topic here :forge:`discussion/forum/5 <dedicated forum>` 
+a specific topic here :forge:`discussion/forum/5 <dedicated forum>`
 
 
@@ -55,5 +59,5 @@
   routines to the ticket, to highlight the proposed changes by adding to the ticket the output of ``svn diff``
   or ``svn patch`` from your working copy.
-  
+
 | Your development seems relevant for addition into the future release of NEMO shared reference.
   Implementing it into NEMO shared reference following the usual quality control will require some additionnal work
@@ -61,9 +65,9 @@
   your suggestion should be send as a proposed enhancement here :forge:`newticket?type=Enhancement <enhancement>`
   including description of the development, its implementation, and the existing validations.
-  
-  The proposed enhancement will be examined  by NEMO Developers Committee / Scientific Advisory Board. 
+
+  The proposed enhancement will be examined  by NEMO Developers Committee / Scientific Advisory Board.
   Once approved by the  Committee, the assicated development task can be scheduled in NEMO development work plan,
   and tasks distributed between you as initial developer and PI of this development action, and the NEMO System Team.
-  
+
   Once sucessful (meeting the usual quality control steps) this action will allow the merge of these developments with
   other developments of the year, building the future NEMO.
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/INSTALL.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/INSTALL.rst	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/INSTALL.rst	(revision 11954)
@@ -3,4 +3,8 @@
 *******************
 
+.. todo::
+
+
+
 .. contents::
    :local:
@@ -10,5 +14,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.
@@ -23,5 +27,5 @@
 - *Fortran* compiler (``ifort``, ``gfortran``, ``pgfortran``, ...),
 - *Message Passing Interface (MPI)* implementation (e.g. |OpenMPI|_ or |MPICH|_).
-- |NetCDF|_ library with its underlying |HDF|_ 
+- |NetCDF|_ library with its underlying |HDF|_
 
 **NEMO, by default, takes advantage of some MPI features introduced into the MPI-3 standard.**
@@ -40,258 +44,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``: |SI3| for sea ice                               |
-|           | - ``NST``: AGRIF for embedded zooms                        |
-|           | - ``OCE``: |OPA| for ocean dynamics                        |
-|           | - ``TOP``: |TOP| 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 +50,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
+------------------------------------------------
+
++---------------+----------------------------------------+
+| :file:`arch`  | Compilation settings                   |
++---------------+----------------------------------------+
+| :file:`cfgs`  | :doc:`Reference configurations <cfgs>` |
++---------------+----------------------------------------+
+| :file:`doc`   | :doc:`Documentation <doc>`             |
++---------------+----------------------------------------+
+| :file:`ext`   | Dependencies included                  |
+|               | (``AGRIF``, ``FCM`` & ``IOIPSL``)      |
++---------------+----------------------------------------+
+| :file:`mk`    | Compilation scripts                    |
++---------------+----------------------------------------+
+| :file:`src`   | :doc:`Modelling routines <src>`        |
++---------------+----------------------------------------+
+| :file:`tests` | :doc:`Test cases <tests>`              |
+|               | (unsupported)                          |
++---------------+----------------------------------------+
+| :file:`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 :file:`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 :file:`makenemo` command,
+the executable called `nemo` is available in the :file:`EXP00` directory
+
+More :file:`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
+-----------------------------
+
+* :file:`functions.sh`: bash functions used by ``makenemo``, for instance to create the WORK directory
+* :file:`cfg.txt`     : text list of configurations and source directories
+* :file:`bld.cfg`     : FCM rules for compilation
+
+Examples
+--------
+
+.. literalinclude:: ../../../makenemo
+   :language: text
+   :lines: 146-153
+
+Running the model
+=================
+
+Once :file:`makenemo` has run successfully,
+the ``nemo`` executable is available in :file:`./cfgs/MY_CONFIG/EXP00`.
+For the reference configurations, the :file:`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 :file:`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/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/README.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/README.rst	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/README.rst	(revision 11954)
@@ -1,7 +1,7 @@
-:Release:  |release|
-:Date:     |today|
-:SVN rev.: |revision|
+.. todo::
 
-NEMO_ for **Nucleus for European Modelling of the Ocean** is a state-of-the-art modelling framework for
+
+
+NEMO_ for *Nucleus for European Modelling of the Ocean* is a state-of-the-art modelling framework for
 research activities and forecasting services in ocean and climate sciences,
 developed in a sustainable way by a European consortium since 2008.
@@ -15,13 +15,14 @@
 The NEMO ocean model has 3 major components:
 
-- |OPA| models the ocean {thermo}dynamics and solves the primitive equations
-  (``./src/OCE``)
-- |SI3| simulates seaice {thermo}dynamics, brine inclusions and subgrid-scale thickness variations
-  (``./src/ICE``)
-- |TOP| models the {on,off}line oceanic tracers transport and biogeochemical processes
-  (``./src/TOP``)
+- |OCE| models the ocean {thermo}dynamics and solves the primitive equations
+  (:file:`./src/OCE`)
+- |ICE| simulates sea-ice {thermo}dynamics, brine inclusions and
+  subgrid-scale thickness variations (:file:`./src/ICE`)
+- |MBG| models the {on,off}line oceanic tracers transport and biogeochemical processes
+  (:file:`./src/TOP`)
 
-These physical core engines are described in their respective `references`_ that
-must be cited for any work related to their use.
+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:`cite`).
 
 Assets and solutions
@@ -33,16 +34,16 @@
 - 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 (``./cfgs``).
+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
-address specific physical processes(``./tests``).
+The user can also checkout available :doc:`idealized test cases<tests>` that
+address specific physical processes (:file:`./tests`).
 
-A set of :doc:`utilities <tools>` is also provided to {pre,post}process your data (``./tools``).
+A set of :doc:`utilities <tools>` is also provided to {pre,post}process your data (:file:`./tools`).
 
 Project documentation
@@ -50,23 +51,20 @@
 
 A walkthrough tutorial illustrates how to get code dependencies, compile and execute NEMO
-(``./INSTALL.rst``) . 
+(:file:`./INSTALL.rst`).
 
 Reference manuals and quick start guide can be build from source and
-exported to HTML or PDF formats (``./doc``) or
-downloaded directly from the :website:`website<bibliography/documentation>`.
+exported to HTML or PDF formats (:file:`./doc`) or
+downloaded directly from the :forge:`development platform<wiki/Documentations>`.
 
-=========== ===================== ===============
- Component   Reference Manual      Quick start
-=========== ===================== ===============
- |OPA|       |NEMO manual|_        |NEMO guide|
-             :cite:`NEMO_manual`
- |SI3|       |SI3 manual|
-             :cite:`SI3_manual`
- |TOP|       |TOP manual|
-             :cite:`TOP_manual`
-=========== ===================== ===============
+============ ================== ===================
+ Component    Reference Manual   Quick Start Guide
+============ ================== ===================
+ |NEMO-OCE|   |DOI man OCE|_     |DOI qsg|
+ |NEMO-ICE|   |DOI man ICE|
+ |NEMO-MBG|   |DOI man MBG|
+============ ================== ===================
 
 Since 2014 the project has a `Special Issue`_ in the open-access journal
-Geoscientific Model Development (GMD) from the European Geosciences Union (EGU).
+Geoscientific Model Development (GMD) from the European Geosciences Union (EGU_).
 The main scope is to collect relevant manuscripts covering various topics and
 to provide a single portal to assess the model potential and evolution.
@@ -79,22 +77,23 @@
 =================
 
-The NEMO Consortium pulling together 5 European institutes (CMCC_, CNRS_, MOI_, `Met Office`_ and NERC_)
-plans the sustainable development in order to keep a reliable evolving framework since 2008.
+The NEMO Consortium pulling together 5 European institutes
+(CMCC_, CNRS_, MOI_, `Met Office`_ and NERC_) plans the sustainable development in order to
+keep a reliable evolving framework since 2008.
 
-It defines the |NEMO strategy|_ that is implemented by the System Team on a yearly basis in order to
-release a new version almost every four years.
+It defines the |DOI dev stgy|_ that is implemented by the System Team on a yearly basis
+in order to release a new version almost every four years.
 
 When the need arises, :forge:`working groups<wiki/WorkingGroups>` are created or resumed to
 gather the community expertise for advising on the development activities.
 
+.. |DOI dev stgy| replace:: multi-year development strategy
 
-.. Substitutions / Links
+Disclaimer
+==========
 
-.. |NEMO manual| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1464816.svg
-.. |NEMO guide|  image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1475325.svg
-.. |SI3 manual|  image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1471689.svg
-.. |TOP manual|  image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1471700.svg
+The NEMO source code is freely available and distributed under
+:download:`CeCILL v2.0 license <../../../LICENSE>` (GNU GPL compatible).
 
-.. |NEMO strategy| replace:: multi-year development strategy
-
-.. _Special Issue: https://www.geosci-model-dev.net/special_issue40.html
+You can use, modify and/or redistribute the software under its terms,
+but users are provided only with a limited warranty and the software's authors and
+the successive licensor's have only limited liability.
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/REFERENCES.bib
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/REFERENCES.bib	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/REFERENCES.bib	(revision 11954)
@@ -1,59 +1,46 @@
-@manual{NEMO_manual,
-   title={NEMO ocean engine},
-   author={Madec Gurvan and NEMO System Team},
-   organization={NEMO Consortium},
-   journal={Notes du Pôle de modélisation de l\'Institut Pierre-Simon Laplace (IPSL)},
-   number={27},
-   publisher={Zenodo},
-   abstract={The ocean engine of NEMO is a primitive equation model adapted to regional and
-   global ocean circulation problems.
-   It is intended to be a flexible tool for studying the ocean and its interactions with
-   the others components of the earth climate system over a wide range of space and time scales.},
-   doi={10.5281/zenodo.1464816},
-   edition={},
-   year={}
+@manual{NEMO_man,
+   title="NEMO ocean engine",
+   author="NEMO System Team",
+   series="Scientific Notes of Climate Modelling Center",
+   number="27",
+   institution="Institut Pierre-Simon Laplace (IPSL)",
+   publisher="Zenodo",
+   doi="10.5281/zenodo.1464816",
 }
+%   edition="",
+%   year=""
 
-@manual{SI3_manual,
-   title={SI³ – Sea Ice modelling Integrated Initiative – The NEMO Sea Ice engine},
-   author={NEMO Sea Ice Working Group},
-   organization={NEMO Consortium},
-   journal={Notes du Pôle de modélisation de l\'Institut Pierre-Simon Laplace (IPSL)},
-   number={31},
-   publisher={Zenodo},
-   abstract={SI³ (Sea Ice modelling Integrated Initiative) is the sea ice engine of NEMO
-   (Nucleus for European Modelling of the Ocean).
-   SI³ is based on the Arctic Ice Dynamics Joint EXperiment (AIDJEX) framework,
-   combining the ice thickness distribution framework, the conservation of horizontal momentum,
-   an elastic-viscous plastic rheology, and energy-conserving halo-thermodynamics.
-   SI³ is interfaced with the NEMO ocean engine, and, via the OASIS coupler, with
-   several atmospheric general circulation models.
-   It also supports two-way grid embedding via the AGRIF software.},
-   doi={10.5281/zenodo.1471689},
-   edition={},
-   year={}
+@manual{SI3_man,
+   title="Sea Ice modelling Integrated Initiative (SI$^3$) -- The NEMO Sea Ice engine",
+   author="NEMO Sea Ice Working Group",
+   series="Scientific Notes of Climate Modelling Center",
+   number="31",
+   institution="Institut Pierre-Simon Laplace (IPSL)",
+   publisher="Zenodo",
+   doi="10.5281/zenodo.1471689",
 }
+%   edition="",
+%   year=""
 
-@manual{TOP_manual,
-   title={TOP – Tracers in Ocean Paradigm – The NEMO Tracers engine},
-   author={NEMO TOP Working Group},
-   organization={NEMO Consortium},
-   journal={Notes du Pôle de modélisation de l\'Institut Pierre-Simon Laplace (IPSL)},
-   number={28},
-   publisher={Zenodo},
-   abstract={},
-   doi={10.5281/zenodo.1471700},
-   edition={},
-   year={}
+@manual{TOP_man,
+   title="Tracers in Ocean Paradigm (TOP) -- The NEMO Tracers engine",
+   author="NEMO TOP Working Group",
+   series="Scientific Notes of Climate Modelling Center",
+   number="28",
+   institution="Institut Pierre-Simon Laplace (IPSL)",
+   publisher="Zenodo",
+   doi="10.5281/zenodo.1471700",
 }
+%   edition="",
+%   year=""
 
-@Article{gmd-8-1245-2015,
-   author = {Vidard, A. and Bouttier, P.-A. and Vigilant, F.},
-   title = {{NEMOTAM}: {T}angent and {A}djoint {M}odels for the ocean modelling platform {NEMO}},
-   journal = {Geoscientific Model Development},
-   volume = {8},
-   year = {2015},
-   number = {4},
-   pages = {1245--1257},
-   doi = {10.5194/gmd-8-1245-2015}
+@article{TAM_pub,
+   author = "Vidard, A. and Bouttier, P.-A. and Vigilant, F.",
+   title = "NEMOTAM: Tangent and Adjoint Models for the ocean modelling platform NEMO",
+   journal = "Geoscientific Model Development",
+   volume = "8",
+   year = "2015",
+   number = "4",
+   pages = "1245--1257",
+   doi = "10.5194/gmd-8-1245-2015"
 }
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/RELEASE_NOTES.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/RELEASE_NOTES.rst	(revision 11712)
+++ 	(revision )
@@ -1,129 +1,0 @@
-*************
-Release Notes
-*************
-
-New sea-ice component SI3 (in place of LIMx)
-============================================
-
-- Physics
-
-  - Lateral melting
-  - Melt ponds: constant or :doi:`Holland et al. 2012<10.1175/JCLI-D-11-00078.1>` formulation (and soon topographic melt ponds)
-  - Ice-atm. drags from :doi:`Lupkes et al. 2012<10.1029/2012JD017630>` (depending on ice concentration) or :doi:`Lupkes et al. 2015<10.1002/2014JD022418>` (depending on sea ice concentration and atm. stability)
-  - Landfast ice (:doi:`Lemieux et al. 2016<10.1002/2016JC012006>`)
-
-- Numerics
-
-  - Advection: Ultimate-Macho scheme
-  - Rheology: adaptive EVP (:doi:`Kimmritz et al. 2017<10.1016/j.ocemod.2016.03.004>`)
-  - Coupling interface: conductivity as surface forcing instead of heat fluxes (Met Office requirement)
-
-- Performance: all thermodynamics in 1D and reduced mpp communications
-- Usability (users & developers friendly)
-
-  - Comprehensive set of outputs (universal units and understandable names + includes CMIP)
-  - New architecture and namelist
-  - All processes can be decoupled from each other (switch on/off)
-  - Ice categories bounds can be defined by the user or set automatically
-  - For open boundaries, the number of ice categories from the forcing model can be different from the number of categories in the regional simulation
-  - Fully compatible with AGRIF_
-  - Revised documentation 
-
-AGRIF for embedded zooms
-========================
-
-- Now compatible with new sea ice component
-- Now compatible with z* coordinate
-- Extended ghost cells area to properly handle scheme with spatial order >2
-- Added vertical refinement (beta)
-- Nesting tools for setup now up to date and working 
-
-Enhancements
-============
-
-- Fix for tracer conservation with split explicit free surface
-- Bulk formulae : move to aerobulk package (:doi:`Brodeau et al. 2016<10.1175/JPO-D-16-0169.1>`), i.e. NCAR, COARE and ECMWF bulk (remove Clio and MFS bulk)
-- Wetting and drying
-- Added tidal self attraction and loading either read from a file or from usual "scalar" approximation
-- Add a 4th order centered (CEN) and Flux Corrected Transport (FCT) tracer advection
-  (using a 4th compact in the vertical)
-- iso-neutral mixing (iso and triad operators):
-  add the Method of Stabilizing Correction (MSC) (more accurate calculation) + add a bilaplacian case
-- Lateral physics (``LDF``): scale aware setting of eddy viscosity and diffusivity
-- Vorticity: 2 new energy conserving scheme: ENT with Coriolis defined at T-point (better for Flux form) and EET a variant of EEN where e3t is used instead of e3f (solved the issue with e3f specification but is not enstrophy conserving) 
-
-Test Cases
-==========
-
-The first test cases available for now are:
-
-- ``CANAL``: east-west periodic canal of variable size with several initial states and associated geostrophic currents (zonal jets or vortex)
-- ``ICE_AGRIF``: east-west + north-south periodic channel. The common configuration includes an AGRIF zoom (1:3) in the middle of the basin to test how an ice patch is advected through it but one can also test the advection schemes (Prather and Ultimate-Macho) by removing the ``key_agrif`` in the cpp keys
-- ``ISOMIP``: simple box configuration with an ice shelf with simple geometry on top. The purpose of this test case is to evaluate the impact of various schemes and new development with iceshelf cavities. The exact original setup is described ​here
-- ``LOCK-EXCHANGE``: classical fluid dynamics experiment that has been adapted by Haidvogel and Beckmann (1999) for testing advection schemes in ocean circulation models. It has been used by several authors including Burchard and Bolding (2002) and :doi:`Ilıcak et al. (2012)<10.1016/j.ocemod.2011.10.003>`. The ``LOCK EXCHANGE`` experiment can in particular illustrate the impact of different choices of numerical schemes and/or subgrid closures on spurious interior mixing
-- ``OVERFLOW``: illustrates the impact of different choices of numerical schemes and/or subgrid closures on spurious interior mixing close to bottom topography. It is adapted from the non-rotating overflow configuration described in Haidvogel and Beckmann (1999) and further used by :doi:`Ilıcak et al. (2012)<10.1016/j.ocemod.2011.10.003>`
-- ``VORTEX``: illustrates the propagation of an anticyclonic eddy over a Beta plan and flat bottom. It is implemented here with an online refined subdomain (thanks to ``AGRIF`` library) out of which the vortex propagates. It serves as a benchmark to diagnose nesting errors as in :doi:`Debreu et al. (2012)<10.1016/j.ocemod.2012.03.003>`, :doi:`Penven et al. (2006)<10.1016/j.ocemod.2005.05.002>` and :doi:`Spall and Holland (1991)<10.1175/1520-0485(1991)021<0205:ANPEMF>2.0.CO;2>`
-- ``WAD``: 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
-
-New Reference configurations
-============================
-
-``AGRIF_DEMO``: 2 interlocked zooms (1:4 & 1:3) in the Nordic Seas + 1 zoom (1:1) at the equator
-
-``SPITZ12``: regional configuration around the Svalbard archipelago 
-
-Wave coupling
-=============
-
-Coupled interface to external wave model
-
-Large scale wave interaction process added in momentum and tracer equations 
-
-Passive tracer TOP and biogeochemical PISCES components
-=======================================================
-
-- The passive tracers transport component was redesigned toward a modular structure and users can enable each module directly through logical flags in namelist_top (no more fortran macros!)
-- :doc:`TOP on-line user documentation<tracers>`
-- TOP currently accounts for the following 5 modules: ``CFC`` contains inorganic carbon tracers (CFC11/CFC12/SF6), ``MY_TRC`` is a template for new modules (or external couplings), ``AGE`` deals with water age tracking, ``C14`` as a radiocarbon passive tracer, and the companion ecosystem model ``PISCES``
-- A generalized infrastructure was developed to handle the prescription of either surface, coastal, or open boundaries conditions for each passive tracer
-- A new configuration, named ``ORCA2_OFF_TRC``, was created to provide a benchmark simulation environment to deal with inert carbon tracers dynamics by exploiting the offline coupling with NEMO
-- PISCES model contains new developments and modifications:
-
-  - Particulate Organic Carbon (POC) component comes with a new liability scheme, while the former Kriest parametrisation was superseded
-  - A complex iron chemistry scheme is now available, with an improved description of ligands for the marine iron cycle
-  - Carbonate chemistry is based on MOCSY 2.0 routines (see :doi:`10.5194/gmd-8-485-2015 <Orr and Epitalon, 2015>`), by complying also with CMIP6 standards
-  - Ecosystem components can be optionally modelled by means of explicit nutrient quotas (PISCES-QUOTA) 
-
-High Performance Computing (HPC): performances improvements
-===========================================================
-
-- Reduce number of MPI communications
-  (suppression of redundant communications, gather multiple communications into one)
-- Use of MPI-3 asynchronous routines for performance (use ``key_mpi2`` if MPI-3 not available)
-- Back to standard dynamical allocation (remove of wrk_alloc/dealloc statements)
-- :xios:`XIOS software<>` for IOs version 2.5 as default, and optionally available for restarts 
-
-Simplification and robustness
-=============================
-
-- Revised structure of ``namelist_ref`` / ``namelist_cfg`` and default reference values
-- Lateral physics (``LDF``): simplification of user interface and removal of CPP keys
-- Vertical physics (``ZDF``) (modularity, share shear production calculation between TKE and GKS, removal of all ZDF CPP keys, removal of ``avmu`` & ``avmv``, minimization of MPP comm.: ~15 removed)
-- Remove the split-explicit ZDF scheme for both ``TRA`` and ``DYN``
-- Remove the acceleration of convergence
-- Generalised ``lbc_lnk`` and ``lbc_nfd``
-- Unify mppini
-- Use non uniform jpi/jpj with dynamic allocation to avoid ghost rows/columns
-- MPI Message passing re coded
-- Configuration interface completely rewritten (``DOM`` module mainly suppressed , and in place: ``domain_cfg.nc`` file, or ``usr_def`` module) 
-
-Collaborative Development Environment
-=====================================
-
-- Access to information on wiki reorganised through portals for users/developers/System Team and complete refactoring of all pages and their layout
-- Reorganisation of SVN repository to be compliant with usual directory tree and facilitate building of the executable
-- Define and install a separate repository for test cases to all easy contributions from the community
-- :forge:`Forums<discussion>` created
-- :website:`Public web site<>` has been revamped and cleaned using Wordpress
-- New mailing lists have been set up
-- Improvements of reliability through automatic and regular testing of the changes made in repository 
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/AGRIF_DEMO/EXPREF/namelist_ice_cfg
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/AGRIF_DEMO/EXPREF/namelist_ice_cfg	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/AGRIF_DEMO/EXPREF/namelist_ice_cfg	(revision 11954)
@@ -38,4 +38,5 @@
 &namdyn_rhg     !   Ice rheology
 !------------------------------------------------------------------------------
+      ln_aEVP       = .false.          !     adaptive rheology (Kimmritz et al. 2016 & 2017)
 /
 !------------------------------------------------------------------------------
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/AGRIF_DEMO/README.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/AGRIF_DEMO/README.rst	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/AGRIF_DEMO/README.rst	(revision 11954)
@@ -2,4 +2,8 @@
 Embedded zooms
 **************
+
+.. todo::
+
+
 
 .. contents::
@@ -9,24 +13,26 @@
 ========
 
-AGRIF (Adaptive Grid Refinement In Fortran) is a library that allows the seamless space and time refinement over
-rectangular regions in NEMO.
+AGRIF (Adaptive Grid Refinement In Fortran) is a library that
+allows the seamless space and time refinement over rectangular regions in NEMO.
 Refinement factors can be odd or even (usually lower than 5 to maintain stability).
-Interaction between grid is "two-ways" in the sense that the parent grid feeds the child grid open boundaries and
-the child grid provides volume averages of prognostic variables once a given number of time step is completed.
+Interaction between grid is "two-ways" in the sense that
+the parent grid feeds the child grid open boundaries and
+the child grid provides volume averages of prognostic variables once
+a given number of time step is completed.
 These pages provide guidelines how to use AGRIF in NEMO.
-For a more technical description of the library itself, please refer to http://agrif.imag.fr.
+For a more technical description of the library itself, please refer to AGRIF_.
 
 Compilation
 ===========
 
-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
 
-	./makenemo add_key 'key_agrif'
+   ./makenemo [...] add_key 'key_agrif'
 
-Although this is transparent to users, the way the code is processed during compilation is different from
-the standard case:
-a preprocessing stage (the so called "conv" program) translates the actual code so that
+Although this is transparent to users,
+the way the code is processed during compilation is different from the standard case:
+a preprocessing stage (the so called ``conv`` program) translates the actual code so that
 saved arrays may be switched in memory space from one domain to an other.
 
@@ -34,25 +40,26 @@
 ================================
 
-An additional text file ``AGRIF_FixedGrids.in`` is required at run time.
+An additional text file :file:`AGRIF_FixedGrids.in` is required at run time.
 This is where the grid hierarchy is defined.
-An example of such a file, here taken from the ``ICEDYN`` test case, is given below::
+An example of such a file, here taken from the ``ICEDYN`` test case, is given below
 
-	1
-	34 63 34 63 3 3 3
-	0
+.. literalinclude:: ../../../tests/ICE_AGRIF/EXPREF/AGRIF_FixedGrids.in
 
 The first line indicates the number of zooms (1).
 The second line contains the starting and ending indices in both directions on the root grid
-(imin=34 imax=63 jmin=34 jmax=63) followed by the space and time refinement factors (3 3 3).
+(``imin=34 imax=63 jmin=34 jmax=63``) followed by the space and time refinement factors (3 3 3).
 The last line is the number of child grid nested in the refined region (0).
 A more complex example with telescoping grids can be found below and
-in the ``AGRIF_DEMO`` reference configuration directory.
+in the :file:`AGRIF_DEMO` reference configuration directory.
 
-[Add some plots here with grid staggering and positioning ?]
+.. todo::
 
-When creating the nested domain, one must keep in mind that the child domain is shifted toward north-east and
-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.  
+   Add some plots here with grid staggering and positioning?
+
+When creating the nested domain, one must keep in mind that
+the child domain is shifted toward north-east and
+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.
 
 .. image:: _static/agrif_grid_position.jpg
@@ -62,14 +69,15 @@
 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
 =============
 
-Knowing the refinement factors and area, a ``NESTING`` pre-processing tool may help to create needed input files
+Knowing the refinement factors and area,
+a ``NESTING`` pre-processing tool may help to create needed input files
 (mesh file, restart, climatological and forcing files).
 The key is to ensure volume matching near the child grid interface,
-a step done by invoking the ``Agrif_create_bathy.exe`` program.
-You may use the namelists provided in the ``NESTING`` directory as a guide.
+a step done by invoking the :file:`Agrif_create_bathy.exe` program.
+You may use the namelists provided in the :file:`NESTING` directory as a guide.
 These correspond to the namelists used to create ``AGRIF_DEMO`` inputs.
 
@@ -78,30 +86,21 @@
 
 Each child grid expects to read its own namelist so that different numerical choices can be made
-(these should be stored in the form ``1_namelist_cfg``, ``2_namelist_cfg``, etc... according to their rank in
-the grid hierarchy).
+(these should be stored in the form :file:`1_namelist_cfg`, :file:`2_namelist_cfg`, etc...
+according to their rank in the grid hierarchy).
 Consistent time steps and number of steps with the chosen time refinement have to be provided.
 Specific to AGRIF is the following block:
 
-.. code-block:: fortran
-
-	!-----------------------------------------------------------------------
-	&namagrif      !  AGRIF zoom                                            ("key_agrif")
-	!-----------------------------------------------------------------------
-	   ln_spc_dyn    = .true.  !  use 0 as special value for dynamics
-	   rn_sponge_tra = 2880.   !  coefficient for tracer   sponge layer [m2/s]
-	   rn_sponge_dyn = 2880.   !  coefficient for dynamics sponge layer [m2/s]
-	   ln_chk_bathy  = .false. !  =T  check the parent bathymetry
-	/             
+.. literalinclude:: ../../namelists/namagrif
+   :language: fortran
 
 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/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/ORCA2_ICE_PISCES/EXPREF/namelist_ice_cfg
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/ORCA2_ICE_PISCES/EXPREF/namelist_ice_cfg	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/ORCA2_ICE_PISCES/EXPREF/namelist_ice_cfg	(revision 11954)
@@ -38,4 +38,5 @@
 &namdyn_rhg     !   Ice rheology
 !------------------------------------------------------------------------------
+      ln_aEVP       = .false.          !     adaptive rheology (Kimmritz et al. 2016 & 2017)
 /
 !------------------------------------------------------------------------------
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/README.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/README.rst	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/README.rst	(revision 11954)
@@ -1,5 +1,9 @@
-************************
-Reference configurations
-************************
+********************************
+Run the Reference configurations
+********************************
+
+.. todo::
+
+   Lack of illustrations for ref. cfgs, and more generally in the guide.
 
 NEMO is distributed with a set of reference configurations allowing both
@@ -7,4 +11,8 @@
 the developer to test/validate his NEMO developments (using SETTE package).
 
+.. contents::
+   :local:
+   :depth: 1
+
 .. attention::
 
@@ -21,42 +29,49 @@
 ===========================================================
 
-A user who wants to compile the ORCA2_ICE_PISCES_ reference configuration using ``makenemo``
-should use the following, by selecting among available architecture file or providing a user defined one:
+To compile the ORCA2_ICE_PISCES_ reference configuration using :file:`makenemo`,
+one should use the following, by selecting among available architecture file or
+providing a user defined one:
 
 .. code-block:: console
-                
-   $ ./makenemo -r 'ORCA2_ICE_PISCES' -m 'my-fortran.fcm' -j '4'
+
+   $ ./makenemo -r 'ORCA2_ICE_PISCES' -m 'my_arch' -j '4'
 
 A new ``EXP00`` folder will be created within the selected reference configurations,
-namely ``./cfgs/ORCA2_ICE_PISCES/EXP00``,
-where it will be necessary to uncompress the Input & Forcing Files listed in the above table.
+namely ``./cfgs/ORCA2_ICE_PISCES/EXP00``.
+It will be necessary to uncompress the archives listed in the above table for
+the given reference configuration that includes input & forcing files.
 
 Then it will be possible to launch the execution of the model through a runscript
 (opportunely adapted to the user system).
-   
+
 List of Configurations
 ======================
 
-All forcing files listed below in the table are available from |NEMO archives URL|_
-
-.. |NEMO archives URL| image:: https://www.zenodo.org/badge/DOI/10.5281/zenodo.1472245.svg
-.. _NEMO archives URL: https://doi.org/10.5281/zenodo.1472245
-
-====================== ===== ===== ===== ======== ======= ================================================
- Configuration                     Component(s)                            Input & Forcing File(s)
----------------------- ---------------------------------- ------------------------------------------------
- Name                   OPA   SI3   TOP   PISCES   AGRIF
-====================== ===== ===== ===== ======== ======= ================================================
- AGRIF_DEMO_             X     X                     X     AGRIF_DEMO_v4.0.tar, ORCA2_ICE_v4.0.tar
- AMM12_                  X                                 AMM12_v4.0.tar
- C1D_PAPA_               X                                 INPUTS_C1D_PAPA_v4.0.tar
- GYRE_BFM_               X           X                     *none*
- GYRE_PISCES_            X           X      X              *none*
- ORCA2_ICE_PISCES_       X     X     X      X              ORCA2_ICE_v4.0.tar, INPUTS_PISCES_v4.0.tar
- ORCA2_OFF_PISCES_                   X      X              ORCA2_OFF_v4.0.tar, INPUTS_PISCES_v4.0.tar
- ORCA2_OFF_TRC_                      X                     ORCA2_OFF_v4.0.tar
- ORCA2_SAS_ICE_                X                           ORCA2_ICE_v4.0.tar, INPUTS_SAS_v4.0.tar
- SPITZ12_                X     X                           SPITZ12_v4.0.tar
-====================== ===== ===== ===== ======== ======= ================================================
+All forcing files listed below in the table are available from |DOI data|_
+
+=================== === === === === === ==================================
+ Configuration       Component(s)        Archives (input & forcing files)
+------------------- ------------------- ----------------------------------
+ Name                O   S   T   P   A
+=================== === === === === === ==================================
+ AGRIF_DEMO_         X   X           X   AGRIF_DEMO_v4.0.tar,
+                                         ORCA2_ICE_v4.0.tar
+ AMM12_              X                   AMM12_v4.0.tar
+ C1D_PAPA_           X                   INPUTS_C1D_PAPA_v4.0.tar
+ GYRE_BFM_           X       X           *none*
+ GYRE_PISCES_        X       X   X       *none*
+ ORCA2_ICE_PISCES_   X   X   X   X       ORCA2_ICE_v4.0.tar,
+                                         INPUTS_PISCES_v4.0.tar
+ ORCA2_OFF_PISCES_           X   X       ORCA2_OFF_v4.0.tar,
+                                         INPUTS_PISCES_v4.0.tar
+ ORCA2_OFF_TRC_              X           ORCA2_OFF_v4.0.tar
+ ORCA2_SAS_ICE_          X               ORCA2_ICE_v4.0.tar,
+                                         INPUTS_SAS_v4.0.tar
+ SPITZ12_            X   X               SPITZ12_v4.0.tar
+=================== === === === === === ==================================
+
+.. admonition:: Legend for component combination
+
+   O for OCE, S for SI\ :sup:`3`, T for TOP, P for PISCES and A for AGRIF
 
 AGRIF_DEMO
@@ -72,9 +87,14 @@
 particular interest to test sea ice coupling.
 
+.. image:: _static/AGRIF_DEMO_no_cap.jpg
+   :scale: 66%
+   :align: center
+
 The 1:1 grid can be used alone as a benchmark to check that
-the model solution is not corrupted by grid exchanges. 
+the model solution is not corrupted by grid exchanges.
 Note that since grids interact only at the baroclinic time level,
 numerically exact results can not be achieved in the 1:1 case.
-Perfect reproducibility is obtained only by switching to a fully explicit setup instead of a split explicit free surface scheme.
+Perfect reproducibility is obtained only by switching to a fully explicit setup instead of
+a split explicit free surface scheme.
 
 AMM12
@@ -85,5 +105,8 @@
 a regular horizontal grid of ~12 km of resolution (see :cite:`ODEA2012`).
 
-This configuration allows to tests several features of NEMO specifically addressed to the shelf seas. 
+.. image:: _static/AMM_domain.png
+   :align: center
+
+This configuration allows to tests several features of NEMO specifically addressed to the shelf seas.
 In particular, ``AMM12`` accounts for vertical s-coordinates system, GLS turbulence scheme,
 tidal lateral boundary conditions using a flather scheme (see more in ``BDY``).
@@ -99,21 +122,33 @@
 --------
 
-``C1D_PAPA`` is a 1D configuration for the `PAPA station <http://www.pmel.noaa.gov/OCS/Papa/index-Papa.shtml>`_ located in the northern-eastern Pacific Ocean at 50.1°N, 144.9°W.
-See `Reffray et al. (2015) <http://www.geosci-model-dev.net/8/69/2015>`_ for the description of its physical and numerical turbulent-mixing behaviour.
-
-The water column setup, called NEMO1D, is activated with the inclusion of the CPP key ``key_c1d`` and
-has a horizontal domain of 3x3 grid points.
-
-This reference configuration uses 75 vertical levels grid (1m at the surface), GLS turbulence scheme with K-epsilon closure and the NCAR bulk formulae.
+.. figure:: _static/Papa2015.jpg
+   :height: 225px
+   :align:  left
+
+``C1D_PAPA`` is a 1D configuration for the `PAPA station`_ located in
+the northern-eastern Pacific Ocean at 50.1°N, 144.9°W.
+See :gmd:`Reffray et al. (2015) <8/69/2015>` for the description of
+its physical and numerical turbulent-mixing behaviour.
+
+| The water column setup, called NEMO1D, is activated with
+  the inclusion of the CPP key ``key_c1d`` and
+  has a horizontal domain of 3x3 grid points.
+| This reference configuration uses 75 vertical levels grid (1m at the surface),
+  GLS turbulence scheme with K-epsilon closure and the NCAR bulk formulae.
+
 Data provided with ``INPUTS_C1D_PAPA_v4.0.tar`` file account for:
 
-- ``forcing_PAPASTATION_1h_y201[0-1].nc`` : ECMWF operational analysis atmospheric forcing rescaled to 1h (with long and short waves flux correction) for years 2010 and 2011
-- ``init_PAPASTATION_m06d15.nc`` : Initial Conditions from observed data and Levitus 2009 climatology
-- ``chlorophyll_PAPASTATION.nc`` : surface chlorophyll file from Seawifs data
+- :file:`forcing_PAPASTATION_1h_y201[0-1].nc`:
+  ECMWF operational analysis atmospheric forcing rescaled to 1h
+  (with long and short waves flux correction) for years 2010 and 2011
+- :file:`init_PAPASTATION_m06d15.nc`: Initial Conditions from
+  observed data and Levitus 2009 climatology
+- :file:`chlorophyll_PAPASTATION.nc`: surface chlorophyll file from Seawifs data
 
 GYRE_BFM
 --------
 
-``GYRE_BFM`` shares the same physical setup of GYRE_PISCES_, but NEMO is coupled with the `BFM <http://www.bfm-community.eu/>`_ biogeochemical model as described in ``./cfgs/GYRE_BFM/README``.
+``GYRE_BFM`` shares the same physical setup of GYRE_PISCES_,
+but NEMO is coupled with the `BFM`_ biogeochemical model as described in ``./cfgs/GYRE_BFM/README``.
 
 GYRE_PISCES
@@ -123,43 +158,42 @@
 in the Beta-plane approximation with a regular 1° horizontal resolution and 31 vertical levels,
 with PISCES BGC model :cite:`gmd-8-2465-2015`.
-Analytical forcing for heat, freshwater and wind-stress fields are applied.  
-
-This configuration acts also as demonstrator of the **user defined setup** (``ln_read_cfg = .false.``) and
-grid setting are handled through the ``&namusr_def`` controls in ``namelist_cfg``:
+Analytical forcing for heat, freshwater and wind-stress fields are applied.
+
+This configuration acts also as demonstrator of the **user defined setup**
+(``ln_read_cfg = .false.``) and grid setting are handled through
+the ``&namusr_def`` controls in :file:`namelist_cfg`:
 
 .. literalinclude:: ../../../cfgs/GYRE_PISCES/EXPREF/namelist_cfg
    :language: fortran
-   :lines: 34-42
+   :lines:    35-41
 
 Note that, the default grid size is 30x20 grid points (with ``nn_GYRE = 1``) and
 vertical levels are set by ``jpkglo``.
-The specific code changes can be inspected in ``./src/OCE/USR``.
-
-**Running GYRE as a benchmark** :
-this simple configuration can be used as a benchmark since it is easy to increase resolution,
-with the drawback of getting results that have a very limited physical meaning.
-
-GYRE grid resolution can be increased at runtime by setting a different value of ``nn_GYRE`` (integer multiplier scaling factor), as described in the following table: 
-
-=========== ========= ========== ============ ===================
-``nn_GYRE``  *jpiglo*  *jpjglo*   ``jpkglo``   **Equivalent to**
-=========== ========= ========== ============ ===================
- 1           30        20         31           GYRE 1°
- 25          750       500        101          ORCA 1/2°
- 50          1500      1000       101          ORCA 1/4°
- 150         4500      3000       101          ORCA 1/12°
- 200         6000      4000       101          ORCA 1/16°
-=========== ========= ========== ============ ===================
-
-Note that, it is necessary to set ``ln_bench = .true.`` in ``namusr_def`` to
-avoid problems in the physics computation and that
-the model timestep should be adequately rescaled. 
-
-For example if ``nn_GYRE = 150``, equivalent to an ORCA 1/12° grid,
-the timestep ``rn_rdt = 1200`` should be set to 1200 seconds
-
-Differently from previous versions of NEMO,
-the code uses by default the time-splitting scheme and
-internally computes the number of sub-steps. 
+The specific code changes can be inspected in :file:`./src/OCE/USR`.
+
+.. rubric:: Running GYRE as a benchmark
+
+| This simple configuration can be used as a benchmark since it is easy to increase resolution,
+  with the drawback of getting results that have a very limited physical meaning.
+| GYRE grid resolution can be increased at runtime by setting a different value of ``nn_GYRE``
+  (integer multiplier scaling factor), as described in the following table:
+
+=========== ============ ============ ============ ===============
+``nn_GYRE``  ``jpiglo``   ``jpjglo``   ``jpkglo``   Equivalent to
+=========== ============ ============ ============ ===============
+ 1           30           20           31           GYRE 1°
+ 25          750          500          101          ORCA 1/2°
+ 50          1500         1000         101          ORCA 1/4°
+ 150         4500         3000         101          ORCA 1/12°
+ 200         6000         4000         101          ORCA 1/16°
+=========== ============ ============ ============ ===============
+
+| Note that, it is necessary to set ``ln_bench = .true.`` in ``&namusr_def`` to
+  avoid problems in the physics computation and that
+  the model timestep should be adequately rescaled.
+| For example if ``nn_GYRE = 150``, equivalent to an ORCA 1/12° grid,
+  the timestep ``rn_rdt`` should be set to 1200 seconds
+  Differently from previous versions of NEMO, the code uses by default the time-splitting scheme and
+  internally computes the number of sub-steps.
 
 ORCA2_ICE_PISCES
@@ -174,41 +208,37 @@
 the ratio of anisotropy is nearly one everywhere
 
-this configuration uses the three components 
-
-- |OPA|, the ocean dynamical core 
-- |SI3|, the thermodynamic-dynamic sea ice model.
-- |TOP|, passive tracer transport module and PISCES BGC model :cite:`gmd-8-2465-2015`
+This configuration uses the three components
+
+- |OCE|, the ocean dynamical core
+- |ICE|, the thermodynamic-dynamic sea ice model.
+- |MBG|, passive tracer transport module and PISCES BGC model :cite:`gmd-8-2465-2015`
 
 All components share the same grid.
-
 The model is forced with CORE-II normal year atmospheric forcing and
 it uses the NCAR bulk formulae.
 
-In this ``ORCA2_ICE_PISCES`` configuration,
-AGRIF nesting can be activated that includes a nested grid in the Agulhas region.
-
-To set up this configuration, after extracting NEMO:
-
-Build your AGRIF configuration directory from ``ORCA2_ICE_PISCES``,
-with the ``key_agrif`` CPP key activated:
-
-.. code-block:: console
-                
-        $ ./makenemo -r 'ORCA2_ICE_PISCES' -n 'AGRIF' add_key 'key_agrif'
-
-By using the input files and namelists for ``ORCA2_ICE_PISCES``,
-the AGRIF test configuration is ready to run.
-
-**Ocean Physics**
-
-- *horizontal diffusion on momentum*: the eddy viscosity coefficient depends on the geographical position. It is taken as 40000 m^2/s, reduced in the equator regions (2000 m^2/s) excepted near the western boundaries.
-- *isopycnal diffusion on tracers*: the diffusion acts along the isopycnal surfaces (neutral surface) with an eddy diffusivity coefficient of 2000 m^2/s.
-- *Eddy induced velocity parametrization* with a coefficient that depends on the growth rate of baroclinic instabilities (it usually varies from 15 m^2/s to 3000 m^2/s).
-- *lateral boundary conditions* : zero fluxes of heat and salt and no-slip conditions are applied through lateral solid boundaries.
-- *bottom boundary condition* : zero fluxes of heat and salt are applied through the ocean bottom.
-  The Beckmann [19XX] simple bottom boundary layer parameterization is applied along continental slopes.
-  A linear friction is applied on momentum.
-- *convection*: the vertical eddy viscosity and diffusivity coefficients are increased to 1 m^2/s in case of static instability.
-- *time step* is 5760sec (1h36') so that there is 15 time steps in one day.
+.. rubric:: Ocean Physics
+
+:horizontal diffusion on momentum:
+   the eddy viscosity coefficient depends on the geographical position.
+   It is taken as 40000 m\ :sup:`2`/s, reduced in the equator regions (2000 m\ :sup:`2`/s)
+   excepted near the western boundaries.
+:isopycnal diffusion on tracers:
+   the diffusion acts along the isopycnal surfaces (neutral surface) with
+   an eddy diffusivity coefficient of 2000 m\ :sup:`2`/s.
+:Eddy induced velocity parametrization:
+   With a coefficient that depends on the growth rate of baroclinic instabilities
+   (it usually varies from 15 m\ :sup:`2`/s to 3000 m\ :sup:`2`/s).
+:lateral boundary conditions:
+   Zero fluxes of heat and salt and no-slip conditions are applied through lateral solid boundaries.
+:bottom boundary condition:
+   Zero fluxes of heat and salt are applied through the ocean bottom.
+   The Beckmann [19XX] simple bottom boundary layer parameterization is applied along
+   continental slopes.
+   A linear friction is applied on momentum.
+:convection:
+   The vertical eddy viscosity and diffusivity coefficients are increased to 1 m\ :sup:`2`/s in
+   case of static instability.
+:time step: is 5760sec (1h36') so that there is 15 time steps in one day.
 
 ORCA2_OFF_PISCES
@@ -218,34 +248,34 @@
 but only PISCES model is an active component of TOP.
 
-
 ORCA2_OFF_TRC
 -------------
 
-``ORCA2_OFF_TRC`` is based on the ORCA2 global ocean configuration
-(see ORCA2_ICE_PISCES_ for general description) along with the tracer passive transport module (TOP), but dynamical fields are pre-calculated and read with specific time frequency.
-
-This enables for an offline coupling of TOP components,
-here specifically inorganic carbon compounds (cfc11, cfc12, sf6, c14) and water age module (age).
-See ``namelist_top_cfg`` to inspect the selection of each component with the dedicated logical keys.
+| ``ORCA2_OFF_TRC`` is based on the ORCA2 global ocean configuration
+  (see ORCA2_ICE_PISCES_ for general description) along with
+  the tracer passive transport module (TOP),
+  but dynamical fields are pre-calculated and read with specific time frequency.
+| This enables for an offline coupling of TOP components,
+  here specifically inorganic carbon compounds (CFC11, CFC12, SF6, C14) and water age module (age).
+  See :file:`namelist_top_cfg` to inspect the selection of
+  each component with the dedicated logical keys.
 
 Pre-calculated dynamical fields are provided to NEMO using
-the namelist ``&namdta_dyn``  in ``namelist_cfg``,
+the namelist ``&namdta_dyn``  in :file:`namelist_cfg`,
 in this case with a 5 days frequency (120 hours):
 
-.. literalinclude:: ../../../cfgs/GYRE_PISCES/EXPREF/namelist_ref
+.. literalinclude:: ../../namelists/namdta_dyn
    :language: fortran
-   :lines: 935-960
-
-Input dynamical fields for this configuration (``ORCA2_OFF_v4.0.tar``) comes from
+
+Input dynamical fields for this configuration (:file:`ORCA2_OFF_v4.0.tar`) comes from
 a 2000 years long climatological simulation of ORCA2_ICE using ERA40 atmospheric forcing.
 
-Note that, this configuration default uses linear free surface (``ln_linssh = .true.``) assuming that
-model mesh is not varying in time and
-it includes the bottom boundary layer parameterization (``ln_trabbl = .true.``) that
-requires the provision of bbl coefficients through ``sn_ubl`` and ``sn_vbl`` fields.
-
-It is also possible to activate PISCES model (see ``ORCA2_OFF_PISCES``) or
-a user defined set of tracers and source-sink terms with ``ln_my_trc = .true.``
-(and adaptation of ``./src/TOP/MY_TRC`` routines).
+| Note that,
+  this configuration default uses linear free surface (``ln_linssh = .true.``) assuming that
+  model mesh is not varying in time and
+  it includes the bottom boundary layer parameterization (``ln_trabbl = .true.``) that
+  requires the provision of BBL coefficients through ``sn_ubl`` and ``sn_vbl`` fields.
+| It is also possible to activate PISCES model (see ``ORCA2_OFF_PISCES``) or
+  a user defined set of tracers and source-sink terms with ``ln_my_trc = .true.``
+  (and adaptation of ``./src/TOP/MY_TRC`` routines).
 
 In addition, the offline module (OFF) allows for the provision of further fields:
@@ -254,34 +284,32 @@
    by including an input datastream similarly to the following:
 
-.. code-block:: fortran
-
-   sn_rnf  = 'dyna_grid_T', 120, 'sorunoff' , .true., .true., 'yearly', '', '', ''
-
-2. **VVL dynamical fields**,
-   in the case input data were produced by a dyamical core using variable volume (``ln_linssh = .false.``)
-   it necessary to provide also diverce and E-P at before timestep by
+   .. code-block:: fortran
+
+      sn_rnf  = 'dyna_grid_T', 120, 'sorunoff' , .true., .true., 'yearly', '', '', ''
+
+2. **VVL dynamical fields**, in the case input data were produced by a dyamical core using
+   variable volume (``ln_linssh = .false.``)
+   it is necessary to provide also diverce and E-P at before timestep by
    including input datastreams similarly to the following
 
-.. code-block:: fortran
-
-   sn_div  = 'dyna_grid_T', 120, 'e3t'      , .true., .true., 'yearly', '', '', ''
-   sn_empb = 'dyna_grid_T', 120, 'sowaflupb', .true., .true., 'yearly', '', '', ''
-
+   .. code-block:: fortran
+
+      sn_div  = 'dyna_grid_T', 120, 'e3t'      , .true., .true., 'yearly', '', '', ''
+      sn_empb = 'dyna_grid_T', 120, 'sowaflupb', .true., .true., 'yearly', '', '', ''
 
 More details can be found by inspecting the offline data manager in
-the routine ``./src/OFF/dtadyn.F90``.
+the routine :file:`./src/OFF/dtadyn.F90`.
 
 ORCA2_SAS_ICE
 -------------
 
-ORCA2_SAS_ICE is a demonstrator of the Stand-Alone Surface (SAS) module and
-it relies on ORCA2 global ocean configuration (see ORCA2_ICE_PISCES_ for general description).
-
-The standalone surface module allows surface elements such as sea-ice, iceberg drift, and
-surface fluxes to be run using prescribed model state fields.
-It can profitably be used to compare different bulk formulae or
-adjust the parameters of a given bulk formula.
-
-More informations about SAS can be found in NEMO manual.
+| ORCA2_SAS_ICE is a demonstrator of the Stand-Alone Surface (SAS) module and
+  it relies on ORCA2 global ocean configuration (see ORCA2_ICE_PISCES_ for general description).
+| The standalone surface module allows surface elements such as sea-ice, iceberg drift, and
+  surface fluxes to be run using prescribed model state fields.
+  It can profitably be used to compare different bulk formulae or
+  adjust the parameters of a given bulk formula.
+
+More informations about SAS can be found in :doc:`NEMO manual <cite>`.
 
 SPITZ12
@@ -290,5 +318,5 @@
 ``SPITZ12`` is a regional configuration around the Svalbard archipelago
 at 1/12° of horizontal resolution and 75 vertical levels.
-See `Rousset et al. (2015) <https://www.geosci-model-dev.net/8/2991/2015/>`_ for more details.
+See :gmd:`Rousset et al. (2015) <8/2991/2015>` for more details.
 
 This configuration references to year 2002,
@@ -296,12 +324,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/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/SHARED/README.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/SHARED/README.rst	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/SHARED/README.rst	(revision 11954)
@@ -3,39 +3,58 @@
 ***********
 
+.. todo::
+
+
+
 .. contents::
-           :local:
+   :local:
 
 Output of diagnostics in NEMO is usually done using XIOS.
-This is an efficient way of writing diagnostics because the time averaging, file writing and even some simple arithmetic or regridding is carried out in parallel to the NEMO model run.
+This is an efficient way of writing diagnostics because
+the time averaging, file writing and even some simple arithmetic or regridding is carried out in
+parallel to the NEMO model run.
 This page gives a basic introduction to using XIOS with NEMO.
-Much more information is available from the XIOS homepage above and from the NEMO manual.
+Much more information is available from the :xios:`XIOS homepage<>` above and from the NEMO manual.
 
-Use of XIOS for diagnostics is activated using the pre-compiler key ``key_iomput``. 
+Use of XIOS for diagnostics is activated using the pre-compiler key ``key_iomput``.
 
 Extracting and installing XIOS
-------------------------------
+==============================
 
 1. Install the NetCDF4 library.
-   If you want to use single file output you will need to compile the HDF & NetCDF libraries to allow parallel IO.
-2. Download the version of XIOS that you wish to use. The recommended version is now XIOS 2.5:
-   
-.. code-block:: console
+   If you want to use single file output you will need to compile the HDF & NetCDF libraries to
+   allow parallel IO.
+2. Download the version of XIOS that you wish to use.
+   The recommended version is now XIOS 2.5:
 
-	$ svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5 xios-2.5
+   .. code-block:: console
 
-and follow the instructions in `XIOS documentation <http://forge.ipsl.jussieu.fr/ioserver/wiki/documentation>`_ to compile it.
-   If you find problems at this stage, support can be found by subscribing to the `XIOS mailing list <http://forge.ipsl.jussieu.fr/mailman/listinfo.cgi/xios-users>`_ and sending a mail message to it. 
+      $ svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5
+
+and follow the instructions in :xios:`XIOS documentation <wiki/documentation>` to compile it.
+If you find problems at this stage, support can be found by subscribing to
+the :xios:`XIOS mailing list <../mailman/listinfo.cgi/xios-users>` and sending a mail message to it.
 
 XIOS Configuration files
 ------------------------
 
-XIOS is controlled using xml input files that should be copied to your model run directory before running the model.
-Examples of these files can be found in the reference configurations (``cfgs``). The XIOS executable expects to find a file called ``iodef.xml`` in the model run directory.
-In NEMO we have made the decision to use include statements in the ``iodef.xml`` file to include ``field_def_nemo-oce.xml`` (for physics), ``field_def_nemo-ice.xml`` (for ice), ``field_def_nemo-pisces.xml`` (for biogeochemistry) and ``domain_def.xml`` from the /cfgs/SHARED directory.
-Most users will not need to modify ``domain_def.xml`` or ``field_def_nemo-???.xml`` unless they want to add new diagnostics to the NEMO code.
-The definition of the output files is organized into separate ``file_definition.xml`` files which are included in the ``iodef.xml`` file.
+XIOS is controlled using XML input files that should be copied to
+your model run directory before running the model.
+Examples of these files can be found in the reference configurations (:file:`./cfgs`).
+The XIOS executable expects to find a file called :file:`iodef.xml` in the model run directory.
+In NEMO we have made the decision to use include statements in the :file:`iodef.xml` file to include:
+
+- :file:`field_def_nemo-oce.xml` (for physics),
+- :file:`field_def_nemo-ice.xml` (for ice),
+- :file:`field_def_nemo-pisces.xml` (for biogeochemistry) and
+- :file:`domain_def.xml` from the :file:`./cfgs/SHARED` directory.
+
+Most users will not need to modify :file:`domain_def.xml` or :file:`field_def_nemo-???.xml` unless
+they want to add new diagnostics to the NEMO code.
+The definition of the output files is organized into separate :file:`file_definition.xml` files which
+are included in the :file:`iodef.xml` file.
 
 Modes
------
+=====
 
 Detached Mode
@@ -44,11 +63,12 @@
 In detached mode the XIOS executable is executed on separate cores from the NEMO model.
 This is the recommended method for using XIOS for realistic model runs.
-To use this mode set ``using_server`` to ``true`` at the bottom of the ``iodef.xml`` file:
+To use this mode set ``using_server`` to ``true`` at the bottom of the :file:`iodef.xml` file:
 
 .. code-block:: xml
 
-	<variable id="using_server" type="boolean">true</variable>
+   <variable id="using_server" type="boolean">true</variable>
 
-Make sure there is a copy (or link to) your XIOS executable in the working directory and in your job submission script allocate processors to XIOS.
+Make sure there is a copy (or link to) your XIOS executable in the working directory and
+in your job submission script allocate processors to XIOS.
 
 Attached Mode
@@ -56,33 +76,44 @@
 
 In attached mode XIOS runs on each of the cores used by NEMO.
-This method is less efficient than the detached mode but can be more convenient for testing or with small configurations.
-To activate this mode simply set ``using_server`` to false in the ``iodef.xml`` file
+This method is less efficient than the detached mode but can be more convenient for testing or
+with small configurations.
+To activate this mode simply set ``using_server`` to false in the :file:`iodef.xml` file
 
 .. code-block:: xml
 
-	<variable id="using_server" type="boolean">false</variable>
+   <variable id="using_server" type="boolean">false</variable>
 
 and don't allocate any cores to XIOS.
-Note that due to the different domain decompositions between XIOS and NEMO if the total number of cores is larger than the number of grid points in the j direction then the model run will fail.
+
+.. note::
+
+   Due to the different domain decompositions between XIOS and NEMO,
+   if the total number of cores is larger than the number of grid points in the ``j`` direction then
+   the model run will fail.
 
 Adding new diagnostics
-----------------------
+======================
 
 If you want to add a NEMO diagnostic to the NEMO code you will need to do the following:
 
 1. Add any necessary code to calculate you new diagnostic in NEMO
-2. Send the field to XIOS using ``CALL iom_put( 'field_id', variable )`` where ``field_id`` is a unique id for your new diagnostics and variable is the fortran variable containing the data.
-   This should be called at every model timestep regardless of how often you want to output the field. No time averaging should be done in the model code. 
-3. If it is computationally expensive to calculate your new diagnostic you should also use "iom_use" to determine if it is requested in the current model run. For example,
-   
-.. code-block:: fortran
+2. Send the field to XIOS using ``CALL iom_put( 'field_id', variable )`` where
+   ``field_id`` is a unique id for your new diagnostics and
+   variable is the fortran variable containing the data.
+   This should be called at every model timestep regardless of how often you want to output the field.
+   No time averaging should be done in the model code.
+3. If it is computationally expensive to calculate your new diagnostic
+   you should also use "iom_use" to determine if it is requested in the current model run.
+   For example,
 
-		IF iom_use('field_id') THEN
-		   !Some expensive computation
-	   	!...
-		   !...
-	   	iom_put('field_id', variable)
-		ENDIF
+   .. code-block:: fortran
 
-4. Add a variable definition to the ``field_def_nemo-???.xml`` file.
-5. Add the variable to the ``iodef.xml`` or ``file_definition.xml`` file.
+      IF iom_use('field_id') THEN
+         !Some expensive computation
+         !...
+         !...
+	 iom_put('field_id', variable)
+      ENDIF
+
+4. Add a variable definition to the :file:`field_def_nemo-???.xml` file.
+5. Add the variable to the :file:`iodef.xml` or :file:`file_definition.xml` file.
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/SHARED/namelist_ice_ref
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/SHARED/namelist_ice_ref	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/SHARED/namelist_ice_ref	(revision 11954)
@@ -57,10 +57,8 @@
    ln_landfast_L16  = .false.         !  landfast: parameterization from Lemieux 2016
       rn_depfra     =   0.125         !        fraction of ocean depth that ice must reach to initiate landfast
-                                      !          recommended range: [0.1 ; 0.25] - L16=0.125 - home=0.15
-      rn_icebfr     =  15.            !        ln_landfast_L16:  maximum bottom stress per unit volume [N/m3]
-                                      !        ln_landfast_home: maximum bottom stress per unit area of contact [N/m2]
-                                      !          recommended range: ?? L16=15 - home=10
+                                      !          recommended range: [0.1 ; 0.25]
+      rn_icebfr     =  15.            !        maximum bottom stress per unit volume [N/m3]
       rn_lfrelax    =   1.e-5         !        relaxation time scale to reach static friction [s-1]
-      rn_tensile    =   0.2           !        ln_landfast_L16: isotropic tensile strength
+      rn_tensile    =   0.05          !        isotropic tensile strength [0-0.5??]
 /
 !------------------------------------------------------------------------------
@@ -93,5 +91,5 @@
 !------------------------------------------------------------------------------
    ln_rhg_EVP       = .true.          !  EVP rheology
-      ln_aEVP       = .false.         !     adaptive rheology (Kimmritz et al. 2016 & 2017)
+      ln_aEVP       = .true.          !     adaptive rheology (Kimmritz et al. 2016 & 2017)
       rn_creepl     =   2.0e-9        !     creep limit [1/s]
       rn_ecc        =   2.0           !     eccentricity of the elliptical yield curve          
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/SHARED/namelist_ref
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/SHARED/namelist_ref	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/SHARED/namelist_ref	(revision 11954)
@@ -290,5 +290,4 @@
    !                       !   -> file cplmask.nc with the float variable called cplmask (jpi,jpj,nn_cplmodel)
    nn_cats_cpl   =     5   !  Number of sea ice categories over which coupling is to be carried out (if not 1)
-
    !_____________!__________________________!____________!_____________!______________________!________!
    !             !        description       !  multiple  !    vector   !       vector         ! vector !
@@ -327,5 +326,5 @@
    sn_rcv_wper   =   'none'                 ,    'no'    ,     ''      ,         ''           ,   ''
    sn_rcv_wnum   =   'none'                 ,    'no'    ,     ''      ,         ''           ,   ''
-   sn_rcv_wstrf  =   'none'                 ,    'no'    ,     ''      ,         ''           ,   ''
+   sn_rcv_wfreq  =   'none'                 ,    'no'    ,     ''      ,         ''           ,   ''
    sn_rcv_wdrag  =   'none'                 ,    'no'    ,     ''      ,         ''           ,   ''
    sn_rcv_ts_ice =   'none'                 ,    'no'    ,     ''      ,         ''           ,   ''
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/SPITZ12/EXPREF/namelist_ice_cfg
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/SPITZ12/EXPREF/namelist_ice_cfg	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/cfgs/SPITZ12/EXPREF/namelist_ice_cfg	(revision 11954)
@@ -44,6 +44,4 @@
 &namdyn_rhg     !   Ice rheology
 !------------------------------------------------------------------------------
-   ln_rhg_EVP       = .true.          !  EVP rheology
-      ln_aEVP       = .true.          !     adaptive rheology (Kimmritz et al. 2016 & 2017)
 /
 !------------------------------------------------------------------------------
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/README.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/README.rst	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/README.rst	(revision 11954)
@@ -1,3 +1,17 @@
+**************************
+Building the documentation
+**************************
 
+.. todo::
+
+
+
+:file:`latex`    : LaTeX sources and Latexmk configuration to build reference manuals with :file:`manual_build.sh`
+
+:file:`namelists`: Namelist blocks included in the documentation
+
+:file:`rst`      : |RST man|_ sources and Sphinx configuration to build this guide hereby with :file:`guide_build.sh`
+
+.. |RST man| replace:: reStructuredText (rst)
 
 .. warning::
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/main/bibliography.bib
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/main/bibliography.bib	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/main/bibliography.bib	(revision 11954)
@@ -1614,4 +1614,24 @@
 }
 
+@article{         kraus.turner_tellus67,
+  author = {Kraus, E.B. and Turner, J.},
+  journal = {Tellus},
+  pages = {98--106},
+  title = {A one dimensional model of the seasonal thermocline {II}. {T}he general theory and its consequences},
+  volume = {19},
+  year = {1967}
+}
+
+@article{        large.ea_RG97,
+  author        = "Large, W. G. and McWilliams, J. C. and Doney, S. C.",
+  doi           = "10.1029/94RG01872",
+  journal       = "Reviews of Geophysics",
+  number        = {4},
+  pages         = {363--403},
+  publisher     = {AGU},
+  title         = "Oceanic vertical mixing: {A} review and a model with a nonlocal boundary layer parameterization",
+  year          = "1994"
+}
+
 @techreport{      large.yeager_rpt04,
   title         = "Diurnal to decadal global forcing for ocean and sea-ice
@@ -2184,4 +2204,13 @@
 }
 
+@article{mcwilliams.ea_JFM97,
+	author = {McWilliams, James C. and Sullivan, Peter P. and Moeng, Chin-Hoh},
+	doi = {10.1017/S0022112096004375},
+	journal = {Journal of Fluid Mechanics},
+	pages = {1--30},
+	title = {Langmuir turbulence in the ocean},
+	volume = {334},
+	year = {1997},
+}
 @article{         mellor.blumberg_JPO04,
   title         = "Wave Breaking and Ocean Surface Layer Thermal Response",
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/apdx_DOMAINcfg.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/apdx_DOMAINcfg.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/apdx_DOMAINcfg.tex	(revision 11954)
@@ -113,5 +113,5 @@
 \begin{figure}[!tb]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_zgr}
+  \includegraphics[width=0.66\textwidth]{DOMCFG_zgr}
   \caption[DOMAINcfg: default vertical mesh for ORCA2]{
     Default vertical mesh for ORCA2: 30 ocean levels (L30).
@@ -444,5 +444,5 @@
 \begin{figure}[!ht]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_sco_function}
+  \includegraphics[width=0.66\textwidth]{DOMCFG_sco_function}
   \caption[DOMAINcfg: examples of the stretching function applied to a seamount]{
     Examples of the stretching function applied to a seamount;
@@ -493,5 +493,5 @@
 \begin{figure}[!ht]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_DOM_compare_coordinates_surface}
+  \includegraphics[width=0.66\textwidth]{DOMCFG_compare_coordinates_surface}
   \caption[DOMAINcfg: comparison of $s$- and $z$-coordinate]{
     A comparison of the \citet{song.haidvogel_JCP94} $S$-coordinate (solid lines),
@@ -530,5 +530,5 @@
 This option is described in the Report by Levier \textit{et al.} (2007), available on the \NEMO\ web site.
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/apdx_algos.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/apdx_algos.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/apdx_algos.tex	(revision 11954)
@@ -311,5 +311,5 @@
 \begin{figure}[!ht]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_ISO_triad}
+  %\includegraphics[width=0.66\textwidth]{ALGOS_ISO_triad}
   \caption[Triads used in the Griffies's like iso-neutral diffision scheme for
     $u$- and $w$-components)]{
@@ -461,8 +461,7 @@
 where $A_{e}$ is the eddy induced velocity coefficient,
 and $r_i$ and $r_j$ the slopes between the iso-neutral and the geopotential surfaces.
-%%gm wrong: to be modified with 2 2D streamfunctions
+\cmtgm{Wrong: to be modified with 2 2D streamfunctions}
 In other words, the eddy induced velocity can be derived from a vector streamfuntion, $\phi$,
 which is given by $\phi = A_e\,\textbf{r}$ as $\textbf{U}^*  = \textbf{k} \times \nabla \phi$.
-%%end gm
 
 A traditional way to implement this additional advection is to add it to the eulerian velocity prior to
@@ -822,5 +821,5 @@
 \ie\ the variance of the tracer is preserved by the discretisation of the skew fluxes.
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/apdx_diff_opers.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/apdx_diff_opers.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/apdx_diff_opers.tex	(revision 11954)
@@ -421,5 +421,5 @@
 that is a Laplacian diffusion is applied on momentum along the coordinate directions.
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/apdx_invariants.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/apdx_invariants.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/apdx_invariants.tex	(revision 11954)
@@ -25,8 +25,8 @@
 \clearpage
 
-%%%  Appendix put in gmcomment as it has not been updated for \zstar and s coordinate
+%%%  Appendix put in cmtgm as it has not been updated for \zstar and s coordinate
 %I'm writting this appendix. It will be available in a forthcoming release of the documentation
 
-%\gmcomment{
+%\cmtgm{
 
 %% =================================================================================================
@@ -270,5 +270,5 @@
 
 %gm comment
-\gmcomment{
+\cmtgm{
 The last equality comes from the following equation,
 \begin{flalign*}
@@ -583,5 +583,5 @@
 \label{subsec:INVARIANTS_2.6}
 
-\gmcomment{
+\cmtgm{
   A pressure gradient has no contribution to the evolution of the vorticity as the curl of a gradient is zero.
   In the $z$-coordinate, this property is satisfied locally on a C-grid with 2nd order finite differences
@@ -694,5 +694,5 @@
 
 %gm comment
-\gmcomment{
+\cmtgm{
   \begin{flalign*}
     \sum\limits_{i,j,k} \biggl\{   p_t\;\partial_t b_t   \biggr\}                                &&&\\
@@ -1479,5 +1479,5 @@
 %}
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/apdx_s_coord.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/apdx_s_coord.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/apdx_s_coord.tex	(revision 11954)
@@ -584,5 +584,5 @@
 the expression of the 3D divergence in the $s-$coordinates established above.
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/apdx_triads.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/apdx_triads.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/apdx_triads.tex	(revision 11954)
@@ -212,5 +212,5 @@
 \begin{figure}[tb]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_GRIFF_triad_fluxes}
+  \includegraphics[width=0.66\textwidth]{TRIADS_GRIFF_triad_fluxes}
   \caption[Triads arrangement and tracer gradients to give lateral and vertical tracer fluxes]{
     (a) Arrangement of triads $S_i$ and tracer gradients to
@@ -272,5 +272,5 @@
 \begin{figure}[tb]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_GRIFF_qcells}
+  \includegraphics[width=0.66\textwidth]{TRIADS_GRIFF_qcells}
   \caption[Triad notation for quarter cells]{
     Triad notation for quarter cells.
@@ -657,5 +657,5 @@
 \begin{figure}[h]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_GRIFF_bdry_triads}
+  \includegraphics[width=0.66\textwidth]{TRIADS_GRIFF_bdry_triads}
   \caption[Boundary triads]{
     (a) Uppermost model layer $k=1$ with $i,1$ and $i+1,1$ tracer points (black dots),
@@ -808,5 +808,5 @@
 \begin{figure}[h]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_GRIFF_MLB_triads}
+  \includegraphics[width=0.66\textwidth]{TRIADS_GRIFF_MLB_triads}
   \caption[Definition of mixed-layer depth and calculation of linearly tapered triads]{
     Definition of mixed-layer depth and calculation of linearly tapered triads.
@@ -1177,5 +1177,5 @@
 \]
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_ASM.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_ASM.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_ASM.tex	(revision 11954)
@@ -194,5 +194,5 @@
 \end{clines}
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_DIA.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_DIA.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_DIA.tex	(revision 11954)
@@ -55,5 +55,5 @@
 A complete description of the use of this I/O server is presented in the next section.
 
-%\gmcomment{                    % start of gmcomment
+%\cmtgm{                    % start of gmcomment
 
 %% =================================================================================================
@@ -1967,5 +1967,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_mask_subasins}
+  \includegraphics[width=0.66\textwidth]{DIA_mask_subasins}
   \caption[Decomposition of the World Ocean to compute transports as well as
   the meridional stream-function]{
@@ -2061,5 +2061,5 @@
 The maximum values from the run are also copied to the ocean.output file.
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_DIU.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_DIU.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_DIU.tex	(revision 11954)
@@ -160,5 +160,5 @@
 \]
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_DOM.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_DOM.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_DOM.tex	(revision 11954)
@@ -6,19 +6,12 @@
 \label{chap:DOM}
 
-% Missing things:
-% 	- istate: description of the initial state   ==> this has to be put elsewhere..
-%                  perhaps in MISC ?  By the way the initialisation of T S and dynamics
-%                  should be put outside of DOM routine (better with TRC staff and off-line
-%                  tracers)
-% 	-geo2ocean:  how to switch from geographic to mesh coordinate
-%     - domclo:  closed sea and lakes.... management of closea sea area : specific to global configuration, both forced and coupled
-
-%    {\em 4.0} & {\em Simon M\"{u}ller \& Andrew Coward} &
-%    {\em
-%      Compatibility changes Major simplification has moved many of the options to external domain configuration tools.
-%      (see \autoref{apdx:DOMCFG})
-%    }                                                                                            \\
-%    {\em 3.x} & {\em Rachid Benshila, Gurvan Madec \& S\'{e}bastien Masson} &
-%    {\em First version}                                                                          \\
+% Missing things
+% -    istate: description of the initial state   ==> this has to be put elsewhere..
+%              perhaps in MISC ?  By the way the initialisation of T S and dynamics
+%              should be put outside of DOM routine (better with TRC staff and off-line
+%              tracers)
+% - geo2ocean: how to switch from geographic to mesh coordinate
+% -    domclo: closed sea and lakes....
+%              management of closea sea area: specific to global cfg, both forced and coupled
 
 \thispagestyle{plain}
@@ -29,11 +22,21 @@
 
 {\footnotesize
-  \begin{tabularx}{\textwidth}{l||X|X}
-    Release & Author(s) & Modifications \\
-    \hline
-    {\em   4.0} & {\em ...} & {\em ...} \\
-    {\em   3.6} & {\em ...} & {\em ...} \\
-    {\em   3.4} & {\em ...} & {\em ...} \\
-    {\em <=3.4} & {\em ...} & {\em ...}
+  \begin{tabularx}{0.8\textwidth}{l||X|X}
+    Release                                                                                 &
+    Author(s)                                                                               &
+    Modifications                                                                           \\
+    \hline
+    {\em 4.0                                                                              } &
+    {\em Simon M\"{u}ller \& Andrew Coward \newline \newline
+      Simona Flavoni and Tim Graham                                                       } &
+    {\em Compatibility changes: many options moved to external domain configuration tools
+      (see \autoref{apdx:DOMCFG}). \newline
+      Updates                                                                             } \\
+    {\em 3.6                                                                              } &
+    {\em Rachid Benshila, Christian \'{E}th\'{e}, Pierre Mathiot and Gurvan Madec         } &
+    {\em Updates                                                                          } \\
+    {\em $\leq$ 3.4                                                                       } &
+    {\em Gurvan Madec and S\'{e}bastien Masson                                            } &
+    {\em First version                                                                    }
   \end{tabularx}
 }
@@ -41,5 +44,6 @@
 \clearpage
 
-Having defined the continuous equations in \autoref{chap:MB} and chosen a time discretisation \autoref{chap:TD},
+Having defined the continuous equations in \autoref{chap:MB} and
+chosen a time discretisation \autoref{chap:TD},
 we need to choose a grid for spatial discretisation and related numerical algorithms.
 In the present chapter, we provide a general description of the staggered grid used in \NEMO,
@@ -54,65 +58,68 @@
 \label{subsec:DOM_cell}
 
-\begin{figure}[!tb]
+\begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_cell}
+  \includegraphics[width=0.33\textwidth]{DOM_cell}
   \caption[Arrangement of variables in the unit cell of space domain]{
     Arrangement of variables in the unit cell of space domain.
     $t$ indicates scalar points where
     temperature, salinity, density, pressure and horizontal divergence are defined.
-    $(u,v,w)$ indicates vector points,
-    and $f$ indicates vorticity points where
+    $(u,v,w)$ indicates vector points, and $f$ indicates vorticity points where
     both relative and planetary vorticities are defined.}
   \label{fig:DOM_cell}
 \end{figure}
 
-The numerical techniques used to solve the Primitive Equations in this model are based on the traditional,
-centred second-order finite difference approximation.
+The numerical techniques used to solve the Primitive Equations in this model are based on
+the traditional, centred second-order finite difference approximation.
 Special attention has been given to the homogeneity of the solution in the three spatial directions.
 The arrangement of variables is the same in all directions.
-It consists of cells centred on scalar points ($t$, $S$, $p$, $\rho$) with vector points $(u, v, w)$ defined in
-the centre of each face of the cells (\autoref{fig:DOM_cell}).
-This is the generalisation to three dimensions of the well-known ``C'' grid in Arakawa's classification
-\citep{mesinger.arakawa_bk76}.
-The relative and planetary vorticity, $\zeta$ and $f$, are defined in the centre of each vertical edge and
-the barotropic stream function $\psi$ is defined at horizontal points overlying the $\zeta$ and $f$-points.
-
-The ocean mesh (\ie\ the position of all the scalar and vector points) is defined by the transformation that
-gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$.
-The grid-points are located at integer or integer and a half value of $(i,j,k)$ as indicated on \autoref{tab:DOM_cell}.
-In all the following, subscripts $u$, $v$, $w$, $f$, $uw$, $vw$ or $fw$ indicate the position of
-the grid-point where the scale factors are defined.
+It consists of cells centred on scalar points ($t$, $S$, $p$, $\rho$) with
+vector points $(u, v, w)$ defined in the centre of each face of the cells (\autoref{fig:DOM_cell}).
+This is the generalisation to three dimensions of the well-known ``C'' grid in
+Arakawa's classification \citep{mesinger.arakawa_bk76}.
+The relative and planetary vorticity, $\zeta$ and $f$, are defined in the centre of each
+vertical edge and the barotropic stream function $\psi$ is defined at horizontal points overlying
+the $\zeta$ and $f$-points.
+
+The ocean mesh (\ie\ the position of all the scalar and vector points) is defined by
+the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$.
+The grid-points are located at integer or integer and a half value of $(i,j,k)$ as indicated on
+\autoref{tab:DOM_cell}.
+In all the following,
+subscripts $u$, $v$, $w$, $f$, $uw$, $vw$ or $fw$ indicate the position of the grid-point where
+the scale factors are defined.
 Each scale factor is defined as the local analytical value provided by \autoref{eq:MB_scale_factors}.
 As a result, the mesh on which partial derivatives $\pd[]{\lambda}$, $\pd[]{\varphi}$ and
 $\pd[]{z}$ are evaluated is a uniform mesh with a grid size of unity.
-Discrete partial derivatives are formulated by the traditional, centred second order finite difference approximation
-while the scale factors are chosen equal to their local analytical value.
+Discrete partial derivatives are formulated by
+the traditional, centred second order finite difference approximation while
+the scale factors are chosen equal to their local analytical value.
 An important point here is that the partial derivative of the scale factors must be evaluated by
 centred finite difference approximation, not from their analytical expression.
-This preserves the symmetry of the discrete set of equations and therefore satisfies many of
-the continuous properties (see \autoref{apdx:INVARIANTS}).
+This preserves the symmetry of the discrete set of equations and
+therefore satisfies many of the continuous properties (see \autoref{apdx:INVARIANTS}).
 A similar, related remark can be made about the domain size:
-when needed, an area, volume, or the total ocean depth must be evaluated as the product or sum of the relevant scale factors
-(see \autoref{eq:DOM_bar} in the next section).
-
-\begin{table}[!tb]
+when needed, an area, volume, or the total ocean depth must be evaluated as
+the product or sum of the relevant scale factors (see \autoref{eq:DOM_bar} in the next section).
+
+\begin{table}
   \centering
-  \begin{tabular}{|p{46pt}|p{56pt}|p{56pt}|p{56pt}|}
-    \hline
-    t	& $i 		 $ & $j      $ & $k      $ \\
-    \hline
-    u	& $i + 1/2$ & $j      $ & $k      $ \\
-    \hline
-    v	& $i	 	 $ & $j + 1/2$ & $k      $ \\
-    \hline
-    w	& $i	 	 $ & $j      $ & $k + 1/2$ \\
-    \hline
-    f	& $i + 1/2$ & $j + 1/2$ & $k      $ \\
-    \hline
-    uw	& $i + 1/2$ & $j      $ & $k + 1/2$ \\
-    \hline
-    vw	& $i	 	 $ & $j + 1/2$ & $k + 1/2$ \\
-    \hline
-    fw	& $i + 1/2$ & $j + 1/2$ & $k + 1/2$ \\
+  \begin{tabular}{|l|l|l|l|}
+    \hline
+    t   & $i      $ & $j      $ & $k      $ \\
+    \hline
+    u   & $i + 1/2$ & $j      $ & $k      $ \\
+    \hline
+    v   & $i      $ & $j + 1/2$ & $k      $ \\
+    \hline
+    w   & $i      $ & $j      $ & $k + 1/2$ \\
+    \hline
+    f   & $i + 1/2$ & $j + 1/2$ & $k      $ \\
+    \hline
+    uw  & $i + 1/2$ & $j      $ & $k + 1/2$ \\
+    \hline
+    vw  & $i      $ & $j + 1/2$ & $k + 1/2$ \\
+    \hline
+    fw  & $i + 1/2$ & $j + 1/2$ & $k + 1/2$ \\
     \hline
   \end{tabular}
@@ -120,5 +127,5 @@
     Location of grid-points as a function of integer or
     integer and a half value of the column, line or level.
-    This indexing is only used for the writing of the semi -discrete equations.
+    This indexing is only used for the writing of the semi-discrete equations.
     In the code, the indexing uses integer values only and
     is positive downwards in the vertical with $k=1$ at the surface.
@@ -137,10 +144,12 @@
 firstly, there is no ambiguity in the scale factors appearing in the discrete equations,
 since they are first introduced in the continuous equations;
-secondly, analytical transformations encourage good practice by the definition of smoothly varying grids
-(rather than allowing the user to set arbitrary jumps in thickness between adjacent layers) \citep{treguier.dukowicz.ea_JGR96}.
+secondly, analytical transformations encourage good practice by
+the definition of smoothly varying grids
+(rather than allowing the user to set arbitrary jumps in thickness between adjacent layers)
+\citep{treguier.dukowicz.ea_JGR96}.
 An example of the effect of such a choice is shown in \autoref{fig:DOM_zgr_e3}.
-\begin{figure}[!t]
+\begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_zgr_e3}
+  \includegraphics[width=0.5\textwidth]{DOM_zgr_e3}
   \caption[Comparison of grid-point position, vertical grid-size and scale factors]{
     Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical,
@@ -159,6 +168,6 @@
 \label{subsec:DOM_operators}
 
-Given the values of a variable $q$ at adjacent points, the differencing and averaging operators at
-the midpoint between them are:
+Given the values of a variable $q$ at adjacent points,
+the differencing and averaging operators at the midpoint between them are:
 \begin{alignat*}{2}
   % \label{eq:DOM_di_mi}
@@ -168,26 +177,27 @@
 
 Similar operators are defined with respect to $i + 1/2$, $j$, $j + 1/2$, $k$, and $k + 1/2$.
-Following \autoref{eq:MB_grad} and \autoref{eq:MB_lap}, the gradient of a variable $q$ defined at a $t$-point has
-its three components defined at $u$-, $v$- and $w$-points while its Laplacian is defined at the $t$-point.
+Following \autoref{eq:MB_grad} and \autoref{eq:MB_lap},
+the gradient of a variable $q$ defined at a $t$-point has
+its three components defined at $u$-, $v$- and $w$-points while
+its Laplacian is defined at the $t$-point.
 These operators have the following discrete forms in the curvilinear $s$-coordinates system:
-\[
+\begin{gather*}
   % \label{eq:DOM_grad}
   \nabla q \equiv   \frac{1}{e_{1u}} \delta_{i + 1/2} [q] \; \, \vect i
                   + \frac{1}{e_{2v}} \delta_{j + 1/2} [q] \; \, \vect j
-                  + \frac{1}{e_{3w}} \delta_{k + 1/2} [q] \; \, \vect k
-\]
-\begin{multline*}
+                  + \frac{1}{e_{3w}} \delta_{k + 1/2} [q] \; \, \vect k \\
   % \label{eq:DOM_lap}
   \Delta q \equiv   \frac{1}{e_{1t} \, e_{2t} \, e_{3t}}
                     \; \lt[   \delta_i \lt( \frac{e_{2u} \, e_{3u}}{e_{1u}} \; \delta_{i + 1/2} [q] \rt)
-                            + \delta_j \lt( \frac{e_{1v} \, e_{3v}}{e_{2v}} \; \delta_{j + 1/2} [q] \rt) \; \rt] \\
+                            + \delta_j \lt( \frac{e_{1v} \, e_{3v}}{e_{2v}} \; \delta_{j + 1/2} [q] \rt) \; \rt]
                   + \frac{1}{e_{3t}}
                               \delta_k \lt[ \frac{1              }{e_{3w}} \; \delta_{k + 1/2} [q] \rt]
-\end{multline*}
-
-Following \autoref{eq:MB_curl} and \autoref{eq:MB_div}, a vector $\vect A = (a_1,a_2,a_3)$ defined at
-vector points $(u,v,w)$ has its three curl components defined at $vw$-, $uw$, and $f$-points, and
+\end{gather*}
+
+Following \autoref{eq:MB_curl} and \autoref{eq:MB_div},
+a vector $\vect A = (a_1,a_2,a_3)$ defined at vector points $(u,v,w)$ has
+its three curl components defined at $vw$-, $uw$, and $f$-points, and
 its divergence defined at $t$-points:
-\begin{multline}
+\begin{multline*}
 % \label{eq:DOM_curl}
   \nabla \times \vect A \equiv   \frac{1}{e_{2v} \, e_{3vw}}
@@ -200,14 +210,14 @@
                                  \Big[   \delta_{i + 1/2} (e_{2v} \, a_2)
                                        - \delta_{j + 1/2} (e_{1u} \, a_1) \Big] \vect k
-\end{multline}
-\begin{equation}
+\end{multline*}
+\[
 % \label{eq:DOM_div}
   \nabla \cdot \vect A \equiv   \frac{1}{e_{1t} \, e_{2t} \, e_{3t}}
                                 \Big[ \delta_i (e_{2u} \, e_{3u} \, a_1) + \delta_j (e_{1v} \, e_{3v} \, a_2) \Big]
                               + \frac{1}{e_{3t}} \delta_k (a_3)
-\end{equation}
-
-The vertical average over the whole water column is denoted by an overbar and is for
-a masked field $q$ (\ie\ a quantity that is equal to zero inside solid areas):
+\]
+
+The vertical average over the whole water column is denoted by an overbar and
+is for a masked field $q$ (\ie\ a quantity that is equal to zero inside solid areas):
 \begin{equation}
   \label{eq:DOM_bar}
@@ -215,6 +225,7 @@
 \end{equation}
 where $H_q$  is the ocean depth, which is the masked sum of the vertical scale factors at $q$ points,
-$k^b$ and $k^o$ are the bottom and surface $k$-indices, and the symbol $\sum \limits_k$ refers to a summation over
-all grid points of the same type in the direction indicated by the subscript (here $k$).
+$k^b$ and $k^o$ are the bottom and surface $k$-indices,
+and the symbol $\sum \limits_k$ refers to a summation over all grid points of the same type in
+the direction indicated by the subscript (here $k$).
 
 In continuous form, the following properties are satisfied:
@@ -226,13 +237,14 @@
 \end{gather}
 
-It is straightforward to demonstrate that these properties are verified locally in discrete form as soon as
-the scalar $q$ is taken at $t$-points and the vector $\vect A$ has its components defined at
+It is straightforward to demonstrate that these properties are verified locally in discrete form as
+soon as the scalar $q$ is taken at $t$-points and the vector $\vect A$ has its components defined at
 vector points $(u,v,w)$.
 
 Let $a$ and $b$ be two fields defined on the mesh, with a value of zero inside continental areas.
-It can be shown that the differencing operators ($\delta_i$, $\delta_j$ and $\delta_k$)
-are skew-symmetric linear operators, and further that the averaging operators $\overline{\cdots}^{\, i}$,
-$\overline{\cdots}^{\, j}$ and $\overline{\cdots}^{\, k}$) are symmetric linear operators, \ie
-\begin{alignat}{4}
+It can be shown that the differencing operators ($\delta_i$, $\delta_j$ and
+$\delta_k$) are skew-symmetric linear operators,
+and further that the averaging operators ($\overline{\cdots}^{\, i}$, $\overline{\cdots}^{\, j}$ and
+$\overline{\cdots}^{\, k}$) are symmetric linear operators, \ie
+\begin{alignat}{5}
   \label{eq:DOM_di_adj}
   &\sum \limits_i a_i \; \delta_i [b]      &\equiv &- &&\sum \limits_i \delta      _{   i + 1/2} [a] &b_{i + 1/2} \\
@@ -241,5 +253,6 @@
 \end{alignat}
 
-In other words, the adjoint of the differencing and averaging operators are $\delta_i^* = \delta_{i + 1/2}$ and
+In other words,
+the adjoint of the differencing and averaging operators are $\delta_i^* = \delta_{i + 1/2}$ and
 $(\overline{\cdots}^{\, i})^* = \overline{\cdots}^{\, i + 1/2}$, respectively.
 These two properties will be used extensively in the \autoref{apdx:INVARIANTS} to
@@ -250,7 +263,7 @@
 \label{subsec:DOM_Num_Index}
 
-\begin{figure}[!tb]
+\begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_index_hor}
+  \includegraphics[width=0.33\textwidth]{DOM_index_hor}
   \caption[Horizontal integer indexing]{
     Horizontal integer indexing used in the \fortran\ code.
@@ -261,9 +274,11 @@
 
 The array representation used in the \fortran\ code requires an integer indexing.
-However, the analytical definition of the mesh (see \autoref{subsec:DOM_cell}) is associated with the use of
-integer values for $t$-points only while all the other points involve integer and a half values.
+However, the analytical definition of the mesh (see \autoref{subsec:DOM_cell}) is associated with
+the use of integer values for $t$-points only while
+all the other points involve integer and a half values.
 Therefore, a specific integer indexing has been defined for points other than $t$-points
 (\ie\ velocity and vorticity grid-points).
-Furthermore, the direction of the vertical indexing has been reversed and the surface level set at $k = 1$.
+Furthermore, the direction of the vertical indexing has been reversed and
+the surface level set at $k = 1$.
 
 %% =================================================================================================
@@ -281,15 +296,16 @@
 \label{subsec:DOM_Num_Index_vertical}
 
-In the vertical, the chosen indexing requires special attention since the direction of the $k$-axis in
-the \fortran\ code is the reverse of that used in the semi -discrete equations and
-given in \autoref{subsec:DOM_cell}.
-The sea surface corresponds to the $w$-level $k = 1$, which is the same index as the $t$-level just below
-(\autoref{fig:DOM_index_vert}).
+In the vertical, the chosen indexing requires special attention since
+the direction of the $k$-axis in the \fortran\ code is the reverse of
+that used in the semi-discrete equations and given in \autoref{subsec:DOM_cell}.
+The sea surface corresponds to the $w$-level $k = 1$,
+which is the same index as the $t$-level just below (\autoref{fig:DOM_index_vert}).
 The last $w$-level ($k = jpk$) either corresponds to or is below the ocean floor while
 the last $t$-level is always outside the ocean domain (\autoref{fig:DOM_index_vert}).
 Note that a $w$-point and the directly underlaying $t$-point have a common $k$ index
 (\ie\ $t$-points and their nearest $w$-point neighbour in negative index direction),
-in contrast to the indexing on the horizontal plane where the $t$-point has the same index as
-the nearest velocity points in the positive direction of the respective horizontal axis index
+in contrast to the indexing on the horizontal plane where
+the $t$-point has the same index as the nearest velocity points in
+the positive direction of the respective horizontal axis index
 (compare the dashed area in \autoref{fig:DOM_index_hor} and \autoref{fig:DOM_index_vert}).
 Since the scale factors are chosen to be strictly positive,
@@ -298,7 +314,7 @@
 accommodate the opposing vertical index directions in implementation and documentation.
 
-\begin{figure}[!pt]
+\begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_index_vert}
+  \includegraphics[width=0.33\textwidth]{DOM_index_vert}
   \caption[Vertical integer indexing]{
     Vertical integer indexing used in the \fortran\ code.
@@ -314,9 +330,11 @@
 
 Two typical methods are available to specify the spatial domain configuration;
-they can be selected using parameter \np{ln_read_cfg}{ln\_read\_cfg} parameter in namelist \nam{cfg}{cfg}.
+they can be selected using parameter \np{ln_read_cfg}{ln\_read\_cfg} parameter in
+namelist \nam{cfg}{cfg}.
 
 If \np{ln_read_cfg}{ln\_read\_cfg} is set to \forcode{.true.},
-the domain-specific parameters and fields are read from a netCDF input file,
-whose name (without its .nc suffix) can be specified as the value of the \np{cn_domcfg}{cn\_domcfg} parameter in namelist \nam{cfg}{cfg}.
+the domain-specific parameters and fields are read from a NetCDF input file,
+whose name (without its .nc suffix) can be specified as
+the value of the \np{cn_domcfg}{cn\_domcfg} parameter in namelist \nam{cfg}{cfg}.
 
 If \np{ln_read_cfg}{ln\_read\_cfg} is set to \forcode{.false.},
@@ -324,6 +342,6 @@
 subroutines \mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}.
 These subroutines can be supplied in the \path{MY_SRC} directory of the configuration,
-and default versions that configure the spatial domain for the GYRE reference configuration are present in
-the \path{./src/OCE/USR} directory.
+and default versions that configure the spatial domain for the GYRE reference configuration are
+present in the \path{./src/OCE/USR} directory.
 
 In version 4.0 there are no longer any options for reading complex bathymetries and
@@ -332,12 +350,14 @@
 to run similar models with and without partial bottom boxes and/or sigma-coordinates,
 supporting such choices leads to overly complex code.
-Worse still is the difficulty of ensuring the model configurations intended to be identical are indeed so when
-the model domain itself can be altered by runtime selections.
-The code previously used to perform vertical discretisation has been incorporated into an external tool
-(\path{./tools/DOMAINcfg}) which is briefly described in \autoref{apdx:DOMCFG}.
-
-The next subsections summarise the parameter and fields related to the configuration of the whole model domain.
-These represent the minimum information that must be provided either via the \np{cn_domcfg}{cn\_domcfg} file or set by code
-inserted into user-supplied versions of the \texttt{usrdef\_*} subroutines.
+Worse still is the difficulty of ensuring the model configurations intended to be identical are
+indeed so when the model domain itself can be altered by runtime selections.
+The code previously used to perform vertical discretisation has been incorporated into
+an external tool (\path{./tools/DOMAINcfg}) which is briefly described in \autoref{apdx:DOMCFG}.
+
+The next subsections summarise the parameter and fields related to
+the configuration of the whole model domain.
+These represent the minimum information that must be provided either via
+the \np{cn_domcfg}{cn\_domcfg} file or
+set by code inserted into user-supplied versions of the \texttt{usrdef\_*} subroutines.
 The requirements are presented in three sections:
 the domain size (\autoref{subsec:DOM_size}), the horizontal mesh (\autoref{subsec:DOM_hgr}),
@@ -348,9 +368,9 @@
 \label{subsec:DOM_size}
 
-The total size of the computational domain is set by the parameters \jp{jpiglo}, \jp{jpjglo} and \jp{jpkglo} for
-the $i$, $j$ and $k$ directions, respectively.
-Note, that the variables \texttt{jpi} and \texttt{jpj} refer to the size of each processor subdomain when
-the code is run in parallel using domain decomposition (\key{mpp\_mpi} defined,
-see \autoref{sec:LBC_mpp}).
+The total size of the computational domain is set by the parameters \jp{jpiglo}, \jp{jpjglo} and
+\jp{jpkglo} for the $i$, $j$ and $k$ directions, respectively.
+Note, that the variables \texttt{jpi} and \texttt{jpj} refer to
+the size of each processor subdomain when the code is run in parallel using domain decomposition
+(\key{mpp\_mpi} defined, see \autoref{sec:LBC_mpp}).
 
 The name of the configuration is set through parameter \np{cn_cfg}{cn\_cfg},
@@ -360,5 +380,6 @@
 
 The global lateral boundary condition type is selected from 8 options using parameter \jp{jperio}.
-See \autoref{sec:LBC_jperio} for details on the available options and the corresponding values for \jp{jperio}.
+See \autoref{sec:LBC_jperio} for details on the available options and
+the corresponding values for \jp{jperio}.
 
 %% =================================================================================================
@@ -370,14 +391,15 @@
 \label{sec:DOM_hgr_fields}
 
-The explicit specification of a range of mesh-related fields are required for the definition of a configuration.
+The explicit specification of a range of mesh-related fields are required for
+the definition of a configuration.
 These include:
 
 \begin{clines}
-int    jpiglo, jpjglo, jpkglo            /* global domain sizes                                          */
-int    jperio                            /* lateral global domain b.c.                                   */
-double glamt, glamu, glamv, glamf        /* geographic longitude (t,u,v and f points respectively)       */
-double gphit, gphiu, gphiv, gphif        /* geographic latitude                                          */
-double e1t, e1u, e1v, e1f                /* horizontal scale factors                                     */
-double e2t, e2u, e2v, e2f                /* horizontal scale factors                                     */
+int    jpiglo, jpjglo, jpkglo     /* global domain sizes                                    */
+int    jperio                     /* lateral global domain b.c.                             */
+double glamt, glamu, glamv, glamf /* geographic longitude (t,u,v and f points respectively) */
+double gphit, gphiu, gphiv, gphif /* geographic latitude                                    */
+double e1t, e1u, e1v, e1f         /* horizontal scale factors                               */
+double e2t, e2u, e2v, e2f         /* horizontal scale factors                               */
 \end{clines}
 
@@ -393,8 +415,8 @@
 
 \begin{clines}
-                                         /* Optional:                                                    */
-int    ORCA, ORCA_index                  /* configuration name, configuration resolution                 */
-double e1e2u, e1e2v                      /* U and V surfaces (if grid size reduction in some straits)    */
-double ff_f, ff_t                        /* Coriolis parameter (if not on the sphere)                    */
+                        /* Optional:                                                 */
+int    ORCA, ORCA_index /* configuration name, configuration resolution              */
+double e1e2u, e1e2v     /* U and V surfaces (if grid size reduction in some straits) */
+double ff_f, ff_t       /* Coriolis parameter (if not on the sphere)                 */
 \end{clines}
 
@@ -403,31 +425,35 @@
 This is particularly useful for locations such as Gibraltar or Indonesian Throughflow pinch-points
 (see \autoref{sec:MISC_strait} for illustrated examples).
-The key is to reduce the faces of $T$-cell (\ie\ change the value of the horizontal scale factors at $u$- or $v$-point) but
+The key is to reduce the faces of $T$-cell
+(\ie\ change the value of the horizontal scale factors at $u$- or $v$-point) but
 not the volume of the cells.
 Doing otherwise can lead to numerical instability issues.
 In normal operation the surface areas are computed from $e1u * e2u$ and $e1v * e2v$ but
 in cases where a gridsize reduction is required,
-the unaltered surface areas at $u$ and $v$ grid points (\texttt{e1e2u} and \texttt{e1e2v}, respectively) must be read or
-pre-computed in \mdl{usrdef\_hgr}.
-If these arrays are present in the \np{cn_domcfg}{cn\_domcfg} file they are read and the internal computation is suppressed.
-Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{e1e2u} and \texttt{e1e2v} should set
-the surface-area computation flag:
+the unaltered surface areas at $u$ and $v$ grid points
+(\texttt{e1e2u} and \texttt{e1e2v}, respectively) must be read or pre-computed in \mdl{usrdef\_hgr}.
+If these arrays are present in the \np{cn_domcfg}{cn\_domcfg} file they are read and
+the internal computation is suppressed.
+Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{e1e2u} and \texttt{e1e2v} should
+set the surface-area computation flag:
 \texttt{ie1e2u\_v} to a non-zero value to suppress their re-computation.
 
 \smallskip
 Similar logic applies to the other optional fields:
-\texttt{ff\_f} and \texttt{ff\_t} which can be used to provide the Coriolis parameter at F- and T-points respectively if
-the mesh is not on a sphere.
-If present these fields will be read and used and the normal calculation ($2 * \Omega * \sin(\varphi)$) suppressed.
-Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{ff\_f} and \texttt{ff\_t} should set
-the Coriolis computation flag:
+\texttt{ff\_f} and \texttt{ff\_t} which can be used to
+provide the Coriolis parameter at F- and T-points respectively if the mesh is not on a sphere.
+If present these fields will be read and used and
+the normal calculation ($2 * \Omega * \sin(\varphi)$) suppressed.
+Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{ff\_f} and \texttt{ff\_t} should
+set the Coriolis computation flag:
 \texttt{iff} to a non-zero value to suppress their re-computation.
 
-Note that longitudes, latitudes, and scale factors at $w$ points are exactly equal to those of $t$ points,
-thus no specific arrays are defined at $w$ points.
+Note that longitudes, latitudes, and scale factors at $w$ points are exactly equal to
+those of $t$ points, thus no specific arrays are defined at $w$ points.
 
 %% =================================================================================================
 \subsection[Vertical grid (\textit{domzgr.F90})]{Vertical grid (\protect\mdl{domzgr})}
 \label{subsec:DOM_zgr}
+
 \begin{listing}
   \nlst{namdom}
@@ -438,23 +464,27 @@
 In the vertical, the model mesh is determined by four things:
 \begin{enumerate}
-  \item the bathymetry given in meters;
-  \item the number of levels of the model (\jp{jpk});
-  \item the analytical transformation $z(i,j,k)$ and the vertical scale factors (derivatives of the transformation); and
-  \item the masking system, \ie\ the number of wet model levels at each
-$(i,j)$ location of the horizontal grid.
+\item the bathymetry given in meters;
+\item the number of levels of the model (\jp{jpk});
+\item the analytical transformation $z(i,j,k)$ and the vertical scale factors
+  (derivatives of the transformation); and
+\item the masking system,
+  \ie\ the number of wet model levels at each $(i,j)$ location of the horizontal grid.
 \end{enumerate}
 
-\begin{figure}[!tb]
+\begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_z_zps_s_sps}
+  \includegraphics[width=0.5\textwidth]{DOM_z_zps_s_sps}
   \caption[Ocean bottom regarding coordinate systems ($z$, $s$ and hybrid $s-z$)]{
     The ocean bottom as seen by the model:
-    (a) $z$-coordinate with full step,
-    (b) $z$-coordinate with partial step,
-    (c) $s$-coordinate: terrain following representation,
-    (d) hybrid $s-z$ coordinate,
-    (e) hybrid $s-z$ coordinate with partial step, and
-    (f) same as (e) but in the non-linear free surface (\protect\np[=.false.]{ln_linssh}{ln\_linssh}).
-    Note that the non-linear free surface can be used with any of the 5 coordinates (a) to (e).}
+    \begin{enumerate*}[label=(\textit{\alph*})]
+    \item $z$-coordinate with full step,
+    \item $z$-coordinate with partial step,
+    \item $s$-coordinate: terrain following representation,
+    \item hybrid $s-z$ coordinate,
+    \item hybrid $s-z$ coordinate with partial step, and
+    \item same as (e) but in the non-linear free surface
+      (\protect\np[=.false.]{ln_linssh}{ln\_linssh}).
+  \end{enumerate*}
+  Note that the non-linear free surface can be used with any of the 5 coordinates (a) to (e).}
   \label{fig:DOM_z_zps_s_sps}
 \end{figure}
@@ -463,25 +493,30 @@
 it is not intended to be an option which can be changed in the middle of an experiment.
 The one exception to this statement being the choice of linear or non-linear free surface.
-In v4.0 the linear free surface option is implemented as a special case of the non-linear free surface.
+In v4.0 the linear free surface option is implemented as
+a special case of the non-linear free surface.
 This is computationally wasteful since it uses the structures for time-varying 3D metrics
 for fields that (in the linear free surface case) are fixed.
-However, the linear free-surface is rarely used and implementing it this way means
-a single configuration file can support both options.
-
-By default a non-linear free surface is used (\np{ln_linssh}{ln\_linssh} set to \forcode{=.false.} in \nam{dom}{dom}):
-the coordinate follow the time-variation of the free surface so that the transformation is time dependent:
-$z(i,j,k,t)$ (\eg\ \autoref{fig:DOM_z_zps_s_sps}f).
-When a linear free surface is assumed (\np{ln_linssh}{ln\_linssh} set to \forcode{=.true.} in \nam{dom}{dom}),
-the vertical coordinates are fixed in time, but the seawater can move up and down across the $z_0$ surface
+However, the linear free-surface is rarely used and
+implementing it this way means a single configuration file can support both options.
+
+By default a non-linear free surface is used
+(\np{ln_linssh}{ln\_linssh} set to \forcode{=.false.} in \nam{dom}{dom}):
+the coordinate follow the time-variation of the free surface so that
+the transformation is time dependent: $z(i,j,k,t)$ (\eg\ \autoref{fig:DOM_z_zps_s_sps}f).
+When a linear free surface is assumed
+(\np{ln_linssh}{ln\_linssh} set to \forcode{=.true.} in \nam{dom}{dom}),
+the vertical coordinates are fixed in time, but
+the seawater can move up and down across the $z_0$ surface
 (in other words, the top of the ocean in not a rigid lid).
 
 Note that settings:
-\np{ln_zco}{ln\_zco}, \np{ln_zps}{ln\_zps}, \np{ln_sco}{ln\_sco} and \np{ln_isfcav}{ln\_isfcav} mentioned in the following sections
-appear to be namelist options but they are no longer truly namelist options for \NEMO.
+\np{ln_zco}{ln\_zco}, \np{ln_zps}{ln\_zps}, \np{ln_sco}{ln\_sco} and \np{ln_isfcav}{ln\_isfcav}
+mentioned in the following sections appear to be namelist options but
+they are no longer truly namelist options for \NEMO.
 Their value is written to and read from the domain configuration file and
 they should be treated as fixed parameters for a particular configuration.
-They are namelist options for the \texttt{DOMAINcfg} tool that can be used to build the configuration file and
-serve both to provide a record of the choices made whilst building the configuration and
-to trigger appropriate code blocks within \NEMO.
+They are namelist options for the \texttt{DOMAINcfg} tool that can be used to
+build the configuration file and serve both to provide a record of the choices made whilst
+building the configuration and to trigger appropriate code blocks within \NEMO.
 These values should not be altered in the \np{cn_domcfg}{cn\_domcfg} file.
 
@@ -501,11 +536,14 @@
 A further choice related to vertical coordinate concerns
 the presence (or not) of ocean cavities beneath ice shelves within the model domain.
-A setting of \np{ln_isfcav}{ln\_isfcav} as \forcode{.true.} indicates that the domain contains ocean cavities,
+A setting of \np{ln_isfcav}{ln\_isfcav} as \forcode{.true.} indicates that
+the domain contains ocean cavities,
 otherwise the top, wet layer of the ocean will always be at the ocean surface.
 This option is currently only available for $z$- or $zps$-coordinates.
 In the latter case, partial steps are also applied at the ocean/ice shelf interface.
 
-Within the model, the arrays describing the grid point depths and vertical scale factors are three set of
-three dimensional arrays $(i,j,k)$ defined at \textit{before}, \textit{now} and \textit{after} time step.
+Within the model,
+the arrays describing the grid point depths and vertical scale factors are
+three set of three dimensional arrays $(i,j,k)$ defined at
+\textit{before}, \textit{now} and \textit{after} time step.
 The time at which they are defined is indicated by a suffix: $\_b$, $\_n$, or $\_a$, respectively.
 They are updated at each model time step.
@@ -534,6 +572,6 @@
 \end{clines}
 
-This set of vertical metrics is sufficient to describe the initial depth and thickness of every gridcell in
-the model regardless of the choice of vertical coordinate.
+This set of vertical metrics is sufficient to describe the initial depth and thickness of
+every gridcell in the model regardless of the choice of vertical coordinate.
 With constant z-levels, e3 metrics will be uniform across each horizontal level.
 In the partial step case each e3 at the \jp{bottom\_level}
@@ -541,11 +579,12 @@
 may vary from its horizontal neighbours.
 And, in s-coordinates, variations can occur throughout the water column.
-With the non-linear free-surface, all the coordinates behave more like the s-coordinate in
-that variations occur throughout the water column with displacements related to the sea surface height.
+With the non-linear free-surface, all the coordinates behave more like the s-coordinate in that
+variations occur throughout the water column with displacements related to the sea surface height.
 These variations are typically much smaller than those arising from bottom fitted coordinates.
 The values for vertical metrics supplied in the domain configuration file can be considered as
 those arising from a flat sea surface with zero elevation.
 
-The \jp{bottom\_level} and \jp{top\_level} 2D arrays define the \jp{bottom\_level} and top wet levels in each grid column.
+The \jp{bottom\_level} and \jp{top\_level} 2D arrays define
+the \jp{bottom\_level} and top wet levels in each grid column.
 Without ice cavities, \jp{top\_level} is essentially a land mask (0 on land; 1 everywhere else).
 With ice cavities, \jp{top\_level} determines the first wet point below the overlying ice shelf.
@@ -556,23 +595,23 @@
 
 From \jp{top\_level} and \jp{bottom\_level} fields, the mask fields are defined as follows:
-\begin{alignat*}{2}
-  tmask(i,j,k) &= &  &
-    \begin{cases}
-                  0 &\text{if $                  k  <    top\_level(i,j)$} \\
-                  1 &\text{if $bottom\_level(i,j) \leq k \leq   top\_level(i,j)$} \\
-                  0 &\text{if $                  k  >     bottom\_level(i,j)$}
-    \end{cases}
-  \\
-  umask(i,j,k) &= &  &tmask(i,j,k) * tmask(i + 1,j,    k) \\
-  vmask(i,j,k) &= &  &tmask(i,j,k) * tmask(i    ,j + 1,k) \\
-  fmask(i,j,k) &= &  &tmask(i,j,k) * tmask(i + 1,j,    k) \\
-               &  &* &tmask(i,j,k) * tmask(i + 1,j,    k) \\
-  wmask(i,j,k) &= &  &tmask(i,j,k) * tmask(i    ,j,k - 1) \\
-  \text{with~} wmask(i,j,1) &= & &tmask(i,j,1)
-\end{alignat*}
+\begin{align*}
+  tmask(i,j,k) &=
+  \begin{cases}
+    0 &\text{if $                             k <    top\_level(i,j)$} \\
+    1 &\text{if $     bottom\_level(i,j) \leq k \leq top\_level(i,j)$} \\
+    0 &\text{if $k >  bottom\_level(i,j)                            $}
+  \end{cases} \\
+  umask(i,j,k) &= tmask(i,j,k) * tmask(i + 1,j,    k) \\
+  vmask(i,j,k) &= tmask(i,j,k) * tmask(i    ,j + 1,k) \\
+  fmask(i,j,k) &= tmask(i,j,k) * tmask(i + 1,j,    k) * tmask(i,j,k) * tmask(i + 1,j,    k) \\
+  wmask(i,j,k) &= tmask(i,j,k) * tmask(i    ,j,k - 1) \\
+  \text{with~} wmask(i,j,1) &= tmask(i,j,1)
+\end{align*}
 
 Note that, without ice shelves cavities,
-masks at $t-$ and $w-$points are identical with the numerical indexing used (\autoref{subsec:DOM_Num_Index}).
-Nevertheless, $wmask$ are required with ocean cavities to deal with the top boundary (ice shelf/ocean interface)
+masks at $t-$ and $w-$points are identical with the numerical indexing used
+(\autoref{subsec:DOM_Num_Index}).
+Nevertheless,
+$wmask$ are required with ocean cavities to deal with the top boundary (ice shelf/ocean interface)
 exactly in the same way as for the bottom boundary.
 
@@ -588,19 +627,21 @@
 \label{subsec:DOM_closea}
 
-When a global ocean is coupled to an atmospheric model it is better to represent all large water bodies
-(\eg\ Great Lakes, Caspian sea \dots) even if the model resolution does not allow their communication with
-the rest of the ocean.
+When a global ocean is coupled to an atmospheric model it is better to
+represent all large water bodies (\eg\ Great Lakes, Caspian sea, \dots) even if
+the model resolution does not allow their communication with the rest of the ocean.
 This is unnecessary when the ocean is forced by fixed atmospheric conditions,
 so these seas can be removed from the ocean domain.
-The user has the option to set the bathymetry in closed seas to zero (see \autoref{sec:MISC_closea}) and
-to optionally decide on the fate of any freshwater imbalance over the area.
-The options are explained in \autoref{sec:MISC_closea} but it should be noted here that
-a successful use of these options requires appropriate mask fields to be present in the domain configuration file.
+The user has the option to
+set the bathymetry in closed seas to zero (see \autoref{sec:MISC_closea}) and to
+optionally decide on the fate of any freshwater imbalance over the area.
+The options are explained in \autoref{sec:MISC_closea} but
+it should be noted here that a successful use of these options requires
+appropriate mask fields to be present in the domain configuration file.
 Among the possibilities are:
 
 \begin{clines}
-int    closea_mask          /* non-zero values in closed sea areas for optional masking                  */
-int    closea_mask_rnf      /* non-zero values in closed sea areas with runoff locations (precip only)   */
-int    closea_mask_emp      /* non-zero values in closed sea areas with runoff locations (total emp)     */
+int closea_mask     /* non-zero values in closed sea areas for optional masking                */
+int closea_mask_rnf /* non-zero values in closed sea areas with runoff locations (precip only) */
+int closea_mask_emp /* non-zero values in closed sea areas with runoff locations (total emp)   */
 \end{clines}
 
@@ -610,7 +651,7 @@
 
 Most of the arrays relating to a particular ocean model configuration discussed in this chapter
-(grid-point position, scale factors)
-can be saved in a file if
-namelist parameter \np{ln_write_cfg}{ln\_write\_cfg} (namelist \nam{cfg}{cfg}) is set to \forcode{.true.};
+(grid-point position, scale factors) can be saved in a file if
+namelist parameter \np{ln_write_cfg}{ln\_write\_cfg} (namelist \nam{cfg}{cfg}) is set to
+\forcode{.true.};
 the output filename is set through parameter \np{cn_domcfg_out}{cn\_domcfg\_out}.
 This is only really useful if
@@ -619,7 +660,8 @@
 
 Alternatively, all the arrays relating to a particular ocean model configuration
-(grid-point position, scale factors, depths and masks)
-can be saved in a file called \texttt{mesh\_mask} if
-namelist parameter \np{ln_meshmask}{ln\_meshmask} (namelist \nam{dom}{dom}) is set to \forcode{.true.}.
+(grid-point position, scale factors, depths and masks) can be saved in
+a file called \texttt{mesh\_mask} if
+namelist parameter \np{ln_meshmask}{ln\_meshmask} (namelist \nam{dom}{dom}) is set to
+\forcode{.true.}.
 This file contains additional fields that can be useful for post-processing applications.
 
@@ -627,4 +669,5 @@
 \section[Initial state (\textit{istate.F90} and \textit{dtatsd.F90})]{Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})}
 \label{sec:DOM_DTA_tsd}
+
 \begin{listing}
   \nlst{namtsd}
@@ -638,15 +681,19 @@
 
 \begin{description}
-\item [{\np[=.true.]{ln_tsd_init}{ln\_tsd\_init}}] Use T and S input files that can be given on the model grid itself or on their native input data grids.
-  In the latter case, the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid
+\item [{\np[=.true.]{ln_tsd_init}{ln\_tsd\_init}}] Use T and S input files that can be given on
+  the model grid itself or on their native input data grids.
+  In the latter case,
+  the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid
   (see \autoref{subsec:SBC_iof}).
-  The information relating to the input files are specified in the \np{sn_tem}{sn\_tem} and \np{sn_sal}{sn\_sal} structures.
+  The information relating to the input files are specified in
+  the \np{sn_tem}{sn\_tem} and \np{sn_sal}{sn\_sal} structures.
   The computation is done in the \mdl{dtatsd} module.
-\item [{\np[=.false.]{ln_tsd_init}{ln\_tsd\_init}}] Initial values for T and S are set via a user supplied \rou{usr\_def\_istate} routine contained in \mdl{userdef\_istate}.
+\item [{\np[=.false.]{ln_tsd_init}{ln\_tsd\_init}}] Initial values for T and S are set via
+  a user supplied \rou{usr\_def\_istate} routine contained in \mdl{userdef\_istate}.
   The default version sets horizontally uniform T and profiles as used in the GYRE configuration
   (see \autoref{sec:CFGS_gyre}).
 \end{description}
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_DYN.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_DYN.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_DYN.tex	(revision 11954)
@@ -67,6 +67,6 @@
 Furthermore, the tendency terms associated with the 2D barotropic vorticity balance (when \texttt{trdvor?} is defined)
 can be derived from the 3D terms.
-\gmcomment{STEVEN: not quite sure I've got the sense of the last sentence. does
-MISC correspond to "extracting tendency terms" or "vorticity balance"?}
+\cmtgm{STEVEN: not quite sure I've got the sense of the last sentence.
+  Does MISC correspond to "extracting tendency terms" or "vorticity balance"?}
 
 %% =================================================================================================
@@ -153,5 +153,5 @@
 as changes in the divergence of the barotropic transport are absorbed into the change of the level thicknesses,
 re-orientated downward.
-\gmcomment{not sure of this...  to be modified with the change in emp setting}
+\cmtgm{not sure of this...  to be modified with the change in emp setting}
 In the case of a linear free surface, the time derivative in \autoref{eq:DYN_wzv} disappears.
 The upper boundary condition applies at a fixed level $z=0$.
@@ -287,5 +287,5 @@
 $u$ and $v$ are located at different grid points,
 a price worth paying to avoid a double averaging in the pressure gradient term as in the $B$-grid.
-\gmcomment{ To circumvent this, Adcroft (ADD REF HERE)
+\cmtgm{ To circumvent this, Adcroft (ADD REF HERE)
 Nevertheless, this technique strongly distort the phase and group velocity of Rossby waves....}
 
@@ -311,5 +311,5 @@
 \begin{figure}[!ht]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_DYN_een_triad}
+  \includegraphics[width=0.66\textwidth]{DYN_een_triad}
   \caption[Triads used in the energy and enstrophy conserving scheme (EEN)]{
     Triads used in the energy and enstrophy conserving scheme (EEN) for
@@ -516,5 +516,5 @@
 In the vertical, the centred $2^{nd}$ order evaluation of the advection is preferred, \ie\ $u_{uw}^{ubs}$ and
 $u_{vw}^{ubs}$ in \autoref{eq:DYN_adv_cen2} are used.
-UBS is diffusive and is associated with vertical mixing of momentum. \gmcomment{ gm  pursue the
+UBS is diffusive and is associated with vertical mixing of momentum. \cmtgm{ gm  pursue the
 sentence:Since vertical mixing of momentum is a source term of the TKE equation...  }
 
@@ -534,5 +534,5 @@
 there is also the possibility of using a $4^{th}$ order evaluation of the advective velocity as in ROMS.
 This is an error and should be suppressed soon.
-\gmcomment{action :  this have to be done}
+\cmtgm{action :  this have to be done}
 
 %% =================================================================================================
@@ -846,5 +846,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_DYN_dynspg_ts}
+  \includegraphics[width=0.66\textwidth]{DYN_dynspg_ts}
   \caption[Split-explicit time stepping scheme for the external and internal modes]{
     Schematic of the split-explicit time stepping scheme for the external and internal modes.
@@ -915,5 +915,5 @@
 it is still significant as shown by \citet{levier.treguier.ea_rpt07} in the case of an analytical barotropic Kelvin wave.
 
-\gmcomment{               %%% copy from griffies Book
+\cmtgm{               %%% copy from griffies Book
 
 \textbf{title: Time stepping the barotropic system }
@@ -1043,5 +1043,5 @@
 
 %% gm %%======>>>>   given here the discrete eqs provided to the solver
-\gmcomment{               %%% copy from chap-model basics
+\cmtgm{               %%% copy from chap-model basics
   \[
     % \label{eq:DYN_spg_flt}
@@ -1054,5 +1054,5 @@
   and $\mathrm {\mathbf M}$ represents the collected contributions of the Coriolis, hydrostatic pressure gradient,
   non-linear and viscous terms in \autoref{eq:MB_dyn}.
-}   %end gmcomment
+}   %end cmtgm
 
 Note that in the linear free surface formulation (\texttt{vvl?} not defined),
@@ -1082,5 +1082,5 @@
 no slip or partial slip boundary conditions are applied according to the user's choice (see \autoref{chap:LBC}).
 
-\gmcomment{
+\cmtgm{
   Hyperviscous operators are frequently used in the simulation of turbulent flows to
   control the dissipation of unresolved small scale features.
@@ -1183,5 +1183,5 @@
 the first derivative term normal to the coast depends on the free or no-slip lateral boundary conditions chosen,
 while the third derivative terms normal to the coast are set to zero (see \autoref{chap:LBC}).
-\gmcomment{add a remark on the the change in the position of the coefficient}
+\cmtgm{add a remark on the the change in the position of the coefficient}
 
 %% =================================================================================================
@@ -1252,5 +1252,5 @@
 the snow-ice mass is taken into account when computing the surface pressure gradient.
 
-\gmcomment{ missing : the lateral boundary condition !!!   another external forcing
+\cmtgm{ missing : the lateral boundary condition !!!   another external forcing
  }
 
@@ -1480,5 +1480,5 @@
 \begin{figure}[!ht]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_WAD_dynhpg}
+  \includegraphics[width=0.66\textwidth]{DYN_WAD_dynhpg}
   \caption[Combinations controlling the limiting of the horizontal pressure gradient in
   wetting and drying regimes]{
@@ -1596,5 +1596,5 @@
 and only array swapping and Asselin filtering is done in \mdl{dynnxt}.
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_LBC.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_LBC.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_LBC.tex	(revision 11954)
@@ -25,5 +25,5 @@
 \clearpage
 
-%gm% add here introduction to this chapter
+\cmtgm{Add here introduction to this chapter}
 
 %% =================================================================================================
@@ -79,5 +79,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_LBC_uv}
+  \includegraphics[width=0.66\textwidth]{LBC_uv}
   \caption[Lateral boundary at $T$-level]{
     Lateral boundary (thick line) at T-level.
@@ -104,5 +104,5 @@
 \begin{figure}[!p]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_LBC_shlat}
+  \includegraphics[width=0.66\textwidth]{LBC_shlat}
   \caption[Lateral boundary conditions]{
     Lateral boundary conditions
@@ -201,5 +201,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_LBC_jperio}
+  \includegraphics[width=0.66\textwidth]{LBC_jperio}
   \caption[Setting of east-west cyclic and symmetric across the Equator boundary conditions]{
     Setting of (a) east-west cyclic (b) symmetric across the Equator boundary conditions}
@@ -219,5 +219,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_North_Fold_T}
+  \includegraphics[width=0.66\textwidth]{LBC_North_Fold_T}
   \caption[North fold boundary in ORCA 2\deg, 1/4\deg and 1/12\deg]{
     North fold boundary with a $T$-point pivot and cyclic east-west boundary condition ($jperio=4$),
@@ -272,5 +272,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_mpp}
+  \includegraphics[width=0.66\textwidth]{LBC_mpp}
   \caption{Positioning of a sub-domain when massively parallel processing is used}
   \label{fig:LBC_mpp}
@@ -325,5 +325,5 @@
 \begin{figure}[!ht]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_mppini2}
+  \includegraphics[width=0.66\textwidth]{LBC_mppini2}
   \caption[Atlantic domain defined for the CLIPPER projet]{
     Example of Atlantic domain defined for the CLIPPER projet.
@@ -596,5 +596,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_LBC_bdy_geom}
+  \includegraphics[width=0.66\textwidth]{LBC_bdy_geom}
   \caption[Geometry of unstructured open boundary]{Example of geometry of unstructured open boundary}
   \label{fig:LBC_bdy_geom}
@@ -631,5 +631,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_LBC_nc_header}
+  \includegraphics[width=0.66\textwidth]{LBC_nc_header}
   \caption[Header for a \protect\ifile{coordinates.bdy} file]{
     Example of the header for a \protect\ifile{coordinates.bdy} file}
@@ -708,5 +708,5 @@
 direction of rotation). %, e.g. anticlockwise or clockwise.
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_LDF.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_LDF.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_LDF.tex	(revision 11954)
@@ -68,5 +68,5 @@
 \label{sec:LDF_slp}
 
-\gmcomment{
+\cmtgm{
   we should emphasize here that the implementation is a rather old one.
   Better work can be achieved by using \citet{griffies.gnanadesikan.ea_JPO98, griffies_bk04} iso-neutral scheme.
@@ -84,5 +84,5 @@
 $r_{1f}$, $r_{1vw}$, $r_{2t}$, $r_{2vw}$ for $v$.
 
-%gm% add here afigure of the slope in i-direction
+\cmtgm{Add here afigure of the slope in i-direction}
 
 %% =================================================================================================
@@ -94,5 +94,6 @@
 the diffusive fluxes in the three directions are set to zero and $T$ is assumed to be horizontally uniform,
 \ie\ a linear function of $z_T$, the depth of a $T$-point.
-%gm { Steven : My version is obviously wrong since I'm left with an arbitrary constant which is the local vertical temperature gradient}
+\cmtgm{Steven : My version is obviously wrong since
+  I'm left with an arbitrary constant which is the local vertical temperature gradient}
 
 \begin{equation}
@@ -112,5 +113,5 @@
 \end{equation}
 
-%gm%  caution I'm not sure the simplification was a good idea!
+\cmtgm{Caution I'm not sure the simplification was a good idea!}
 
 These slopes are computed once in \rou{ldf\_slp\_init} when \np[=.true.]{ln_sco}{ln\_sco},
@@ -144,5 +145,5 @@
 \end{equation}
 
-%gm% rewrite this as the explanation is not very clear !!!
+\cmtgm{rewrite this as the explanation is not very clear !!!}
 %In practice, \autoref{eq:LDF_slp_iso} is of little help in evaluating the neutral surface slopes. Indeed, for an unsimplified equation of state, the density has a strong dependancy on pressure (here approximated as the depth), therefore applying \autoref{eq:LDF_slp_iso} using the $in situ$ density, $\rho$, computed at T-points leads to a flattening of slopes as the depth increases. This is due to the strong increase of the $in situ$ density with depth.
 
@@ -173,5 +174,4 @@
   will include a pressure dependent part, leading to the wrong evaluation of the neutral slopes.
 
-%gm%
   Note: The solution for $s$-coordinate passes trough the use of different (and better) expression for
   the constraint on iso-neutral fluxes.
@@ -182,5 +182,5 @@
     \alpha \ \textbf{F}(T) = \beta \ \textbf{F}(S)
   \]
-  % gm{  where vector F is ....}
+  \cmtgm{where vector F is ....}
 
 This constraint leads to the following definition for the slopes:
@@ -229,5 +229,5 @@
 This allows an iso-neutral diffusion scheme without additional background horizontal mixing.
 This technique can be viewed as a diffusion operator that acts along large-scale
-(2~$\Delta$x) \gmcomment{2deltax doesnt seem very large scale} iso-neutral surfaces.
+(2~$\Delta$x) \cmtgm{2deltax doesnt seem very large scale} iso-neutral surfaces.
 The diapycnal diffusion required for numerical stability is thus minimized and its net effect on the flow is quite small when compared to the effect of an horizontal background mixing.
 
@@ -237,5 +237,5 @@
 \begin{figure}[!ht]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_LDF_ZDF1}
+  \includegraphics[width=0.66\textwidth]{LDF_ZDF1}
   \caption{Averaging procedure for isopycnal slope computation}
   \label{fig:LDF_ZDF1}
@@ -263,5 +263,5 @@
 \begin{figure}[!ht]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_eiv_slp}
+  \includegraphics[width=0.66\textwidth]{LDF_eiv_slp}
   \caption[Vertical profile of the slope used for lateral mixing in the mixed layer]{
     Vertical profile of the slope used for lateral mixing in the mixed layer:
@@ -478,5 +478,5 @@
 
 %%gm  from Triad appendix  : to be incorporated....
-\gmcomment{
+\cmtgm{
   Values of iso-neutral diffusivity and GM coefficient are set as described in \autoref{sec:LDF_coef}.
   If none of the keys \key{traldf\_cNd}, N=1,2,3 is set (the default), spatially constant iso-neutral $A_l$ and
@@ -544,5 +544,5 @@
 \colorbox{yellow}{TBC}
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_OBS.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_OBS.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_OBS.tex	(revision 11954)
@@ -711,5 +711,5 @@
 \begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_OBS_avg_rec}
+  \includegraphics[width=0.66\textwidth]{OBS_avg_rec}
   \caption[Observational weights with a rectangular footprint]{
     Weights associated with each model grid box (blue lines and numbers)
@@ -720,5 +720,5 @@
 \begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_OBS_avg_rad}
+  \includegraphics[width=0.66\textwidth]{OBS_avg_rad}
   \caption[Observational weights with a radial footprint]{
     Weights associated with each model grid box (blue lines and numbers)
@@ -798,5 +798,5 @@
 \begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_ASM_obsdist_local}
+  \includegraphics[width=0.66\textwidth]{OBS_obsdist_local}
   \caption[Observations with the geographical distribution]{
     Example of the distribution of observations with
@@ -825,5 +825,5 @@
 \begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_ASM_obsdist_global}
+  \includegraphics[width=0.66\textwidth]{OBS_obsdist_global}
   \caption[Observations with the round-robin distribution]{
     Example of the distribution of observations with
@@ -855,5 +855,5 @@
 
 %% =================================================================================================
-\section{Standalone observation operator}
+\section{Standalone observation operator (\texttt{SAO})}
 \label{sec:OBS_sao}
 
@@ -1164,5 +1164,5 @@
 \begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_OBS_dataplot_main}
+  \includegraphics[width=0.66\textwidth]{OBS_dataplot_main}
   \caption{Main window of dataplot}
   \label{fig:OBS_dataplotmain}
@@ -1174,5 +1174,5 @@
 \begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_OBS_dataplot_prof}
+  \includegraphics[width=0.66\textwidth]{OBS_dataplot_prof}
   \caption[Profile plot from dataplot]{
     Profile plot from dataplot produced by right clicking on a point in the main window}
@@ -1180,5 +1180,5 @@
 \end{figure}
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_SBC.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_SBC.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_SBC.tex	(revision 11954)
@@ -880,11 +880,29 @@
 %ENDIF
 
-%\gmcomment{  word doc of runoffs:
-%In the current \NEMO\ setup river runoff is added to emp fluxes, these are then applied at just the sea surface as a volume change (in the variable volume case this is a literal volume change, and in the linear free surface case the free surface is moved) and a salt flux due to the concentration/dilution effect.  There is also an option to increase vertical mixing near river mouths; this gives the effect of having a 3d river.  All river runoff and emp fluxes are assumed to be fresh water (zero salinity) and at the same temperature as the sea surface.
-%Our aim was to code the option to specify the temperature and salinity of river runoff, (as well as the amount), along with the depth that the river water will affect.  This would make it possible to model low salinity outflow, such as the Baltic, and would allow the ocean temperature to be affected by river runoff.
-
-%The depth option makes it possible to have the river water affecting just the surface layer, throughout depth, or some specified point in between.
-
-%To do this we need to treat evaporation/precipitation fluxes and river runoff differently in the tra_sbc module.  We decided to separate them throughout the code, so that the variable emp represented solely evaporation minus precipitation fluxes, and a new 2d variable rnf was added which represents the volume flux of river runoff (in kg/m2s to remain consistent with emp).  This meant many uses of emp and emps needed to be changed, a list of all modules which use emp or emps and the changes made are below:
+\cmtgm{  word doc of runoffs:
+In the current \NEMO\ setup river runoff is added to emp fluxes,
+these are then applied at just the sea surface as a volume change (in the variable volume case
+this is a literal volume change, and in the linear free surface case the free surface is moved)
+and a salt flux due to the concentration/dilution effect.
+There is also an option to increase vertical mixing near river mouths;
+this gives the effect of having a 3d river.
+All river runoff and emp fluxes are assumed to be fresh water (zero salinity) and
+at the same temperature as the sea surface.
+Our aim was to code the option to specify the temperature and salinity of river runoff,
+(as well as the amount), along with the depth that the river water will affect.
+This would make it possible to model low salinity outflow, such as the Baltic,
+and would allow the ocean temperature to be affected by river runoff.
+
+The depth option makes it possible to have the river water affecting just the surface layer,
+throughout depth, or some specified point in between.
+
+To do this we need to treat evaporation/precipitation fluxes and river runoff differently in
+the \mdl{tra_sbc} module.
+We decided to separate them throughout the code,
+so that the variable emp represented solely evaporation minus precipitation fluxes,
+and a new 2d variable rnf was added which represents the volume flux of river runoff
+(in $kg/m^2s$ to remain consistent with $emp$).
+This meant many uses of emp and emps needed to be changed,
+a list of all modules which use $emp$ or $emps$ and the changes made are below:}
 
 %% =================================================================================================
@@ -908,62 +926,62 @@
   Two different bulk formulae are available:
 
-	\begin{description}
-	\item [{\np[=1]{nn_isfblk}{nn\_isfblk}}]: The melt rate is based on a balance between the upward ocean heat flux and
-     the latent heat flux at the ice shelf base. A complete description is available in \citet{hunter_rpt06}.
-	\item [{\np[=2]{nn_isfblk}{nn\_isfblk}}]: The melt rate and the heat flux are based on a 3 equations formulation
-     (a heat flux budget at the ice base, a salt flux budget at the ice base and a linearised freezing point temperature equation).
-     A complete description is available in \citet{jenkins_JGR91}.
-	\end{description}
-
-     Temperature and salinity used to compute the melt are the average temperature in the top boundary layer \citet{losch_JGR08}.
-     Its thickness is defined by \np{rn_hisf_tbl}{rn\_hisf\_tbl}.
-     The fluxes and friction velocity are computed using the mean temperature, salinity and velocity in the the first \np{rn_hisf_tbl}{rn\_hisf\_tbl} m.
-     Then, the fluxes are spread over the same thickness (ie over one or several cells).
-     If \np{rn_hisf_tbl}{rn\_hisf\_tbl} larger than top $e_{3}t$, there is no more feedback between the freezing point at the interface and the the top cell temperature.
-     This can lead to super-cool temperature in the top cell under melting condition.
-     If \np{rn_hisf_tbl}{rn\_hisf\_tbl} smaller than top $e_{3}t$, the top boundary layer thickness is set to the top cell thickness.\\
-
-     Each melt bulk formula depends on a exchange coeficient ($\Gamma^{T,S}$) between the ocean and the ice.
-     There are 3 different ways to compute the exchange coeficient:
-	\begin{description}
-        \item [{\np[=0]{nn_gammablk}{nn\_gammablk}}]: The salt and heat exchange coefficients are constant and defined by \np{rn_gammas0}{rn\_gammas0} and \np{rn_gammat0}{rn\_gammat0}.
-     \begin{gather*}
+  \begin{description}
+  \item [{\np[=1]{nn_isfblk}{nn\_isfblk}}]: The melt rate is based on a balance between the upward ocean heat flux and
+    the latent heat flux at the ice shelf base. A complete description is available in \citet{hunter_rpt06}.
+  \item [{\np[=2]{nn_isfblk}{nn\_isfblk}}]: The melt rate and the heat flux are based on a 3 equations formulation
+    (a heat flux budget at the ice base, a salt flux budget at the ice base and a linearised freezing point temperature equation).
+    A complete description is available in \citet{jenkins_JGR91}.
+  \end{description}
+
+  Temperature and salinity used to compute the melt are the average temperature in the top boundary layer \citet{losch_JGR08}.
+  Its thickness is defined by \np{rn_hisf_tbl}{rn\_hisf\_tbl}.
+  The fluxes and friction velocity are computed using the mean temperature, salinity and velocity in the the first \np{rn_hisf_tbl}{rn\_hisf\_tbl} m.
+  Then, the fluxes are spread over the same thickness (ie over one or several cells).
+  If \np{rn_hisf_tbl}{rn\_hisf\_tbl} larger than top $e_{3}t$, there is no more feedback between the freezing point at the interface and the the top cell temperature.
+  This can lead to super-cool temperature in the top cell under melting condition.
+  If \np{rn_hisf_tbl}{rn\_hisf\_tbl} smaller than top $e_{3}t$, the top boundary layer thickness is set to the top cell thickness.\\
+
+  Each melt bulk formula depends on a exchange coeficient ($\Gamma^{T,S}$) between the ocean and the ice.
+  There are 3 different ways to compute the exchange coeficient:
+  \begin{description}
+  \item [{\np[=0]{nn_gammablk}{nn\_gammablk}}]: The salt and heat exchange coefficients are constant and defined by \np{rn_gammas0}{rn\_gammas0} and \np{rn_gammat0}{rn\_gammat0}.
+    \begin{gather*}
        % \label{eq:SBC_isf_gamma_iso}
-       \gamma^{T} = rn\_gammat0 \\
-       \gamma^{S} = rn\_gammas0
-     \end{gather*}
-     This is the recommended formulation for ISOMIP.
-	\item [{\np[=1]{nn_gammablk}{nn\_gammablk}}]: The salt and heat exchange coefficients are velocity dependent and defined as
-     \begin{gather*}
-       \gamma^{T} = rn\_gammat0 \times u_{*} \\
-       \gamma^{S} = rn\_gammas0 \times u_{*}
-     \end{gather*}
-     where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn_hisf_tbl}{rn\_hisf\_tbl} meters).
-     See \citet{jenkins.nicholls.ea_JPO10} for all the details on this formulation. It is the recommended formulation for realistic application.
-	\item [{\np[=2]{nn_gammablk}{nn\_gammablk}}]: The salt and heat exchange coefficients are velocity and stability dependent and defined as:
-\[
-\gamma^{T,S} = \frac{u_{*}}{\Gamma_{Turb} + \Gamma^{T,S}_{Mole}}
-\]
-     where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn_hisf_tbl}{rn\_hisf\_tbl} meters),
-     $\Gamma_{Turb}$ the contribution of the ocean stability and
-     $\Gamma^{T,S}_{Mole}$ the contribution of the molecular diffusion.
-     See \citet{holland.jenkins_JPO99} for all the details on this formulation.
-     This formulation has not been extensively tested in \NEMO\ (not recommended).
-   \end{description}
-  \item [{\np[=2]{nn_isf}{nn\_isf}}]: The ice shelf cavity is not represented.
-   The fwf and heat flux are computed using the \citet{beckmann.goosse_OM03} parameterisation of isf melting.
-   The fluxes are distributed along the ice shelf edge between the depth of the average grounding line (GL)
-   (\np{sn_depmax_isf}{sn\_depmax\_isf}) and the base of the ice shelf along the calving front
-   (\np{sn_depmin_isf}{sn\_depmin\_isf}) as in (\np[=3]{nn_isf}{nn\_isf}).
-   The effective melting length (\np{sn_Leff_isf}{sn\_Leff\_isf}) is read from a file.
-  \item [{\np[=3]{nn_isf}{nn\_isf}}]: The ice shelf cavity is not represented.
-   The fwf (\np{sn_rnfisf}{sn\_rnfisf}) is prescribed and distributed along the ice shelf edge between
-   the depth of the average grounding line (GL) (\np{sn_depmax_isf}{sn\_depmax\_isf}) and
-   the base of the ice shelf along the calving front (\np{sn_depmin_isf}{sn\_depmin\_isf}).
-   The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$.
-  \item [{\np[=4]{nn_isf}{nn\_isf}}]: The ice shelf cavity is opened (\np[=.true.]{ln_isfcav}{ln\_isfcav} needed).
-   However, the fwf is not computed but specified from file \np{sn_fwfisf}{sn\_fwfisf}).
-   The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$.
-   As in \np[=1]{nn_isf}{nn\_isf}, the fluxes are spread over the top boundary layer thickness (\np{rn_hisf_tbl}{rn\_hisf\_tbl})\\
+      \gamma^{T} = rn\_gammat0 \\
+      \gamma^{S} = rn\_gammas0
+    \end{gather*}
+    This is the recommended formulation for ISOMIP.
+  \item [{\np[=1]{nn_gammablk}{nn\_gammablk}}]: The salt and heat exchange coefficients are velocity dependent and defined as
+    \begin{gather*}
+      \gamma^{T} = rn\_gammat0 \times u_{*} \\
+      \gamma^{S} = rn\_gammas0 \times u_{*}
+    \end{gather*}
+    where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn_hisf_tbl}{rn\_hisf\_tbl} meters).
+    See \citet{jenkins.nicholls.ea_JPO10} for all the details on this formulation. It is the recommended formulation for realistic application.
+  \item [{\np[=2]{nn_gammablk}{nn\_gammablk}}]: The salt and heat exchange coefficients are velocity and stability dependent and defined as:
+    \[
+      \gamma^{T,S} = \frac{u_{*}}{\Gamma_{Turb} + \Gamma^{T,S}_{Mole}}
+    \]
+    where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn_hisf_tbl}{rn\_hisf\_tbl} meters),
+    $\Gamma_{Turb}$ the contribution of the ocean stability and
+    $\Gamma^{T,S}_{Mole}$ the contribution of the molecular diffusion.
+    See \citet{holland.jenkins_JPO99} for all the details on this formulation.
+    This formulation has not been extensively tested in \NEMO\ (not recommended).
+  \end{description}
+\item [{\np[=2]{nn_isf}{nn\_isf}}]: The ice shelf cavity is not represented.
+  The fwf and heat flux are computed using the \citet{beckmann.goosse_OM03} parameterisation of isf melting.
+  The fluxes are distributed along the ice shelf edge between the depth of the average grounding line (GL)
+  (\np{sn_depmax_isf}{sn\_depmax\_isf}) and the base of the ice shelf along the calving front
+  (\np{sn_depmin_isf}{sn\_depmin\_isf}) as in (\np[=3]{nn_isf}{nn\_isf}).
+  The effective melting length (\np{sn_Leff_isf}{sn\_Leff\_isf}) is read from a file.
+\item [{\np[=3]{nn_isf}{nn\_isf}}]: The ice shelf cavity is not represented.
+  The fwf (\np{sn_rnfisf}{sn\_rnfisf}) is prescribed and distributed along the ice shelf edge between
+  the depth of the average grounding line (GL) (\np{sn_depmax_isf}{sn\_depmax\_isf}) and
+  the base of the ice shelf along the calving front (\np{sn_depmin_isf}{sn\_depmin\_isf}).
+  The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$.
+\item [{\np[=4]{nn_isf}{nn\_isf}}]: The ice shelf cavity is opened (\np[=.true.]{ln_isfcav}{ln\_isfcav} needed).
+  However, the fwf is not computed but specified from file \np{sn_fwfisf}{sn\_fwfisf}).
+  The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$.
+  As in \np[=1]{nn_isf}{nn\_isf}, the fluxes are spread over the top boundary layer thickness (\np{rn_hisf_tbl}{rn\_hisf\_tbl})
 \end{description}
 
@@ -986,5 +1004,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_SBC_isf}
+  \includegraphics[width=0.66\textwidth]{SBC_isf}
   \caption[Ice shelf location and fresh water flux definition]{
     Illustration of the location where the fwf is injected and
@@ -1307,5 +1325,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_SBC_diurnal}
+  \includegraphics[width=0.66\textwidth]{SBC_diurnal}
   \caption[Reconstruction of the diurnal cycle variation of short wave flux]{
     Example of reconstruction of the diurnal cycle variation of short wave flux from
@@ -1341,5 +1359,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_SBC_dcy}
+  \includegraphics[width=0.66\textwidth]{SBC_dcy}
   \caption[Reconstruction of the diurnal cycle variation of short wave flux on an ORCA2 grid]{
     Example of reconstruction of the diurnal cycle variation of short wave flux from
@@ -1521,5 +1539,5 @@
 % in ocean-ice models.
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_STO.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_STO.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_STO.tex	(revision 11954)
@@ -205,5 +205,5 @@
 The first four parameters define the stochastic part of equation of state.
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_TRA.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_TRA.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_TRA.tex	(revision 11954)
@@ -14,10 +14,9 @@
 {\footnotesize
   \begin{tabularx}{\textwidth}{l||X|X}
-    Release & Author(s) & Modifications \\
+    Release          & Author(s)                                   & Modifications       \\
     \hline
-    {\em   4.0} & {\em ...} & {\em ...} \\
-    {\em   3.6} & {\em ...} & {\em ...} \\
-    {\em   3.4} & {\em ...} & {\em ...} \\
-    {\em <=3.4} & {\em ...} & {\em ...}
+    {\em        4.0} & {\em Christian \'{E}th\'{e}               } & {\em Review       } \\
+    {\em        3.6} & {\em Gurvan Madec                         } & {\em Update       } \\
+    {\em $\leq$ 3.4} & {\em Gurvan Madec and S\'{e}bastien Masson} & {\em First version} \\
   \end{tabularx}
 }
@@ -34,6 +33,6 @@
 the tracer equations are available depending on the vertical coordinate used and on the physics used.
 In all the equations presented here, the masking has been omitted for simplicity.
-One must be aware that all the quantities are masked fields and that each time a mean or
-difference operator is used, the resulting field is multiplied by a mask.
+One must be aware that all the quantities are masked fields and that
+each time a mean or difference operator is used, the resulting field is multiplied by a mask.
 
 The two active tracers are potential temperature and salinity.
@@ -46,7 +45,9 @@
 NXT stands for next, referring to the time-stepping.
 From left to right, the terms on the rhs of the tracer equations are the advection (ADV),
-the lateral diffusion (LDF), the vertical diffusion (ZDF), the contributions from the external forcings
-(SBC: Surface Boundary Condition, QSR: penetrative Solar Radiation, and BBC: Bottom Boundary Condition),
-the contribution from the bottom boundary Layer (BBL) parametrisation, and an internal damping (DMP) term.
+the lateral diffusion (LDF), the vertical diffusion (ZDF),
+the contributions from the external forcings (SBC: Surface Boundary Condition,
+QSR: penetrative Solar Radiation, and BBC: Bottom Boundary Condition),
+the contribution from the bottom boundary Layer (BBL) parametrisation,
+and an internal damping (DMP) term.
 The terms QSR, BBC, BBL and DMP are optional.
 The external forcings and parameterisations require complex inputs and complex calculations
@@ -54,12 +55,12 @@
 LDF and ZDF modules and described in \autoref{chap:SBC}, \autoref{chap:LDF} and
 \autoref{chap:ZDF}, respectively.
-Note that \mdl{tranpc}, the non-penetrative convection module, although located in
-the \path{./src/OCE/TRA} directory as it directly modifies the tracer fields,
+Note that \mdl{tranpc}, the non-penetrative convection module,
+although located in the \path{./src/OCE/TRA} directory as it directly modifies the tracer fields,
 is described with the model vertical physics (ZDF) together with
 other available parameterization of convection.
 
-In the present chapter we also describe the diagnostic equations used to compute the sea-water properties
-(density, Brunt-V\"{a}is\"{a}l\"{a} frequency, specific heat and freezing point with
-associated modules \mdl{eosbn2} and \mdl{phycst}).
+In the present chapter we also describe the diagnostic equations used to
+compute the sea-water properties (density, Brunt-V\"{a}is\"{a}l\"{a} frequency, specific heat and
+freezing point with associated modules \mdl{eosbn2} and \mdl{phycst}).
 
 The different options available to the user are managed by namelist logicals.
@@ -70,5 +71,6 @@
 
 The user has the option of extracting each tendency term on the RHS of the tracer equation for output
-(\np{ln_tra_trd}{ln\_tra\_trd} or \np[=.true.]{ln_tra_mxl}{ln\_tra\_mxl}), as described in \autoref{chap:DIA}.
+(\np{ln_tra_trd}{ln\_tra\_trd} or \np[=.true.]{ln_tra_mxl}{ln\_tra\_mxl}),
+as described in \autoref{chap:DIA}.
 
 %% =================================================================================================
@@ -85,5 +87,5 @@
 the advection tendency of a tracer is expressed in flux form,
 \ie\ as the divergence of the advective fluxes.
-Its discrete expression is given by :
+Its discrete expression is given by:
 \begin{equation}
   \label{eq:TRA_adv}
@@ -94,15 +96,19 @@
 where $\tau$ is either T or S, and $b_t = e_{1t} \, e_{2t} \, e_{3t}$ is the volume of $T$-cells.
 The flux form in \autoref{eq:TRA_adv} implicitly requires the use of the continuity equation.
-Indeed, it is obtained by using the following equality: $\nabla \cdot (\vect U \, T) = \vect U \cdot \nabla T$ which
-results from the use of the continuity equation, $\partial_t e_3 + e_3 \; \nabla \cdot \vect U = 0$
-(which reduces to $\nabla \cdot \vect U = 0$ in linear free surface, \ie\ \np[=.true.]{ln_linssh}{ln\_linssh}).
-Therefore it is of paramount importance to design the discrete analogue of the advection tendency so that
-it is consistent with the continuity equation in order to enforce the conservation properties of
-the continuous equations.
-In other words, by setting $\tau = 1$ in (\autoref{eq:TRA_adv}) we recover the discrete form of
-the continuity equation which is used to calculate the vertical velocity.
-\begin{figure}[!t]
+Indeed, it is obtained by using the following equality:
+$\nabla \cdot (\vect U \, T) = \vect U \cdot \nabla T$ which
+results from the use of the continuity equation,
+$\partial_t e_3 + e_3 \; \nabla \cdot \vect U = 0$
+(which reduces to $\nabla \cdot \vect U = 0$ in linear free surface,
+\ie\ \np[=.true.]{ln_linssh}{ln\_linssh}).
+Therefore it is of paramount importance to
+design the discrete analogue of the advection tendency so that
+it is consistent with the continuity equation in order to
+enforce the conservation properties of the continuous equations.
+In other words, by setting $\tau = 1$ in (\autoref{eq:TRA_adv}) we recover
+the discrete form of the continuity equation which is used to calculate the vertical velocity.
+\begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_adv_scheme}
+  \includegraphics[width=0.66\textwidth]{TRA_adv_scheme}
   \caption[Ways to evaluate the tracer value and the amount of tracer exchanged]{
     Schematic representation of some ways used to evaluate the tracer value at $u$-point and
@@ -120,6 +126,6 @@
 \end{figure}
 
-The key difference between the advection schemes available in \NEMO\ is the choice made in space and
-time interpolation to define the value of the tracer at the velocity points
+The key difference between the advection schemes available in \NEMO\ is the choice made in
+space and time interpolation to define the value of the tracer at the velocity points
 (\autoref{fig:TRA_adv_scheme}).
 
@@ -129,21 +135,25 @@
 
 \begin{description}
-\item [linear free surface:] (\np[=.true.]{ln_linssh}{ln\_linssh})
+\item [linear free surface] (\np[=.true.]{ln_linssh}{ln\_linssh})
   the first level thickness is constant in time:
-  the vertical boundary condition is applied at the fixed surface $z = 0$ rather than on
-  the moving surface $z = \eta$.
-  There is a non-zero advective flux which is set for all advection schemes as
-  $\tau_w|_{k = 1/2} = T_{k = 1}$, \ie\ the product of surface velocity (at $z = 0$) by
-  the first level tracer value.
-\item [non-linear free surface:] (\np[=.false.]{ln_linssh}{ln\_linssh})
+  the vertical boundary condition is applied at the fixed surface $z = 0$ rather than
+  on the moving surface $z = \eta$.
+  There is a non-zero advective flux which is set for
+  all advection schemes as $\tau_w|_{k = 1/2} = T_{k = 1}$,
+  \ie\ the product of surface velocity (at $z = 0$) by the first level tracer value.
+\item [non-linear free surface] (\np[=.false.]{ln_linssh}{ln\_linssh})
   convergence/divergence in the first ocean level moves the free surface up/down.
-  There is no tracer advection through it so that the advective fluxes through the surface are also zero.
+  There is no tracer advection through it so that
+  the advective fluxes through the surface are also zero.
 \end{description}
 
 In all cases, this boundary condition retains local conservation of tracer.
-Global conservation is obtained in non-linear free surface case, but \textit{not} in the linear free surface case.
-Nevertheless, in the latter case, it is achieved to a good approximation since
-the non-conservative term is the product of the time derivative of the tracer and the free surface height,
-two quantities that are not correlated \citep{roullet.madec_JGR00, griffies.pacanowski.ea_MWR01, campin.adcroft.ea_OM04}.
+Global conservation is obtained in non-linear free surface case,
+but \textit{not} in the linear free surface case.
+Nevertheless, in the latter case,
+it is achieved to a good approximation since the non-conservative term is
+the product of the time derivative of the tracer and the free surface height,
+two quantities that are not correlated
+\citep{roullet.madec_JGR00, griffies.pacanowski.ea_MWR01, campin.adcroft.ea_OM04}.
 
 The velocity field that appears in (\autoref{eq:TRA_adv} is
@@ -153,36 +163,45 @@
 (see \autoref{chap:LDF}).
 
-Several tracer advection scheme are proposed, namely a $2^{nd}$ or $4^{th}$ order centred schemes (CEN),
-a $2^{nd}$ or $4^{th}$ order Flux Corrected Transport scheme (FCT), a Monotone Upstream Scheme for
-Conservative Laws scheme (MUSCL), a $3^{rd}$ Upstream Biased Scheme (UBS, also often called UP3),
-and a Quadratic Upstream Interpolation for Convective Kinematics with Estimated Streaming Terms scheme (QUICKEST).
-The choice is made in the \nam{tra_adv}{tra\_adv} namelist, by setting to \forcode{.true.} one of
-the logicals \textit{ln\_traadv\_xxx}.
-The corresponding code can be found in the \textit{traadv\_xxx.F90} module, where
-\textit{xxx} is a 3 or 4 letter acronym corresponding to each scheme.
-By default (\ie\ in the reference namelist, \textit{namelist\_ref}), all the logicals are set to \forcode{.false.}.
-If the user does not select an advection scheme in the configuration namelist (\textit{namelist\_cfg}),
-the tracers will \textit{not} be advected!
+Several tracer advection scheme are proposed,
+namely a $2^{nd}$ or $4^{th}$ order \textbf{CEN}tred schemes (CEN),
+a $2^{nd}$ or $4^{th}$ order \textbf{F}lux \textbf{C}orrected \textbf{T}ransport scheme (FCT),
+a \textbf{M}onotone \textbf{U}pstream \textbf{S}cheme for
+\textbf{C}onservative \textbf{L}aws scheme (MUSCL),
+a $3^{rd}$ \textbf{U}pstream \textbf{B}iased \textbf{S}cheme (UBS, also often called UP3),
+and a \textbf{Q}uadratic \textbf{U}pstream \textbf{I}nterpolation for
+\textbf{C}onvective \textbf{K}inematics with
+\textbf{E}stimated \textbf{S}treaming \textbf{T}erms scheme (QUICKEST).
+The choice is made in the \nam{tra_adv}{tra\_adv} namelist,
+by setting to \forcode{.true.} one of the logicals \textit{ln\_traadv\_xxx}.
+The corresponding code can be found in the \textit{traadv\_xxx.F90} module,
+where \textit{xxx} is a 3 or 4 letter acronym corresponding to each scheme.
+By default (\ie\ in the reference namelist, \textit{namelist\_ref}),
+all the logicals are set to \forcode{.false.}.
+If the user does not select an advection scheme in the configuration namelist
+(\textit{namelist\_cfg}), the tracers will \textit{not} be advected!
 
 Details of the advection schemes are given below.
-The choosing an advection scheme is a complex matter which depends on the model physics, model resolution,
-type of tracer, as well as the issue of numerical cost. In particular, we note that
+The choosing an advection scheme is a complex matter which depends on the
+model physics, model resolution, type of tracer, as well as the issue of numerical cost.
+In particular, we note that
 
 \begin{enumerate}
-\item CEN and FCT schemes require an explicit diffusion operator while the other schemes are diffusive enough so that
-  they do not necessarily need additional diffusion;
-\item CEN and UBS are not \textit{positive} schemes
-  \footnote{negative values can appear in an initially strictly positive tracer field which is advected},
+\item CEN and FCT schemes require an explicit diffusion operator while
+  the other schemes are diffusive enough so that they do not necessarily need additional diffusion;
+\item CEN and UBS are not \textit{positive} schemes \footnote{negative values can appear in
+    an initially strictly positive tracer field which is advected},
   implying that false extrema are permitted.
   Their use is not recommended on passive tracers;
-\item It is recommended that the same advection-diffusion scheme is used on both active and passive tracers.
+\item It is recommended that the same advection-diffusion scheme is used on
+  both active and passive tracers.
 \end{enumerate}
 
-Indeed, if a source or sink of a passive tracer depends on an active one, the difference of treatment of active and
-passive tracers can create very nice-looking frontal structures that are pure numerical artefacts.
+Indeed, if a source or sink of a passive tracer depends on an active one,
+the difference of treatment of active and passive tracers can create
+very nice-looking frontal structures that are pure numerical artefacts.
 Nevertheless, most of our users set a different treatment on passive and active tracers,
 that's the reason why this possibility is offered.
-We strongly suggest them to perform a sensitivity experiment using a same treatment to assess the robustness of
-their results.
+We strongly suggest them to perform a sensitivity experiment using a same treatment to
+assess the robustness of their results.
 
 %% =================================================================================================
@@ -192,11 +211,12 @@
 %        2nd order centred scheme
 
-The centred advection scheme (CEN) is used when \np[=.true.]{ln_traadv_cen}{ln\_traadv\_cen}.
-Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on horizontal (iso-level) and vertical direction by
+The \textbf{CEN}tred advection scheme (CEN) is used when \np[=.true.]{ln_traadv_cen}{ln\_traadv\_cen}.
+Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on
+horizontal (iso-level) and vertical direction by
 setting \np{nn_cen_h}{nn\_cen\_h} and \np{nn_cen_v}{nn\_cen\_v} to $2$ or $4$.
 CEN implementation can be found in the \mdl{traadv\_cen} module.
 
-In the $2^{nd}$ order centred formulation (CEN2), the tracer at velocity points is evaluated as the mean of
-the two neighbouring $T$-point values.
+In the $2^{nd}$ order centred formulation (CEN2), the tracer at velocity points is evaluated as
+the mean of the two neighbouring $T$-point values.
 For example, in the $i$-direction :
 \begin{equation}
@@ -205,9 +225,10 @@
 \end{equation}
 
-CEN2 is non diffusive (\ie\ it conserves the tracer variance, $\tau^2$) but dispersive
-(\ie\ it may create false extrema).
-It is therefore notoriously noisy and must be used in conjunction with an explicit diffusion operator to
-produce a sensible solution.
-The associated time-stepping is performed using a leapfrog scheme in conjunction with an Asselin time-filter,
+CEN2 is non diffusive (\ie\ it conserves the tracer variance, $\tau^2$) but
+dispersive (\ie\ it may create false extrema).
+It is therefore notoriously noisy and must be used in conjunction with
+an explicit diffusion operator to produce a sensible solution.
+The associated time-stepping is performed using
+a leapfrog scheme in conjunction with an Asselin time-filter,
 so $T$ in (\autoref{eq:TRA_adv_cen2}) is the \textit{now} tracer value.
 
@@ -217,6 +238,7 @@
 %        4nd order centred scheme
 
-In the $4^{th}$ order formulation (CEN4), tracer values are evaluated at u- and v-points as
-a $4^{th}$ order interpolation, and thus depend on the four neighbouring $T$-points.
+In the $4^{th}$ order formulation (CEN4),
+tracer values are evaluated at u- and v-points as a $4^{th}$ order interpolation,
+and thus depend on the four neighbouring $T$-points.
 For example, in the $i$-direction:
 \begin{equation}
@@ -226,21 +248,23 @@
 In the vertical direction (\np[=4]{nn_cen_v}{nn\_cen\_v}),
 a $4^{th}$ COMPACT interpolation has been prefered \citep{demange_phd14}.
-In the COMPACT scheme, both the field and its derivative are interpolated, which leads, after a matrix inversion,
-spectral characteristics similar to schemes of higher order \citep{lele_JCP92}.
+In the COMPACT scheme, both the field and its derivative are interpolated,
+which leads, after a matrix inversion, spectral characteristics similar to schemes of higher order
+\citep{lele_JCP92}.
 
 Strictly speaking, the CEN4 scheme is not a $4^{th}$ order advection scheme but
 a $4^{th}$ order evaluation of advective fluxes,
 since the divergence of advective fluxes \autoref{eq:TRA_adv} is kept at $2^{nd}$ order.
-The expression \textit{$4^{th}$ order scheme} used in oceanographic literature is usually associated with
-the scheme presented here.
-Introducing a \forcode{.true.} $4^{th}$ order advection scheme is feasible but, for consistency reasons,
-it requires changes in the discretisation of the tracer advection together with changes in the continuity equation,
-and the momentum advection and pressure terms.
+The expression \textit{$4^{th}$ order scheme} used in oceanographic literature is
+usually associated with the scheme presented here.
+Introducing a ``true'' $4^{th}$ order advection scheme is feasible but, for consistency reasons,
+it requires changes in the discretisation of the tracer advection together with
+changes in the continuity equation, and the momentum advection and pressure terms.
 
 A direct consequence of the pseudo-fourth order nature of the scheme is that it is not non-diffusive,
 \ie\ the global variance of a tracer is not preserved using CEN4.
-Furthermore, it must be used in conjunction with an explicit diffusion operator to produce a sensible solution.
-As in CEN2 case, the time-stepping is performed using a leapfrog scheme in conjunction with an Asselin time-filter,
-so $T$ in (\autoref{eq:TRA_adv_cen4}) is the \textit{now} tracer.
+Furthermore, it must be used in conjunction with an explicit diffusion operator to
+produce a sensible solution.
+As in CEN2 case, the time-stepping is performed using a leapfrog scheme in conjunction with
+an Asselin time-filter, so $T$ in (\autoref{eq:TRA_adv_cen4}) is the \textit{now} tracer.
 
 At a $T$-grid cell adjacent to a boundary (coastline, bottom and surface),
@@ -248,6 +272,6 @@
 This hypothesis usually reduces the order of the scheme.
 Here we choose to set the gradient of $T$ across the boundary to zero.
-Alternative conditions can be specified, such as a reduction to a second order scheme for
-these near boundary grid points.
+Alternative conditions can be specified,
+such as a reduction to a second order scheme for these near boundary grid points.
 
 %% =================================================================================================
@@ -255,11 +279,13 @@
 \label{subsec:TRA_adv_tvd}
 
-The Flux Corrected Transport schemes (FCT) is used when \np[=.true.]{ln_traadv_fct}{ln\_traadv\_fct}.
-Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on horizontal (iso-level) and vertical direction by
+The \textbf{F}lux \textbf{C}orrected \textbf{T}ransport schemes (FCT) is used when
+\np[=.true.]{ln_traadv_fct}{ln\_traadv\_fct}.
+Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on
+horizontal (iso-level) and vertical direction by
 setting \np{nn_fct_h}{nn\_fct\_h} and \np{nn_fct_v}{nn\_fct\_v} to $2$ or $4$.
 FCT implementation can be found in the \mdl{traadv\_fct} module.
 
-In FCT formulation, the tracer at velocity points is evaluated using a combination of an upstream and
-a centred scheme.
+In FCT formulation, the tracer at velocity points is evaluated using
+a combination of an upstream and a centred scheme.
 For example, in the $i$-direction :
 \begin{equation}
@@ -270,6 +296,5 @@
                      T_{i + 1} & \text{if~} u_{i + 1/2} <    0 \\
                      T_i       & \text{if~} u_{i + 1/2} \geq 0 \\
-    \end{cases}
-    \\
+    \end{cases} \\
     \tau_u^{fct} &= \tau_u^{ups} + c_u \, \big( \tau_u^{cen} - \tau_u^{ups} \big)
   \end{split}
@@ -288,6 +313,6 @@
 $\tau_u^{cen}$ is evaluated in (\autoref{eq:TRA_adv_fct}) using the \textit{now} tracer while
 $\tau_u^{ups}$ is evaluated using the \textit{before} tracer.
-In other words, the advective part of the scheme is time stepped with a leap-frog scheme
-while a forward scheme is used for the diffusive part.
+In other words, the advective part of the scheme is time stepped with a leap-frog scheme while
+a forward scheme is used for the diffusive part.
 
 %% =================================================================================================
@@ -295,33 +320,34 @@
 \label{subsec:TRA_adv_mus}
 
-The Monotone Upstream Scheme for Conservative Laws (MUSCL) is used when \np[=.true.]{ln_traadv_mus}{ln\_traadv\_mus}.
+The \textbf{M}onotone \textbf{U}pstream \textbf{S}cheme for \textbf{C}onservative \textbf{L}aws
+(MUSCL) is used when \np[=.true.]{ln_traadv_mus}{ln\_traadv\_mus}.
 MUSCL implementation can be found in the \mdl{traadv\_mus} module.
 
 MUSCL has been first implemented in \NEMO\ by \citet{levy.estublier.ea_GRL01}.
-In its formulation, the tracer at velocity points is evaluated assuming a linear tracer variation between
-two $T$-points (\autoref{fig:TRA_adv_scheme}).
+In its formulation, the tracer at velocity points is evaluated assuming
+a linear tracer variation between two $T$-points (\autoref{fig:TRA_adv_scheme}).
 For example, in the $i$-direction :
-\begin{equation}
+\[
   % \label{eq:TRA_adv_mus}
   \tau_u^{mus} = \lt\{
   \begin{split}
-                       \tau_i         &+ \frac{1}{2} \lt( 1 - \frac{u_{i + 1/2} \, \rdt}{e_{1u}} \rt)
-                       \widetilde{\partial_i         \tau} & \text{if~} u_{i + 1/2} \geqslant 0 \\
-                       \tau_{i + 1/2} &+ \frac{1}{2} \lt( 1 + \frac{u_{i + 1/2} \, \rdt}{e_{1u}} \rt)
-                       \widetilde{\partial_{i + 1/2} \tau} & \text{if~} u_{i + 1/2} <         0
+    \tau_i        &+ \frac{1}{2} \lt( 1 - \frac{u_{i + 1/2} \, \rdt}{e_{1u}} \rt)
+    \widetilde{\partial_i        \tau} & \text{if~} u_{i + 1/2} \geqslant 0 \\
+    \tau_{i + 1/2} &+ \frac{1}{2} \lt( 1 + \frac{u_{i + 1/2} \, \rdt}{e_{1u}} \rt)
+    \widetilde{\partial_{i + 1/2} \tau} & \text{if~} u_{i + 1/2} <         0
   \end{split}
                                                                                                       \rt.
-\end{equation}
-where $\widetilde{\partial_i \tau}$ is the slope of the tracer on which a limitation is imposed to
-ensure the \textit{positive} character of the scheme.
-
-The time stepping is performed using a forward scheme, that is the \textit{before} tracer field is used to
-evaluate $\tau_u^{mus}$.
+\]
+where $\widetilde{\partial_i \tau}$ is the slope of the tracer on which
+a limitation is imposed to ensure the \textit{positive} character of the scheme.
+
+The time stepping is performed using a forward scheme,
+that is the \textit{before} tracer field is used to evaluate $\tau_u^{mus}$.
 
 For an ocean grid point adjacent to land and where the ocean velocity is directed toward land,
 an upstream flux is used.
 This choice ensure the \textit{positive} character of the scheme.
-In addition, fluxes round a grid-point where a runoff is applied can optionally be computed using upstream fluxes
-(\np[=.true.]{ln_mus_ups}{ln\_mus\_ups}).
+In addition, fluxes round a grid-point where a runoff is applied can optionally be computed using
+upstream fluxes (\np[=.true.]{ln_mus_ups}{ln\_mus\_ups}).
 
 %% =================================================================================================
@@ -329,9 +355,11 @@
 \label{subsec:TRA_adv_ubs}
 
-The Upstream-Biased Scheme (UBS) is used when \np[=.true.]{ln_traadv_ubs}{ln\_traadv\_ubs}.
+The \textbf{U}pstream-\textbf{B}iased \textbf{S}cheme (UBS) is used when
+\np[=.true.]{ln_traadv_ubs}{ln\_traadv\_ubs}.
 UBS implementation can be found in the \mdl{traadv\_mus} module.
 
 The UBS scheme, often called UP3, is also known as the Cell Averaged QUICK scheme
-(Quadratic Upstream Interpolation for Convective Kinematics).
+(\textbf{Q}uadratic \textbf{U}pstream \textbf{I}nterpolation for
+\textbf{C}onvective \textbf{K}inematics).
 It is an upstream-biased third order scheme based on an upstream-biased parabolic interpolation.
 For example, in the $i$-direction:
@@ -340,35 +368,39 @@
   \tau_u^{ubs} = \overline T ^{i + 1/2} - \frac{1}{6}
     \begin{cases}
-                                                      \tau"_i       & \text{if~} u_{i + 1/2} \geqslant 0 \\
-                                                      \tau"_{i + 1} & \text{if~} u_{i + 1/2} <         0
+      \tau"_i       & \text{if~} u_{i + 1/2} \geqslant 0 \\
+      \tau"_{i + 1} & \text{if~} u_{i + 1/2} <         0
     \end{cases}
-  \quad
-  \text{where~} \tau"_i = \delta_i \lt[ \delta_{i + 1/2} [\tau] \rt]
+  \quad \text{where~} \tau"_i = \delta_i \lt[ \delta_{i + 1/2} [\tau] \rt]
 \end{equation}
 
 This results in a dissipatively dominant (i.e. hyper-diffusive) truncation error
 \citep{shchepetkin.mcwilliams_OM05}.
-The overall performance of the advection scheme is similar to that reported in \cite{farrow.stevens_JPO95}.
+The overall performance of the advection scheme is similar to that reported in
+\cite{farrow.stevens_JPO95}.
 It is a relatively good compromise between accuracy and smoothness.
 Nevertheless the scheme is not \textit{positive}, meaning that false extrema are permitted,
 but the amplitude of such are significantly reduced over the centred second or fourth order method.
-Therefore it is not recommended that it should be applied to a passive tracer that requires positivity.
+Therefore it is not recommended that it should be applied to
+a passive tracer that requires positivity.
 
 The intrinsic diffusion of UBS makes its use risky in the vertical direction where
 the control of artificial diapycnal fluxes is of paramount importance
 \citep{shchepetkin.mcwilliams_OM05, demange_phd14}.
-Therefore the vertical flux is evaluated using either a $2^nd$ order FCT scheme or a $4^th$ order COMPACT scheme
-(\np[=2 or 4]{nn_ubs_v}{nn\_ubs\_v}).
-
-For stability reasons (see \autoref{chap:TD}), the first term  in \autoref{eq:TRA_adv_ubs}
-(which corresponds to a second order centred scheme)
-is evaluated using the \textit{now} tracer (centred in time) while the second term
-(which is the diffusive part of the scheme),
+Therefore the vertical flux is evaluated using either a $2^nd$ order FCT scheme or
+a $4^th$ order COMPACT scheme (\np[=2 or 4]{nn_ubs_v}{nn\_ubs\_v}).
+
+For stability reasons (see \autoref{chap:TD}),
+the first term  in \autoref{eq:TRA_adv_ubs} (which corresponds to a second order centred scheme)
+is evaluated using the \textit{now}    tracer (centred in time) while
+the second term (which is the diffusive part of the scheme),
 is evaluated using the \textit{before} tracer (forward in time).
-This choice is discussed by \citet{webb.de-cuevas.ea_JAOT98} in the context of the QUICK advection scheme.
+This choice is discussed by \citet{webb.de-cuevas.ea_JAOT98} in
+the context of the QUICK advection scheme.
 UBS and QUICK schemes only differ by one coefficient.
-Replacing 1/6 with 1/8 in \autoref{eq:TRA_adv_ubs} leads to the QUICK advection scheme \citep{webb.de-cuevas.ea_JAOT98}.
+Replacing 1/6 with 1/8 in \autoref{eq:TRA_adv_ubs} leads to the QUICK advection scheme
+\citep{webb.de-cuevas.ea_JAOT98}.
 This option is not available through a namelist parameter, since the 1/6 coefficient is hard coded.
-Nevertheless it is quite easy to make the substitution in the \mdl{traadv\_ubs} module and obtain a QUICK scheme.
+Nevertheless it is quite easy to make the substitution in the \mdl{traadv\_ubs} module and
+obtain a QUICK scheme.
 
 Note that it is straightforward to rewrite \autoref{eq:TRA_adv_ubs} as follows:
@@ -389,9 +421,11 @@
 Firstly, it clearly reveals that the UBS scheme is based on the fourth order scheme to which
 an upstream-biased diffusion term is added.
-Secondly, this emphasises that the $4^{th}$ order part (as well as the $2^{nd}$ order part as stated above) has to
-be evaluated at the \textit{now} time step using \autoref{eq:TRA_adv_ubs}.
-Thirdly, the diffusion term is in fact a biharmonic operator with an eddy coefficient which
-is simply proportional to the velocity: $A_u^{lm} = \frac{1}{12} \, {e_{1u}}^3 \, |u|$.
-Note the current version of \NEMO\ uses the computationally more efficient formulation \autoref{eq:TRA_adv_ubs}.
+Secondly,
+this emphasises that the $4^{th}$ order part (as well as the $2^{nd}$ order part as stated above) has to be evaluated at the \textit{now} time step using \autoref{eq:TRA_adv_ubs}.
+Thirdly, the diffusion term is in fact a biharmonic operator with
+an eddy coefficient which is simply proportional to the velocity:
+$A_u^{lm} = \frac{1}{12} \, {e_{1u}}^3 \, |u|$.
+Note the current version of \NEMO\ uses the computationally more efficient formulation
+\autoref{eq:TRA_adv_ubs}.
 
 %% =================================================================================================
@@ -399,11 +433,14 @@
 \label{subsec:TRA_adv_qck}
 
-The Quadratic Upstream Interpolation for Convective Kinematics with Estimated Streaming Terms (QUICKEST) scheme
-proposed by \citet{leonard_CMAME79} is used when \np[=.true.]{ln_traadv_qck}{ln\_traadv\_qck}.
+The \textbf{Q}uadratic \textbf{U}pstream \textbf{I}nterpolation for
+\textbf{C}onvective \textbf{K}inematics with \textbf{E}stimated \textbf{S}treaming \textbf{T}erms
+(QUICKEST) scheme proposed by \citet{leonard_CMAME79} is used when
+\np[=.true.]{ln_traadv_qck}{ln\_traadv\_qck}.
 QUICKEST implementation can be found in the \mdl{traadv\_qck} module.
 
 QUICKEST is the third order Godunov scheme which is associated with the ULTIMATE QUICKEST limiter
 \citep{leonard_CMAME91}.
-It has been implemented in \NEMO\ by G. Reffray (MERCATOR-ocean) and can be found in the \mdl{traadv\_qck} module.
+It has been implemented in \NEMO\ by G. Reffray (Mercator Ocean) and
+can be found in the \mdl{traadv\_qck} module.
 The resulting scheme is quite expensive but \textit{positive}.
 It can be used on both active and passive tracers.
@@ -412,7 +449,8 @@
 Therefore the vertical flux is evaluated using the CEN2 scheme.
 This no longer guarantees the positivity of the scheme.
-The use of FCT in the vertical direction (as for the UBS case) should be implemented to restore this property.
-
-%%%gmcomment   :  Cross term are missing in the current implementation....
+The use of FCT in the vertical direction (as for the UBS case) should be implemented to
+restore this property.
+
+\cmtgm{Cross term are missing in the current implementation....}
 
 %% =================================================================================================
@@ -428,9 +466,12 @@
 Options are defined through the \nam{tra_ldf}{tra\_ldf} namelist variables.
 They are regrouped in four items, allowing to specify
-$(i)$   the type of operator used (none, laplacian, bilaplacian),
-$(ii)$  the direction along which the operator acts (iso-level, horizontal, iso-neutral),
-$(iii)$ some specific options related to the rotated operators (\ie\ non-iso-level operator), and
-$(iv)$  the specification of eddy diffusivity coefficient (either constant or variable in space and time).
-Item $(iv)$ will be described in \autoref{chap:LDF}.
+\begin{enumerate*}[label=(\textit{\roman*})]
+\item the type of operator used (none, laplacian, bilaplacian),
+\item the direction along which the operator acts (iso-level, horizontal, iso-neutral),
+\item some specific options related to the rotated operators (\ie\ non-iso-level operator), and
+\item the specification of eddy diffusivity coefficient
+  (either constant or variable in space and time).
+\end{enumerate*}
+Item (iv) will be described in \autoref{chap:LDF}.
 The direction along which the operators act is defined through the slope between
 this direction and the iso-level surfaces.
@@ -440,7 +481,9 @@
 \ie\ the tracers appearing in its expression are the \textit{before} tracers in time,
 except for the pure vertical component that appears when a rotation tensor is used.
-This latter component is solved implicitly together with the vertical diffusion term (see \autoref{chap:TD}).
-When \np[=.true.]{ln_traldf_msc}{ln\_traldf\_msc}, a Method of Stabilizing Correction is used in which
-the pure vertical component is split into an explicit and an implicit part \citep{lemarie.debreu.ea_OM12}.
+This latter component is solved implicitly together with the vertical diffusion term
+(see \autoref{chap:TD}).
+When \np[=.true.]{ln_traldf_msc}{ln\_traldf\_msc},
+a Method of Stabilizing Correction is used in which the pure vertical component is split into
+an explicit and an implicit part \citep{lemarie.debreu.ea_OM12}.
 
 %% =================================================================================================
@@ -451,8 +494,11 @@
 
 \begin{description}
-\item [{\np[=.true.]{ln_traldf_OFF}{ln\_traldf\_OFF}}] no operator selected, the lateral diffusive tendency will not be applied to the tracer equation.
-  This option can be used when the selected advection scheme is diffusive enough (MUSCL scheme for example).
+\item [{\np[=.true.]{ln_traldf_OFF}{ln\_traldf\_OFF}}] no operator selected,
+  the lateral diffusive tendency will not be applied to the tracer equation.
+  This option can be used when the selected advection scheme is diffusive enough
+  (MUSCL scheme for example).
 \item [{\np[=.true.]{ln_traldf_lap}{ln\_traldf\_lap}}] a laplacian operator is selected.
-  This harmonic operator takes the following expression:  $\mathcal{L}(T) = \nabla \cdot A_{ht} \; \nabla T $,
+  This harmonic operator takes the following expression:
+  $\mathcal{L}(T) = \nabla \cdot A_{ht} \; \nabla T $,
   where the gradient operates along the selected direction (see \autoref{subsec:TRA_ldf_dir}),
   and $A_{ht}$ is the eddy diffusivity coefficient expressed in $m^2/s$ (see \autoref{chap:LDF}).
@@ -461,5 +507,6 @@
   $\mathcal{B} = - \mathcal{L}(\mathcal{L}(T)) = - \nabla \cdot b \nabla (\nabla \cdot b \nabla T)$
   where the gradient operats along the selected direction,
-  and $b^2 = B_{ht}$ is the eddy diffusivity coefficient expressed in $m^4/s$ (see \autoref{chap:LDF}).
+  and $b^2 = B_{ht}$ is the eddy diffusivity coefficient expressed in $m^4/s$
+  (see \autoref{chap:LDF}).
   In the code, the bilaplacian operator is obtained by calling the laplacian twice.
 \end{description}
@@ -469,6 +516,7 @@
 minimizing the impact on the larger scale features.
 The main difference between the two operators is the scale selectiveness.
-The bilaplacian damping time (\ie\ its spin down time) scales like $\lambda^{-4}$ for
-disturbances of wavelength $\lambda$ (so that short waves damped more rapidelly than long ones),
+The bilaplacian damping time (\ie\ its spin down time) scales like
+$\lambda^{-4}$ for disturbances of wavelength $\lambda$
+(so that short waves damped more rapidelly than long ones),
 whereas the laplacian damping time scales only like $\lambda^{-2}$.
 
@@ -479,6 +527,6 @@
 The choice of a direction of action determines the form of operator used.
 The operator is a simple (re-entrant) laplacian acting in the (\textbf{i},\textbf{j}) plane when
-iso-level option is used (\np[=.true.]{ln_traldf_lev}{ln\_traldf\_lev}) or
-when a horizontal (\ie\ geopotential) operator is demanded in \textit{z}-coordinate
+iso-level option is used (\np[=.true.]{ln_traldf_lev}{ln\_traldf\_lev}) or when
+a horizontal (\ie\ geopotential) operator is demanded in \textit{z}-coordinate
 (\np{ln_traldf_hor}{ln\_traldf\_hor} and \np[=.true.]{ln_zco}{ln\_zco}).
 The associated code can be found in the \mdl{traldf\_lap\_blp} module.
@@ -489,6 +537,6 @@
 see \mdl{traldf\_iso} or \mdl{traldf\_triad} module, resp.), or
 when a horizontal (\ie\ geopotential) operator is demanded in \textit{s}-coordinate
-(\np{ln_traldf_hor}{ln\_traldf\_hor} and \np{ln_sco}{ln\_sco} = \forcode{.true.})
-\footnote{In this case, the standard iso-neutral operator will be automatically selected}.
+(\np{ln_traldf_hor}{ln\_traldf\_hor} and \np{ln_sco}{ln\_sco} = \forcode{.true.}) \footnote{
+  In this case, the standard iso-neutral operator will be automatically selected}.
 In that case, a rotation is applied to the gradient(s) that appears in the operator so that
 diffusive fluxes acts on the three spatial direction.
@@ -511,11 +559,15 @@
 first (and third in bilaplacian case) horizontal tracer derivative are masked.
 It is implemented in the \rou{tra\_ldf\_lap} subroutine found in the \mdl{traldf\_lap\_blp} module.
-The module also contains \rou{tra\_ldf\_blp}, the subroutine calling twice \rou{tra\_ldf\_lap} in order to
+The module also contains \rou{tra\_ldf\_blp},
+the subroutine calling twice \rou{tra\_ldf\_lap} in order to
 compute the iso-level bilaplacian operator.
 
 It is a \textit{horizontal} operator (\ie acting along geopotential surfaces) in
-the $z$-coordinate with or without partial steps, but is simply an iso-level operator in the $s$-coordinate.
-It is thus used when, in addition to \np{ln_traldf_lap}{ln\_traldf\_lap} or \np[=.true.]{ln_traldf_blp}{ln\_traldf\_blp},
-we have \np[=.true.]{ln_traldf_lev}{ln\_traldf\_lev} or \np{ln_traldf_hor}{ln\_traldf\_hor}~=~\np[=.true.]{ln_zco}{ln\_zco}.
+the $z$-coordinate with or without partial steps,
+but is simply an iso-level operator in the $s$-coordinate.
+It is thus used when,
+in addition to \np{ln_traldf_lap}{ln\_traldf\_lap} or \np[=.true.]{ln_traldf_blp}{ln\_traldf\_blp},
+we have \np[=.true.]{ln_traldf_lev}{ln\_traldf\_lev} or
+\np[=]{ln_traldf_hor}{ln\_traldf\_hor}\np[=.true.]{ln_zco}{ln\_zco}.
 In both cases, it significantly contributes to diapycnal mixing.
 It is therefore never recommended, even when using it in the bilaplacian case.
@@ -523,5 +575,6 @@
 Note that in the partial step $z$-coordinate (\np[=.true.]{ln_zps}{ln\_zps}),
 tracers in horizontally adjacent cells are located at different depths in the vicinity of the bottom.
-In this case, horizontal derivatives in (\autoref{eq:TRA_ldf_lap}) at the bottom level require a specific treatment.
+In this case,
+horizontal derivatives in (\autoref{eq:TRA_ldf_lap}) at the bottom level require a specific treatment.
 They are calculated in the \mdl{zpshde} module, described in \autoref{sec:TRA_zpshde}.
 
@@ -533,6 +586,7 @@
 \subsubsection[Standard rotated (bi-)laplacian operator (\textit{traldf\_iso.F90})]{Standard rotated (bi-)laplacian operator (\protect\mdl{traldf\_iso})}
 \label{subsec:TRA_ldf_iso}
+
 The general form of the second order lateral tracer subgrid scale physics (\autoref{eq:MB_zdf})
-takes the following semi -discrete space form in $z$- and $s$-coordinates:
+takes the following semi-discrete space form in $z$- and $s$-coordinates:
 \begin{equation}
   \label{eq:TRA_ldf_iso}
@@ -554,20 +608,23 @@
 or both \np[=.true.]{ln_traldf_hor}{ln\_traldf\_hor} and \np[=.true.]{ln_zco}{ln\_zco}.
 The way these slopes are evaluated is given in \autoref{sec:LDF_slp}.
-At the surface, bottom and lateral boundaries, the turbulent fluxes of heat and salt are set to zero using
-the mask technique (see \autoref{sec:LBC_coast}).
+At the surface, bottom and lateral boundaries,
+the turbulent fluxes of heat and salt are set to zero using the mask technique
+(see \autoref{sec:LBC_coast}).
 
 The operator in \autoref{eq:TRA_ldf_iso} involves both lateral and vertical derivatives.
-For numerical stability, the vertical second derivative must be solved using the same implicit time scheme as that
-used in the vertical physics (see \autoref{sec:TRA_zdf}).
+For numerical stability, the vertical second derivative must be solved using
+the same implicit time scheme as that used in the vertical physics (see \autoref{sec:TRA_zdf}).
 For computer efficiency reasons, this term is not computed in the \mdl{traldf\_iso} module,
 but in the \mdl{trazdf} module where, if iso-neutral mixing is used,
-the vertical mixing coefficient is simply increased by $\frac{e_{1w} e_{2w}}{e_{3w}}(r_{1w}^2 + r_{2w}^2)$.
+the vertical mixing coefficient is simply increased by
+$\frac{e_{1w} e_{2w}}{e_{3w}}(r_{1w}^2 + r_{2w}^2)$.
 
 This formulation conserves the tracer but does not ensure the decrease of the tracer variance.
-Nevertheless the treatment performed on the slopes (see \autoref{chap:LDF}) allows the model to run safely without
-any additional background horizontal diffusion \citep{guilyardi.madec.ea_CD01}.
+Nevertheless the treatment performed on the slopes (see \autoref{chap:LDF}) allows the model to
+run safely without any additional background horizontal diffusion \citep{guilyardi.madec.ea_CD01}.
 
 Note that in the partial step $z$-coordinate (\np[=.true.]{ln_zps}{ln\_zps}),
-the horizontal derivatives at the bottom level in \autoref{eq:TRA_ldf_iso} require a specific treatment.
+the horizontal derivatives at the bottom level in \autoref{eq:TRA_ldf_iso} require
+a specific treatment.
 They are calculated in module zpshde, described in \autoref{sec:TRA_zpshde}.
 
@@ -576,13 +633,16 @@
 \label{subsec:TRA_ldf_triad}
 
-An alternative scheme developed by \cite{griffies.gnanadesikan.ea_JPO98} which ensures tracer variance decreases
-is also available in \NEMO\ (\np[=.true.]{ln_traldf_triad}{ln\_traldf\_triad}).
+An alternative scheme developed by \cite{griffies.gnanadesikan.ea_JPO98} which
+ensures tracer variance decreases is also available in \NEMO\
+(\np[=.true.]{ln_traldf_triad}{ln\_traldf\_triad}).
 A complete description of the algorithm is given in \autoref{apdx:TRIADS}.
 
-The lateral fourth order bilaplacian operator on tracers is obtained by applying (\autoref{eq:TRA_ldf_lap}) twice.
+The lateral fourth order bilaplacian operator on tracers is obtained by
+applying (\autoref{eq:TRA_ldf_lap}) twice.
 The operator requires an additional assumption on boundary conditions:
 both first and third derivative terms normal to the coast are set to zero.
 
-The lateral fourth order operator formulation on tracers is obtained by applying (\autoref{eq:TRA_ldf_iso}) twice.
+The lateral fourth order operator formulation on tracers is obtained by
+applying (\autoref{eq:TRA_ldf_iso}) twice.
 It requires an additional assumption on boundary conditions:
 first and third derivative terms normal to the coast,
@@ -593,11 +653,12 @@
 \label{subsec:TRA_ldf_options}
 
-\begin{itemize}
-\item \np{ln_traldf_msc}{ln\_traldf\_msc} = Method of Stabilizing Correction (both operators)
-\item \np{rn_slpmax}{rn\_slpmax} = slope limit (both operators)
-\item \np{ln_triad_iso}{ln\_triad\_iso} = pure horizontal mixing in ML (triad only)
-\item \np{rn_sw_triad}{rn\_sw\_triad} $= 1$ switching triad; $= 0$ all 4 triads used (triad only)
-\item \np{ln_botmix_triad}{ln\_botmix\_triad} = lateral mixing on bottom (triad only)
-\end{itemize}
+\begin{labeling}{{\np{ln_botmix_triad}{ln\_botmix\_triad}}}
+\item [{\np{ln_traldf_msc}{ln\_traldf\_msc}    }] Method of Stabilizing Correction (both operators)
+\item [{\np{rn_slpmax}{rn\_slpmax}             }] Slope limit (both operators)
+\item [{\np{ln_triad_iso}{ln\_triad\_iso}      }] Pure horizontal mixing in ML (triad only)
+\item [{\np{rn_sw_triad}{rn\_sw\_triad}        }] \forcode{=1} switching triad;
+  \forcode{= 0} all 4 triads used (triad only)
+\item [{\np{ln_botmix_triad}{ln\_botmix\_triad}}] Lateral mixing on bottom (triad only)
+\end{labeling}
 
 %% =================================================================================================
@@ -606,20 +667,21 @@
 
 Options are defined through the \nam{zdf}{zdf} namelist variables.
-The formulation of the vertical subgrid scale tracer physics is the same for all the vertical coordinates,
-and is based on a laplacian operator.
-The vertical diffusion operator given by (\autoref{eq:MB_zdf}) takes the following semi -discrete space form:
-\begin{gather*}
+The formulation of the vertical subgrid scale tracer physics is the same for
+all the vertical coordinates, and is based on a laplacian operator.
+The vertical diffusion operator given by (\autoref{eq:MB_zdf}) takes
+the following semi-discrete space form:
+\[
   % \label{eq:TRA_zdf}
-    D^{vT}_T = \frac{1}{e_{3t}} \, \delta_k \lt[ \, \frac{A^{vT}_w}{e_{3w}} \delta_{k + 1/2}[T] \, \rt] \\
-    D^{vS}_T = \frac{1}{e_{3t}} \; \delta_k \lt[ \, \frac{A^{vS}_w}{e_{3w}} \delta_{k + 1/2}[S] \, \rt]
-\end{gather*}
-where $A_w^{vT}$ and $A_w^{vS}$ are the vertical eddy diffusivity coefficients on temperature and salinity,
-respectively.
+  D^{vT}_T = \frac{1}{e_{3t}} \, \delta_k \lt[ \, \frac{A^{vT}_w}{e_{3w}} \delta_{k + 1/2}[T] \, \rt] \quad
+  D^{vS}_T = \frac{1}{e_{3t}} \; \delta_k \lt[ \, \frac{A^{vS}_w}{e_{3w}} \delta_{k + 1/2}[S] \, \rt]
+\]
+where $A_w^{vT}$ and $A_w^{vS}$ are the vertical eddy diffusivity coefficients on
+temperature and salinity, respectively.
 Generally, $A_w^{vT} = A_w^{vS}$ except when double diffusive mixing is parameterised
 (\ie\ \np[=.true.]{ln_zdfddm}{ln\_zdfddm},).
 The way these coefficients are evaluated is given in \autoref{chap:ZDF} (ZDF).
-Furthermore, when iso-neutral mixing is used, both mixing coefficients are increased by
-$\frac{e_{1w} e_{2w}}{e_{3w} }({r_{1w}^2 + r_{2w}^2})$ to account for the vertical second derivative of
-\autoref{eq:TRA_ldf_iso}.
+Furthermore, when iso-neutral mixing is used,
+both mixing coefficients are increased by $\frac{e_{1w} e_{2w}}{e_{3w} }({r_{1w}^2 + r_{2w}^2})$ to
+account for the vertical second derivative of \autoref{eq:TRA_ldf_iso}.
 
 At the surface and bottom boundaries, the turbulent fluxes of heat and salt must be specified.
@@ -628,6 +690,6 @@
 a geothermal flux forcing is prescribed as a bottom boundary condition (see \autoref{subsec:TRA_bbc}).
 
-The large eddy coefficient found in the mixed layer together with high vertical resolution implies that
-there would be too restrictive constraint on the time step if we use explicit time stepping.
+The large eddy coefficient found in the mixed layer together with high vertical resolution implies
+that there would be too restrictive constraint on the time step if we use explicit time stepping.
 Therefore an implicit time stepping is preferred for the vertical diffusion since
 it overcomes the stability constraint.
@@ -648,34 +710,37 @@
 
 Due to interactions and mass exchange of water ($F_{mass}$) with other Earth system components
-(\ie\ atmosphere, sea-ice, land), the change in the heat and salt content of the surface layer of the ocean is due
-both to the heat and salt fluxes crossing the sea surface (not linked with $F_{mass}$) and
+(\ie\ atmosphere, sea-ice, land),
+the change in the heat and salt content of the surface layer of the ocean is due both to
+the heat and salt fluxes crossing the sea surface (not linked with $F_{mass}$) and
 to the heat and salt content of the mass exchange.
 They are both included directly in $Q_{ns}$, the surface heat flux,
 and $F_{salt}$, the surface salt flux (see \autoref{chap:SBC} for further details).
-By doing this, the forcing formulation is the same for any tracer (including temperature and salinity).
-
-The surface module (\mdl{sbcmod}, see \autoref{chap:SBC}) provides the following forcing fields (used on tracers):
-
-\begin{itemize}
-\item $Q_{ns}$, the non-solar part of the net surface heat flux that crosses the sea surface
-  (\ie\ the difference between the total surface heat flux and the fraction of the short wave flux that
-  penetrates into the water column, see \autoref{subsec:TRA_qsr})
+By doing this, the forcing formulation is the same for any tracer
+(including temperature and salinity).
+
+The surface module (\mdl{sbcmod}, see \autoref{chap:SBC}) provides the following forcing fields
+(used on tracers):
+
+\begin{labeling}{\textit{fwfisf}}
+\item [$Q_{ns}$] The non-solar part of the net surface heat flux that crosses the sea surface
+  (\ie\ the difference between the total surface heat flux and
+  the fraction of the short wave flux that penetrates into the water column,
+  see \autoref{subsec:TRA_qsr})
   plus the heat content associated with of the mass exchange with the atmosphere and lands.
-\item $\textit{sfx}$, the salt flux resulting from ice-ocean mass exchange (freezing, melting, ridging...)
-\item \textit{emp}, the mass flux exchanged with the atmosphere (evaporation minus precipitation) and
+\item [\textit{sfx}] The salt flux resulting from ice-ocean mass exchange
+  (freezing, melting, ridging...)
+\item [\textit{emp}] The mass flux exchanged with the atmosphere (evaporation minus precipitation) and
   possibly with the sea-ice and ice-shelves.
-\item \textit{rnf}, the mass flux associated with runoff
+\item [\textit{rnf}] The mass flux associated with runoff
   (see \autoref{sec:SBC_rnf} for further detail of how it acts on temperature and salinity tendencies)
-\item \textit{fwfisf}, the mass flux associated with ice shelf melt,
+\item [\textit{fwfisf}] The mass flux associated with ice shelf melt,
   (see \autoref{sec:SBC_isf} for further details on how the ice shelf melt is computed and applied).
-\end{itemize}
+\end{labeling}
 
 The surface boundary condition on temperature and salinity is applied as follows:
 \begin{equation}
   \label{eq:TRA_sbc}
-  \begin{alignedat}{2}
-    F^T &= \frac{1}{C_p} &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} &\overline{Q_{ns}      }^t \\
-    F^S &=               &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} &\overline{\textit{sfx}}^t
-  \end{alignedat}
+    F^T = \frac{1}{C_p} \frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} \overline{Q_{ns}      }^t \qquad
+    F^S =               \frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}} \overline{\textit{sfx}}^t
 \end{equation}
 where $\overline x^t$ means that $x$ is averaged over two consecutive time steps
@@ -683,23 +748,25 @@
 Such time averaging prevents the divergence of odd and even time step (see \autoref{chap:TD}).
 
-In the linear free surface case (\np[=.true.]{ln_linssh}{ln\_linssh}), an additional term has to be added on
-both temperature and salinity.
-On temperature, this term remove the heat content associated with mass exchange that has been added to $Q_{ns}$.
-On salinity, this term mimics the concentration/dilution effect that would have resulted from a change in
-the volume of the first level.
+In the linear free surface case (\np[=.true.]{ln_linssh}{ln\_linssh}),
+an additional term has to be added on both temperature and salinity.
+On temperature, this term remove the heat content associated with
+mass exchange that has been added to $Q_{ns}$.
+On salinity, this term mimics the concentration/dilution effect that would have resulted from
+a change in the volume of the first level.
 The resulting surface boundary condition is applied as follows:
 \begin{equation}
   \label{eq:TRA_sbc_lin}
-  \begin{alignedat}{2}
-    F^T &= \frac{1}{C_p} &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}}
-          &\overline{(Q_{ns}       - C_p \, \textit{emp} \lt. T \rt|_{k = 1})}^t \\
-    F^S &=               &\frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}}
-          &\overline{(\textit{sfx} -        \textit{emp} \lt. S \rt|_{k = 1})}^t
-  \end{alignedat}
-\end{equation}
-Note that an exact conservation of heat and salt content is only achieved with non-linear free surface.
+    F^T = \frac{1}{C_p} \frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}}
+          \overline{(Q_{ns}       - C_p \, \textit{emp} \lt. T \rt|_{k = 1})}^t \qquad
+    F^S =               \frac{1}{\rho_o \lt. e_{3t} \rt|_{k = 1}}
+          \overline{(\textit{sfx} -        \textit{emp} \lt. S \rt|_{k = 1})}^t
+\end{equation}
+Note that an exact conservation of heat and salt content is only achieved with
+non-linear free surface.
 In the linear free surface case, there is a small imbalance.
-The imbalance is larger than the imbalance associated with the Asselin time filter \citep{leclair.madec_OM09}.
-This is the reason why the modified filter is not applied in the linear free surface case (see \autoref{chap:TD}).
+The imbalance is larger than the imbalance associated with the Asselin time filter
+\citep{leclair.madec_OM09}.
+This is the reason why the modified filter is not applied in the linear free surface case
+(see \autoref{chap:TD}).
 
 %% =================================================================================================
@@ -716,8 +783,9 @@
 When the penetrative solar radiation option is used (\np[=.true.]{ln_traqsr}{ln\_traqsr}),
 the solar radiation penetrates the top few tens of meters of the ocean.
-If it is not used (\np[=.false.]{ln_traqsr}{ln\_traqsr}) all the heat flux is absorbed in the first ocean level.
-Thus, in the former case a term is added to the time evolution equation of temperature \autoref{eq:MB_PE_tra_T} and
-the surface boundary condition is modified to take into account only the non-penetrative part of the surface
-heat flux:
+If it is not used (\np[=.false.]{ln_traqsr}{ln\_traqsr}) all the heat flux is absorbed in
+the first ocean level.
+Thus, in the former case a term is added to the time evolution equation of temperature
+\autoref{eq:MB_PE_tra_T} and the surface boundary condition is modified to
+take into account only the non-penetrative part of the surface heat flux:
 \begin{equation}
   \label{eq:TRA_PE_qsr}
@@ -736,13 +804,15 @@
 
 The shortwave radiation, $Q_{sr}$, consists of energy distributed across a wide spectral range.
-The ocean is strongly absorbing for wavelengths longer than 700~nm and these wavelengths contribute to
-heating the upper few tens of centimetres.
-The fraction of $Q_{sr}$ that resides in these almost non-penetrative wavebands, $R$, is $\sim 58\%$
+The ocean is strongly absorbing for wavelengths longer than 700 $nm$ and
+these wavelengths contribute to heat the upper few tens of centimetres.
+The fraction of $Q_{sr}$ that resides in these almost non-penetrative wavebands, $R$, is $\sim$ 58\%
 (specified through namelist parameter \np{rn_abs}{rn\_abs}).
-It is assumed to penetrate the ocean with a decreasing exponential profile, with an e-folding depth scale, $\xi_0$,
-of a few tens of centimetres (typically $\xi_0 = 0.35~m$ set as \np{rn_si0}{rn\_si0} in the \nam{tra_qsr}{tra\_qsr} namelist).
-For shorter wavelengths (400-700~nm), the ocean is more transparent, and solar energy propagates to
-larger depths where it contributes to local heating.
-The way this second part of the solar energy penetrates into the ocean depends on which formulation is chosen.
+It is assumed to penetrate the ocean with a decreasing exponential profile,
+with an e-folding depth scale, $\xi_0$, of a few tens of centimetres
+(typically $\xi_0 = 0.35~m$ set as \np{rn_si0}{rn\_si0} in the \nam{tra_qsr}{tra\_qsr} namelist).
+For shorter wavelengths (400-700 $nm$), the ocean is more transparent,
+and solar energy propagates to larger depths where it contributes to local heating.
+The way this second part of the solar energy penetrates into
+the ocean depends on which formulation is chosen.
 In the simple 2-waveband light penetration scheme (\np[=.true.]{ln_qsr_2bd}{ln\_qsr\_2bd})
 a chlorophyll-independent monochromatic formulation is chosen for the shorter wavelengths,
@@ -754,6 +824,6 @@
 where $\xi_1$ is the second extinction length scale associated with the shorter wavelengths.
 It is usually chosen to be 23~m by setting the \np{rn_si0}{rn\_si0} namelist parameter.
-The set of default values ($\xi_0, \xi_1, R$) corresponds to a Type I water in Jerlov's (1968) classification
-(oligotrophic waters).
+The set of default values ($\xi_0, \xi_1, R$) corresponds to
+a Type I water in Jerlov's (1968) classification (oligotrophic waters).
 
 Such assumptions have been shown to provide a very crude and simplistic representation of
@@ -763,10 +833,12 @@
 a 61 waveband formulation.
 Unfortunately, such a model is very computationally expensive.
-Thus, \cite{lengaigne.menkes.ea_CD07} have constructed a simplified version of this formulation in which
-visible light is split into three wavebands: blue (400-500 nm), green (500-600 nm) and red (600-700nm).
-For each wave-band, the chlorophyll-dependent attenuation coefficient is fitted to the coefficients computed from
-the full spectral model of \cite{morel_JGR88} (as modified by \cite{morel.maritorena_JGR01}),
-assuming the same power-law relationship.
-As shown in \autoref{fig:TRA_qsr_irradiance}, this formulation, called RGB (Red-Green-Blue),
+Thus, \cite{lengaigne.menkes.ea_CD07} have constructed a simplified version of
+this formulation in which visible light is split into three wavebands:
+blue (400-500 $nm$), green (500-600 $nm$) and red (600-700 $nm$).
+For each wave-band, the chlorophyll-dependent attenuation coefficient is fitted to
+the coefficients computed from the full spectral model of \cite{morel_JGR88}
+(as modified by \cite{morel.maritorena_JGR01}), assuming the same power-law relationship.
+As shown in \autoref{fig:TRA_qsr_irradiance}, this formulation,
+called RGB (\textbf{R}ed-\textbf{G}reen-\textbf{B}lue),
 reproduces quite closely the light penetration profiles predicted by the full spectal model,
 but with much greater computational efficiency.
@@ -774,17 +846,21 @@
 
 The RGB formulation is used when \np[=.true.]{ln_qsr_rgb}{ln\_qsr\_rgb}.
-The RGB attenuation coefficients (\ie\ the inverses of the extinction length scales) are tabulated over
-61 nonuniform chlorophyll classes ranging from 0.01 to 10 g.Chl/L
+The RGB attenuation coefficients (\ie\ the inverses of the extinction length scales) are
+tabulated over 61 nonuniform chlorophyll classes ranging from 0.01 to 10 $g.Chl/L$
 (see the routine \rou{trc\_oce\_rgb} in \mdl{trc\_oce} module).
 Four types of chlorophyll can be chosen in the RGB formulation:
 
 \begin{description}
-\item [{\np[=0]{nn_chldta}{nn\_chldta}}] a constant 0.05 g.Chl/L value everywhere ;
-\item [{\np[=1]{nn_chldta}{nn\_chldta}}] an observed time varying chlorophyll deduced from satellite surface ocean color measurement spread uniformly in the vertical direction;
-\item [{\np[=2]{nn_chldta}{nn\_chldta}}] same as previous case except that a vertical profile of chlorophyl is used.
-  Following \cite{morel.berthon_LO89}, the profile is computed from the local surface chlorophyll value;
-\item [{\np[=.true.]{ln_qsr_bio}{ln\_qsr\_bio}}] simulated time varying chlorophyll by TOP biogeochemical model.
-  In this case, the RGB formulation is used to calculate both the phytoplankton light limitation in
-  PISCES and the oceanic heating rate.
+\item [{\np[=0]{nn_chldta}{nn\_chldta}}] a constant 0.05 $g.Chl/L$ value everywhere;
+\item [{\np[=1]{nn_chldta}{nn\_chldta}}] an observed time varying chlorophyll deduced from
+  satellite surface ocean color measurement spread uniformly in the vertical direction;
+\item [{\np[=2]{nn_chldta}{nn\_chldta}}] same as previous case except that
+  a vertical profile of chlorophyl is used.
+  Following \cite{morel.berthon_LO89},
+  the profile is computed from the local surface chlorophyll value;
+\item [{\np[=.true.]{ln_qsr_bio}{ln\_qsr\_bio}}] simulated time varying chlorophyll by
+  \TOP\ biogeochemical model.
+  In this case, the RGB formulation is used to calculate both
+  the phytoplankton light limitation in \PISCES\ and the oceanic heating rate.
 \end{description}
 
@@ -797,11 +873,12 @@
 (\ie\ it is less than the computer precision) is computed once,
 and the trend associated with the penetration of the solar radiation is only added down to that level.
-Finally, note that when the ocean is shallow ($<$ 200~m), part of the solar radiation can reach the ocean floor.
+Finally, note that when the ocean is shallow ($<$ 200~m),
+part of the solar radiation can reach the ocean floor.
 In this case, we have chosen that all remaining radiation is absorbed in the last ocean level
 (\ie\ $I$ is masked).
 
-\begin{figure}[!t]
+\begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_TRA_Irradiance}
+  \includegraphics[width=0.66\textwidth]{TRA_Irradiance}
   \caption[Penetration profile of the downward solar irradiance calculated by four models]{
     Penetration profile of the downward solar irradiance calculated by four models.
@@ -810,5 +887,5 @@
     4 waveband RGB formulation (red),
     61 waveband Morel (1988) formulation (black) for a chlorophyll concentration of
-    (a) Chl=0.05 mg/m$^3$ and (b) Chl=0.5 mg/m$^3$.
+    (a) Chl=0.05 $mg/m^3$ and (b) Chl=0.5 $mg/m^3$.
     From \citet{lengaigne.menkes.ea_CD07}.}
   \label{fig:TRA_qsr_irradiance}
@@ -824,7 +901,8 @@
   \label{lst:nambbc}
 \end{listing}
-\begin{figure}[!t]
+
+\begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_TRA_geoth}
+  \includegraphics[width=0.66\textwidth]{TRA_geoth}
   \caption[Geothermal heat flux]{
     Geothermal Heat flux (in $mW.m^{-2}$) used by \cite{emile-geay.madec_OS09}.
@@ -836,16 +914,22 @@
 \ie\ a no flux boundary condition is applied on active tracers at the bottom.
 This is the default option in \NEMO, and it is implemented using the masking technique.
-However, there is a non-zero heat flux across the seafloor that is associated with solid earth cooling.
-This flux is weak compared to surface fluxes (a mean global value of $\sim 0.1 \, W/m^2$ \citep{stein.stein_N92}),
+However, there is a non-zero heat flux across the seafloor that
+is associated with solid earth cooling.
+This flux is weak compared to surface fluxes
+(a mean global value of $\sim 0.1 \, W/m^2$ \citep{stein.stein_N92}),
 but it warms systematically the ocean and acts on the densest water masses.
 Taking this flux into account in a global ocean model increases the deepest overturning cell
-(\ie\ the one associated with the Antarctic Bottom Water) by a few Sverdrups \citep{emile-geay.madec_OS09}.
+(\ie\ the one associated with the Antarctic Bottom Water) by
+a few Sverdrups \citep{emile-geay.madec_OS09}.
 
 Options are defined through the \nam{bbc}{bbc} namelist variables.
-The presence of geothermal heating is controlled by setting the namelist parameter \np{ln_trabbc}{ln\_trabbc} to true.
-Then, when \np{nn_geoflx}{nn\_geoflx} is set to 1, a constant geothermal heating is introduced whose value is given by
-the \np{rn_geoflx_cst}{rn\_geoflx\_cst}, which is also a namelist parameter.
-When \np{nn_geoflx}{nn\_geoflx} is set to 2, a spatially varying geothermal heat flux is introduced which is provided in
-the \ifile{geothermal\_heating} NetCDF file (\autoref{fig:TRA_geothermal}) \citep{emile-geay.madec_OS09}.
+The presence of geothermal heating is controlled by
+setting the namelist parameter \np{ln_trabbc}{ln\_trabbc} to true.
+Then, when \np{nn_geoflx}{nn\_geoflx} is set to 1, a constant geothermal heating is introduced whose
+value is given by the \np{rn_geoflx_cst}{rn\_geoflx\_cst}, which is also a namelist parameter.
+When \np{nn_geoflx}{nn\_geoflx} is set to 2,
+a spatially varying geothermal heat flux is introduced which is provided in
+the \ifile{geothermal\_heating} NetCDF file
+(\autoref{fig:TRA_geothermal}) \citep{emile-geay.madec_OS09}.
 
 %% =================================================================================================
@@ -865,19 +949,24 @@
 where dense water formed in marginal seas flows into a basin filled with less dense water,
 or along the continental slope when dense water masses are formed on a continental shelf.
-The amount of entrainment that occurs in these gravity plumes is critical in determining the density and
-volume flux of the densest waters of the ocean, such as Antarctic Bottom Water, or North Atlantic Deep Water.
+The amount of entrainment that occurs in these gravity plumes is critical in
+determining the density and volume flux of the densest waters of the ocean,
+such as Antarctic Bottom Water, or North Atlantic Deep Water.
 $z$-coordinate models tend to overestimate the entrainment,
-because the gravity flow is mixed vertically by convection as it goes ''downstairs'' following the step topography,
+because the gravity flow is mixed vertically by convection as
+it goes ''downstairs'' following the step topography,
 sometimes over a thickness much larger than the thickness of the observed gravity plume.
-A similar problem occurs in the $s$-coordinate when the thickness of the bottom level varies rapidly downstream of
-a sill \citep{willebrand.barnier.ea_PO01}, and the thickness of the plume is not resolved.
-
-The idea of the bottom boundary layer (BBL) parameterisation, first introduced by \citet{beckmann.doscher_JPO97},
+A similar problem occurs in the $s$-coordinate when
+the thickness of the bottom level varies rapidly downstream of a sill
+\citep{willebrand.barnier.ea_PO01}, and the thickness of the plume is not resolved.
+
+The idea of the bottom boundary layer (BBL) parameterisation, first introduced by
+\citet{beckmann.doscher_JPO97},
 is to allow a direct communication between two adjacent bottom cells at different levels,
 whenever the densest water is located above the less dense water.
-The communication can be by a diffusive flux (diffusive BBL), an advective flux (advective BBL), or both.
+The communication can be by a diffusive flux (diffusive BBL),
+an advective flux (advective BBL), or both.
 In the current implementation of the BBL, only the tracers are modified, not the velocities.
-Furthermore, it only connects ocean bottom cells, and therefore does not include all the improvements introduced by
-\citet{campin.goosse_T99}.
+Furthermore, it only connects ocean bottom cells,
+and therefore does not include all the improvements introduced by \citet{campin.goosse_T99}.
 
 %% =================================================================================================
@@ -885,5 +974,6 @@
 \label{subsec:TRA_bbl_diff}
 
-When applying sigma-diffusion (\np[=.true.]{ln_trabbl}{ln\_trabbl} and \np{nn_bbl_ldf}{nn\_bbl\_ldf} set to 1),
+When applying sigma-diffusion
+(\np[=.true.]{ln_trabbl}{ln\_trabbl} and \np{nn_bbl_ldf}{nn\_bbl\_ldf} set to 1),
 the diffusive flux between two adjacent cells at the ocean floor is given by
 \[
@@ -891,6 +981,6 @@
   \vect F_\sigma = A_l^\sigma \, \nabla_\sigma T
 \]
-with $\nabla_\sigma$ the lateral gradient operator taken between bottom cells, and
-$A_l^\sigma$ the lateral diffusivity in the BBL.
+with $\nabla_\sigma$ the lateral gradient operator taken between bottom cells,
+and $A_l^\sigma$ the lateral diffusivity in the BBL.
 Following \citet{beckmann.doscher_JPO97}, the latter is prescribed with a spatial dependence,
 \ie\ in the conditional form
@@ -900,9 +990,9 @@
       \begin{cases}
         A_{bbl} & \text{if~} \nabla_\sigma \rho \cdot \nabla H < 0 \\
-        \\
-        0      & \text{otherwise} \\
+        0      & \text{otherwise}
       \end{cases}
 \end{equation}
-where $A_{bbl}$ is the BBL diffusivity coefficient, given by the namelist parameter \np{rn_ahtbbl}{rn\_ahtbbl} and
+where $A_{bbl}$ is the BBL diffusivity coefficient,
+given by the namelist parameter \np{rn_ahtbbl}{rn\_ahtbbl} and
 usually set to a value much larger than the one used for lateral mixing in the open ocean.
 The constraint in \autoref{eq:TRA_bbl_coef} implies that sigma-like diffusion only occurs when
@@ -915,6 +1005,7 @@
   \nabla_\sigma \rho / \rho = \alpha \, \nabla_\sigma T + \beta \, \nabla_\sigma S
 \]
-where $\rho$, $\alpha$ and $\beta$ are functions of $\overline T^\sigma$, $\overline S^\sigma$ and
-$\overline H^\sigma$, the along bottom mean temperature, salinity and depth, respectively.
+where $\rho$, $\alpha$ and $\beta$ are functions of
+$\overline T^\sigma$, $\overline S^\sigma$ and $\overline H^\sigma$,
+the along bottom mean temperature, salinity and depth, respectively.
 
 %% =================================================================================================
@@ -927,7 +1018,7 @@
 %}
 
-\begin{figure}[!t]
+\begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_BBL_adv}
+  \includegraphics[width=0.33\textwidth]{TRA_BBL_adv}
   \caption[Advective/diffusive bottom boundary layer]{
     Advective/diffusive Bottom Boundary Layer.
@@ -946,57 +1037,56 @@
 %!!        i.e. transport proportional to the along-slope density gradient
 
-%%%gmcomment   :  this section has to be really written
-
-When applying an advective BBL (\np[=1..2]{nn_bbl_adv}{nn\_bbl\_adv}), an overturning circulation is added which
-connects two adjacent bottom grid-points only if dense water overlies less dense water on the slope.
+\cmtgm{This section has to be really written}
+
+When applying an advective BBL (\np[=1..2]{nn_bbl_adv}{nn\_bbl\_adv}),
+an overturning circulation is added which connects two adjacent bottom grid-points only if
+dense water overlies less dense water on the slope.
 The density difference causes dense water to move down the slope.
 
-\np[=1]{nn_bbl_adv}{nn\_bbl\_adv}:
-the downslope velocity is chosen to be the Eulerian ocean velocity just above the topographic step
-(see black arrow in \autoref{fig:TRA_bbl}) \citep{beckmann.doscher_JPO97}.
-It is a \textit{conditional advection}, that is, advection is allowed only
-if dense water overlies less dense water on the slope (\ie\ $\nabla_\sigma \rho \cdot \nabla H < 0$) and
-if the velocity is directed towards greater depth (\ie\ $\vect U \cdot \nabla H > 0$).
-
-\np[=2]{nn_bbl_adv}{nn\_bbl\_adv}:
-the downslope velocity is chosen to be proportional to $\Delta \rho$,
-the density difference between the higher cell and lower cell densities \citep{campin.goosse_T99}.
-The advection is allowed only  if dense water overlies less dense water on the slope
-(\ie\ $\nabla_\sigma \rho \cdot \nabla H < 0$).
-For example, the resulting transport of the downslope flow, here in the $i$-direction (\autoref{fig:TRA_bbl}),
-is simply given by the following expression:
-\[
-  % \label{eq:TRA_bbl_Utr}
-  u^{tr}_{bbl} = \gamma g \frac{\Delta \rho}{\rho_o} e_{1u} \, min ({e_{3u}}_{kup},{e_{3u}}_{kdwn})
-\]
-where $\gamma$, expressed in seconds, is the coefficient of proportionality provided as \np{rn_gambbl}{rn\_gambbl},
-a namelist parameter, and \textit{kup} and \textit{kdwn} are the vertical index of the higher and lower cells,
-respectively.
-The parameter $\gamma$ should take a different value for each bathymetric step, but for simplicity,
-and because no direct estimation of this parameter is available, a uniform value has been assumed.
-The possible values for $\gamma$ range between 1 and $10~s$ \citep{campin.goosse_T99}.
-
-Scalar properties are advected by this additional transport $(u^{tr}_{bbl},v^{tr}_{bbl})$ using the upwind scheme.
-Such a diffusive advective scheme has been chosen to mimic the entrainment between the downslope plume and
-the surrounding water at intermediate depths.
+\begin{description}
+\item [{\np[=1]{nn_bbl_adv}{nn\_bbl\_adv}}] the downslope velocity is chosen to
+  be the Eulerian ocean velocity just above the topographic step
+  (see black arrow in \autoref{fig:TRA_bbl}) \citep{beckmann.doscher_JPO97}.
+  It is a \textit{conditional advection}, that is,
+  advection is allowed only if dense water overlies less dense water on the slope
+  (\ie\ $\nabla_\sigma \rho \cdot \nabla H < 0$) and if the velocity is directed towards greater depth
+  (\ie\ $\vect U \cdot \nabla H > 0$).
+\item [{\np[=2]{nn_bbl_adv}{nn\_bbl\_adv}}] the downslope velocity is chosen to be proportional to
+  $\Delta \rho$, the density difference between the higher cell and lower cell densities
+  \citep{campin.goosse_T99}.
+  The advection is allowed only  if dense water overlies less dense water on the slope
+  (\ie\ $\nabla_\sigma \rho \cdot \nabla H < 0$).
+  For example, the resulting transport of the downslope flow, here in the $i$-direction
+  (\autoref{fig:TRA_bbl}), is simply given by the following expression:
+  \[
+    % \label{eq:TRA_bbl_Utr}
+    u^{tr}_{bbl} = \gamma g \frac{\Delta \rho}{\rho_o} e_{1u} \, min ({e_{3u}}_{kup},{e_{3u}}_{kdwn})
+  \]
+  where $\gamma$, expressed in seconds, is the coefficient of proportionality provided as
+  \np{rn_gambbl}{rn\_gambbl}, a namelist parameter, and
+  \textit{kup} and \textit{kdwn} are the vertical index of the higher and lower cells, respectively.
+  The parameter $\gamma$ should take a different value for each bathymetric step, but for simplicity,
+  and because no direct estimation of this parameter is available, a uniform value has been assumed.
+  The possible values for $\gamma$ range between 1 and $10~s$ \citep{campin.goosse_T99}.
+\end{description}
+
+Scalar properties are advected by this additional transport $(u^{tr}_{bbl},v^{tr}_{bbl})$ using
+the upwind scheme.
+Such a diffusive advective scheme has been chosen to mimic the entrainment between
+the downslope plume and the surrounding water at intermediate depths.
 The entrainment is replaced by the vertical mixing implicit in the advection scheme.
 Let us consider as an example the case displayed in \autoref{fig:TRA_bbl} where
 the density at level $(i,kup)$ is larger than the one at level $(i,kdwn)$.
-The advective BBL scheme modifies the tracer time tendency of the ocean cells near the topographic step by
-the downslope flow \autoref{eq:TRA_bbl_dw}, the horizontal \autoref{eq:TRA_bbl_hor} and
-the upward \autoref{eq:TRA_bbl_up} return flows as follows:
-\begin{alignat}{3}
+The advective BBL scheme modifies the tracer time tendency of
+the ocean cells near the topographic step by the downslope flow \autoref{eq:TRA_bbl_dw},
+the horizontal \autoref{eq:TRA_bbl_hor} and the upward \autoref{eq:TRA_bbl_up} return flows as follows:
+\begin{alignat}{5}
   \label{eq:TRA_bbl_dw}
-  \partial_t T^{do}_{kdw} &\equiv \partial_t T^{do}_{kdw}
-                                &&+ \frac{u^{tr}_{bbl}}{{b_t}^{do}_{kdw}} &&\lt( T^{sh}_{kup} - T^{do}_{kdw} \rt) \\
+  \partial_t T^{do}_{kdw} &\equiv \partial_t T^{do}_{kdw} &&+ \frac{u^{tr}_{bbl}}{{b_t}^{do}_{kdw}} &&\lt( T^{sh}_{kup} - T^{do}_{kdw} \rt) \\
   \label{eq:TRA_bbl_hor}
-  \partial_t T^{sh}_{kup} &\equiv \partial_t T^{sh}_{kup}
-                                &&+ \frac{u^{tr}_{bbl}}{{b_t}^{sh}_{kup}} &&\lt( T^{do}_{kup} - T^{sh}_{kup} \rt) \\
-  %
-  \intertext{and for $k =kdw-1,\;..., \; kup$ :}
-  %
+  \partial_t T^{sh}_{kup} &\equiv \partial_t T^{sh}_{kup} &&+ \frac{u^{tr}_{bbl}}{{b_t}^{sh}_{kup}} &&\lt( T^{do}_{kup} - T^{sh}_{kup} \rt) \\
+  \shortintertext{and for $k =kdw-1,\;..., \; kup$ :}
   \label{eq:TRA_bbl_up}
-  \partial_t T^{do}_{k} &\equiv \partial_t S^{do}_{k}
-                                &&+ \frac{u^{tr}_{bbl}}{{b_t}^{do}_{k}}   &&\lt( T^{do}_{k +1} - T^{sh}_{k}   \rt)
+  \partial_t T^{do}_{k}   &\equiv \partial_t S^{do}_{k}   &&+ \frac{u^{tr}_{bbl}}{{b_t}^{do}_{k}}   &&\lt( T^{do}_{k +1} - T^{sh}_{k}   \rt)
 \end{alignat}
 where $b_t$ is the $T$-cell volume.
@@ -1015,48 +1105,52 @@
 \end{listing}
 
-In some applications it can be useful to add a Newtonian damping term into the temperature and salinity equations:
+In some applications it can be useful to add a Newtonian damping term into
+the temperature and salinity equations:
 \begin{equation}
   \label{eq:TRA_dmp}
-  \begin{gathered}
-    \pd[T]{t} = \cdots - \gamma (T - T_o) \\
-    \pd[S]{t} = \cdots - \gamma (S - S_o)
-  \end{gathered}
-\end{equation}
-where $\gamma$ is the inverse of a time scale, and $T_o$ and $S_o$ are given temperature and salinity fields
-(usually a climatology).
-Options are defined through the  \nam{tra_dmp}{tra\_dmp} namelist variables.
+    \pd[T]{t} = \cdots - \gamma (T - T_o) \qquad \pd[S]{t} = \cdots - \gamma (S - S_o)
+\end{equation}
+where $\gamma$ is the inverse of a time scale,
+and $T_o$ and $S_o$ are given temperature and salinity fields (usually a climatology).
+Options are defined through the \nam{tra_dmp}{tra\_dmp} namelist variables.
 The restoring term is added when the namelist parameter \np{ln_tradmp}{ln\_tradmp} is set to true.
-It also requires that both \np{ln_tsd_init}{ln\_tsd\_init} and \np{ln_tsd_dmp}{ln\_tsd\_dmp} are set to true in
-\nam{tsd}{tsd} namelist as well as \np{sn_tem}{sn\_tem} and \np{sn_sal}{sn\_sal} structures are correctly set
+It also requires that both \np{ln_tsd_init}{ln\_tsd\_init} and
+\np{ln_tsd_dmp}{ln\_tsd\_dmp} are set to true in \nam{tsd}{tsd} namelist as well as
+\np{sn_tem}{sn\_tem} and \np{sn_sal}{sn\_sal} structures are correctly set
 (\ie\ that $T_o$ and $S_o$ are provided in input files and read using \mdl{fldread},
 see \autoref{subsec:SBC_fldread}).
-The restoring coefficient $\gamma$ is a three-dimensional array read in during the \rou{tra\_dmp\_init} routine.
+The restoring coefficient $\gamma$ is a three-dimensional array read in during
+the \rou{tra\_dmp\_init} routine.
 The file name is specified by the namelist variable \np{cn_resto}{cn\_resto}.
-The DMP\_TOOLS tool is provided to allow users to generate the netcdf file.
+The \texttt{DMP\_TOOLS} are provided to allow users to generate the netcdf file.
 
 The two main cases in which \autoref{eq:TRA_dmp} is used are
-\textit{(a)} the specification of the boundary conditions along artificial walls of a limited domain basin and
-\textit{(b)} the computation of the velocity field associated with a given $T$-$S$ field
-(for example to build the initial state of a prognostic simulation,
-or to use the resulting velocity field for a passive tracer study).
+\begin{enumerate*}[label=(\textit{\alph*})]
+\item the specification of the boundary conditions along
+  artificial walls of a limited domain basin and
+\item the computation of the velocity field associated with a given $T$-$S$ field
+  (for example to build the initial state of a prognostic simulation,
+  or to use the resulting velocity field for a passive tracer study).
+\end{enumerate*}
 The first case applies to regional models that have artificial walls instead of open boundaries.
-In the vicinity of these walls, $\gamma$ takes large values (equivalent to a time scale of a few days) whereas
-it is zero in the interior of the model domain.
+In the vicinity of these walls, $\gamma$ takes large values (equivalent to a time scale of a few days)
+whereas it is zero in the interior of the model domain.
 The second case corresponds to the use of the robust diagnostic method \citep{sarmiento.bryan_JGR82}.
 It allows us to find the velocity field consistent with the model dynamics whilst
 having a $T$, $S$ field close to a given climatological field ($T_o$, $S_o$).
 
-The robust diagnostic method is very efficient in preventing temperature drift in intermediate waters but
-it produces artificial sources of heat and salt within the ocean.
+The robust diagnostic method is very efficient in preventing temperature drift in
+intermediate waters but it produces artificial sources of heat and salt within the ocean.
 It also has undesirable effects on the ocean convection.
-It tends to prevent deep convection and subsequent deep-water formation, by stabilising the water column too much.
-
-The namelist parameter \np{nn_zdmp}{nn\_zdmp} sets whether the damping should be applied in the whole water column or
-only below the mixed layer (defined either on a density or $S_o$ criterion).
+It tends to prevent deep convection and subsequent deep-water formation,
+by stabilising the water column too much.
+
+The namelist parameter \np{nn_zdmp}{nn\_zdmp} sets whether the damping should be applied in
+the whole water column or only below the mixed layer (defined either on a density or $S_o$ criterion).
 It is common to set the damping to zero in the mixed layer as the adjustment time scale is short here
 \citep{madec.delecluse.ea_JPO96}.
 
-For generating \ifile{resto}, see the documentation for the DMP tool provided with the source code under
-\path{./tools/DMP_TOOLS}.
+For generating \ifile{resto},
+see the documentation for the DMP tools provided with the source code under \path{./tools/DMP_TOOLS}.
 
 %% =================================================================================================
@@ -1065,9 +1159,10 @@
 
 Options are defined through the \nam{dom}{dom} namelist variables.
-The general framework for tracer time stepping is a modified leap-frog scheme \citep{leclair.madec_OM09},
-\ie\ a three level centred time scheme associated with a Asselin time filter (cf. \autoref{sec:TD_mLF}):
+The general framework for tracer time stepping is a modified leap-frog scheme
+\citep{leclair.madec_OM09}, \ie\ a three level centred time scheme associated with
+a Asselin time filter (cf. \autoref{sec:TD_mLF}):
 \begin{equation}
   \label{eq:TRA_nxt}
-  \begin{alignedat}{3}
+  \begin{alignedat}{5}
     &(e_{3t}T)^{t + \rdt} &&= (e_{3t}T)_f^{t - \rdt} &&+ 2 \, \rdt \,e_{3t}^t \ \text{RHS}^t \\
     &(e_{3t}T)_f^t        &&= (e_{3t}T)^t            &&+ \, \gamma \, \lt[ (e_{3t}T)_f^{t - \rdt} - 2(e_{3t}T)^t + (e_{3t}T)^{t + \rdt} \rt] \\
@@ -1075,19 +1170,19 @@
   \end{alignedat}
 \end{equation}
-where RHS is the right hand side of the temperature equation, the subscript $f$ denotes filtered values,
-$\gamma$ is the Asselin coefficient, and $S$ is the total forcing applied on $T$
-(\ie\ fluxes plus content in mass exchanges).
-$\gamma$ is initialized as \np{rn_atfp}{rn\_atfp} (\textbf{namelist} parameter).
-Its default value is \np[=10.e-3]{rn_atfp}{rn\_atfp}.
+where RHS is the right hand side of the temperature equation,
+the subscript $f$ denotes filtered values, $\gamma$ is the Asselin coefficient,
+and $S$ is the total forcing applied on $T$ (\ie\ fluxes plus content in mass exchanges).
+$\gamma$ is initialized as \np{rn_atfp}{rn\_atfp}, its default value is \forcode{10.e-3}.
 Note that the forcing correction term in the filter is not applied in linear free surface
 (\jp{ln\_linssh}\forcode{=.true.}) (see \autoref{subsec:TRA_sbc}).
-Not also that in constant volume case, the time stepping is performed on $T$, not on its content, $e_{3t}T$.
-
-When the vertical mixing is solved implicitly, the update of the \textit{next} tracer fields is done in
-\mdl{trazdf} module.
+Not also that in constant volume case, the time stepping is performed on $T$,
+not on its content, $e_{3t}T$.
+
+When the vertical mixing is solved implicitly,
+the update of the \textit{next} tracer fields is done in \mdl{trazdf} module.
 In this case only the swapping of arrays and the Asselin filtering is done in the \mdl{tranxt} module.
 
-In order to prepare for the computation of the \textit{next} time step, a swap of tracer arrays is performed:
-$T^{t - \rdt} = T^t$ and $T^t = T_f$.
+In order to prepare for the computation of the \textit{next} time step,
+a swap of tracer arrays is performed: $T^{t - \rdt} = T^t$ and $T^t = T_f$.
 
 %% =================================================================================================
@@ -1105,111 +1200,122 @@
 \label{subsec:TRA_eos}
 
-The Equation Of Seawater (EOS) is an empirical nonlinear thermodynamic relationship linking seawater density,
-$\rho$, to a number of state variables, most typically temperature, salinity and pressure.
+The \textbf{E}quation \textbf{O}f \textbf{S}eawater (EOS) is
+an empirical nonlinear thermodynamic relationship linking
+seawater density, $\rho$, to a number of state variables,
+most typically temperature, salinity and pressure.
 Because density gradients control the pressure gradient force through the hydrostatic balance,
-the equation of state provides a fundamental bridge between the distribution of active tracers and
-the fluid dynamics.
+the equation of state provides a fundamental bridge between
+the distribution of active tracers and the fluid dynamics.
 Nonlinearities of the EOS are of major importance, in particular influencing the circulation through
 determination of the static stability below the mixed layer,
-thus controlling rates of exchange between the atmosphere and the ocean interior \citep{roquet.madec.ea_JPO15}.
-Therefore an accurate EOS based on either the 1980 equation of state (EOS-80, \cite{fofonoff.millard_bk83}) or
-TEOS-10 \citep{ioc.iapso_bk10} standards should be used anytime a simulation of the real ocean circulation is attempted
+thus controlling rates of exchange between the atmosphere and the ocean interior
 \citep{roquet.madec.ea_JPO15}.
+Therefore an accurate EOS based on either the 1980 equation of state
+(EOS-80, \cite{fofonoff.millard_bk83}) or TEOS-10 \citep{ioc.iapso_bk10} standards should
+be used anytime a simulation of the real ocean circulation is attempted \citep{roquet.madec.ea_JPO15}.
 The use of TEOS-10 is highly recommended because
-\textit{(i)}   it is the new official EOS,
-\textit{(ii)}  it is more accurate, being based on an updated database of laboratory measurements, and
-\textit{(iii)} it uses Conservative Temperature and Absolute Salinity (instead of potential temperature and
-practical salinity for EOS-80, both variables being more suitable for use as model variables
-\citep{ioc.iapso_bk10, graham.mcdougall_JPO13}.
+\begin{enumerate*}[label=(\textit{\roman*})]
+\item it is the new official EOS,
+\item it is more accurate, being based on an updated database of laboratory measurements, and
+\item it uses Conservative Temperature and Absolute Salinity
+  (instead of potential temperature and practical salinity for EOS-80),
+  both variables being more suitable for use as model variables
+  \citep{ioc.iapso_bk10, graham.mcdougall_JPO13}.
+\end{enumerate*}
 EOS-80 is an obsolescent feature of the \NEMO\ system, kept only for backward compatibility.
 For process studies, it is often convenient to use an approximation of the EOS.
 To that purposed, a simplified EOS (S-EOS) inspired by \citet{vallis_bk06} is also available.
 
-In the computer code, a density anomaly, $d_a = \rho / \rho_o - 1$, is computed, with $\rho_o$ a reference density.
-Called \textit{rau0} in the code, $\rho_o$ is set in \mdl{phycst} to a value of $1,026~Kg/m^3$.
-This is a sensible choice for the reference density used in a Boussinesq ocean climate model, as,
-with the exception of only a small percentage of the ocean,
-density in the World Ocean varies by no more than 2$\%$ from that value \citep{gill_bk82}.
+In the computer code, a density anomaly, $d_a = \rho / \rho_o - 1$, is computed,
+with $\rho_o$ a reference density.
+Called \textit{rau0} in the code,
+$\rho_o$ is set in \mdl{phycst} to a value of \texttt{1,026} $Kg/m^3$.
+This is a sensible choice for the reference density used in a Boussinesq ocean climate model,
+as, with the exception of only a small percentage of the ocean,
+density in the World Ocean varies by no more than 2\% from that value \citep{gill_bk82}.
 
 Options which control the EOS used are defined through the \nam{eos}{eos} namelist variables.
 
 \begin{description}
-\item [{\np[=.true.]{ln_teos10}{ln\_teos10}}] the polyTEOS10-bsq equation of seawater \citep{roquet.madec.ea_OM15} is used.
+\item [{\np[=.true.]{ln_teos10}{ln\_teos10}}] the polyTEOS10-bsq equation of seawater
+  \citep{roquet.madec.ea_OM15} is used.
   The accuracy of this approximation is comparable to the TEOS-10 rational function approximation,
-  but it is optimized for a boussinesq fluid and the polynomial expressions have simpler and
-  more computationally efficient expressions for their derived quantities which make them more adapted for
-  use in ocean models.
-  Note that a slightly higher precision polynomial form is now used replacement of
-  the TEOS-10 rational function approximation for hydrographic data analysis \citep{ioc.iapso_bk10}.
+  but it is optimized for a Boussinesq fluid and
+  the polynomial expressions have simpler and more computationally efficient expressions for
+  their derived quantities which make them more adapted for use in ocean models.
+  Note that a slightly higher precision polynomial form is now used
+  replacement of the TEOS-10 rational function approximation for hydrographic data analysis
+  \citep{ioc.iapso_bk10}.
   A key point is that conservative state variables are used:
-  Absolute Salinity (unit: g/kg, notation: $S_A$) and Conservative Temperature (unit: \deg{C}, notation: $\Theta$).
+  Absolute Salinity (unit: $g/kg$, notation: $S_A$) and
+  Conservative Temperature (unit: $\deg{C}$, notation: $\Theta$).
   The pressure in decibars is approximated by the depth in meters.
   With TEOS10, the specific heat capacity of sea water, $C_p$, is a constant.
-  It is set to $C_p = 3991.86795711963~J\,Kg^{-1}\,^{\circ}K^{-1}$, according to \citet{ioc.iapso_bk10}.
+  It is set to $C_p$ = 3991.86795711963 $J.Kg^{-1}.\deg{K}^{-1}$,
+  according to \citet{ioc.iapso_bk10}.
   Choosing polyTEOS10-bsq implies that the state variables used by the model are $\Theta$ and $S_A$.
-  In particular, the initial state deined by the user have to be given as \textit{Conservative} Temperature and
-  \textit{Absolute} Salinity.
+  In particular, the initial state defined by the user have to be given as
+  \textit{Conservative} Temperature and \textit{Absolute} Salinity.
   In addition, when using TEOS10, the Conservative SST is converted to potential SST prior to
   either computing the air-sea and ice-sea fluxes (forced mode) or
   sending the SST field to the atmosphere (coupled mode).
 \item [{\np[=.true.]{ln_eos80}{ln\_eos80}}] the polyEOS80-bsq equation of seawater is used.
-  It takes the same polynomial form as the polyTEOS10, but the coefficients have been optimized to
-  accurately fit EOS80 (Roquet, personal comm.).
+  It takes the same polynomial form as the polyTEOS10,
+  but the coefficients have been optimized to accurately fit EOS80 (Roquet, personal comm.).
   The state variables used in both the EOS80 and the ocean model are:
-  the Practical Salinity ((unit: psu, notation: $S_p$)) and
-  Potential Temperature (unit: $^{\circ}C$, notation: $\theta$).
+  the Practical Salinity (unit: $psu$, notation: $S_p$) and
+  Potential Temperature (unit: $\deg{C}$, notation: $\theta$).
   The pressure in decibars is approximated by the depth in meters.
-  With thsi EOS, the specific heat capacity of sea water, $C_p$, is a function of temperature, salinity and
-  pressure \citep{fofonoff.millard_bk83}.
+  With EOS, the specific heat capacity of sea water, $C_p$, is a function of
+  temperature, salinity and pressure \citep{fofonoff.millard_bk83}.
   Nevertheless, a severe assumption is made in order to have a heat content ($C_p T_p$) which
   is conserved by the model: $C_p$ is set to a constant value, the TEOS10 value.
-\item [{\np[=.true.]{ln_seos}{ln\_seos}}] a simplified EOS (S-EOS) inspired by \citet{vallis_bk06} is chosen,
-  the coefficients of which has been optimized to fit the behavior of TEOS10
-  (Roquet, personal comm.) (see also \citet{roquet.madec.ea_JPO15}).
+\item [{\np[=.true.]{ln_seos}{ln\_seos}}] a simplified EOS (S-EOS) inspired by
+  \citet{vallis_bk06} is chosen,
+  the coefficients of which has been optimized to fit the behavior of TEOS10 (Roquet, personal comm.)
+  (see also \citet{roquet.madec.ea_JPO15}).
   It provides a simplistic linear representation of both cabbeling and thermobaricity effects which
   is enough for a proper treatment of the EOS in theoretical studies \citep{roquet.madec.ea_JPO15}.
-  With such an equation of state there is no longer a distinction between
-  \textit{conservative} and \textit{potential} temperature,
-  as well as between \textit{absolute} and \textit{practical} salinity.
+  With such an equation of state there is no longer a distinction between \textit{conservative} and
+  \textit{potential} temperature, as well as between \textit{absolute} and
+  \textit{practical} salinity.
   S-EOS takes the following expression:
-
   \begin{gather*}
     % \label{eq:TRA_S-EOS}
-    \begin{alignedat}{2}
-    &d_a(T,S,z) = \frac{1}{\rho_o} \big[ &- a_0 \; ( 1 + 0.5 \; \lambda_1 \; T_a + \mu_1 \; z ) * &T_a \big. \\
-    &                                    &+ b_0 \; ( 1 - 0.5 \; \lambda_2 \; S_a - \mu_2 \; z ) * &S_a       \\
-    &                              \big. &- \nu \;                           T_a                  &S_a \big] \\
-    \end{alignedat}
-    \\
+    d_a(T,S,z) = \frac{1}{\rho_o} \big[ - a_0 \; ( 1 + 0.5 \; \lambda_1 \; T_a + \mu_1 \; z ) * T_a \big.
+                                        + b_0 \; ( 1 - 0.5 \; \lambda_2 \; S_a - \mu_2 \; z ) * S_a
+                                  \big. - \nu \;                           T_a                  S_a \big] \\
     \text{with~} T_a = T - 10 \, ; \, S_a = S - 35 \, ; \, \rho_o = 1026~Kg/m^3
   \end{gather*}
-  where the computer name of the coefficients as well as their standard value are given in \autoref{tab:TRA_SEOS}.
+  where the computer name of the coefficients as well as their standard value are given in
+  \autoref{tab:TRA_SEOS}.
   In fact, when choosing S-EOS, various approximation of EOS can be specified simply by
   changing the associated coefficients.
-  Setting to zero the two thermobaric coefficients $(\mu_1,\mu_2)$ remove thermobaric effect from S-EOS.
-  setting to zero the three cabbeling coefficients $(\lambda_1,\lambda_2,\nu)$ remove cabbeling effect from
-  S-EOS.
+  Setting to zero the two thermobaric coefficients $(\mu_1,\mu_2)$
+  remove thermobaric effect from S-EOS.
+  Setting to zero the three cabbeling coefficients $(\lambda_1,\lambda_2,\nu)$
+  remove   cabbeling effect from S-EOS.
   Keeping non-zero value to $a_0$ and $b_0$ provide a linear EOS function of T and S.
 \end{description}
 
-\begin{table}[!tb]
+\begin{table}
   \centering
   \begin{tabular}{|l|l|l|l|}
     \hline
-    coeff.	   & computer name   & S-EOS		      & description		                 \\
+    coeff.      & computer name                & S-EOS            & description                     \\
     \hline
-    $a_0$       & \np{rn_a0}{rn\_a0}     & $1.6550~10^{-1}$ & linear thermal expansion coeff. \\
+    $a_0      $ & \np{rn_a0}{rn\_a0}           & $1.6550~10^{-1}$ & linear thermal expansion coeff. \\
     \hline
-    $b_0$	      & \np{rn_b0}{rn\_b0} 	   & $7.6554~10^{-1}$ & linear haline  expansion coeff. \\
+    $b_0      $ & \np{rn_b0}{rn\_b0}           & $7.6554~10^{-1}$ & linear haline  expansion coeff. \\
     \hline
-    $\lambda_1$	& \np{rn_lambda1}{rn\_lambda1}& $5.9520~10^{-2}$ & cabbeling coeff. in $T^2$ 	     \\
+    $\lambda_1$ & \np{rn_lambda1}{rn\_lambda1} & $5.9520~10^{-2}$ & cabbeling coeff. in $T^2$       \\
     \hline
-    $\lambda_2$	& \np{rn_lambda2}{rn\_lambda2}& $5.4914~10^{-4}$ & cabbeling coeff. in $S^2$	 	  \\
+    $\lambda_2$ & \np{rn_lambda2}{rn\_lambda2} & $5.4914~10^{-4}$ & cabbeling coeff. in $S^2$       \\
     \hline
-    $\nu$       & \np{rn_nu}{rn\_nu}     & $2.4341~10^{-3}$ & cabbeling coeff. in $T \, S$ 	  \\
+    $\nu      $ & \np{rn_nu}{rn\_nu}           & $2.4341~10^{-3}$ & cabbeling coeff. in $T \, S$    \\
     \hline
-    $\mu_1$     & \np{rn_mu1}{rn\_mu1} 	& $1.4970~10^{-4}$ & thermobaric coeff. in T    	  \\
+    $\mu_1    $ & \np{rn_mu1}{rn\_mu1}         & $1.4970~10^{-4}$ & thermobaric coeff. in T         \\
     \hline
-    $\mu_2$     & \np{rn_mu2}{rn\_mu2} 	& $1.1090~10^{-5}$ & thermobaric coeff. in S   	     \\
+    $\mu_2    $ & \np{rn_mu2}{rn\_mu2}         & $1.1090~10^{-5}$ & thermobaric coeff. in S         \\
     \hline
   \end{tabular}
@@ -1222,6 +1328,6 @@
 \label{subsec:TRA_bn2}
 
-An accurate computation of the ocean stability (i.e. of $N$, the brunt-V\"{a}is\"{a}l\"{a} frequency) is of
-paramount importance as determine the ocean stratification and is used in several ocean parameterisations
+An accurate computation of the ocean stability (i.e. of $N$, the Brunt-V\"{a}is\"{a}l\"{a} frequency) is of paramount importance as determine the ocean stratification and
+is used in several ocean parameterisations
 (namely TKE, GLS, Richardson number dependent vertical diffusion, enhanced vertical diffusion,
 non-penetrative convection, tidal mixing  parameterisation, iso-neutral diffusion).
@@ -1235,6 +1341,6 @@
 where $(T,S) = (\Theta,S_A)$ for TEOS10, $(\theta,S_p)$ for TEOS-80, or $(T,S)$ for S-EOS, and,
 $\alpha$ and $\beta$ are the thermal and haline expansion coefficients.
-The coefficients are a polynomial function of temperature, salinity and depth which expression depends on
-the chosen EOS.
+The coefficients are a polynomial function of temperature, salinity and depth which
+expression depends on the chosen EOS.
 They are computed through \textit{eos\_rab}, a \fortran\ function that can be found in \mdl{eosbn2}.
 
@@ -1246,9 +1352,8 @@
 \begin{equation}
   \label{eq:TRA_eos_fzp}
-  \begin{split}
-    &T_f (S,p) = \lt( a + b \, \sqrt{S} + c \, S \rt) \, S + d \, p \\
-    &\text{where~} a = -0.0575, \, b = 1.710523~10^{-3}, \, c = -2.154996~10^{-4} \\
-    &\text{and~} d = -7.53~10^{-3}
-    \end{split}
+  \begin{gathered}
+    T_f (S,p) = \lt( a + b \, \sqrt{S} + c \, S \rt) \, S + d \, p \\
+    \text{where~} a = -0.0575, \, b = 1.710523~10^{-3}, \, c = -2.154996~10^{-4} \text{and~} d = -7.53~10^{-3}
+    \end{gathered}
 \end{equation}
 
@@ -1269,13 +1374,14 @@
 \label{sec:TRA_zpshde}
 
-\gmcomment{STEVEN: to be consistent with earlier discussion of differencing and averaging operators,
+\cmtgm{STEVEN: to be consistent with earlier discussion of differencing and averaging operators,
 I've changed "derivative" to "difference" and "mean" to "average"}
 
-With partial cells (\np[=.true.]{ln_zps}{ln\_zps}) at bottom and top (\np[=.true.]{ln_isfcav}{ln\_isfcav}),
+With partial cells (\np[=.true.]{ln_zps}{ln\_zps}) at bottom and top
+(\np[=.true.]{ln_isfcav}{ln\_isfcav}),
 in general, tracers in horizontally adjacent cells live at different depths.
-Horizontal gradients of tracers are needed for horizontal diffusion (\mdl{traldf} module) and
-the hydrostatic pressure gradient calculations (\mdl{dynhpg} module).
-The partial cell properties at the top (\np[=.true.]{ln_isfcav}{ln\_isfcav}) are computed in the same way as
-for the bottom.
+Horizontal gradients of tracers are needed for horizontal diffusion
+(\mdl{traldf} module) and the hydrostatic pressure gradient calculations (\mdl{dynhpg} module).
+The partial cell properties at the top (\np[=.true.]{ln_isfcav}{ln\_isfcav}) are computed in
+the same way as for the bottom.
 So, only the bottom interpolation is explained below.
 
@@ -1283,9 +1389,10 @@
 a linear interpolation in the vertical is used to approximate the deeper tracer as if
 it actually lived at the depth of the shallower tracer point (\autoref{fig:TRA_Partial_step_scheme}).
-For example, for temperature in the $i$-direction the needed interpolated temperature, $\widetilde T$, is:
-
-\begin{figure}[!p]
+For example, for temperature in the $i$-direction the needed interpolated temperature,
+$\widetilde T$, is:
+
+\begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_partial_step_scheme}
+  \includegraphics[width=0.33\textwidth]{TRA_partial_step_scheme}
   \caption[Discretisation of the horizontal difference and average of tracers in
   the $z$-partial step coordinate]{
@@ -1294,17 +1401,16 @@
     the case $(e3w_k^{i + 1} - e3w_k^i) > 0$.
     A linear interpolation is used to estimate $\widetilde T_k^{i + 1}$,
-    the tracer value at the depth of the shallower tracer point of
-    the two adjacent bottom $T$-points.
+    the tracer value at the depth of the shallower tracer point of the two adjacent bottom $T$-points.
     The horizontal difference is then given by:
-    $\delta_{i + 1/2} T_k = \widetilde T_k^{\, i + 1} -T_k^{\, i}$ and
-    the average by:
+    $\delta_{i + 1/2} T_k = \widetilde T_k^{\, i + 1} -T_k^{\, i}$ and the average by:
     $\overline T_k^{\, i + 1/2} = (\widetilde T_k^{\, i + 1/2} - T_k^{\, i}) / 2$.}
   \label{fig:TRA_Partial_step_scheme}
 \end{figure}
+
 \[
   \widetilde T = \lt\{
     \begin{alignedat}{2}
       &T^{\, i + 1} &-\frac{ \lt( e_{3w}^{i + 1} -e_{3w}^i \rt) }{ e_{3w}^{i + 1} } \; \delta_k T^{i + 1}
-      & \quad \text{if $e_{3w}^{i + 1} \geq e_{3w}^i$} \\ \\
+      & \quad \text{if $e_{3w}^{i + 1} \geq e_{3w}^i$} \\
       &T^{\, i}     &+\frac{ \lt( e_{3w}^{i + 1} -e_{3w}^i \rt )}{e_{3w}^i       } \; \delta_k T^{i + 1}
       & \quad \text{if $e_{3w}^{i + 1} <    e_{3w}^i$}
@@ -1312,5 +1418,6 @@
   \rt.
 \]
-and the resulting forms for the horizontal difference and the horizontal average value of $T$ at a $U$-point are:
+and the resulting forms for the horizontal difference and the horizontal average value of
+$T$ at a $U$-point are:
 \begin{equation}
   \label{eq:TRA_zps_hde}
@@ -1318,14 +1425,11 @@
     \delta_{i + 1/2} T       &=
     \begin{cases}
-                                \widetilde T - T^i          & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\
-                                \\
-                                T^{\, i + 1} - \widetilde T & \text{if~} e_{3w}^{i + 1} <    e_{3w}^i
-    \end{cases}
-    \\
+      \widetilde T - T^i          & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\
+      T^{\, i + 1} - \widetilde T & \text{if~} e_{3w}^{i + 1} <    e_{3w}^i
+    \end{cases} \\
     \overline T^{\, i + 1/2} &=
     \begin{cases}
-                                (\widetilde T - T^{\, i}   ) / 2 & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\
-                                \\
-                                (T^{\, i + 1} - \widetilde T) / 2 & \text{if~} e_{3w}^{i + 1} <   e_{3w}^i
+      (\widetilde T - T^{\, i}    ) / 2 & \text{if~} e_{3w}^{i + 1} \geq e_{3w}^i \\
+      (T^{\, i + 1} - \widetilde T) / 2 & \text{if~} e_{3w}^{i + 1} <   e_{3w}^i
     \end{cases}
   \end{split}
@@ -1334,8 +1438,9 @@
 The computation of horizontal derivative of tracers as well as of density is performed once for all at
 each time step in \mdl{zpshde} module and stored in shared arrays to be used when needed.
-It has to be emphasized that the procedure used to compute the interpolated density, $\widetilde \rho$,
-is not the same as that used for $T$ and $S$.
-Instead of forming a linear approximation of density, we compute $\widetilde \rho$ from the interpolated values of
-$T$ and $S$, and the pressure at a $u$-point
+It has to be emphasized that the procedure used to compute the interpolated density,
+$\widetilde \rho$, is not the same as that used for $T$ and $S$.
+Instead of forming a linear approximation of density,
+we compute $\widetilde \rho$ from the interpolated values of $T$ and $S$,
+and the pressure at a $u$-point
 (in the equation of state pressure is approximated by depth, see \autoref{subsec:TRA_eos}):
 \[
@@ -1345,9 +1450,10 @@
 
 This is a much better approximation as the variation of $\rho$ with depth (and thus pressure)
-is highly non-linear with a true equation of state and thus is badly approximated with a linear interpolation.
-This approximation is used to compute both the horizontal pressure gradient (\autoref{sec:DYN_hpg}) and
-the slopes of neutral surfaces (\autoref{sec:LDF_slp}).
-
-Note that in almost all the advection schemes presented in this Chapter,
+is highly non-linear with a true equation of state and thus is badly approximated with
+a linear interpolation.
+This approximation is used to compute both the horizontal pressure gradient (\autoref{sec:DYN_hpg})
+and the slopes of neutral surfaces (\autoref{sec:LDF_slp}).
+
+Note that in almost all the advection schemes presented in this chapter,
 both averaging and differencing operators appear.
 Yet \autoref{eq:TRA_zps_hde} has not been used in these schemes:
@@ -1356,9 +1462,9 @@
 The main motivation is to preserve the domain averaged mean variance of the advected field when
 using the $2^{nd}$ order centred scheme.
-Sensitivity of the advection schemes to the way horizontal averages are performed in the vicinity of
-partial cells should be further investigated in the near future.
-\gmcomment{gm :   this last remark has to be done}
-
-\onlyinsubfile{\input{../../global/epilogue}}
+Sensitivity of the advection schemes to the way horizontal averages are performed in
+the vicinity of partial cells should be further investigated in the near future.
+\cmtgm{gm :   this last remark has to be done}
+
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_ZDF.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_ZDF.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_ZDF.tex	(revision 11954)
@@ -28,5 +28,6 @@
 \clearpage
 
-%gm% Add here a small introduction to ZDF and naming of the different physics (similar to what have been written for TRA and DYN.
+\cmtgm{ Add here a small introduction to ZDF and naming of the different physics
+(similar to what have been written for TRA and DYN).}
 
 %% =================================================================================================
@@ -248,5 +249,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_mixing_length}
+  \includegraphics[width=0.66\textwidth]{ZDF_mixing_length}
   \caption[Mixing length computation]{Illustration of the mixing length computation}
   \label{fig:ZDF_mixing_length}
@@ -533,6 +534,9 @@
  in \citet{reffray.guillaume.ea_GMD15} for the \NEMO\ model.
 
-%% =================================================================================================
-\subsection[OSM: OSMosis boundary layer scheme (\forcode{ln_zdfosm})]{OSM: OSMosis boundary layer scheme (\protect\np{ln_zdfosm}{ln\_zdfosm})}
+% -------------------------------------------------------------------------------------------------------------
+%        OSM OSMOSIS BL Scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection[OSM: OSMOSIS boundary layer scheme (\forcode{ln_zdfosm = .true.})]
+{OSM: OSMOSIS boundary layer scheme (\protect\np{ln_zdfosm}{ln\_zdfosm})}
 \label{subsec:ZDF_osm}
 
@@ -543,5 +547,207 @@
 \end{listing}
 
-The OSMOSIS turbulent closure scheme is based on......   TBC
+%--------------------------------------------------------------------------------------------------------------
+\paragraph{Namelist choices}
+Most of the namelist options refer to how to specify the Stokes
+surface drift and penetration depth. There are three options:
+\begin{description}
+  \item \protect\np[=0]{nn_osm_wave}{nn\_osm\_wave} Default value in \texttt{namelist\_ref}. In this case the Stokes drift is
+      assumed to be parallel to the surface wind stress, with
+      magnitude consistent with a constant turbulent Langmuir number
+    $\mathrm{La}_t=$ \protect\np{rn_m_la} {rn\_m\_la} i.e.\
+    $u_{s0}=\tau/(\mathrm{La}_t^2\rho_0)$.  Default value of
+    \protect\np{rn_m_la}{rn\_m\_la} is 0.3. The Stokes penetration
+      depth $\delta = $ \protect\np{rn_osm_dstokes}{rn\_osm\_dstokes}; this has default value
+      of 5~m.
+
+  \item \protect\np[=1]{nn_osm_wave}{nn\_osm\_wave} In this case the Stokes drift is
+      assumed to be parallel to the surface wind stress, with
+      magnitude as in the classical Pierson-Moskowitz wind-sea
+      spectrum.  Significant wave height and
+      wave-mean period taken from this spectrum are used to calculate the Stokes penetration
+      depth, following the approach set out in  \citet{breivik.janssen.ea_JPO14}.
+
+    \item \protect\np[=2]{nn_osm_wave}{nn\_osm\_wave} In this case the Stokes drift is
+      taken from  ECMWF wave model output, though only the component parallel
+      to the wind stress is retained. Significant wave height and
+      wave-mean period from ECMWF wave model output are used to calculate the Stokes penetration
+      depth, again following \citet{breivik.janssen.ea_JPO14}.
+
+    \end{description}
+
+    Others refer to the treatment of diffusion and viscosity beneath
+    the surface boundary layer:
+\begin{description}
+   \item \protect\np{ln_kpprimix} {ln\_kpprimix}  Default is \np{.true.}. Switches on KPP-style Ri \#-dependent
+     mixing below the surface boundary layer. If this is set
+     \texttt{.true.}  the following variable settings are honoured:
+    \item \protect\np{rn_riinfty}{rn\_riinfty} Critical value of local Ri \# below which
+      shear instability increases vertical mixing from background value.
+    \item \protect\np{rn_difri} {rn\_difri} Maximum value of Ri \#-dependent mixing at $\mathrm{Ri}=0$.
+    \item \protect\np{ln_convmix}{ln\_convmix} If \texttt{.true.} then, where water column is unstable, specify
+       diffusivity equal to \protect\np{rn_dif_conv}{rn\_dif\_conv} (default value is 1 m~s$^{-2}$).
+ \end{description}
+ Diagnostic output is controlled by:
+  \begin{description}
+    \item \protect\np{ln_dia_osm}{ln\_dia\_osm} Default is \np{.false.}; allows XIOS output of OSMOSIS internal fields.
+  \end{description}
+Obsolete namelist parameters include:
+\begin{description}
+   \item \protect\np{ln_use_osm_la}\np{ln\_use\_osm\_la} With \protect\np[=0]{nn_osm_wave}{nn\_osm\_wave},
+      \protect\np{rn_osm_dstokes} {rn\_osm\_dstokes} is always used to specify the Stokes
+      penetration depth.
+   \item \protect\np{nn_ave} {nn\_ave} Choice of averaging method for KPP-style Ri \#
+      mixing. Not taken account of.
+   \item \protect\np{rn_osm_hbl0} {rn\_osm\_hbl0} Depth of initial boundary layer is now set
+     by a density criterion similar to that used in calculating \emph{hmlp} (output as \texttt{mldr10\_1}) in \mdl{zdfmxl}.
+\end{description}
+
+\subsubsection{Summary}
+Much of the time the turbulent motions in the ocean surface boundary
+layer (OSBL) are not given by
+classical shear turbulence. Instead they are in a regime known as
+`Langmuir turbulence',  dominated by an
+interaction between the currents and the Stokes drift of the surface waves \citep[e.g.][]{mcwilliams.ea_JFM97}.
+This regime is characterised by strong vertical turbulent motion, and appears when the surface Stokes drift $u_{s0}$ is much greater than the friction velocity $u_{\ast}$. More specifically Langmuir turbulence is thought to be crucial where the turbulent Langmuir number $\mathrm{La}_{t}=(u_{\ast}/u_{s0}) > 0.4$.
+
+The OSMOSIS model is fundamentally based on results of Large Eddy
+Simulations (LES) of Langmuir turbulence and aims to fully describe
+this Langmuir regime. The description in this section is of necessity incomplete and further details are available in Grant. A (2019); in prep.
+
+The OSMOSIS turbulent closure scheme is a similarity-scale scheme in
+the same spirit as the K-profile
+parameterization (KPP) scheme of \citet{large.ea_RG97}.
+A specified shape of diffusivity, scaled by the (OSBL) depth
+$h_{\mathrm{BL}}$ and a turbulent velocity scale, is imposed throughout the
+boundary layer
+$-h_{\mathrm{BL}}<z<\eta$. The turbulent closure model
+also includes fluxes of tracers and momentum that are``non-local'' (independent of the local property gradient).
+
+Rather than the OSBL
+depth being diagnosed in terms of a bulk Richardson number criterion,
+as in KPP, it is set by a prognostic equation that is informed by
+energy budget considerations reminiscent of the classical mixed layer
+models of \citet{kraus.turner_tellus67}.
+The model also includes an explicit parametrization of the structure
+of the pycnocline (the stratified region at the bottom of the OSBL).
+
+Presently, mixing below the OSBL is handled by the Richardson
+number-dependent mixing scheme used in \citet{large.ea_RG97}.
+
+Convective parameterizations such as described in \ref{sec:ZDF_conv}
+below should not be used with the OSMOSIS-OBL model: instabilities
+within the OSBL are part of the model, while instabilities below the
+ML are handled by the Ri \# dependent scheme.
+
+\subsubsection{Depth and velocity scales}
+The model supposes a boundary layer of thickness $h_{\mathrm{bl}}$ enclosing a well-mixed layer of thickness $h_{\mathrm{ml}}$ and a relatively thin pycnocline at the base of thickness $\Delta h$; Fig.~\ref{fig: OSBL_structure} shows typical (a) buoyancy structure and (b) turbulent buoyancy flux profile for the unstable boundary layer (losing buoyancy at the surface; e.g.\ cooling).
+\begin{figure}[!t]
+  \begin{center}
+    %\includegraphics[width=0.7\textwidth]{ZDF_OSM_structure_of_OSBL}
+    \caption{
+      \protect\label{fig: OSBL_structure}
+     The structure of the entraining  boundary layer. (a) Mean buoyancy profile. (b) Profile of the buoyancy flux.
+    }
+  \end{center}
+\end{figure}
+The pycnocline in the OSMOSIS scheme is assumed to have a finite thickness, and may include a number of model levels. This means that the OSMOSIS scheme must parametrize both the thickness of the pycnocline, and the turbulent fluxes within the pycnocline.
+
+Consideration of the power input by wind acting on the Stokes drift suggests that the Langmuir turbulence has velocity scale:
+\begin{equation}\label{eq:w_La}
+w_{*L}= \left(u_*^2 u_{s\,0}\right)^{1/3};
+\end{equation}
+but at times the Stokes drift may be weak due to e.g.\ ice cover, short fetch, misalignment with the surface stress, etc.\ so  a composite velocity scale is assumed for the stable (warming) boundary layer:
+\begin{equation}\label{eq:composite-nu}
+  \nu_{\ast}= \left\{ u_*^3 \left[1-\exp(-.5 \mathrm{La}_t^2)\right]+w_{*L}^3\right\}^{1/3}.
+\end{equation}
+For the unstable boundary layer this is merged with the standard convective velocity scale $w_{*C}=\left(\overline{w^\prime b^\prime}_0 \,h_\mathrm{ml}\right)^{1/3}$, where $\overline{w^\prime b^\prime}_0$ is the upwards surface buoyancy flux, to give:
+\begin{equation}\label{eq:vel-scale-unstable}
+\omega_* = \left(\nu_*^3 + 0.5 w_{*C}^3\right)^{1/3}.
+\end{equation}
+
+\subsubsection{The flux gradient model}
+The flux-gradient relationships used in the OSMOSIS scheme take the form:
+%
+\begin{equation}\label{eq:flux-grad-gen}
+\overline{w^\prime\chi^\prime}=-K\frac{\partial\overline{\chi}}{\partial z} + N_{\chi,s} +N_{\chi,b} +N_{\chi,t},
+\end{equation}
+%
+where $\chi$ is a general variable and $N_{\chi,s}, N_{\chi,b} \mathrm{and} N_{\chi,t}$  are the non-gradient terms, and represent the effects of the different terms in the turbulent flux-budget on the transport of $\chi$. $N_{\chi,s}$ represents the effects that the Stokes shear has on the transport of $\chi$, $N_{\chi,b}$  the effect of buoyancy, and $N_{\chi,t}$ the effect of the turbulent transport.  The same general form for the flux-gradient relationship is used to parametrize the transports of momentum, heat and salinity.
+
+In terms of the non-dimensionalized depth variables
+%
+\begin{equation}\label{eq:sigma}
+\sigma_{\mathrm{ml}}= -z/h_{\mathrm{ml}}; \;\sigma_{\mathrm{bl}}= -z/h_{\mathrm{bl}},
+\end{equation}
+%
+in unstable conditions the eddy diffusivity ($K_d$) and eddy viscosity ($K_\nu$) profiles are parametrized as:
+%
+\begin{align}\label{eq:diff-unstable}
+K_d=&0.8\, \omega_*\, h_{\mathrm{ml}} \, \sigma_{\mathrm{ml}} \left(1-\beta_d \sigma_{\mathrm{ml}}\right)^{3/2}
+\\\label{eq:visc-unstable}
+K_\nu =& 0.3\, \omega_* \,h_{\mathrm{ml}}\, \sigma_{\mathrm{ml}} \left(1-\beta_\nu \sigma_{\mathrm{ml}}\right)\left(1-\tfrac{1}{2}\sigma_{\mathrm{ml}}^2\right)
+\end{align}
+%
+where $\beta_d$ and $\beta_\nu$ are parameters that are determined by matching Eqs \ref{eq:diff-unstable} and \ref{eq:visc-unstable} to the eddy diffusivity and viscosity at the base of the well-mixed layer, given by
+%
+\begin{equation}\label{eq:diff-wml-base}
+K_{d,\mathrm{ml}}=K_{\nu,\mathrm{ml}}=\,0.16\,\omega_* \Delta h.
+\end{equation}
+%
+For stable conditions the eddy diffusivity/viscosity profiles are given by:
+%
+\begin{align}\label{diff-stable}
+K_d= & 0.75\,\, \nu_*\, h_{\mathrm{ml}}\,\,  \exp\left[-2.8 \left(h_{\mathrm{bl}}/L_L\right)^2\right]\sigma_{\mathrm{ml}} \left(1-\sigma_{\mathrm{ml}}\right)^{3/2} \\\label{eq:visc-stable}
+K_\nu = & 0.375\,\,  \nu_*\, h_{\mathrm{ml}} \,\, \exp\left[-2.8 \left(h_{\mathrm{bl}}/L_L\right)^2\right] \sigma_{\mathrm{ml}} \left(1-\sigma_{\mathrm{ml}}\right)\left(1-\tfrac{1}{2}\sigma_{\mathrm{ml}}^2\right).
+\end{align}
+%
+The shape of the eddy viscosity and diffusivity profiles is the same as the shape in the unstable OSBL. The eddy diffusivity/viscosity depends on the stability parameter $h_{\mathrm{bl}}/{L_L}$ where $ L_L$ is analogous to the Obukhov length, but for Langmuir turbulence:
+\begin{equation}\label{eq:L_L}
+  L_L=-w_{*L}^3/\left<\overline{w^\prime b^\prime}\right>_L,
+\end{equation}
+with the mean turbulent buoyancy flux averaged over the boundary layer given in terms of its surface value $\overline{w^\prime b^\prime}_0$ and (downwards) )solar irradiance $I(z)$ by
+\begin{equation} \label{eq:stable-av-buoy-flux}
+\left<\overline{w^\prime b^\prime}\right>_L = \tfrac{1}{2} {\overline{w^\prime b^\prime}}_0-g\alpha_E\left[\tfrac{1}{2}(I(0)+I(-h))-\left<I\right>\right].
+\end{equation}
+%
+In unstable conditions the eddy diffusivity and viscosity depend on stability through the velocity scale $\omega_*$, which depends on the two velocity scales $\nu_*$ and $w_{*C}$.
+
+Details of the non-gradient terms in \eqref{eq:flux-grad-gen} and of the fluxes within the pycnocline $-h_{\mathrm{bl}}<z<h_{\mathrm{ml}}$ can be found in Grant (2019).
+
+\subsubsection{Evolution of the boundary layer depth}
+
+The prognostic equation for the depth of the neutral/unstable boundary layer is given by \citep{grant+etal18},
+
+\begin{equation} \label{eq:dhdt-unstable}
+%\frac{\partial h_\mathrm{bl}}{\partial t} + \mathbf{U}_b\cdot\nabla h_\mathrm{bl}= W_b - \frac{{\overline{w^\prime b^\prime}}_\mathrm{ent}}{\Delta B_\mathrm{bl}}
+\frac{\partial h_\mathrm{bl}}{\partial t} = W_b - \frac{{\overline{w^\prime b^\prime}}_\mathrm{ent}}{\Delta B_\mathrm{bl}}
+\end{equation}
+where $h_\mathrm{bl}$ is the horizontally-varying depth of the OSBL,
+$\mathbf{U}_b$ and $W_b$ are the mean horizontal and vertical
+velocities at the base of the OSBL, ${\overline{w^\prime
+    b^\prime}}_\mathrm{ent}$ is the buoyancy flux due to entrainment
+and $\Delta B_\mathrm{bl}$ is the difference between the buoyancy
+averaged over the depth of the OSBL (i.e.\ including the ML and
+pycnocline) and the buoyancy just below the base of the OSBL. This
+equation for the case when the pycnocline has a finite thickness,
+based on the potential energy budget of the OSBL, is the leading term
+\citep{grant+etal18} of a generalization of that used in mixed-layer
+models e.g.\ \citet{kraus.turner_tellus67}, in which the thickness of the pycnocline is taken to be zero.
+
+The entrainment flux for the combination of convective and Langmuir turbulence is given by
+\begin{equation} \label{eq:entrain-flux}
+  {\overline{w^\prime b^\prime}}_\mathrm{ent} = -\alpha_{\mathrm{B}} {\overline{w^\prime b^\prime}}_0 - \alpha_{\mathrm{S}} \frac{u_*^3}{h_{\mathrm{ml}}}
+  + G\left(\delta/h_{\mathrm{ml}} \right)\left[\alpha_{\mathrm{S}}e^{-1.5\, \mathrm{La}_t}-\alpha_{\mathrm{L}} \frac{w_{\mathrm{*L}}^3}{h_{\mathrm{ml}}}\right]
+\end{equation}
+where the factor $G\equiv 1 - \mathrm{e}^ {-25\delta/h_{\mathrm{bl}}}(1-4\delta/h_{\mathrm{bl}})$ models the lesser efficiency of Langmuir mixing when the boundary-layer depth is much greater than the Stokes depth, and $\alpha_{\mathrm{B}}$, $\alpha_{S}$  and $\alpha_{\mathrm{L}}$ depend on the ratio of the appropriate eddy turnover time to the inertial timescale $f^{-1}$. Results from the LES suggest $\alpha_{\mathrm{B}}=0.18 F(fh_{\mathrm{bl}}/w_{*C})$, $\alpha_{S}=0.15 F(fh_{\mathrm{bl}}/u_*$  and $\alpha_{\mathrm{L}}=0.035 F(fh_{\mathrm{bl}}/u_{*L})$, where $F(x)\equiv\tanh(x^{-1})^{0.69}$.
+
+For the stable boundary layer, the equation for the depth of the OSBL is:
+
+\begin{equation}\label{eq:dhdt-stable}
+\max\left(\Delta B_{bl},\frac{w_{*L}^2}{h_\mathrm{bl}}\right)\frac{\partial h_\mathrm{bl}}{\partial t} = \left(0.06 + 0.52\,\frac{ h_\mathrm{bl}}{L_L}\right) \frac{w_{*L}^3}{h_\mathrm{bl}} +\left<\overline{w^\prime b^\prime}\right>_L.
+\end{equation}
+
+Equation. \ref{eq:dhdt-unstable} always leads to the depth of the entraining OSBL increasing (ignoring the effect of the mean vertical motion), but the change in the thickness of the stable OSBL given by Eq. \ref{eq:dhdt-stable} can be positive or negative, depending on the magnitudes of $\left<\overline{w^\prime b^\prime}\right>_L$ and $h_\mathrm{bl}/L_L$. The rate at which the depth of the OSBL can decrease is limited by choosing an effective buoyancy $w_{*L}^2/h_\mathrm{bl}$, in place of $\Delta B_{bl}$ which will be $\approx 0$ for the collapsing OSBL.
+
 
 %% =================================================================================================
@@ -551,5 +757,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_ZDF_TKE_time_scheme}
+  \includegraphics[width=0.66\textwidth]{ZDF_TKE_time_scheme}
   \caption[Subgrid kinetic energy integration in GLS and TKE schemes]{
     Illustration of the subgrid kinetic energy integration in GLS and TKE schemes and
@@ -663,5 +869,5 @@
 \begin{figure}[!htb]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_npc}
+  \includegraphics[width=0.66\textwidth]{ZDF_npc}
   \caption[Unstable density profile treated by the non penetrative convective adjustment algorithm]{
     Example of an unstable density profile treated by
@@ -808,5 +1014,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_zdfddm}
+  \includegraphics[width=0.66\textwidth]{ZDF_ddm}
   \caption[Diapycnal diffusivities for temperature and salt in regions of salt fingering and
   diffusive convection]{
@@ -1286,5 +1492,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_ZDF_zad_Aimp_coeff}
+  \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_coeff}
   \caption[Partitioning coefficient used to partition vertical velocities into parts]{
     The value of the partitioning coefficient (\cf) used to partition vertical velocities into
@@ -1326,5 +1532,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_ZDF_zad_Aimp_overflow_frames}
+  \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_overflow_frames}
   \caption[OVERFLOW: time-series of temperature vertical cross-sections]{
     A time-series of temperature vertical cross-sections for the OVERFLOW test case.
@@ -1406,5 +1612,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_ZDF_zad_Aimp_overflow_all_rdt}
+  \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_overflow_all_rdt}
   \caption[OVERFLOW: sample temperature vertical cross-sections from mid- and end-run]{
     Sample temperature vertical cross-sections from mid- and end-run using
@@ -1419,5 +1625,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_ZDF_zad_Aimp_maxCf}
+  \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_maxCf}
   \caption[OVERFLOW: maximum partitioning coefficient during a series of test runs]{
     The maximum partitioning coefficient during a series of test runs with
@@ -1430,5 +1636,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_ZDF_zad_Aimp_maxCf_loc}
+  \includegraphics[width=0.66\textwidth]{ZDF_zad_Aimp_maxCf_loc}
   \caption[OVERFLOW: maximum partitioning coefficient for the case overlaid]{
     The maximum partitioning coefficient for the \forcode{nn_rdt=10.0} case overlaid with
@@ -1437,5 +1643,5 @@
 \end{figure}
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_cfgs.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_cfgs.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_cfgs.tex	(revision 11954)
@@ -93,5 +93,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_ORCA_NH_mesh}
+  \includegraphics[width=0.66\textwidth]{CFGS_ORCA_NH_mesh}
   \caption[ORCA mesh conception]{
     ORCA mesh conception.
@@ -120,6 +120,6 @@
 \begin{figure}[!tbp]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_ORCA_NH_msh05_e1_e2}
-  \includegraphics[width=0.66\textwidth]{Fig_ORCA_aniso}
+  \includegraphics[width=0.66\textwidth]{CFGS_ORCA_NH_msh05_e1_e2}
+  \includegraphics[width=0.66\textwidth]{CFGS_ORCA_aniso}
   \caption[Horizontal scale factors and ratio of anisotropy for ORCA 0.5\deg\ mesh]{
     \textit{Top}: Horizontal scale factors ($e_1$, $e_2$) and
@@ -264,5 +264,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_GYRE}
+  \includegraphics[width=0.66\textwidth]{CFGS_GYRE}
   \caption[Snapshot of relative vorticity at the surface of the model domain in GYRE R9, R27 and R54]{
     Snapshot of relative vorticity at the surface of the model domain in GYRE R9, R27 and R54.
@@ -292,5 +292,5 @@
 Unlike ordinary river points the Baltic inputs also include salinity and temperature data.
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_conservation.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_conservation.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_conservation.tex	(revision 11954)
@@ -334,5 +334,5 @@
 It has not been implemented.
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_misc.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_misc.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_misc.tex	(revision 11954)
@@ -94,6 +94,6 @@
 \begin{figure}[!tbp]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_Gibraltar}
-  \includegraphics[width=0.66\textwidth]{Fig_Gibraltar2}
+  \includegraphics[width=0.66\textwidth]{MISC_Gibraltar}
+  \includegraphics[width=0.66\textwidth]{MISC_Gibraltar2}
   \caption[Two methods to defined the Gibraltar strait]{
     Example of the Gibraltar strait defined in a 1\deg\ $\times$ 1\deg\ mesh.
@@ -111,5 +111,5 @@
 \begin{figure}[!tbp]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_closea_mask_example}
+  \includegraphics[width=0.66\textwidth]{MISC_closea_mask_example}
   \caption[Mask fields for the \protect\mdl{closea} module]{
     Example of mask fields for the \protect\mdl{closea} module.
@@ -415,5 +415,5 @@
 increment also applies to the time.step file which is otherwise updated every timestep.
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_model_basics.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_model_basics.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_model_basics.tex	(revision 11954)
@@ -13,11 +13,11 @@
 
 {\footnotesize
-  \begin{tabularx}{\textwidth}{l||X|X}
-    Release & Author(s) & Modifications \\
+  \begin{tabular}{l||l|l}
+    Release          & Author(s)                                   & Modifications       \\
     \hline
-    {\em   4.0} & {\em Mike Bell                       } & {\em Update       } \\
-    {\em   3.6} & {\em Gurvan Madec                    } & {\em Minor changes} \\
-    {\em <=3.4} & {\em Gurvan Madec and Steven Alderson} & {\em First version} \\
-  \end{tabularx}
+    {\em        4.0} & {\em Mike Bell                            } & {\em Review       } \\
+    {\em        3.6} & {\em Tim Graham and Gurvan Madec          } & {\em Updates      } \\
+    {\em $\leq$ 3.4} & {\em Gurvan Madec and S\'{e}bastien Masson} & {\em First version} \\
+  \end{tabular}
 }
 
@@ -130,5 +130,5 @@
 \begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_I_ocean_bc}
+  \includegraphics[width=0.66\textwidth]{MB_ocean_bc}
   \caption[Ocean boundary conditions]{
     The ocean is bounded by two surfaces, $z = - H(i,j)$ and $z = \eta(i,j,t)$,
@@ -208,5 +208,5 @@
 \]
 Two strategies can be considered for the surface pressure term:
-\begin{enumerate*}[label={(\alph*)}]
+\begin{enumerate*}[label=(\textit{\alph*})]
 \item introduce of a new variable $\eta$, the free-surface elevation,
 for which a prognostic equation can be established and solved;
@@ -327,5 +327,5 @@
 \begin{figure}
   \centering
-  \includegraphics[width=0.33\textwidth]{Fig_I_earth_referential}
+  \includegraphics[width=0.33\textwidth]{MB_earth_referential}
   \caption[Geographical and curvilinear coordinate systems]{
     the geographical coordinate system $(\lambda,\varphi,z)$ and the curvilinear
@@ -486,14 +486,14 @@
 \item [Flux form of the momentum equations]
   % \label{eq:MB_dyn_flux}
-  \begin{multline*}
+  \begin{alignat*}{2}
     % \label{eq:MB_dyn_flux_u}
-    \pd[u]{t} = + \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, v - \frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, u)]{i} + \pd[(e_1 \, v \, u)]{j} \rt) \\
-    - \frac{1}{e_3} \pd[(w \, u)]{k} - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) + D_u^{\vect U} + F_u^{\vect U}
-  \end{multline*}
-  \begin{multline*}
+    \pd[u]{t} = &+ \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, v - \frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, u)]{i} + \pd[(e_1 \, v \, u)]{j} \rt) - \frac{1}{e_3} \pd[(w \, u)]{k} \\
+    &- \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) + D_u^{\vect U} + F_u^{\vect U}
+  \end{alignat*}
+  \begin{alignat*}{2}
     % \label{eq:MB_dyn_flux_v}
-    \pd[v]{t} = - \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, u - \frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, v)]{i} + \pd[(e_1 \, v \, v)]{j} \rt) \\
-    - \frac{1}{e_3} \pd[(w \, v)]{k} - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) + D_v^{\vect U} + F_v^{\vect U}
-  \end{multline*}
+    \pd[v]{t} = &- \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, u - \frac{1}{e_1 \; e_2} \lt( \pd[(e_2 \, u \, v)]{i} + \pd[(e_1 \, v \, v)]{j} \rt) - \frac{1}{e_3} \pd[(w \, v)]{k} \\
+    &- \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) + D_v^{\vect U} + F_v^{\vect U}
+  \end{alignat*}
   where $\zeta$, the relative vorticity, is given by \autoref{eq:MB_curl_Uh} and
   $p_s$, the surface pressure, is given by:
@@ -579,6 +579,6 @@
 an explicit computation of vertical advection relative to the moving s-surfaces.
 
-%\gmcomment{
-%A key point here is that the $s$-coordinate depends on $(i,j)$ ==> horizontal pressure gradient...
+\cmtgm{A key point here is that the $s$-coordinate depends on $(i,j)$
+  ==> horizontal pressure gradient...}
 The generalized vertical coordinates used in ocean modelling are not orthogonal,
 which contrasts with many other applications in mathematical physics.
@@ -650,14 +650,14 @@
   \end{gather*}
 \item [Flux form of the momentum equation]
-  \begin{multline*}
+  \begin{alignat*}{2}
     % \label{eq:MB_sco_u_flux}
-    \frac{1}{e_3} \pd[(e_3 \, u)]{t} = + \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, v - \frac{1}{e_1 \; e_2 \; e_3} \lt( \pd[(e_2 \, e_3 \, u \, u)]{i} + \pd[(e_1 \, e_3 \, v \, u)]{j} \rt) \\
-    - \frac{1}{e_3} \pd[(\omega \, u)]{k} - \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) - g \frac{\rho}{\rho_o} \sigma_1 + D_u^{\vect U} + F_u^{\vect U}
-  \end{multline*}
-  \begin{multline*}
+    \frac{1}{e_3} \pd[(e_3 \, u)]{t} = &+ \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, v - \frac{1}{e_1 \; e_2 \; e_3} \lt( \pd[(e_2 \, e_3 \, u \, u)]{i} + \pd[(e_1 \, e_3 \, v \, u)]{j} \rt) - \frac{1}{e_3} \pd[(\omega \, u)]{k} \\
+    &- \frac{1}{e_1} \pd[]{i} \lt( \frac{p_s + p_h}{\rho_o} \rt) - g \frac{\rho}{\rho_o} \sigma_1 + D_u^{\vect U} + F_u^{\vect U}
+  \end{alignat*}
+  \begin{alignat*}{2}
   % \label{eq:MB_sco_v_flux}
-    \frac{1}{e_3} \pd[(e_3 \, v)]{t} = - \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, u - \frac{1}{e_1 \; e_2 \; e_3} \lt( \pd[( e_2 \; e_3 \, u \, v)]{i} + \pd[(e_1 \; e_3 \, v \, v)]{j} \rt) \\
-    - \frac{1}{e_3} \pd[(\omega \, v)]{k} - \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) - g \frac{\rho}{\rho_o}\sigma_2 + D_v^{\vect U} + F_v^{\vect U}
-  \end{multline*}
+    \frac{1}{e_3} \pd[(e_3 \, v)]{t} = &- \lt[ f + \frac{1}{e_1 \; e_2} \lt( v \pd[e_2]{i} - u \pd[e_1]{j} \rt) \rt] \, u - \frac{1}{e_1 \; e_2 \; e_3} \lt( \pd[( e_2 \; e_3 \, u \, v)]{i} + \pd[(e_1 \; e_3 \, v \, v)]{j} \rt) - \frac{1}{e_3} \pd[(\omega \, v)]{k} \\
+    &- \frac{1}{e_2} \pd[]{j} \lt( \frac{p_s + p_h}{\rho_o} \rt) - g \frac{\rho}{\rho_o}\sigma_2 + D_v^{\vect U} + F_v^{\vect U}
+  \end{alignat*}
   where the relative vorticity, $\zeta$, the surface pressure gradient,
   and the hydrostatic pressure have the same expressions as in $z$-coordinates although
@@ -680,5 +680,5 @@
 and similar expressions are used for mixing and forcing terms.
 
-\gmcomment{
+\cmtgm{
   \colorbox{yellow}{ to be updated $= = >$}
   Add a few works on z and zps and s and underlies the differences between all of them
@@ -692,7 +692,7 @@
 \begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_z_zstar}
+  \includegraphics[width=0.66\textwidth]{MB_z_zstar}
   \caption[Curvilinear z-coordinate systems (\{non-\}linear free-surface cases and re-scaled \zstar)]{
-    \begin{enumerate*}[label={(\alph*)}]
+    \begin{enumerate*}[label=(\textit{\alph*})]
     \item $z$-coordinate in linear free-surface case;
     \item $z$-coordinate in non-linear free surface case;
@@ -1051,6 +1051,6 @@
 \begin{equation}
   \label{eq:MB_iso_slopes}
-  r_1 = \frac{e_3}{e_1}	\lt( \pd[\rho]{i} \rt) \lt( \pd[\rho]{k} \rt)^{-1} \quad
-  r_2 = \frac{e_3}{e_2}	\lt( \pd[\rho]{j} \rt) \lt( \pd[\rho]{k} \rt)^{-1}
+  r_1 = \frac{e_3}{e_1} \lt( \pd[\rho]{i} \rt) \lt( \pd[\rho]{k} \rt)^{-1} \quad
+  r_2 = \frac{e_3}{e_2} \lt( \pd[\rho]{j} \rt) \lt( \pd[\rho]{k} \rt)^{-1}
 \end{equation}
 while in $s$-coordinates $\pd[]{k}$ is replaced by $\pd[]{s}$.
@@ -1067,11 +1067,11 @@
 where $ \vect U^\ast = \lt( u^\ast,v^\ast,w^\ast \rt)$ is a non-divergent,
 eddy-induced transport velocity. This velocity field is defined by:
-\begin{gather*}
+\[
   % \label{eq:MB_eiv}
   u^\ast =   \frac{1}{e_3}            \pd[]{k} \lt( A^{eiv} \;        \tilde{r}_1 \rt) \quad
-  v^\ast =   \frac{1}{e_3}            \pd[]{k} \lt( A^{eiv} \;        \tilde{r}_2 \rt) \\
+  v^\ast =   \frac{1}{e_3}            \pd[]{k} \lt( A^{eiv} \;        \tilde{r}_2 \rt) \quad
   w^\ast = - \frac{1}{e_1 e_2} \lt[   \pd[]{i} \lt( A^{eiv} \; e_2 \, \tilde{r}_1 \rt)
                                      + \pd[]{j} \lt( A^{eiv} \; e_1 \, \tilde{r}_2 \rt) \rt]
-\end{gather*}
+\]
 where $A^{eiv}$ is the eddy induced velocity coefficient
 (or equivalently the isoneutral thickness diffusivity coefficient),
@@ -1130,9 +1130,9 @@
 the $u$ and $v$-fields are considered as independent scalar fields,
 so that the diffusive operator is given by:
-\begin{gather*}
+\[
   % \label{eq:MB_lapU_iso}
-    D_u^{l \vect U} = \nabla . \lt( A^{lm} \; \Re \; \nabla u \rt) \\
+    D_u^{l \vect U} = \nabla . \lt( A^{lm} \; \Re \; \nabla u \rt) \quad
     D_v^{l \vect U} = \nabla . \lt( A^{lm} \; \Re \; \nabla v \rt)
-\end{gather*}
+\]
 where $\Re$ is given by \autoref{eq:MB_iso_tensor}.
 It is the same expression as those used for diffusive operator on tracers.
@@ -1150,5 +1150,5 @@
 Nevertheless it is currently not available in the iso-neutral case.
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_model_basics_zstar.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_model_basics_zstar.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_model_basics_zstar.tex	(revision 11954)
@@ -147,5 +147,5 @@
 \begin{figure}[!t]
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_DYN_dynspg_ts}
+  %\includegraphics[width=0.66\textwidth]{MBZ_DYN_dynspg_ts}
   \caption[Schematic of the split-explicit time stepping scheme for
   the barotropic and baroclinic modes, after \citet{Griffies2004?}]{
@@ -311,5 +311,5 @@
 In particular, this means that in filtered case, the matrix to be inverted has to be recomputed at each time-step.
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_time_domain.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_time_domain.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/NEMO/subfiles/chap_time_domain.tex	(revision 11954)
@@ -13,11 +13,14 @@
 
 {\footnotesize
-  \begin{tabularx}{\textwidth}{l||X|X}
-    Release & Author(s) & Modifications \\
+  \begin{tabularx}{0.5\textwidth}{l||X|X}
+    Release          & Author(s)                                       &
+    Modifications                                                      \\
     \hline
-    {\em   4.0} & {\em ...} & {\em ...} \\
-    {\em   3.6} & {\em ...} & {\em ...} \\
-    {\em   3.4} & {\em ...} & {\em ...} \\
-    {\em <=3.4} & {\em ...} & {\em ...}
+    {\em        4.0} & {\em J\'{e}r\^{o}me Chanut \newline Tim Graham} &
+    {\em Review \newline Update                                      } \\
+    {\em        3.6} & {\em Christian \'{E}th\'{e}                   } &
+    {\em Update                                                      } \\
+    {\em $\leq$ 3.4} & {\em Gurvan Madec                             } &
+    {\em First version                                               } \\
   \end{tabularx}
 }
@@ -26,13 +29,14 @@
 
 % Missing things:
-%	- daymod: definition of the time domain (nit000, nitend and the calendar)
-
-\gmcomment{STEVEN :maybe a picture of the directory structure in the introduction which could be referred to here,
-  would help  ==> to be added}
-
-Having defined the continuous equations in \autoref{chap:MB}, we need now to choose a time discretization,
+% - daymod: definition of the time domain (nit000, nitend and the calendar)
+
+\cmtgm{STEVEN :maybe a picture of the directory structure in the introduction which
+could be referred to here, would help  ==> to be added}
+
+Having defined the continuous equations in \autoref{chap:MB},
+we need now to choose a time discretization,
 a key feature of an ocean model as it exerts a strong influence on the structure of the computer code
 (\ie\ on its flowchart).
-In the present chapter, we provide a general description of the \NEMO\  time stepping strategy and
+In the present chapter, we provide a general description of the \NEMO\ time stepping strategy and
 the consequences for the order in which the equations are solved.
 
@@ -47,14 +51,15 @@
 \end{equation}
 where $x$ stands for $u$, $v$, $T$ or $S$;
-RHS is the Right-Hand-Side of the corresponding time evolution equation;
+RHS is the \textbf{R}ight-\textbf{H}and-\textbf{S}ide of the corresponding time evolution equation;
 $\rdt$ is the time step;
 and the superscripts indicate the time at which a quantity is evaluated.
-Each term of the RHS is evaluated at a specific time stepping depending on the physics with which it is associated.
+Each term of the RHS is evaluated at a specific time stepping depending on
+the physics with which it is associated.
 
 The choice of the time stepping used for this evaluation is discussed below as well as
 the implications for starting or restarting a model simulation.
 Note that the time stepping calculation is generally performed in a single operation.
-With such a complex and nonlinear system of equations it would be dangerous to let a prognostic variable evolve in
-time for each term separately.
+With such a complex and nonlinear system of equations it would be dangerous to
+let a prognostic variable evolve in time for each term separately.
 
 The three level scheme requires three arrays for each prognostic variable.
@@ -62,6 +67,9 @@
 The third array, although referred to as $x_a$ (after) in the code,
 is usually not the variable at the after time step;
-but rather it is used to store the time derivative (RHS in \autoref{eq:TD}) prior to time-stepping the equation.
-The time stepping itself is performed once at each time step where implicit vertical diffusion is computed, \ie\ in the \mdl{trazdf} and \mdl{dynzdf} modules.
+but rather it is used to store the time derivative (RHS in \autoref{eq:TD})
+prior to time-stepping the equation.
+The time stepping itself is performed once at each time step where
+implicit vertical diffusion is computed,
+\ie\ in the \mdl{trazdf} and \mdl{dynzdf} modules.
 
 %% =================================================================================================
@@ -69,22 +77,25 @@
 \label{sec:TD_leap_frog}
 
-The time stepping used for processes other than diffusion is the well-known leapfrog scheme
-\citep{mesinger.arakawa_bk76}.
+The time stepping used for processes other than diffusion is
+the well-known \textbf{L}eap\textbf{F}rog (LF) scheme \citep{mesinger.arakawa_bk76}.
 This scheme is widely used for advection processes in low-viscosity fluids.
-It is a time centred scheme, \ie\ the RHS in \autoref{eq:TD} is evaluated at time step $t$, the now time step.
+It is a time centred scheme, \ie\ the RHS in \autoref{eq:TD} is evaluated at
+time step $t$, the now time step.
 It may be used for momentum and tracer advection, pressure gradient, and Coriolis terms,
 but not for diffusion terms.
 It is an efficient method that achieves second-order accuracy with
 just one right hand side evaluation per time step.
-Moreover, it does not artificially damp linear oscillatory motion nor does it produce instability by
-amplifying the oscillations.
+Moreover, it does not artificially damp linear oscillatory motion
+nor does it produce instability by amplifying the oscillations.
 These advantages are somewhat diminished by the large phase-speed error of the leapfrog scheme,
-and the unsuitability of leapfrog differencing for the representation of diffusion and Rayleigh damping processes.
+and the unsuitability of leapfrog differencing for the representation of diffusion and
+Rayleigh damping processes.
 However, the scheme allows the coexistence of a numerical and a physical mode due to
 its leading third order dispersive error.
 In other words a divergence of odd and even time steps may occur.
-To prevent it, the leapfrog scheme is often used in association with a Robert-Asselin time filter
-(hereafter the LF-RA scheme).
-This filter, first designed by \citet{robert_JMSJ66} and more comprehensively studied by \citet{asselin_MWR72},
+To prevent it, the leapfrog scheme is often used in association with
+a \textbf{R}obert-\textbf{A}sselin time filter (hereafter the LF-RA scheme).
+This filter,
+first designed by \citet{robert_JMSJ66} and more comprehensively studied by \citet{asselin_MWR72},
 is a kind of laplacian diffusion in time that mixes odd and even time steps:
 \begin{equation}
@@ -99,10 +110,11 @@
 However, the second order truncation error is proportional to $\gamma$, which is small compared to 1.
 Therefore, the LF-RA is a quasi second order accurate scheme.
-The LF-RA scheme is preferred to other time differencing schemes such as predictor corrector or trapezoidal schemes,
-because the user has an explicit and simple control of the magnitude of the time diffusion of the scheme.
-When used with the 2nd order space centred discretisation of the advection terms in
+The LF-RA scheme is preferred to other time differencing schemes such as
+predictor corrector or trapezoidal schemes, because the user has an explicit and simple control of
+the magnitude of the time diffusion of the scheme.
+When used with the 2$^nd$ order space centred discretisation of the advection terms in
 the momentum and tracer equations, LF-RA avoids implicit numerical diffusion:
-diffusion is set explicitly by the user through the Robert-Asselin
-filter parameter and the viscosity and diffusion coefficients.
+diffusion is set explicitly by the user through the Robert-Asselin filter parameter and
+the viscosity and diffusion coefficients.
 
 %% =================================================================================================
@@ -110,5 +122,6 @@
 \label{sec:TD_forward_imp}
 
-The leapfrog differencing scheme is unsuitable for the representation of diffusion and damping processes.
+The leapfrog differencing scheme is unsuitable for
+the representation of diffusion and damping processes.
 For a tendency $D_x$, representing a diffusion term or a restoring term to a tracer climatology
 (when present, see \autoref{sec:TRA_dmp}), a forward time differencing scheme is used :
@@ -119,5 +132,6 @@
 
 This is diffusive in time and conditionally stable.
-The conditions for stability of second and fourth order horizontal diffusion schemes are \citep{griffies_bk04}:
+The conditions for stability of second and fourth order horizontal diffusion schemes are
+\citep{griffies_bk04}:
 \begin{equation}
   \label{eq:TD_euler_stability}
@@ -128,12 +142,15 @@
   \end{cases}
 \end{equation}
-where $e$ is the smallest grid size in the two horizontal directions and $A^h$ is the mixing coefficient.
+where $e$ is the smallest grid size in the two horizontal directions and
+$A^h$ is the mixing coefficient.
 The linear constraint \autoref{eq:TD_euler_stability} is a necessary condition, but not sufficient.
 If it is not satisfied, even mildly, then the model soon becomes wildly unstable.
-The instability can be removed by either reducing the length of the time steps or reducing the mixing coefficient.
+The instability can be removed by either reducing the length of the time steps or
+reducing the mixing coefficient.
 
 For the vertical diffusion terms, a forward time differencing scheme can be used,
-but usually the numerical stability condition imposes a strong constraint on the time step. To overcome the stability constraint, a
-backward (or implicit) time differencing scheme is used. This scheme is unconditionally stable but diffusive and can be written as follows:
+but usually the numerical stability condition imposes a strong constraint on the time step.
+To overcome the stability constraint, a backward (or implicit) time differencing scheme is used.
+This scheme is unconditionally stable but diffusive and can be written as follows:
 \begin{equation}
   \label{eq:TD_imp}
@@ -141,9 +158,8 @@
 \end{equation}
 
-%%gm
-%%gm   UPDATE the next paragraphs with time varying thickness ...
-%%gm
-
-This scheme is rather time consuming since it requires a matrix inversion. For example, the finite difference approximation of the temperature equation is:
+\cmtgm{UPDATE the next paragraphs with time varying thickness ...}
+
+This scheme is rather time consuming since it requires a matrix inversion.
+For example, the finite difference approximation of the temperature equation is:
 \[
   % \label{eq:TD_imp_zdf}
@@ -159,13 +175,14 @@
 \end{equation}
 where
-\begin{align*}
-  c(k) &= A_w^{vT} (k) \, / \, e_{3w} (k)     \\
-  d(k) &= e_{3t}   (k)       \, / \, (2 \rdt) + c_k + c_{k + 1}    \\
-  b(k) &= e_{3t}   (k) \; \lt( T^{t - 1}(k) \, / \, (2 \rdt) + \text{RHS} \rt)
-\end{align*}
-
-\autoref{eq:TD_imp_mat} is a linear system of equations with an associated matrix which is tridiagonal.
-Moreover,
-$c(k)$ and $d(k)$ are positive and the diagonal term is greater than the sum of the two extra-diagonal terms,
+\[
+  c(k) = A_w^{vT} (k) \, / \, e_{3w} (k) \text{,} \quad
+  d(k) = e_{3t}   (k)       \, / \, (2 \rdt) + c_k + c_{k + 1} \quad \text{and} \quad
+  b(k) = e_{3t}   (k) \; \lt( T^{t - 1}(k) \, / \, (2 \rdt) + \text{RHS} \rt)
+\]
+
+\autoref{eq:TD_imp_mat} is a linear system of equations with
+an associated matrix which is tridiagonal.
+Moreover, $c(k)$ and $d(k)$ are positive and
+the diagonal term is greater than the sum of the two extra-diagonal terms,
 therefore a special adaptation of the Gauss elimination procedure is used to find the solution
 (see for example \citet{richtmyer.morton_bk67}).
@@ -175,24 +192,31 @@
 \label{sec:TD_spg_ts}
 
-The leapfrog environment supports a centred in time computation of the surface pressure, \ie\ evaluated
-at \textit{now} time step. This refers to as the explicit free surface case in the code (\np[=.true.]{ln_dynspg_exp}{ln\_dynspg\_exp}).
-This choice however imposes a strong constraint on the time step which should be small enough to resolve the propagation
-of external gravity waves. As a matter of fact, one rather use in a realistic setup, a split-explicit free surface
-(\np[=.true.]{ln_dynspg_ts}{ln\_dynspg\_ts}) in which barotropic and baroclinic dynamical equations are solved separately with ad-hoc
-time steps. The use of the time-splitting (in combination with non-linear free surface) imposes some constraints on the design of
-the overall flowchart, in particular to ensure exact tracer conservation (see \autoref{fig:TD_TimeStep_flowchart}).
-
-Compared to the former use of the filtered free surface in \NEMO\ v3.6 (\citet{roullet.madec_JGR00}), the use of a split-explicit free surface is advantageous
-on massively parallel computers. Indeed, no global computations are anymore required by the elliptic solver which saves a substantial amount of communication
-time. Fast barotropic motions (such as tides) are also simulated with a better accuracy.
-
-%\gmcomment{
-\begin{figure}[!t]
+The leapfrog environment supports a centred in time computation of the surface pressure,
+\ie\ evaluated at \textit{now} time step.
+This refers to as the explicit free surface case in the code
+(\np[=.true.]{ln_dynspg_exp}{ln\_dynspg\_exp}).
+This choice however imposes a strong constraint on the time step which
+should be small enough to resolve the propagation of external gravity waves.
+As a matter of fact, one rather use in a realistic setup,
+a split-explicit free surface (\np[=.true.]{ln_dynspg_ts}{ln\_dynspg\_ts}) in which
+barotropic and baroclinic dynamical equations are solved separately with ad-hoc time steps.
+The use of the time-splitting (in combination with non-linear free surface) imposes
+some constraints on the design of the overall flowchart,
+in particular to ensure exact tracer conservation (see \autoref{fig:TD_TimeStep_flowchart}).
+
+Compared to the former use of the filtered free surface in \NEMO\ v3.6 (\citet{roullet.madec_JGR00}),
+the use of a split-explicit free surface is advantageous on massively parallel computers.
+Indeed, no global computations are anymore required by the elliptic solver which
+saves a substantial amount of communication time.
+Fast barotropic motions (such as tides) are also simulated with a better accuracy.
+
+%\cmtgm{
+\begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_TimeStepping_flowchart_v4}
+  \includegraphics[width=0.66\textwidth]{TD_TimeStepping_flowchart_v4}
   \caption[Leapfrog time stepping sequence with split-explicit free surface]{
     Sketch of the leapfrog time stepping sequence in \NEMO\ with split-explicit free surface.
-    The latter combined with non-linear free surface requires the dynamical tendency being
-    updated prior tracers tendency to ensure conservation.
+    The latter combined with non-linear free surface requires
+    the dynamical tendency being updated prior tracers tendency to ensure conservation.
     Note the use of time integrated fluxes issued from the barotropic loop in
     subsequent calculations of tracer advection and in the continuity equation.
@@ -203,15 +227,17 @@
 
 %% =================================================================================================
-\section{Modified Leapfrog -- Asselin filter scheme}
+\section{Modified LeapFrog -- Robert Asselin filter scheme (LF-RA)}
 \label{sec:TD_mLF}
 
-Significant changes have been introduced by \cite{leclair.madec_OM09} in the LF-RA scheme in order to
-ensure tracer conservation and to allow the use of a much smaller value of the Asselin filter parameter.
+Significant changes have been introduced by \cite{leclair.madec_OM09} in
+the LF-RA scheme in order to ensure tracer conservation and to
+allow the use of a much smaller value of the Asselin filter parameter.
 The modifications affect both the forcing and filtering treatments in the LF-RA scheme.
 
-In a classical LF-RA environment, the forcing term is centred in time,
-\ie\ it is time-stepped over a $2 \rdt$ period:
+In a classical LF-RA environment,
+the forcing term is centred in time, \ie\ it is time-stepped over a $2 \rdt$ period:
 $x^t = x^t + 2 \rdt Q^t$ where $Q$ is the forcing applied to $x$,
-and the time filter is given by \autoref{eq:TD_asselin} so that $Q$ is redistributed over several time step.
+and the time filter is given by \autoref{eq:TD_asselin} so that
+$Q$ is redistributed over several time step.
 In the modified LF-RA environment, these two formulations have been replaced by:
 \begin{gather}
@@ -222,16 +248,17 @@
                     - \gamma \, \rdt \, \lt( Q^{t + \rdt / 2} - Q^{t - \rdt / 2} \rt)
 \end{gather}
-The change in the forcing formulation given by \autoref{eq:TD_forcing} (see \autoref{fig:TD_MLF_forcing})
-has a significant effect:
-the forcing term no longer excites the divergence of odd and even time steps \citep{leclair.madec_OM09}.
+The change in the forcing formulation given by \autoref{eq:TD_forcing}
+(see \autoref{fig:TD_MLF_forcing}) has a significant effect:
+the forcing term no longer excites the divergence of odd and even time steps
+\citep{leclair.madec_OM09}.
 % forcing seen by the model....
 This property improves the LF-RA scheme in two aspects.
 First, the LF-RA can now ensure the local and global conservation of tracers.
 Indeed, time filtering is no longer required on the forcing part.
-The influence of the Asselin filter on the forcing is explicitly removed by adding a new term in the filter
-(last term in \autoref{eq:TD_RA} compared to \autoref{eq:TD_asselin}).
+The influence of the Asselin filter on the forcing is explicitly removed by
+adding a new term in the filter (last term in \autoref{eq:TD_RA} compared to \autoref{eq:TD_asselin}).
 Since the filtering of the forcing was the source of non-conservation in the classical LF-RA scheme,
 the modified formulation becomes conservative \citep{leclair.madec_OM09}.
-Second, the LF-RA becomes a truly quasi -second order scheme.
+Second, the LF-RA becomes a truly quasi-second order scheme.
 Indeed, \autoref{eq:TD_forcing} used in combination with a careful treatment of static instability
 (\autoref{subsec:ZDF_evd}) and of the TKE physics (\autoref{subsec:ZDF_tke_ene})
@@ -245,7 +272,7 @@
 even if separated by only $\rdt$ since the time filter is no longer applied to the forcing term.
 
-\begin{figure}[!t]
+\begin{figure}
   \centering
-  \includegraphics[width=0.66\textwidth]{Fig_MLF_forcing}
+  \includegraphics[width=0.66\textwidth]{TD_MLF_forcing}
   \caption[Forcing integration methods for modified leapfrog (top and bottom)]{
     Illustration of forcing integration methods.
@@ -271,11 +298,12 @@
 \end{listing}
 
-The first time step of this three level scheme when starting from initial conditions is a forward step
-(Euler time integration):
+The first time step of this three level scheme when starting from initial conditions is
+a forward step (Euler time integration):
 \[
   % \label{eq:TD_DOM_euler}
   x^1 = x^0 + \rdt \ \text{RHS}^0
 \]
-This is done simply by keeping the leapfrog environment (\ie\ the \autoref{eq:TD} three level time stepping) but
+This is done simply by keeping the leapfrog environment
+(\ie\ the \autoref{eq:TD} three level time stepping) but
 setting all $x^0$ (\textit{before}) and $x^1$ (\textit{now}) fields equal at the first time step and
 using half the value of a leapfrog time step ($2 \rdt$).
@@ -286,22 +314,27 @@
 running the model for $2N$ time steps in one go,
 or by performing two consecutive experiments of $N$ steps with a restart.
-This requires saving two time levels and many auxiliary data in the restart files in machine precision.
+This requires saving two time levels and many auxiliary data in
+the restart files in machine precision.
 
 Note that the time step $\rdt$, is also saved in the restart file.
-When restarting, if the time step has been changed, or one of the prognostic variables at \textit{before} time step
-is missing, an Euler time stepping scheme is imposed. A forward initial step can still be enforced by the user by setting
-the namelist variable \np[=0]{nn_euler}{nn\_euler}. Other options to control the time integration of the model
-are defined through the  \nam{run}{run} namelist variables.
-\gmcomment{
+When restarting, if the time step has been changed, or
+one of the prognostic variables at \textit{before} time step is missing,
+an Euler time stepping scheme is imposed.
+A forward initial step can still be enforced by the user by
+setting the namelist variable \np[=0]{nn_euler}{nn\_euler}.
+Other options to control the time integration of the model are defined through
+the \nam{run}{run} namelist variables.
+
+\cmtgm{
 add here how to force the restart to contain only one time step for operational purposes
 
 add also the idea of writing several restart for seasonal forecast : how is it done ?
 
-verify that all namelist pararmeters are truly described
+verify that all namelist parameters are truly described
 
 a word on the check of restart  .....
 }
 
-\gmcomment{       % add a subsection here
+\cmtgm{       % add a subsection here
 
 %% =================================================================================================
@@ -309,14 +342,14 @@
 \label{subsec:TD_time}
 
-Options are defined through the  \nam{dom}{dom} namelist variables.
+Options are defined through the\nam{dom}{dom} namelist variables.
  \colorbox{yellow}{add here a few word on nit000 and nitend}
 
  \colorbox{yellow}{Write documentation on the calendar and the key variable adatrj}
 
-add a description of daymod, and the model calandar (leap-year and co)
-
-}     	%% end add
-
-\gmcomment{       % add implicit in vvl case  and Crant-Nicholson scheme
+add a description of daymod, and the model calendar (leap-year and co)
+
+}     %% end add
+
+\cmtgm{       % add implicit in vvl case  and Crant-Nicholson scheme
 
 Implicit time stepping in case of variable volume thickness.
@@ -369,5 +402,5 @@
 }
 
-\onlyinsubfile{\input{../../global/epilogue}}
+\subinc{\input{../../global/epilogue}}
 
 \end{document}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/SI3/build/SI3_manual.ist
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/SI3/build/SI3_manual.ist	(revision 11712)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../global/index.ist
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/SI3/namelists/namdyn_adv
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/SI3/namelists/namdyn_adv	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/SI3/namelists/namdyn_adv	(revision 11954)
@@ -2,6 +2,6 @@
 &namdyn_adv     !   Ice advection
 !------------------------------------------------------------------------------
-   ln_adv_Pra       = .false.         !  Advection scheme (Prather)
-   ln_adv_UMx       = .true.          !  Advection scheme (Ultimate-Macho)
+   ln_adv_Pra       = .true.         !  Advection scheme (Prather)
+   ln_adv_UMx       = .false.          !  Advection scheme (Ultimate-Macho)
       nn_UMx        =   5             !     order of the scheme for UMx (1-5 ; 20=centered 2nd order)
 /
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/TOP/build/TOP_manual.ist
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/TOP/build/TOP_manual.ist	(revision 11712)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../global/index.ist
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/TOP/subfiles/model_description.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/TOP/subfiles/model_description.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/TOP/subfiles/model_description.tex	(revision 11954)
@@ -14,5 +14,5 @@
 \chapter{Model Description}
 \label{chap:ModDes}
-\minitoc
+\chaptertoc
 
 \section{Basics}
@@ -80,5 +80,5 @@
 \nlst{namtrc_ldf}
 %-------------------------------------------------------------------------------------------------------------
-In NEMO v4.0, the passive tracer diffusion has necessarily the same form as the active tracer diffusion, meaning that the numerical scheme must be the same. However the passive tracer mixing coefficient can be chosen as a multiple of the active ones by changing the value of \textit{rn\_ldf\_multi} in namelist \textit{namtrc\_ldf}. The choice of numerical scheme is then set  in the \ngn{namtra\_ldf} namelist for the dynamic described in section 5.2 of \citep{nemo_manual}.
+In NEMO v4.0, the passive tracer diffusion has necessarily the same form as the active tracer diffusion, meaning that the numerical scheme must be the same. However the passive tracer mixing coefficient can be chosen as a multiple of the active ones by changing the value of \textit{rn\_ldf\_multi} in namelist \textit{namtrc\_ldf}. The choice of numerical scheme is then set  in the \nam{namtra_ldf}{namtra\_ldf} namelist for the dynamic described in section 5.2 of \citep{nemo_manual}.
 
 
@@ -95,5 +95,5 @@
 
 The use of newtonian damping  to climatological fields or observations is also coded, sharing the same routine dans active tracers. Boolean variables are defined in the namelist\_top\_ref to select the tracers on which restoring is applied
-Options are defined through the  \ngn{namtrc\_dmp} namelist variables. The restoring term is added when the namelist parameter \np{ln\_trcdmp} is set to true. The restoring coefficient is a three-dimensional array read in a file, which name is specified by the namelist variable \np{cn\_resto\_tr}. This netcdf file can be generated using the DMP\_TOOLS tool.
+Options are defined through the \nam{namtrc_dmp}{namtrc\_dmp} namelist variables. The restoring term is added when the namelist parameter \np{ln\_trcdmp} is set to true. The restoring coefficient is a three-dimensional array read in a file, which name is specified by the namelist variable \np{cn\_resto\_tr}. This netcdf file can be generated using the DMP\_TOOLS tool.
 
  \subsection{ Tracer positivity}
@@ -104,5 +104,5 @@
 
 Sometimes, numerical scheme can generates negative values of passive tracers concentration that must be positive. For exemple,  isopycnal diffusion can created extrema. The trcrad routine artificially corrects negative concentrations with a very crude solution that either sets negative concentration to zero without adjusting the tracer budget, or by removing negative concentration and keeping mass conservation.
-The treatment of negative concentrations is an option and can be selected in the namelist \ngn{namtrc\_rad} by setting the parameter \np{ln\_trcrad}  to true.
+The treatment of negative concentrations is an option and can be selected in the namelist \nam{namtrc_rad}{namtrc\_rad} by setting the parameter \np{ln\_trcrad}  to true.
 
 \section{The SMS modules}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/global/document.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/global/document.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/global/document.tex	(revision 11954)
@@ -18,11 +18,11 @@
 %% End of common preamble between main and sub-files
 %% Override custom cmds for full manual compilation
-\newcommand{\onlyinsubfile}[1]{#1}
-\newcommand{\notinsubfile}[1]{}
+\newcommand{\subinc}[1]{#1}
+\newcommand{\subexc}[1]{}
 
 \begin{document}
 
-\renewcommand{\onlyinsubfile}[1]{}
-\renewcommand{\notinsubfile}[1]{#1}
+\renewcommand{\subinc}[1]{}
+\renewcommand{\subexc}[1]{#1}
 
 
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/global/frontpage.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/global/frontpage.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/global/frontpage.tex	(revision 11954)
@@ -33,5 +33,5 @@
     \LARGE Version \version\ -\ \today \\
     \medskip
-    \href{http://doi.org/10.5281/zenodo.\zid}{ \includegraphics{{badges/zenodo.\zid}.pdf} }
+    \href{http://doi.org/10.5281/zenodo.\zid}{ \includegraphics{badges/zenodo.\zid} }
   \end{center}
 
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/global/new_cmds.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/global/new_cmds.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/global/new_cmds.tex	(revision 11954)
@@ -34,5 +34,5 @@
 
 %% Gurvan's comments
-\newcommand{\gmcomment}[1]{}
+\newcommand{\cmtgm}[1]{}
 
 %% Maths
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/global/packages.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/global/packages.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/global/packages.tex	(revision 11954)
@@ -18,13 +18,14 @@
 %% Issue with fontawesome pkg: path to FontAwesome.otf has to be hard-coded
 \defaultfontfeatures{
-    Path = /home/ntmlod/.local/texlive2019/texmf-dist/fonts/opentype/public/fontawesome/
+    Path = /usr/local/texlive/2019/texmf-dist/fonts/opentype/public/fontawesome/
 }
 \usepackage{academicons, fontawesome, newtxtext}
 
 %% Formatting
+\usepackage[inline]{enumitem}
 \usepackage{etoc, tabularx, xcolor}
 
 %% Graphics
-\usepackage{caption, graphicx}
+\usepackage{caption, graphicx, grffile}
 
 %% Labels
@@ -32,5 +33,5 @@
 
 %% Mathematics
-\usepackage{amsmath, amssymb}
+\usepackage{amsmath, amssymb, mathtools}
 
 %% Versatility
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/global/styles.tex
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/global/styles.tex	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/latex/global/styles.tex	(revision 11954)
@@ -72,3 +72,14 @@
 }
 
+%% Temporary fix
+\def\set@curr@file#1{%
+  \begingroup
+    \escapechar\m@ne
+    \xdef\@curr@file{\expandafter\string\csname #1\endcsname}%
+  \endgroup
+}
+\def\quote@name#1{"\quote@@name#1\@gobble""}
+\def\quote@@name#1"{#1\quote@@name}
+\def\unquote@name#1{\quote@@name#1\@gobble"}
+
 \makeatother
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nam_diadct
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nam_diadct	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nam_diadct	(revision 11954)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&nam_diadct     !   transports through some sections                    (default: OFF)
+&nam_diadct    !   transports through some sections                     (default: OFF)
 !-----------------------------------------------------------------------
     ln_diadct  = .false.   ! Calculate transport thru sections or not
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nam_diaharm
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nam_diaharm	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nam_diaharm	(revision 11954)
@@ -7,4 +7,4 @@
        nstep_han  = 15     !    Time step frequency for harmonic analysis
        tname(1)   = 'M2'   !    Name of tidal constituents
-       tname(2)   = 'K1'
+       tname(2)   = 'K1'   !              ---
 /
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nambdy
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nambdy	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nambdy	(revision 11954)
@@ -26,5 +26,5 @@
    ln_dyn3d_dmp  =.false.     !  open boundary condition for baroclinic velocities
    rn_time_dmp   =  1.        !  Damping time scale in days
-   rn_time_dmp_out = 1.        !  Outflow damping time scale
+   rn_time_dmp_out = 1.       !  Outflow damping time scale
    nn_rimwidth   = 10         !  width of the relaxation zone
    ln_vol        = .false.    !  total volume correction (see nn_volctl parameter)
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nambdy_dta
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nambdy_dta	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nambdy_dta	(revision 11954)
@@ -11,11 +11,11 @@
    !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
    !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
-   bn_ssh      = 'amm12_bdyT_u2d'        ,         24        , 'sossheig',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
-   bn_u2d      = 'amm12_bdyU_u2d'        ,         24        , 'vobtcrtx',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
-   bn_v2d      = 'amm12_bdyV_u2d'        ,         24        , 'vobtcrty',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
-   bn_u3d      = 'amm12_bdyU_u3d'        ,         24        , 'vozocrtx',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
-   bn_v3d      = 'amm12_bdyV_u3d'        ,         24        , 'vomecrty',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
-   bn_tem      = 'amm12_bdyT_tra'        ,         24        , 'votemper',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
-   bn_sal      = 'amm12_bdyT_tra'        ,         24        , 'vosaline',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
+   bn_ssh      = 'amm12_bdyT_u2d'        ,         24.       , 'sossheig',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
+   bn_u2d      = 'amm12_bdyU_u2d'        ,         24.       , 'vobtcrtx',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
+   bn_v2d      = 'amm12_bdyV_u2d'        ,         24.       , 'vobtcrty',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
+   bn_u3d      = 'amm12_bdyU_u3d'        ,         24.       , 'vozocrtx',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
+   bn_v3d      = 'amm12_bdyV_u3d'        ,         24.       , 'vomecrty',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
+   bn_tem      = 'amm12_bdyT_tra'        ,         24.       , 'votemper',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
+   bn_sal      = 'amm12_bdyT_tra'        ,         24.       , 'vosaline',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
 !* for si3
    bn_a_i      = 'amm12_bdyT_ice'        ,         24.       , 'siconc'  ,    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namberg
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namberg	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namberg	(revision 11954)
@@ -37,4 +37,4 @@
    !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
    !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
-   sn_icb     =  'calving'              ,         -1         ,'calvingmask',  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_icb     =  'calving'              ,         -1.        ,'calvingmask',  .true.   , .true. , 'yearly'  , ''               , ''       , ''
 /
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namc1d_uvd
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namc1d_uvd	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namc1d_uvd	(revision 11954)
@@ -10,5 +10,5 @@
    !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
    !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
-   sn_ucur     = 'ucurrent'              ,         -1        ,'u_current',   .false.   , .true. , 'monthly' ,  ''              ,  'Ume'   , ''
-   sn_vcur     = 'vcurrent'              ,         -1        ,'v_current',   .false.   , .true. , 'monthly' ,  ''              ,  'Vme'   , ''
+   sn_ucur     = 'ucurrent'              ,         -1.       ,'u_current',   .false.   , .true. , 'monthly' ,  ''              ,  'Ume'   , ''
+   sn_vcur     = 'vcurrent'              ,         -1.       ,'v_current',   .false.   , .true. , 'monthly' ,  ''              ,  'Vme'   , ''
 /
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namdia
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namdia	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namdia	(revision 11954)
@@ -2,8 +2,8 @@
 &namdia         !   Diagnostics
 !------------------------------------------------------------------------------
-   ln_icediachk     = .false.         !  check online the heat, mass & salt budgets at each time step
-      !                               !     rate of ice spuriously gained/lost. For ex., rn_icechk=1. <=> 1mm/year, rn_icechk=0.1 <=> 1mm/10years
-      rn_icechk_cel =  1.             !     check at any gridcell           => stops the code if violated (and writes a file)
-      rn_icechk_glo =  0.1            !     check over the entire ice cover => only prints warnings
+   ln_icediachk     = .false.         !  check online heat, mass & salt budgets
+      !                               !   rate of ice spuriously gained/lost at each time step => rn_icechk=1 <=> 1.e-6 m/hour
+      rn_icechk_cel =  100.           !     check at each gridcell          (1.e-4m/h)=> stops the code if violated (and writes a file)
+      rn_icechk_glo =  1.             !     check over the entire ice cover (1.e-6m/h)=> only prints warnings
    ln_icediahsb     = .false.         !  output the heat, mass & salt budgets (T) or not (F)
    ln_icectl        = .false.         !  ice points output for debug (T or F)
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namdta_dyn
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namdta_dyn	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namdta_dyn	(revision 11954)
@@ -10,17 +10,17 @@
    !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
    !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
-   sn_tem      = 'dyna_grid_T'           ,       120         , 'votemper'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
-   sn_sal      = 'dyna_grid_T'           ,       120         , 'vosaline'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
-   sn_mld      = 'dyna_grid_T'           ,       120         , 'somixhgt'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
-   sn_emp      = 'dyna_grid_T'           ,       120         , 'sowaflup'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
-   sn_fmf      = 'dyna_grid_T'           ,       120         , 'iowaflup'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
-   sn_ice      = 'dyna_grid_T'           ,       120         , 'soicecov'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
-   sn_qsr      = 'dyna_grid_T'           ,       120         , 'soshfldo'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
-   sn_wnd      = 'dyna_grid_T'           ,       120         , 'sowindsp'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
-   sn_uwd      = 'dyna_grid_U'           ,       120         , 'uocetr_eff',  .true.   , .true. , 'yearly'  , ''               , ''       , ''
-   sn_vwd      = 'dyna_grid_V'           ,       120         , 'vocetr_eff',  .true.   , .true. , 'yearly'  , ''               , ''       , ''
-   sn_wwd      = 'dyna_grid_W'           ,       120         , 'wocetr_eff',  .true.   , .true. , 'yearly'  , ''               , ''       , ''
-   sn_avt      = 'dyna_grid_W'           ,       120         , 'voddmavs'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
-   sn_ubl      = 'dyna_grid_U'           ,       120         , 'sobblcox'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
-   sn_vbl      = 'dyna_grid_V'           ,       120         , 'sobblcoy'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_tem      = 'dyna_grid_T'           ,       120.        , 'votemper'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_sal      = 'dyna_grid_T'           ,       120.        , 'vosaline'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_mld      = 'dyna_grid_T'           ,       120.        , 'somixhgt'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_emp      = 'dyna_grid_T'           ,       120.        , 'sowaflup'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_fmf      = 'dyna_grid_T'           ,       120.        , 'iowaflup'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_ice      = 'dyna_grid_T'           ,       120.        , 'soicecov'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_qsr      = 'dyna_grid_T'           ,       120.        , 'soshfldo'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_wnd      = 'dyna_grid_T'           ,       120.        , 'sowindsp'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_uwd      = 'dyna_grid_U'           ,       120.        , 'uocetr_eff',  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_vwd      = 'dyna_grid_V'           ,       120.        , 'vocetr_eff',  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_wwd      = 'dyna_grid_W'           ,       120.        , 'wocetr_eff',  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_avt      = 'dyna_grid_W'           ,       120.        , 'voddmavs'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_ubl      = 'dyna_grid_U'           ,       120.        , 'sobblcox'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_vbl      = 'dyna_grid_V'           ,       120.        , 'sobblcoy'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
 /
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namdyn
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namdyn	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namdyn	(revision 11954)
@@ -10,11 +10,8 @@
    rn_ishlat        =   2.            !  lbc : free slip (0) ; partial slip (0-2) ; no slip (2) ; strong slip (>2)
    ln_landfast_L16  = .false.         !  landfast: parameterization from Lemieux 2016
-   ln_landfast_home = .false.         !  landfast: parameterization from "home made"
       rn_depfra     =   0.125         !        fraction of ocean depth that ice must reach to initiate landfast
-                                      !          recommended range: [0.1 ; 0.25] - L16=0.125 - home=0.15
-      rn_icebfr     =  15.            !        ln_landfast_L16:  maximum bottom stress per unit volume [N/m3]
-                                      !        ln_landfast_home: maximum bottom stress per unit area of contact [N/m2]
-                                      !          recommended range: ?? L16=15 - home=10
+                                      !          recommended range: [0.1 ; 0.25]
+      rn_icebfr     =  15.            !        maximum bottom stress per unit volume [N/m3]
       rn_lfrelax    =   1.e-5         !        relaxation time scale to reach static friction [s-1]
-      rn_tensile    =   0.2           !        ln_landfast_L16: isotropic tensile strength
+      rn_tensile    =   0.05          !        isotropic tensile strength [0-0.5??]
 /
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namini
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namini	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namini	(revision 11954)
@@ -23,5 +23,5 @@
    rn_hpd_ini_n     =   0.05          !  initial pond depth          (m), North
    rn_hpd_ini_s     =   0.05          !        "            "             South
-   !        ! if ln_iceini_file=T
+   ! -- for ln_iceini_file = T
    sn_hti = 'Ice_initialization'    , -12 ,'hti'   ,  .false.  , .true., 'yearly'  , '' , '', ''
    sn_hts = 'Ice_initialization'    , -12 ,'hts'   ,  .false.  , .true., 'yearly'  , '' , '', ''
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nammpp
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nammpp	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nammpp	(revision 11954)
@@ -2,6 +2,8 @@
 &nammpp        !   Massively Parallel Processing                        ("key_mpp_mpi")
 !-----------------------------------------------------------------------
+   ln_listonly =  .false.  !  do nothing else than listing the best domain decompositions (with land domains suppression)
+   !                       !  if T: the largest number of cores tested is defined by max(mppsize, jpni*jpnj)
    ln_nnogather =  .true.  !  activate code to avoid mpi_allgather use at the northfold
-   jpni        =   0       !  jpni   number of processors following i (set automatically if < 1)
-   jpnj        =   0       !  jpnj   number of processors following j (set automatically if < 1)
+   jpni        =   0       !  number of processors following i (set automatically if < 1), see also ln_listonly = T
+   jpnj        =   0       !  number of processors following j (set automatically if < 1), see also ln_listonly = T
 /
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namobs
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namobs	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namobs	(revision 11954)
@@ -8,5 +8,5 @@
    ln_sla      = .false.             ! Logical switch for SLA observations
    ln_sst      = .false.             ! Logical switch for SST observations
-   ln_sss      = .false.             ! Logical switch for SSS observations
+   ln_sss      = .false.             ! Logical swithc for SSS observations
    ln_sic      = .false.             ! Logical switch for Sea Ice observations
    ln_vel3d    = .false.             ! Logical switch for velocity observations
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nampisatm
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nampisatm	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nampisatm	(revision 11954)
@@ -4,6 +4,6 @@
 !              !  file name   ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
 !              !              !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
-   sn_patm     = 'presatm'    ,     -1            , 'patm'    ,  .true.      , .true. , 'yearly'  , ''       , ''       , ''
-   sn_atmco2   = 'presatmco2' ,     -1            , 'xco2'    ,  .true.      , .true. , 'yearly'  , ''       , ''       , ''
+   sn_patm     = 'presatm'    ,     -1.           , 'patm'    ,  .true.      , .true. , 'yearly'  , ''       , ''       , ''
+   sn_atmco2   = 'presatmco2' ,     -1.           , 'xco2'    ,  .true.      , .true. , 'yearly'  , ''       , ''       , ''
    cn_dir      = './'     !  root directory for the location of the dynamical files
 !
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nampisopt
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nampisopt	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nampisopt	(revision 11954)
@@ -4,5 +4,5 @@
 !              !  file name       ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
 !              !                  !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
-   sn_par      = 'par.orca'       ,     24            , 'fr_par'  ,  .true.      , .true. , 'yearly'  , ''       , ''       , ''
+   sn_par      = 'par.orca'       ,     24.           , 'fr_par'  ,  .true.      , .true. , 'yearly'  , ''       , ''       , ''
    cn_dir      = './'      !  root directory for the location of the dynamical files
    ln_varpar   =  .true.   ! boolean for PAR variable
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nampissbc
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nampissbc	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/nampissbc	(revision 11954)
@@ -4,16 +4,16 @@
 !              !  file name        ! frequency (hours) ! variable      ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
 !              !                   !  (if <0  months)  !   name        !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
-   sn_dust     = 'dust.orca'       ,     -1            , 'dust'        ,  .true.      , .true. , 'yearly'  , ''       , ''    , ''
-   sn_solub    = 'solubility.orca' ,    -12            , 'solubility1' ,  .false.     , .true. , 'yearly'  , ''       , ''    , ''
-   sn_riverdic = 'river.orca'      ,    120            , 'riverdic'    ,  .true.      , .true. , 'yearly'  , ''       , ''    , ''
-   sn_riverdoc = 'river.orca'      ,    120            , 'riverdoc'    ,  .true.      , .true. , 'yearly'  , ''       , ''    , ''
-   sn_riverdin = 'river.orca'      ,    120            , 'riverdin'    ,  .true.      , .true. , 'yearly'  , ''       , ''    , ''
-   sn_riverdon = 'river.orca'      ,    120            , 'riverdon'    ,  .true.      , .true. , 'yearly'  , ''       , ''    , ''
-   sn_riverdip = 'river.orca'      ,    120            , 'riverdip'    ,  .true.      , .true. , 'yearly'  , ''       , ''    , ''
-   sn_riverdop = 'river.orca'      ,    120            , 'riverdop'    ,  .true.      , .true. , 'yearly'  , ''       , ''    , ''
-   sn_riverdsi = 'river.orca'      ,    120            , 'riverdsi'    ,  .true.      , .true. , 'yearly'  , ''       , ''    , ''
-   sn_ndepo    = 'ndeposition.orca',    -12            , 'ndep'        ,  .false.     , .true. , 'yearly'  , ''       , ''    , ''
-   sn_ironsed  = 'bathy.orca'      ,    -12            , 'bathy'       ,  .false.     , .true. , 'yearly'  , ''       , ''    , ''
-   sn_hydrofe  = 'hydrofe.orca'    ,    -12            , 'epsdb'       ,  .false.     , .true. , 'yearly'  , ''       , ''    , ''
+   sn_dust     = 'dust.orca'       ,     -1.           , 'dust'        ,  .true.      , .true. , 'yearly'  , ''       , ''    , ''
+   sn_solub    = 'solubility.orca' ,    -12.           , 'solubility1' ,  .false.     , .true. , 'yearly'  , ''       , ''    , ''
+   sn_riverdic = 'river.orca'      ,    120.           , 'riverdic'    ,  .true.      , .true. , 'yearly'  , ''       , ''    , ''
+   sn_riverdoc = 'river.orca'      ,    120.           , 'riverdoc'    ,  .true.      , .true. , 'yearly'  , ''       , ''    , ''
+   sn_riverdin = 'river.orca'      ,    120.           , 'riverdin'    ,  .true.      , .true. , 'yearly'  , ''       , ''    , ''
+   sn_riverdon = 'river.orca'      ,    120.           , 'riverdon'    ,  .true.      , .true. , 'yearly'  , ''       , ''    , ''
+   sn_riverdip = 'river.orca'      ,    120.           , 'riverdip'    ,  .true.      , .true. , 'yearly'  , ''       , ''    , ''
+   sn_riverdop = 'river.orca'      ,    120.           , 'riverdop'    ,  .true.      , .true. , 'yearly'  , ''       , ''    , ''
+   sn_riverdsi = 'river.orca'      ,    120.           , 'riverdsi'    ,  .true.      , .true. , 'yearly'  , ''       , ''    , ''
+   sn_ndepo    = 'ndeposition.orca',    -12.           , 'ndep'        ,  .false.     , .true. , 'yearly'  , ''       , ''    , ''
+   sn_ironsed  = 'bathy.orca'      ,    -12.           , 'bathy'       ,  .false.     , .true. , 'yearly'  , ''       , ''    , ''
+   sn_hydrofe  = 'hydrofe.orca'    ,    -12.           , 'epsdb'       ,  .false.     , .true. , 'yearly'  , ''       , ''    , ''
 !
    cn_dir      = './'      !  root directory for the location of the dynamical files
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namrun
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namrun	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namrun	(revision 11954)
@@ -18,12 +18,16 @@
       cn_ocerst_indir = "."         !  directory from which to read input ocean restarts
       cn_ocerst_out   = "restart"   !  suffix of ocean restart name (output)
-      cn_ocerst_outdir = "."         !  directory in which to write output ocean restarts
+      cn_ocerst_outdir = "."        !  directory in which to write output ocean restarts
    ln_iscpl    = .false.   !  cavity evolution forcing or coupling to ice sheet model
    nn_istate   =       0   !  output the initial state (1) or not (0)
    ln_rst_list = .false.   !  output restarts at list of times using nn_stocklist (T) or at set frequency with nn_stock (F)
-   nn_stock    =    5840   !  frequency of creation of a restart file (modulo referenced to 1)
+   nn_stock    =       0   !  used only if ln_rst_list = F: output restart freqeuncy (modulo referenced to 1)
+      !                          !    =  0 force to write restart files only at the end of the run
+      !                          !    = -1 do not do any restart
    nn_stocklist = 0,0,0,0,0,0,0,0,0,0 ! List of timesteps when a restart file is to be written
-   nn_write    =    5840   !  frequency of write in the output file   (modulo referenced to nn_it000)
-   ln_mskland  = .false.   !  mask land points in NetCDF outputs (costly: + ~15%)
+   nn_write    =       0   !  used only if key_iomput is not defined: output frequency (modulo referenced to nn_it000)
+      !                          !    =  0 force to write output files only at the end of the run
+      !                          !    = -1 do not do any output file
+   ln_mskland  = .false.   !  mask land points in NetCDF outputs
    ln_cfmeta   = .false.   !  output additional data to netCDF files required for compliance with the CF metadata standard
    ln_clobber  = .true.    !  clobber (overwrite) an existing file
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_apr
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_apr	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_apr	(revision 11954)
@@ -10,4 +10,4 @@
    !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
    !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
-   sn_apr      = 'patm'                  ,         -1        ,'somslpre' ,   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,      ''
+   sn_apr      = 'patm'                  ,         -1.       ,'somslpre' ,   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,      ''
 /
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_blk
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_blk	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_blk	(revision 11954)
@@ -22,13 +22,13 @@
    !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ !       weights filename               ! rotation ! land/sea mask !
    !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                                      ! pairing  !    filename   !
-   sn_wndi     = 'u_10.15JUNE2009_fill'       ,    6         , 'U_10_MOD',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bicubic_noc.nc'  , 'Uwnd'   , ''
-   sn_wndj     = 'v_10.15JUNE2009_fill'       ,    6         , 'V_10_MOD',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bicubic_noc.nc'  , 'Vwnd'   , ''
-   sn_qsr      = 'ncar_rad.15JUNE2009_fill'   ,   24         , 'SWDN_MOD',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
-   sn_qlw      = 'ncar_rad.15JUNE2009_fill'   ,   24         , 'LWDN_MOD',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
-   sn_tair     = 't_10.15JUNE2009_fill'       ,    6         , 'T_10_MOD',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
-   sn_humi     = 'q_10.15JUNE2009_fill'       ,    6         , 'Q_10_MOD',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
-   sn_prec     = 'ncar_precip.15JUNE2009_fill',   -1         , 'PRC_MOD1',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
-   sn_snow     = 'ncar_precip.15JUNE2009_fill',   -1         , 'SNOW'    ,   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
-   sn_slp      = 'slp.15JUNE2009_fill'        ,    6         , 'SLP'     ,   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
+   sn_wndi     = 'u_10.15JUNE2009_fill'       ,    6.        , 'U_10_MOD',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bicubic_noc.nc'  , 'Uwnd'   , ''
+   sn_wndj     = 'v_10.15JUNE2009_fill'       ,    6.        , 'V_10_MOD',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bicubic_noc.nc'  , 'Vwnd'   , ''
+   sn_qsr      = 'ncar_rad.15JUNE2009_fill'   ,   24.        , 'SWDN_MOD',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
+   sn_qlw      = 'ncar_rad.15JUNE2009_fill'   ,   24.        , 'LWDN_MOD',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
+   sn_tair     = 't_10.15JUNE2009_fill'       ,    6.        , 'T_10_MOD',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
+   sn_humi     = 'q_10.15JUNE2009_fill'       ,    6.        , 'Q_10_MOD',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
+   sn_prec     = 'ncar_precip.15JUNE2009_fill',   -1.        , 'PRC_MOD1',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
+   sn_snow     = 'ncar_precip.15JUNE2009_fill',   -1.        , 'SNOW'    ,   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
+   sn_slp      = 'slp.15JUNE2009_fill'        ,    6.        , 'SLP'     ,   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
    sn_tdif     = 'taudif_core'                ,   24         , 'taudif'  ,   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
 /
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_flx
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_flx	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_flx	(revision 11954)
@@ -6,8 +6,8 @@
    !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
    !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
-   sn_utau     = 'utau'                  ,        24         , 'utau'    , .false.     , .false., 'yearly'  , ''               , ''       , ''
-   sn_vtau     = 'vtau'                  ,        24         , 'vtau'    , .false.     , .false., 'yearly'  , ''               , ''       , ''
-   sn_qtot     = 'qtot'                  ,        24         , 'qtot'    , .false.     , .false., 'yearly'  , ''               , ''       , ''
-   sn_qsr      = 'qsr'                   ,        24         , 'qsr'     , .false.     , .false., 'yearly'  , ''               , ''       , ''
-   sn_emp      = 'emp'                   ,        24         , 'emp'     , .false.     , .false., 'yearly'  , ''               , ''       , ''
+   sn_utau     = 'utau'                  ,        24.        , 'utau'    , .false.     , .false., 'yearly'  , ''               , ''       , ''
+   sn_vtau     = 'vtau'                  ,        24.        , 'vtau'    , .false.     , .false., 'yearly'  , ''               , ''       , ''
+   sn_qtot     = 'qtot'                  ,        24.        , 'qtot'    , .false.     , .false., 'yearly'  , ''               , ''       , ''
+   sn_qsr      = 'qsr'                   ,        24.        , 'qsr'     , .false.     , .false., 'yearly'  , ''               , ''       , ''
+   sn_emp      = 'emp'                   ,        24.        , 'emp'     , .false.     , .false., 'yearly'  , ''               , ''       , ''
 /
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_isf
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_isf	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_isf	(revision 11954)
@@ -24,11 +24,11 @@
    !           !             !  (if <0  months)  !   name    !  (logical)  !  (T/F)  ! 'monthly' ! filename ! pairing  ! filename      !
 !* nn_isf = 4 case
-   sn_fwfisf   = 'rnfisf'    ,         -12       ,'sowflisf' ,  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
+   sn_fwfisf   = 'rnfisf'    ,         -12.      ,'sowflisf' ,  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
 !* nn_isf = 3 case
-   sn_rnfisf   = 'rnfisf'    ,         -12       ,'sofwfisf' ,  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
+   sn_rnfisf   = 'rnfisf'    ,         -12.      ,'sofwfisf' ,  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
 !* nn_isf = 2 and 3 cases 
-   sn_depmax_isf ='rnfisf'    ,         -12       ,'sozisfmax',  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
-   sn_depmin_isf ='rnfisf'    ,         -12       ,'sozisfmin',  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
+   sn_depmax_isf ='rnfisf'   ,         -12.      ,'sozisfmax',  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
+   sn_depmin_isf ='rnfisf'   ,         -12.      ,'sozisfmin',  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
 !* nn_isf = 2 case
-   sn_Leff_isf = 'rnfisf'    ,         -12       ,'Leff'     ,  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
+   sn_Leff_isf = 'rnfisf'    ,         -12.      ,'Leff'     ,  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
 /
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_rnf
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_rnf	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_rnf	(revision 11954)
@@ -18,8 +18,8 @@
    !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
    !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
-   sn_rnf      = 'runoff_core_monthly'   ,        -1         , 'sorunoff',   .true.    , .true. , 'yearly'  , ''               , ''       , ''
-   sn_cnf      = 'runoff_core_monthly'   ,         0         , 'socoefr0',   .false.   , .true. , 'yearly'  , ''               , ''       , ''
-   sn_s_rnf    = 'runoffs'               ,        24         , 'rosaline',   .true.    , .true. , 'yearly'  , ''               , ''       , ''
-   sn_t_rnf    = 'runoffs'               ,        24         , 'rotemper',   .true.    , .true. , 'yearly'  , ''               , ''       , ''
-   sn_dep_rnf  = 'runoffs'               ,         0         , 'rodepth' ,   .false.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_rnf      = 'runoff_core_monthly'   ,        -1.        , 'sorunoff',   .true.    , .true. , 'yearly'  , ''               , ''       , ''
+   sn_cnf      = 'runoff_core_monthly'   ,         0.        , 'socoefr0',   .false.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_s_rnf    = 'runoffs'               ,        24.        , 'rosaline',   .true.    , .true. , 'yearly'  , ''               , ''       , ''
+   sn_t_rnf    = 'runoffs'               ,        24.        , 'rotemper',   .true.    , .true. , 'yearly'  , ''               , ''       , ''
+   sn_dep_rnf  = 'runoffs'               ,         0.        , 'rodepth' ,   .false.   , .true. , 'yearly'  , ''               , ''       , ''
 /
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_sas
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_sas	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_sas	(revision 11954)
@@ -10,10 +10,10 @@
    !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
    !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
-   sn_usp      = 'sas_grid_U'            ,       120         , 'uos'     ,   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
-   sn_vsp      = 'sas_grid_V'            ,       120         , 'vos'     ,   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
-   sn_tem      = 'sas_grid_T'            ,       120         , 'sosstsst',   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
-   sn_sal      = 'sas_grid_T'            ,       120         , 'sosaline',   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
-   sn_ssh      = 'sas_grid_T'            ,       120         , 'sossheig',   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
-   sn_e3t      = 'sas_grid_T'            ,       120         , 'e3t_m'   ,   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
-   sn_frq      = 'sas_grid_T'            ,       120         , 'frq_m'   ,   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
+   sn_usp      = 'sas_grid_U'            ,       120.        , 'uos'     ,   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
+   sn_vsp      = 'sas_grid_V'            ,       120.        , 'vos'     ,   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
+   sn_tem      = 'sas_grid_T'            ,       120.        , 'sosstsst',   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
+   sn_sal      = 'sas_grid_T'            ,       120.        , 'sosaline',   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
+   sn_ssh      = 'sas_grid_T'            ,       120.        , 'sossheig',   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
+   sn_e3t      = 'sas_grid_T'            ,       120.        , 'e3t_m'   ,   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
+   sn_frq      = 'sas_grid_T'            ,       120.        , 'frq_m'   ,   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
 /
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_ssr
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_ssr	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_ssr	(revision 11954)
@@ -14,5 +14,5 @@
    !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
    !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
-   sn_sst      = 'sst_data'              ,        24         ,  'sst'    ,    .false.  , .false., 'yearly'  ,    ''            ,    ''    ,     ''
-   sn_sss      = 'sss_data'              ,        -1         ,  'sss'    ,    .true.   , .true. , 'yearly'  ,    ''            ,    ''    ,     ''
+   sn_sst      = 'sst_data'              ,        24.        ,  'sst'    ,    .false.  , .false., 'yearly'  ,    ''            ,    ''    ,     ''
+   sn_sss      = 'sss_data'              ,        -1.        ,  'sss'    ,    .true.   , .true. , 'yearly'  ,    ''            ,    ''    ,     ''
 /
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_wave
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_wave	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namsbc_wave	(revision 11954)
@@ -6,13 +6,13 @@
    !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
    !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
-   sn_cdg      =  'sdw_ecwaves_orca2'    ,        6          , 'drag_coeff' ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
-   sn_usd      =  'sdw_ecwaves_orca2'    ,        6          , 'u_sd2d'     ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
-   sn_vsd      =  'sdw_ecwaves_orca2'    ,        6          , 'v_sd2d'     ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
-   sn_hsw      =  'sdw_ecwaves_orca2'    ,        6          , 'hs'         ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
-   sn_wmp      =  'sdw_ecwaves_orca2'    ,        6          , 'wmp'        ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
-   sn_wfr      =  'sdw_ecwaves_orca2'    ,        6          , 'wfr'        ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
-   sn_wnum     =  'sdw_ecwaves_orca2'    ,        6          , 'wave_num'   ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
-   sn_tauwoc   =  'sdw_ecwaves_orca2'    ,        6          , 'wave_stress',  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
-   sn_tauwx    =  'sdw_ecwaves_orca2'    ,        6          , 'wave_stress',  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
-   sn_tauwy    =  'sdw_ecwaves_orca2'    ,        6          , 'wave_stress',  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_cdg      =  'sdw_ecwaves_orca2'    ,        6.         , 'drag_coeff' ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_usd      =  'sdw_ecwaves_orca2'    ,        6.         , 'u_sd2d'     ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_vsd      =  'sdw_ecwaves_orca2'    ,        6.         , 'v_sd2d'     ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_hsw      =  'sdw_ecwaves_orca2'    ,        6.         , 'hs'         ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_wmp      =  'sdw_ecwaves_orca2'    ,        6.         , 'wmp'        ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_wfr      =  'sdw_ecwaves_orca2'    ,        6.         , 'wfr'        ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_wnum     =  'sdw_ecwaves_orca2'    ,        6.         , 'wave_num'   ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_tauwoc   =  'sdw_ecwaves_orca2'    ,        6.         , 'wave_stress',  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_tauwx    =  'sdw_ecwaves_orca2'    ,        6.         , 'wave_stress',  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_tauwy    =  'sdw_ecwaves_orca2'    ,        6.         , 'wave_stress',  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
 /
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namtra_qsr
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namtra_qsr	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namtra_qsr	(revision 11954)
@@ -16,4 +16,4 @@
    !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
    !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
-   sn_chl      ='chlorophyll'            ,        -1         , 'CHLA'    ,   .true.    , .true. , 'yearly'  , ''               , ''       , ''
+   sn_chl      ='chlorophyll'            ,        -1.        , 'CHLA'    ,   .true.    , .true. , 'yearly'  , ''               , ''       , ''
 /
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namtrc_dta
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namtrc_dta	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namtrc_dta	(revision 11954)
@@ -4,5 +4,5 @@
 !                !  file name        ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
 !                !                   !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
-   sn_trcdta(1)  = 'data_TRC_nomask' ,        -12        ,  'TRC'    ,    .false.   , .true. , 'yearly'  , ''       , ''       , ''
+   sn_trcdta(1)  = 'data_TRC_nomask' ,        -12.       ,  'TRC'    ,    .false.   , .true. , 'yearly'  , ''       , ''       , ''
    !
    cn_dir        =  './'     !  root directory for the location of the data files
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namtsd
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namtsd	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/namelists/namtsd	(revision 11954)
@@ -10,5 +10,5 @@
    !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
    !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
-   sn_tem = 'data_1m_potential_temperature_nomask',  -1      , 'votemper',   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
-   sn_sal = 'data_1m_salinity_nomask'             ,  -1      , 'vosaline',   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
+   sn_tem = 'data_1m_potential_temperature_nomask',  -1.     , 'votemper',   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
+   sn_sal = 'data_1m_salinity_nomask'             ,  -1.     , 'vosaline',   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
 /
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/Makefile
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/Makefile	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/Makefile	(revision 11954)
@@ -1,3 +1,3 @@
-# Minimal makefile for Sphinx documentation
+# Makefile for Sphinx documentation
 #
 
@@ -5,21 +5,155 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
-SPHINXPROJ    = NEMO
-SOURCEDIR     = source
+PAPER         =
 BUILDDIR      = build
 
-# Put it first so that "make" without argument is like "make help".
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml drafthtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  drafthtml  to make an autoupdate HTML export while editing (todo list included)"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
-.PHONY: help Makefile
+clean:
+	-rm -rf $(BUILDDIR)/*
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+html:
+	$(SPHINXBUILD)   -b html          $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-# Watch source directory and rebuild the documentation when a change is detected
-# Browse to 127.0.0.1:8000/NEMO_guide.html
-htmllive:
-	sphinx-autobuild $(SPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/htmllive
+dirhtml:
+	$(SPHINXBUILD)   -b dirhtml       $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+drafthtml:
+	sphinx-autobuild -b html -t draft $(ALLSPHINXOPTS) $(BUILDDIR)/drafthtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/drafthtml."
+
+singlehtml:
+	$(SPHINXBUILD)   -b singlehtml    $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD)   -b pickle        $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD)   -b json          $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD)   -b htmlhelp      $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD)   -b qthelp        $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/NEMO.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/NEMO.qhc"
+
+devhelp:
+	$(SPHINXBUILD)   -b devhelp       $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/NEMO"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/NEMO"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD)   -b epub          $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD)   -b latex         $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD)   -b latex         $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD)   -b text          $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD)   -b man           $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD)   -b texinfo       $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD)   -b texinfo       $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD)   -b gettext      $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD)   -b changes       $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD)   -b linkcheck     $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD)   -b doctest       $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/README.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/README.rst	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/README.rst	(revision 11954)
@@ -3,5 +3,7 @@
 **********************
 
-| The NEMO guide is made up of several files written in `ReStructuredText <http://docutils.sourceforge.net/rst.html>`_ (`.rst` extension), a WYSIWYG markup language used in the Python community, and scattered all over the NEMO sources.
+| The NEMO guide is made up of several files written in
+  `ReStructuredText <http://docutils.sourceforge.net/rst.html>`_ (`.rst` extension),
+  a WYSIWYG markup language used in the Python community, and scattered all over the NEMO sources.
 | You can view them one by one in plain text from `./source` folder, or export all to a user-friendly guide under `./build` (only HTML format at the moment, PDF expected later).
 
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/NEMO_guide.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/NEMO_guide.rst	(revision 11712)
+++ 	(revision )
@@ -1,70 +1,0 @@
-#################
-Quick Start Guide
-#################
-
-..
-	For headings markup, this convention is recommended from Python’s Style Guide
-	# with overline, for parts
-	* with overline, for chapters
-	=, for sections
-	-, for subsections
-	^, for subsubsections
-	", for paragraphs
-
-	'global.rst' contains a list of common directives (roles, substitutions and URL links)
-	It is loaded for each file thanks to 'rst_epilog' setting in 'conf.py'
-
-.. toctree::
-   :hidden:
-   :caption: Getting started
-
-   install
-   configurations
-   test_cases
-
-.. toctree::
-   :hidden:
-   :caption: Setup your configuration
-
-   setup
-   diagnostics
-   tools
-
-.. toctree::
-   :hidden:
-   :caption: Advanced use
-
-   zooms
-   coupling
-   data_assimilation
-   tracers
-
-.. toctree::
-   :hidden:
-   :caption: Miscellaneous
-
-   contributing
-   release_notes
-   Glossary<definitions>
-
-.. include:: readme.rst
-
-.. Next headings markup acording to readme.rst
-
-References
-==========
-
-.. bibliography:: references.bib
-   :all:
-   :style: unsrt
-   :labelprefix: R
-
-Disclaimer
-==========
-
-The NEMO source code is freely available and distributed under CeCILL license
-(GNU GPL compatible - see ``./LICENSE``).
-
-You can use, modify and/or redistribute the software under its terms,
-but users are provided only with a limited warranty and the software's authors and
-the successive licensor's have only limited liability.
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/_static/style.css
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/_static/style.css	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/_static/style.css	(revision 11954)
@@ -1,5 +1,5 @@
-.rstblue               { color: blue    ; }
-.rstgrey , .rstgreysup { color: grey    ; }
-.rstgreen              { color: seagreen; }
+.blue            { color: blue    ; }
+.grey , .greysup { color: grey    ; }
+.green           { color: seagreen; }
 
 .logo { filter: invert(1) !important; }
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/acro.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/acro.rst	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/acro.rst	(revision 11954)
@@ -0,0 +1,39 @@
+********
+Acronyms
+********
+
+.. todo::
+
+
+
+.. glossary::
+
+   `AGRIF`_
+      *Adaptive Grid Refinement In Fortran*,
+      package for the integration of full adaptive mesh refinement features within
+      an existing multidimensional finite difference model
+
+   SI\ :sup:`3`\
+      *Sea Ice Integrated Initiative*,
+      unified sea ice model merging functionalities from CICE, GELATO and LIM into the NEMO framework
+
+   `OASIS`_
+      *Ocean Atmosphere Sea Ice Soil*,
+      coupling software to synchronise numerical codes representing different components of the climate system
+
+   PISCES
+      *Pelagic Interactions Scheme for Carbon and Ecosystem Studies*,
+      biogeochemical model simulating marine ecosystems, cycles of carbon and the main nutrients
+
+   TAM
+      *Tangent linear and Adjoint Model*,
+      tools to analyse and control the NEMO dynamical core for a wide range of applications such as
+      sensitivity analysis, parameter estimation, vectors computation or data assimilation.
+
+   TOP
+      *Tracers in Ocean Paradigm*,
+      on/off-line oceanic tracers transport and biogeochemistry models
+
+   `XIOS`_
+      *XML Input Output Server*,
+      library dedicated to input/output management of climate code
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/cfgs.bib
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/cfgs.bib	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/cfgs.bib	(revision 11954)
@@ -0,0 +1,25 @@
+@article{ODEA2012,
+author = {E J O’Dea and A K Arnold and K P Edwards and R Furner and P Hyder and M J Martin and J R Siddorn and D Storkey and J While and J T Holt and H Liu},
+title = {An operational ocean forecast system incorporating NEMO and SST data assimilation for the tidally driven European North-West shelf},
+journal = {Journal of Operational Oceanography},
+volume = {5},
+number = {1},
+pages = {3-17},
+year  = {2012},
+publisher = {Taylor & Francis},
+doi = {10.1080/1755876X.2012.11020128},
+URL = {https://doi.org/10.1080/1755876X.2012.11020128},
+eprint = {https://doi.org/10.1080/1755876X.2012.11020128}
+}
+
+@Article{gmd-8-2465-2015,
+AUTHOR = {Aumont, O. and Eth\'e, C. and Tagliabue, A. and Bopp, L. and Gehlen, M.},
+TITLE = {PISCES-v2: an ocean biogeochemical model for carbon and ecosystem studies},
+JOURNAL = {Geoscientific Model Development},
+VOLUME = {8},
+YEAR = {2015},
+NUMBER = {8},
+PAGES = {2465--2513},
+URL = {https://www.geosci-model-dev.net/8/2465/2015/},
+DOI = {10.5194/gmd-8-2465-2015}
+}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/cfgs.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/cfgs.rst	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/cfgs.rst	(revision 11954)
@@ -0,0 +1,1 @@
+link ../../../cfgs/README.rst
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/changes.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/changes.rst	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/changes.rst	(revision 11954)
@@ -0,0 +1,1 @@
+link ../../../CHANGES.rst
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/cite.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/cite.rst	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/cite.rst	(revision 11954)
@@ -0,0 +1,48 @@
+***********
+How to cite
+***********
+
+.. todo::
+
+
+
+|NEMO-OCE|
+   :title:`NEMO ocean engine`,
+   NEMO System Team,
+   Scientific Notes of Climate Modelling Center, 27,
+   ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL),
+   :doi:`10.5281/zenodo.1464816`
+
+.. literalinclude:: ref.bib
+   :language: bibtex
+   :lines:    1-9
+   :caption:  BibTeX source for NEMO manual
+
+|NEMO-ICE|
+   :title:`Sea Ice modelling Integrated Initiative (SI`\ :sup:`3`\ :title:`) --
+   The NEMO sea ice engine`,
+   NEMO Sea Ice Working Group,
+   Scientific Notes of Climate Modelling Center, 31,
+   ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL),
+   :doi:`10.5281/zenodo.1471689`
+
+.. warning::  No official publication yet
+
+.. literalinclude:: ref.bib
+   :language: bibtex
+   :lines:    13-21
+   :caption:  BibTeX source for SI\ :sup:`3` manual
+
+|NEMO-MBG|
+   :title:`Tracer in Ocean Paradigm (TOP) -- The NEMO passive tracer engine`,
+   NEMO TOP Working Group,
+   Scientific Notes of Climate Modelling Center, 28,
+   ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL),
+   :doi:`10.5281/zenodo.1471700`
+
+.. warning::  No official publication yet
+
+.. literalinclude:: ref.bib
+   :language: bibtex
+   :lines:    25-33
+   :caption:  BibTeX source for TOP manual
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/coarsening.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/coarsening.rst	(revision 11712)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../src/OCE/CRS/README.rst
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/conf.py
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/conf.py	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/conf.py	(revision 11954)
@@ -1,48 +1,96 @@
 # -*- coding: utf-8 -*-
 #
-# Configuration file for the Sphinx documentation builder.
-#
-# This file does only contain a selection of the most common options. For a
-# full list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
-
-# -- Project information -----------------------------------------------------
-
-project = 'NEMO'
-author = 'NEMO System Team'
-
-# The short X.Y version
-version = 'trk'
-# The full version, including alpha/beta/rc tags
-release = 'trunk'
-
-
-# -- General configuration ---------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = ['sphinx.ext.extlinks', 'sphinxcontrib.bibtex']
+# NEMO documentation build configuration file, created by
+# sphinx-quickstart on Tue Oct 15 20:13:55 2019.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.extlinks', 'sphinxcontrib.bibtex',
+              'sphinx.ext.todo'    , 'sphinx.ext.autosectionlabel']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
 # The master toctree document.
-master_doc = 'NEMO_guide'
+master_doc = 'guide'
+
+# General information about the project.
+project = u'NEMO'
+copyright = u'2019, NEMO Consortium'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = 'trk'
+# The full version, including alpha/beta/rc tags.
+release = 'trunk'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = ['global.rst', 'coarsening.rst']
+exclude_patterns = ['global.rst', 'readme.rst']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-
-# -- Options for HTML output -------------------------------------------------
+pygments_style = 'emacs'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
 html_theme = 'sphinx_rtd_theme'
 
@@ -50,6 +98,24 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
-#
-html_theme_options = {}
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+html_favicon = '_static/ORCA.ico'
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -58,37 +124,124 @@
 html_static_path = ['_static']
 
-html_favicon = '_static/ORCA.ico'
-
-
-# -- Options for LaTeX output ------------------------------------------------
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'NEMOdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
 
 latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
+# (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-    (master_doc, 'NEMO_guide.tex', 'NEMO Quick Start Guide',
-     'NEMO System Team', 'howto'),
+  ('guide', 'guide.tex', u'NEMO Quick Start Guide',
+   u'NEMO Consortium', 'howto'),
 ]
 
-
-# -- Customisation -----------------------------------------------------------
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('guide', 'nemo', u'NEMO Documentation',
+     [u'NEMO System Team'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('guide', 'NEMO', u'NEMO Documentation',
+   u'NEMO System Team', 'NEMO', 'Community Ocean Model',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# -- Customisation -------------------------------------------------------------
 
 # Timestamping
@@ -99,10 +252,12 @@
 # Link aliases
 extlinks = {
-	'doi'    : ('https://doi.org/%s'                       , None),
-	'forge'  : ('https://forge.ipsl.jussieu.fr/nemo/%s'    , None),
-	'github' : ('https://github.com/%s'                    , None),
-	'xios'   : ('https://forge.ipsl.jussieu.fr/ioserver/%s', None),
-	'website': ('https://www.nemo-ocean.eu/%s'             , None),
-	'zenodo' : ('https://zenodo.org/publication/%s'        , None)
+   'doi'    : ('https://doi.org/%s'                                                    , 'doi:'),
+   'manhtml': ('https://forge.ipsl.jussieu.fr/nemo/chrome/site/doc/NEMO/manual/html/%s', None  ),
+   'forge'  : ('https://forge.ipsl.jussieu.fr/nemo/%s'                                 , None  ),
+   'gmd'    : ('https://www.geosci-model-dev.net/%s'                                   , None  ),
+   'github' : ('https://github.com/NEMO-ocean/%s'                                      , None  ),
+   'xios'   : ('https://forge.ipsl.jussieu.fr/ioserver/%s'                             , None  ),
+   'website': ('https://www.nemo-ocean.eu/%s'                                          , None  ),
+   'zenodo' : ('https://zenodo.org/publication/%s'                                     , None  )
 }
 
@@ -112,4 +267,14 @@
 # SVN revision
 import subprocess
-revision = subprocess.check_output("svnversion").decode("utf-8")
-rst_prolog = '.. |revision| replace:: %s' % revision
+rev = subprocess.check_output("svnversion").decode("utf-8")
+rst_prolog = '.. |revision| replace:: %s' % rev
+
+# 'draft' build tag: DRAFT watermark and TODO list
+if tags.has('draft'):
+   todo_include_todos = True
+   todo_emit_warnings = True
+else:
+   exclude_patterns = ['global.rst', 'readme.rst', 'todos.rst', 'unpub*']
+
+# Default language to highlight set to fortran
+highlight_language = 'fortran'
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/configurations.bib
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/configurations.bib	(revision 11712)
+++ 	(revision )
@@ -1,25 +1,0 @@
-@article{ODEA2012,
-author = {E J O’Dea and A K Arnold and K P Edwards and R Furner and P Hyder and M J Martin and J R Siddorn and D Storkey and J While and J T Holt and H Liu},
-title = {An operational ocean forecast system incorporating NEMO and SST data assimilation for the tidally driven European North-West shelf},
-journal = {Journal of Operational Oceanography},
-volume = {5},
-number = {1},
-pages = {3-17},
-year  = {2012},
-publisher = {Taylor & Francis},
-doi = {10.1080/1755876X.2012.11020128},
-URL = {https://doi.org/10.1080/1755876X.2012.11020128},
-eprint = {https://doi.org/10.1080/1755876X.2012.11020128}
-}
-
-@Article{gmd-8-2465-2015,
-AUTHOR = {Aumont, O. and Eth\'e, C. and Tagliabue, A. and Bopp, L. and Gehlen, M.},
-TITLE = {PISCES-v2: an ocean biogeochemical model for carbon and ecosystem studies},
-JOURNAL = {Geoscientific Model Development},
-VOLUME = {8},
-YEAR = {2015},
-NUMBER = {8},
-PAGES = {2465--2513},
-URL = {https://www.geosci-model-dev.net/8/2465/2015/},
-DOI = {10.5194/gmd-8-2465-2015}
-}
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/configurations.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/configurations.rst	(revision 11712)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../cfgs/README.rst
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/contrib.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/contrib.rst	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/contrib.rst	(revision 11954)
@@ -0,0 +1,1 @@
+link ../../../CONTRIBUTING.rst
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/contributing.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/contributing.rst	(revision 11712)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../CONTRIBUTING.rst
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/coupling.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/coupling.rst	(revision 11712)
+++ 	(revision )
@@ -1,12 +1,0 @@
-********
-Coupling
-********
-
-NEMO currently exploits OASIS-3-MCT (versions 1 to 4) to implement a generalised coupled interface
-(`Coupled Formulation <http://forge.ipsl.jussieu.fr/nemo/doxygen/node50.html?doc=NEMO>`_).
-It can be used to interface with most of the European atmospheric GCM (ARPEGE, ECHAM, ECMWF, Ha- dAM, HadGAM, LMDz), as well as to regional atmospheric models (WRF, COSMO, Meso-NH, AROME).
-To implement the coupling of two independent NEMO components, ocean on one hand and sea-ice plus other surface processes on the other hand
-(`Standalone Surface Module - SAS <http://forge.ipsl.jussieu.fr/nemo/doxygen/node46.html?doc=NEMO>`_).
-
-To enable the OASIS interface the required compilation key is ``key_oasis3``. You must also add ``key_oasis3_v1v2`` if you use OASIS-3-MCT version 1 and 2.
-The parameters to set are in sections ``namsbc_cpl`` and in case of using of SAS also in section ``namsbc_sas``.
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/cplg.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/cplg.rst	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/cplg.rst	(revision 11954)
@@ -0,0 +1,21 @@
+********
+Coupling
+********
+
+.. todo::
+
+   The ‘Coupling’ chapter needs to be enriched
+
+NEMO currently exploits OASIS-3-MCT (versions 1 to 4) to implement a generalised coupled interface
+(:manhtml:`Coupled Formulation <node50.html>`).
+It can be used to interface with most of the European atmospheric GCM
+(ARPEGE, ECHAM, ECMWF, Ha- dAM, HadGAM, LMDz), as well as to regional atmospheric models
+(WRF, COSMO, Meso-NH, AROME).
+To implement the coupling of two independent NEMO components,
+ocean on one hand and sea-ice plus other surface processes on the other hand
+(:manhtml:`Standalone Surface Module - SAS <node46.html>`).
+
+To enable the OASIS interface the required compilation key is ``key_oasis3``.
+You must also add ``key_oasis3_v1v2`` if you use OASIS-3-MCT version 1 and 2.
+The parameters to set are in sections ``&namsbc_cpl`` and
+in case of using of SAS also in section ``&namsbc_sas``.
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/da.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/da.rst	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/da.rst	(revision 11954)
@@ -0,0 +1,68 @@
+*****************
+Data assimilation
+*****************
+
+.. todo::
+
+
+
+.. contents::
+   :local:
+
+The assimilation interface to NEMO is split into three modules.
+
+- ``OBS`` for the observation operator
+- ``ASM`` for the application of increments and model bias correction
+  (based on the assimilation increments).
+- ``TAM`` the tangent linear and adjoint model.
+
+Please see :doc:`NEMO manual <cite>` for more details including
+information about the input file formats and the namelist settings.
+
+Observation and model comparison (``OBS``)
+==========================================
+
+The observation and model comparison code (OBS) reads in observation files
+(profile temperature and salinity, sea surface temperature, sea level anomaly, sea ice concentration,
+and velocity) and calculates an interpolated model equivalent value at
+the observation location and nearest model timestep.
+The resulting data are saved in a feedback file (or files).
+The code was originally developed for use with the NEMOVAR data assimilation code, but
+can be used for validation or verification of model or any other data assimilation system.
+This is all controlled by the namelist.
+To build with the OBS code active ``key_diaobs`` must be set.
+
+More details in :manhtml:`"Observation and Model Comparison (OBS)" chapter <node83.html>`.
+
+Standalone observation operator (``SAO``)
+-----------------------------------------
+
+The OBS code can also be run after a model run using saved NEMO model data.
+This is accomplished using the standalone observation operator (SAO)
+(previously known the offline observation operator).
+
+To build the SAO use :file:`makenemo`.
+This means compiling NEMO once (in the normal way) for the chosen configuration.
+Then include ``SAO`` at the end of the relevant line in :file:`cfg.txt` file.
+Then recompile with the replacement main program in :file:`./src/SAO`.
+This is a special version of :file:`nemogcm.F90` (which doesn't run the model,
+but reads in the model fields, and observations and runs the OBS code.
+See :manhtml:`"Standalone observation operator (SAO)" section <node88.html>`.
+
+Apply assimilation increments (``ASM``)
+=======================================
+
+The ASM code adds the functionality to apply increments to the model variables:
+temperature, salinity, sea surface height, velocity and sea ice concentration.
+These are read into the model from a NetCDF file which
+may be produced by separate data assimilation code.
+The code can also output model background fields which are used as an input to data assimilation code.
+This is all controlled by the namelist ``&nam_asminc``.
+To build the ASM code ``key asminc`` must be set.
+
+More details in :manhtml:`"Apply Assimilation Increments (ASM)" chapter <node89.html>`.
+
+Tangent linear and adjoint (``TAM``)
+====================================
+
+This is the tangent linear and adjoint code of NEMO which is useful to 4D VAR assimilation.
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/data_assimilation.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/data_assimilation.rst	(revision 11712)
+++ 	(revision )
@@ -1,60 +1,0 @@
-*****************
-Data assimilation
-*****************
-
-.. contents::
-   :local:
-
-The assimilation interface to NEMO is split into three modules.
-- OBS for the observation operator
-- ASM for the application of increments and model bias correction (based on the assimilation increments).
-- TAM the tangent linear and adjoint model.
-
-Please see the `NEMO manual`_ for more details including information about the input file formats and
-the namelist settings.
-
-Observation and model comparison (OBS)
-======================================
-
-The observation and model comparison code (OBS) reads in observation files (profile temperature and salinity,
-sea surface temperature, sea level anomaly, sea ice concentration, and velocity) and
-calculates an interpolated model equivalent value at the observation location and nearest model timestep.
-The resulting data are saved in a feedback file (or files).
-The code was originally developed for use with the NEMOVAR data assimilation code, but
-can be used for validation or verification of model or any other data assimilation system.
-This is all controlled by the namelist.
-To build with the OBS code active ``key_diaobs`` must be set. 
-
-More details in the `NEMO manual`_ chapter 12.
-
-Standalone observation operator (SAO)
--------------------------------------
-
-The OBS code can also be run after a model run using saved NEMO model data.
-This is accomplished using the standalone observation operator (SAO)
-(previously known the offline observation operator).
-
-To build the SAO use makenemo.
-This means compiling NEMO once (in the normal way) for the chosen configuration.
-Then include ``SAO`` at the end of the relevant line in ``cfg.txt`` file.
-Then recompile with the replacement main program in ``./src/SAO``.
-This is a special version of ``nemogcm.F90`` (which doesn't run the model, but reads in the model fields, and
-observations and runs the OBS code.
-See section 12.4 of the `NEMO manual`_.
-
-Apply assimilation increments (ASM)
-===================================
-
-The ASM code adds the functionality to apply increments to the model variables:
-temperature, salinity, sea surface height, velocity and sea ice concentration.
-These are read into the model from a NetCDF file which may be produced by separate data assimilation code.
-The code can also output model background fields which are used as an input to data assimilation code.
-This is all controlled by the namelist nam_asminc.
-To build the ASM code ``key asminc`` must be set.
-
-More details in the `NEMO manual`_ chapter 13.
-
-Tangent linear and adjoint (TAM)
-================================
-
-This is the tangent linear and adjoint code of NEMO which is useful to 4D VAR assimilation.
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/definitions.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/definitions.rst	(revision 11712)
+++ 	(revision )
@@ -1,33 +1,0 @@
-***********
-Definitions
-***********
-
-`AGRIF`_
-	*Adaptive Grid Refinement In Fortran*, 
-	package for the integration of full adaptive mesh refinement features within 
-	an existing multidimensional finite difference model
-
-SI\ :sup:`3`\ 
-	*Sea Ice Integrated Initiative*, 
-	unified sea ice model merging functionalities from CICE, GELATO and LIM into the NEMO framework
-
-`OASIS`_
-	*Ocean Atmosphere Sea Ice Soil*, 
-	coupling software to synchronise numerical codes representing different components of the climate system
-
-PISCES
-	*Pelagic Interactions Scheme for Carbon and Ecosystem Studies*, 
-	biogeochemical model simulating marine ecosystems, cycles of carbon and the main nutrients
-
-TAM
-	*Tangent linear and Adjoint Model*, 
-	tools to analyse and control the NEMO dynamical core for a wide range of applications such as
-	sensitivity analysis, parameter estimation, vectors computation or data assimilation.
-
-TOP
-	*Tracers in Ocean Paradigm*, 
-	on/off-line oceanic tracers transport and biogeochemistry models
-
-`XIOS`_
-	*XML Input Output Server*, 
-	library dedicated to input/output management of climate code
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/diagnostics.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/diagnostics.rst	(revision 11712)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../cfgs/SHARED/README.rst
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/diags.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/diags.rst	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/diags.rst	(revision 11954)
@@ -0,0 +1,1 @@
+link ../../../cfgs/SHARED/README.rst
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/docutils.conf
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/docutils.conf	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/docutils.conf	(revision 11954)
@@ -0,0 +1,2 @@
+[restructuredtext parser]
+syntax_highlight = short
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/global.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/global.rst	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/global.rst	(revision 11954)
@@ -1,39 +1,79 @@
-.. Roles (custom styles related to CSS classes in 'source/_static/style.css')
+.. Roles
 
-.. role:: rstblue
-.. role:: rstgreen
-.. role:: rstgrey
-.. role:: rstgreysup(sup)
-.. role:: underline 
-   :class: underline
+.. custom styles related to CSS classes in './_static/style.css'
+
+.. role:: blue
+.. role:: green
+.. role:: grey
+.. role:: greysup(sup)
+
+.. inline code snippets
+
+.. role:: python(code)
+   :language: python
+   :class: highlight
+
+.. role:: fortran(code)
+   :language: fortran
+   :class: highlight
+
+.. role:: console(code)
+   :language: console
+   :class: highlight
 
 .. Substitutions
 
-.. |OPA| replace:: :rstblue:`NEMO-OPA`
-.. |SI3| replace:: :rstgrey:`NEMO-SI`\ :rstgreysup:`3`
-.. |TOP| replace:: :rstgreen:`NEMO-TOP/PISCES`
+.. |NEMO-OCE| replace::  :blue:`NEMO-OCE (Ocean dynamics)`
+.. |OCE|      replace::  :blue:`NEMO-OCE`
+.. |NEMO-ICE| replace::  :grey:`NEMO-SI`\ :greysup:`3`  :grey:`(Sea Ice)`
+.. |ICE|      replace::  :grey:`NEMO-SI`\ :greysup:`3`
+.. |NEMO-MBG| replace:: :green:`NEMO-TOP/PISCES (Tracers)`
+.. |MBG|      replace:: :green:`NEMO-TOP/PISCES`
 
-.. Institutes
+.. External links
 
-.. _CMCC:           https://www.cmcc.it 
-.. _CNRS:           https://www.cnrs.fr
-.. _Mercator Ocean: https://www.mercator-ocean.fr
-.. _Met Office:     https://www.metoffice.gov.uk
-.. _MOI:            https://www.mercator-ocean.fr
-.. _NERC:           https://nerc.ukri.org
+   .. Consortium institutes
 
-.. Models / Softwares
+.. _CMCC:       https://www.cmcc.it
+.. _CNRS:       https://www.cnrs.fr
+.. _Met Office: https://www.metoffice.gov.uk
+.. _MOI:        https://www.mercator-ocean.fr
+.. _NERC:       https://nerc.ukri.org
+
+   .. Models / Libraries / Dependencies
 
 .. _AGRIF:  http://agrif.imag.fr
-.. _FCM:    https://metomi.github.io/fcm/doc/
+.. _BFM:    http://www.bfm-community.eu
+.. _FCM:    https://metomi.github.io/fcm
 .. _IOIPSL: https://forge.ipsl.jussieu.fr/igcmg/browser/IOIPSL
+.. _NEMO:   https://www.nemo-ocean.eu
 .. _OASIS:  https://portal.enes.org/oasis
+.. _XIOS:   https://forge.ipsl.jussieu.fr/ioserver
 
-.. NEMO
+   .. Misc.
 
-.. _NEMO:          https://www.nemo-ocean.eu
-.. _NEMO strategy: https://doi.org/10.5281/zenodo.1471663
-.. _NEMO guide:    :samp: https://doi.org/10.5281/zenodo.1475325
-.. _NEMO manual:   https://doi.org/10.5281/zenodo.1464816
-.. _SI3 manual:    :samp: https://doi.org/10.5281/zenodo.1471689
-.. _TOP manual:    :samp: https://doi.org/10.5281/zenodo.1471700
+.. _EGU: http://www.egu.eu
+.. _Special Issue: https://www.geosci-model-dev.net/special_issue40.html
+.. _BFM man: https://cmcc-foundation.github.io/www.bfm-community.eu/files/bfm-nemo-manual_r1.0_201508.pdf
+.. _RST man: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
+.. _PAPA station: http://www.pmel.noaa.gov/OCS/Papa/index-Papa.shtml
+.. _ISOMIP: http://staff.acecrc.org.au/~bkgalton/ISOMIP/test_cavities.pdf
+
+.. DOI
+
+   .. Publications (`:samp:` to deactivate link for unpublished documents)
+
+.. _DOI man OCE:          https://doi.org/10.5281/zenodo.1464816
+.. _DOI man ICE:   :samp: https://doi.org/10.5281/zenodo.1471689
+.. _DOI man MBG:   :samp: https://doi.org/10.5281/zenodo.1471700
+.. _DOI qsg:       :samp: https://doi.org/10.5281/zenodo.1475325
+.. _DOI dev  stgy:        https://doi.org/10.5281/zenodo.1471663
+.. _DOI data:             https://doi.org/10.5281/zenodo.1472245
+
+   .. Badges (same labels as previously, substitution to link images)
+
+.. |DOI man OCE| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1464816.svg
+.. |DOI man ICE| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1471689.svg
+.. |DOI man MBG| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1471700.svg
+.. |DOI qsg|     image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1475325.svg
+.. |DOI data|    image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1472245.svg
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/guide.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/guide.rst	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/guide.rst	(revision 11954)
@@ -0,0 +1,76 @@
+#################
+Quick Start Guide
+#################
+
+.. For headings markup, this convention is recommended from Python’s Style Guide
+   # with overline, for parts
+   * with overline, for chapters
+   =, for sections
+   -, for subsections
+   ^, for subsubsections
+   ", for paragraphs
+
+   'global.rst' contains a list of roles, substitutions and URL links for the guide.
+   It is loaded for each file with the 'rst_epilog' setting in 'conf.py'
+
+.. toctree::
+   :hidden:
+
+   todos
+
+.. Only displayed with 'make drafthtml'
+
+.. toctree::
+   :hidden:
+   :caption: Unpublished READMEs
+   :glob:
+   :titlesonly:
+
+   unpub/*
+
+.. Only displayed with 'make drafthtml'
+
+.. toctree::
+   :hidden:
+   :caption: Getting started
+
+   install
+   cfgs
+   tests
+
+.. toctree::
+   :hidden:
+   :caption: Setup your configuration
+
+   setup
+   diags
+   tools
+
+.. toctree::
+   :hidden:
+   :caption: Advanced use
+
+   zooms
+   cplg
+   da
+   tracers
+
+.. toctree::
+   :hidden:
+   :caption: Miscellaneous
+
+   cite
+   contrib
+   changes
+   acro
+
+:Release:  |release|
+
+.. only:: draft
+
+   .. Only on draft
+
+   :*Date*:     |today|
+   :*SVN rev*:  |revision|
+
+.. include:: readme.rst
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/ref.bib
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/ref.bib	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/ref.bib	(revision 11954)
@@ -0,0 +1,1 @@
+link ../../../REFERENCES.bib
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/references.bib
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/references.bib	(revision 11712)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../REFERENCES.bib
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/release_notes.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/release_notes.rst	(revision 11712)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../RELEASE_NOTES.rst
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/setup.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/setup.rst	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/setup.rst	(revision 11954)
@@ -1,249 +1,1 @@
-******************************
-Setting up a new configuration
-******************************
-
-.. contents::
-
-Starting from an existing configuration
-=======================================
-
-There are three options to build a new configuration from an existing one:
-
-Option 1: Duplicate an existing configuration
----------------------------------------------
-
-The NEMO so-called Reference Configurations cover a number of major features for NEMO setup
-(global, regional, 1D, using embeded zoom with AGRIF...)
-
-One can create a new configuration by duplicating one of the reference configurations
-(``ORCA2_ICE_PISCES`` in the following example)
-
-.. code-block:: sh
-
-	makenemo –n 'ORCA2_ICE_PISCES_MINE' -r 'ORCA2_ICE_PISCES'
-
-Option 2: Duplicate with differences
-------------------------------------
-
-Create and compile a new configuration based on a reference configuration
-(``ORCA2_ICE_PISCES`` in the following example) but with different pre-processor options.
-For this either add ``add_key`` or ``del_key`` keys as required; e.g.
-
-.. code-block:: sh
-
-	makenemo –n 'ORCA2_ICE_PISCES_MINE' -r 'ORCA2_ICE_PISCES' del_key 'key_iomput' add_key 'key_diahth'
-
-Option 3: Use the SIREN tools to subset an existing model
----------------------------------------------------------
-
-Define a regional configuration which is a sub- or super-set of an existing configuration.
-
-This last option employs the SIREN software tools that are included in the standard distribution.
-The software is written in Fortran 95 and available in the ``./tools/SIREN`` directory.
-SIREN allows you to create your own regional configuration embedded in a wider one.
-
-SIREN is a set of programs to create all the input files you need to run a NEMO regional configuration.
-As a basic demonstrator, a set of GLORYS files (GLObal ReanalYSis on the ORCA025 grid),
-as well as examples of namelists are available `here`_.
-
-`SIREN documentation`_
-
-Any questions or comments regarding the use of SIREN should be posted in `the corresponding forum`_.
-
-Creating a completely new configuration
-=======================================
-
-From NEMO version 4.0 there are two ways to build configurations from scratch.
-The appropriate method to use depends largely on the target configuration.
-Method 1 is for more complex/realistic global or regional configurations and
-method 2 is intended for simpler, idealised configurations whose
-domains and characteristics can be described in simple geometries and formulae.
-
-Option 1: Create and use a domain configuration file
-----------------------------------------------------
-
-This method is used by each of the reference configurations,
-so that downloading their input files linked to their description can help.
-Although starting from scratch, it is advisable to create the directory structure to house your new configuration by
-duplicating the closest reference configuration to your target application.
-For example, if your application requires both ocean ice and passive tracers,
-then use the ``ORCA2_ICE_PISCES`` as template,
-and execute following command to build your ``MY_NEW_CONFIG`` configuration:
-
-.. code-block:: sh
-
-	makenemo –n 'MY_NEW_CONFIG' -r 'ORCA2_ICE_PISCES'
-
-where ``MY_NEW_CONFIG`` can be substituted with a suitably descriptive name for your new configuration.  
-
-The purpose of this step is simply to create and populate the appropriate ``WORK``, ``MY_SRC`` and
-``EXP00`` subdirectories for your new configuration.
-Other choices for the base reference configuration might be
-
-- ``GYRE``  - If your target application is ocean-only
-- ``AMM12`` - If your target application is regional with open boundaries
-
-All the domain information for your new configuration will be contained within
-a netcdf file called ``domain_cfg.nc`` which you will need to create and
-place in the ``./cfgs/MY_NEW_CONFIG/EXP00`` sub-directory.
-Firstly though, ensure that your configuration is set to use such a file by checking that
-
-.. code-block:: fortran
-
-	ln_read_cfg = .true.
-
-in	``./cfgs/MY_NEW_CONFIG/EXP00/namelist_cfg``
-
-Create the domain_cfg.nc file which must contain the following fields
-
-.. code-block:: c++
-
-	int    ORCA, ORCA_index                  /* configuration name, configuration resolution                 */
-	int    jpiglo, jpjglo, jpkglo            /* global domain sizes                                          */
-	int    jperio                            /* lateral global domain b.c.                                   */
-	int    ln_zco, ln_zps, ln_sco            /* flags for z-coord, z-coord with partial steps and s-coord    */
-	int    ln_isfcav                         /* flag  for ice shelf cavities                                 */
-	double glamt, glamu, glamv, glamf        /* geographic position                                          */
-	double gphit, gphiu, gphiv, gphif        /* geographic position                                          */
-	double iff, ff_f, ff_t                   /* Coriolis parameter (if not on the sphere)                    */
-	double e1t, e1u, e1v, e1f                /* horizontal scale factors                                     */
-	double e2t, e2u, e2v, e2f                /* horizontal scale factors                                     */
-	double ie1e2u_v, e1e2u, e1e2v            /* U and V surfaces (if grid size reduction in some straits)    */
-	double e3t_1d, e3w_1d                    /* reference vertical scale factors at T and W points           */
-	double e3t_0, e3u_0, e3v_0, e3f_0, e3w_0 /* vertical scale factors 3D coordinate at T,U,V,F and W points */
-	double e3uw_0, e3vw_0                    /* vertical scale factors 3D coordinate at UW and VW points     */
-	int    bottom_level, top_level           /* last wet T-points, 1st wet T-points (for ice shelf cavities) */
-
-There are two options for creating a domain_cfg.nc file:
-
-- Users can use tools of their own choice to build a ``domain_cfg.nc`` with all mandatory fields.
-- Users can adapt and apply the supplied tool available in ``./tools/DOMAINcfg``.
-  This tool is based on code extracted from NEMO version 3.6 and will allow similar choices for
-  the horizontal and vertical grids that were available internally to that version.
-  See ``./tools/DOMAINcfg/README`` for details.
-
-Option 2: Adapt the usr_def configuration module of NEMO for you own purposes
------------------------------------------------------------------------------
-
-This method is intended for configuring easily simple/idealised configurations which
-are often used as demonstrators or for process evaluation and comparison.
-This method can be used whenever the domain geometry has a simple mathematical description and
-the ocean initial state and boundary forcing is described analytically. 
-As a start, consider the case of starting a completely new ocean-only test case based on
-the ``LOCK_EXCHANGE`` example.
-.. [Note: we probably need an even more basic example than this with only one namelist and
-minimal changes to the usrdef modules]
-
-Firstly, construct the directory structure, starting in the ``cfgs`` directory:
-
-.. code-block:: sh
-
-	./makenemo -n 'MY_NEW_TEST' -t 'LOCK_EXCHANGE'
-
-where the ``-t`` option has been used to locate the new configuration in the ``tests`` subdirectory
-(it is recommended practice to keep full configurations and idealised cases clearly distinguishable).
-This command will create (amongst others) the following files and directories::
-
-	./tests/MY_NEW_TEST:
-	BLD	  MY_SRC cpp_MY_NEW_TEST.fcm
-	EXP00   WORK
-	#
-	./tests/MY_NEW_TEST/EXP00:
-	context_nemo.xml       domain_def_nemo.xml
-	field_def_nemo-opa.xml file_def_nemo-opa.xml
-	iodef.xml
-	namelist_cfg
-	namelist_ref
-	#
-	./tests/MY_NEW_TEST/MY_SRC:
-	usrdef_hgr.F90    usrdef_nam.F90 usrdef_zgr.F90
-	usrdef_istate.F90 usrdef_sbc.F90 zdfini.F90
-
-The key to setting up an idealised configuration lies in adapting a small set of short Fortran 90 modules which
-should be dropped into the ``MY_SRC`` directory.
-Here the ``LOCK_EXCHANGE`` example is using 5 such routines but the full set that is available in
-the ``src/OCE/USR`` directory is::
-
-	./src/OCE/USR:
-	usrdef_closea.F90 usrdef_istate.F90 usrdef_zgr.F90
-	usrdef_fmask.F90  usrdef_nam.F90
-	usrdef_hgr.F90    usrdef_sbc.F90
-
-Before discussing these in more detail it is worth noting the various namelist controls that
-engage the different user-defined aspects.
-These controls are set using two new logical switches or are implied by the settings of existing ones.
-For example, the mandatory requirement for an idealised configuration is to provide routines which
-define the horizontal and vertical domains.
-Templates for these are provided in the ``usrdef_hgr.F90`` and ``usrdef_zgr.F90`` modules.
-The application of these modules is activated whenever:
-
-.. code-block:: fortran
-
-	ln_read_cfg = .false.
-
-in any configuration's ``namelist_cfg`` file.
-This setting also activates the reading of an optional ``nam_usrdef`` namelist which can be used to
-supply configuration specific settings.
-These need to be declared and read in the ``usrdef_nam.F90`` module.
-
-Another explicit control is available in the ``namsbc`` namelist which activates the use of analytical forcing.
-With
-
-.. code-block:: fortran
-
-	ln_usr = .true.
-
-Other usrdef modules are activated by less explicit means.
-For example, code in ``usrdef_istate.F90`` is used to define initial temperature and salinity fields if
-
-.. code-block:: fortran
-
-	ln_tsd_init   = .false.
-
-in the ``namtsd`` namelist.
-The remaining modules, namely::
-
-	usrdef_closea.F90 usrdef_fmask.F90
-
-are specific to ORCA configurations and set local variations of some specific fields for
-the various resolutions of the global models.
-They do not need to be considered here in the context of idealised cases but it is worth noting that all
-configuration specific code has now been isolated in the usrdef modules.
-In the case of these last two modules, they are activated only if an ORCA configuration is detected.
-Currently, this requires a specific integer variable named ``ORCA`` to be set in a ``domain_cfg.nc`` file.
-.. [Note: this would be less confusing if the cn_cfg string is read directly as a character attribue from
-the ``domain_cfg.nc`` ]
-
-So, in most cases, the set up of idealised model configurations can be completed by
-copying the template routines from ``./src/OCE/USR`` into
-your new ``./cfgs/MY_NEW_TEST/MY_SRC`` directory and editing the appropriate modules as needed.
-The default set are those used for the GYRE reference configuration.
-The contents of ``MY_SRC`` directories from other idealised configurations may provide more convenient templates if
-they share common characteristics with your target application.
-
-Whatever the starting point, it should not require too many changes or additional lines of code to
-produce routines in ``./src/OCE/USR`` that define analytically the domain,
-the initial state and the surface boundary conditions for your new configuration.
-
-To summarize, the base set of modules is:
-
-- ``usrdef_hgr.F90``   : define horizontal grid
-- ``usrdef_zgr.F90``   : define vertical grid
-- ``usrdef_sbc.F90``   : provides at each time-step the surface boundary condition, i.e. the momentum, heat and freshwater fluxes
-- ``usrdef_istate.F90``: defines initialization of the dynamics and tracers
-- ``usrdef_nam.F90``   : configuration-specific namelist processing to set any associated run-time parameters
-
-with two specialised ORCA modules
-(not related to idealised configurations but used to isolate configuration specific code that is used in
-ORCA2 reference configurations and established global configurations using the ORCA tripolar grid):
-
-- ``usrdef_fmask.F90`` : only used in ORCA CONFIGURATIONS for alteration of f-point land/ocean mask in some straits
-- ``usrdef_closea.F90``: only used in ORCA CONFIGURATIONS for specific treatments associated with closed seas
-
-From version 4.0, the NEMO release includes a ``tests`` subdirectory containing available and
-up to date test cases build by the community.
-These will not be fully supported as are NEMO reference configurations, but should provide a source of raw material.
-
-.. _here:                     http://prodn.idris.fr/thredds/catalog/ipsl_public/rron463/catalog.html?dataset=DatasetScanipsl_public/rron463/INPUT_SIREN.tar
-.. _the corresponding forum:  http://forge.ipsl.jussieu.fr/nemo/discussion/forum/2
-.. _SIREN documentation:      http://forge.ipsl.jussieu.fr/nemo/doxygen/index.html
+link ../../../src/OCE/USR/README.rst
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/test_cases.bib
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/test_cases.bib	(revision 11712)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../tests/test_cases.bib
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/test_cases.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/test_cases.rst	(revision 11712)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../tests/README.rst
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/tests.bib
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/tests.bib	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/tests.bib	(revision 11954)
@@ -0,0 +1,1 @@
+link ../../../tests/test_cases.bib
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/tests.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/tests.rst	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/tests.rst	(revision 11954)
@@ -0,0 +1,1 @@
+link ../../../tests/README.rst
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/todos.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/todos.rst	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/todos.rst	(revision 11954)
@@ -0,0 +1,5 @@
+*********************
+List of editing tasks
+*********************
+
+.. todolist::
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/unpub/crs.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/unpub/crs.rst	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/unpub/crs.rst	(revision 11954)
@@ -0,0 +1,1 @@
+link ../../../../src/OCE/CRS/README.rst
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/unpub/doc.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/unpub/doc.rst	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/unpub/doc.rst	(revision 11954)
@@ -0,0 +1,1 @@
+link ../../../README.rst
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/unpub/src.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/unpub/src.rst	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/doc/rst/source/unpub/src.rst	(revision 11954)
@@ -0,0 +1,1 @@
+link ../../../../src/README.rst
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/ICE/ice.F90
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/ICE/ice.F90	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/ICE/ice.F90	(revision 11954)
@@ -328,12 +328,12 @@
    REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:,:) ::   sz_i     !: ice salinity          [PSS]
 
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   a_ip       !: melt pond fraction per grid cell area
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   a_ip       !: melt pond concentration
    REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   v_ip       !: melt pond volume per grid cell area      [m]
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   a_ip_frac  !: melt pond volume per ice area
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   h_ip       !: melt pond thickness                      [m]
-
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:)   ::   at_ip      !: total melt pond fraction
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   a_ip_frac  !: melt pond fraction (a_ip/a_i)
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   h_ip       !: melt pond depth                          [m]
+
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:)   ::   at_ip      !: total melt pond concentration
    REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:)   ::   hm_ip      !: mean melt pond depth                     [m]
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:)   ::   vt_ip      !: total melt pond volume per unit area     [m]
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:)   ::   vt_ip      !: total melt pond volume per gridcell area [m]
 
    !!----------------------------------------------------------------------
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/ICE/icedyn_adv_pra.F90
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/ICE/icedyn_adv_pra.F90	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/ICE/icedyn_adv_pra.F90	(revision 11954)
@@ -16,4 +16,5 @@
    !!   adv_pra_rst     : read/write Prather field in ice restart file, or initialized to zero
    !!----------------------------------------------------------------------
+   USE phycst         ! physical constant
    USE dom_oce        ! ocean domain
    USE ice            ! sea-ice variables
@@ -36,8 +37,7 @@
    REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:)   ::   sxice, syice, sxxice, syyice, sxyice   ! ice thickness 
    REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:)   ::   sxsn , sysn , sxxsn , syysn , sxysn    ! snow thickness
-   REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:)   ::   sxa  , sya  , sxxa  , syya  , sxya     ! lead fraction
+   REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:)   ::   sxa  , sya  , sxxa  , syya  , sxya     ! ice concentration
    REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:)   ::   sxsal, sysal, sxxsal, syysal, sxysal   ! ice salinity
    REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:)   ::   sxage, syage, sxxage, syyage, sxyage   ! ice age
-   REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:)   ::   sxopw, syopw, sxxopw, syyopw, sxyopw   ! open water in sea ice
    REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:,:) ::   sxc0 , syc0 , sxxc0 , syyc0 , sxyc0    ! snow layers heat content
    REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:,:) ::   sxe  , sye  , sxxe  , syye  , sxye     ! ice layers heat content
@@ -81,10 +81,11 @@
       REAL(wp), DIMENSION(:,:,:,:), INTENT(inout) ::   pe_i       ! ice heat content
       !
-      INTEGER  ::   jk, jl, jt              ! dummy loop indices
+      INTEGER  ::   ji,jj, jk, jl, jt       ! dummy loop indices
       INTEGER  ::   icycle                  ! number of sub-timestep for the advection
       REAL(wp) ::   zdt                     !   -      -
       REAL(wp), DIMENSION(1)                  ::   zcflprv, zcflnow   ! for global communication
+      REAL(wp), DIMENSION(jpi,jpj)            ::   zati1, zati2
+      REAL(wp), DIMENSION(jpi,jpj)            ::   zudy, zvdx
       REAL(wp), DIMENSION(jpi,jpj,jpl)        ::   zarea
-      REAL(wp), DIMENSION(jpi,jpj,1)          ::   z0opw
       REAL(wp), DIMENSION(jpi,jpj,jpl)        ::   z0ice, z0snw, z0ai, z0smi, z0oi
       REAL(wp), DIMENSION(jpi,jpj,jpl)        ::   z0ap , z0vp
@@ -109,127 +110,138 @@
       zdt = rdt_ice / REAL(icycle)
       
-      !-------------------------
-      ! transported fields                                        
-      !-------------------------
-      z0opw(:,:,1) = pato_i(:,:) * e1e2t(:,:)              ! Open water area 
-      DO jl = 1, jpl
-         zarea(:,:,jl) = e1e2t(:,:)
-         z0snw(:,:,jl) = pv_s (:,:,jl) * e1e2t(:,:)        ! Snow volume
-         z0ice(:,:,jl) = pv_i (:,:,jl) * e1e2t(:,:)        ! Ice  volume
-         z0ai (:,:,jl) = pa_i (:,:,jl) * e1e2t(:,:)        ! Ice area
-         z0smi(:,:,jl) = psv_i(:,:,jl) * e1e2t(:,:)        ! Salt content
-         z0oi (:,:,jl) = poa_i(:,:,jl) * e1e2t(:,:)        ! Age content
-         DO jk = 1, nlay_s
-            z0es(:,:,jk,jl) = pe_s(:,:,jk,jl) * e1e2t(:,:) ! Snow heat content
-         END DO
-         DO jk = 1, nlay_i
-            z0ei(:,:,jk,jl) = pe_i(:,:,jk,jl) * e1e2t(:,:) ! Ice  heat content
-         END DO
-         IF ( ln_pnd_H12 ) THEN
-            z0ap(:,:,jl)  = pa_ip(:,:,jl) * e1e2t(:,:)     ! Melt pond fraction
-            z0vp(:,:,jl)  = pv_ip(:,:,jl) * e1e2t(:,:)     ! Melt pond volume
-         ENDIF
-      END DO
-
-      !                                                    !--------------------------------------------!
-      IF( MOD( ( kt - 1) / nn_fsbc , 2 ) == 0 ) THEN       !==  odd ice time step:  adv_x then adv_y  ==!
-         !                                                 !--------------------------------------------!
-         DO jt = 1, icycle
-            CALL adv_x( zdt , pu_ice , 1._wp , zarea , z0opw , sxopw , sxxopw , syopw , syyopw , sxyopw ) !--- open water
-            CALL adv_y( zdt , pv_ice , 0._wp , zarea , z0opw , sxopw , sxxopw , syopw , syyopw , sxyopw )
-            CALL adv_x( zdt , pu_ice , 1._wp , zarea , z0ice , sxice , sxxice , syice , syyice , sxyice ) !--- ice volume
-            CALL adv_y( zdt , pv_ice , 0._wp , zarea , z0ice , sxice , sxxice , syice , syyice , sxyice )
-            CALL adv_x( zdt , pu_ice , 1._wp , zarea , z0snw , sxsn  , sxxsn  , sysn  , syysn  , sxysn  ) !--- snow volume
-            CALL adv_y( zdt , pv_ice , 0._wp , zarea , z0snw , sxsn  , sxxsn  , sysn  , syysn  , sxysn  )
-            CALL adv_x( zdt , pu_ice , 1._wp , zarea , z0smi , sxsal , sxxsal , sysal , syysal , sxysal ) !--- ice salinity
-            CALL adv_y( zdt , pv_ice , 0._wp , zarea , z0smi , sxsal , sxxsal , sysal , syysal , sxysal )
-            CALL adv_x( zdt , pu_ice , 1._wp , zarea , z0ai  , sxa   , sxxa   , sya   , syya   , sxya   ) !--- ice concentration
-            CALL adv_y( zdt , pv_ice , 0._wp , zarea , z0ai  , sxa   , sxxa   , sya   , syya   , sxya   )
-            CALL adv_x( zdt , pu_ice , 1._wp , zarea , z0oi  , sxage , sxxage , syage , syyage , sxyage ) !--- ice age
-            CALL adv_y( zdt , pv_ice , 0._wp , zarea , z0oi  , sxage , sxxage , syage , syyage , sxyage )
+      ! --- transport --- !
+      zudy(:,:) = pu_ice(:,:) * e2u(:,:)
+      zvdx(:,:) = pv_ice(:,:) * e1v(:,:)
+
+      DO jt = 1, icycle
+
+         ! record at_i before advection (for open water)
+         zati1(:,:) = SUM( pa_i(:,:,:), dim=3 )
+         
+         ! --- transported fields --- !                                        
+         DO jl = 1, jpl
+            zarea(:,:,jl) = e1e2t(:,:)
+            z0snw(:,:,jl) = pv_s (:,:,jl) * e1e2t(:,:)        ! Snow volume
+            z0ice(:,:,jl) = pv_i (:,:,jl) * e1e2t(:,:)        ! Ice  volume
+            z0ai (:,:,jl) = pa_i (:,:,jl) * e1e2t(:,:)        ! Ice area
+            z0smi(:,:,jl) = psv_i(:,:,jl) * e1e2t(:,:)        ! Salt content
+            z0oi (:,:,jl) = poa_i(:,:,jl) * e1e2t(:,:)        ! Age content
+            DO jk = 1, nlay_s
+               z0es(:,:,jk,jl) = pe_s(:,:,jk,jl) * e1e2t(:,:) ! Snow heat content
+            END DO
+            DO jk = 1, nlay_i
+               z0ei(:,:,jk,jl) = pe_i(:,:,jk,jl) * e1e2t(:,:) ! Ice  heat content
+            END DO
+            IF ( ln_pnd_H12 ) THEN
+               z0ap(:,:,jl)  = pa_ip(:,:,jl) * e1e2t(:,:)     ! Melt pond fraction
+               z0vp(:,:,jl)  = pv_ip(:,:,jl) * e1e2t(:,:)     ! Melt pond volume
+            ENDIF
+         END DO
+         !
+         !                                                                  !--------------------------------------------!
+         IF( MOD( (kt - 1) / nn_fsbc , 2 ) ==  MOD( (jt - 1) , 2 ) ) THEN   !==  odd ice time step:  adv_x then adv_y  ==!
+            !                                                               !--------------------------------------------!
+            CALL adv_x( zdt , zudy , 1._wp , zarea , z0ice , sxice , sxxice , syice , syyice , sxyice ) !--- ice volume
+            CALL adv_y( zdt , zvdx , 0._wp , zarea , z0ice , sxice , sxxice , syice , syyice , sxyice )
+            CALL adv_x( zdt , zudy , 1._wp , zarea , z0snw , sxsn  , sxxsn  , sysn  , syysn  , sxysn  ) !--- snow volume
+            CALL adv_y( zdt , zvdx , 0._wp , zarea , z0snw , sxsn  , sxxsn  , sysn  , syysn  , sxysn  )
+            CALL adv_x( zdt , zudy , 1._wp , zarea , z0smi , sxsal , sxxsal , sysal , syysal , sxysal ) !--- ice salinity
+            CALL adv_y( zdt , zvdx , 0._wp , zarea , z0smi , sxsal , sxxsal , sysal , syysal , sxysal )
+            CALL adv_x( zdt , zudy , 1._wp , zarea , z0ai  , sxa   , sxxa   , sya   , syya   , sxya   ) !--- ice concentration
+            CALL adv_y( zdt , zvdx , 0._wp , zarea , z0ai  , sxa   , sxxa   , sya   , syya   , sxya   )
+            CALL adv_x( zdt , zudy , 1._wp , zarea , z0oi  , sxage , sxxage , syage , syyage , sxyage ) !--- ice age
+            CALL adv_y( zdt , zvdx , 0._wp , zarea , z0oi  , sxage , sxxage , syage , syyage , sxyage )
             !
-            DO jk = 1, nlay_s                                                                             !--- snow heat content
-               CALL adv_x( zdt, pu_ice, 1._wp, zarea, z0es (:,:,jk,:), sxc0(:,:,jk,:),   &
-                  &                                   sxxc0(:,:,jk,:), syc0(:,:,jk,:), syyc0(:,:,jk,:), sxyc0(:,:,jk,:) )
-               CALL adv_y( zdt, pv_ice, 0._wp, zarea, z0es (:,:,jk,:), sxc0(:,:,jk,:),   &
-                  &                                   sxxc0(:,:,jk,:), syc0(:,:,jk,:), syyc0(:,:,jk,:), sxyc0(:,:,jk,:) )
-            END DO
-            DO jk = 1, nlay_i                                                                             !--- ice heat content
-               CALL adv_x( zdt, pu_ice, 1._wp, zarea, z0ei(:,:,jk,:), sxe(:,:,jk,:),   & 
-                  &                                   sxxe(:,:,jk,:), sye(:,:,jk,:), syye(:,:,jk,:), sxye(:,:,jk,:) )
-               CALL adv_y( zdt, pv_ice, 0._wp, zarea, z0ei(:,:,jk,:), sxe(:,:,jk,:),   & 
-                  &                                   sxxe(:,:,jk,:), sye(:,:,jk,:), syye(:,:,jk,:), sxye(:,:,jk,:) )
+            DO jk = 1, nlay_s                                                                           !--- snow heat content
+               CALL adv_x( zdt, zudy, 1._wp, zarea, z0es (:,:,jk,:), sxc0(:,:,jk,:),   &
+                  &                                 sxxc0(:,:,jk,:), syc0(:,:,jk,:), syyc0(:,:,jk,:), sxyc0(:,:,jk,:) )
+               CALL adv_y( zdt, zvdx, 0._wp, zarea, z0es (:,:,jk,:), sxc0(:,:,jk,:),   &
+                  &                                 sxxc0(:,:,jk,:), syc0(:,:,jk,:), syyc0(:,:,jk,:), sxyc0(:,:,jk,:) )
+            END DO
+            DO jk = 1, nlay_i                                                                           !--- ice heat content
+               CALL adv_x( zdt, zudy, 1._wp, zarea, z0ei(:,:,jk,:), sxe(:,:,jk,:),   & 
+                  &                                 sxxe(:,:,jk,:), sye(:,:,jk,:), syye(:,:,jk,:), sxye(:,:,jk,:) )
+               CALL adv_y( zdt, zvdx, 0._wp, zarea, z0ei(:,:,jk,:), sxe(:,:,jk,:),   & 
+                  &                                 sxxe(:,:,jk,:), sye(:,:,jk,:), syye(:,:,jk,:), sxye(:,:,jk,:) )
             END DO
             !
             IF ( ln_pnd_H12 ) THEN
-               CALL adv_x( zdt , pu_ice , 1._wp , zarea , z0ap , sxap , sxxap , syap , syyap , sxyap )    !--- melt pond fraction
-               CALL adv_y( zdt , pv_ice , 0._wp , zarea , z0ap , sxap , sxxap , syap , syyap , sxyap ) 
-               CALL adv_x( zdt , pu_ice , 1._wp , zarea , z0vp , sxvp , sxxvp , syvp , syyvp , sxyvp )    !--- melt pond volume
-               CALL adv_y( zdt , pv_ice , 0._wp , zarea , z0vp , sxvp , sxxvp , syvp , syyvp , sxyvp ) 
+               CALL adv_x( zdt , zudy , 1._wp , zarea , z0ap , sxap , sxxap , syap , syyap , sxyap )    !--- melt pond fraction
+               CALL adv_y( zdt , zvdx , 0._wp , zarea , z0ap , sxap , sxxap , syap , syyap , sxyap ) 
+               CALL adv_x( zdt , zudy , 1._wp , zarea , z0vp , sxvp , sxxvp , syvp , syyvp , sxyvp )    !--- melt pond volume
+               CALL adv_y( zdt , zvdx , 0._wp , zarea , z0vp , sxvp , sxxvp , syvp , syyvp , sxyvp ) 
             ENDIF
-         END DO
-      !                                                    !--------------------------------------------!
-      ELSE                                                 !== even ice time step:  adv_y then adv_x  ==!
-         !                                                 !--------------------------------------------!
-         DO jt = 1, icycle
-            CALL adv_y( zdt , pv_ice , 1._wp , zarea , z0opw , sxopw , sxxopw , syopw , syyopw , sxyopw ) !--- open water
-            CALL adv_x( zdt , pu_ice , 0._wp , zarea , z0opw , sxopw , sxxopw , syopw , syyopw , sxyopw )
-            CALL adv_y( zdt , pv_ice , 1._wp , zarea , z0ice , sxice , sxxice , syice , syyice , sxyice ) !--- ice volume
-            CALL adv_x( zdt , pu_ice , 0._wp , zarea , z0ice , sxice , sxxice , syice , syyice , sxyice )
-            CALL adv_y( zdt , pv_ice , 1._wp , zarea , z0snw , sxsn  , sxxsn  , sysn  , syysn  , sxysn  ) !--- snow volume
-            CALL adv_x( zdt , pu_ice , 0._wp , zarea , z0snw , sxsn  , sxxsn  , sysn  , syysn  , sxysn  )
-            CALL adv_y( zdt , pv_ice , 1._wp , zarea , z0smi , sxsal , sxxsal , sysal , syysal , sxysal ) !--- ice salinity
-            CALL adv_x( zdt , pu_ice , 0._wp , zarea , z0smi , sxsal , sxxsal , sysal , syysal , sxysal )
-            CALL adv_y( zdt , pv_ice , 1._wp , zarea , z0ai  , sxa   , sxxa   , sya   , syya   , sxya   ) !--- ice concentration
-            CALL adv_x( zdt , pu_ice , 0._wp , zarea , z0ai  , sxa   , sxxa   , sya   , syya   , sxya   )
-            CALL adv_y( zdt , pv_ice , 1._wp , zarea , z0oi  , sxage , sxxage , syage , syyage , sxyage ) !--- ice age
-            CALL adv_x( zdt , pu_ice , 0._wp , zarea , z0oi  , sxage , sxxage , syage , syyage , sxyage )
-            DO jk = 1, nlay_s                                                                             !--- snow heat content
-               CALL adv_y( zdt, pv_ice, 1._wp, zarea, z0es (:,:,jk,:), sxc0(:,:,jk,:),   &
-                  &                                   sxxc0(:,:,jk,:), syc0(:,:,jk,:), syyc0(:,:,jk,:), sxyc0(:,:,jk,:) )
-               CALL adv_x( zdt, pu_ice, 0._wp, zarea, z0es (:,:,jk,:), sxc0(:,:,jk,:),   &
-                  &                                   sxxc0(:,:,jk,:), syc0(:,:,jk,:), syyc0(:,:,jk,:), sxyc0(:,:,jk,:) )
-            END DO
-            DO jk = 1, nlay_i                                                                             !--- ice heat content
-               CALL adv_y( zdt, pv_ice, 1._wp, zarea, z0ei(:,:,jk,:), sxe(:,:,jk,:),   & 
-                  &                                   sxxe(:,:,jk,:), sye(:,:,jk,:), syye(:,:,jk,:), sxye(:,:,jk,:) )
-               CALL adv_x( zdt, pu_ice, 0._wp, zarea, z0ei(:,:,jk,:), sxe(:,:,jk,:),   & 
-                  &                                   sxxe(:,:,jk,:), sye(:,:,jk,:), syye(:,:,jk,:), sxye(:,:,jk,:) )
+            !                                                               !--------------------------------------------!
+         ELSE                                                               !== even ice time step:  adv_y then adv_x  ==!
+            !                                                               !--------------------------------------------!
+            CALL adv_y( zdt , zvdx , 1._wp , zarea , z0ice , sxice , sxxice , syice , syyice , sxyice ) !--- ice volume
+            CALL adv_x( zdt , zudy , 0._wp , zarea , z0ice , sxice , sxxice , syice , syyice , sxyice )
+            CALL adv_y( zdt , zvdx , 1._wp , zarea , z0snw , sxsn  , sxxsn  , sysn  , syysn  , sxysn  ) !--- snow volume
+            CALL adv_x( zdt , zudy , 0._wp , zarea , z0snw , sxsn  , sxxsn  , sysn  , syysn  , sxysn  )
+            CALL adv_y( zdt , zvdx , 1._wp , zarea , z0smi , sxsal , sxxsal , sysal , syysal , sxysal ) !--- ice salinity
+            CALL adv_x( zdt , zudy , 0._wp , zarea , z0smi , sxsal , sxxsal , sysal , syysal , sxysal )
+            CALL adv_y( zdt , zvdx , 1._wp , zarea , z0ai  , sxa   , sxxa   , sya   , syya   , sxya   ) !--- ice concentration
+            CALL adv_x( zdt , zudy , 0._wp , zarea , z0ai  , sxa   , sxxa   , sya   , syya   , sxya   )
+            CALL adv_y( zdt , zvdx , 1._wp , zarea , z0oi  , sxage , sxxage , syage , syyage , sxyage ) !--- ice age
+            CALL adv_x( zdt , zudy , 0._wp , zarea , z0oi  , sxage , sxxage , syage , syyage , sxyage )
+            DO jk = 1, nlay_s                                                                           !--- snow heat content
+               CALL adv_y( zdt, zvdx, 1._wp, zarea, z0es (:,:,jk,:), sxc0(:,:,jk,:),   &
+                  &                                 sxxc0(:,:,jk,:), syc0(:,:,jk,:), syyc0(:,:,jk,:), sxyc0(:,:,jk,:) )
+               CALL adv_x( zdt, zudy, 0._wp, zarea, z0es (:,:,jk,:), sxc0(:,:,jk,:),   &
+                  &                                 sxxc0(:,:,jk,:), syc0(:,:,jk,:), syyc0(:,:,jk,:), sxyc0(:,:,jk,:) )
+            END DO
+            DO jk = 1, nlay_i                                                                           !--- ice heat content
+               CALL adv_y( zdt, zvdx, 1._wp, zarea, z0ei(:,:,jk,:), sxe(:,:,jk,:),   & 
+                  &                                 sxxe(:,:,jk,:), sye(:,:,jk,:), syye(:,:,jk,:), sxye(:,:,jk,:) )
+               CALL adv_x( zdt, zudy, 0._wp, zarea, z0ei(:,:,jk,:), sxe(:,:,jk,:),   & 
+                  &                                 sxxe(:,:,jk,:), sye(:,:,jk,:), syye(:,:,jk,:), sxye(:,:,jk,:) )
             END DO
             IF ( ln_pnd_H12 ) THEN
-               CALL adv_y( zdt , pv_ice , 1._wp , zarea , z0ap , sxap , sxxap , syap , syyap , sxyap )    !--- melt pond fraction
-               CALL adv_x( zdt , pu_ice , 0._wp , zarea , z0ap , sxap , sxxap , syap , syyap , sxyap )
-               CALL adv_y( zdt , pv_ice , 1._wp , zarea , z0vp , sxvp , sxxvp , syvp , syyvp , sxyvp )    !--- melt pond volume
-               CALL adv_x( zdt , pu_ice , 0._wp , zarea , z0vp , sxvp , sxxvp , syvp , syyvp , sxyvp )
+               CALL adv_y( zdt , zvdx , 1._wp , zarea , z0ap , sxap , sxxap , syap , syyap , sxyap )    !--- melt pond fraction
+               CALL adv_x( zdt , zudy , 0._wp , zarea , z0ap , sxap , sxxap , syap , syyap , sxyap )
+               CALL adv_y( zdt , zvdx , 1._wp , zarea , z0vp , sxvp , sxxvp , syvp , syyvp , sxyvp )    !--- melt pond volume
+               CALL adv_x( zdt , zudy , 0._wp , zarea , z0vp , sxvp , sxxvp , syvp , syyvp , sxyvp )
             ENDIF
-         END DO
-      ENDIF
-
-      !-------------------------------------------
-      ! Recover the properties from their contents
-      !-------------------------------------------
-      pato_i(:,:) = z0opw(:,:,1) * r1_e1e2t(:,:) * tmask(:,:,1)
-      DO jl = 1, jpl
-         pv_i (:,:,jl) = z0ice(:,:,jl) * r1_e1e2t(:,:) * tmask(:,:,1)
-         pv_s (:,:,jl) = z0snw(:,:,jl) * r1_e1e2t(:,:) * tmask(:,:,1)
-         psv_i(:,:,jl) = z0smi(:,:,jl) * r1_e1e2t(:,:) * tmask(:,:,1)
-         poa_i(:,:,jl) = z0oi (:,:,jl) * r1_e1e2t(:,:) * tmask(:,:,1)
-         pa_i (:,:,jl) = z0ai (:,:,jl) * r1_e1e2t(:,:) * tmask(:,:,1)
-         DO jk = 1, nlay_s
-            pe_s(:,:,jk,jl) = z0es(:,:,jk,jl) * r1_e1e2t(:,:) * tmask(:,:,1)
-         END DO
-         DO jk = 1, nlay_i
-            pe_i(:,:,jk,jl) = z0ei(:,:,jk,jl) * r1_e1e2t(:,:) * tmask(:,:,1)
-         END DO
-         IF ( ln_pnd_H12 ) THEN
-            pa_ip(:,:,jl) = z0ap(:,:,jl) * r1_e1e2t(:,:) * tmask(:,:,1)
-            pv_ip(:,:,jl) = z0vp(:,:,jl) * r1_e1e2t(:,:) * tmask(:,:,1)
+            !
          ENDIF
+
+         ! --- Recover the properties from their contents --- !
+         DO jl = 1, jpl
+            pv_i (:,:,jl) = z0ice(:,:,jl) * r1_e1e2t(:,:) * tmask(:,:,1)
+            pv_s (:,:,jl) = z0snw(:,:,jl) * r1_e1e2t(:,:) * tmask(:,:,1)
+            psv_i(:,:,jl) = z0smi(:,:,jl) * r1_e1e2t(:,:) * tmask(:,:,1)
+            poa_i(:,:,jl) = z0oi (:,:,jl) * r1_e1e2t(:,:) * tmask(:,:,1)
+            pa_i (:,:,jl) = z0ai (:,:,jl) * r1_e1e2t(:,:) * tmask(:,:,1)
+            DO jk = 1, nlay_s
+               pe_s(:,:,jk,jl) = z0es(:,:,jk,jl) * r1_e1e2t(:,:) * tmask(:,:,1)
+            END DO
+            DO jk = 1, nlay_i
+               pe_i(:,:,jk,jl) = z0ei(:,:,jk,jl) * r1_e1e2t(:,:) * tmask(:,:,1)
+            END DO
+            IF ( ln_pnd_H12 ) THEN
+               pa_ip(:,:,jl) = z0ap(:,:,jl) * r1_e1e2t(:,:) * tmask(:,:,1)
+               pv_ip(:,:,jl) = z0vp(:,:,jl) * r1_e1e2t(:,:) * tmask(:,:,1)
+            ENDIF
+         END DO
+         !
+         ! derive open water from ice concentration
+         zati2(:,:) = SUM( pa_i(:,:,:), dim=3 )
+         DO jj = 2, jpjm1
+            DO ji = fs_2, fs_jpim1
+               pato_i(ji,jj) = pato_i(ji,jj) - ( zati2(ji,jj) - zati1(ji,jj) ) &                        !--- open water
+                  &                          - ( zudy(ji,jj) - zudy(ji-1,jj) + zvdx(ji,jj) - zvdx(ji,jj-1) ) * r1_e1e2t(ji,jj) * zdt
+            END DO
+         END DO
+         CALL lbc_lnk( 'icedyn_adv_pra', pato_i, 'T',  1. )
+         !
+         ! --- Ensure non-negative fields --- !
+         !     Remove negative values (conservation is ensured)
+         !     (because advected fields are not perfectly bounded and tiny negative values can occur, e.g. -1.e-20)
+         CALL ice_var_zapneg( zdt, pato_i, pv_i, pv_s, psv_i, poa_i, pa_i, pa_ip, pv_ip, pe_s, pe_i )
+         !
+         ! --- Ensure snow load is not too big --- !
+         CALL Hsnow( zdt, pv_i, pv_s, pa_i, pa_ip, pe_s )
+         !
       END DO
-      !
-      ! --- Ensure non-negative fields --- !
-      ! Remove negative values (conservation is ensured)
-      !    (because advected fields are not perfectly bounded and tiny negative values can occur, e.g. -1.e-20)
-      CALL ice_var_zapneg( zdt, pato_i, pv_i, pv_s, psv_i, poa_i, pa_i, pa_ip, pv_ip, pe_s, pe_i )
       !
       IF( lrst_ice )   CALL adv_pra_rst( 'WRITE', kt )   !* write Prather fields in the restart file
@@ -293,5 +305,5 @@
             DO ji = 1, jpi
                zbet(ji,jj)  =  MAX( 0._wp, SIGN( 1._wp, put(ji,jj) ) )
-               zalf         =  MAX( 0._wp, put(ji,jj) ) * pdt * e2u(ji,jj) / psm(ji,jj,jl)
+               zalf         =  MAX( 0._wp, put(ji,jj) ) * pdt / psm(ji,jj,jl)
                zalfq        =  zalf * zalf
                zalf1        =  1.0 - zalf
@@ -319,5 +331,5 @@
          DO jj = 2, jpjm1                      !  Flux from i+1 to i when u LT 0.
             DO ji = 1, fs_jpim1
-               zalf          = MAX( 0._wp, -put(ji,jj) ) * pdt * e2u(ji,jj) / psm(ji+1,jj,jl) 
+               zalf          = MAX( 0._wp, -put(ji,jj) ) * pdt / psm(ji+1,jj,jl) 
                zalg  (ji,jj) = zalf
                zalfq         = zalf * zalf
@@ -462,5 +474,5 @@
             DO ji = fs_2, fs_jpim1
                zbet(ji,jj)  =  MAX( 0._wp, SIGN( 1._wp, pvt(ji,jj) ) )
-               zalf         =  MAX( 0._wp, pvt(ji,jj) ) * pdt * e1v(ji,jj) / psm(ji,jj,jl)
+               zalf         =  MAX( 0._wp, pvt(ji,jj) ) * pdt / psm(ji,jj,jl)
                zalfq        =  zalf * zalf
                zalf1        =  1.0 - zalf
@@ -488,5 +500,5 @@
          DO jj = 1, jpjm1                   !  Flux from j+1 to j when v LT 0.
             DO ji = fs_2, fs_jpim1
-               zalf          = ( MAX(0._wp, -pvt(ji,jj) ) * pdt * e1v(ji,jj) ) / psm(ji,jj+1,jl) 
+               zalf          = MAX( 0._wp, -pvt(ji,jj) ) * pdt / psm(ji,jj+1,jl) 
                zalg  (ji,jj) = zalf
                zalfq         = zalf * zalf
@@ -578,4 +590,58 @@
 
 
+   SUBROUTINE Hsnow( pdt, pv_i, pv_s, pa_i, pa_ip, pe_s )
+      !!-------------------------------------------------------------------
+      !!                  ***  ROUTINE Hsnow  ***
+      !!
+      !! ** Purpose : 1- Check snow load after advection
+      !!              2- Correct pond concentration to avoid a_ip > a_i
+      !!
+      !! ** Method :  If snow load makes snow-ice interface to deplet below the ocean surface
+      !!              then put the snow excess in the ocean
+      !!
+      !! ** Notes :   This correction is crucial because of the call to routine icecor afterwards
+      !!              which imposes a mini of ice thick. (rn_himin). This imposed mini can artificially
+      !!              make the snow very thick (if concentration decreases drastically)
+      !!              This behavior has been seen in Ultimate-Macho and supposedly it can also be true for Prather
+      !!-------------------------------------------------------------------
+      REAL(wp)                    , INTENT(in   ) ::   pdt   ! tracer time-step
+      REAL(wp), DIMENSION(:,:,:)  , INTENT(inout) ::   pv_i, pv_s, pa_i, pa_ip
+      REAL(wp), DIMENSION(:,:,:,:), INTENT(inout) ::   pe_s
+      !
+      INTEGER  ::   ji, jj, jl   ! dummy loop indices
+      REAL(wp) ::   z1_dt, zvs_excess, zfra
+      !!-------------------------------------------------------------------
+      !
+      z1_dt = 1._wp / pdt
+      !
+      ! -- check snow load -- !
+      DO jl = 1, jpl
+         DO jj = 1, jpj
+            DO ji = 1, jpi
+               IF ( pv_i(ji,jj,jl) > 0._wp ) THEN
+                  !
+                  zvs_excess = MAX( 0._wp, pv_s(ji,jj,jl) - pv_i(ji,jj,jl) * (rau0-rhoi) * r1_rhos )
+                  !
+                  IF( zvs_excess > 0._wp ) THEN   ! snow-ice interface deplets below the ocean surface
+                     ! put snow excess in the ocean
+                     zfra = ( pv_s(ji,jj,jl) - zvs_excess ) / MAX( pv_s(ji,jj,jl), epsi20 )
+                     wfx_res(ji,jj) = wfx_res(ji,jj) + zvs_excess * rhos * z1_dt
+                     hfx_res(ji,jj) = hfx_res(ji,jj) - SUM( pe_s(ji,jj,1:nlay_s,jl) ) * ( 1._wp - zfra ) * z1_dt ! W.m-2 <0
+                     ! correct snow volume and heat content
+                     pe_s(ji,jj,1:nlay_s,jl) = pe_s(ji,jj,1:nlay_s,jl) * zfra
+                     pv_s(ji,jj,jl)          = pv_s(ji,jj,jl) - zvs_excess
+                  ENDIF
+                  !
+               ENDIF
+            END DO
+         END DO
+      END DO
+      !
+      !-- correct pond concentration to avoid a_ip > a_i -- !
+      WHERE( pa_ip(:,:,:) > pa_i(:,:,:) )   pa_ip(:,:,:) = pa_i(:,:,:)
+      !
+   END SUBROUTINE Hsnow
+
+
    SUBROUTINE adv_pra_init
       !!-------------------------------------------------------------------
@@ -588,6 +654,5 @@
       !
       !                             !* allocate prather fields
-      ALLOCATE( sxopw(jpi,jpj,1)   , syopw(jpi,jpj,1)   , sxxopw(jpi,jpj,1)   , syyopw(jpi,jpj,1)   , sxyopw(jpi,jpj,1)   ,   &
-         &      sxice(jpi,jpj,jpl) , syice(jpi,jpj,jpl) , sxxice(jpi,jpj,jpl) , syyice(jpi,jpj,jpl) , sxyice(jpi,jpj,jpl) ,   &
+      ALLOCATE( sxice(jpi,jpj,jpl) , syice(jpi,jpj,jpl) , sxxice(jpi,jpj,jpl) , syyice(jpi,jpj,jpl) , sxyice(jpi,jpj,jpl) ,   &
          &      sxsn (jpi,jpj,jpl) , sysn (jpi,jpj,jpl) , sxxsn (jpi,jpj,jpl) , syysn (jpi,jpj,jpl) , sxysn (jpi,jpj,jpl) ,   &
          &      sxa  (jpi,jpj,jpl) , sya  (jpi,jpj,jpl) , sxxa  (jpi,jpj,jpl) , syya  (jpi,jpj,jpl) , sxya  (jpi,jpj,jpl) ,   &
@@ -635,5 +700,5 @@
          !                                   !==========================!
          !
-         IF( ln_rstart ) THEN   ;   id1 = iom_varid( numrir, 'sxopw' , ldstop = .FALSE. )    ! file exist: id1>0
+         IF( ln_rstart ) THEN   ;   id1 = iom_varid( numrir, 'sxice' , ldstop = .FALSE. )    ! file exist: id1>0
          ELSE                   ;   id1 = 0                                                  ! no restart: id1=0
          ENDIF
@@ -653,5 +718,5 @@
             CALL iom_get( numrir, jpdom_autoglo, 'syysn' , syysn  )
             CALL iom_get( numrir, jpdom_autoglo, 'sxysn' , sxysn  )
-            !                                                        ! lead fraction
+            !                                                        ! ice concentration
             CALL iom_get( numrir, jpdom_autoglo, 'sxa'   , sxa    )
             CALL iom_get( numrir, jpdom_autoglo, 'sya'   , sya    )
@@ -671,10 +736,4 @@
             CALL iom_get( numrir, jpdom_autoglo, 'syyage', syyage )
             CALL iom_get( numrir, jpdom_autoglo, 'sxyage', sxyage )
-            !                                                        ! open water in sea ice
-            CALL iom_get( numrir, jpdom_autoglo, 'sxopw' , sxopw  )
-            CALL iom_get( numrir, jpdom_autoglo, 'syopw' , syopw  )
-            CALL iom_get( numrir, jpdom_autoglo, 'sxxopw', sxxopw )
-            CALL iom_get( numrir, jpdom_autoglo, 'syyopw', syyopw )
-            CALL iom_get( numrir, jpdom_autoglo, 'sxyopw', sxyopw )
             !                                                        ! snow layers heat content
             DO jk = 1, nlay_s
@@ -716,8 +775,7 @@
             sxice = 0._wp   ;   syice = 0._wp   ;   sxxice = 0._wp   ;   syyice = 0._wp   ;   sxyice = 0._wp      ! ice thickness
             sxsn  = 0._wp   ;   sysn  = 0._wp   ;   sxxsn  = 0._wp   ;   syysn  = 0._wp   ;   sxysn  = 0._wp      ! snow thickness
-            sxa   = 0._wp   ;   sya   = 0._wp   ;   sxxa   = 0._wp   ;   syya   = 0._wp   ;   sxya   = 0._wp      ! lead fraction
+            sxa   = 0._wp   ;   sya   = 0._wp   ;   sxxa   = 0._wp   ;   syya   = 0._wp   ;   sxya   = 0._wp      ! ice concentration
             sxsal = 0._wp   ;   sysal = 0._wp   ;   sxxsal = 0._wp   ;   syysal = 0._wp   ;   sxysal = 0._wp      ! ice salinity
             sxage = 0._wp   ;   syage = 0._wp   ;   sxxage = 0._wp   ;   syyage = 0._wp   ;   sxyage = 0._wp      ! ice age
-            sxopw = 0._wp   ;   syopw = 0._wp   ;   sxxopw = 0._wp   ;   syyopw = 0._wp   ;   sxyopw = 0._wp      ! open water in sea ice
             sxc0  = 0._wp   ;   syc0  = 0._wp   ;   sxxc0  = 0._wp   ;   syyc0  = 0._wp   ;   sxyc0  = 0._wp      ! snow layers heat content
             sxe   = 0._wp   ;   sye   = 0._wp   ;   sxxe   = 0._wp   ;   syye   = 0._wp   ;   sxye   = 0._wp      ! ice layers heat content
@@ -750,5 +808,5 @@
          CALL iom_rstput( iter, nitrst, numriw, 'syysn' , syysn  )
          CALL iom_rstput( iter, nitrst, numriw, 'sxysn' , sxysn  )
-         !                                                           ! lead fraction
+         !                                                           ! ice concentration
          CALL iom_rstput( iter, nitrst, numriw, 'sxa'   , sxa    )
          CALL iom_rstput( iter, nitrst, numriw, 'sya'   , sya    )
@@ -768,10 +826,4 @@
          CALL iom_rstput( iter, nitrst, numriw, 'syyage', syyage )
          CALL iom_rstput( iter, nitrst, numriw, 'sxyage', sxyage )
-         !                                                           ! open water in sea ice
-         CALL iom_rstput( iter, nitrst, numriw, 'sxopw' , sxopw  )
-         CALL iom_rstput( iter, nitrst, numriw, 'syopw' , syopw  )
-         CALL iom_rstput( iter, nitrst, numriw, 'sxxopw', sxxopw )
-         CALL iom_rstput( iter, nitrst, numriw, 'syyopw', syyopw )
-         CALL iom_rstput( iter, nitrst, numriw, 'sxyopw', sxyopw )
          !                                                           ! snow layers heat content
          DO jk = 1, nlay_s
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/ICE/icedyn_adv_umx.F90
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/ICE/icedyn_adv_umx.F90	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/ICE/icedyn_adv_umx.F90	(revision 11954)
@@ -83,5 +83,5 @@
       REAL(wp), DIMENSION(:,:,:)  , INTENT(inout) ::   poa_i      ! age content
       REAL(wp), DIMENSION(:,:,:)  , INTENT(inout) ::   pa_i       ! ice concentration
-      REAL(wp), DIMENSION(:,:,:)  , INTENT(inout) ::   pa_ip      ! melt pond fraction
+      REAL(wp), DIMENSION(:,:,:)  , INTENT(inout) ::   pa_ip      ! melt pond concentration
       REAL(wp), DIMENSION(:,:,:)  , INTENT(inout) ::   pv_ip      ! melt pond volume
       REAL(wp), DIMENSION(:,:,:,:), INTENT(inout) ::   pe_s       ! snw heat content
@@ -325,5 +325,5 @@
          !== melt ponds ==!
          IF ( ln_pnd_H12 ) THEN
-            ! fraction
+            ! concentration
             zamsk = 1._wp
             CALL adv_umx( zamsk, kn_umx, jt, kt, zdt, zudy , zvdx , zu_cat , zv_cat , zcu_box, zcv_box, &
@@ -1527,5 +1527,5 @@
       !!              3- check whether snow load deplets the snow-ice interface below sea level$
       !!                 and reduce it by sending the excess in the ocean
-      !!              4- correct pond fraction to avoid a_ip > a_i
+      !!              4- correct pond concentration to avoid a_ip > a_i
       !!
       !! ** input   : Max thickness of the surrounding 9-points
@@ -1597,5 +1597,5 @@
          END DO
       END DO 
-      !                                           !-- correct pond fraction to avoid a_ip > a_i
+      !                                           !-- correct pond concentration to avoid a_ip > a_i
       WHERE( pa_ip(:,:,:) > pa_i(:,:,:) )   pa_ip(:,:,:) = pa_i(:,:,:)
       !
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/ICE/icedyn_rdgrft.F90
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/ICE/icedyn_rdgrft.F90	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/ICE/icedyn_rdgrft.F90	(revision 11954)
@@ -86,7 +86,7 @@
       !!                ***  ROUTINE ice_dyn_rdgrft_alloc ***
       !!-------------------------------------------------------------------
-      ALLOCATE( closing_net(jpij), opning(jpij)   , closing_gross(jpij),   &
-         &      apartf(jpij,0:jpl), hrmin(jpij,jpl), hraft(jpij,jpl)    , aridge(jpij,jpl),   &
-         &      hrmax(jpij,jpl), hi_hrdg(jpij,jpl)  , araft (jpij,jpl),  &
+      ALLOCATE( closing_net(jpij)  , opning(jpij)      , closing_gross(jpij) ,               &
+         &      apartf(jpij,0:jpl) , hrmin  (jpij,jpl) , hraft(jpij,jpl) , aridge(jpij,jpl), &
+         &      hrmax (jpij,jpl)   , hi_hrdg(jpij,jpl) , araft(jpij,jpl) ,                   &
          &      ze_i_2d(jpij,nlay_i,jpl), ze_s_2d(jpij,nlay_s,jpl), STAT=ice_dyn_rdgrft_alloc )
 
@@ -137,5 +137,4 @@
       REAL(wp) ::   zfac                       ! local scalar
       INTEGER , DIMENSION(jpij) ::   iptidx        ! compute ridge/raft or not
-      REAL(wp), DIMENSION(jpij) ::   zdivu_adv     ! divu as implied by transport scheme  (1/s)
       REAL(wp), DIMENSION(jpij) ::   zdivu, zdelt  ! 1D divu_i & delta_i
       !
@@ -175,7 +174,7 @@
         
          ! just needed here
-         CALL tab_2d_1d( npti, nptidx(1:npti), zdivu   (1:npti)      , divu_i  )
          CALL tab_2d_1d( npti, nptidx(1:npti), zdelt   (1:npti)      , delta_i )
          ! needed here and in the iteration loop
+         CALL tab_2d_1d( npti, nptidx(1:npti), zdivu   (1:npti)      , divu_i) ! zdivu is used as a work array here (no change in divu_i)
          CALL tab_3d_2d( npti, nptidx(1:npti), a_i_2d  (1:npti,1:jpl), a_i   )
          CALL tab_3d_2d( npti, nptidx(1:npti), v_i_2d  (1:npti,1:jpl), v_i   )
@@ -187,16 +186,8 @@
             closing_net(ji) = rn_csrdg * 0.5_wp * ( zdelt(ji) - ABS( zdivu(ji) ) ) - MIN( zdivu(ji), 0._wp )
             !
-            ! divergence given by the advection scheme
-            !   (which may not be equal to divu as computed from the velocity field)
-            IF    ( ln_adv_Pra ) THEN
-               zdivu_adv(ji) = ( 1._wp - ato_i_1d(ji) - SUM( a_i_2d(ji,:) ) ) * r1_rdtice
-            ELSEIF( ln_adv_UMx ) THEN
-               zdivu_adv(ji) = zdivu(ji)
-            ENDIF
-            !
-            IF( zdivu_adv(ji) < 0._wp )   closing_net(ji) = MAX( closing_net(ji), -zdivu_adv(ji) )   ! make sure the closing rate is large enough
-            !                                                                                        ! to give asum = 1.0 after ridging
+            IF( zdivu(ji) < 0._wp )   closing_net(ji) = MAX( closing_net(ji), -zdivu(ji) )   ! make sure the closing rate is large enough
+            !                                                                                ! to give asum = 1.0 after ridging
             ! Opening rate (non-negative) that will give asum = 1.0 after ridging.
-            opning(ji) = closing_net(ji) + zdivu_adv(ji)
+            opning(ji) = closing_net(ji) + zdivu(ji)
          END DO
          !
@@ -215,5 +206,5 @@
                ato_i_1d   (ipti)   = ato_i_1d   (ji)
                closing_net(ipti)   = closing_net(ji)
-               zdivu_adv  (ipti)   = zdivu_adv  (ji)
+               zdivu      (ipti)   = zdivu      (ji)
                opning     (ipti)   = opning     (ji)
             ENDIF
@@ -259,7 +250,7 @@
                ELSE
                   iterate_ridging  = 1
-                  zdivu_adv  (ji) = zfac * r1_rdtice
-                  closing_net(ji) = MAX( 0._wp, -zdivu_adv(ji) )
-                  opning     (ji) = MAX( 0._wp,  zdivu_adv(ji) )
+                  zdivu      (ji) = zfac * r1_rdtice
+                  closing_net(ji) = MAX( 0._wp, -zdivu(ji) )
+                  opning     (ji) = MAX( 0._wp,  zdivu(ji) )
                ENDIF
             END DO
@@ -309,5 +300,5 @@
 
       !                       ! Ice thickness needed for rafting
-      WHERE( pa_i(1:npti,:) > epsi20 )   ;   zhi(1:npti,:) = pv_i(1:npti,:) / pa_i(1:npti,:)
+      WHERE( pa_i(1:npti,:) > epsi10 )   ;   zhi(1:npti,:) = pv_i(1:npti,:) / pa_i(1:npti,:)
       ELSEWHERE                          ;   zhi(1:npti,:) = 0._wp
       END WHERE
@@ -328,5 +319,5 @@
       zasum(1:npti) = pato_i(1:npti) + SUM( pa_i(1:npti,:), dim=2 )
       !
-      WHERE( zasum(1:npti) > epsi20 )   ;   z1_asum(1:npti) = 1._wp / zasum(1:npti)
+      WHERE( zasum(1:npti) > epsi10 )   ;   z1_asum(1:npti) = 1._wp / zasum(1:npti)
       ELSEWHERE                         ;   z1_asum(1:npti) = 0._wp
       END WHERE
@@ -454,5 +445,5 @@
       ! Based on the ITD of ridging and ridged ice, convert the net closing rate to a gross closing rate.  
       ! NOTE: 0 < aksum <= 1
-      WHERE( zaksum(1:npti) > epsi20 )   ;   closing_gross(1:npti) = pclosing_net(1:npti) / zaksum(1:npti)
+      WHERE( zaksum(1:npti) > epsi10 )   ;   closing_gross(1:npti) = pclosing_net(1:npti) / zaksum(1:npti)
       ELSEWHERE                          ;   closing_gross(1:npti) = 0._wp
       END WHERE
@@ -537,5 +528,5 @@
             IF( apartf(ji,jl1) > 0._wp .AND. closing_gross(ji) > 0._wp ) THEN   ! only if ice is ridging
 
-               IF( a_i_2d(ji,jl1) > epsi20 ) THEN   ;   z1_ai(ji) = 1._wp / a_i_2d(ji,jl1)
+               IF( a_i_2d(ji,jl1) > epsi10 ) THEN   ;   z1_ai(ji) = 1._wp / a_i_2d(ji,jl1)
                ELSE                                 ;   z1_ai(ji) = 0._wp
                ENDIF
@@ -595,5 +586,5 @@
                ! virtual salt flux to keep salinity constant
                IF( nn_icesal /= 2 )  THEN
-                  sirdg2(ji)     = sirdg2(ji)     - vsw * ( sss_1d(ji) - s_i_1d(ji) )        ! ridge salinity = s_i
+                  sirdg2(ji)     = sirdg2(ji)     - vsw * ( sss_1d(ji) - s_i_1d(ji) )       ! ridge salinity = s_i
                   sfx_bri_1d(ji) = sfx_bri_1d(ji) + sss_1d(ji) * vsw * rhoi * r1_rdtice  &  ! put back sss_m into the ocean
                      &                            - s_i_1d(ji) * vsw * rhoi * r1_rdtice     ! and get  s_i  from the ocean 
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/ICE/iceitd.F90
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/ICE/iceitd.F90	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/ICE/iceitd.F90	(revision 11954)
@@ -211,5 +211,5 @@
                CALL itd_glinear( zhb0(1:npti)  , zhb1(1:npti)  , h_ib_1d(1:npti)  , a_i_1d(1:npti)  ,  &   ! in
                   &              g0  (1:npti,1), g1  (1:npti,1), hL     (1:npti,1), hR    (1:npti,1)   )   ! out
-                  !
+               !
                ! Area lost due to melting of thin ice
                DO ji = 1, npti
@@ -218,5 +218,5 @@
                      !
                      zdh0 =  h_i_1d(ji) - h_ib_1d(ji)                
-                     IF( zdh0 < 0.0 ) THEN      !remove area from category 1
+                     IF( zdh0 < 0.0 ) THEN      ! remove area from category 1
                         zdh0 = MIN( -zdh0, hi_max(1) )
                         !Integrate g(1) from 0 to dh0 to estimate area melted
@@ -226,8 +226,7 @@
                            zx1    = zetamax
                            zx2    = 0.5 * zetamax * zetamax 
-                           zda0   = g1(ji,1) * zx2 + g0(ji,1) * zx1                        ! ice area removed
+                           zda0   = g1(ji,1) * zx2 + g0(ji,1) * zx1                ! ice area removed
                            zdamax = a_i_1d(ji) * (1.0 - h_i_1d(ji) / h_ib_1d(ji) ) ! Constrain new thickness <= h_i                
-                           zda0   = MIN( zda0, zdamax )                                                  ! ice area lost due to melting 
-                           !     of thin ice (zdamax > 0)
+                           zda0   = MIN( zda0, zdamax )                            ! ice area lost due to melting of thin ice (zdamax > 0)
                            ! Remove area, conserving volume
                            h_i_1d(ji) = h_i_1d(ji) * a_i_1d(ji) / ( a_i_1d(ji) - zda0 )
@@ -349,5 +348,5 @@
       DO ji = 1, npti
          !
-         IF( paice(ji) > epsi10  .AND. phice(ji) > 0._wp )  THEN
+         IF( paice(ji) > epsi10  .AND. phice(ji) > epsi10 )  THEN
             !
             ! Initialize hL and hR
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/ICE/icevar.F90
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/ICE/icevar.F90	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/ICE/icevar.F90	(revision 11954)
@@ -622,5 +622,5 @@
                   pv_s   (ji,jj,jl) = 0._wp
                ENDIF
-               IF( psv_i(ji,jj,jl) < 0._wp .OR. pa_i(ji,jj,jl) <= 0._wp ) THEN
+               IF( psv_i(ji,jj,jl) < 0._wp .OR. pa_i(ji,jj,jl) <= 0._wp .OR. pv_i(ji,jj,jl) <= 0._wp ) THEN
                   sfx_res(ji,jj)    = sfx_res(ji,jj) + psv_i(ji,jj,jl) * rhoi * z1_dt
                   psv_i  (ji,jj,jl) = 0._wp
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/BDY/bdydta.F90
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/BDY/bdydta.F90	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/BDY/bdydta.F90	(revision 11954)
@@ -461,4 +461,5 @@
                ELSE                                                            ;   ipl = 1            ! xy or xyt
                ENDIF
+               bf(jp_bdya_i,jbdy)%clrootname = 'NOT USED'   ! reset to default value as this subdomain may not need to read this bdy
             ENDIF
          ENDIF
@@ -629,5 +630,5 @@
             ENDIF
 
-            IF( llneed ) THEN                                              ! dta_bdy(jbdy)%xxx will be needed
+            IF( llneed .AND. iszdim > 0 ) THEN                             ! dta_bdy(jbdy)%xxx will be needed
                !                                                           !   -> must be associated with an allocated target
                ALLOCATE( bf_alias(1)%fnow( iszdim, 1, ipk ) )              ! allocate the target
@@ -638,4 +639,5 @@
                   bf_alias(1)%imap    => idx_bdy(jbdy)%nbmap(1:iszdim,igrd)   ! associate the mapping used for this bdy
                   bf_alias(1)%igrd    = igrd                                  ! used only for vertical integration of 3D arrays
+                  bf_alias(1)%ibdy    = jbdy                                  !  "    "    "     "          "      "  "    "    
                   bf_alias(1)%ltotvel = ln_full_vel                           ! T if u3d is full velocity
                   bf_alias(1)%lzint   = ln_zinterp                            ! T if it requires a vertical interpolation
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/CRS/README.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/CRS/README.rst	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/CRS/README.rst	(revision 11954)
@@ -2,4 +2,8 @@
 On line biogeochemistry coarsening
 **********************************
+
+.. todo::
+
+
 
 .. contents::
@@ -63,6 +67,6 @@
 	                           ! 1, MAX of KZ
 	                           ! 2, MIN of KZ
-	                           ! 3, 10^(MEAN(LOG(KZ)) 
-	                           ! 4, MEDIANE of KZ 
+	                           ! 3, 10^(MEAN(LOG(KZ))
+	                           ! 4, MEDIANE of KZ
 	   ln_crs_wn   = .false.   ! wn coarsened (T) or computed using horizontal divergence ( F )
 	                           !                           !
@@ -73,5 +77,5 @@
   the north-fold lateral boundary condition (ORCA025, ORCA12, ORCA36, ...).
 - ``nn_msh_crs = 1`` will activate the generation of the coarsened grid meshmask.
-- ``nn_crs_kz`` is the operator to coarsen the vertical mixing coefficient. 
+- ``nn_crs_kz`` is the operator to coarsen the vertical mixing coefficient.
 - ``ln_crs_wn``
 
@@ -80,5 +84,5 @@
   - when ``key_vvl`` is not activated,
 
-    - coarsened vertical velocities are computed using horizontal divergence (``ln_crs_wn = .false.``) 
+    - coarsened vertical velocities are computed using horizontal divergence (``ln_crs_wn = .false.``)
     - or coarsened vertical velocities are computed with an average operator (``ln_crs_wn = .true.``)
 - ``ln_crs_top = .true.``: should be activated to run BCG model in coarsened space;
@@ -97,5 +101,5 @@
 
 In the [attachment:iodef.xml iodef.xml]  file, a "nemo" context is defined and
-some variable defined in [attachment:file_def.xml file_def.xml] are writted on the ocean-dynamic grid.  
+some variable defined in [attachment:file_def.xml file_def.xml] are writted on the ocean-dynamic grid.
 To write variables on the coarsened grid, and in particular the passive tracers,
 a "nemo_crs" context should be defined in [attachment:iodef.xml iodef.xml] and
@@ -111,5 +115,5 @@
   interpolated `on-the-fly <http://forge.ipsl.jussieu.fr/nemo/wiki/Users/SetupNewConfiguration/Weight-creator>`_.
   Example of namelist for PISCES :
-  
+
 	.. code-block:: fortran
 
@@ -134,5 +138,5 @@
 	   	rn_trfac(14)  =   1.0e-06  !  -      -      -     -
 		   rn_trfac(23)  =   7.6e-06  !  -      -      -     -
-		
+
 	   	cn_dir        =  './'      !  root directory for the location of the data files
 
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/FLO/flodom.F90
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/FLO/flodom.F90	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/FLO/flodom.F90	(revision 11954)
@@ -433,5 +433,5 @@
       IF( ABS(dlx) > 1.0_wp ) dlx = 1.0_wp
       !
-      dld = ATAN(DSQRT( 1._wp * ( 1._wp-dlx )/( 1._wp+dlx ) )) * 222.24_wp / dls
+      dld = ATAN(SQRT( 1._wp * ( 1._wp-dlx )/( 1._wp+dlx ) )) * 222.24_wp / dls
       flo_dstnce = dld * 1000._wp
       !
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/FLO/flowri.F90
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/FLO/flowri.F90	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/FLO/flowri.F90	(revision 11954)
@@ -221,5 +221,5 @@
                clname=TRIM(clname)//".nc"
 
-               CALL fliocrfd( clname , (/ 'ntraj' , 't' /), (/ jpnfl , -1  /) , numflo )
+               CALL fliocrfd( clname , (/'ntraj' , '    t' /), (/ jpnfl , -1/) , numflo )
    
                CALL fliodefv( numflo, 'traj_lon'    , (/1,2/), v_t=flio_r8, long_name="Longitude"           , units="degrees_east"  )
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/LBC/mppini.F90
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/LBC/mppini.F90	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/LBC/mppini.F90	(revision 11954)
@@ -534,5 +534,5 @@
  9401    FORMAT('              '   ,20('   ',i3,'          ') )
  9402    FORMAT('       ',i3,' *  ',20(i3,'  x',i3,'   *   ') )
- 9404    FORMAT('           *  '   ,20('      ',i3,'   *   ') )
+ 9404    FORMAT('           *  '   ,20('     ' ,i4,'   *   ') )
       ENDIF
          
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/LDF/ldfdyn.F90
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/LDF/ldfdyn.F90	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/LDF/ldfdyn.F90	(revision 11954)
@@ -313,6 +313,6 @@
             DO jj = 1, jpj             ! Set local gridscale values
                DO ji = 1, jpi
-                  esqt(ji,jj) = ( e1e2t(ji,jj) / ( e1t(ji,jj) + e2t(ji,jj) ) )**2 
-                  esqf(ji,jj) = ( e1e2f(ji,jj) / ( e1f(ji,jj) + e2f(ji,jj) ) )**2 
+                  esqt(ji,jj) = ( 2._wp * e1e2t(ji,jj) / ( e1t(ji,jj) + e2t(ji,jj) ) )**2 
+                  esqf(ji,jj) = ( 2._wp * e1e2f(ji,jj) / ( e1f(ji,jj) + e2f(ji,jj) ) )**2 
                END DO
             END DO
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/USR/README-setup-configs
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/USR/README-setup-configs	(revision 11712)
+++ 	(revision )
@@ -1,53 +1,0 @@
-==============================================================
-== HOW TO set up user’s configuration in NEMO version 4.0 : ==
-==============================================================
-This document describes how a configuration is set up in NEMO.
-
-In NEMO 4.0 two types of configurations can be build: global/regional and idealized.
-
-- create ./cfgs/your_config
-- case 1: regional or global 
-    => ln_read_cfg = .true. in ./cfgs/your_config/EXP00/namelist_cfg (i.e. read domain_cfg.nc)
-- case 2: idealized 
-    =>in ./cfgs/your_config/EXP00/namelist_cfg :
-      ln_read_cfg = .false. (need to define usrdef_hgr.F90 and usrdef_zgr.F90) 
-      ln_usr = .true.       (need to define usrdef_sbc.F90)    
-    => copy ./src/OCE/USR in ./cfgs/your_config/MY_SRC routines nedeed to set up domain, forcing fields and initial state
-    
-  Routines in NEMOGCM/NEMO/OCE/USR define analytically the domain, the initial state and the surface boundary conditions for the reference configuration GYRE.
-	  •	usrdef_hgr.F90 and usrdef_zgr.F90 : define horizontal and vertical grid
-	  •	usrdef_sbc.F90    : provides at each time-step the surface boundary condition, i.e. the momentum, heat and freshwater fluxes
-	  •	usrdef_istate.F90 : defines initialization of the dynamics and tracers
-	  •	usrdef_fmask.F90  : used just in ORCA CONFIGURATIONS for alteration of f-point land/ocean mask in some straits 
-	  •	usrdef_closea.F90 : used just in ORCA CONFIGURATIONS for specific treatments associated with closed seas
-	  •	usrdef_nam.F90    : set the domain characteristics of a user configuration
-
-  Other analytical examples are given in ./tests.
-
-===========================================
-== The domain_cfg.nc file must contain : ==
-===========================================
-   int ORCA  , ORCA_index            : configuration name, configuration resolution
-   int jpiglo, jpjglo , jpkglo       : global domain sizes 
-   int jperio                        : lateral global domain b.c. 
-   int ln_zco, ln_zps, ln_sco        : flags for z-coordinate, z-coordinate with partial steps and s-coordinate 
-   int ln_isfcav                     : flag  for ice shelf cavities 
-   double glamt, glamu, glamv, glamf : geographic position 
-   double gphit, gphiu, gphiv, gphif : geographic position
-   double iff, ff_f, ff_t            : Coriolis parameter (if not on the sphere)
-   double e1t, e1u, e1v, e1f         : horizontal scale factors
-   double e2t, e2u, e2v, e2f         : horizontal scale factors
-   double ie1e2u_v, e1e2u, e1e2v     : U and V surfaces (if grid size reduction in some straits)
-   double e3t_1d, e3w_1d             : reference vertical scale factors at T and W points
-   double e3t_0, e3u_0, e3v_0, e3f_0, e3w_0 : vertical scale factors 3D coordinate at T,U,V,F and W points
-   double e3uw_0,e3vw_0              : vertical scale factors 3D coordinate at UW and VW points
-   int bottom_level, top_level       : last wet T-points, 1st wet T-points (for ice shelf cavities)
-
-=======================================
-= HOW TO CREATE domain_cfg.nc file : ==
-=======================================
-Two options are possible :
-
- - users can create with his own tool the domain_cfg.nc with all mandatory fields.  
-
- - tool is available in ./tools/DOMAINcfg based on NEMO 3.6 version. See ./tools/DOMAINcfg/README.
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/USR/README.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/USR/README.rst	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/OCE/USR/README.rst	(revision 11954)
@@ -0,0 +1,280 @@
+******************************
+Setting up a new configuration
+******************************
+
+.. todo::
+
+
+
+.. contents::
+   :local:
+
+Starting from an existing configuration
+=======================================
+
+There are three options to build a new configuration from an existing one.
+
+Option 1: Duplicate an existing configuration
+---------------------------------------------
+
+The NEMO so-called Reference Configurations cover a number of major features for NEMO setup
+(global, regional, 1D, using embedded zoom with AGRIF...)
+
+One can create a new configuration by duplicating one of the reference configurations
+(``ORCA2_ICE_PISCES`` in the following example)
+
+.. code-block:: console
+
+   $ ./makenemo –n 'ORCA2_ICE_PISCES_MINE' -r 'ORCA2_ICE_PISCES' -m 'my_arch'
+
+Option 2: Duplicate with differences
+------------------------------------
+
+Create and compile a new configuration based on a reference configuration
+(``ORCA2_ICE_PISCES`` in the following example) but with different pre-processor options.
+For this either add ``add_key`` or ``del_key`` keys as required; e.g.
+
+.. code-block:: console
+
+   $ ./makenemo –n 'ORCA2_ICE_PISCES_MINE' -r 'ORCA2_ICE_PISCES' -m 'my_arch' del_key 'key_iomput' add_key 'key_diahth'
+
+Option 3: Use the SIREN tools to subset an existing model
+---------------------------------------------------------
+
+Define a regional configuration which is a {sub,super}-set of an existing configuration.
+
+This last option employs the SIREN software tools that are included in the standard distribution.
+The software is written in Fortran 95 and available in the :file:`./tools/SIREN` directory.
+SIREN allows you to create your own regional configuration embedded in a wider one.
+
+SIREN is a set of programs to create all the input files you need to
+run a NEMO regional configuration.
+
+:Demo:     Set of GLORYS files (GLObal ReanalYSis on the ORCA025 grid),
+           as well as examples of namelists are available `here`_.
+:Doc:      :forge:`chrome/site/doc/SIREN/html/index.html`
+:Support:  Any questions or comments regarding the use of SIREN should be posted in
+  :forge:`the corresponding forum <discussion/forum/2>`.
+
+.. _here: https://prodn.idris.fr/thredds/catalog/ipsl_public/rron463/catalog.html
+
+Creating a completely new configuration
+=======================================
+
+From NEMO version 4.0 there are two ways to build configurations from scratch.
+The appropriate method to use depends largely on the target configuration.
+Method 1 is for more complex/realistic global or regional configurations and
+method 2 is intended for simpler, idealised configurations whose
+domains and characteristics can be described in simple geometries and formulae.
+
+Option 1: Create and use a domain configuration file
+----------------------------------------------------
+
+This method is used by each of the reference configurations,
+so that downloading their input files linked to their description can help.
+Although starting from scratch,
+it is advisable to create the directory structure to house your new configuration by
+duplicating the closest reference configuration to your target application.
+For example, if your application requires both ocean ice and passive tracers,
+then use the ``ORCA2_ICE_PISCES`` as template,
+and execute following command to build your ``MY_NEW_CONFIG`` configuration:
+
+.. code-block:: sh
+
+   $ ./makenemo –n 'MY_NEW_CONFIG' -r 'ORCA2_ICE_PISCES' -m 'my_arch'
+
+where ``MY_NEW_CONFIG`` can be substituted with
+a suitably descriptive name for your new configuration.
+
+The purpose of this step is simply to create and populate the appropriate :file:`WORK`,
+:file:`MY_SRC` and :file:`EXP00` subdirectories for your new configuration.
+Other choices for the base reference configuration might be
+
+:GYRE:  If your target application is ocean-only
+:AMM12: If your target application is regional with open boundaries
+
+All the domain information for your new configuration will be contained within
+a netcdf file called :file:`domain_cfg.nc` which you will need to create and
+place in the :file:`./cfgs/MY_NEW_CONFIG/EXP00` sub-directory.
+Firstly though, ensure that your configuration is set to use such a file by checking that
+
+.. code-block:: fortran
+
+   ln_read_cfg = .true.
+
+in :file:`./cfgs/MY_NEW_CONFIG/EXP00/namelist_cfg`
+
+Create the :file:`domain_cfg.nc` file which must contain the following fields
+
+.. code-block:: c
+
+   /* configuration name, configuration resolution                 */
+   int    ORCA, ORCA_index
+   /* global domain sizes                                          */
+   int    jpiglo, jpjglo, jpkglo
+   /* lateral global domain b.c.                                   */
+   int    jperio
+   /* flags for z-coord, z-coord with partial steps and s-coord    */
+   int    ln_zco, ln_zps, ln_sco
+   /* flag  for ice shelf cavities                                 */
+   int    ln_isfcav
+   /* geographic position                                          */
+   double glamt, glamu, glamv, glamf
+   /* geographic position                                          */
+   double gphit, gphiu, gphiv, gphif
+   /* Coriolis parameter (if not on the sphere)                    */
+   double iff, ff_f, ff_t
+   /* horizontal scale factors                                     */
+   double e1t, e1u, e1v, e1f
+   /* horizontal scale factors                                     */
+   double e2t, e2u, e2v, e2f
+   /* U and V surfaces (if grid size reduction in some straits)    */
+   double ie1e2u_v, e1e2u, e1e2v
+   /* reference vertical scale factors at T and W points           */
+   double e3t_1d, e3w_1d
+   /* vertical scale factors 3D coordinate at T,U,V,F and W points */
+   double e3t_0, e3u_0, e3v_0, e3f_0, e3w_0
+   /* vertical scale factors 3D coordinate at UW and VW points     */
+   double e3uw_0, e3vw_0
+   /* last wet T-points, 1st wet T-points (for ice shelf cavities) */
+   int    bottom_level, top_level
+
+There are two options for creating a :file:`domain_cfg.nc` file:
+
+- Users can use tools of their own choice to build a :file:`domain_cfg.nc` with all mandatory fields.
+- Users can adapt and apply the supplied tool available in :file:`./tools/DOMAINcfg`.
+  This tool is based on code extracted from NEMO version 3.6 and will allow similar choices for
+  the horizontal and vertical grids that were available internally to that version.
+  See :ref:`tools <DOMAINcfg>` for details.
+
+Option 2: Adapt the usr_def configuration module of NEMO for you own purposes
+-----------------------------------------------------------------------------
+
+This method is intended for configuring easily simple/idealised configurations which
+are often used as demonstrators or for process evaluation and comparison.
+This method can be used whenever the domain geometry has a simple mathematical description and
+the ocean initial state and boundary forcing is described analytically.
+As a start, consider the case of starting a completely new ocean-only test case based on
+the ``LOCK_EXCHANGE`` example.
+
+.. note::
+
+   We probably need an even more basic example than this with only one namelist and
+   minimal changes to the usrdef modules
+
+Firstly, construct the directory structure, starting in the :file:`cfgs` directory:
+
+.. code-block:: console
+
+   $ ./makenemo -n 'MY_NEW_TEST' -t 'LOCK_EXCHANGE' -m 'my_arch'
+
+where the ``-t`` option has been used to locate the new configuration in
+the :file:`tests` subdirectory
+(it is recommended practice to keep full configurations and idealised cases clearly distinguishable).
+This command will create (amongst others) the following files and directories::
+
+   ./tests/MY_NEW_TEST:
+   BLD  EXP00  MY_SRC WORK  cpp_MY_NEW_TEST.fcm
+
+   ./tests/MY_NEW_TEST/EXP00:
+   context_nemo.xml  domain_def_nemo.xml  field_def_nemo-oce.xml  file_def_nemo-oce.xml  iodef.xml
+   namelist_cfg      namelist_ref
+
+   ./tests/MY_NEW_TEST/MY_SRC:
+   usrdef_hgr.F90  usrdef_nam.F90  usrdef_zgr.F90  usrdef_istate.F90  usrdef_sbc.F90  zdfini.F90
+
+The key to setting up an idealised configuration lies in
+adapting a small set of short Fortran 90 modules which
+should be dropped into the :file:`MY_SRC` directory.
+Here the ``LOCK_EXCHANGE`` example is using 5 such routines but the full set that is available in
+the :file:`src/OCE/USR` directory is::
+
+   ./src/OCE/USR:
+   usrdef_closea.F90  usrdef_fmask.F90  usrdef_hgr.F90  usrdef_istate.F90
+   usrdef_nam.F90     usrdef_sbc.F90    usrdef_zgr.F90
+
+Before discussing these in more detail it is worth noting the various namelist controls that
+engage the different user-defined aspects.
+These controls are set using two new logical switches or are implied by the settings of existing ones.
+For example, the mandatory requirement for an idealised configuration is to provide routines which
+define the horizontal and vertical domains.
+Templates for these are provided in the :file:`usrdef_hgr.F90` and :file:`usrdef_zgr.F90` modules.
+The application of these modules is activated whenever:
+
+.. code-block:: fortran
+
+   ln_read_cfg = .false.
+
+in any configuration's :file:`namelist_cfg` file.
+This setting also activates the reading of an optional ``&nam_usrdef`` namelist which can be used to
+supply configuration specific settings.
+These need to be declared and read in the :file:`usrdef_nam.F90` module.
+
+Another explicit control is available in the ``&namsbc`` namelist which
+activates the use of analytical forcing.
+With
+
+.. code-block:: fortran
+
+   ln_usr = .true.
+
+Other usrdef modules are activated by less explicit means.
+For example, code in :file:`usrdef_istate.F90` is used to
+define initial temperature and salinity fields if
+
+.. code-block:: fortran
+
+   ln_tsd_init   = .false.
+
+in the ``&namtsd`` namelist.
+The remaining modules, namely :file:`usrdef_closea.F90` :file:`usrdef_fmask.F90` are specific to
+ORCA configurations and set local variations of some specific fields for
+the various resolutions of the global models.
+They do not need to be considered here in the context of idealised cases but
+it is worth noting that all configuration specific code has now been isolated in the usrdef modules.
+In the case of these last two modules, they are activated only if an ORCA configuration is detected.
+Currently,
+this requires a specific integer variable named ``ORCA`` to be set in a :file:`domain_cfg.nc` file.
+
+.. note::
+
+   This would be less confusing if the ``cn_cfg`` string is read directly as
+   a character attribue from the :file:`domain_cfg.nc`.
+
+So, in most cases, the set up of idealised model configurations can be completed by
+copying the template routines from :file:`./src/OCE/USR` into
+your new :file:`./cfgs/MY_NEW_TEST/MY_SRC` directory and
+editing the appropriate modules as needed.
+The default set are those used for the GYRE reference configuration.
+The contents of :file:`MY_SRC` directories from other idealised configurations may provide
+more convenient templates if they share common characteristics with your target application.
+
+Whatever the starting point,
+it should not require too many changes or additional lines of code to produce routines in
+:file:`./src/OCE/USR` that define analytically the domain,
+the initial state and the surface boundary conditions for your new configuration.
+
+To summarize, the base set of modules is:
+
+:usrdef_hgr.F90:    Define horizontal grid
+:usrdef_zgr.F90:    Define vertical grid
+:usrdef_sbc.F90:    Provides at each time-step the surface boundary condition,
+   i.e. the momentum, heat and freshwater fluxes
+:usrdef_istate.F90: Defines initialization of the dynamics and tracers
+:usrdef_nam.F90:    Configuration-specific namelist processing to
+   set any associated run-time parameters
+
+with two specialised ORCA modules
+(not related to idealised configurations but used to isolate configuration specific code that
+is used in ORCA2 reference configurations and established global configurations using
+the ORCA tripolar grid):
+
+:usrdef_fmask.F90:  only used in ORCA configurations for
+   alteration of f-point land/ocean mask in some straits
+:usrdef_closea.F90: only used in ORCA configurations for
+   specific treatments associated with closed seas
+
+From version 4.0, the NEMO release includes a :file:`tests` subdirectory containing available and
+up to date :doc:`test cases <tests>` build by the community.
+These will not be fully supported as are NEMO reference configurations,
+but should provide a source of raw material.
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/README.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/README.rst	(revision 11954)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/README.rst	(revision 11954)
@@ -0,0 +1,15 @@
+*******
+Sources
+*******
+
+.. todo::
+
+
+
+:file:`ICE`: |NEMO-ICE|
+
+:file:`NST`: AGRIF for embedded zooms
+
+:file:`OCE`: |NEMO-OCE|
+
+:file:`TOP`: |NEMO-MBG|
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/TOP/README.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/TOP/README.rst	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/TOP/README.rst	(revision 11954)
@@ -3,46 +3,51 @@
 ***************
 
+.. todo::
+
+
+
 .. contents::
-	:local:
-
-TOP (Tracers in the Ocean Paradigm) is the NEMO hardwired interface toward biogeochemical models and
-provide the physical constraints/boundaries for oceanic tracers.
-It consists of a modular framework to handle multiple ocean tracers, including also a variety of built-in modules.
+   :local:
+
+TOP (Tracers in the Ocean Paradigm) is the NEMO hardwired interface toward
+biogeochemical models and provide the physical constraints/boundaries for oceanic tracers.
+It consists of a modular framework to handle multiple ocean tracers,
+including also a variety of built-in modules.
 
 This component of the NEMO framework allows one to exploit available modules (see below) and
 further develop a range of applications, spanning from the implementation of a dye passive tracer to
 evaluate dispersion processes (by means of MY_TRC), track water masses age (AGE module),
-assess the ocean interior penetration of persistent chemical compounds (e.g., gases like CFC or even PCBs),
-up to the full set of equations involving marine biogeochemical cycles.
+assess the ocean interior penetration of persistent chemical compounds
+(e.g., gases like CFC or even PCBs), up to the full set of equations involving
+marine biogeochemical cycles.
 
 Structure
 =========
 
-TOP interface has the following location in the source code ``./src/MBG/`` and
+TOP interface has the following location in the source code :file:`./src/TOP` and
 the following modules are available:
 
-``TRP``
-	Interface to NEMO physical core for computing tracers transport
-
-``CFC``
-	Inert carbon tracers (CFC11,CFC12,SF6)
-
-``C14``
-	Radiocarbon passive tracer
-
-``AGE``
-	Water age tracking
-
-``MY_TRC``
-	Template for creation of new modules and external BGC models coupling
-
-``PISCES``
-	Built in BGC model.
-	See [https://www.geosci-model-dev.net/8/2465/2015/gmd-8-2465-2015-discussion.html Aumont et al. (2015)] for
-	a throughout description. |
-
-The usage of TOP is activated i) by including in the configuration definition  the component ``MBG`` and
-ii) by adding the macro ``key_top`` in the configuration CPP file
-(see for more details [http://forge.ipsl.jussieu.fr/nemo/wiki/Users "Learn more about the model"]).
+:file:`TRP`
+   Interface to NEMO physical core for computing tracers transport
+
+:file:`CFC`
+   Inert carbon tracers (CFC11,CFC12,SF6)
+
+:file:`C14`
+   Radiocarbon passive tracer
+
+:file:`AGE`
+   Water age tracking
+
+:file:`MY_TRC`
+   Template for creation of new modules and external BGC models coupling
+
+:file:`PISCES`
+   Built in BGC model. See :cite:`gmd-8-2465-2015` for a throughout description.
+
+The usage of TOP is activated
+*i)* by including in the configuration definition the component ``TOP`` and
+*ii)* by adding the macro ``key_top`` in the configuration CPP file
+(see for more details :forge:`"Learn more about the model" <wiki/Users>`).
 
 As an example, the user can refer to already available configurations in the code,
@@ -51,5 +56,6 @@
 (see also Section 4) .
 
-Note that, since version 4.0, TOP interface core functionalities are activated by means of logical keys and
+Note that, since version 4.0,
+TOP interface core functionalities are activated by means of logical keys and
 all submodules preprocessing macros from previous versions were removed.
 
@@ -57,118 +63,131 @@
 
 ``key_iomput``
-	use XIOS I/O
+   use XIOS I/O
 
 ``key_agrif``
-	enable AGRIF coupling
+   enable AGRIF coupling
 
 ``key_trdtrc`` & ``key_trdmxl_trc``
-	trend computation for tracers
+   trend computation for tracers
 
 Synthetic Workflow
 ==================
 
-A synthetic description of the TOP interface workflow is given below to summarize the steps involved in
-the computation of biogeochemical and physical trends and their time integration and outputs,
+A synthetic description of the TOP interface workflow is given below to
+summarize the steps involved in the computation of biogeochemical and physical trends and
+their time integration and outputs,
 by reporting also the principal Fortran subroutine herein involved.
 
-**Model initialization (OPA_SRC/nemogcm.F90)**
-
-call to trc_init (trcini.F90)
-
-  ↳ call trc_nam (trcnam.F90) to initialize TOP tracers and run setting
-
-  ↳ call trc_ini_sms, to initialize each submodule
-
-  ↳ call trc_ini_trp, to initialize transport for tracers
-
-  ↳ call trc_ice_ini, to initialize tracers in seaice
-
-  ↳ call trc_ini_state, read passive tracers from a restart or input data
-
-  ↳ call trc_sub_ini, setup substepping if {{{nn_dttrc /= 1}}}
-
-**Time marching procedure (OPA_SRC/stp.F90)**
-
-call to trc_stp.F90 (trcstp.F90)
-
-  ↳ call trc_sub_stp, averaging physical variables for sub-stepping
-
-  ↳ call trc_wri, call XIOS for output of data
-
-  ↳ call trc_sms, compute BGC trends for each submodule
-
-    ↳ call trc_sms_my_trc, includes also surface and coastal BCs trends
-
-  ↳ call trc_trp (TRP/trctrp.F90), compute physical trends
-
-    ↳ call trc_sbc, get trend due to surface concentration/dilution
-
-    ↳ call trc_adv, compute tracers advection
-
-    ↳ call to trc_ldf, compute tracers lateral diffusion
-
-    ↳ call to trc_zdf, vertical mixing and after tracer fields
-
-    ↳ call to trc_nxt, tracer fields at next time step. Lateral Boundary Conditions are solved in here.
-
-    ↳ call to trc_rad, Correct artificial negative concentrations
-
-  ↳ call trc_rst_wri, output tracers restart files
+Model initialization (:file:`./src/OCE/nemogcm.F90`)
+----------------------------------------------------
+
+Call to ``trc_init`` subroutine (:file:`./src/TOP/trcini.F90`) to initialize TOP.
+
+.. literalinclude:: ../../../src/TOP/trcini.F90
+   :language:        fortran
+   :lines:           41-86
+   :emphasize-lines: 21,30-32,38-40
+   :caption:         ``trc_init`` subroutine
+
+Time marching procedure (:file:`./src/OCE/step.F90`)
+----------------------------------------------------
+
+Call to ``trc_stp`` subroutine (:file:`./src/TOP/trcstp.F90`) to compute/update passive tracers.
+
+.. literalinclude:: ../../../src/TOP/trcstp.F90
+   :language:        fortran
+   :lines:           46-125
+   :emphasize-lines: 42,55-57
+   :caption:         ``trc_stp`` subroutine
+
+BGC trends computation for each submodule (:file:`./src/TOP/trcsms.F90`)
+------------------------------------------------------------------------
+
+.. literalinclude:: ../../../src/TOP/trcsms.F90
+   :language:        fortran
+   :lines:           21
+   :caption:         :file:`trcsms` snippet
+
+Physical trends computation (:file:`./src/TOP/TRP/trctrp.F90`)
+--------------------------------------------------------------
+
+.. literalinclude:: ../../../src/TOP/TRP/trctrp.F90
+   :language:        fortran
+   :lines:           46-95
+   :emphasize-lines: 17,21,29,33-35
+   :caption:         ``trc_trp`` subroutine
 
 Namelists walkthrough
 =====================
 
-namelist_top
-------------
-
-Here below are listed the features/options of the TOP interface accessible through the namelist_top_ref and
-modifiable by means of namelist_top_cfg (as for NEMO physical ones).
-
-Note that ## is used to refer to a number in an array field.
+:file:`namelist_top`
+--------------------
+
+Here below are listed the features/options of the TOP interface accessible through
+the :file:`namelist_top_ref` and modifiable by means of :file:`namelist_top_cfg`
+(as for NEMO physical ones).
+
+Note that ``##`` is used to refer to a number in an array field.
 
 .. literalinclude:: ../../namelists/namtrc_run
+   :language: fortran
 
 .. literalinclude:: ../../namelists/namtrc
+   :language: fortran
 
 .. literalinclude:: ../../namelists/namtrc_dta
+   :language: fortran
 
 .. literalinclude:: ../../namelists/namtrc_adv
+   :language: fortran
 
 .. literalinclude:: ../../namelists/namtrc_ldf
+   :language: fortran
 
 .. literalinclude:: ../../namelists/namtrc_rad
+   :language: fortran
 
 .. literalinclude:: ../../namelists/namtrc_snk
+   :language: fortran
 
 .. literalinclude:: ../../namelists/namtrc_dmp
+   :language: fortran
 
 .. literalinclude:: ../../namelists/namtrc_ice
+   :language: fortran
 
 .. literalinclude:: ../../namelists/namtrc_trd
+   :language: fortran
 
 .. literalinclude:: ../../namelists/namtrc_bc
+   :language: fortran
 
 .. literalinclude:: ../../namelists/namtrc_bdy
+   :language: fortran
 
 .. literalinclude:: ../../namelists/namage
-
-Two main types of data structure are used within TOP interface to initialize tracer properties (1) and
+   :language: fortran
+
+Two main types of data structure are used within TOP interface
+to initialize tracer properties (1) and
 to provide related initial and boundary conditions (2).
 
-**1. TOP tracers initialization**: sn_tracer (namtrc)
+1. TOP tracers initialization: ``sn_tracer`` (``&namtrc``)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Beside providing name and metadata for tracers,
-here are also defined the use of initial ({{{sn_tracer%llinit}}}) and
-boundary ({{{sn_tracer%llsbc, sn_tracer%llcbc, sn_tracer%llobc}}}) conditions.
-
-In the following, an example of the full structure definition is given for two idealized tracers both with
-initial conditions given, while the first has only surface boundary forcing and
+here are also defined the use of initial (``sn_tracer%llinit``) and
+boundary (``sn_tracer%llsbc, sn_tracer%llcbc, sn_tracer%llobc``) conditions.
+
+In the following, an example of the full structure definition is given for
+two idealized tracers both with initial conditions given,
+while the first has only surface boundary forcing and
 the second both surface and coastal forcings:
 
 .. code-block:: fortran
 
-	!             !    name   !           title of the field            !   units    ! initial data ! sbc   !   cbc  !   obc  !
-	sn_tracer(1)  = 'TRC1'    , 'Tracer 1 Concentration                ',   ' - '    ,  .true.      , .true., .false., .true.
-	sn_tracer(2)  = 'TRC2 '   , 'Tracer 2 Concentration                ',   ' - '    ,  .true.      , .true., .true. , .false.
+   !             !    name   !           title of the field            !   units    ! initial data ! sbc   !   cbc  !   obc  !
+   sn_tracer(1)  = 'TRC1'    , 'Tracer 1 Concentration                ',   ' - '    ,  .true.      , .true., .false., .true.
+   sn_tracer(2)  = 'TRC2 '   , 'Tracer 2 Concentration                ',   ' - '    ,  .true.      , .true., .true. , .false.
 
 As tracers in BGC models are increasingly growing,
@@ -177,94 +196,101 @@
 .. code-block:: fortran
 
-	!             !    name   !           title of the field            !   units    ! initial data !
-	sn_tracer(1)  = 'TRC1'    , 'Tracer 1 Concentration                ',   ' - '    ,   .true.
-	sn_tracer(2)  = 'TRC2 '   , 'Tracer 2 Concentration                ',   ' - '    ,   .true.
-	! sbc
-	sn_tracer(1)%llsbc = .true.
-	sn_tracer(2)%llsbc = .true.
-	! cbc
-	sn_tracer(2)%llcbc = .true.
+   !             !    name   !           title of the field            !   units    ! initial data !
+   sn_tracer(1)  = 'TRC1'    , 'Tracer 1 Concentration                ',   ' - '    ,   .true.
+   sn_tracer(2)  = 'TRC2 '   , 'Tracer 2 Concentration                ',   ' - '    ,   .true.
+   ! sbc
+   sn_tracer(1)%llsbc = .true.
+   sn_tracer(2)%llsbc = .true.
+   ! cbc
+   sn_tracer(2)%llcbc = .true.
 
 The data structure is internally initialized by code with dummy names and
-all initialization/forcing logical fields set to .false. .
-
-**2. Structures to read input initial and boundary conditions**: namtrc_dta (sn_trcdta), namtrc_bc (sn_trcsbc/sn_trccbc/sn_trcobc)
+all initialization/forcing logical fields set to ``.false.`` .
+
+2. Structures to read input initial and boundary conditions: ``&namtrc_dta`` (``sn_trcdta``), ``&namtrc_bc`` (``sn_trcsbc`` / ``sn_trccbc`` / ``sn_trcobc``)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The overall data structure (Fortran type) is based on the general one defined for NEMO core in the SBC component
-(see details in User Manual SBC Chapter on Input Data specification).
-
-Input fields are prescribed within namtrc_dta (with sn_trcdta structure),
-while Boundary Conditions are applied to the model by means of namtrc_bc,
-with dedicated structure fields for surface (sn_trcsbc), riverine (sn_trccbc), and
-lateral open (sn_trcobc) boundaries.
+(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),
+while Boundary Conditions are applied to the model by means of ``&namtrc_bc``,
+with dedicated structure fields for surface (``sn_trcsbc``), riverine (``sn_trccbc``), and
+lateral open (``sn_trcobc``) boundaries.
 
 The following example illustrates the data structure in the case of initial condition for
-a single tracer contained in the file named tracer_1_data.nc (.nc is implicitly assumed in namelist filename),
-with a doubled initial value, and located in the usr/work/model/inputdata/ folder:
+a single tracer contained in the file named :file:`tracer_1_data.nc`
+(``.nc`` is implicitly assumed in namelist filename),
+with a doubled initial value, and located in the :file:`usr/work/model/inputdata` folder:
 
 .. code-block:: fortran
 
-	!               !  file name             ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
-	!               !                        !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
-	  sn_trcdta(1)  = 'tracer_1_data'        ,        -12        ,  'TRC1'   ,    .false.   , .true. , 'yearly'  , ''       , ''       , ''
-	  rf_trfac(1) = 2.0
-	  cn_dir = “usr/work/model/inputdata/”
-
-Note that, the Lateral Open Boundaries conditions are applied on the segments defined for the physical core of NEMO
-(see BDY description in the User Manual).
-
-namelist_trc
-------------
-
-Here below the description of namelist_trc_ref used to handle Carbon tracers modules, namely CFC and C14.
-
-|||| &'''namcfc'''     !   CFC ||
-
-|||| &'''namc14_typ'''     !  C14 - type of C14 tracer, default values of C14/C and pco2 ||
-
-|||| &'''namc14_sbc'''     !  C14 - surface BC ||
-
-|||| &'''namc14_fcg'''     !  files & dates ||
+   !               !  file name             ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
+   !               !                        !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
+     sn_trcdta(1)  = 'tracer_1_data'        ,        -12        ,  'TRC1'   ,    .false.   , .true. , 'yearly'  , ''       , ''       , ''
+     rf_trfac(1) = 2.0
+     cn_dir = 'usr/work/model/inputdata/'
+
+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 <cite>`).
+
+:file:`namelist_trc`
+--------------------
+
+Here below the description of :file:`namelist_trc_ref` used to handle Carbon tracers modules,
+namely CFC and C14.
+
+.. literalinclude:: ../../../cfgs/SHARED/namelist_trc_ref
+   :language: fortran
+   :lines: 7,17,26,34
+   :caption: :file:`namelist_trc_ref` snippet
 
 ``MY_TRC`` interface for coupling external BGC models
 =====================================================
 
-The generalized interface is pivoted on MY_TRC module that contains template files to build the coupling between
+The generalized interface is pivoted on MY_TRC module that contains template files to
+build the coupling between
 NEMO and any external BGC model.
 
-The call to MY_TRC is activated by setting ``ln_my_trc = .true.`` (in namtrc)
+The call to MY_TRC is activated by setting ``ln_my_trc = .true.`` (in ``&namtrc``)
 
 The following 6 fortran files are available in MY_TRC with the specific purposes here described.
 
-``par_my_trc.F90``
-	This module allows to define additional arrays and public variables to be used within the MY_TRC interface
-
-``trcini_my_trc.F90``
-	Here are initialized user defined namelists and the call to the external BGC model initialization procedures to
-	populate general tracer array (trn and trb). Here are also likely to be defined suport arrays related to
-	system metrics that could be needed by the BGC model.
-
-``trcnam_my_trc.F90``
-	This routine is called at the beginning of trcini_my_trc and should contain the initialization of
-	additional namelists for the BGC model or user-defined code.
-
-``trcsms_my_trc.F90``
-	The routine performs the call to Boundary Conditions and its main purpose is to
-	contain the Source-Minus-Sinks terms due to the biogeochemical processes of the external model.
-	Be aware that lateral boundary conditions are applied in trcnxt routine.
-	IMPORTANT: the routines to compute the light penetration along the water column and
-	the tracer vertical sinking should be defined/called in here, as generalized modules are still missing in
-	the code.
-
-``trcice_my_trc.F90``
-	Here it is possible to prescribe the tracers concentrations in the seaice that will be used as
-	boundary conditions when ice melting occurs (nn_ice_tr =1 in namtrc_ice).
-	See e.g. the correspondent PISCES subroutine.
-
-``trcwri_my_trc.F90``
-	This routine performs the output of the model tracers (only those defined in namtrc) using IOM module
-	(see Manual Chapter “Output and Diagnostics”).
-	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.
+:file:`par_my_trc.F90`
+   This module allows to define additional arrays and public variables to
+   be used within the MY_TRC interface
+
+:file:`trcini_my_trc.F90`
+   Here are initialized user defined namelists and
+   the call to the external BGC model initialization procedures to populate general tracer array
+   (``trn`` and ``trb``).
+   Here are also likely to be defined support arrays related to system metrics that
+   could be needed by the BGC model.
+
+:file:`trcnam_my_trc.F90`
+   This routine is called at the beginning of ``trcini_my_trc`` and
+   should contain the initialization of additional namelists for the BGC model or user-defined code.
+
+:file:`trcsms_my_trc.F90`
+   The routine performs the call to Boundary Conditions and its main purpose is to
+   contain the Source-Minus-Sinks terms due to the biogeochemical processes of the external model.
+   Be aware that lateral boundary conditions are applied in trcnxt routine.
+
+   .. warning::
+      The routines to compute the light penetration along the water column and
+      the tracer vertical sinking should be defined/called in here,
+      as generalized modules are still missing in the code.
+
+:file:`trcice_my_trc.F90`
+   Here it is possible to prescribe the tracers concentrations in the sea-ice that
+   will be used as boundary conditions when ice melting occurs (``nn_ice_tr = 1`` in ``&namtrc_ice``).
+   See e.g. the correspondent PISCES subroutine.
+
+: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 <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``.
 
 Coupling an external BGC model using NEMO framework
@@ -273,18 +299,20 @@
 The coupling with an external BGC model through the NEMO compilation framework can be achieved in
 different ways according to the degree of coding complexity of the Biogeochemical model, like e.g.,
-the whole code is made only by one file or it has multiple modules and interfaces spread across several subfolders.
-
-Beside the 6 core files of MY_TRC module, let’s assume an external BGC model named *MYBGC* and constituted by
-a rather essential coding structure, likely few Fortran files.
+the whole code is made only by one file or
+it has multiple modules and interfaces spread across several subfolders.
+
+Beside the 6 core files of MY_TRC module, let’s assume an external BGC model named *MYBGC* and
+constituted by a rather essential coding structure, likely few Fortran files.
 The new coupled configuration name is *NEMO_MYBGC*.
 
-The best solution is to have all files (the modified ``MY_TRC`` routines and the BGC model ones) placed in
-a unique folder with root ``MYBGCPATH`` and to use the makenemo external readdressing of ``MY_SRC`` folder.
-
-The coupled configuration listed in ``work_cfgs.txt`` will look like
+The best solution is to have all files (the modified ``MY_TRC`` routines and the BGC model ones)
+placed in a unique folder with root ``MYBGCPATH`` and
+to use the makenemo external readdressing of ``MY_SRC`` folder.
+
+The coupled configuration listed in :file:`work_cfgs.txt` will look like
 
 ::
 
-	NEMO_MYBGC OPA_SRC TOP_SRC
+   NEMO_MYBGC OCE TOP
 
 and the related ``cpp_MYBGC.fcm`` content will be
@@ -292,46 +320,46 @@
 .. code-block:: perl
 
-	bld::tool::fppkeys  key_iomput key_mpp_mpi key_top
-
-the compilation with ``makenemo`` will be executed through the following syntax
+   bld::tool::fppkeys key_iomput key_mpp_mpi key_top
+
+the compilation with :file:`makenemo` will be executed through the following syntax
 
 .. code-block:: console
 
-	$ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>'
-
-The makenemo feature “-e” was introduced to readdress at compilation time the standard MY_SRC folder
-(usually found in NEMO configurations) with a user defined external one.
-
-The compilation of more articulated BGC model code & infrastructure, like in the case of BFM
-([http://www.bfm-community.eu/publications/bfmnemomanual_r1.0_201508.pdf BFM-NEMO coupling manual]),
-requires some additional features.
+   $ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>'
+
+The makenemo feature ``-e`` was introduced to
+readdress at compilation time the standard MY_SRC folder (usually found in NEMO configurations) with
+a user defined external one.
+
+The compilation of more articulated BGC model code & infrastructure,
+like in the case of BFM (|BFM man|_), requires some additional features.
 
 As before, let’s assume a coupled configuration name *NEMO_MYBGC*,
-but in this case MYBGC model root becomes ``<MYBGCPATH>`` that contains 4 different subfolders for
-biogeochemistry, named ``initialization``, ``pelagic``, and ``benthic``, and
-a separate one named ``nemo_coupling`` including the modified ``MY_SRC`` routines.
+but in this case MYBGC model root becomes :file:`MYBGC` path that
+contains 4 different subfolders for biogeochemistry,
+named :file:`initialization`, :file:`pelagic`, and :file:`benthic`,
+and a separate one named :file:`nemo_coupling` including the modified `MY_SRC` routines.
 The latter folder containing the modified NEMO coupling interface will be still linked using
-the makenemo “-e” option.
+the makenemo ``-e`` option.
 
 In order to include the BGC model subfolders in the compilation of NEMO code,
-it will be necessary to extend the configuration ``cpp_NEMO_MYBGC.fcm`` file to include the specific paths of
-``MYBGC`` folders, as in the following example
+it will be necessary to extend the configuration :file:`cpp_NEMO_MYBGC.fcm` file to include the specific paths of :file:`MYBGC` folders, as in the following example
 
 .. code-block:: perl
 
-	bld::tool::fppkeys  key_iomput key_mpp_mpi key_top
-	
-	src::MYBGC::initialization         <MYBGCPATH>/initialization
-	src::MYBGC::pelagic                <MYBGCPATH>/pelagic
-	src::MYBGC::benthic                <MYBGCPATH>/benthic
-	
-	bld::pp::MYBGC      1
-	bld::tool::fppflags::MYBGC   %FPPFLAGS
-	bld::tool::fppkeys           %bld::tool::fppkeys MYBGC_MACROS
+   bld::tool::fppkeys  key_iomput key_mpp_mpi key_top
+
+   src::MYBGC::initialization         <MYBGCPATH>/initialization
+   src::MYBGC::pelagic                <MYBGCPATH>/pelagic
+   src::MYBGC::benthic                <MYBGCPATH>/benthic
+
+   bld::pp::MYBGC      1
+   bld::tool::fppflags::MYBGC   %FPPFLAGS
+   bld::tool::fppkeys           %bld::tool::fppkeys MYBGC_MACROS
 
 where *MYBGC_MACROS* is the space delimited list of macros used in *MYBGC* model for
 selecting/excluding specific parts of the code.
-The BGC model code will be preprocessed in the configuration ``BLD`` folder as for NEMO,
-but with an independent path, like ``NEMO_MYBGC/BLD/MYBGC/<subforlders>``.
+The BGC model code will be preprocessed in the configuration :file:`BLD` folder as for NEMO,
+but with an independent path, like :file:`NEMO_MYBGC/BLD/MYBGC/<subforlders>`.
 
 The compilation will be performed similarly to in the previous case with the following
@@ -339,20 +367,26 @@
 .. code-block:: console
 
-	$ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>/nemo_coupling'
-
-Note that, the additional lines specific for the BGC model source and build paths can be written into
-a separate file, e.g. named ``MYBGC.fcm``, and then simply included in the ``cpp_NEMO_MYBGC.fcm`` as follow
-
-.. code-block:: perl
-
-	bld::tool::fppkeys  key_zdftke key_dynspg_ts key_iomput key_mpp_mpi key_top
-	inc <MYBGCPATH>/MYBGC.fcm
-
-This will enable a more portable compilation structure for all MYBGC related configurations.
-
-**Important**: the coupling interface contained in nemo_coupling cannot be added using the FCM syntax,
-as the same files already exists in NEMO and they are overridden only with the readdressing of MY_SRC contents to
-avoid compilation conflicts due to duplicate routines.
-
-All modifications illustrated above, can be easily implemented using shell or python scripting to
-edit the NEMO configuration CPP.fcm file and to create the BGC model specific FCM compilation file with code paths.
+   $ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>/nemo_coupling'
+
+.. note::
+   The additional lines specific for the BGC model source and build paths can be written into
+   a separate file, e.g. named :file:`MYBGC.fcm`,
+   and then simply included in the :file:`cpp_NEMO_MYBGC.fcm` as follow
+
+   .. code-block:: perl
+
+      bld::tool::fppkeys  key_zdftke key_dynspg_ts key_iomput key_mpp_mpi key_top
+      inc <MYBGCPATH>/MYBGC.fcm
+
+   This will enable a more portable compilation structure for all MYBGC related configurations.
+
+.. warning::
+   The coupling interface contained in :file:`nemo_coupling` cannot be added using the FCM syntax,
+   as the same files already exists in NEMO and they are overridden only with
+   the readdressing of MY_SRC contents to avoid compilation conflicts due to duplicate routines.
+
+All modifications illustrated above, can be easily implemented using shell or python scripting
+to edit the NEMO configuration :file:`CPP.fcm` file and
+to create the BGC model specific FCM compilation file with code paths.
+
+.. |BFM man| replace:: BFM-NEMO coupling manual
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/TOP/trcbdy.F90
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/TOP/trcbdy.F90	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/src/TOP/trcbdy.F90	(revision 11954)
@@ -95,5 +95,5 @@
          END DO
          IF( ANY(llsend1) .OR. ANY(llrecv1) ) THEN   ! if need to send/recv in at least one direction
-            CALL lbc_lnk( 'bdytra', tsa, 'T',  1., kfillmode=jpfillnothing ,lsend=llsend1, lrecv=llrecv1 )
+            CALL lbc_lnk( 'trcbdy', tra, 'T',  1., kfillmode=jpfillnothing ,lsend=llsend1, lrecv=llrecv1 )
          END IF
          !
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/CANAL/MY_SRC/usrdef_nam.F90
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/CANAL/MY_SRC/usrdef_nam.F90	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/CANAL/MY_SRC/usrdef_nam.F90	(revision 11954)
@@ -85,5 +85,5 @@
       !
       READ  ( numnam_cfg, namusr_def, IOSTAT = ios, ERR = 902 )
-902   IF( ios /= 0 )   CALL ctl_nam ( ios , 'namusr_def in configuration namelist', cdtxt )
+902   IF( ios /= 0 )   CALL ctl_nam ( ios , 'namusr_def in configuration namelist' )
       !
       IF(lwm)   WRITE( numond, namusr_def )
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/OVERFLOW/EXPREF/namelist_sco_FCT2_flux_cen-ahm1000_cfg
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/OVERFLOW/EXPREF/namelist_sco_FCT2_flux_cen-ahm1000_cfg	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/OVERFLOW/EXPREF/namelist_sco_FCT2_flux_cen-ahm1000_cfg	(revision 11954)
@@ -210,5 +210,5 @@
    !                       ! coefficients
    rn_avm0     =   1.e-4     !  vertical eddy viscosity   [m2/s]       (background Kz if ln_zdfcst=F)
-   rn_avt0     =   0.0e      !  vertical eddy diffusivity [m2/s]       (background Kz if ln_zdfcst=F)
+   rn_avt0     =   0.0       !  vertical eddy diffusivity [m2/s]       (background Kz if ln_zdfcst=F)
    nn_avb      =    0        !  profile for background avt & avm (=1) or not (=0)
    nn_havtb    =    0        !  horizontal shape for avtb (=1) or not (=0)
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/OVERFLOW/EXPREF/namelist_sco_FCT2_flux_ubs_cfg
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/OVERFLOW/EXPREF/namelist_sco_FCT2_flux_ubs_cfg	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/OVERFLOW/EXPREF/namelist_sco_FCT2_flux_ubs_cfg	(revision 11954)
@@ -210,5 +210,5 @@
    !                       ! coefficients
    rn_avm0     =   1.e-4     !  vertical eddy viscosity   [m2/s]       (background Kz if ln_zdfcst=F)
-   rn_avt0     =   0.0e      !  vertical eddy diffusivity [m2/s]       (background Kz if ln_zdfcst=F)
+   rn_avt0     =   0.0       !  vertical eddy diffusivity [m2/s]       (background Kz if ln_zdfcst=F)
    nn_avb      =    0        !  profile for background avt & avm (=1) or not (=0)
    nn_havtb    =    0        !  horizontal shape for avtb (=1) or not (=0)
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/OVERFLOW/EXPREF/namelist_sco_FCT4_flux_ubs_cfg
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/OVERFLOW/EXPREF/namelist_sco_FCT4_flux_ubs_cfg	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/OVERFLOW/EXPREF/namelist_sco_FCT4_flux_ubs_cfg	(revision 11954)
@@ -210,5 +210,5 @@
    !                       ! coefficients
    rn_avm0     =   1.e-4     !  vertical eddy viscosity   [m2/s]       (background Kz if ln_zdfcst=F)
-   rn_avt0     =   0.0e      !  vertical eddy diffusivity [m2/s]       (background Kz if ln_zdfcst=F)
+   rn_avt0     =   0.0       !  vertical eddy diffusivity [m2/s]       (background Kz if ln_zdfcst=F)
    nn_avb      =    0        !  profile for background avt & avm (=1) or not (=0)
    nn_havtb    =    0        !  horizontal shape for avtb (=1) or not (=0)
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/OVERFLOW/EXPREF/namelist_zps_FCT2_flux_ubs_cfg
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/OVERFLOW/EXPREF/namelist_zps_FCT2_flux_ubs_cfg	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/OVERFLOW/EXPREF/namelist_zps_FCT2_flux_ubs_cfg	(revision 11954)
@@ -211,5 +211,5 @@
    !                       ! coefficients
    rn_avm0     =   1.e-4     !  vertical eddy viscosity   [m2/s]       (background Kz if ln_zdfcst=F)
-   rn_avt0     =   0.0e      !  vertical eddy diffusivity [m2/s]       (background Kz if ln_zdfcst=F)
+   rn_avt0     =   0.0       !  vertical eddy diffusivity [m2/s]       (background Kz if ln_zdfcst=F)
    nn_avb      =    0        !  profile for background avt & avm (=1) or not (=0)
    nn_havtb    =    0        !  horizontal shape for avtb (=1) or not (=0)
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/OVERFLOW/EXPREF/namelist_zps_FCT4_flux_ubs_cfg
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/OVERFLOW/EXPREF/namelist_zps_FCT4_flux_ubs_cfg	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/OVERFLOW/EXPREF/namelist_zps_FCT4_flux_ubs_cfg	(revision 11954)
@@ -34,9 +34,8 @@
    cn_exp      =   "OVF_zps_FCT4_flux_ubs"  !  experience name
    nn_it000    =       1   !  first time step
-   !nn_itend    =    6120  ! here 17h of simulation  (=6120 time-step) 
-   nn_itend    =    5760   ! here 16h of simulation  (=5760 time-step) abort after 5802 for zps: pb of physics conditions
+   nn_itend    =    6120   ! here 17h of simulation  (=6120 time-step) 
    nn_istate   =       0   !  output the initial state (1) or not (0)
-   nn_stock    =    1080   !  frequency of creation of a restart file (modulo referenced to 1)
-   nn_write    =    1080   !  frequency of write in the output file   (modulo referenced to nn_it000)
+   nn_stock    =    6120   !  frequency of creation of a restart file (modulo referenced to 1)
+   nn_write    =    6120   !  frequency of write in the output file   (modulo referenced to nn_it000)
 /
 !-----------------------------------------------------------------------
@@ -255,4 +254,7 @@
 &namzdf        !   vertical physics manager                             (default: NO selection)
 !-----------------------------------------------------------------------
+   !                       ! adaptive-implicit vertical advection
+   ln_zad_Aimp = .true.       !  Courant number dependent scheme (Shchepetkin 2015)
+   !
    !                       ! type of vertical closure (required)
    ln_zdfcst   = .true.      !  constant mixing
@@ -279,5 +281,5 @@
    !                       ! coefficients
    rn_avm0     =   1.e-4     !  vertical eddy viscosity   [m2/s]       (background Kz if ln_zdfcst=F)
-   rn_avt0     =   0.0e      !  vertical eddy diffusivity [m2/s]       (background Kz if ln_zdfcst=F)
+   rn_avt0     =   0.0       !  vertical eddy diffusivity [m2/s]       (background Kz if ln_zdfcst=F)
    nn_avb      =    0        !  profile for background avt & avm (=1) or not (=0)
    nn_havtb    =    0        !  horizontal shape for avtb (=1) or not (=0)
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/OVERFLOW/EXPREF/namelist_zps_FCT4_vect_een_cfg
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/OVERFLOW/EXPREF/namelist_zps_FCT4_vect_een_cfg	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/OVERFLOW/EXPREF/namelist_zps_FCT4_vect_een_cfg	(revision 11954)
@@ -210,5 +210,5 @@
    !                       ! coefficients
    rn_avm0     =   1.e-4     !  vertical eddy viscosity   [m2/s]       (background Kz if ln_zdfcst=F)
-   rn_avt0     =   0.0e      !  vertical eddy diffusivity [m2/s]       (background Kz if ln_zdfcst=F)
+   rn_avt0     =   0.0       !  vertical eddy diffusivity [m2/s]       (background Kz if ln_zdfcst=F)
    nn_avb      =    0        !  profile for background avt & avm (=1) or not (=0)
    nn_havtb    =    0        !  horizontal shape for avtb (=1) or not (=0)
Index: NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/README.rst
===================================================================
--- NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/README.rst	(revision 11712)
+++ NEMO/branches/2019/dev_r11613_ENHANCE-04_namelists_as_internalfiles/tests/README.rst	(revision 11954)
@@ -3,8 +3,21 @@
 **********************
 
-The complete and up-to-date set of test cases is available on
-`NEMO test cases Github repository <http://github.com/NEMO-ocean/NEMO-examples>`_.
-
-Download it directly in the ``./tests`` root directory with
+.. todo::
+
+   CANAL animated gif is missing
+
+.. contents::
+   :local:
+   :depth: 1
+
+Installation
+============
+
+Download
+--------
+
+| The complete and up-to-date set of test cases is available on
+  :github:`NEMO test cases repository <NEMO-examples>`.
+| Download it directly into the :file:`./tests` root directory with
 
 .. code-block:: console
@@ -12,140 +25,182 @@
    $ git clone http://github.com/NEMO-ocean/NEMO-examples
 
-.. contents::
-	:local:
-
-Procedure
-=========
-
-Compile test cases
-------------------
-
-The compilation of the test cases is very similar to the manner the reference configurations are compiled.
-If you are not familiar on how to compile NEMO, it is first recomended to read :doc:`the instructions <install>`
-
-| In the same manner as the ref. cfg are compiled with '-r' option, test cases can be compile by the use of makenemo with '-a' option.
-| Here an example to compile a copy named WAD2 of the wetting and drying test case (WAD) on the macport_osx architecture on 4 cores:
+Compilation
+-----------
+
+The compilation of the test cases is very similar to
+the manner the reference configurations are compiled.
+If you are not familiar on how to compile NEMO,
+it is first recomended to read :doc:`the instructions <install>`.
+
+| As the reference configurations are compiled with ``-r`` option,
+  test cases can be compiled by the use of :file:`makenemo` with ``-a`` option.
+| Here an example to compile a copy named WAD2 of the wetting and drying test case (WAD):
 
 .. code-block:: console
 
-   $ ./makenemo -n 'WAD2' -a 'WAD' -m 'macport_osx' -j '4'
-
-Run and analyse the test cases
-------------------------------
-
-There no requirement of specific input file for the test_cases presented here. The XIOS xml input files and namelist are already setup correctly. 
+   $ ./makenemo -n 'WAD2' -a 'WAD' -m 'my_arch' -j '4'
+
+Run and analysis
+----------------
+
+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>`_
+the :github:`NEMO test cases repository <NEMO-examples>`
 
 The description below is a brief advertisement of some test cases.
 
+List of test cases
+==================
+
 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  
-  and across the AGRIF boundary
-  One can either impose ice velocities or ice-atm. stresses and let rheology define velocities
-  (see README for details)
-
-  .. image:: _static/ICE_AGRIF_UDIAG_43days_UM5.gif
+---------
+
+.. figure:: _static/ICE_AGRIF_UDIAG_43days_UM5.gif
+   :width: 200px
+   :align: left
+
+   ..
+
+| 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 and across the AGRIF boundary.
+  One can either impose ice velocities or ice-atm.
+  Stresses and let rheology define velocities (see :file:`README` for details)
 
 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
+------
+
+.. figure:: _static/VORTEX_anim.gif
+   :width: 200px
+   :align: right
+
+   ..
+
+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 :cite:`DEBREU2012`,
+:cite:`PENVEN2006` or :cite:`SPALL1991`.
+
+The animation (sea level anomaly in meters) illustrates with
+two 1:2 successively nested grids how the vortex smoothly propagates out of the refined grids.
 
 ISOMIP
-======
-
-  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`. 
-  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).
-
-  .. image:: _static/ISOMIP_moc.png
+------
+
+.. figure:: _static/ISOMIP_moc.png
+   :width: 200px
+   :align: left
+
+   ..
+
+| 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 :cite:`LOSCH2008` and
+  :cite:`MATHIOT2017`.
+  The default setup is the one described |ISOMIP|_.
+| The figure (meridional overturning circulation) illustrates
+  the circulation generated after 10000 days by the ice shelf melting (ice pump).
+
+.. |ISOMIP| replace:: here
 
 LOCK_EXCHANGE
-=============
-
-  The LOCK EXCHANGE experiment is a classical fluid dynamics experiment that has been adapted
-  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 
-  and/or subgrid closures on spurious interior mixing.
-
-  Below the animation of the LOCK_EXCHANGE test case using the advection scheme FCT4 (forth order) for tracer and ubs for dynamics.
-
-  .. image:: _static/LOCK-FCT4_flux_ubs.gif
+-------------
+
+.. figure:: _static/LOCK-FCT4_flux_ubs.gif
+   :width: 200px
+   :align: right
+
+   ..
+
+| The LOCK EXCHANGE experiment is a classical fluid dynamics experiment that has been adapted
+  by :cite:`HAIDVOGEL1999` for testing advection schemes in ocean circulation models.
+  It has been used by several authors including :cite:`BURCHARD2002` and :cite:`ILICAK2012`.
+  The LOCK EXCHANGE experiment can in particular illustrate
+  the impact of different choices of numerical schemes and/or subgrid closures on
+  spurious interior mixing.
+| Here the animation of the LOCK_EXCHANGE test case using
+  the advection scheme FCT4 (forth order) for tracer and ubs for dynamics.
 
 OVERFLOW
-========
-
-  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 (...).
-
-  Below the animation of the OVERFLOW test case in sigma coordinate with the forth-order advection scheme FCT4.
-
-  .. image:: _static/OVF-sco_FCT4_flux_cen-ahm1000.gif
+--------
+
+.. figure:: _static/OVF-sco_FCT4_flux_cen-ahm1000.gif
+   :width: 200px
+   :align: left
+
+   ..
+
+| 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
+  :cite:`HAIDVOGEL1999` and further used by :cite:`ILICAK2012`.
+  Here we can assess the behaviour of the second-order tracer advection scheme FCT2 and
+  forth-order FCT4, z-coordinate and sigma coordinate (...).
+| Here the animation of the OVERFLOW test case in sigma coordinate with
+  the forth-order advection scheme FCT4.
 
 WAD
-===
-
-  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.
-  The parameters are chosen such that the surge rises above sea-level before falling back and oscillating towards an equilibrium position
-
-  .. image:: _static/wad_testcase_7.gif
+---
+
+.. figure:: _static/wad_testcase_7.gif
+   :width: 200px
+   :align: right
+
+   ..
+
+| 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.
+| Here 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.
+  The parameters are chosen such that
+  the surge rises above sea-level before falling back and oscillating towards an equilibrium position.
 
 CANAL
-=====
-
-  East-west periodic canal of variable size with several initial states and associated geostrophic currents (zonal jets or vortex).
-
-  .. image::_static/CANAL_image.gif
+-----
+
+.. figure:: _static/CANAL_image.gif
+   :width: 200px
+   :align: left
+
+   ..
+
+East-west periodic canal of variable size with several initial states and
+associated geostrophic currents (zonal jets or vortex).
 
 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).
+---------
+
+| 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).
   The configuration is similar to ICE_AGRIF, except for the AGRIF zoom.
-  The purpose of this configuration is to test the advection schemes available in the sea-ice code
+| The purpose of this configuration is to test the advection schemes available in the sea-ice code
   (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`,
-  and in which very specific shapes of ice concentration, thickness and volume converge toward the center of a basin.
+---------
+
+| This experiment is the classical :cite:`SCHAR1996` test case ,
+  which has been used in :cite:`LIPSCOMB2004`, and in which very specific shapes of ice concentration,
+  thickness and volume converge toward the center of a basin.
   Convergence is unidirectional (in x) while fields are homogeneous in y.
-  The purpose of this configuration is to test the caracteristics of advection schemes available in the sea-ice code
+| 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.  
-
-References
-==========
-
-.. bibliography:: test_cases.bib
-	:all:
-	:style: unsrt
-	:labelprefix: T
+  especially the constitency between concentration, thickness and volume,
+  and the preservation of initial shapes.
+
+.. rubric:: References
+
+.. bibliography:: tests.bib
+   :all:
+   :style: unsrt
+   :labelprefix: T
