Index: NEMO/branches/2019/ENHANCE-03_closea/cfgs/README.rst
===================================================================
--- NEMO/branches/2019/ENHANCE-03_closea/cfgs/README.rst	(revision 11207)
+++ NEMO/branches/2019/ENHANCE-03_closea/cfgs/README.rst	(revision 12149)
@@ -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
-
