Index: NEMO/trunk/doc/rst/source/.global.rst
===================================================================
--- NEMO/trunk/doc/rst/source/.global.rst	(revision 10201)
+++ NEMO/trunk/doc/rst/source/.global.rst	(revision 10201)
@@ -0,0 +1,35 @@
+.. Roles (custom styles related to CSS classes)
+
+.. role:: rstblue
+.. role:: rstgreen
+.. role:: rstgrey
+.. role:: rstgreysup(sup)
+
+.. Links
+
+	.. Institutes
+
+.. _CMCC:           http://www.cmcc.it 
+.. _CNRS:           http://www.cnrs.fr
+.. _Mercator Océan: http://www.mercator-ocean.fr
+.. _Met Office:     http://www.metoffice.gov.uk
+.. _MOI:            http://www.mercator-ocean.fr
+.. _NERC:           http://nerc.ukri.org
+
+	.. Models / Softwares
+
+.. _AGRIF: http://agrif.imag.fr
+.. _OASIS: http://verc.enes.org/oasis
+
+	.. NEMO
+
+.. _NEMO:             http://www.nemo-ocean.eu
+.. _Reference Manual: http://doi.org/10.5281/zenodo.1137733
+.. _Special Issue:    http://www.geosci-model-dev.net/special_issue40.html
+.. _Working Groups:   http://forge.ipsl.jussieu.fr/nemo/wiki/WorkingGroups
+
+	.. XIOS
+
+.. _XIOS:                    http://forge.ipsl.jussieu.fr/ioserver
+.. _XIOS documentation:      http://forge.ipsl.jussieu.fr/ioserver/wiki/documentation
+.. _XIOS users mailing list: http://forge.ipsl.jussieu.fr/mailman/listinfo.cgi/xios-users
Index: NEMO/trunk/doc/rst/source/NEMO_guide.rst
===================================================================
--- NEMO/trunk/doc/rst/source/NEMO_guide.rst	(revision 10188)
+++ NEMO/trunk/doc/rst/source/NEMO_guide.rst	(revision 10201)
@@ -4,7 +4,18 @@
    contain the root `toctree` directive.
 
-=================
+#################
 Quick Start Guide
-=================
+#################
+
+..
+	A hidden .global.rst should be included in every subfiles with `include` directive
+   It contains a list of common URL links 
+     
+.. include:: .global.rst
+
+.. include:: readme.rst
+
+Summary
+=======
 
 .. toctree::
@@ -18,12 +29,19 @@
 	setup_configuration.rst
 	interfacing_options.rst
-	references.rst
+	definitions.rst
 
-.. include:: readme.rst
+..
+   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
 
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+..
+	Indices and tables
+	==================
+	* :ref:`genindex`
+	* :ref:`modindex`
+	* :ref:`search`
Index: NEMO/trunk/doc/rst/source/README-setup-configs
===================================================================
--- NEMO/trunk/doc/rst/source/README-setup-configs	(revision 10188)
+++ 	(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/trunk/doc/rst/source/coarsening.rst
===================================================================
--- NEMO/trunk/doc/rst/source/coarsening.rst	(revision 10201)
+++ NEMO/trunk/doc/rst/source/coarsening.rst	(revision 10201)
@@ -0,0 +1,1 @@
+link ../../../src/OCE/CRS/README.rst
Index: NEMO/trunk/doc/rst/source/conf.py
===================================================================
--- NEMO/trunk/doc/rst/source/conf.py	(revision 10188)
+++ NEMO/trunk/doc/rst/source/conf.py	(revision 10201)
@@ -25,7 +25,7 @@
 
 # The short X.Y version
-version = ''
+version = '4.0'
 # The full version, including alpha/beta/rc tags
-release = '4.0'
+release = '4.0rc'
 
 
@@ -39,6 +39,5 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-]
+extensions = ['sphinxcontrib.bibtex']
 
 # Add any paths that contain templates here, relative to this directory.
