Index: /NEMO/trunk/README.rst
===================================================================
--- /NEMO/trunk/README.rst	(revision 11712)
+++ /NEMO/trunk/README.rst	(revision 11713)
@@ -1,6 +1,2 @@
-:Release:  |release|
-:Date:     |today|
-:SVN rev.: |revision|
-
 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,
@@ -15,9 +11,10 @@
 The NEMO ocean model has 3 major components:
 
-- |NEMO-OCE| models the ocean {thermo}dynamics and solves the primitive equations (``./src/OCE``)
-- |NEMO-ICE| simulates seaice {thermo}dynamics, brine inclusions and
-  subgrid-scale thickness variations (``./src/ICE``)
-- |NEMO-MBG| models the {on,off}line oceanic tracers transport and biogeochemical processes
-  (``./src/TOP``)
+- |OCE| models the ocean {thermo}dynamics and solves the primitive equations
+  (:file:`./src/OCE`)
+- |ICE| simulates sea-ice {thermo}dynamics, brine inclusions and
+  subgrid-scale thickness variations (:file:`./src/ICE`)
+- |MBG| models the {on,off}line oceanic tracers transport and biogeochemical processes
+  (:file:`./src/TOP`)
 
 These physical core engines are described in
@@ -39,10 +36,10 @@
 Several :doc:`built-in configurations<configurations>` are provided to
 evaluate the skills and performances of the model which
-can be used as templates for setting up a new configurations (``./cfgs``).
+can be used as templates for setting up a new configurations (:file:`./cfgs`).
 
 The user can also checkout available :doc:`idealized test cases<test_cases>` that
-address specific physical processes (``./tests``).
+address specific physical processes (:file:`./tests`).
 
-A set of :doc:`utilities <tools>` is also provided to {pre,post}process your data (``./tools``).
+A set of :doc:`utilities <tools>` is also provided to {pre,post}process your data (:file:`./tools`).
 
 Project documentation
@@ -50,17 +47,17 @@
 
 A walkthrough tutorial illustrates how to get code dependencies, compile and execute NEMO
-(``./INSTALL.rst``).
+(:file:`./INSTALL.rst`).
 
 Reference manuals and quick start guide can be build from source and
-exported to HTML or PDF formats (``./doc``) or
+exported to HTML or PDF formats (:file:`./doc`) or
 downloaded directly from the :forge:`development platform<wiki/Documentations>`.
 
-============ ================== ====================
- Component    Reference Manual   Quick start
-============ ================== ====================
+============ ================== ===================
+ Component    Reference Manual   Quick Start Guide
+============ ================== ===================
  |NEMO-OCE|   |DOI man OCE|_     |DOI strt gui|
  |NEMO-ICE|   |DOI man ICE|
  |NEMO-MBG|   |DOI man MBG|
-============ ================== ====================
+============ ================== ===================
 
 Since 2014 the project has a `Special Issue`_ in the open-access journal
@@ -87,2 +84,12 @@
 
 .. |DOI dev stgy| replace:: multi-year development strategy
+
+Disclaimer
+==========
+
+The NEMO source code is freely available and distributed under
+:download:`CeCILL v2.0 license <../../../LICENSE>` (GNU GPL compatible).
+
+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/REFERENCES.bib
===================================================================
--- /NEMO/trunk/REFERENCES.bib	(revision 11712)
+++ /NEMO/trunk/REFERENCES.bib	(revision 11713)
@@ -1,59 +1,46 @@
-@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={}
+@manual{NEMO_man,
+   title="NEMO ocean engine",
+   author="NEMO System Team",
+   series="Scientific Notes of Climate Modelling Center",
+   number="27",
+   institution="Institut Pierre-Simon Laplace (IPSL)",
+   publisher="Zenodo",
+   doi="10.5281/zenodo.1464816",
 }
+%   edition="",
+%   year=""
 
