Index: NEMO/trunk/doc/rst/Makefile
===================================================================
--- NEMO/trunk/doc/rst/Makefile	(revision 11711)
+++ 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 11711)
+++ 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 11711)
+++ 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 11711)
+++ 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 11711)
+++ 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 11711)
+++ 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 11711)
+++ 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::
