Index: /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/cfgs/AGRIF_DEMO/EXPREF/namelist_ice_cfg
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/cfgs/AGRIF_DEMO/EXPREF/namelist_ice_cfg	(revision 11835)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/cfgs/AGRIF_DEMO/EXPREF/namelist_ice_cfg	(revision 11836)
@@ -38,4 +38,5 @@
 &namdyn_rhg     !   Ice rheology
 !------------------------------------------------------------------------------
+      ln_aEVP       = .false.          !     adaptive rheology (Kimmritz et al. 2016 & 2017)
 /
 !------------------------------------------------------------------------------
Index: /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/cfgs/AGRIF_DEMO/README.rst
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/cfgs/AGRIF_DEMO/README.rst	(revision 11835)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/cfgs/AGRIF_DEMO/README.rst	(revision 11836)
@@ -13,11 +13,13 @@
 ========
 
-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
@@ -28,9 +30,9 @@
 .. 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.
 
@@ -38,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
@@ -71,9 +74,10 @@
 =============
 
-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.
 
@@ -82,23 +86,15 @@
 
 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``)
 
 .. rubric:: References
Index: /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/cfgs/README.rst
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/cfgs/README.rst	(revision 11835)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/cfgs/README.rst	(revision 11836)
@@ -29,5 +29,5 @@
 ===========================================================
 
-To compile the ORCA2_ICE_PISCES_ reference configuration using ``makenemo``,
+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:
Index: /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/cfgs/SHARED/README.rst
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/cfgs/SHARED/README.rst	(revision 11835)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/cfgs/SHARED/README.rst	(revision 11836)
@@ -11,35 +11,50 @@
 
 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``.
 
 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:
+   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
+   .. code-block:: console
 
-	$ svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5 xios-2.5
+      $ svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5
 
-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.
+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
@@ -48,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
@@ -60,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,
+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
+   .. code-block:: fortran
 
-		IF iom_use('field_id') THEN
-		   !Some expensive computation
-	   	!...
-		   !...
-	   	iom_put('field_id', variable)
-		ENDIF
+      IF iom_use('field_id') THEN
+         !Some expensive computation
+         !...
+         !...
+	 iom_put('field_id', variable)
+      ENDIF
 
-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.
+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_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/cfgs/SHARED/namelist_ref
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/cfgs/SHARED/namelist_ref	(revision 11835)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/cfgs/SHARED/namelist_ref	(revision 11836)
@@ -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_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/README.rst
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/README.rst	(revision 11835)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/README.rst	(revision 11836)
@@ -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_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/conf.py
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/conf.py	(revision 11835)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/conf.py	(revision 11836)
@@ -26,5 +26,6 @@
 # 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']
+extensions = ['sphinx.ext.extlinks', 'sphinxcontrib.bibtex',
+              'sphinx.ext.todo'    , 'sphinx.ext.autosectionlabel']
 
 # Add any paths that contain templates here, relative to this directory.