-@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).
-   SI³ 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.
-   SI³ 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{SI3_man,
+   title="Sea Ice modelling Integrated Initiative (SI$^3$) -- The NEMO Sea Ice engine",
+   author="NEMO Sea Ice Working Group",
+   series="Scientific Notes of Climate Modelling Center",
+   number="31",
+   institution="Institut Pierre-Simon Laplace (IPSL)",
+   publisher="Zenodo",
+   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={}
+@manual{TOP_man,
+   title="Tracers in Ocean Paradigm (TOP) -- The NEMO Tracers engine",
+   author="NEMO TOP Working Group",
+   series="Scientific Notes of Climate Modelling Center",
+   number="28",
+   institution="Institut Pierre-Simon Laplace (IPSL)",
+   publisher="Zenodo",
+   doi="10.5281/zenodo.1471700",
 }
+%   edition="",
+%   year=""
 
-@Article{gmd-8-1245-2015,
-   author = {Vidard, A. and Bouttier, P.-A. and Vigilant, F.},
-   title = {{NEMOTAM}: {T}angent and {A}djoint {M}odels for the ocean modelling platform {NEMO}},
-   journal = {Geoscientific Model Development},
-   volume = {8},
-   year = {2015},
-   number = {4},
-   pages = {1245--1257},
-   doi = {10.5194/gmd-8-1245-2015}
+@article{TAM_pub,
+   author = "Vidard, A. and Bouttier, P.-A. and Vigilant, F.",
+   title = "NEMOTAM: Tangent and Adjoint Models for the ocean modelling platform NEMO",
+   journal = "Geoscientific Model Development",
+   volume = "8",
+   year = "2015",
+   number = "4",
+   pages = "1245--1257",
+   doi = "10.5194/gmd-8-1245-2015"
 }
Index: /NEMO/trunk/RELEASE_NOTES.rst
===================================================================
--- /NEMO/trunk/RELEASE_NOTES.rst	(revision 11712)
+++ /NEMO/trunk/RELEASE_NOTES.rst	(revision 11713)
@@ -3,127 +3,5 @@
 *************
 
-New sea-ice component SI3 (in place of LIMx)
-============================================
+.. todo::
 
-- Physics
-
-  - Lateral melting
-  - Melt ponds: constant or :doi:`Holland et al. 2012<10.1175/JCLI-D-11-00078.1>` formulation (and soon topographic melt ponds)
-  - Ice-atm. drags from :doi:`Lupkes et al. 2012<10.1029/2012JD017630>` (depending on ice concentration) or :doi:`Lupkes et al. 2015<10.1002/2014JD022418>` (depending on sea ice concentration and atm. stability)
-  - Landfast ice (:doi:`Lemieux et al. 2016<10.1002/2016JC012006>`)
-
-- Numerics
-
-  - Advection: Ultimate-Macho scheme
-  - Rheology: adaptive EVP (:doi:`Kimmritz et al. 2017<10.1016/j.ocemod.2016.03.004>`)
-  - Coupling interface: conductivity as surface forcing instead of heat fluxes (Met Office requirement)
-
-- Performance: all thermodynamics in 1D and reduced mpp communications
-- Usability (users & developers friendly)
-
-  - Comprehensive set of outputs (universal units and understandable names + includes CMIP)
-  - New architecture and namelist
-  - All processes can be decoupled from each other (switch on/off)
-  - Ice categories bounds can be defined by the user or set automatically
-  - For open boundaries, the number of ice categories from the forcing model can be different from the number of categories in the regional simulation
-  - Fully compatible with AGRIF_
-  - Revised documentation 
-
-AGRIF for embedded zooms
-========================
-
-- Now compatible with new sea ice component
-- Now compatible with z* coordinate
-- Extended ghost cells area to properly handle scheme with spatial order >2
-- Added vertical refinement (beta)
-- Nesting tools for setup now up to date and working 
-
-Enhancements
-============
-
-- Fix for tracer conservation with split explicit free surface
-- Bulk formulae : move to aerobulk package (:doi:`Brodeau et al. 2016<10.1175/JPO-D-16-0169.1>`), i.e. NCAR, COARE and ECMWF bulk (remove Clio and MFS bulk)
-- Wetting and drying
-- Added tidal self attraction and loading either read from a file or from usual "scalar" approximation
-- Add a 4th order centered (CEN) and Flux Corrected Transport (FCT) tracer advection
-  (using a 4th compact in the vertical)
-- iso-neutral mixing (iso and triad operators):
-  add the Method of Stabilizing Correction (MSC) (more accurate calculation) + add a bilaplacian case
-- Lateral physics (``LDF``): scale aware setting of eddy viscosity and diffusivity
-- Vorticity: 2 new energy conserving scheme: ENT with Coriolis defined at T-point (better for Flux form) and EET a variant of EEN where e3t is used instead of e3f (solved the issue with e3f specification but is not enstrophy conserving) 
-
-Test Cases
-==========
-
-The first test cases available for now are:
-
-- ``CANAL``: east-west periodic canal of variable size with several initial states and associated geostrophic currents (zonal jets or vortex)
-- ``ICE_AGRIF``: east-west + north-south periodic channel. The common 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
-- ``ISOMIP``: simple box configuration with an ice shelf with simple geometry on top. The purpose of this test case is to evaluate the impact of various schemes and new development with iceshelf cavities. The exact original setup is described ​here
-- ``LOCK-EXCHANGE``: classical fluid dynamics experiment that has been adapted by Haidvogel and Beckmann (1999) for testing advection schemes in ocean circulation models. It has been used by several authors including Burchard and Bolding (2002) and :doi:`Ilıcak et al. (2012)<10.1016/j.ocemod.2011.10.003>`. The ``LOCK EXCHANGE`` experiment can in particular illustrate the impact of different choices of numerical schemes and/or subgrid closures on spurious interior mixing
-- ``OVERFLOW``: illustrates the impact of different choices of numerical schemes and/or subgrid closures on spurious interior mixing close to bottom topography. It is adapted from the non-rotating overflow configuration described in Haidvogel and Beckmann (1999) and further used by :doi:`Ilıcak et al. (2012)<10.1016/j.ocemod.2011.10.003>`
-- ``VORTEX``: illustrates the propagation of an anticyclonic eddy over a Beta plan and flat bottom. It is implemented here with an online refined subdomain (thanks to ``AGRIF`` library) out of which the vortex propagates. It serves as a benchmark to diagnose nesting errors as in :doi:`Debreu et al. (2012)<10.1016/j.ocemod.2012.03.003>`, :doi:`Penven et al. (2006)<10.1016/j.ocemod.2005.05.002>` and :doi:`Spall and Holland (1991)<10.1175/1520-0485(1991)021<0205:ANPEMF>2.0.CO;2>`
-- ``WAD``: a set of simple closed basin geometries for testing the wetting and drying capabilities. Examples range from a closed channel with EW linear bottom slope to a parabolic EW channel with a Gaussian ridge
-
-New Reference configurations
-============================
-
-``AGRIF_DEMO``: 2 interlocked zooms (1:4 & 1:3) in the Nordic Seas + 1 zoom (1:1) at the equator
-
-``SPITZ12``: regional configuration around the Svalbard archipelago 
-
-Wave coupling
-=============
-
-Coupled interface to external wave model
-
-Large scale wave interaction process added in momentum and tracer equations 
-
-Passive tracer TOP and biogeochemical PISCES components
-=======================================================
-
-- The passive tracers transport component was redesigned toward a modular structure and users can enable each module directly through logical flags in namelist_top (no more fortran macros!)
-- :doc:`TOP on-line user documentation<tracers>`
-- TOP currently accounts for the following 5 modules: ``CFC`` contains inorganic carbon tracers (CFC11/CFC12/SF6), ``MY_TRC`` is a template for new modules (or external couplings), ``AGE`` deals with water age tracking, ``C14`` as a radiocarbon passive tracer, and the companion ecosystem model ``PISCES``
-- A generalized infrastructure was developed to handle the prescription of either surface, coastal, or open boundaries conditions for each passive tracer
-- A new configuration, named ``ORCA2_OFF_TRC``, was created to provide a benchmark simulation environment to deal with inert carbon tracers dynamics by exploiting the offline coupling with NEMO
-- PISCES model contains new developments and modifications:
-
-  - Particulate Organic Carbon (POC) component comes with a new liability scheme, while the former Kriest parametrisation was superseded
-  - A complex iron chemistry scheme is now available, with an improved description of ligands for the marine iron cycle
-  - Carbonate chemistry is based on MOCSY 2.0 routines (see :doi:`10.5194/gmd-8-485-2015 <Orr and Epitalon, 2015>`), by complying also with CMIP6 standards
-  - Ecosystem components can be optionally modelled by means of explicit nutrient quotas (PISCES-QUOTA) 
-
-High Performance Computing (HPC): performances improvements
-===========================================================
-
-- Reduce number of MPI communications
-  (suppression of redundant communications, gather multiple communications into one)
-- Use of MPI-3 asynchronous routines for performance (use ``key_mpi2`` if MPI-3 not available)
-- Back to standard dynamical allocation (remove of wrk_alloc/dealloc statements)
-- :xios:`XIOS software<>` for IOs version 2.5 as default, and optionally available for restarts 
-
-Simplification and robustness
-=============================
-
-- Revised structure of ``namelist_ref`` / ``namelist_cfg`` and default reference values
-- Lateral physics (``LDF``): simplification of user interface and removal of CPP keys
-- Vertical physics (``ZDF``) (modularity, share shear production calculation between TKE and GKS, removal of all ZDF CPP keys, removal of ``avmu`` & ``avmv``, minimization of MPP comm.: ~15 removed)
-- Remove the split-explicit ZDF scheme for both ``TRA`` and ``DYN``
-- Remove the acceleration of convergence
-- Generalised ``lbc_lnk`` and ``lbc_nfd``
-- Unify mppini
-- Use non uniform jpi/jpj with dynamic allocation to avoid ghost rows/columns
-- MPI Message passing re coded
-- Configuration interface completely rewritten (``DOM`` module mainly suppressed , and in place: ``domain_cfg.nc`` file, or ``usr_def`` module) 
-
-Collaborative Development Environment
-=====================================
-
-- Access to information on wiki reorganised through portals for users/developers/System Team and complete refactoring of all pages and their layout
-- Reorganisation of SVN repository to be compliant with usual directory tree and facilitate building of the executable
-- Define and install a separate repository for test cases to all easy contributions from the community
-- :forge:`Forums<discussion>` created
-- :website:`Public web site<>` has been revamped and cleaned using Wordpress
-- New mailing lists have been set up
-- Improvements of reliability through automatic and regular testing of the changes made in repository 
+   Complete "Release Notes"
Index: /NEMO/trunk/doc/rst/Makefile
===================================================================
--- /NEMO/trunk/doc/rst/Makefile	(revision 11712)
+++ /NEMO/trunk/doc/rst/Makefile	(revision 11713)
@@ -15,5 +15,5 @@
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: help clean html dirhtml drafthtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
 
 help:
@@ -21,6 +21,6 @@
 	@echo "  html       to make standalone HTML files"
 	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  drafthtml  to make an autoupdate HTML export while editing (todo list included)"
 	@echo "  singlehtml to make a single large HTML file"
-	@echo "  livehtml   to make an autoupdate HTML export while editing"
 	@echo "  pickle     to make pickle files"
 	@echo "  json       to make JSON files"
@@ -44,35 +44,35 @@
 
 html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(SPHINXBUILD)   -b html          $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	$(SPHINXBUILD)   -b dirhtml       $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
+drafthtml:
+	sphinx-autobuild -b html -t draft $(ALLSPHINXOPTS) $(BUILDDIR)/drafthtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/drafthtml."
+
 singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	$(SPHINXBUILD)   -b singlehtml    $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
-livehtml:
-	sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
 pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	$(SPHINXBUILD)   -b pickle        $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
 json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	$(SPHINXBUILD)   -b json          $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
 htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	$(SPHINXBUILD)   -b htmlhelp      $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
@@ -80,5 +80,5 @@
 
 qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	$(SPHINXBUILD)   -b qthelp        $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -89,5 +89,5 @@
 
 devhelp:
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	$(SPHINXBUILD)   -b devhelp       $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
@@ -98,10 +98,10 @@
 
 epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	$(SPHINXBUILD)   -b epub          $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
 latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	$(SPHINXBUILD)   -b latex         $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@@ -110,5 +110,5 @@
 
 latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	$(SPHINXBUILD)   -b latex         $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
@@ -116,15 +116,15 @@
 
 text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	$(SPHINXBUILD)   -b text          $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
 
 man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	$(SPHINXBUILD)   -b man           $(ALLSPHINXOPTS) $(BUILDDIR)/man
 	@echo
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
 
 texinfo:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	$(SPHINXBUILD)   -b texinfo       $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo
 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@@ -133,5 +133,5 @@
 
 info:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	$(SPHINXBUILD)   -b texinfo       $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo "Running Texinfo files through makeinfo..."
 	make -C $(BUILDDIR)/texinfo info
@@ -139,15 +139,15 @@
 
 gettext:
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	$(SPHINXBUILD)   -b gettext      $(I18NSPHINXOPTS) $(BUILDDIR)/locale
 	@echo
 	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
 
 changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	$(SPHINXBUILD)   -b changes       $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
 linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	$(SPHINXBUILD)   -b linkcheck     $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
@@ -155,5 +155,5 @@
 
 doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	$(SPHINXBUILD)   -b doctest       $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
Index: /NEMO/trunk/doc/rst/source/NEMO_guide.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/NEMO_guide.rst	(revision 11712)
+++ /NEMO/trunk/doc/rst/source/NEMO_guide.rst	(revision 11713)
@@ -12,6 +12,6 @@
 	", for paragraphs
 
-	'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'
+	'global.rst' contains a list of roles, substitutions and URL links for the guide.
+	It is loaded for each file with the 'rst_epilog' setting in 'conf.py'
 
 .. toctree::
@@ -49,15 +49,9 @@
    glossary
 
+:Release:  |release|
+
+.. only:: draft
+
+   .. include:: todos.rst
+
 .. include:: readme.rst
-
-.. Next headings markup acording to readme.rst
-
-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/citations.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/citations.rst	(revision 11712)
+++ /NEMO/trunk/doc/rst/source/citations.rst	(revision 11713)
@@ -1,27 +1,25 @@
-****************
-How to cite NEMO
-****************
+***********
+How to cite
+***********
 
-
-|NEMO-OCE| :cite:`NEMO_manual`
-
-   | "**NEMO ocean engine**"
-   | Gurvan Madec and NEMO System Team
-   | *Scientific Notes of Climate Modelling Center*, **27**
-   | ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL)
-   | |DOI man OCE|_
+|NEMO-OCE|
+   :title:`NEMO ocean engine`,
+   NEMO System Team,
+   Scientific Notes of Climate Modelling Center, 27,
+   ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL),
+   :doi:`10.5281/zenodo.1464816`
 
 .. literalinclude:: references.bib
    :language: bibtex
