Index: NEMO/trunk/INSTALL.rst
===================================================================
--- NEMO/trunk/INSTALL.rst	(revision 10272)
+++ NEMO/trunk/INSTALL.rst	(revision 10279)
@@ -1,9 +1,7 @@
-=====================
+*********************
 Install the framework
-=====================
+*********************
 
-.. include:: .global.rst
-
-.. contents:: \
+.. contents::
 	:local:
       
@@ -24,5 +22,6 @@
 =======================
 
-Download the source code 
+Download the source code
+------------------------
 
 .. code:: console
@@ -31,31 +30,32 @@
 
 Description of directory tree
-=============================
+-----------------------------
 
-+-----------+---------------------------------------------------------------+
-| Folder    | Purpose                                                       |
-+===========+===============================================================+
-| ``arch``  | Settings (per architecture-compiler pair)                     |
-+-----------+---------------------------------------------------------------+
-| ``cfgs``  | Reference configurations                                      |
-+-----------+---------------------------------------------------------------+
-| ``doc``   | - ``latex``: reference manuals for NEMO, SI\ :sup:`3`\  & TOP |
-|           | - ``rst``:   quick start guide                                |
-+-----------+---------------------------------------------------------------+
-| ``ext``   | Dependencies included (AGRIF, FCM & IOIPSL)                   |
-+-----------+---------------------------------------------------------------+
-| ``mk``    | Building  routines                                            |
-+-----------+---------------------------------------------------------------+
-| ``src``   | Modelling routines                                            |
-|           |                                                               |
-|           | - ``ICE``: SI\ :sup:`3`\ for sea ice                          |
-|           | - ``NST``: AGRIF         for embedded zooms                   |
-|           | - ``OCE``: OPA           for ocean dynamics                   |
-|           | - ``MBG``: TOP           for tracers                          |
-+-----------+---------------------------------------------------------------+
-| ``tests`` | Test cases                                                    |
-+-----------+---------------------------------------------------------------+
-| ``tools`` | Utilities to [pre|post]process data                           |
-+-----------+---------------------------------------------------------------+
++-----------+------------------------------------------------------------+
+| Folder    | Purpose                                                    |
++===========+============================================================+
+| ``arch``  | Settings (per architecture-compiler pair)                  |
++-----------+------------------------------------------------------------+
+| ``cfgs``  | :doc:`Reference configurations <configurations>`           |
++-----------+------------------------------------------------------------+
+| ``doc``   | - ``latex``: reference manuals for |OPA|, |SI3| & |TOP|    |
+|           | - ``namelists``: k start guide                             |
+|           | - ``rst``:   quick start guide                             |
++-----------+------------------------------------------------------------+
+| ``ext``   | Dependencies included (AGRIF, FCM & IOIPSL)                |
++-----------+------------------------------------------------------------+
+| ``mk``    | Building  routines                                         |
++-----------+------------------------------------------------------------+
+| ``src``   | Modelling routines                                         |
+|           |                                                            |
+|           | - ``ICE``: |SI3| for sea ice                               |
+|           | - ``NST``: AGRIF for embedded zooms                        |
+|           | - ``OCE``: |OPA| for ocean dynamics                        |
+|           | - ``MBG``: |TOP| for tracers                               |
++-----------+------------------------------------------------------------+
+| ``tests`` | :doc:`Test cases <test_cases>` (unsupported)               |
++-----------+------------------------------------------------------------+
+| ``tools`` | :doc:`Utilities <tools>` to [pre|post]process data         |
++-----------+------------------------------------------------------------+
 
 Extract and install XIOS
@@ -121,5 +121,4 @@
 	.. literalinclude::
 
------------------
 Default behaviour
 -----------------
@@ -128,5 +127,4 @@
     If –n option is not specified, ORCA2_LIM is the default configuration used. 
 
------------------------------
 Tools used during the process
 -----------------------------
@@ -136,5 +134,4 @@
     bld.cfg : FCM rules to compile 
 
---------
 Examples
 --------
@@ -163,7 +160,6 @@
         echo "./makenemo -n MY_CONFIG -j0 add_key \"key_iomput key_mpp_mpi\" del_key \"key_agrif\" ";
 
------------------
 Running the model
------------------
+=================
 
 Once makenemo has run successfully, the opa executable is available in ``CONFIG/MY_CONFIG/EXP00``
@@ -173,7 +169,6 @@
    mpirun -n $NPROCS ./opa    # $NPROCS is the number of processes ; mpirun is your MPI wrapper
 
---------------------------------------------
 Viewing and changing list of active CPP keys
---------------------------------------------
+============================================
 
 For a given configuration (here called MY_CONFIG), the list of active CPP keys can be found in::
