Index: /NEMO/trunk/README.rst
===================================================================
--- /NEMO/trunk/README.rst	(revision 10459)
+++ /NEMO/trunk/README.rst	(revision 10460)
@@ -1,8 +1,8 @@
-:Authors: NEMO System Team
 :Release: |release|
 :Date:    |today|
 
-`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.
+`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.
 
 .. contents::
@@ -21,29 +21,30 @@
   (``./src/MBG``) :cite:`TOP_manual`.
 
-These physical core engines are described in their respective <reference publications> that must be cited for
-any work related to their use.
+These physical core engines are described in their respective `reference publications`_,
+that must be cited for any work related to their use.
 
-Applications and capabilities
-=============================
+Assets and ready-to-use solutions
+=================================
 
 Not only does the NEMO framework model the ocean circulation,
 it offers various features to enable
 
-- Create :doc:`embedded zooms <zooms>` seamlessly with 2-way nesting package `AGRIF`_.
-- :doc:`Low cost biogeochemistry <coarsening>` and :doc:`alternative model opportunity <tracers>`.
-- Versatile :doc:`assimilation <assimilation>`.
-- :doc:`Output diagnostics <diagnostics>` with `XIOS`_ server.
-- :doc:`Coupling <coupling>` via `OASIS`_ for Earth system modelling.
+- Create :doc:`embedded zooms <zooms>` seamlessly thanks to 2-way nesting package `AGRIF`_.
+- Opportunity to integrate an :doc:`alternative biogeochemistry model <tracers>`
+- Versatile :doc:`data_assimilation <data assimilation>`.
+- Generation of :doc:`diagnostics <diagnostics>` through effective `XIOS`_ server.
+- Roll-out Earth system modelling with :doc:`coupling interface <coupling>` to `OASIS`_.
 
-| Several :doc:`builtins configurations <configurations>` are provided to assess the skills and performances of
+| Several :doc:`built-in configurations <configurations>` are provided to evaluate the skills and performances of
 	the model which can be used as templates for :doc:`setting up a new configuration <setup>` (``./cfgs``).
-| The end user could also find some :doc:`idealised test cases <test_cases>` online to serve as templates and
+| The end user could also find online some :doc:`idealised test cases <test_cases>` to serve as templates and
 	to study particular processes (``./tests``).
 
 A set of :doc:`utilities <tools>` is also provided to [pre|post]process your data (``./tools``).
 
-Literature
-==========
+Project literature
+==================
 
+A tutorial 
 :doc:`install`
 
@@ -76,6 +77,6 @@
 extensive :website:`bibliography <bibliography/publications>` published.
 
-Community development
-=====================
+Collaborative development
+=========================
 
 | The NEMO Consortium pulling together 5 European institutes (`CMCC`_, `CNRS`_, `MOI`_, `Met Office`_ and `NERC`_)
@@ -88,2 +89,4 @@
 When the need arises, :forge:`working groups <wiki/WorkingGroups>` are created or resumed to
 gather the community expertise for advising on the development activities.
+
+:doc:`<contributing>`
Index: /NEMO/trunk/cfgs/AGRIF_DEMO/README.rst
===================================================================
--- /NEMO/trunk/cfgs/AGRIF_DEMO/README.rst	(revision 10459)
+++ /NEMO/trunk/cfgs/AGRIF_DEMO/README.rst	(revision 10460)
@@ -1,5 +1,5 @@
-**********************
-Embedded zooms (AGRIF)
-**********************
+**************
+Embedded zooms
+**************
 
 .. contents::
Index: /NEMO/trunk/cfgs/README.rst
===================================================================
--- /NEMO/trunk/cfgs/README.rst	(revision 10459)
+++ /NEMO/trunk/cfgs/README.rst	(revision 10460)
@@ -1,5 +1,5 @@
-*****************************
-Run a reference configuration
-*****************************
+***************************
+Run built-in configurations
+***************************
 
 .. contents::
@@ -14,31 +14,31 @@
 | :underline:`The NEMO System Team is in charge of these configurations`.
 
-+----------------------+-----+-----+-----+--------+-------+-------------------------------+
-|                      | OPA | SI3 | TOP | PISCES | AGRIF | Inputs                        |
-+======================+=====+=====+=====+========+=======+===============================+
-| `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  |        |       | ``-``                         |
-+----------------------+-----+-----+-----+--------+-------+-------------------------------+
-| `GYRE_PISCES`_       |  X  |     |  X  |   X    |       | ``-``                         |
-+----------------------+-----+-----+-----+--------+-------+-------------------------------+
-| `ORCA2_ICE_PISCES`_  |  X  |  X  |  X  |   X    |       | - `ORCA2_ICE_v4.0.tar`_       |
-|                      |     |     |     |        |       | - `INPUTS_PISCES_v4.0.tar`_   |
-+----------------------+-----+-----+-----+--------+-------+-------------------------------+
-| `ORCA2_OFF_PISCES`_  |     |     |  X  |   X    |       | - `INPUTS_PISCES_v4.0.tar`_   |
-|                      |     |     |     |        |       | - `ORCA2_OFF_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`_           |
-+----------------------+-----+-----+-----+--------+-------+-------------------------------+
++----------------------+-----+-----+-----+--------+-------+--------------------------+
+|                      | OPA | SI3 | TOP | PISCES | AGRIF | Inputs                   |
++======================+=====+=====+=====+========+=======+==========================+
+| `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  |        |       | ``-``                    |
++----------------------+-----+-----+-----+--------+-------+--------------------------+
+| `GYRE_PISCES`_       |  X  |     |  X  |   X    |       | ``-``                    |
++----------------------+-----+-----+-----+--------+-------+--------------------------+
+| `ORCA2_ICE_PISCES`_  |  X  |  X  |  X  |   X    |       | - ORCA2_ICE_v4.0.tar     |
+|                      |     |     |     |        |       | - INPUTS_PISCES_v4.0.tar |
++----------------------+-----+-----+-----+--------+-------+--------------------------+
+| `ORCA2_OFF_PISCES`_  |     |     |  X  |   X    |       | - INPUTS_PISCES_v4.0.tar |
+|                      |     |     |     |        |       | - ORCA2_OFF_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         |
++----------------------+-----+-----+-----+--------+-------+--------------------------+
 
 AGRIF_DEMO