@@ -65,5 +66,5 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['global.rst', 'crs.rst']
+exclude_patterns = ['global.rst', 'readme.rst']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
@@ -252,5 +253,5 @@
 extlinks = {
    'doi'    : ('https://doi.org/%s'                                                    , 'doi:'),
-   'doxy'   : ('https://forge.ipsl.jussieu.fr/nemo/chrome/site/doc/NEMO/manual/html/%s', None  ),
+   '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  ),
@@ -266,9 +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
+   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_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/cplg.rst
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/cplg.rst	(revision 11835)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/cplg.rst	(revision 11836)
@@ -5,15 +5,17 @@
 .. todo::
 
-
+   The ‘Coupling’ chapter needs to be enriched
 
 NEMO currently exploits OASIS-3-MCT (versions 1 to 4) to implement a generalised coupled interface
-(:doxy:`Coupled Formulation <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).
+(: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
-(:doxy:`Standalone Surface Module - SAS <node46.html?doc=NEMO>`).
+(: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``.
+The parameters to set are in sections ``&namsbc_cpl`` and
+in case of using of SAS also in section ``&namsbc_sas``.
Index: MO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/crs.rst
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/crs.rst	(revision 11835)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../src/OCE/CRS/README.rst
Index: /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/da.rst
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/da.rst	(revision 11835)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/da.rst	(revision 11836)
@@ -17,6 +17,6 @@
 - ``TAM`` the tangent linear and adjoint model.
 
-Please see |DOI man OCE|_ for more details including information about the input file formats and
-the namelist settings.
+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``)
@@ -33,5 +33,5 @@
 To build with the OBS code active ``key_diaobs`` must be set.
 
-More details in |DOI man OCE|_ "Observation and Model Comparison (``OBS``)" chapter.
+More details in :manhtml:`"Observation and Model Comparison (OBS)" chapter <node83.html>`.
 
 Standalone observation operator (``SAO``)
@@ -42,5 +42,5 @@
 (previously known the offline observation operator).
 
-To build the SAO use makenemo.
+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.
@@ -48,5 +48,5 @@
 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 "Standalone observation operator (``SAO``)" section in |DOI man OCE|_.
+See :manhtml:`"Standalone observation operator (SAO)" section <node88.html>`.
 
 Apply assimilation increments (``ASM``)
@@ -61,5 +61,5 @@
 To build the ASM code ``key asminc`` must be set.
 
-More details in |DOI man OCE|_ "Apply Assimilation Increments (``ASM``)" chapter.
+More details in :manhtml:`"Apply Assimilation Increments (ASM)" chapter <node89.html>`.
 
 Tangent linear and adjoint (``TAM``)
Index: MO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/doc.rst
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/doc.rst	(revision 11835)
+++ 	(revision )
@@ -1,13 +1,0 @@
-**************************
-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)
Index: /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/guide.rst
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/guide.rst	(revision 11835)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/guide.rst	(revision 11836)
@@ -3,15 +3,31 @@
 #################
 
-..
-	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
+.. 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'
+   '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::
@@ -53,8 +69,8 @@
 .. only:: draft
 
+   .. Only on draft
+
    :*Date*:     |today|
    :*SVN rev*:  |revision|
 
-   .. include:: todos.rst
-
 .. include:: readme.rst
Index: /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/setup.rst
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/setup.rst	(revision 11835)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/setup.rst	(revision 11836)
@@ -1,253 +1,1 @@
-******************************
-Setting up a new configuration
-******************************
-
-.. todo::
-
-
-
-.. 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: MO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/src.rst
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/src.rst	(revision 11835)
+++ 	(revision )
@@ -1,12 +1,0 @@
-*******
-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_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/todos.rst
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/todos.rst	(revision 11835)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/todos.rst	(revision 11836)
@@ -1,3 +1,5 @@
-.. rubric:: List of editing tasks
+*********************
+List of editing tasks
+*********************
 
 .. todolist::
Index: /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/unpub/crs.rst
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/unpub/crs.rst	(revision 11836)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/unpub/crs.rst	(revision 11836)
@@ -0,0 +1,1 @@
+link ../../../../src/OCE/CRS/README.rst
Index: /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/unpub/doc.rst
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/unpub/doc.rst	(revision 11836)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/unpub/doc.rst	(revision 11836)
@@ -0,0 +1,1 @@
+link ../../../README.rst
Index: /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/unpub/src.rst
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/unpub/src.rst	(revision 11836)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/doc/rst/source/unpub/src.rst	(revision 11836)
@@ -0,0 +1,1 @@
+link ../../../../src/README.rst
Index: /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/ICE/icedyn_adv_pra.F90
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/ICE/icedyn_adv_pra.F90	(revision 11835)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/ICE/icedyn_adv_pra.F90	(revision 11836)
@@ -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
Index: /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/OCE/BDY/bdydta.F90
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/OCE/BDY/bdydta.F90	(revision 11835)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/OCE/BDY/bdydta.F90	(revision 11836)
@@ -624,4 +624,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_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/OCE/FLO/flodom.F90
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/OCE/FLO/flodom.F90	(revision 11835)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/OCE/FLO/flodom.F90	(revision 11836)
@@ -436,5 +436,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_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/OCE/FLO/flowri.F90
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/OCE/FLO/flowri.F90	(revision 11835)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/OCE/FLO/flowri.F90	(revision 11836)
@@ -222,5 +222,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: MO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/OCE/USR/README-setup-configs
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/OCE/USR/README-setup-configs	(revision 11835)
+++ 	(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_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/OCE/USR/README.rst
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/OCE/USR/README.rst	(revision 11836)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/OCE/USR/README.rst	(revision 11836)
@@ -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_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/README.rst
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/README.rst	(revision 11836)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/README.rst	(revision 11836)
@@ -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_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/TOP/trcbdy.F90
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/TOP/trcbdy.F90	(revision 11835)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/src/TOP/trcbdy.F90	(revision 11836)
@@ -96,5 +96,5 @@
          END DO
          IF( ANY(llsend1) .OR. ANY(llrecv1) ) THEN   ! if need to send/recv in at least one direction
-            CALL lbc_lnk( 'bdytra', tr(:,:,:,:,Krhs), 'T',  1., kfillmode=jpfillnothing ,lsend=llsend1, lrecv=llrecv1 )
+            CALL lbc_lnk( 'trcbdy', tr(:,:,:,:,Krhs), 'T',  1., kfillmode=jpfillnothing ,lsend=llsend1, lrecv=llrecv1 )
          END IF
          !
Index: /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/tests/README.rst
===================================================================
--- /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/tests/README.rst	(revision 11835)
+++ /NEMO/branches/2019/dev_r10721_KERNEL-02_Storkey_Coward_IMMERSE_first_steps/tests/README.rst	(revision 11836)
@@ -5,5 +5,5 @@
 .. todo::
 
-
+   CANAL animated gif is missing
 
 .. contents::