-   :lines:    1-15
+   :lines:    1-9
    :caption:  BibTeX source for NEMO manual
 
-|NEMO-ICE| :cite:`SI3_manual`
-
-   | "**Sea Ice modelling Integrated Initiative (SI** :sup:`3` **) -- The NEMO sea ice engine**"
-   | NEMO Sea Ice Working Group
-   | *Scientific Notes of Climate Modelling Center*, **31**
-   | ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL)
-   | |DOI man ICE|
+|NEMO-ICE|
+   :title:`Sea Ice modelling Integrated Initiative (SI`\ :sup:`3`\ :title:`) --
+   The NEMO sea ice engine`,
+   NEMO Sea Ice Working Group,
+   Scientific Notes of Climate Modelling Center, 31,
+   ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL),
+   :doi:`10.5281/zenodo.1471689`
 
 .. warning::  No official publication yet
@@ -29,14 +27,13 @@
 .. literalinclude:: references.bib
    :language: bibtex
-   :lines:    17-33
+   :lines:    13-21
    :caption:  BibTeX source for SI\ :sup:`3` manual
 
-|NEMO-MBG| :cite:`TOP_manual`
-
-   | "**Tracer in Ocean Paradigm (TOP) -- The NEMO passive tracer engine**"
-   | NEMO TOP Working Group
-   | *Scientific Notes of Climate Modelling Center*, **28**
-   | ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL)
-   | |DOI man MBG|
+|NEMO-MBG|
+   :title:`Tracer in Ocean Paradigm (TOP) -- The NEMO passive tracer engine`,
+   NEMO TOP Working Group,
+   Scientific Notes of Climate Modelling Center, 28,
+   ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL),
+   :doi:`10.5281/zenodo.1471700`
 
 .. warning::  No official publication yet