Index: NEMO/trunk/README.rst
===================================================================
--- NEMO/trunk/README.rst	(revision 10272)
+++ NEMO/trunk/README.rst	(revision 10279)
@@ -1,10 +1,8 @@
-.. include:: .global.rst
-
+: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 of 
-ocean related engines for oceanographic research, operational oceanography, seasonal forecast and 
-[paleo]climate studies.
+
+`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.
 
 .. contents::
@@ -14,15 +12,14 @@
 ========
 
-Distributed under CeCILL license (GNU GPL compatible - see ``./LICENSE``),
-the NEMO ocean model has 3 major components:
+The NEMO ocean model has 3 major components:
 
-- :rstblue:`OPA` is fundamental to all users by modelling the ocean [thermo]dynamics and 
-  solving the primitive equations         (``./src/OCE``); :cite:`madec_bk08`
-- :rstgrey:`SI`\ :rstgreysup:`3` for sea-ice simulates ice [thermo]dynamics, brine inclusions and 
-  subgrid-scale thickness variations      (``./src/ICE``); :cite:`gmd-8-2991-2015,vancoppenolle200933`
-- :rstgreen:`TOP-PISCES` models biogeochemistry with TOP for the on/offline oceanic tracers transport and 
-  PISCES for the biogeochemical processes (``./src/MBG``). :cite:`gmd-8-2465-2015`
+- |OPA| models the ocean [thermo]dynamics and solves the primitive equations
+  (``./src/OCE``) :cite:`NEMO_manual`;
+- |SI3| simulates ice [thermo]dynamics, brine inclusions and subgrid-scale thickness variations
+  (``./src/ICE``) :cite:`SI3_manual`;
+- |TOP| models the [on|off]line oceanic tracers transport and the biogeochemical processes
+  (``./src/MBG``) :cite:`TOP_manual`.
 
-These physical engines are described in their respective reference publications that must be cited for
+These physical core engines are described in their respective <reference publications> that must be cited for
 any work related to their use.
 
@@ -33,49 +30,60 @@
 it offers various features to enable
 
-- 2-way nesting package `AGRIF`_ to create :doc:`embedded zooms <zooms>` seamlessly
-- Flexible biogeochemistry with :doc:`online coarsening <coarsening>` and
-  opportunity to integrate an :doc:`alternative model <tracers>`
-- Versatile :doc:`data assimilation interface <data_assimilation>`
+- 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.
 
-lation a efficient XIOS_ server for outputing diagnostics a coupled via OASIS_ to alternative components or other models to enable Earth system modelling.
-
-| Several :doc:`builtins configurations <reference_configurations>` are provided to assess the skills and
-	performances of the model which can be used as templates for setting up a new configuration (``./cfgs``).
-| The end user could also find some :doc:`idealised test cases <test_cases>` on the web to serve as examples and
+| Several :doc:`builtins configurations <configurations>` are provided to assess 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
 	to study particular processes (``./tests``).
 
-A set of tools is also provided to setup your own configuration and [pre|post]process your data (``./tools``).
+A set of :doc:`utilities <tools>` is also provided to [pre|post]process your data (``./tools``).
 
 Literature
 ==========
 
-| The NEMO reference manual and a quick start guide can be generated from Latex and RST source code files
-	(``./doc``), either in PDF or in HTML format, but it might require some additional installations.
-| In any case, both formats are available online: `HTML`_ | `PDF`_
+:doc:`install`
 
-| Since 2014 the project has a `Special Issue`_ in the open-access journal Geoscientific Model Development (GMD) 
-	from the European Geosciences Union (EGU).
-	The main scope is to collect relevant manuscripts which cover a wide variety of topics like
-	process studies, new parameterizations, implementation of new model features and new NEMO configurations.
-| Also it provides a single portal to search, discover and understand about
-	the NEMO modelling framework potential and evolution and to submit their contributions. 
+The reference documentation is archived online
+
++-------+-------------------+----------------+
+|       | Reference manual  | |NEMO manual|_ |
+| |OPA| +-------------------+----------------+
+|       | Quick start guide | |NEMO guide|_  |
++-------+-------------------+----------------+
+| |SI3|                     | |SI3 manual|_  |
++---------------------------+----------------+
+| |TOP|                     | |TOP manual|_  |
++---------------------------+----------------+
+
+.. |NEMO manual| image:: http://zenodo.org/badge/DOI/10.5281/zenodo.1464816.svg
+.. |NEMO guide|  image:: http://zenodo.org/badge/DOI/10.5281/zenodo.1475325.svg
+.. |SI3 manual|  image:: http://zenodo.org/badge/DOI/10.5281/zenodo.1471689.svg
+.. |TOP manual|  image:: http://zenodo.org/badge/DOI/10.5281/zenodo.1471700.svg
+
+| Reference manuals and quick start guide can be build from source and exported to HTML or PDF (``./doc``).
+| In any case, one can find them online:
+
+Since 2014 the project has a `Special Issue <http://www.geosci-model-dev.net/special_issue40.html>`_ in
+the open-access journal Geoscientific Model Development (GMD) from the European Geosciences Union (EGU).
+The main scope is to collect relevant manuscripts covering various topics and to provide a single portal to
+assess the model potential and evolution.
+
+Used by a wide audience, numerous :website:`associated projects <projects>` have been carried out and
+extensive :website:`bibliography <bibliography/publications>` published.
 
 Community development
 =====================
 
-| The NEMO Consortium gathering 6 European institutes (`CMCC`_, `CNRS`_, `MOI`_, `Met Office`_ and `NERC`_)
-	organises the sustainable development in order to keep a reliable evolving system since 2008.
-| It defines the multi-year development strategy which is implemented by the NEMO System Team.
+| The NEMO Consortium pulling together 5 European institutes (`CMCC`_, `CNRS`_, `MOI`_, `Met Office`_ and `NERC`_)
+	plans the sustainable development in order to keep a reliable evolving framework since 2008.
+| It defines the |NEMO strategy|_ which is implemented by the System Team on
+	a yearly basis in	order to release a new version almost every four years.
 