Index: NEMO/trunk/doc/rst/source/coupling.rst
===================================================================
--- NEMO/trunk/doc/rst/source/coupling.rst	(revision 10201)
+++ NEMO/trunk/doc/rst/source/coupling.rst	(revision 10201)
@@ -0,0 +1,14 @@
+Coupling with other models (OASIS, SAS, ...)
+============================================
+
+.. include:: .global.rst
+
+NEMO currently exploits OASIS-3-MCT to implement a generalised coupled interface
+(`Coupled Formulation <http://forge.ipsl.jussieu.fr/nemo/doxygen/node50.html?doc=NEMO>`_).
+It can be used to interface with most of the European atmospheric GCM (ARPEGE, ECHAM, ECMWF, Ha- dAM, HadGAM, LMDz),
+as well as to WRF (Weather Research and Forecasting Model), and to implement the coupling of
+two independent NEMO components, ocean on one hand and sea-ice plus other surface processes on the other hand
+(`Standalone Surface Module - SAS <http://forge.ipsl.jussieu.fr/nemo/doxygen/node46.html?doc=NEMO>`_).
+
+To enable the OASIS interface the required compilation key is ``key_oasis3``.
+The parameters to set are in sections ``namsbc_cpl`` and in case of using of SAS also in section ``namsbc_sas``.
Index: NEMO/trunk/doc/rst/source/data_assimilation.rst
===================================================================
--- NEMO/trunk/doc/rst/source/data_assimilation.rst	(revision 10201)
+++ NEMO/trunk/doc/rst/source/data_assimilation.rst	(revision 10201)
@@ -0,0 +1,66 @@
+Data assimilation
+=================
+
+.. include:: .global.rst
+
+.. 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 reference 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 reference 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 reference 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 reference 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.
+
+.. _NEMO reference manual: http://doi.org/10.5281/zenodo.
Index: NEMO/trunk/doc/rst/source/definitions.rst
===================================================================
--- NEMO/trunk/doc/rst/source/definitions.rst	(revision 10201)
+++ NEMO/trunk/doc/rst/source/definitions.rst	(revision 10201)
@@ -0,0 +1,35 @@
+===========
+Definitions
+===========
+
+.. include:: .global.rst
+
+AGRIF
+	*Adaptive Grid Refinement In Fortran*, 
+	package for the integration of full adaptive mesh refinement features within 
+	an existing multidimensional finite difference model
+
+SI\ :sup:`3`\ 
+	*Sea Ice Integrated Initiative*, 
+	unified sea ice model merging functionalities from CICE, GELATO and LIM into the NEMO framework
+
+OASIS
+	*Ocean Atmosphere Sea Ice Soil*, 
+	coupling software to synchronise numerical codes representing different components of the climate system
+
+PISCES
+	*Pelagic Interactions Scheme for Carbon and Ecosystem Studies*, 
+	biogeochemical model simulating marine ecosystems, cycles of carbon and the main nutrients
+
+TAM
+	*Tangent linear and Adjoint Model*, 
+	tools to analyse and control the NEMO dynamical core for a wide range of applications such as
+	sensitivity analysis, parameter estimation, vectors computation or data assimilation.
+
+TOP
+	*Tracers in Ocean Paradigm*, 
+	on/off-line oceanic tracers transport and biogeochemistry models
+
+XIOS
+	*XML Input Output Server*, 
+	library dedicated to input/output management of climate code
Index: NEMO/trunk/doc/rst/source/input-output.rst
===================================================================
--- NEMO/trunk/doc/rst/source/input-output.rst	(revision 10201)
+++ NEMO/trunk/doc/rst/source/input-output.rst	(revision 10201)
@@ -0,0 +1,1 @@
+link ../../../cfgs/SHARED/README.rst
Index: NEMO/trunk/doc/rst/source/interfacing_options.rst
===================================================================
--- NEMO/trunk/doc/rst/source/interfacing_options.rst	(revision 10188)
+++ NEMO/trunk/doc/rst/source/interfacing_options.rst	(revision 10201)
@@ -3,454 +3,29 @@
 ===================
 
+.. include:: .global.rst
+
 .. contents::
 	:local:
 	:depth: 1
-           
-Embedded zooms with AGRIF
-=========================
 
-.. contents::
-   :local:
-
---------
-Overview
---------
-
-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.
-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.
-
------------
-Compilation
------------
-
-Activating AGRIF requires to append the cpp key ``key_agrif`` at compilation time: 
-
-.. code-block:: sh
-
-	./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
-saved arrays may be switched in memory space from one domain to an other.
-
---------------------------------
-Definition of the grid hierarchy
---------------------------------
-
-An additional text 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::
-
-	1
-	34 63 34 63 3 3 3
-	0
-
-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).
-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.
-
-[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
-
-Note that rectangular regions must be defined so that they are connected to a single parent grid.
-Hence, defining overlapping grids with the same refinement ratio will not work properly,
-boundary data exchange and update being only performed between root and child grids.
-Use of east-west periodic or north-fold boundary conditions is not allowed in child grids either.
-Defining for instance a circumpolar zoom in a global model is therefore not possible. 
-
--------------
-Preprocessing
--------------
-
-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.
-These correspond to the namelists used to create ``AGRIF_DEMO`` inputs.
-
-----------------
-Namelist options
-----------------
-
-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).
-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
-	/             
-
-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) 
-
-----------   
-References
-----------
-
-`Debreu, L., P. Marchesiello, P. Penven and G. Cambon, 2012: Two-way nesting in split-explicit ocean models: Algorithms, implementation and validation. Ocean Modelling, 49-50, 1-21. <http://doi.org/10.1016/j.ocemod.2012.03.003>`_
-
-`Penven, P., L. Debreu, P. Marchesiello and J. C. Mc Williams, 2006: Evaluation and application of the ROMS 1-way embedding procedure to the central california upwelling system. Ocean Modelling, 12, 157-187. <http://doi.org/10.1016/j.ocemod.2005.05.002>`_
-
-`Spall, M. A. and W. R. Holland, 1991: A Nested Primitive Equation Model for Oceanic Applications. J. Phys. Ocean., 21, 205-220. <https://doi.org/10.1175/1520-0485(1991)021\<0205:ANPEMF\>2.0.CO;2>`_
+.. include:: zooms.rst
 
 ----
 