Index: /NEMO/trunk/cfgs/SHARED/README.rst
===================================================================
--- /NEMO/trunk/cfgs/SHARED/README.rst	(revision 10459)
+++ /NEMO/trunk/cfgs/SHARED/README.rst	(revision 10460)
@@ -1,5 +1,5 @@
-******************
-Diagnostics (XIOS)
-******************
+***********
+Diagnostics
+***********
 
 .. contents::
Index: /NEMO/trunk/doc/rst/source/NEMO_guide.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/NEMO_guide.rst	(revision 10459)
+++ /NEMO/trunk/doc/rst/source/NEMO_guide.rst	(revision 10460)
@@ -41,5 +41,4 @@
 
 	zooms
-	coarsening
 	coupling
 	assimilation
@@ -56,6 +55,6 @@
 .. Next headings markup acording to readme.rst
 
-How to cite NEMO
-================
+Reference publications
+======================
 
 ..	bibliography:: references.bib
Index: MO/trunk/doc/rst/source/assimilation.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/assimilation.rst	(revision 10459)
+++ 	(revision )
@@ -1,60 +1,0 @@
-**************************************
-Data assimilation (OBS/SAO, ASM & TAM)
-**************************************
-
-.. 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/trunk/doc/rst/source/conf.py
===================================================================
--- /NEMO/trunk/doc/rst/source/conf.py	(revision 10459)
+++ /NEMO/trunk/doc/rst/source/conf.py	(revision 10460)
@@ -63,5 +63,5 @@
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = ['global.rst']
+exclude_patterns = ['global.rst', 'coarsening.rst']
 
 # The name of the Pygments (syntax highlighting) style to use.
Index: /NEMO/trunk/doc/rst/source/coupling.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/coupling.rst	(revision 10459)
+++ /NEMO/trunk/doc/rst/source/coupling.rst	(revision 10460)
@@ -1,5 +1,5 @@
-**********************
-Coupling (OASIS & SAS)
-**********************
+********
+Coupling
+********
 
 NEMO currently exploits OASIS-3-MCT to implement a generalised coupled interface
Index: /NEMO/trunk/doc/rst/source/data_assimilation.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/data_assimilation.rst	(revision 10460)
+++ /NEMO/trunk/doc/rst/source/data_assimilation.rst	(revision 10460)
@@ -0,0 +1,60 @@
+*****************
+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: MO/trunk/doc/rst/source/interfacing_options.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/interfacing_options.rst	(revision 10459)
+++ 	(revision )
@@ -1,36 +1,0 @@
-===================
-Interfacing options
-===================
-
-..
-	contents::
-	:local:
-	:depth: 1
-
-.. include:: zooms.rst
-
-.. bibliography:: zooms.bib
-	:all:
-	:style: unsrt
-	:labelprefix: A
-	:keyprefix: a-
-
-----
-
-.. include:: coarsening.rst
-
-----
-
-.. include:: coupling.rst
-
-----
-
-.. include:: assimilation.rst
-
-----
-
-.. include:: input-output.rst
-
-----
-
-.. include:: tracers.rst
Index: MO/trunk/src/OCE/USR/README.rst
===================================================================
--- /NEMO/trunk/src/OCE/USR/README.rst	(revision 10459)
+++ 	(revision )
@@ -1,256 +1,0 @@
-==============================
-Setting up a new configuration
-==============================
-
-.. include:: .global.rst
-
-.. 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_LIM3_PISCES`` in the following example)
-
-.. code-block:: sh
-
-	makenemo –n 'ORCA2_LIM3_PISCES_MINE' -r 'ORCA2_LIM3_PISCES'
-
-------------------------------------
-Option 2: Duplicate with differences
-------------------------------------
-
-Create and compile a new configuration based on a reference configuration
-(``ORCA2_LIM3_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_LIM3_PISCES_MINE' -r 'ORCA2_LIM3_PISCES' del_key 'key_iomput' add_key 'key_xios'
-
----------------------------------------------------------
-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_LIM3_PISCES`` as template,
-and execute following command to build your ``MY_NEW_CONFIG`` configuration:
-
-.. code-block:: sh
-
-	makenemo –n 'MY_NEW_CONFIG' -r 'ORCA2_LIM3_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 have created (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 is NEMO reference 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
Index: /NEMO/trunk/src/TOP/README.rst
===================================================================
--- /NEMO/trunk/src/TOP/README.rst	(revision 10459)
+++ /NEMO/trunk/src/TOP/README.rst	(revision 10460)
@@ -1,5 +1,5 @@
-*********************
-Oceanic tracers (TOP)
-*********************
+***************
+Oceanic tracers
+***************
 
 .. contents::