-When the need arises, `Working Groups`_ are created or resumed to gather the expertise in the community in order to
-focus the development work on a specific subject or major component of the framework.
+.. |NEMO strategy| replace:: multi-year development strategy
 
-How to cite NEMO
-================
-
-..	bibliography:: references.bib
-	:all:
-	:style: unsrt
-
-.. _HTML:           http://www.nemo-ocean.eu/doc
-.. _PDF:            http://www.nemo-ocean.eu/wp-content/uploads/NEMO_book.pdf
+When the need arises, :forge:`working groups <wiki/WorkingGroups>` are created or resumed to
+gather the community expertise for advising on the development activities.
Index: NEMO/trunk/REFERENCES.bib
===================================================================
--- NEMO/trunk/REFERENCES.bib	(revision 10272)
+++ NEMO/trunk/REFERENCES.bib	(revision 10279)
@@ -1,19 +1,58 @@
-@Book{madec_bk08,
-   title = {NEMO ocean engine},
-   publisher = {Note du P\^ole de mod{\'e}lisation, Institut Pierre-Simon Laplace
-   (IPSL), France, No 27, ISSN No 1288-1619},
-   year = {2008},
-   author = {G. Madec and NEMO System Team}
+@manual{NEMO_manual,
+   title={NEMO ocean engine},
+   author={Madec Gurvan and NEMO System Team},
+   organization={NEMO Consortium},
+   journal={Notes du Pôle de modélisation de l\'Institut Pierre-Simon Laplace (IPSL)},
+   number={27},
+   publisher={Zenodo},
+   abstract={The ocean engine of NEMO is a primitive equation model adapted to regional and
+   global ocean circulation problems.
+   It is intended to be a flexible tool for studying the ocean and its interactions with
+   the others components of the earth climate system over a wide range of space and time scales.},
+   doi={10.5281/zenodo.1464816},
+   edition={},
+   year={}
 }
 
-@Article{gmd-8-2465-2015,
-   author = {Aumont, O. and Eth\'e, C. and Tagliabue, A. and Bopp, L. and Gehlen, M.},
-   title = {{PISCES}-v2: an ocean biogeochemical model for carbon and ecosystem studies},
-   journal = {Geoscientific Model Development},
-   volume = {8},
-   year = {2015},
-   number = {8},
-   pages = {2465--2513},
-   doi = {10.5194/gmd-8-2465-2015}
+@manual{SI3_manual,
+   title={SI³ – Sea Ice modelling Integrated Initiative – The NEMO Sea Ice engine},
+   author={NEMO Sea Ice Working Group},
+   organization={NEMO Consortium},
+   journal={Notes du Pôle de modélisation de l\'Institut Pierre-Simon Laplace (IPSL)},
+   number={31},
+   publisher={Zenodo},
+   abstract={SI³ (Sea Ice modelling Integrated Initiative) is the sea ice engine of NEMO
+   (Nucleus for European Modelling of the Ocean).
+   It is adapted to regional and global sea ice and climate problems.
+   It is intended to be a flexible tool for studying sea ice and its interactions with
+   the other components of the Earth System over a wide range of space and time scales.
+   SI3 is based on the Arctic Ice Dynamics Joint EXperiment (AIDJEX) framework,
+   combining the ice thickness distribution framework, the conservation of horizontal momentum,
+   an elastic-viscous plastic rheology, and energy-conserving halo-thermodynamics.
+   Prognostic variables are the two-dimensional horizontal velocity field, ice volume, area, enthalpy,
+   salt content, snow volume and enthalpy.
+   In the horizontal direction, the model uses a curvilinear orthogonal grid.
+   In the vertical direction, the model uses equally-spaced layers.
+   In thickness space, the model uses thickness categories with prescribed boundaries.
+   Various physical and numerical choices are available to describe sea ice physics.
+   SI3 is interfaced with the NEMO ocean engine, and, via the OASIS coupler, with
+   several atmospheric general circulation models.
+   It also supports two-way grid embedding via the AGRIF software.},
+   doi={10.5281/zenodo.1471689},
+   edition={},
+   year={}
+}
+
+@manual{TOP_manual,
+   title={TOP – Tracers in Ocean Paradigm – The NEMO Tracers engine},
+   author={NEMO TOP Working Group},
+   organization={NEMO Consortium},
+   journal={Notes du Pôle de modélisation de l\'Institut Pierre-Simon Laplace (IPSL)},
+   number={28},
+   publisher={Zenodo},
+   abstract={},
+   doi={10.5281/zenodo.1471700},
+   edition={},
+   year={}
 }
 
@@ -28,26 +67,2 @@
    doi = {10.5194/gmd-8-1245-2015}
 }
-
-@Article{gmd-8-2991-2015,
-   author = {Rousset, C. and Vancoppenolle, M. and Madec, G. and Fichefet, T. and Flavoni, S. and Barth\'elemy, A. and Benshila, R. and Chanut, J. and Levy, C. and Masson, S. and Vivier, F.},
-   title = {The {L}ouvain-la-{N}euve sea ice model {LIM}3.6: global and regional capabilities},
-   journal = {Geoscientific Model Development},
-   volume = {8},
-   year = {2015},
-   number = {10},
-   pages = {2991--3005},
-   doi = {10.5194/gmd-8-2991-2015}
-}
-
-@Article{vancoppenolle200933,
-   title = "Simulating the mass balance and salinity of Arctic and Antarctic sea ice. 1. Model description and validation",
-   journal = "Ocean Modelling",
-   volume = "27",
-   number = "1–2",
-   pages = "33 - 53",
-   year = "2009",
-   issn = "1463-5003",
-   doi = "10.1016/j.ocemod.2008.10.005",
-   author = "Martin Vancoppenolle and Thierry Fichefet and Hugues Goosse and Sylvain Bouillon and Gurvan Madec and Miguel Angel Morales Maqueda",
-   keywords = "sea ice, model, thickness, salinity, age, arctic, antarctic"
-}
Index: NEMO/trunk/RELEASE_NOTES.rst
===================================================================
--- NEMO/trunk/RELEASE_NOTES.rst	(revision 10272)
+++ NEMO/trunk/RELEASE_NOTES.rst	(revision 10279)
@@ -1,7 +1,5 @@
-======================
+**********************
 What's new in NEMO 4.0
-======================
-
-.. include:: .global.rst
+**********************
 
 .. contents::
@@ -208,4 +206,5 @@
 .. _TOP User Quick Guide:        http://forge.ipsl.jussieu.fr/nemo/wiki/WorkingGroups/top-dg/TOP-UserQuickGuide
 
+.. The following references should be in the manual bibliographies and referenced via 'bibliography' directive
 .. _Brodeau 2017:                http://doi.org/10.1175/JPO-D-16-0169.1
 .. _Holland 2012:                http://doi.org/10.1175/JCLI-D-11-00078.1
Index: NEMO/trunk/cfgs/AGRIF_DEMO/README.rst
===================================================================
--- NEMO/trunk/cfgs/AGRIF_DEMO/README.rst	(revision 10272)
+++ NEMO/trunk/cfgs/AGRIF_DEMO/README.rst	(revision 10279)
@@ -1,13 +1,11 @@
-Embedded zooms with AGRIF
-=========================
-
-.. include:: .global.rst
+**********************
+Embedded zooms (AGRIF)
+**********************
 
 .. contents::
    :local:
 
---------
 Overview
---------
+========
 
 AGRIF (Adaptive Grid Refinement In Fortran) is a library that allows the seamless space and time refinement over
@@ -19,7 +17,6 @@
 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: 
@@ -34,7 +31,6 @@
 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.
@@ -68,7 +64,6 @@
 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
@@ -79,7 +74,6 @@
 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
@@ -104,9 +98,10 @@
 2 x refinement factor (from i=1+nbghostcells+1 to i=1+nbghostcells+sponge_area) 
 
-----------
 References
-----------
+==========
 
 .. bibliography:: zooms.bib
 	:all:
 	:style: unsrt
+	:labelprefix: A
+	:keyprefix: a-
Index: NEMO/trunk/cfgs/AGRIF_DEMO/zooms.bib
===================================================================
--- NEMO/trunk/cfgs/AGRIF_DEMO/zooms.bib	(revision 10272)
+++ NEMO/trunk/cfgs/AGRIF_DEMO/zooms.bib	(revision 10279)
@@ -1,3 +1,3 @@
-@article{DEBREU20121,
+@article{DEBREU2012,
    title = "Two-way nesting in split-explicit ocean models: Algorithms, implementation and validation",
    journal = "Ocean Modelling",
@@ -11,5 +11,5 @@
 }
 
-@article{PENVEN2006157,
+@article{PENVEN2006,
    title = "Evaluation and application of the {ROMS} 1-way embedding procedure to the central california upwelling system",
    journal = "Ocean Modelling",
@@ -24,5 +24,5 @@
 }
 
-@article{doi:10.1175/1520-0485(1991)021<0205:ANPEMF>2.0.CO;2,
+@article{SPALL1991,
    author = {Spall, Michael A. and Holland, William R.},
    title = {A Nested Primitive Equation Model for Oceanic Applications},
Index: NEMO/trunk/cfgs/README.rst
===================================================================
--- NEMO/trunk/cfgs/README.rst	(revision 10272)
+++ NEMO/trunk/cfgs/README.rst	(revision 10279)
@@ -1,7 +1,5 @@
-=====================
-Build a configuration
-=====================
-
-.. include:: .global.rst
+*****************************
+Run a reference configuration
+*****************************
 
 .. contents::
@@ -9,7 +7,4 @@
 	:depth: 1
       
-.. role:: underline 
-   :class: underline
-
 Official configurations
 =======================
@@ -47,5 +42,4 @@
 +----------------------+-----+-----+-----+--------+-------+-------------------------------+
 
-----------
 AGRIF_DEMO
 ----------
@@ -78,5 +72,4 @@
 	0
 
------
 AMM12
 -----
@@ -101,5 +94,4 @@
 Unlike ordinary river points the Baltic inputs also include salinity and temperature data.
 
---------
 C1D_PAPA
 --------
@@ -127,5 +119,4 @@
 - surface chlorophyll file (``chlorophyll_PAPASTATION.nc``) deduced from Seawifs data.
 
---------
 GYRE_BFM
 --------
@@ -134,5 +125,4 @@
 BFM biogeochemichal model in coupled mode.
 
------------
 GYRE_PISCES
 -----------
@@ -145,5 +135,5 @@
 
 Running GYRE as a benchmark
----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This simple configuration can be used as a benchmark since it is easy to increase resolution
@@ -206,5 +196,4 @@
 http://prodn.idris.fr/thredds/catalog/ipsl_public/reee451/NEMO_OUT/GYRE/catalog.html
 
-----------------
 ORCA2_ICE_PISCES
 ----------------
@@ -293,5 +282,4 @@
   `COREII`_ forcing files extrapolated on continents
 
-----------------
 ORCA2_OFF_PISCES
 ----------------
@@ -305,5 +293,4 @@
 They are coming from a 2000 years of an ORCA2_LIM climatological run using ERA40 atmospheric forcing.
 
--------------
 ORCA2_OFF_TRC
 -------------
@@ -320,5 +307,4 @@
 ERA40 atmospheric forcing.
 
--------------
 ORCA2_SAS_ICE
 -------------
@@ -335,7 +321,6 @@
 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`_.
-
--------
+More informations on input and configuration files in `NEMO manual`_.
+
 SPITZ12
 -------
@@ -358,5 +343,4 @@
 .. _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
Index: NEMO/trunk/cfgs/SHARED/README.rst
===================================================================
--- NEMO/trunk/cfgs/SHARED/README.rst	(revision 10272)
+++ NEMO/trunk/cfgs/SHARED/README.rst	(revision 10279)
@@ -1,8 +1,8 @@
-Inputs-Outputs with XIOS
-========================
-
-.. include:: .global.rst
+******************
+Diagnostics (XIOS)
+******************
 
 .. contents::
+	:local:
 
 | Output of diagnostics in NEMO is usually done using XIOS.
@@ -10,12 +10,11 @@
   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 `Reference Manual`_.
+  Much more information is available from the XIOS homepage above and from the `NEMO 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.
@@ -28,11 +27,11 @@
 		$ 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. 
+	and follow the instructions in :xios:`XIOS documentation <wiki/documentation>` to compile it.
+	If you find problems at this stage, support can be found by subscribing to the `XIOS mailing list
+	<http://forge.ipsl.jussieu.fr/mailman/listinfo.cgi/xios-users>`_
+	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
@@ -47,7 +46,6 @@
 Note that the ``domain_def.xml`` file is also different for XIOS 2.0.
 
------
 Modes
------
+=====
 
 Detached Mode
@@ -81,7 +79,6 @@
 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
-------------------------------
+Adding new diagnostics
+======================
 
 If you want to add a NEMO diagnostic to the NEMO code you will need to do the following:
Index: NEMO/trunk/doc/rst/source/.global.rst
===================================================================
--- NEMO/trunk/doc/rst/source/.global.rst	(revision 10272)
+++ 	(revision )
@@ -1,35 +1,0 @@
-.. 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 10272)
+++ NEMO/trunk/doc/rst/source/NEMO_guide.rst	(revision 10279)
@@ -1,7 +1,2 @@
-.. NEMO documentation master file, created by
-   sphinx-quickstart on Tue Oct  9 18:14:01 2018.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 #################
 Quick Start Guide
@@ -9,28 +4,5 @@
 
 ..
-	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::
-	:maxdepth: 1
-	:titlesonly:
-
-	release_notes.rst
-	install.rst
-	reference_configurations.rst
-	test_cases.rst
-	setup_configuration.rst
-	interfacing_options.rst
-	definitions.rst
-
-..
-   For headings markup, this convention is recommended from Python’s Style Guide
+	For headings markup, this convention is recommended from Python’s Style Guide
 	# with overline, for parts
 	* with overline, for chapters
@@ -40,8 +12,63 @@
 	", for paragraphs
 
-..
-	Indices and tables
-	==================
-	* :ref:`genindex`
-	* :ref:`modindex`
-	* :ref:`search`
+	'global.rst' contains a list of common directives (roles, substitutions and URL links)
+	It is loaded for each file thanks to 'rst_epilog' setting in 'conf.py'
+
+.. toctree::
+	:hidden:
+
+	release_notes.rst
+
+.. toctree::
+	:hidden:
+	:caption: Getting started
+
+	install
+	configurations
+	test_cases
+
+.. toctree::
+	:hidden:
+	:caption: Setup your configuration
+
+	setup
+	diagnostics
+	tools
+
+.. toctree::
+	:hidden:
+	:caption: Advanced use
+
+	zooms
+	coarsening
+	coupling
+	assimilation
+	tracers
+
+.. toctree::
+	:hidden:
+	:caption: Glossary
+
+	definitions
+
+.. include:: readme.rst
+
+.. Next headings markup acording to readme.rst
+
+How to cite NEMO
+================
+
+..	bibliography:: references.bib
+	:all:
+	:style: unsrt
+	:labelprefix: R
+
+Disclaimer
+==========
+
+The NEMO source code is freely available and distributed under CeCILL license
+(GNU GPL compatible - see ``./LICENSE``).
+
+You can use, modify and/or redistribute the software under its terms,
+but users are provided only with a limited warranty and the software's authors and
+the successive licensor's have only limited liability.
Index: NEMO/trunk/doc/rst/source/_static/style.css
===================================================================
--- NEMO/trunk/doc/rst/source/_static/style.css	(revision 10279)
+++ NEMO/trunk/doc/rst/source/_static/style.css	(revision 10279)
@@ -0,0 +1,5 @@
+.rstblue               { color: blue    ; }
+.rstgrey , .rstgreysup { color: grey    ; }
+.rstgreen              { color: seagreen; }
+
+.logo { filter: invert(1) !important; }
Index: NEMO/trunk/doc/rst/source/_templates/layout.html
===================================================================
--- NEMO/trunk/doc/rst/source/_templates/layout.html	(revision 10279)
+++ NEMO/trunk/doc/rst/source/_templates/layout.html	(revision 10279)
@@ -0,0 +1,18 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+	<link href="{{ pathto("_static/style.css", True) }}" rel="stylesheet" type="text/css">
+{% endblock %}
+
+{% block sidebartitle %}
+
+	<a href="{{ pathto(master_doc) }}">
+		<img src="{{ pathto('_static/NEMO_grey.png', 1) }}" class="logo" alt="Logo"/>
+	</a>
+
+	<p>Community ocean model for multifarious space and time scales</p>
+
+	<div class="version">{{ release }}</div>
+
+	{% include "searchbox.html" %}
+
+{% endblock %}
Index: NEMO/trunk/doc/rst/source/assimilation.rst
===================================================================
--- NEMO/trunk/doc/rst/source/assimilation.rst	(revision 10279)
+++ NEMO/trunk/doc/rst/source/assimilation.rst	(revision 10279)
@@ -0,0 +1,60 @@
+**************************************
+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 10272)
+++ NEMO/trunk/doc/rst/source/conf.py	(revision 10279)
@@ -21,5 +21,5 @@
 
 project = 'NEMO'
-copyright = '2018, NEMO System Team'
+copyright = ''
 author = 'NEMO System Team'
 
@@ -39,5 +39,5 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinxcontrib.bibtex']
+extensions = ['sphinx.ext.extlinks', 'sphinxcontrib.bibtex']
 
 # Add any paths that contain templates here, relative to this directory.
@@ -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 = []
+exclude_patterns = ['global.rst']
 
 # The name of the Pygments (syntax highlighting) style to use.
@@ -74,5 +74,6 @@
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+#html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
@@ -81,11 +82,8 @@
 #
 html_theme_options = {
-    'logo': 'NEMO_grey.png',
-    'description': 'Community ocean model for multifarious space and time scales',
-    'fixed_sidebar': 'true',
-#    'github_user': 'NEMO-ocean',
-#    'github_repo': 'NEMO-examples',
-#    'github_button': 'true',
-#    'github_banner': 'true'
+#	Alabaster theme options
+#	'logo': 'NEMO_grey.png',
+#	'description': 'Community ocean model for multifarious space and time scales',
+#	'fixed_sidebar': True,
 }
 
@@ -162,2 +160,22 @@
      'Miscellaneous'),
 ]
+
+
+# -- Customisation -----------------------------------------------------------
+
+import datetime
+year = datetime.date.today().year
+copyright = '2008-' + str( year ) + ', NEMO Consortium'
+
+# Link aliases
+extlinks = {
+	'doi'    : ('http://doi.org/%s'                       , None),
+	'forge'  : ('http://forge.ipsl.jussieu.fr/nemo/%s'    , None),
+	'github' : ('http://github.com/%s'                    , None),
+	'xios'   : ('http://forge.ipsl.jussieu.fr/ioserver/%s', None),
+	'website': ('http://www.nemo-ocean.eu/%s'             , None),
+	'zenodo' : ('http://zenodo.org/publication/%s'        , None)
+}
+
+# Include common directives for every rst file
+rst_epilog = open('global.rst', 'r').read()
Index: NEMO/trunk/doc/rst/source/configurations.rst
===================================================================
--- NEMO/trunk/doc/rst/source/configurations.rst	(revision 10279)
+++ NEMO/trunk/doc/rst/source/configurations.rst	(revision 10279)
@@ -0,0 +1,1 @@
+link ../../../cfgs/README.rst
Index: NEMO/trunk/doc/rst/source/coupling.rst
===================================================================
--- NEMO/trunk/doc/rst/source/coupling.rst	(revision 10272)
+++ NEMO/trunk/doc/rst/source/coupling.rst	(revision 10279)
@@ -1,6 +1,5 @@
-Coupling with other models (OASIS, SAS, ...)
-============================================
-
-.. include:: .global.rst
+**********************
+Coupling (OASIS & SAS)
+**********************
 
 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 10272)
+++ 	(revision )
@@ -1,66 +1,0 @@
-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 10272)
+++ NEMO/trunk/doc/rst/source/definitions.rst	(revision 10279)
@@ -1,9 +1,7 @@
-===========
+***********
 Definitions
-===========
+***********
 
-.. include:: .global.rst
-
-AGRIF
+`AGRIF`_
 	*Adaptive Grid Refinement In Fortran*, 
 	package for the integration of full adaptive mesh refinement features within 
@@ -14,5 +12,5 @@
 	unified sea ice model merging functionalities from CICE, GELATO and LIM into the NEMO framework
 
-OASIS
+`OASIS`_
 	*Ocean Atmosphere Sea Ice Soil*, 
 	coupling software to synchronise numerical codes representing different components of the climate system
@@ -31,5 +29,5 @@
 	on/off-line oceanic tracers transport and biogeochemistry models
 
-XIOS
+`XIOS`_
 	*XML Input Output Server*, 
 	library dedicated to input/output management of climate code
Index: NEMO/trunk/doc/rst/source/diagnostics.rst
===================================================================
--- NEMO/trunk/doc/rst/source/diagnostics.rst	(revision 10279)
+++ NEMO/trunk/doc/rst/source/diagnostics.rst	(revision 10279)
@@ -0,0 +1,1 @@
+link ../../../cfgs/SHARED/README.rst
Index: NEMO/trunk/doc/rst/source/global.rst
===================================================================
--- NEMO/trunk/doc/rst/source/global.rst	(revision 10279)
+++ NEMO/trunk/doc/rst/source/global.rst	(revision 10279)
@@ -0,0 +1,38 @@
+.. Roles (custom styles related to CSS classes in 'source/_static/style.css')
+
+.. role:: rstblue
+.. role:: rstgreen
+.. role:: rstgrey
+.. role:: rstgreysup(sup)
+.. role:: underline 
+   :class: underline
+
+.. Substitutions
+
+.. |OPA| replace:: :rstblue:`NEMO-OPA`
+.. |SI3| replace:: :rstgrey:`NEMO-SI`\ :rstgreysup:`3`
+.. |TOP| replace:: :rstgreen:`NEMO-TOP/PISCES`
+
+.. 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
+.. _XIOS:  http://forge.ipsl.jussieu.fr/ioserver
+
+.. NEMO
+
+.. _NEMO:          http://www.nemo-ocean.eu
+.. _NEMO strategy: http://doi.org/10.5281/zenodo.1471663
+.. _NEMO guide:    http://doi.org/10.5281/zenodo.1475325
+.. _NEMO manual:   http://doi.org/10.5281/zenodo.1464816
+.. _SI3 manual:    http://doi.org/10.5281/zenodo.1471689
+.. _TOP manual:    http://doi.org/10.5281/zenodo.1471700
Index: NEMO/trunk/doc/rst/source/input-output.rst
===================================================================
--- NEMO/trunk/doc/rst/source/input-output.rst	(revision 10272)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../cfgs/SHARED/README.rst
Index: NEMO/trunk/doc/rst/source/interfacing_options.rst
===================================================================
--- NEMO/trunk/doc/rst/source/interfacing_options.rst	(revision 10272)
+++ NEMO/trunk/doc/rst/source/interfacing_options.rst	(revision 10279)
@@ -3,11 +3,16 @@
 ===================
 
-.. include:: .global.rst
-
-.. contents::
+..
+	contents::
 	:local:
 	:depth: 1
 
 .. include:: zooms.rst
+
+.. bibliography:: zooms.bib
+	:all:
+	:style: unsrt
+	:labelprefix: A
+	:keyprefix: a-
 
 ----
@@ -21,5 +26,5 @@
 ----
 
-.. include:: data_assimilation.rst
+.. include:: assimilation.rst
 
 ----
Index: NEMO/trunk/doc/rst/source/reference_configurations.rst
===================================================================
--- NEMO/trunk/doc/rst/source/reference_configurations.rst	(revision 10272)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../cfgs/README.rst
Index: NEMO/trunk/doc/rst/source/setup.rst
===================================================================
--- NEMO/trunk/doc/rst/source/setup.rst	(revision 10279)
+++ NEMO/trunk/doc/rst/source/setup.rst	(revision 10279)
@@ -0,0 +1,249 @@
+******************************
+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
Index: NEMO/trunk/doc/rst/source/setup_configuration.rst
===================================================================
--- NEMO/trunk/doc/rst/source/setup_configuration.rst	(revision 10272)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../src/OCE/USR/README.rst
Index: NEMO/trunk/src/OCE/CRS/README.rst
===================================================================
--- NEMO/trunk/src/OCE/CRS/README.rst	(revision 10272)
+++ NEMO/trunk/src/OCE/CRS/README.rst	(revision 10279)
@@ -1,16 +1,11 @@
+**********************************
 On line biogeochemistry coarsening
-==================================
-
-.. include:: .global.rst
+**********************************
 
 .. contents::
    :local:
 
-.. role:: underline 
-   :class: underline
-
-------------
 Presentation
-------------
+============
 
 A capacity of coarsening physics to force a BGC model coupled to NEMO has been developed.
@@ -20,19 +15,16 @@
 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]
@@ -40,9 +32,19 @@
 ''should include precise explanation on MPI decomposition problems too''
 
----------------------------------------------
 How to set up and use on line biogeochemistry
----------------------------------------------
+=============================================
 
-:underline:`How to activate coarsening?`
+Extract the on line biogeochemistry branch
+------------------------------------------
+
+To get the appropriate source code with the on line coarsening of biogeochemistry feature:
+
+.. code-block:: console
+
+	$ svn co https://forge.ipsl.jussieu.fr/nemo/browser/NEMO/branches/2018/dev_r5003_MERCATOR6_CRS
+
+
+How to activate coarsening?
+---------------------------
 
 To activate the coarsening, ``key_crs`` should be added to list of CPP keys.
@@ -83,5 +85,6 @@
   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`
+Choice of operator to coarsene KZ
+---------------------------------
 
 A sensiblity test has been done with an Age tracer to compare the different operators.
@@ -90,5 +93,6 @@
 Some results can be found [xxx here]
 
-:underline:`Example of xml files to output coarsened variables with XIOS`
+Example of xml files to output coarsened variables with XIOS
+------------------------------------------------------------
 
 In the [attachment:iodef.xml iodef.xml]  file, a "nemo" context is defined and
@@ -98,5 +102,6 @@
 the associated variable are listed in [attachment:file_crs_def.xml file_crs_def.xml ].
 
-:underline:`Passive tracers tracers initial conditions`
+Passive tracers tracers initial conditions
+------------------------------------------
 
 When initial conditions are provided in NetCDF files, the field might be:
@@ -132,9 +137,11 @@
 	   	cn_dir        =  './'      !  root directory for the location of the data files
 
-:underline:`PISCES forcing files`
+PISCES forcing files
+--------------------
 
 They might be on the coarsened grid.
 
-:underline:`Perspectives`
+Perspectives
+============
 
 For the future, a few options are on the table to implement coarsening for biogeochemistry in 4.0 and
Index: NEMO/trunk/src/TOP/README.rst
===================================================================
--- NEMO/trunk/src/TOP/README.rst	(revision 10272)
+++ NEMO/trunk/src/TOP/README.rst	(revision 10279)
@@ -1,6 +1,5 @@
-TOP interface
-=============
-
-.. include:: .global.rst
+*********************
+Oceanic tracers (TOP)
+*********************
 
 .. contents::
@@ -17,7 +16,6 @@
 up to the full set of equations involving marine biogeochemical cycles.
 
----------
 Structure
----------
+=========
 
 TOP interface has the following location in the source code ``./src/MBG/`` and
@@ -73,7 +71,6 @@
 	trend computation for tracers
 
-------------------
 Synthetic Workflow
-------------------
+==================
 
 A synthetic description of the TOP interface workflow is given below to summarize the steps involved in
@@ -125,7 +122,6 @@
   ↳ call trc_rst_wri, output tracers restart files
 
----------------------
 Namelists walkthrough
----------------------
+=====================
 
 namelist_top
@@ -235,7 +231,6 @@
 |||| &'''namc14_fcg'''     !  files & dates ||
 
------------------------------------------------------
 ``MY_TRC`` interface for coupling external BGC models
------------------------------------------------------
+=====================================================
 
 The generalized interface is pivoted on MY_TRC module that contains template files to build the coupling between
@@ -277,7 +272,6 @@
 	if not done elsewhere in the code, using the call to iom_put.
 
----------------------------------------------------
 Coupling an external BGC model using NEMO framework
----------------------------------------------------
+===================================================
 
 The coupling with an external BGC model through the NEMO compilation framework can be achieved in
Index: NEMO/trunk/tests/README.rst
===================================================================
--- NEMO/trunk/tests/README.rst	(revision 10272)
+++ NEMO/trunk/tests/README.rst	(revision 10279)
@@ -1,13 +1,16 @@
-======================
+**********************
 Explore the test cases
-======================
+**********************
+
+.. contents::
+	:local:
+
+List
+====
 
   The description below is a brief description of the test cases available in NEMO. 
-  For detailed description and notebook, the reader is directed on the `Github repository`_
-
-.. _Github repository:   https://github.com/sflavoni/NEMO-test-cases/
 
 ICEDYN
-======
+------
   
   This test case illustrates the advection of an ice patch across a East/West and North/South periodic channel. 
@@ -19,5 +22,5 @@
 
 VORTEX
-======
+------
   
   This test case illustrates the propagation of an anticyclonic eddy over a Beta plan and a flat bottom.
@@ -32,5 +35,5 @@
 
 ISOMIP
-======
+------
 
   The purpose of this test case is to evaluate the impact of various schemes and new development with the iceshelf cavities circulation and melt.
@@ -43,5 +46,5 @@
 
 LOCK_EXCHANGE
-=============
+-------------
 
   The LOCK EXCHANGE experiment is a classical fluid dynamics experiment that has been adapted
@@ -56,5 +59,5 @@
 
 OVERFLOW
-========
+--------
 
   The OVERFLOW experiment illustrates the impact of different choices of numerical schemes 
@@ -69,5 +72,5 @@
 
 WAD
-===
+---
 
   A set of simple closed basin geometries for testing the Wetting and drying capabilities. 
@@ -81,5 +84,5 @@
 
 CANAL
-=====
+-----
 
   East-west periodic canal of variable size with several initial states and associated geostrophic currents (zonal jets or vortex).
@@ -87,10 +90,9 @@
   .. image::_static/CANAL_image.gif
 
-==================
 Compile test cases
 ==================
+
 The compilation of the test cases is very similar to the manner the reference configurations are compiled.
-If you are not familiar on how to compile NEMO, it is first recomended to read the instruction 
-`here <http://forge.ipsl.jussieu.fr/nemo/wiki/Users/ModelInstall>`_
+If you are not familiar on how to compile NEMO, it is first recomended to read :doc:`the instructions <install>`
 
 | In the same manner as the ref. cfg are compiled with '-r' option, test cases can be compile by the use of makenemo with '-a' option.
@@ -99,18 +101,19 @@
 
 .. code-block:: console
-                   
-        $ ./makenemo -n WAD2 -a WAD -m macport_osx -j 4
+ 
+	$ ./makenemo -n WAD2 -a WAD -m macport_osx -j 4
 
-=====================================
 Run and analyse the test cases
-=====================================
+==============================
+
 There no requirement of specific input file for the test_cases presented here. The XIOS xml input files and namelist are already setup correctly. 
-All the detailed on how to run a specific test cases and Jupyter notebook are available on github `here <https://github.com/sflavoni/NEMO-test-cases>`_.
+For detailed description and Jupyter notebook, the reader is directed on
+the `NEMO test cases repository <http://github.com/NEMO-ocean/NEMO-examples>`_
 
-==========
 References
 ==========
 
-..      bibliography:: test_cases.bib
-                :all:
-        :style: unsrt
+.. bibliography:: test_cases.bib
+	:all:
+	:style: unsrt
+	:labelprefix: T