@@ -44,11 +41,4 @@
 .. literalinclude:: references.bib
    :language: bibtex
-   :lines:    37-49
+   :lines:    25-33
    :caption:  BibTeX source for TOP manual
-
-References
-==========
-
-.. bibliography:: references.bib
-   :style:       unsrt
-   :labelprefix: R
Index: /NEMO/trunk/doc/rst/source/conf.py
===================================================================
--- /NEMO/trunk/doc/rst/source/conf.py	(revision 11712)
+++ /NEMO/trunk/doc/rst/source/conf.py	(revision 11713)
@@ -26,5 +26,5 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.extlinks', 'sphinxcontrib.bibtex', 'sphinx.ext.todo']
+extensions = ['sphinx.ext.extlinks', 'sphinxcontrib.bibtex', 'sphinx.ext.todo', 'sphinxmark']
 
 # Add any paths that contain templates here, relative to this directory.
@@ -251,10 +251,10 @@
 # Link aliases
 extlinks = {
-   'doi'    : ('https://doi.org/%s'                       , None),
-   'forge'  : ('https://forge.ipsl.jussieu.fr/nemo/%s'    , None),
-   'github' : ('https://github.com/%s'                    , None),
-   'xios'   : ('https://forge.ipsl.jussieu.fr/ioserver/%s', None),
-   'website': ('https://www.nemo-ocean.eu/%s'             , None),
-   'zenodo' : ('https://zenodo.org/publication/%s'        , None)
+   'doi'    : ('https://doi.org/%s'                       , 'doi:'),
+   'forge'  : ('https://forge.ipsl.jussieu.fr/nemo/%s'    ,   None),
+   'github' : ('https://github.com/%s'                    ,   None),
+   'xios'   : ('https://forge.ipsl.jussieu.fr/ioserver/%s',   None),
+   'website': ('https://www.nemo-ocean.eu/%s'             ,   None),
+   'zenodo' : ('https://zenodo.org/publication/%s'        ,   None)
 }
 
@@ -266,2 +266,8 @@
 revision = subprocess.check_output("svnversion").decode("utf-8")
 rst_prolog = '.. |revision| replace:: %s' % revision
+
+# Todo
+if tags.has('draft'):
+    sphinxmark_enable = True
+    todo_include_todos = True
+    todo_emit_warnings = True
Index: /NEMO/trunk/doc/rst/source/data_assimilation.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/data_assimilation.rst	(revision 11712)
+++ /NEMO/trunk/doc/rst/source/data_assimilation.rst	(revision 11713)
@@ -40,7 +40,7 @@
 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,
