Index: /NEMO/trunk/doc/rst/README.rst
===================================================================
--- /NEMO/trunk/doc/rst/README.rst	(revision 11706)
+++ /NEMO/trunk/doc/rst/README.rst	(revision 11707)
@@ -3,5 +3,7 @@
 **********************
 
-| The NEMO guide is made up of several files written in `ReStructuredText <http://docutils.sourceforge.net/rst.html>`_ (`.rst` extension), a WYSIWYG markup language used in the Python community, and scattered all over the NEMO sources.
+| The NEMO guide is made up of several files written in
+  `ReStructuredText <http://docutils.sourceforge.net/rst.html>`_ (`.rst` extension),
+  a WYSIWYG markup language used in the Python community, and scattered all over the NEMO sources.
 | You can view them one by one in plain text from `./source` folder, or export all to a user-friendly guide under `./build` (only HTML format at the moment, PDF expected later).
 
Index: /NEMO/trunk/doc/rst/source/NEMO_guide.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/NEMO_guide.rst	(revision 11706)
+++ /NEMO/trunk/doc/rst/source/NEMO_guide.rst	(revision 11707)
@@ -44,19 +44,12 @@
    :caption: Miscellaneous
 
+   citations
    contributing
    release_notes
-   Glossary<definitions>
+   glossary
 
 .. include:: readme.rst
 
 .. Next headings markup acording to readme.rst
-
-References
-==========
-
-.. bibliography:: references.bib
-   :all:
-   :style: unsrt
-   :labelprefix: R
 
 Disclaimer
Index: /NEMO/trunk/doc/rst/source/_static/style.css
===================================================================
--- /NEMO/trunk/doc/rst/source/_static/style.css	(revision 11706)
+++ /NEMO/trunk/doc/rst/source/_static/style.css	(revision 11707)
@@ -1,5 +1,5 @@
-.rstblue               { color: blue    ; }
-.rstgrey , .rstgreysup { color: grey    ; }
-.rstgreen              { color: seagreen; }
+.blue            { color: blue    ; }
+.grey , .greysup { color: grey    ; }
+.green           { color: seagreen; }
 
 .logo { filter: invert(1) !important; }
Index: /NEMO/trunk/doc/rst/source/citations.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/citations.rst	(revision 11707)
+++ /NEMO/trunk/doc/rst/source/citations.rst	(revision 11707)
@@ -0,0 +1,54 @@
+****************
+How to cite NEMO
+****************
+
+
+|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|_
+
+.. literalinclude:: references.bib
+   :language: bibtex
+   :lines:    1-15
+   :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|
+
+.. warning::  No official publication yet
+
+.. literalinclude:: references.bib
+   :language: bibtex
+   :lines:    17-33
+   :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|
+
+.. warning::  No official publication yet
+
+.. literalinclude:: references.bib
+   :language: bibtex
+   :lines:    37-49
+   :caption:  BibTeX source for TOP manual
+
+References
+==========
+
+.. bibliography:: references.bib
+   :style:       unsrt
+   :labelprefix: R
Index: /NEMO/trunk/doc/rst/source/data_assimilation.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/data_assimilation.rst	(revision 11706)
+++ /NEMO/trunk/doc/rst/source/data_assimilation.rst	(revision 11707)
@@ -7,27 +7,30 @@
 
 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
+- ``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 |DOI man OCE|_ for more details including information about the input file formats and
 the namelist settings.
 
-Observation and model comparison (OBS)
-======================================
+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 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. 
+To build with the OBS code active ``key_diaobs`` must be set.
 
-More details in the `NEMO manual`_ chapter 12.
+More details in |DOI man OCE|_ "Observation and Model Comparison (``OBS``)" chapter.
 
-Standalone observation operator (SAO)
--------------------------------------
+Standalone observation operator (``SAO``)
+-----------------------------------------
 
 The OBS code can also be run after a model run using saved NEMO model data.
@@ -39,22 +42,23 @@
 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`_.
+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 "Standalone observation operator (``SAO``)" section in |DOI man OCE|_.
 
-Apply assimilation increments (ASM)
-===================================
+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.
+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.
+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.
+More details in |DOI man OCE|_ "Apply Assimilation Increments (``ASM``)" chapter.
 
-Tangent linear and adjoint (TAM)
-================================
+Tangent linear and adjoint (``TAM``)
+====================================
 
 This is the tangent linear and adjoint code of NEMO which is useful to 4D VAR assimilation.
Index: MO/trunk/doc/rst/source/definitions.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/definitions.rst	(revision 11706)
+++ 	(revision )
@@ -1,33 +1,0 @@
-***********
-Definitions
-***********
-
-`AGRIF`_
-	*Adaptive Grid Refinement In Fortran*, 
-	package for the integration of full adaptive mesh refinement features within 
-	an existing multidimensional finite difference model
-
-SI\ :sup:`3`\ 
-	*Sea Ice Integrated Initiative*, 
-	unified sea ice model merging functionalities from CICE, GELATO and LIM into the NEMO framework
-
-`OASIS`_
-	*Ocean Atmosphere Sea Ice Soil*, 
-	coupling software to synchronise numerical codes representing different components of the climate system
-
-PISCES
-	*Pelagic Interactions Scheme for Carbon and Ecosystem Studies*, 
-	biogeochemical model simulating marine ecosystems, cycles of carbon and the main nutrients
-
-TAM
-	*Tangent linear and Adjoint Model*, 
-	tools to analyse and control the NEMO dynamical core for a wide range of applications such as
-	sensitivity analysis, parameter estimation, vectors computation or data assimilation.
-
-TOP
-	*Tracers in Ocean Paradigm*, 
-	on/off-line oceanic tracers transport and biogeochemistry models
-
-`XIOS`_
-	*XML Input Output Server*, 
-	library dedicated to input/output management of climate code
Index: /NEMO/trunk/doc/rst/source/global.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/global.rst	(revision 11706)
+++ /NEMO/trunk/doc/rst/source/global.rst	(revision 11707)
@@ -1,39 +1,55 @@
 .. 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
+.. role:: blue
+.. role:: green
+.. role:: grey
+.. role:: greysup(sup)
+.. role: underline
+..   :class: underline
 
 .. Substitutions
 
-.. |OPA| replace:: :rstblue:`NEMO-OPA`
-.. |SI3| replace:: :rstgrey:`NEMO-SI`\ :rstgreysup:`3`
-.. |TOP| replace:: :rstgreen:`NEMO-TOP/PISCES`
+.. |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)`
 