-On line biogeochemistry coarsening
-==================================
-
-.. contents::
-   :local:
-
-.. role:: underline 
-   :class: underline
-
-------------
-Presentation
-------------
-
-A capacity of coarsening physics to force a BGC model coupled to NEMO has been developed.
-This capacity allow to run 'online' a BGC model coupled to OCE-SI3 with a lower resolution,
-to reduce the CPU cost of the BGC model, while preserving the effective resolution of the dynamics.
-
-A presentation is available [attachment:crs_wiki_1.1.pdf​ here], where the methodology is presented.
-
------------------------------------------------------
-What is available and working for now in this version
------------------------------------------------------
-
-[To be completed]
-
-----------------------------------------------
-Description of the successful validation tests
-----------------------------------------------
-
-[To be completed]
-
-------------------------------------------------------------------
-What is not working yet with on line coarsening of biogeochemistry
-------------------------------------------------------------------
-
-[To be completed]
-
-''should include precise explanation on MPI decomposition problems too''
-
----------------------------------------------
-How to set up and use on line biogeochemistry
----------------------------------------------
-
-:underline:`How to activate coarsening?`
-
-To activate the coarsening, ``key_crs`` should be added to list of CPP keys.
-This key will only activate the coarsening of dynamics.
-
-Some parameters are available in the namelist_cfg:
-
-.. code-block:: fortran
-
-	               !   passive tracer coarsened online simulations
-	!-----------------------------------------------------------------------
-	   nn_factx    = 3         !  Reduction factor of x-direction
-	   nn_facty    = 3         !  Reduction factor of y-direction
-	   nn_msh_crs  = 0         !  create (=1) a mesh file or not (=0)
-	   nn_crs_kz   = 3         ! 0, volume-weighted MEAN of KZ
-	                           ! 1, MAX of KZ
-	                           ! 2, MIN of KZ
-	                           ! 3, 10^(MEAN(LOG(KZ)) 
-	                           ! 4, MEDIANE of KZ 
-	   ln_crs_wn   = .false.   ! wn coarsened (T) or computed using horizontal divergence ( F )
-	                           !                           !
-	   ln_crs_top = .true.     !coarsening online for the bio
-	/
-
-- Only ``nn_factx = 3`` is available and the coarsening only works for grids with a T-pivot point for
-  the north-fold lateral boundary condition (ORCA025, ORCA12, ORCA36, ...).
-- ``nn_msh_crs = 1`` will activate the generation of the coarsened grid meshmask.
-- ``nn_crs_kz`` is the operator to coarsen the vertical mixing coefficient. 
-- ``ln_crs_wn``
-
-  - when ``key_vvl`` is activated, this logical has no effect;
-    the coarsened vertical velocities are computed using horizontal divergence.
-  - when ``key_vvl`` is not activated,
-
-    - coarsened vertical velocities are computed using horizontal divergence (``ln_crs_wn = .false.``) 
-    - or coarsened vertical velocities are computed with an average operator (``ln_crs_wn = .true.``)
-- ``ln_crs_top = .true.``: should be activated to run BCG model in coarsened space;
-  so only works when ``key_top`` is in the cpp list and eventually ``key_pisces`` or ``key_my_trc``.
-
-:underline:`Choice of operator to coarsene KZ`
-
-A sensiblity test has been done with an Age tracer to compare the different operators.
-The 3 and 4 options seems to provide the best results.
-
-Some results can be found [xxx here]
-
-:underline:`Example of xml files to output coarsened variables with XIOS`
-
-In the [attachment:iodef.xml iodef.xml]  file, a "nemo" context is defined and
-some variable defined in [attachment:file_def.xml file_def.xml] are writted on the ocean-dynamic grid.  
-To write variables on the coarsened grid, and in particular the passive tracers,
-a "nemo_crs" context should be defined in [attachment:iodef.xml iodef.xml] and
-the associated variable are listed in [attachment:file_crs_def.xml file_crs_def.xml ].
-
-:underline:`Passive tracers tracers initial conditions`
-
-When initial conditions are provided in NetCDF files, the field might be:
-
-- on the coarsened grid
-- or they can be on another grid and
-  interpolated `on-the-fly <http://forge.ipsl.jussieu.fr/nemo/wiki/Users/SetupNewConfiguration/Weight-creator>`_.
-  Example of namelist for PISCES :
-  
-	.. code-block:: fortran
-
-		!-----------------------------------------------------------------------
-		&namtrc_dta      !    Initialisation from data input file
-		!-----------------------------------------------------------------------
-		!
-		   sn_trcdta(1)  = 'DIC_REG1'        ,        -12        ,  'DIC'     ,    .false.   , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , ''
-		   sn_trcdta(2)  = 'ALK_REG1'        ,        -12        ,  'ALK'     ,    .false.   , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , ''
-		   sn_trcdta(3)  = 'O2_REG1'         ,        -1         ,  'O2'      ,    .true.    , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , ''
-		   sn_trcdta(5)  = 'PO4_REG1'        ,        -1         ,  'PO4'     ,    .true.    , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , ''
-		   sn_trcdta(7)  = 'Si_REG1'         ,        -1         ,  'Si'      ,    .true.    , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , ''
-	   	sn_trcdta(10) = 'DOC_REG1'        ,        -12        ,  'DOC'     ,    .false.   , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , ''
-		   sn_trcdta(14) = 'Fe_REG1'         ,        -12        ,  'Fe'      ,    .false.   , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , ''
-		   sn_trcdta(23) = 'NO3_REG1'        ,        -1         ,  'NO3'     ,    .true.    , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , ''
-	   	rn_trfac(1)   =   1.0e-06  !  multiplicative factor
-		   rn_trfac(2)   =   1.0e-06  !  -      -      -     -
-		   rn_trfac(3)   =  44.6e-06  !  -      -      -     -
-	   	rn_trfac(5)   = 122.0e-06  !  -      -      -     -
-		   rn_trfac(7)   =   1.0e-06  !  -      -      -     -
-		   rn_trfac(10)  =   1.0e-06  !  -      -      -     -
-	   	rn_trfac(14)  =   1.0e-06  !  -      -      -     -
-		   rn_trfac(23)  =   7.6e-06  !  -      -      -     -
-		
-	   	cn_dir        =  './'      !  root directory for the location of the data files
-
-:underline:`PISCES forcing files`
-
-They might be on the coarsened grid.
-
-:underline:`Perspectives`
-
-For the future, a few options are on the table to implement coarsening for biogeochemistry in 4.0 and
-future releases.
-Those will be discussed in Autumn 2018
+.. include:: coarsening.rst
 
 ----
 
-Coupling with other models (OASIS, SAS, ...)
-============================================
-
-NEMO currently exploits OASIS-3-MCT to implement a generalised coupled interface
-(`Coupled Formulation <http://forge.ipsl.jussieu.fr/nemo/doxygen/node50.html?doc=NEMO>`_).
-It can be used to interface with most of the European atmospheric GCM (ARPEGE, ECHAM, ECMWF, Ha- dAM, HadGAM, LMDz),
-as well as to WRF (Weather Research and Forecasting Model), and to implement the coupling of
-two independent NEMO components, ocean on one hand and sea-ice plus other surface processes on the other hand
-(`Standalone Surface Module - SAS <http://forge.ipsl.jussieu.fr/nemo/doxygen/node46.html?doc=NEMO>`_).
-
-To enable the OASIS interface the required compilation key is ``key_oasis3``.
-The parameters to set are in sections ``namsbc_cpl`` and in case of using of SAS also in section ``namsbc_sas``.
+.. include:: coupling.rst
 
 ----
 
-With 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 reference 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 reference 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 reference 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 reference 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.
+.. include:: data_assimilation.rst
 
 ----
 
-Inputs-Outputs (using XIOS)
-===========================
+.. include:: input-output.rst
 
-.. contents::
-   :local:
+----
 
-| Output of diagnostics in NEMO is usually done using XIOS.
-  This is an efficient way of writing diagnostics because the time averaging, file writing and even
-  some simple arithmetic or regridding is carried out in parallel to the NEMO model run.
-| This page gives a basic introduction to using XIOS with NEMO.
-  Much more information is available from the XIOS homepage above and from the `NEMO reference manual`_.
-
-Use of XIOS for diagnostics is activated using the pre-compiler key ``key_iomput``.
-The default version of XIOS is the 2.0 release. 
-
-------------------------------
-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.0:
-   
-	.. code-block:: console
-
-		$ svn co ​http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.0 xios-2.0
-
-   and follow the instructions in `XIOS documentation`_ to compile it.
-   If you find problems at this stage, support can be found by subscribing to the `XIOS users mailing list`_ and
-   sending a mail message to it. 
-
----------
-Namelists
----------
-
-XIOS is controlled using xml input files that should be copied to your model run directory before
-running the model.
-The exact setup differs slightly between 1.0 and 2.0 releases.
-
-An ``iodef.xml`` file is still required in the run directory.
-For XIOS 2.0 the ``field_def.xml`` file has been further split into ``field_def-oce.xml`` (for physics),
-``field_def-ice.xml`` (for ice) and ``field_def-bgc.xml`` (for biogeochemistry).
-Also the definition of the output files has been moved from the ``iodef.xml`` file into
-separate ``file_definition.xml`` files which are included in the ``iodef.xml`` file.
-Note that the ``domain_def.xml`` file is also different for XIOS 2.0.
-
------
-Modes
------
-
-Detached Mode
--------------
-
-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:
-
-.. code-block:: xml
-
-	<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.
-
-Attached Mode
--------------
-
-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
-
-.. code-block:: xml
-
-	<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.
-
-------------------------------
-Adding new diagnostics to NEMO
-------------------------------
-
-If you want to add a NEMO diagnostic to the NEMO code you will need to do the following:
-
-1. Add any necessary code to calculate you new diagnostic in NEMO
-2. Send the field to XIOS using ``CALL iom_put( 'field_id', variable )`` where ``field_id`` is a unique id for
-   your new diagnostics and variable is the fortran variable containing the data.
-   This should be called at every model timestep regardless of how often you want to output the field.
-   No time averaging should be done in the model code. 
-3. If it is computationally expensive to calculate your new diagnostic you should also use "iom_use" to
-   determine if it is requested in the current model run. For example,
-   
-	.. code-block:: fortran
-
-		IF iom_use('field_id') THEN
-		   !Some expensive computation
-	   	!...
-		   !...
-	   	iom_put('field_id', variable)
-		ENDIF
-
-4. Add a variable definition to the ``field_def.xml`` (or ``field_def-???.xml``) file
-5. Add the variable to the ``iodef.xml`` or ``file_definition.xml`` file.
-
-.. _NEMO reference manual:   http://forge.ipsl.jussieu.fr/nemo/doxygen/index.html?doc=NEMO
-.. _XIOS documentation:      http://forge.ipsl.jussieu.fr/ioserver/wiki/documentation
-.. _XIOS users mailing list: http://forge.ipsl.jussieu.fr/mailman/listinfo.cgi/xios-users
+.. include:: tracers.rst
Index: NEMO/trunk/doc/rst/source/reference_configurations.rst
===================================================================
--- NEMO/trunk/doc/rst/source/reference_configurations.rst	(revision 10188)
+++ NEMO/trunk/doc/rst/source/reference_configurations.rst	(revision 10201)
@@ -1,364 +1,1 @@
-=====================
-Build a configuration
-=====================
-
-.. contents::
-	:local:
-	:depth: 1
-      
-.. role:: underline 
-   :class: underline
-
-Official configurations
-=======================
-
-| NEMO is distributed with some reference configurations allowing both the user to set up a first application and
-  the developer to validate their developments.
-| :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`_           |
-+----------------------+-----+-----+-----+--------+-------+-------------------------------+
-
-----------
-AGRIF_DEMO
-----------
-
-.. image:: _static/AGRIF_DEMO.jpg
-
-``AGRIF_DEMO`` is based on the ``ORCA2_LIM3_PISCES`` global 2° configuration but
-it includes 3 online nested grids that demonstrate the overall capabilities of AGRIF in a realistic context,
-including nesting sea ice models.
-
-The configuration includes a 1:1 grid in the Pacific and two successively nested grids with odd and
-even refinement ratios over the Arctic ocean.
-The finest grid spanning the whole Svalbard archipelago is of particular interest to check that
-sea ice coupling is done properly.
-The 1:1 grid, used alone, is used as a benchmark to check that the 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.
-One has to switch to a fully explicit in place of a split explicit free surface scheme in order to
-retrieve perfect reproducibility.
-
-Corresponding ``AGRIF_FixedGrids.in`` file is given by::
-
-	2
-	42 82 49 91 1 1 1
-	122 153 110 143 4 4 4
-	0
-	1
-	38 80 71 111 3 3 3
-	0
-
------
-AMM12
------
-
-``AMM12`` for *Atlantic Margin Model 12kms* is a `regional model`_ covering the Northwest European Shelf domain on
-a regular lat-lon grid at approximately 12km horizontal resolution.
-The key ``key_amm_12km`` is used to create the correct dimensions of the AMM domain.
-
-| This configuration tests several features of NEMO functionality specific to the shelf seas.
-| In particular, the AMM uses s-coordinates in the vertical rather than z-coordinates and is forced with
-  tidal lateral boundary conditions using a flather boundary condition from the BDY module (``key_bdy``).
-
-The AMM configuration uses the GLS (``key_zdfgls``) turbulence scheme,
-the VVL non-linear free surface (``key_vvl``) and time-splitting (``key_dynspg_ts``).
-
-In addition to the tidal boundary condition, the model may also take open boundary conditions from
-a North Atlantic model.
-Boundaries may be completely ommited by removing the BDY key (key_bdy) in ``./cfgs/AMM12/cpp_AMM12_fcm``.
-
-Sample surface fluxes, river forcing and a sample initial restart file are included to test a realistic model run.
-The Baltic boundary is included within the river input file and is specified as a river source.
-Unlike ordinary river points the Baltic inputs also include salinity and temperature data.
-
---------
-C1D_PAPA
---------
-
-``C1D_PAPA`` is a 1D configuration (one water column called NEMO1D, activated with CPP key ``key_c1d``),
-located at the `PAPA station 145W-50N <http://www.pmel.noaa.gov/OCS/Papa/index-Papa.shtml>`_.
-
-| NEMO1D is useful to test vertical physics in NEMO
-  (turbulent closure scheme, solar penetration, interaction ocean/atmosphere.,...)
-| Size of the horizontal domain is 3x3 grid points.
-
-This reference configuration uses a 75 vertical levels grid (1m at the surface),
-the GLS (key_zdfgls) turbulence scheme with K-epsilon closure and the CORE BULK formulae.
-The atmospheric forcing comes from ECMWF operational analysis with a modification of the long and short waves flux.
-This set has been rescaled at a frequency of 1h. 1 year is simulated in outputs,
-see below (June,15 2010 to June,14 2011)
-
-`Reffray 2015`_ describes some tests on vertical physic using this configuration.
-
-The inputs tar file includes:
-
-- forcing files covering the years 2010 and 2011 (``forcing_PAPASTATION_1h_y201*.nc``)
-- initialization file for June,15 2010 deduced from observed data and Levitus 2009 climatology
-  (``init_PAPASTATION_m06d15.nc``)
-- surface chlorophyll file (``chlorophyll_PAPASTATION.nc``) deduced from Seawifs data.
-
---------
-GYRE_BFM
---------
-
-``GYRE_BFM`` is the same configuration as `GYRE_PISCES`_, except that PISCES is replaced by
-BFM biogeochemichal model in coupled mode.
-
------------
-GYRE_PISCES
------------
-
-| Idealized configuration representing double gyres in the North hemisphere, Beta-plane with
-  a regular grid spacing at 1° horizontal resolution (and possible use as a benchmark by
-  easily inscreasing grid size), 101 vertical levels, forced with analytical heat, freshwater and
-  wind-stress fields.
-| This configuration is coupled to `PISCES biogeochemical model`_.
-
-Running GYRE as a benchmark
----------------------------
-
-This simple configuration can be used as a benchmark since it is easy to increase resolution
-(and in this case no physical meaning of outputs):
-
-1. Choose the grid size
-
-   In ``./cfgs/GYRE/EXP00``, edit your ``namelist_cfg`` file to change the ``jp_cfg``, ``jpi``, ``jpj``,
-   ``jpk`` variables in &namcfg:
-
-	+------------+---------+---------+---------+------------------+---------------+
-	| ``jp_cfg`` | ``jpi`` | ``jpj`` | ``jpk`` | Number of points | Equivalent to |
-	+============+=========+=========+=========+==================+===============+
-	| 1          | 30      | 20      | 101     | 60600            | GYRE 1°       |
-	+------------+---------+---------+---------+------------------+---------------+
-	| 25         | 750     | 500     | 101     | 37875000         | ORCA 1/2°     |
-	+------------+---------+---------+---------+------------------+---------------+
-	| 50         | 1500    | 1000    | 101     | 151500000        | ORCA 1/4°     |
-	+------------+---------+---------+---------+------------------+---------------+
-	| 150        | 4500    | 3000    | 101     | 1363500000       | ORCA 1/12°    |
-	+------------+---------+---------+---------+------------------+---------------+
-	| 200        | 6000    | 4000    | 101     | 2424000000       | ORCA 1/16°    |
-	+------------+---------+---------+---------+------------------+---------------+
-
-2. In `namelist_cfg` again, avoid problems in the physics (and results will not be meaningful in terms of physics) by setting `nn_bench = 1` in &namctl
-
-.. code-block:: fortran
-   
-   nn_bench    =    1     !  Bench mode (1/0): CAUTION use zero except for bench
-
-3. If you increase domain size, you may need to decrease time-step (for stability) by changing `rn_rdt` value in &namdom (i.e. for `jp_cfg = 150`, ORCA12 equivalent, use `rn_rdt = 1200`)
-
-.. code-block:: fortran
-   
-   rn_rdt      = 1200.     !  time step for the dynamics
-
-4. Optional, in order to increase the number of MPI communication for benchmark purposes:
-   you can change the number of sub-timesteps computed in the time-splitting scheme each iteration.
-   First change the list of active CPP keys for your experiment,
-   in `cfgs/"your configuration name"/cpp_"your configuration name".fcm`:
-   replace ``key_dynspg_flt by key_dynspg_ts`` and recompile/create your executable again
-   
-   .. code-block:: fortran
-   
-   makenemo [...] add_key 'key_dynspg_ts' del_key 'key_dynspg_flt'
-
-In your ``namelist_cfg`` file, edit the &namsplit namelist by adding the following line: 
-
-.. code-block:: fortran
-   
-   nn_baro       =    30               !  Number of iterations of barotropic mode/
-
-``nn_baro = 30`` is a kind of minimum (we usually use 30 to 60).
-So than increasing the ``nn_baro`` value will increase the number of MPI communications.
-
-The GYRE CPP keys, namelists and scripts can be explored in the ``GYRE`` configuration directory
-(``./cfgs/GYRE`` and ``./cfgs/GYRE/EXP00``).
-
-Find `here <http://prodn.idris.fr/thredds/catalog/ipsl_public/reee451/NEMO_OUT/GYRE/catalog.html>`_
-monthly mean outputs of 1 year run
-
-----------------
-ORCA2_ICE_PISCES
-----------------
-
-ORCA is the generic name given to global ocean configurations.
-Its specificity lies on the horizontal curvilinear mesh used to overcome the North Pole singularity found for
-geographical meshes.
-SI3 (Sea Ice Integrated Initiative) is a thermodynamic-dynamic sea ice model specifically designed for
-climate studies.
-A brief description of the model is given here.
-
-:underline:`Space-time domain`
-
-The horizontal resolution available through the standard configuration is ORCA2.
-It is based on a 2 degrees Mercator mesh, (i.e. variation of meridian scale factor as cosinus of the latitude).
-In the northern hemisphere the mesh has two poles so that the ratio of anisotropy is nearly one everywhere.
-The mean grid spacing is about 2/3 of the nominal value: for example it is 1.3 degrees for ORCA2.
-Other resolutions (ORCA4, ORCA05 and ORCA025) are running or under development within specific projects.
-In the coarse resolution version (i.e. ORCA2 and ORCA4) the meridional grid spacing is increased near
-the equator to improve the equatorial dynamics.
-Figures in pdf format of mesh and bathymetry can be found and downloaded here.
-The sea-ice model runs on the same grid.
-
-The vertical domain spreads from the surface to a depth of 5000m.
-There are 31 levels, with 10 levels in the top 100m.
-The vertical mesh is deduced from a mathematical function of z ([[AttachmentNum(1)]]).
-The ocean surface corresponds to the w-level k=1, and the ocean bottom to the w-level k=31.
-The last T-level (k=31) is thus always in the ground.The depths of the vertical levels and
-the associated scale factors can be viewed.
-Higher vertical resolution is used in ORCA025 and ORCA12 (see `DRAKKAR project <http://www.drakkar-ocean.eu>`_).
-
-The time step depends on the resolution. It is 1h36' for ORCA2 so that there is 15 time steps in one day.
-
-:underline:`Ocean Physics (for ORCA2)`
-
-- 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
-  a 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.
-- forcings: the ocean receives heat, freshwater, and momentum fluxes from the atmosphere and/or the sea-ice.
-  The solar radiation penetrates the top meters of the ocean.
-  The downward irradiance I(z) is formulated with two extinction coefficients [Paulson and Simpson, 1977],
-  whose values correspond to a Type I water in Jerlov's classification (i.e the most transparent water)
-
-ORCA2_ICE_PISCES is a reference configuration with the following characteristics:
-
-- global ocean configuration
-- based on a tri-polar ORCA grid, with a 2° horizontal resolution
-- 31 vertical levels
-- forced with climatological surface fields
-- coupled to the sea-ice model SI3.
-- coupled to TOP passive tracer transport module and `PISCES biogeochemical model`_.
-
-:underline:`AGRIF demonstrator`
-
-| From the ``ORCA2_ICE_PISCES`` configuration, a demonstrator using AGRIF nesting can be activated.
-  It includes the global ``ORCA2_ICE_PISCES`` configuration and 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'
-
-- Using the ``ORCA2_ICE_PISCES`` input files and namelist, AGRIF test configuration is ready to run
-
-:underline:`On-The-Fly Interpolation`
-
-| NEMO allows to use the interpolation on the fly option allowing to interpolate input data during the run.
-  If you want to use this option you need files giving informations on weights, which have been created.
-| You can find
-  `here <http://prodn.idris.fr/thredds/catalog/ipsl_public/reee512/ORCA2_ONTHEFLY/WEIGHTS/catalog.html>`_
-  2 weights files `bil_weights` for scalar field (bilinear interpolation) and `bic_weights` for
-  vector field (bicubic interpolation).
-| The data files used are `COREII forcing <http://data1.gdfl.noaa.gov/nomads/forms/mom4/COREv2>`_ extrapolated on
-  continents, ready to be used for on the fly option:
-  `COREII`_ forcing files extrapolated on continents
-
-----------------
-ORCA2_OFF_PISCES
-----------------
-
-``ORCA2_OFF_PISCES`` uses the ORCA2 configuration in which the `PISCES biogeochemical model`_ has been activated in
-standalone using the dynamical fields that are pre calculated.
-
-See `ORCA2_ICE_PISCES`_ for general description of ORCA2.
-
-The input files for PISCES are needed, in addition the dynamical fields are used as input.
-They are coming from a 2000 years of an ORCA2_LIM climatological run using ERA40 atmospheric forcing.
-
--------------
-ORCA2_OFF_TRC
--------------
-
-``ORCA2_OFF_TRC`` uses the ORCA2_LIM configuration in which the tracer passive transport module TOP has been
-activated in standalone using the dynamical fields that are pre calculated.
-
-See `ORCA2_ICE_PISCES`_ for general description of ORCA2.
-
-In ``namelist_top_cfg``, different passive tracers can be activated ( cfc11, cfc12, sf6, c14, age ) or my-trc,
-a user-defined tracer.
-
-The dynamical fields are used as input, they are coming from a 2000 years of an ORCA2_LIM climatological run using
-ERA40 atmospheric forcing.
-
--------------
-ORCA2_SAS_ICE
--------------
-
-``ORCA2_SAS_ICE`` is a demonstrator of the SAS ( Stand-alone Surface module ) based on ORCA2_LIM configuration.
-
-The standalone surface module allows surface elements such as sea-ice, iceberg drift and surface fluxes to
-be run using prescribed model state fields.
-For example, it can be used to inter-compare different bulk formulae or adjust the parameters of
-a given bulk formula
-
-See `ORCA2_ICE_PISCES`_ for general description of ORCA2.
-
-Same input files as `ORCA2_ICE_PISCES`_ are needed plus fields from a previous ORCA2_LIM run.
-
-More informations on input and configuration files in `NEMO Reference manual`_.
-
--------
-SPITZ12
--------
-
-``SPITZ12``
-
-Unsupported configurations
-==========================
-
-Other configurations are developed and used by some projects with "NEMO inside",
-these projects are welcome to publicize it here: http://www.nemo-ocean.eu/projects/add-project
-
-:underline:`Obviously these "projects configurations" are not under the NEMO System Team's responsibility`.
-
-.. _regional model:               http://www.tandfonline.com/doi/pdf/10.1080/1755876X.2012.11020128
-.. _AMM12_v4.0.tar:               http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/AMM12_v4.0.tar
-.. _PISCES biogeochemical model:  http://www.geosci-model-dev.net/8/2465/2015
-.. _INPUTS_PISCES_v4.0.tar:       http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/INPUTS_PISCES_v4.0.tar
-.. _ORCA2_OFF_v4.0.tar:           http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/ORCA2_OFF_v4.0.tar
-.. _ORCA2_ICE_v4.0.tar:           http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/ORCA2_ICE_v4.0.tar
-.. _INPUTS_SAS_v4.0.tar:          http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/INPUTS_SAS_v4.0.tar
-.. _NEMO Reference manual:        http://forge.ipsl.jussieu.fr/nemo/doxygen/index.html?doc=NEMO
-.. _INPUTS_C1D_PAPA_v4.0.tar:     http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/INPUTS_C1D_PAPA_v4.0.tar
-.. _Reffray 2015:                 http://www.geosci-model-dev.net/8/69/2015
-.. _COREII:                       http://prodn.idris.fr/thredds/catalog/ipsl_public/reee512/ORCA2_ONTHEFLY/FILLED_FILES/catalog.html
-.. _SPITZ12_v4.0.tar:             http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/SPITZ12_v4.0.tar
-.. _AGRIF_DEMO_v4.0.tar:          http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/AGRIF_DEMO_v4.0.tar
+link ../../../cfgs/README.rst
Index: NEMO/trunk/doc/rst/source/references.rst
===================================================================
--- NEMO/trunk/doc/rst/source/references.rst	(revision 10188)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../REFERENCES.rst
Index: NEMO/trunk/doc/rst/source/setup_configuration.rst
===================================================================
--- NEMO/trunk/doc/rst/source/setup_configuration.rst	(revision 10188)
+++ NEMO/trunk/doc/rst/source/setup_configuration.rst	(revision 10201)
@@ -1,254 +1,1 @@
-==============================
-Setting up a new configuration
-==============================
-
-.. contents::
-
-Starting from an existing configuration
-=======================================
-
-There are three options to build a new configuration from an existing one:
-
----------------------------------------------
-Option 1: Duplicate an existing configuration
----------------------------------------------
-
-The NEMO so-called Reference Configurations cover a number of major features for NEMO setup
-(global, regional, 1D, using embeded zoom with AGRIF...)
-
-One can create a new configuration by duplicating one of the reference configurations
-(``ORCA2_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
+link ../../../src/OCE/USR/README.rst
Index: NEMO/trunk/doc/rst/source/test_cases.rst
===================================================================
--- NEMO/trunk/doc/rst/source/test_cases.rst	(revision 10188)
+++ NEMO/trunk/doc/rst/source/test_cases.rst	(revision 10201)
@@ -1,23 +1,1 @@
-======================
-Explore the test cases
-======================
-
-- ``tests/ICEDYN``:
-  
-  [Clement to add an illustration here ?]
-
-  This is an East-west + north-south periodic channel.
-  The configuration includes an AGRIF zoom (1:3) in the middle of the basin to test how
-  an ice patch is advected through it but one can also test the advection schemes (Prather and Ultimate-Macho) by
-  removing the ``key_agrif`` in the CPP keys.
-
-- ``tests/VORTEX``:
-  
-  This test case illustrates the propagation of an anticyclonic eddy over a Beta plan and a flat bottom.
-  It is implemented here with an online refined subdomain (1:3) out of which the vortex propagates.
-  It serves as a benchmark for quantitative estimates of nesting errors as in Debreu et al. (2012),
-  Penven et al. (2006) or Spall and Holland (1991).
-  The animation below (sea level anomaly in meters) illustrates with two 1:2 successively nested grids how
-  the vortex smoothly propagates out of the refined grids.
-  
-  .. image:: _static/VORTEX_anim.gif
+link ../../../tests/README.rst
Index: NEMO/trunk/doc/rst/source/tools.rst
===================================================================
--- NEMO/trunk/doc/rst/source/tools.rst	(revision 10201)
+++ NEMO/trunk/doc/rst/source/tools.rst	(revision 10201)
@@ -0,0 +1,1 @@
+link ../../../tools/README.rst
Index: NEMO/trunk/doc/rst/source/tracers.rst
===================================================================
--- NEMO/trunk/doc/rst/source/tracers.rst	(revision 10201)
+++ NEMO/trunk/doc/rst/source/tracers.rst	(revision 10201)
@@ -0,0 +1,1 @@
+link ../../../src/TOP/README.rst
Index: NEMO/trunk/doc/rst/source/zooms.bib
===================================================================
--- NEMO/trunk/doc/rst/source/zooms.bib	(revision 10201)
+++ NEMO/trunk/doc/rst/source/zooms.bib	(revision 10201)
@@ -0,0 +1,1 @@
+link ../../../cfgs/AGRIF_DEMO/zooms.bib
Index: NEMO/trunk/doc/rst/source/zooms.rst
===================================================================
--- NEMO/trunk/doc/rst/source/zooms.rst	(revision 10201)
+++ NEMO/trunk/doc/rst/source/zooms.rst	(revision 10201)
@@ -0,0 +1,1 @@
+link ../../../cfgs/AGRIF_DEMO/README.rst