+Then include ``SAO`` at the end of the relevant line in :file:`cfg.txt` file.
+Then recompile with the replacement main program in :file:`./src/SAO`.
+This is a special version of :file:`nemogcm.F90` (which doesn't run the model,
 but reads in the model fields, and observations and runs the OBS code.
 See "Standalone observation operator (``SAO``)" section in |DOI man OCE|_.
Index: /NEMO/trunk/doc/rst/source/global.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/global.rst	(revision 11712)
+++ /NEMO/trunk/doc/rst/source/global.rst	(revision 11713)
@@ -5,12 +5,13 @@
 .. role:: grey
 .. role:: greysup(sup)
-.. role: underline
-..   :class: underline
 
 .. Substitutions
 
-.. |NEMO-OCE| replace:: :blue:`NEMO-OCE (Ocean dynamics)`
-.. |NEMO-ICE| replace:: :grey:`NEMO-SI`\ :greysup:`3`\ :grey:`(Sea Ice)`
-.. |NEMO-MBG| replace:: :green:`NEMO-TOP/PISCES (Biogeochemistry)`
+.. |NEMO-OCE| replace::  :blue:`NEMO-OCE (Ocean dynamics)`
+.. |OCE|      replace::  :blue:`NEMO-OCE`
+.. |NEMO-ICE| replace::  :grey:`NEMO-SI`\ :greysup:`3`  :grey:`(Sea Ice)`
+.. |ICE|      replace::  :grey:`NEMO-SI`\ :greysup:`3`
+.. |NEMO-MBG| replace:: :green:`NEMO-TOP/PISCES (Tracers)`
+.. |MBG|      replace:: :green:`NEMO-TOP/PISCES`
 
 .. External links
@@ -37,4 +38,5 @@
 .. _EGU: http://www.egu.eu
 .. _Special Issue: https://www.geosci-model-dev.net/special_issue40.html
+.. _BFM man: https://cmcc-foundation.github.io/www.bfm-community.eu/files/bfm-nemo-manual_r1.0_201508.pdf
 
 .. DOI
Index: /NEMO/trunk/doc/rst/source/glossary.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/glossary.rst	(revision 11712)
+++ /NEMO/trunk/doc/rst/source/glossary.rst	(revision 11713)
@@ -3,31 +3,33 @@
 ********
 
-`AGRIF`_
-	*Adaptive Grid Refinement In Fortran*,
-	package for the integration of full adaptive mesh refinement features within
-	an existing multidimensional finite difference model
+.. glossary::
 
-SI\ :sup:`3`\
-	*Sea Ice Integrated Initiative*,
-	unified sea ice model merging functionalities from CICE, GELATO and LIM into the NEMO framework
+   `AGRIF`_
+      *Adaptive Grid Refinement In Fortran*,
+      package for the integration of full adaptive mesh refinement features within
+      an existing multidimensional finite difference model
 
-`OASIS`_
-	*Ocean Atmosphere Sea Ice Soil*,
-	coupling software to synchronise numerical codes representing different components of the climate system
+   SI\ :sup:`3`\
+      *Sea Ice Integrated Initiative*,
+      unified sea ice model merging functionalities from CICE, GELATO and LIM into the NEMO framework
 
-PISCES
-	*Pelagic Interactions Scheme for Carbon and Ecosystem Studies*,
-	biogeochemical model simulating marine ecosystems, cycles of carbon and the main nutrients
+   `OASIS`_
+      *Ocean Atmosphere Sea Ice Soil*,
+      coupling software to synchronise numerical codes representing different components of the climate system
 
-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.
+   PISCES
+      *Pelagic Interactions Scheme for Carbon and Ecosystem Studies*,
+      biogeochemical model simulating marine ecosystems, cycles of carbon and the main nutrients
 
-TOP
-	*Tracers in Ocean Paradigm*,
-	on/off-line oceanic tracers transport and biogeochemistry models
+   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.
 
-`XIOS`_
-	*XML Input Output Server*,
-	library dedicated to input/output management of climate code
+   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/todos.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/todos.rst	(revision 11713)
+++ /NEMO/trunk/doc/rst/source/todos.rst	(revision 11713)
@@ -0,0 +1,6 @@
+.. rubric:: List of editing tasks
+
+:*Date*:     |today|
+:*SVN rev*:  |revision|
+
+.. todolist::
Index: /NEMO/trunk/src/TOP/README.rst
===================================================================
--- /NEMO/trunk/src/TOP/README.rst	(revision 11712)
+++ /NEMO/trunk/src/TOP/README.rst	(revision 11713)
@@ -4,45 +4,46 @@
 
 .. contents::
-	:local:
-
-TOP (Tracers in the Ocean Paradigm) is the NEMO hardwired interface toward biogeochemical models and
-provide the physical constraints/boundaries for oceanic tracers.
-It consists of a modular framework to handle multiple ocean tracers, including also a variety of built-in modules.
+   :local:
+
+TOP (Tracers in the Ocean Paradigm) is the NEMO hardwired interface toward
+biogeochemical models and provide the physical constraints/boundaries for oceanic tracers.
+It consists of a modular framework to handle multiple ocean tracers,
+including also a variety of built-in modules.
 
 This component of the NEMO framework allows one to exploit available modules (see below) and
 further develop a range of applications, spanning from the implementation of a dye passive tracer to
 evaluate dispersion processes (by means of MY_TRC), track water masses age (AGE module),
-assess the ocean interior penetration of persistent chemical compounds (e.g., gases like CFC or even PCBs),
-up to the full set of equations involving marine biogeochemical cycles.
+assess the ocean interior penetration of persistent chemical compounds
+(e.g., gases like CFC or even PCBs), 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
+TOP interface has the following location in the source code :file:`./src/TOP` and
 the following modules are available:
 
-``TRP``
-	Interface to NEMO physical core for computing tracers transport
-
-``CFC``
-	Inert carbon tracers (CFC11,CFC12,SF6)
-
-``C14``
-	Radiocarbon passive tracer
-
-``AGE``
-	Water age tracking
-
-``MY_TRC``
-	Template for creation of new modules and external BGC models coupling
-
-``PISCES``
-	Built in BGC model.
-	See [https://www.geosci-model-dev.net/8/2465/2015/gmd-8-2465-2015-discussion.html Aumont et al. (2015)] for
-	a throughout description. |
-
-The usage of TOP is activated i) by including in the configuration definition  the component ``MBG`` and
-ii) by adding the macro ``key_top`` in the configuration CPP file
-(see for more details [http://forge.ipsl.jussieu.fr/nemo/wiki/Users "Learn more about the model"]).
+:file:`TRP`
+   Interface to NEMO physical core for computing tracers transport
+
+:file:`CFC`
+   Inert carbon tracers (CFC11,CFC12,SF6)
+
+:file:`C14`
+   Radiocarbon passive tracer
+
+:file:`AGE`
+   Water age tracking
+
+:file:`MY_TRC`
+   Template for creation of new modules and external BGC models coupling
+
+:file:`PISCES`
+   Built in BGC model. See :cite:`gmd-8-2465-2015` for a throughout description.
+
+The usage of TOP is activated
+*i)* by including in the configuration definition the component ``TOP`` and
+*ii)* by adding the macro ``key_top`` in the configuration CPP file
+(see for more details :forge:`"Learn more about the model" <wiki/Users>`).
 
 As an example, the user can refer to already available configurations in the code,
@@ -51,5 +52,6 @@
 (see also Section 4) .
 
-Note that, since version 4.0, TOP interface core functionalities are activated by means of logical keys and
+Note that, since version 4.0,
+TOP interface core functionalities are activated by means of logical keys and
 all submodules preprocessing macros from previous versions were removed.
 
@@ -57,73 +59,70 @@
 
 ``key_iomput``
-	use XIOS I/O
+   use XIOS I/O
 
 ``key_agrif``
-	enable AGRIF coupling
+   enable AGRIF coupling
 
 ``key_trdtrc`` & ``key_trdmxl_trc``
-	trend computation for tracers
+   trend computation for tracers
 
 Synthetic Workflow
 ==================
 
-A synthetic description of the TOP interface workflow is given below to summarize the steps involved in
-the computation of biogeochemical and physical trends and their time integration and outputs,
+A synthetic description of the TOP interface workflow is given below to
+summarize the steps involved in the computation of biogeochemical and physical trends and
+their time integration and outputs,
 by reporting also the principal Fortran subroutine herein involved.
 
-**Model initialization (OPA_SRC/nemogcm.F90)**
-
-call to trc_init (trcini.F90)
-
-  ↳ call trc_nam (trcnam.F90) to initialize TOP tracers and run setting
-
-  ↳ call trc_ini_sms, to initialize each submodule
-
-  ↳ call trc_ini_trp, to initialize transport for tracers
-
-  ↳ call trc_ice_ini, to initialize tracers in seaice
-
-  ↳ call trc_ini_state, read passive tracers from a restart or input data
-
-  ↳ call trc_sub_ini, setup substepping if {{{nn_dttrc /= 1}}}
-
-**Time marching procedure (OPA_SRC/stp.F90)**
-
-call to trc_stp.F90 (trcstp.F90)
-
-  ↳ call trc_sub_stp, averaging physical variables for sub-stepping
-
-  ↳ call trc_wri, call XIOS for output of data
-
-  ↳ call trc_sms, compute BGC trends for each submodule
-
-    ↳ call trc_sms_my_trc, includes also surface and coastal BCs trends
-
-  ↳ call trc_trp (TRP/trctrp.F90), compute physical trends
-
-    ↳ call trc_sbc, get trend due to surface concentration/dilution
-
-    ↳ call trc_adv, compute tracers advection
-
-    ↳ call to trc_ldf, compute tracers lateral diffusion
-
-    ↳ call to trc_zdf, vertical mixing and after tracer fields
-
-    ↳ call to trc_nxt, tracer fields at next time step. Lateral Boundary Conditions are solved in here.
-
-    ↳ call to trc_rad, Correct artificial negative concentrations
-
-  ↳ call trc_rst_wri, output tracers restart files
+Model initialization (:file:`./src/OCE/nemogcm.F90`)
+----------------------------------------------------
+
+Call to ``trc_init`` subroutine (:file:`./src/TOP/trcini.F90`) to initialize TOP.
+
+.. literalinclude:: ../../../src/TOP/trcini.F90
+   :language:        fortran
+   :lines:           41-86
+   :emphasize-lines: 21,30-32,38-40
+   :caption:         ``trc_init`` subroutine
+
+Time marching procedure (:file:`./src/OCE/step.F90`)
+----------------------------------------------------
+
+Call to ``trc_stp`` subroutine (:file:`./src/TOP/trcstp.F90`) to compute/update passive tracers.
+
+.. literalinclude:: ../../../src/TOP/trcstp.F90
+   :language:        fortran
+   :lines:           46-125
+   :emphasize-lines: 42,55-57
+   :caption:         ``trc_stp`` subroutine
+
+BGC trends computation for each submodule (:file:`./src/TOP/trcsms.F90`)
+------------------------------------------------------------------------
+
+.. literalinclude:: ../../../src/TOP/trcsms.F90
+   :language:        fortran
+   :lines:           21
+   :caption:         :file:`trcsms` snippet
+
+Physical trends computation (:file:`./src/TOP/TRP/trctrp.F90`)
+--------------------------------------------------------------
+
+.. literalinclude:: ../../../src/TOP/TRP/trctrp.F90
+   :language:        fortran
+   :lines:           46-95
+   :emphasize-lines: 17,21,29,33-35
+   :caption:         ``trc_trp`` subroutine
 
 Namelists walkthrough
 =====================
 