-.. Institutes
+.. External links
 
-.. _CMCC:           https://www.cmcc.it 
-.. _CNRS:           https://www.cnrs.fr
-.. _Mercator Ocean: https://www.mercator-ocean.fr
-.. _Met Office:     https://www.metoffice.gov.uk
-.. _MOI:            https://www.mercator-ocean.fr
-.. _NERC:           https://nerc.ukri.org
+   .. Consortium institutes
 
-.. Models / Softwares
+.. _CMCC:       https://www.cmcc.it
+.. _CNRS:       https://www.cnrs.fr
+.. _Met Office: https://www.metoffice.gov.uk
+.. _MOI:        https://www.mercator-ocean.fr
+.. _NERC:       https://nerc.ukri.org
+
+   .. Models / Libraries / Dependencies
 
 .. _AGRIF:  http://agrif.imag.fr
-.. _FCM:    https://metomi.github.io/fcm/doc/
+.. _FCM:    https://metomi.github.io/fcm
 .. _IOIPSL: https://forge.ipsl.jussieu.fr/igcmg/browser/IOIPSL
+.. _NEMO:   https://www.nemo-ocean.eu
 .. _OASIS:  https://portal.enes.org/oasis
+.. _XIOS:   https://forge.ipsl.jussieu.fr/ioserver
 
-.. NEMO
+   .. Misc.
 
-.. _NEMO:          https://www.nemo-ocean.eu
-.. _NEMO strategy: https://doi.org/10.5281/zenodo.1471663
-.. _NEMO guide:    :samp: https://doi.org/10.5281/zenodo.1475325
-.. _NEMO manual:   https://doi.org/10.5281/zenodo.1464816
-.. _SI3 manual:    :samp: https://doi.org/10.5281/zenodo.1471689
-.. _TOP manual:    :samp: https://doi.org/10.5281/zenodo.1471700
+.. _EGU: http://www.egu.eu
+.. _Special Issue: https://www.geosci-model-dev.net/special_issue40.html
+
+.. DOI
+
+   .. Publications (`:samp:` to deactivate link for unpublished documents)
+
+.. _DOI man   OCE:        https://doi.org/10.5281/zenodo.1464816
+.. _DOI man   ICE: :samp: https://doi.org/10.5281/zenodo.1471689
+.. _DOI man   MBG: :samp: https://doi.org/10.5281/zenodo.1471700
+.. _DOI strt  gui: :samp: https://doi.org/10.5281/zenodo.1475325
+.. _DOI dev  stgy:        https://doi.org/10.5281/zenodo.1471663
+
+   .. Badges (same labels as previously, substitution to link images)
+
+.. |DOI man   OCE| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1464816.svg
+.. |DOI man   ICE| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1471689.svg
+.. |DOI man   MBG| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1471700.svg
+.. |DOI strt  gui| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1475325.svg
Index: /NEMO/trunk/doc/rst/source/glossary.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/glossary.rst	(revision 11707)
+++ /NEMO/trunk/doc/rst/source/glossary.rst	(revision 11707)
@@ -0,0 +1,33 @@
+********
+Glossary
+********
+
+`AGRIF`_
+	*Adaptive Grid Refinement In Fortran*,
+	package for the integration of full adaptive mesh refinement features within
+	an existing multidimensional finite difference model
+
+SI\ :sup:`3`\
+	*Sea Ice Integrated Initiative*,
+	unified sea ice model merging functionalities from CICE, GELATO and LIM into the NEMO framework
+
+`OASIS`_
+	*Ocean Atmosphere Sea Ice Soil*,
+	coupling software to synchronise numerical codes representing different components of the climate system
+
+PISCES
+	*Pelagic Interactions Scheme for Carbon and Ecosystem Studies*,
+	biogeochemical model simulating marine ecosystems, cycles of carbon and the main nutrients
+
+TAM
+	*Tangent linear and Adjoint Model*,
+	tools to analyse and control the NEMO dynamical core for a wide range of applications such as
+	sensitivity analysis, parameter estimation, vectors computation or data assimilation.
+
+TOP
+	*Tracers in Ocean Paradigm*,
+	on/off-line oceanic tracers transport and biogeochemistry models
+
+`XIOS`_
+	*XML Input Output Server*,
+	library dedicated to input/output management of climate code