-namelist_top
-------------
-
-Here below are listed the features/options of the TOP interface accessible through the namelist_top_ref and
-modifiable by means of namelist_top_cfg (as for NEMO physical ones).
-
-Note that ## is used to refer to a number in an array field.
+:file:`namelist_top`
+--------------------
+
+Here below are listed the features/options of the TOP interface accessible through
+the :file:`namelist_top_ref` and modifiable by means of :file:`namelist_top_cfg`
+(as for NEMO physical ones).
+
+Note that ``##`` is used to refer to a number in an array field.
 
 .. literalinclude:: ../../namelists/namtrc_run
@@ -166,22 +165,25 @@
    :language: fortran
 
-Two main types of data structure are used within TOP interface to initialize tracer properties (1) and
+Two main types of data structure are used within TOP interface
+to initialize tracer properties (1) and
 to provide related initial and boundary conditions (2).
 
-**1. TOP tracers initialization**: sn_tracer (namtrc)
+1. TOP tracers initialization: ``sn_tracer`` (``&namtrc``)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Beside providing name and metadata for tracers,
-here are also defined the use of initial ({{{sn_tracer%llinit}}}) and
-boundary ({{{sn_tracer%llsbc, sn_tracer%llcbc, sn_tracer%llobc}}}) conditions.
-
-In the following, an example of the full structure definition is given for two idealized tracers both with
-initial conditions given, while the first has only surface boundary forcing and
+here are also defined the use of initial (``sn_tracer%llinit``) and
+boundary (``sn_tracer%llsbc, sn_tracer%llcbc, sn_tracer%llobc``) conditions.
+
+In the following, an example of the full structure definition is given for
+two idealized tracers both with initial conditions given,
+while the first has only surface boundary forcing and
 the second both surface and coastal forcings:
 
 .. code-block:: fortran
 
-	!             !    name   !           title of the field            !   units    ! initial data ! sbc   !   cbc  !   obc  !
-	sn_tracer(1)  = 'TRC1'    , 'Tracer 1 Concentration                ',   ' - '    ,  .true.      , .true., .false., .true.
-	sn_tracer(2)  = 'TRC2 '   , 'Tracer 2 Concentration                ',   ' - '    ,  .true.      , .true., .true. , .false.
+   !             !    name   !           title of the field            !   units    ! initial data ! sbc   !   cbc  !   obc  !
+   sn_tracer(1)  = 'TRC1'    , 'Tracer 1 Concentration                ',   ' - '    ,  .true.      , .true., .false., .true.
+   sn_tracer(2)  = 'TRC2 '   , 'Tracer 2 Concentration                ',   ' - '    ,  .true.      , .true., .true. , .false.
 
 As tracers in BGC models are increasingly growing,
@@ -190,94 +192,101 @@
 .. code-block:: fortran
 
-	!             !    name   !           title of the field            !   units    ! initial data !
-	sn_tracer(1)  = 'TRC1'    , 'Tracer 1 Concentration                ',   ' - '    ,   .true.
-	sn_tracer(2)  = 'TRC2 '   , 'Tracer 2 Concentration                ',   ' - '    ,   .true.
-	! sbc
-	sn_tracer(1)%llsbc = .true.
-	sn_tracer(2)%llsbc = .true.
-	! cbc
-	sn_tracer(2)%llcbc = .true.
+   !             !    name   !           title of the field            !   units    ! initial data !
+   sn_tracer(1)  = 'TRC1'    , 'Tracer 1 Concentration                ',   ' - '    ,   .true.
+   sn_tracer(2)  = 'TRC2 '   , 'Tracer 2 Concentration                ',   ' - '    ,   .true.
+   ! sbc
+   sn_tracer(1)%llsbc = .true.
+   sn_tracer(2)%llsbc = .true.
+   ! cbc
+   sn_tracer(2)%llcbc = .true.
 
 The data structure is internally initialized by code with dummy names and
-all initialization/forcing logical fields set to .false. .
-
-**2. Structures to read input initial and boundary conditions**: namtrc_dta (sn_trcdta), namtrc_bc (sn_trcsbc/sn_trccbc/sn_trcobc)
+all initialization/forcing logical fields set to ``.false.`` .
+
+2. Structures to read input initial and boundary conditions: ``&namtrc_dta`` (``sn_trcdta``), ``&namtrc_bc`` (``sn_trcsbc`` / ``sn_trccbc`` / ``sn_trcobc``)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The overall data structure (Fortran type) is based on the general one defined for NEMO core in the SBC component
-(see details in User Manual SBC Chapter on Input Data specification).
-
-Input fields are prescribed within namtrc_dta (with sn_trcdta structure),
-while Boundary Conditions are applied to the model by means of namtrc_bc,
-with dedicated structure fields for surface (sn_trcsbc), riverine (sn_trccbc), and
-lateral open (sn_trcobc) boundaries.
+(see details in ``SBC`` Chapter of :doc:`Reference Manual <citations>` on Input Data specification).
+
+Input fields are prescribed within ``&namtrc_dta`` (with ``sn_trcdta`` structure),
+while Boundary Conditions are applied to the model by means of ``&namtrc_bc``,
+with dedicated structure fields for surface (``sn_trcsbc``), riverine (``sn_trccbc``), and
+lateral open (``sn_trcobc``) boundaries.
 
 The following example illustrates the data structure in the case of initial condition for
-a single tracer contained in the file named tracer_1_data.nc (.nc is implicitly assumed in namelist filename),
-with a doubled initial value, and located in the usr/work/model/inputdata/ folder:
+a single tracer contained in the file named :file:`tracer_1_data.nc`
+(``.nc`` is implicitly assumed in namelist filename),
+with a doubled initial value, and located in the :file:`usr/work/model/inputdata` folder:
 
 .. code-block:: fortran
 
-	!               !  file name             ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
-	!               !                        !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
-	  sn_trcdta(1)  = 'tracer_1_data'        ,        -12        ,  'TRC1'   ,    .false.   , .true. , 'yearly'  , ''       , ''       , ''
-	  rf_trfac(1) = 2.0
-	  cn_dir = “usr/work/model/inputdata/”
-
-Note that, the Lateral Open Boundaries conditions are applied on the segments defined for the physical core of NEMO
-(see BDY description in the User Manual).
-
-namelist_trc
-------------
-
-Here below the description of namelist_trc_ref used to handle Carbon tracers modules, namely CFC and C14.
-
-|||| &'''namcfc'''     !   CFC ||
-
-|||| &'''namc14_typ'''     !  C14 - type of C14 tracer, default values of C14/C and pco2 ||
-
-|||| &'''namc14_sbc'''     !  C14 - surface BC ||
-
-|||| &'''namc14_fcg'''     !  files & dates ||
+   !               !  file name             ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
+   !               !                        !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
+     sn_trcdta(1)  = 'tracer_1_data'        ,        -12        ,  'TRC1'   ,    .false.   , .true. , 'yearly'  , ''       , ''       , ''
+     rf_trfac(1) = 2.0
+     cn_dir = 'usr/work/model/inputdata/'
+
+Note that, the Lateral Open Boundaries conditions are applied on
+the segments defined for the physical core of NEMO
+(see ``BDY`` description in the :doc:`Reference Manual <citations>`).
+
+:file:`namelist_trc`
+--------------------
+
+Here below the description of :file:`namelist_trc_ref` used to handle Carbon tracers modules,
+namely CFC and C14.
+
+.. literalinclude:: ../../../cfgs/SHARED/namelist_trc_ref
+   :language: fortran
+   :lines: 7,17,26,34
+   :caption: :file:`namelist_trc_ref` snippet
 
 ``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
+The generalized interface is pivoted on MY_TRC module that contains template files to
+build the coupling between
 NEMO and any external BGC model.
 
-The call to MY_TRC is activated by setting ``ln_my_trc = .true.`` (in namtrc)
+The call to MY_TRC is activated by setting ``ln_my_trc = .true.`` (in ``&namtrc``)
 
 The following 6 fortran files are available in MY_TRC with the specific purposes here described.
 
-``par_my_trc.F90``
-	This module allows to define additional arrays and public variables to be used within the MY_TRC interface
-
-``trcini_my_trc.F90``
-	Here are initialized user defined namelists and the call to the external BGC model initialization procedures to
-	populate general tracer array (trn and trb). Here are also likely to be defined suport arrays related to
-	system metrics that could be needed by the BGC model.
-
-``trcnam_my_trc.F90``
-	This routine is called at the beginning of trcini_my_trc and should contain the initialization of
-	additional namelists for the BGC model or user-defined code.
-
-``trcsms_my_trc.F90``
-	The routine performs the call to Boundary Conditions and its main purpose is to
-	contain the Source-Minus-Sinks terms due to the biogeochemical processes of the external model.
-	Be aware that lateral boundary conditions are applied in trcnxt routine.
-	IMPORTANT: the routines to compute the light penetration along the water column and
-	the tracer vertical sinking should be defined/called in here, as generalized modules are still missing in
-	the code.
-
-``trcice_my_trc.F90``
-	Here it is possible to prescribe the tracers concentrations in the seaice that will be used as
-	boundary conditions when ice melting occurs (nn_ice_tr =1 in namtrc_ice).
-	See e.g. the correspondent PISCES subroutine.
-
-``trcwri_my_trc.F90``
-	This routine performs the output of the model tracers (only those defined in namtrc) using IOM module
-	(see Manual Chapter “Output and Diagnostics”).
-	It is possible to place here the output of additional variables produced by the model,
-	if not done elsewhere in the code, using the call to iom_put.
+:file:`par_my_trc.F90`
+   This module allows to define additional arrays and public variables to
+   be used within the MY_TRC interface
+
+:file:`trcini_my_trc.F90`
+   Here are initialized user defined namelists and
+   the call to the external BGC model initialization procedures to populate general tracer array
+   (``trn`` and ``trb``).
+   Here are also likely to be defined support arrays related to system metrics that
+   could be needed by the BGC model.
+
+:file:`trcnam_my_trc.F90`
+   This routine is called at the beginning of ``trcini_my_trc`` and
+   should contain the initialization of additional namelists for the BGC model or user-defined code.
+
+:file:`trcsms_my_trc.F90`
+   The routine performs the call to Boundary Conditions and its main purpose is to
+   contain the Source-Minus-Sinks terms due to the biogeochemical processes of the external model.
+   Be aware that lateral boundary conditions are applied in trcnxt routine.
+
+   .. warning::
+      The routines to compute the light penetration along the water column and
+      the tracer vertical sinking should be defined/called in here,
+      as generalized modules are still missing in the code.
+
+:file:`trcice_my_trc.F90`
+   Here it is possible to prescribe the tracers concentrations in the sea-ice that
+   will be used as boundary conditions when ice melting occurs (``nn_ice_tr = 1`` in ``&namtrc_ice``).
+   See e.g. the correspondent PISCES subroutine.
+
+:file:`trcwri_my_trc.F90`
+   This routine performs the output of the model tracers (only those defined in ``&namtrc``) using
+   IOM module (see chapter “Output and Diagnostics” in the :doc:`Reference Manual <citations>`).
+   It is possible to place here the output of additional variables produced by the model,
+   if not done elsewhere in the code, using the call to ``iom_put``.
 
 Coupling an external BGC model using NEMO framework
@@ -286,18 +295,20 @@
 The coupling with an external BGC model through the NEMO compilation framework can be achieved in
 different ways according to the degree of coding complexity of the Biogeochemical model, like e.g.,
-the whole code is made only by one file or it has multiple modules and interfaces spread across several subfolders.
-
-Beside the 6 core files of MY_TRC module, let’s assume an external BGC model named *MYBGC* and constituted by
-a rather essential coding structure, likely few Fortran files.
+the whole code is made only by one file or
+it has multiple modules and interfaces spread across several subfolders.
+
+Beside the 6 core files of MY_TRC module, let’s assume an external BGC model named *MYBGC* and
+constituted by a rather essential coding structure, likely few Fortran files.
 The new coupled configuration name is *NEMO_MYBGC*.
 
-The best solution is to have all files (the modified ``MY_TRC`` routines and the BGC model ones) placed in
-a unique folder with root ``MYBGCPATH`` and to use the makenemo external readdressing of ``MY_SRC`` folder.
-
-The coupled configuration listed in ``work_cfgs.txt`` will look like
+The best solution is to have all files (the modified ``MY_TRC`` routines and the BGC model ones)
+placed in a unique folder with root ``MYBGCPATH`` and
+to use the makenemo external readdressing of ``MY_SRC`` folder.
+
+The coupled configuration listed in :file:`work_cfgs.txt` will look like
 
 ::
 
-	NEMO_MYBGC OPA_SRC TOP_SRC
+   NEMO_MYBGC OCE TOP
 
 and the related ``cpp_MYBGC.fcm`` content will be
@@ -305,46 +316,46 @@
 .. code-block:: perl
 
-	bld::tool::fppkeys  key_iomput key_mpp_mpi key_top
-
-the compilation with ``makenemo`` will be executed through the following syntax
+   bld::tool::fppkeys key_iomput key_mpp_mpi key_top
+
+the compilation with :file:`makenemo` will be executed through the following syntax
 
 .. code-block:: console
 
-	$ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>'
-
-The makenemo feature “-e” was introduced to readdress at compilation time the standard MY_SRC folder
-(usually found in NEMO configurations) with a user defined external one.
-
-The compilation of more articulated BGC model code & infrastructure, like in the case of BFM
-([http://www.bfm-community.eu/publications/bfmnemomanual_r1.0_201508.pdf BFM-NEMO coupling manual]),
-requires some additional features.
+   $ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>'
+
+The makenemo feature ``-e`` was introduced to
+readdress at compilation time the standard MY_SRC folder (usually found in NEMO configurations) with
+a user defined external one.
+
+The compilation of more articulated BGC model code & infrastructure,
+like in the case of BFM (|BFM man|_), requires some additional features.
 
 As before, let’s assume a coupled configuration name *NEMO_MYBGC*,
-but in this case MYBGC model root becomes ``<MYBGCPATH>`` that contains 4 different subfolders for
-biogeochemistry, named ``initialization``, ``pelagic``, and ``benthic``, and
-a separate one named ``nemo_coupling`` including the modified ``MY_SRC`` routines.
+but in this case MYBGC model root becomes :file:`MYBGC` path that
+contains 4 different subfolders for biogeochemistry,
+named :file:`initialization`, :file:`pelagic`, and :file:`benthic`,
+and a separate one named :file:`nemo_coupling` including the modified `MY_SRC` routines.
 The latter folder containing the modified NEMO coupling interface will be still linked using
-the makenemo “-e” option.
+the makenemo ``-e`` option.
 
 In order to include the BGC model subfolders in the compilation of NEMO code,
-it will be necessary to extend the configuration ``cpp_NEMO_MYBGC.fcm`` file to include the specific paths of
-``MYBGC`` folders, as in the following example
+it will be necessary to extend the configuration :file:`cpp_NEMO_MYBGC.fcm` file to include the specific paths of :file:`MYBGC` folders, as in the following example
 
 .. code-block:: perl
 
-	bld::tool::fppkeys  key_iomput key_mpp_mpi key_top
-
-	src::MYBGC::initialization         <MYBGCPATH>/initialization
-	src::MYBGC::pelagic                <MYBGCPATH>/pelagic
-	src::MYBGC::benthic                <MYBGCPATH>/benthic
-
-	bld::pp::MYBGC      1
-	bld::tool::fppflags::MYBGC   %FPPFLAGS
-	bld::tool::fppkeys           %bld::tool::fppkeys MYBGC_MACROS
+   bld::tool::fppkeys  key_iomput key_mpp_mpi key_top
+
+   src::MYBGC::initialization         <MYBGCPATH>/initialization
+   src::MYBGC::pelagic                <MYBGCPATH>/pelagic
+   src::MYBGC::benthic                <MYBGCPATH>/benthic
+
+   bld::pp::MYBGC      1
+   bld::tool::fppflags::MYBGC   %FPPFLAGS
+   bld::tool::fppkeys           %bld::tool::fppkeys MYBGC_MACROS
 
 where *MYBGC_MACROS* is the space delimited list of macros used in *MYBGC* model for
 selecting/excluding specific parts of the code.
-The BGC model code will be preprocessed in the configuration ``BLD`` folder as for NEMO,
-but with an independent path, like ``NEMO_MYBGC/BLD/MYBGC/<subforlders>``.
+The BGC model code will be preprocessed in the configuration :file:`BLD` folder as for NEMO,
+but with an independent path, like :file:`NEMO_MYBGC/BLD/MYBGC/<subforlders>`.
 
 The compilation will be performed similarly to in the previous case with the following
@@ -352,20 +363,26 @@
 .. code-block:: console
 
-	$ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>/nemo_coupling'
-
-Note that, the additional lines specific for the BGC model source and build paths can be written into
-a separate file, e.g. named ``MYBGC.fcm``, and then simply included in the ``cpp_NEMO_MYBGC.fcm`` as follow
-
-.. code-block:: perl
-
-	bld::tool::fppkeys  key_zdftke key_dynspg_ts key_iomput key_mpp_mpi key_top
-	inc <MYBGCPATH>/MYBGC.fcm
-
-This will enable a more portable compilation structure for all MYBGC related configurations.
-
-**Important**: the coupling interface contained in nemo_coupling cannot be added using the FCM syntax,
-as the same files already exists in NEMO and they are overridden only with the readdressing of MY_SRC contents to
-avoid compilation conflicts due to duplicate routines.
-
-All modifications illustrated above, can be easily implemented using shell or python scripting to
-edit the NEMO configuration CPP.fcm file and to create the BGC model specific FCM compilation file with code paths.
+   $ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>/nemo_coupling'
+
+.. note::
+   The additional lines specific for the BGC model source and build paths can be written into
+   a separate file, e.g. named :file:`MYBGC.fcm`,
+   and then simply included in the :file:`cpp_NEMO_MYBGC.fcm` as follow
+
+   .. code-block:: perl
+
+      bld::tool::fppkeys  key_zdftke key_dynspg_ts key_iomput key_mpp_mpi key_top
+      inc <MYBGCPATH>/MYBGC.fcm
+
+   This will enable a more portable compilation structure for all MYBGC related configurations.
+
+.. warning::
+   The coupling interface contained in :file:`nemo_coupling` cannot be added using the FCM syntax,
+   as the same files already exists in NEMO and they are overridden only with
+   the readdressing of MY_SRC contents to avoid compilation conflicts due to duplicate routines.
+
+All modifications illustrated above, can be easily implemented using shell or python scripting
+to edit the NEMO configuration :file:`CPP.fcm` file and
+to create the BGC model specific FCM compilation file with code paths.
+
+.. |BFM man| replace:: BFM-NEMO coupling manual
