Index: NEMO/trunk/doc/latex/global/annex_D.tex
===================================================================
--- NEMO/trunk/doc/latex/global/annex_D.tex	(revision 14113)
+++ NEMO/trunk/doc/latex/global/annex_D.tex	(revision 14113)
@@ -0,0 +1,207 @@
+\documentclass[../main/NEMO_manual]{subfiles}
+
+\begin{document}
+% ================================================================
+% Appendix D Coding Rules
+% ================================================================
+\chapter{Coding Rules}
+\label{apdx:D}
+
+\minitoc
+
+\newpage
+
+A "model life" is more than ten years.
+Its software, composed of a few hundred modules, is used by many people who are scientists or students and
+do not necessarily know every aspect of computing very well.
+Moreover, a well thought-out program is easier to read and understand, less difficult to modify,
+produces fewer bugs and is easier to maintain.
+Therefore, it is essential that the model development follows some rules:
+
+- well planned and designed
+
+- well written
+
+- well documented (both on- and off-line)
+
+- maintainable
+
+- easily portable
+
+- flexible.
+
+To satisfy part of these aims, \NEMO\ is written with a coding standard which is close to the ECMWF rules,
+named DOCTOR \citep{gibson_trpt86}. 
+These rules present some advantages like:
+
+- to provide a well presented program
+
+- to use rules for variable names which allow recognition of their type
+(integer, real, parameter, local or shared variables, etc. ). 
+
+This facilitates both the understanding and the debugging of an algorithm.
+
+% ================================================================
+% The program structure
+% ================================================================
+\section{Program structure}
+\label{sec:D_structure}
+
+Each program begins with a set of headline comments containing:
+
+- the program title
+
+- the purpose of the routine
+
+- the method and algorithms used
+
+- the detail of input and output interfaces
+
+- the external routines and functions used (if they exist)
+
+- references (if they exist)
+
+- the author name(s), the date of creation and any updates.
+
+- Each program is split into several well separated sections and
+sub-sections with an underlined title and specific labelled statements.
+
+- A program has not more than 200 to 300 lines.
+
+A template of a module style can be found on the NEMO depository in the following file:
+NEMO/OPA\_SRC/module\_example.
+% ================================================================
+% Coding conventions
+% ================================================================
+\section{Coding conventions}
+\label{sec:D_coding}
+
+- Use of the universal language \fninety, and try to avoid obsolescent features like statement functions,
+do not use GO TO and EQUIVALENCE statements.
+
+- A continuation line begins with the character {\&} indented by three spaces compared to the previous line,
+while the previous line ended with the character {\&}.
+
+- All the variables must be declared.
+The code is usually compiled with implicit none.
+ 
+- Never use continuation lines in the declaration of a variable.
+When searching a variable in the code through a \textit{grep} command, the declaration line will be found.
+
+- In the declaration of a PUBLIC variable, the comment part at the end of the line should start with
+the two characters "\verb?!:?".
+The following UNIX command, \\
+\verb?grep var_name *90 \ grep \!: ? \\
+will display the module name and the line where the var\_name declaration is.
+
+- Always use a three spaces indentation in DO loop, CASE, or IF-ELSEIF-ELSE-ENDIF statements.
+
+- use a space after a comma, except when it appears to separate the indices of an array.
+
+- use call to ctl\_stop routine instead of just a STOP.
+
+\newpage
+
+% ================================================================
+% Naming Conventions
+% ================================================================
+\section{Naming conventions}
+\label{sec:D_naming}
+
+The purpose of the naming conventions is to use prefix letters to classify model variables.
+These conventions allow the variable type to be easily known and rapidly identified.
+The naming conventions are summarised in the Table below:
+
+
+%--------------------------------------------------TABLE--------------------------------------------------
+\begin{table}[htbp]
+  \label{tab:VarName}
+  \begin{center}
+    \begin{tabular}{|p{45pt}|p{35pt}|p{45pt}|p{40pt}|p{40pt}|p{40pt}|p{40pt}|p{40pt}|}
+      \hline
+      Type \par / Status
+      & integer
+      & real
+      & logical
+      & character
+      & structure
+      & double \par precision
+      & complex \\
+      \hline
+      public  \par or  \par module variable
+      & \textbf{m n} \par \textit{but not} \par \textbf{nn\_ np\_}
+      & \textbf{a b e f g h o q r} \par \textbf{t} \textit{to} \textbf{x} \par but not \par \textbf{fs rn\_}
+      & \textbf{l} \par \textit{but not} \par \textbf{lp ld} \par \textbf{ ll ln\_}
+      & \textbf{c} \par \textit{but not} \par \textbf{cp cd} \par \textbf{cl cn\_}
+      & \textbf{s} \par \textit{but not} \par \textbf{sd sd} \par \textbf{sl sn\_}
+      & \textbf{d} \par \textit{but not} \par \textbf{dp dd} \par \textbf{dl dn\_}
+      & \textbf{y} \par \textit{but not} \par \textbf{yp yd} \par \textbf{yl yn} \\
+      \hline
+      dummy \par argument
+      & \textbf{k} \par \textit{but not} \par \textbf{kf}
+      & \textbf{p} \par \textit{but not} \par \textbf{pp pf}
+      & \textbf{ld}
+      & \textbf{cd}
+      & \textbf{sd}
+      & \textbf{dd}
+      & \textbf{yd} \\
+      \hline
+      local \par variable
+      & \textbf{i}
+      & \textbf{z}
+      & \textbf{ll}
+      & \textbf{cl}
+      & \textbf{sl}
+      & \textbf{dl}
+      & \textbf{yl} \\
+      \hline
+      loop \par control
+      & \textbf{j} \par \textit{but not} \par \textbf{jp} &&&&&& \\
+      \hline
+      parameter
+      & \textbf{jp np\_}
+      & \textbf{pp}
+      & \textbf{lp}
+      & \textbf{cp}
+      & \textbf{sp}
+      & \textbf{dp}
+      & \textbf{yp} \\
+      \hline
+      namelist
+      & \textbf{nn\_}
+      & \textbf{rn\_}
+      & \textbf{ln\_}
+      & \textbf{cn\_}
+      & \textbf{sn\_}
+      & \textbf{dn\_}
+      & \textbf{yn\_}
+      \\
+      \hline
+      CPP \par macro
+      & \textbf{kf}
+      & \textbf{fs} \par &&&&& \\
+      \hline
+    \end{tabular}
+    \label{tab:tab1}
+  \end{center}
+\end{table}
+%--------------------------------------------------------------------------------------------------------------
+
+N.B. Parameter here, in not only parameter in the \fortran acceptation,
+it is also used for code variables that are read in namelist and should never been modified during a simulation. 
+It is the case, for example, for the size of a domain (jpi,jpj,jpk).
+
+\newpage
+
+% ================================================================
+% The program structure
+% ================================================================
+%\section{Program structure}
+%\label{sec:Apdx_D_structure}
+
+%To be done....
+\biblio
+
+\pindex
+
+\end{document}
Index: NEMO/trunk/doc/latex/global/coding_rules.tex
===================================================================
--- NEMO/trunk/doc/latex/global/coding_rules.tex	(revision 14113)
+++ NEMO/trunk/doc/latex/global/coding_rules.tex	(revision 14113)
@@ -0,0 +1,844 @@
+
+\chapter{Coding Rules}
+\label{apdx:CODING}
+
+\chaptertoc
+
+\newpage
+
+A "model life" is more than ten years.
+Its software, composed of a few hundred modules, is used by many people who are scientists or students and
+do not necessarily know every aspect of computing very well.
+Moreover, a well thought-out program is easier to read and understand, less difficult to modify,
+produces fewer bugs and is easier to maintain.
+Therefore, it is essential that the model development follows some rules:
+
+\begin{itemize}
+\item well planned and designed
+\item well written
+\item well documented (both on- and off-line)
+\item maintainable
+\item easily portable
+\item flexible.
+\end{itemize}
+
+To satisfy part of these aims, \NEMO\ is written with a coding standard which is close to the ECMWF rules,
+named DOCTOR \citep{gibson_trpt86}.
+These rules present some advantages like:
+
+\begin{itemize}
+\item to provide a well presented program
+\item to use rules for variable names which allow recognition of their type 	(integer, real, parameter, local or shared variables, etc. ).
+\end{itemize}
+
+This facilitates both the understanding and the debugging of an algorithm.
+
+\section{Introduction}
+
+This document describes conventions used in \NEMO\ coding and suggested for its development.
+The objectives are to offer a guide to all readers of the \NEMO\ code, and to facilitate the work of
+all the developers, including the validation of their developments, and
+eventually the implementation of these developments within the \NEMO\ platform.
+
+A first approach of these rules can be found in the code in \path{./src/OCE/module_example} where
+all the basics coding conventions are illustrated.
+More details can be found below.
+
+This work is based on the coding conventions in use for the Community Climate System Model
+\footnote {\href{http://www.cesm.ucar.edu/working_groups/Software/dev_guide/dev_guide/node7.html}{UCAR conventions}},
+the previous version of this document (``FORTRAN coding standard in the OPA System'') and
+the expertise of the \NEMO\ System Team.
+After a general overview below, this document will describe:
+
+\begin{itemize}
+\item The style rules, $i.e.$ the syntax, appearance and naming conventions chosen to improve readability of the code;
+\item The content rules, $i.e.$ the conventions to improve the reliability of the different parts of the code;
+\item The package rules to go a step further by improving the reliability of the whole and
+	interfaces between routines and modules.
+\end{itemize}
+
+\section{Overview and general conventions}
+
+\NEMO\ has 3 major components: ocean dynamics (\path{./src/OCE}), sea-ice (\path{./src/ICE}) and
+marine biogeochemistry (\path{./src/MBG}).
+%, linear-tangent and adjoint of the dynamics ($TAM$) each of them corresponding to a directory.
+In each directory, one will find some FORTRAN files and/or subdirectories, one per functionality of the code:
+\path{./src/OCE/BDY} (boundaries), \path{./src/OCE/DIA} (diagnostics), \path{./src/OCE/DOM} (domain),
+\path{./src/OCE/DYN} (dynamics), \path{./src/OCE/LDF} (lateral diffusion), etc... \\
+All name are chosen to be as self-explanatory as possible, in English, all prefixes are 3 digits. \\
+English is used for all variables names, comments, and documentation. \\
+Physical units are MKS. The only exception to this is the temperature, which is expressed in degrees Celsius,
+except in bulk formulae and part of SI$^3$ sea-ice model where it is in Kelvin.
+See \path{.src/OCE/DOM/phycst.F90} files for conversions.
+
+\section{Architecture}
+
+Within each directory, organisation of files is driven by orthogonality,
+$i.e.$ one functionality of the code is intended to be in one and only one directory, and
+one module and all its related routines are in one file.
+The functional modules are:
+
+\begin{itemize}
+\item \path{SBC}             surface module
+\item \path{IOM}             management of the I/O
+\item \path{NST}             interface to AGRIF (nesting model) for dynamics and biogeochemistry
+\item \path{OBC}, \path{BDY} management of structured and unstructured open boundaries
+\item \path{C1D}             1D (vertical) configuration for dynamics, sea-ice and biogeochemistry
+\item \path{OFF}             off-line module: passive tracer or biogeochemistry alone
+\item \path{...}
+\end{itemize}
+
+For example, the file \textit{domain.F90} contains the module \texttt{domain} and all the subroutines related to
+this module (\texttt{dom\_init, dom\_nam, dom\_ctl}).
+
+\section{Style rules}
+
+\subsection{Argument list format}
+
+Routine argument lists will contain a maximum 5 variables per line,
+whilst continuation lines can be used.
+This applies both to the calling routine and the dummy argument list in the routine being called.
+The purpose is to simplify matching up the arguments between caller and callee.
+
+\begin{forlines}
+SUBROUTINE tra_adv_eiv( kt, pun, pvn, pwn )
+
+      CALL tra_adv_eiv( kt, zun, zvn, zwn )
+\end{forlines}
+
+\subsection{Array syntax}
+
+Except for long loops (see below), array notation should be used if possible.
+To improve readability the array shape must be shown in brackets, $e.g.$:
+
+\begin{forlines}
+onedarraya(:)   = onedarrayb(:) + onedarrayc(:)
+twodarray (:,:) = scalar * anothertwodarray(:,:)
+\end{forlines}
+
+When accessing sections of arrays, for example in finite difference equations,
+do so by using the triplet notation on the full array, $e.g.$:
+
+\begin{forlines}
+twodarray(:,2:len2) =   scalar                      &
+   &                  * ( twodarray2(:,1:len2-1 )   &
+   &                  -   twodarray2(:,2:len2 ) )
+\end{forlines}
+
+For long, complicated loops, explicitly indexed loops should be preferred.
+In general when using this syntax, the order of the loops indices should reflect the following scheme
+(for best usage of data locality):
+
+\begin{forlines}
+DO jk = 1, jpk
+   DO jj = 1, jpj
+      DO ji = 1, jpi
+         threedarray(ji,jj,jk) = ...
+      END DO
+   END DO
+END DO
+\end{forlines}
+
+\subsection{Case}
+
+All FORTRAN keywords are in capital: \forcode{DIMENSION}, \forcode{WRITE}, \forcode{DO}, \forcode{END DO},
+\forcode{NAMELIST}, ... All other parts of the \NEMO\ code will be written in lower case.
+
+\subsection{Comments}
+
+Comments in the code are useful when reading the code and changing or developing it. \\
+The full documentation and detailed explanations are to be added in the reference manual
+(TeX files, aside from the code itself). \\
+In the code, the comments should explain variable content and describe each computational step. \\
+Comments in the header start with ``!!''.
+For more details on the content of the headers, see Content rules/Headers in this document. \\
+Comments in the code start with ``!''. \\
+All comments are indented (3, 6, or 9 blank spaces). \\
+Short comments may be included on the same line as executable code, and an additional line can be used with
+proper alignment.
+For example:
+
+\begin{forlines}
+zx = zx *zzy   ! Describe what is going on and if it is
+!              ! too long use another ! for proper
+!              ! alignment with automatic indentation
+\end{forlines}
+
+More in-depth comments should be written in the form:
+
+\begin{forlines}
+   !  Check of some namelist values
+\end{forlines}
+
+or
+
+\begin{forlines}
+!
+!     !<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+!     !  Bottom boundary condition on tke
+!     !<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+!
+\end{forlines}
+
+Key features of this style are
+
+\begin{enumerate}
+\item it starts with a "!" in the column required for proper indentation,
+\item the text is offset above and below by a blank line or a content line built for underlying.
+\end{enumerate}
+
+\subsection{Continuation lines}
+
+Continuation lines can be used with precise alignment for readability. For example:
+
+\begin{forlines}
+avmu(ji,jj,jk) =   avmu(ji,jj,jk) * ( un(ji,jj,jk-1) - un(ji,jj,jk) )   &
+   &                              * ( ub(ji,jj,jk-1) - ub(ji,jj,jk) )   &
+   &             / (   fse3uw_n(ji,jj,jk)                               &
+   &                 * fse3uw_b(ji,jj,jk) )
+\end{forlines}
+
+Code lines, which are continuation lines of assignment statements, must begin to the right of the column of
+the assignment operator.
+Due to the possibility of automatic indentation in some editor (emacs for example),
+use a ``\&'' as first character of the continuing lines to maintain the alignment.
+
+\subsection{Declaration of arguments and local variables}
+
+In a routine, input arguments and local variables are declared 1 per line,
+with a comment field on the same line as the declaration.
+Multiple comment lines describing a single variable are acceptable if needed.
+For example:
+
+\begin{forlines}
+INTEGER             ::   kstp   ! ocean time-step index
+\end{forlines}
+
+\subsection{F90 Standard}
+
+\NEMO\ software adheres to the \fninety language standard and does not rely on any specific language or
+vendor extensions.
+
+\subsection{Free-Form Source}
+
+Free-form source will be used.
+The F90/95 standard allows lines of up to 132 characters, but a self-imposed limit of 80 should enhance readability,
+or print source files with two columns per page.
+Multi-line comments that extend to column 100 are unacceptable.
+
+\subsection{Indentation}
+
+Code as well as comment lines within loops, if-blocks, continuation lines, \forcode{MODULE} or
+\forcode{SUBROUTINE} statements will be indented 3 characters for readability
+(except for \forcode{CONTAINS} that remains at first column).
+
+\begin{forlines}
+MODULE mod1
+   REAL(wp) xx
+CONTAINS
+   SUBROUTINE sub76( px, py, pz, pw, pa,   &
+      &              pb, pc, pd, pe          )
+      <instruction>
+   END SUBROUTINE sub76
+END MODULE mod1
+\end{forlines}
+
+\subsection{Loops}
+
+Loops, if explicit, should be structured with the do-end do construct as opposed to numbered loops.
+Nevertheless non-numeric labels can be used for a big iterative loop of a recursive algorithm.
+In the case of a long loop, a self-descriptive label can be used ($i.e.$ not just a number).
+
+\subsection{Naming Conventions: files}
+
+A file containing a module will have the same name as the module it contains
+(because dependency rules used by "make" programs are based on file names).
+\footnote{
+  For example, if routine A "\forcode{USE}"s module B, then "make" must be told of the dependency relation which
+  requires B to be compiled before A.
+  If one can assume that module B resides in file B.o,
+  building a tool to generate this dependency rule ($e.g.$ A.o: B.o) is quite simple.
+  Put another way, it is difficult (to say nothing of CPU-intensive) to search an entire source tree to
+  find the file in which module B resides for each routine or module which "\forcode{USE}"s B.
+}
+
+\subsection{Naming Conventions: modules}
+
+Use a meaningful English name and the ``3 letters'' naming convention:
+first 3 letters for the code section, and last 3 to describe the module.
+For example, zdftke, where ``zdf'' stands for vertical diffusion, and ``tke'' for turbulent kinetic energy. \\
+Note that by implication multiple modules are not allowed in a single file.
+The use of common blocks is deprecated in \fortran 90 and their use in \NEMO\ is strongly discouraged.
+Modules are a better way to declare static data.
+Among the advantages of modules is the ability to freely mix data of various types, and
+to limit access to contained variables through the use of the \forcode{ONLY} and \forcode{PRIVATE} attributes.
+
+\subsection{Naming Conventions: variables}
+
+All variable should be named as explicitly as possible in English.
+The naming convention concerns prefix letters of these name, in order to identify the variable type and status. \\
+Never use a \fortran keyword as a routine or variable name. \\
+The table below lists the starting letter(s) to be used for variable naming, depending on their type and status:
+%--------------------------------------------------TABLE--------------------------------------------------
+\begin{table}[htbp]
+  \begin{center}
+    \begin{tabular}{|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|}
+      \hline
+      Type \par / Status                                                                          &
+      integer                                                                                     &
+      real                                                                                        &
+      logical                                                                                     &
+      character                                                                                   &
+      double \par precision                                                                       &
+      complex                                                                                     \\
+      \hline
+      public \par or \par module variable                                                         &
+      \textbf{m n} \par \textit{but not} \par \textbf{nn\_}                                       &
+      \textbf{a b e f g h o} \textbf{q} \textit{to} \textbf{x} \par but not \par \textbf{fs rn\_} &
+      \textbf{l} \par \textit{but not} \par \textbf{lp ld ll ln\_}                                &
+      \textbf{c} \par \textit{but not} \par \textbf{cp cd cl cn\_}                                &
+      \textbf{d} \par \textit{but not} \par \textbf{dp dd dl dn\_}                                &
+      \textbf{y} \par \textit{but not} \par \textbf{yp yd yl}                                     \\
+      \hline
+      dummy \par argument                                                                         &
+      \textbf{k} \par \textit{but not} \par \textbf{kf}                                           &
+      \textbf{p} \par \textit{but not} \par \textbf{pp pf}                                        &
+      \textbf{ld}                                                                                 &
+      \textbf{cd}                                                                                 &
+      \textbf{dd}                                                                                 &
+      \textbf{yd}                                                                                 \\
+      \hline
+      local \par variable                                                                         &
+      \textbf{i}                                                                                  &
+      \textbf{z}                                                                                  &
+      \textbf{ll}                                                                                 &
+      \textbf{cl}                                                                                 &
+      \textbf{cd}                                                                                 &
+      \textbf{yl}                                                                                 \\
+      \hline
+      loop \par control                                                                           &
+      \textbf{j} \par \textit{but not} \par \textbf{jp}                                           &
+                                                                                                  &
+                                                                                                  &
+                                                                                                  &
+                                                                                                  &
+                                                                                                  \\
+      \hline
+      parameter                                                                                   &
+      \textbf{jp}                                                                                 &
+      \textbf{pp}                                                                                 &
+      \textbf{lp}                                                                                 &
+      \textbf{cp}                                                                                 &
+      \textbf{dp}                                                                                 &
+      \textbf{yp}                                                                                 \\
+      \hline
+      namelist                                                                                    &
+      \textbf{nn\_}                                                                               &
+      \textbf{rn\_}                                                                               &
+      \textbf{ln\_}                                                                               &
+      \textbf{cn\_}                                                                               &
+      \textbf{dn\_}                                                                               &
+                                                                                                  \\
+      \hline
+      CPP \par macro                                                                              &
+      \textbf{kf}                                                                                 &
+      \textbf{sf}                                                                                 &
+                                                                                                  &
+                                                                                                  &
+                                                                                                  &
+                                                                                                  \\
+      \hline
+    \end{tabular}
+    \label{tab1}
+  \end{center}
+\end{table}
+%--------------------------------------------------------------------------------------------------------------
+
+\subsection{Operators}
+
+Use of the operators \texttt{<, >, <=, >=, ==, /=} is strongly recommended instead of their deprecated counterparts
+(\texttt{.lt., .gt., .le., .ge., .eq., .ne.}).
+The motivation is readability.
+In general use the notation: \\
+$<Blank><Operator><Blank>$
+
+\subsection{Pre processor}
+
+Where the use of a language pre-processor is required, it will be the C pre-processor (cpp). \\
+The cpp key is the main feature used, allowing to ignore some useless parts of the code at compilation step. \\
+The advantage is to reduce the memory use; the drawback is that compilation of this part of the code isn't checked. \\
+The cpp key feature should only be used for a few limited options, if it reduces the memory usage.
+In all cases, a logical variable and a FORTRAN \forcode{IF} should be preferred.
+When using a cpp key \textit{key\_optionname},
+a corresponding logical variable \textit{lk\_optionname} should be declared to
+allow FORTRAN \forcode{IF} tests in the code and
+a FORTRAN module with the same name ($i.e.$ \textit{optionname.F90}) should be defined.
+This module is the only place where a \``\#if defined'' command appears, selecting either the whole FORTRAN code or
+a dummy module.
+For example, the TKE vertical physics, the module name is \textit{zdftke.F90},
+the CPP key is \textit{key\_zdftke} and the associated logical is \textit{lk\_zdftke}.
+
+The following syntax:
+
+\begin{forlines}
+#if defined key_optionname
+!! Part of code conditionally compiled if cpp key key_optionname is active
+#endif
+\end{forlines}
+
+Is to be used rather than the \#ifdef abbreviate form since it may have conflicts with some Unix scripts.
+
+Tests on cpp keys included in \NEMO\ at compilation step:
+
+\begin{itemize}
+\item
+  The CPP keys used are compared to the previous list of cpp keys
+  (the compilation will stop if trying to specify a non-existing key)
+\item
+  If a change occurs in the CPP keys used for a given experiment, the whole compilation phase is done again.
+\end{itemize}
+
+\section{Content rules}
+
+\subsection{Configurations}
+
+The configuration defines the domain and the grid on which \NEMO\ is running.
+It may be useful to associate a CPP key and some variables to a given configuration, although
+the part of the code changed under each of those keys should be minimized.
+As an example, the "ORCA2" configuration (global ocean, 2 degrees grid size) is associated with
+the cpp key \texttt{key\_orca2} for which
+
+\begin{forlines}
+cp_cfg = "orca"
+jp_cfg = 2
+\end{forlines}
+
+\subsection{Constants}
+
+Physical constants ($e.g.$ $\pi$, gas constants) must never be hard-wired into the executable portion of a code.
+Instead, a mnemonically named variable or parameter should be set to the appropriate value,
+in the setup routine for the package.
+We realize than many parameterizations rely on empirically derived constants or fudge factors,
+which are not easy to name.
+In these cases it is not forbidden to leave such factors coded as "magic numbers" buried in executable code, but
+comments should be included referring to the source of the empirical formula.
+Hard-coded numbers should never be passed through argument lists.
+
+\subsection{Declaration for variables and constants}
+
+\subsubsection{Rules}
+
+Variables used as constants should be declared with attribute \forcode{PARAMETER} and
+used always without copying to local variables, in order to
+prevent from using different values for the same constant or changing it accidentally.
+
+\begin{itemize}
+\item
+  Usage of the \forcode{DIMENSION} statement or attribute is required in declaration statements
+\item
+  The ``::'' notation is quite useful to show that this program unit declaration part is written in
+  standard FORTRAN syntax, even if there are no attributes to clarify the declaration section.
+  Always use the notation $<$blank$>$::$<$three blanks$>$ to improve readability.
+\item
+  Declare the length of a character variable using the \forcode{CHARACTER} (len=xxx) syntax
+  \footnote {
+    The len specifier is important because it is possible to have several kinds for characters
+    ($e.g.$ Unicode using two bytes per character, or there might be a different kind for Japanese $e.g.$ NEC).
+  }
+\item
+  For all global data (in contrast to module data, that is all data that can be access by other module)
+  must be accompanied with a comment field on the same line
+  \footnote {
+    This allows a easy research of where and how a variable is declared using the unix command:
+    ``grep var *90 | grep !:''.
+  }.
+  For example:
+  \begin{forlines}
+  REAL(wp), DIMENSION(jpi,jpj,jpk) ::  ua   ! i-horizontal velocity (m/s)
+  \end{forlines}
+\end{itemize}
+
+\subsubsection{Implicit None}
+
+All subroutines and functions will include an \forcode{IMPLICIT NONE} statement.
+Thus all variables must be explicitly typed.
+It also allows the compiler to detect typographical errors in variable names.
+For modules, one \forcode{IMPLICIT NONE} statement in the modules definition section is needed.
+This also removes the need to have \forcode{IMPLICIT NONE} statements in
+any routines that are \forcode{CONTAINS}'ed in the module.
+Improper data initialisation is another common source of errors
+\footnote{
+  A variable could contain an initial value you did not expect.
+  This can happen for several reasons, $e.g.$ the variable has never been assigned a value, its value is outdated,
+  memory has been allocated for a pointer but you have forgotten to initialise the variable pointed to.
+}.
+To avoid problems, initialise variables as close as possible to where they are first used.
+
+\subsubsection{Attributes}
+
+\forcode{PRIVATE} / \forcode{PUBLIC}:
+All resources of a module are \forcode{PUBLIC} by default.
+A reason to store multiple routines and their data in a single module is that
+the scope of the data defined in the module can be limited to the routines which are in the same module.
+This is accomplished with the \forcode{PRIVATE} attribute. \\
+\forcode{INTENT}:
+All dummy arguments of a routine must include the \forcode{INTENT} clause in their declaration in order to
+improve control of variables in routine calls.
+
+\subsection{Headers}
+
+Prologues are not used in \NEMO\ for now, although it may become an interesting tool in combination with
+ProTeX auto documentation script in the future.
+Rules to code the headers and layout of a module or a routine are illustrated in the example module available with
+the code: \path{./src/OCE/module_example}
+
+\subsection{Interface blocks}
+
+Explicit interface blocks are required between routines if optional or keyword arguments are to be used.
+They also allow the compiler to check that the type, shape and number of arguments specified in the \forcode{CALL}
+are the same as those specified in the subprogram itself.
+FORTRAN 95 compilers can automatically provide explicit interface blocks for routines contained in a module.
+
+\subsection{I/O Error Conditions}
+
+I/O statements which need to check an error condition will use the \texttt{iostat=<integer variable>} construct
+instead of the outmoded \texttt{end=} and \forcode{err=}. \\
+Note that a 0 value means success, a positive value means an error has occurred, and
+a negative value means the end of record or end of file was encountered.
+
+\subsection{PRINT - ASCII output files}
+
+Output listing and errors are directed to \texttt{numout} logical unit =6 and
+produces a file called \textit{ocean.output} (use \texttt{ln\_prt} to have one output per process in MPP).
+Logical \texttt{lwp} variable allows for less verbose outputs.
+To output an error from a routine, one can use the following template:
+
+\begin{forlines}
+IF( nstop /= 0 .AND. lwp ) THEN   ! error print
+   WRITE(numout,cform_err)
+   WRITE(numout,*) nstop, ' error have been found'
+ENDIF
+\end{forlines}
+
+\subsection{Precision}
+
+Parameterizations should not rely on vendor-supplied flags to supply a default floating point precision or
+integer size.
+The F95 \forcode{KIND} feature should be used instead.
+In order to improve portability between 32 and 64 bit platforms,
+it is necessary to make use of kinds by using a specific module \path{./src/OCE/par_kind.F90}
+declaring the "kind definitions" to obtain the required numerical precision and range as well as
+the size of \forcode{INTEGER}.
+It should be noted that numerical constants need to have a suffix of \texttt{\_kindvalue} to
+have the according size. \\
+Thus \forcode{wp} being the "working precision" as declared in \path{./src/OCE/par_kind.F90},
+declaring real array \forcode{zpc} will take the form:
+
+\begin{forlines}
+REAL(wp), DIMENSION(jpi,jpj,jpk) ::  zpc      ! power consumption
+\end{forlines}
+
+\subsection{Structures}
+
+The \forcode{TYPE} structure allowing to declare some variables is more often used in \NEMO,
+especially in the modules dealing with reading fields, or interfaces.
+For example:
+
+\begin{forlines}
+! Definition of a tracer as a structure
+TYPE PTRACER
+   CHARACTER(len = 20)  :: sname  ! short name
+   CHARACTER(len = 80 ) :: lname  ! long name
+   CHARACTER(len = 20 ) :: unit   ! unit
+   LOGICAL              :: lini   ! read in a file or not
+   LOGICAL              :: lsav   ! ouput the tracer or not
+END TYPE PTRACER
+
+TYPE(PTRACER) , DIMENSION(jptra) :: tracer
+\end{forlines}
+
+Missing rule on structure name??
+
+\section{Packages coding rules}
+
+\subsection{Bounds checking}
+
+\NEMO\ is able to run when an array bounds checking option is enabled
+(provided the cpp key \texttt{key\_vectopt\_loop} is not defined). \\
+Thus, constructs of the following form are disallowed:
+
+\begin{forlines}
+REAL(wp) :: arr(1)
+\end{forlines}
+
+where "arr" is an input argument into which the user wishes to index beyond 1.
+Use of the (*) construct in array dimensioning is forbidden also because
+it effectively disables array bounds checking.
+
+\subsection{Communication}
+
+A package should refer only to its own modules and subprograms and to those intrinsic functions included in
+the Fortran standard. \\
+All communication with the package will be through the argument list or namelist input.
+\footnote{
+  The point behind this rule is that packages should not have to know details of
+  the surrounding model data structures, or the names of variables outside of the package.
+  A notable exception to this rule is model resolution parameters.
+  The reason for the exception is to allow compile-time array sizing inside the package.
+  This is often important for efficiency.
+}
+
+\subsection{Error conditions}
+
+When an error condition occurs inside a package, a message describing what went wrong will be printed
+(see PRINT - ASCII output files).
+The name of the routine in which the error occurred must be included.
+It is acceptable to terminate execution within a package, but
+the developer may instead wish to return an error flag through the argument list,
+see \textit{stpctl.F90}.
+
+\subsection{Memory management}
+
+The main action is to identify and declare which arrays are \forcode{PUBLIC} and which are \forcode{PRIVATE}. \\
+As of version 3.3.1 of \NEMO, the use of static arrays (size fixed at compile time) has been deprecated.
+All module arrays are now declared \forcode{ALLOCATABLE} and
+allocated in either the \texttt{<module\_name>\_alloc()} or \texttt{<module\_name>\_init()} routines.
+The success or otherwise of each \forcode{ALLOCATE} must be checked using
+the \texttt{stat=<integer\ variable>} optional argument. \\
+
+In addition to arrays contained within modules, many routines in \NEMO\ require local, ``workspace'' arrays to
+hold the intermediate results of calculations.
+In previous versions of \NEMO, these arrays were declared in such a way as to be automatically allocated on
+the stack when the routine was called.
+An example of an automatic array is:
+
+\begin{forlines}
+SUBROUTINE sub(n)
+   REAL :: a(n)
+   ...
+END SUBROUTINE sub
+\end{forlines}
+
+The downside of this approach is that the program will crash if it runs out of stack space and
+the reason for the crash might not be obvious to the user.
+
+Therefore, as of version 3.3.1, the use of automatic arrays is deprecated.
+Instead, a new module, \textit{wrk\_nemo.F90}, has been introduced which
+contains 1-,2-,3- and 4-dimensional workspace arrays for use in subroutines.
+These workspace arrays should be used in preference to declaring new, local (allocatable) arrays whenever possible.
+The only exceptions to this are when workspace arrays with lower bounds other than 1 and/or
+with extent(s) greater than those in the \textit{wrk\_nemo.F90} module are required. \\
+
+The 2D, 3D and 4D workspace arrays in \textit{wrk\_nemo.F90} have extents \texttt{jpi}, \texttt{jpj},
+\texttt{jpk} and \texttt{jpts} ($x$, $y$, $z$ and tracers) in the first, second, third and fourth dimensions,
+respectively.
+The 1D arrays are allocated with extent MAX($jpi \times jpj, jpk \times jpj, jpi \times jpk$). \\
+
+The \forcode{REAL (KIND = wp)} workspace arrays in \textit{wrk\_nemo.F90}
+are named $e.g.$ \texttt{wrk\_1d\_1, wrk\_4d\_2} etc. and
+should be accessed by USE'ing the \textit{wrk\_nemo.F90} module.
+Since these arrays are available to any routine,
+some care must be taken that a given workspace array is not already being used somewhere up the call stack.
+To help with this, \textit{wrk\_nemo.F90} also contains some utility routines;
+\texttt{wrk\_in\_use()} and \texttt{wrk\_not\_released()}.
+The former first checks that the requested arrays are not already in use and then sets internal flags to show that
+they are now in use.
+The \texttt{wrk\_not\_released()} routine un-sets those internal flags.
+A subroutine using this functionality for two, 3D workspace arrays named \texttt{zwrk1} and
+\texttt{zwrk2} will look something like:
+
+\begin{forlines}
+SUBROUTINE sub()
+   USE wrk_nemo, ONLY: wrk_in_use, wrk_not_released
+   USE wrk_nemo, ONLY: zwrk1 => wrk_3d_5, zwrk2 => wrk_3d_6
+   !
+   IF(wrk_in_use(3, 5,6)THEN
+      CALL ctl_stop('sub: requested workspace arrays unavailable.')
+      RETURN
+   END IF
+   ...
+   ...
+   IF(wrk_not_released(3, 5,6)THEN
+      CALL ctl_stop('sub: failed to release workspace arrays.')
+   END IF
+   !
+END SUBROUTINE sub
+\end{forlines}
+
+The first argument to each of the utility routines is the dimensionality of the required workspace (1--4).
+Following this there must be one or more integers identifying which workspaces are to be used/released.
+Note that, in the interests of keeping the code as simple as possible,
+there is no use of \forcode{POINTER}s etc. in the \textit{wrk\_nemo.F90} module.
+Therefore it is the responsibility of the developer to ensure that the arguments to \texttt{wrk\_in\_use()} and
+\texttt{wrk\_not\_released()} match the workspace arrays actually being used by the subroutine. \\
+
+If a workspace array is required that has extent(s) less than those of the arrays in
+the \textit{wrk\_nemo.F90} module then the advantages of implicit loops and bounds checking may be retained by
+defining a pointer to a sub-array as follows:
+
+\begin{forlines}
+SUBROUTINE sub()
+   USE wrk_nemo, ONLY: wrk_in_use, wrk_not_released
+   USE wrk_nemo, ONLY: wrk_3d_5
+   !
+   REAL(wp), DIMENSION(:,:,:), POINTER :: zwrk1
+   !
+   IF(wrk_in_use(3, 5)THEN
+      CALL ctl_stop('sub: requested workspace arrays unavailable.')
+      RETURN
+   END IF
+   !
+   zwrk1 => wrk_3d_5(1:10,1:10,1:10)
+   ...
+END SUBROUTINE sub
+\end{forlines}
+
+Here, instead of ``use associating'' the variable \texttt{zwrk1} with the array \texttt{wrk\_3d\_5}
+(as in the first example), it is explicitly declared as a pointer to a 3D array.
+It is then associated with a sub-array of \texttt{wrk\_3d\_5} once the call to
+\texttt{wrk\_in\_use()} has completed successfully.
+Note that in F95 (to which \NEMO\ conforms) it is not possible for either the upper or lower array bounds of
+the pointer object to differ from those of the target array. \\
+
+In addition to the \forcode{REAL (KIND = wp)} workspace arrays,
+\textit{wrk\_nemo.F90} also contains 2D integer arrays and 2D REAL arrays with extent (\texttt{jpi}, \texttt{jpk}),
+$i.e.$ $xz$.
+The utility routines for the integer workspaces are \texttt{iwrk\_in\_use()} and \texttt{iwrk\_not\_released()} while
+those for the $xz$ workspaces are \texttt{wrk\_in\_use\_xz()} and \texttt{wrk\_not\_released\_xz()}.
+
+Should a call to one of the \texttt{wrk\_in\_use()} family of utilities fail,
+an error message is printed along with a table showing which of the workspace arrays are currently in use.
+This should enable the developer to choose alternatives for use in the subroutine being worked on. \\
+
+When compiling \NEMO\ for production runs,
+the calls to {\texttt{wrk\_in\_use()} / \texttt{wrk\_not\_released()} can be reduced to stubs that just
+return \forcode{.false.} by setting the cpp key \texttt{key\_no\_workspace\_check}.
+These stubs may then be in-lined (and thus effectively removed altogether) by setting appropriate compiler flags
+($e.g.$ ``-finline'' for the Intel compiler or ``-Q'' for the IBM compiler).
+
+\subsection{Optimisation}
+
+Considering the new computer architecture, optimisation cannot be considered independently from the computer type.
+In \NEMO, portability is a priority, before any too specific optimisation.
+
+Some tools are available to help: for vector computers, \texttt{key\_vectopt\_loop} allows to unroll a loop
+
+\subsection{Package attribute: \forcode{PRIVATE}, \forcode{PUBLIC}, \forcode{USE}, \forcode{ONLY}}
+
+Module variables and routines should be encapsulated by using the \forcode{PRIVATE} attribute.
+What shall be used outside the module can be declared \forcode{PUBLIC} instead.
+Use \forcode{USE} with the \forcode{ONLY} attribute to specify which of the variables, type definitions etc...
+defined in a module are to be made available to the using routine.
+
+\subsection{Parallelism using MPI}
+
+\NEMO\ is written in order to be able to run on one processor, or on one or more using MPI
+($i.e.$ activating the cpp key $key\_mpp\_mpi$).
+The domain decomposition divides the global domain in cubes (see \NEMO\ reference manual).
+Whilst coding a new development, the MPI compatibility has to be taken in account
+(see \path{./src/LBC/lib_mpp.F90}) and should be tested.
+By default, the $x$-$z$ part of the decomposition is chosen to be as square as possible.
+However, this may be overriden by specifying the number of sub-domains in latitude and longitude in
+the \texttt{nammpp} section of the namelist file.
+
+\section{Features to be avoided}
+
+The code must follow the current standards of FORTRAN and ANSI C.
+In particular, the code should not produce any WARNING at compiling phase, so that
+users can be easily alerted of potential bugs when some appear in their new developments.
+Below is a list of features to avoid:
+\begin{itemize}
+\item \forcode{COMMON} block
+  (use the declaration part of \forcode{MODULE} instead)
+\item \forcode{EQUIVALENCE}
+  (use \forcode{POINTER} or derived data type instead to form data structure)
+\item Assigned and computed \forcode{GOTO}
+  (use the \forcode{CASE} construct instead)
+\item Arithmetic \forcode{IF} statement
+  (use the block \forcode{IF}, \forcode{ELSE}, \forcode{ELSEIF}, \forcode{ENDIF} or
+  \forcode{SELECT CASE} construct instead)
+\item Labelled \forcode{DO} construct
+  (use unlabelled \forcode{END DO} instead)
+\item \forcode{FORMAT} statement
+  (use character parameters or
+  explicit format- specifiers inside the \forcode{READ} or \forcode{WRITE} statement instead)
+\item \forcode{GOTO} and \forcode{CONTINUE} statements
+  (use \forcode{IF}, \forcode{CASE}, \forcode{DO WHILE}, \forcode{EXIT} or \forcode{CYCLE} statements or
+  a contained ?)
+\item \forcode{PAUSE}
+\item \forcode{ENTRY} statement: a sub-program must only have one entry point.
+\item \forcode{RETURN} is obsolete and so not necessary at the end of program units
+\item \forcode{FUNCTION} statement
+\item Avoid functions with side effects.
+  \footnote{
+    First, the code is easier to understand, if you can rely on
+    the rule that functions don't change their arguments.
+    Second, some compilers generate more efficient code for PURE functions
+    (in FORTRAN 95 there are the attributes PURE and ELEMENTAL), because
+    they can store the arguments in different places.
+    This is especially important on massive parallel and as well on vector machines.
+  }
+\item \forcode{DATA} and \forcode{BLOCK DATA}
+  (use initialisers)
+\end{itemize}
+
+%% Imported from introduction
+%%gm    To be put somewhere else ....
+%%nm    We should consider creating a glossary for all this kind of stuff (terms, acronyms and symbols)
+%%      http://en.wikibooks.org/wiki/LaTeX/Glossary
+%\noindent CPP keys and namelists are used as inputs to the code.
+
+%\noindent \index{CPP keys} CPP keys
+
+%Some CPP keys are implemented in the \fortran code to allow code selection at compiling step.
+%This selection of code at compilation time reduces the reliability of the whole platform since
+%it changes the code from one set of CPP keys to the other.
+%It is used only when the addition/suppression of the part of code highly changes the amount of memory at run time.
+%Usual coding looks like:
+
+%\begin{forlines}
+%#if defined key_option1
+%	! This part of the \fortran code will be active
+%	! only if key_option1 is activated at compiling step
+%#endif
+%\end{forlines}
+
+%\noindent \index{Namelist} Namelists
+
+%The namelist allows to input variables (character, logical, real and integer) into the code.
+%There is one namelist file for each component of \NEMO\ (dynamics, sea-ice, biogeochemistry...)
+%containing all the \fortran namelists needed.
+%The implementation in \NEMO\ uses a 2-step process.
+%For each \fortran namelist, two files are read:
+
+%\begin{enumerate}
+%\item
+%  A reference namelist (in \path{./cfgs/SHARED/namelist_ref}) is read first.
+%  This file contains all the namelist variables which are initialised to default values
+%\item
+%  A configuration namelist (in \path{./cfgs/CFG_NAME/EXP00/namelist_cfg}) is read aferwards.
+%  This file contains only the namelist variables which are changed from default values, and overwrites those.
+%\end{enumerate}
+%A template can be found in \path{NEMO/OPA_SRC/module.example}.
+%The effective namelist, taken in account during the run, is stored at execution time in
+%an \texttt{output\_namelist\_dyn} (or \texttt{\_ice} or \texttt{\_top}) file.
+%%gm  end
+
+%%nm: Add some words on the \NEMO\ dependencies
+%The model is implemented in \fninety, with preprocessing (C pre-processor).
+%It runs under UNIX.
+%It is optimized for vector computers and parallelised by domain decomposition with MPI.
+%All input and output is done in NetCDF (Network Common Data Format) with a optional direct access format for output.
+%To ensure the clarity and readability of the code it is necessary to follow coding rules.
+%The coding rules for OPA include conventions for naming variables,
+%with different starting letters for different types of variables (real, integer, parameter\ldots).
+%Those rules are briefly presented in \autoref{apdx:coding} and a more complete document is available .
+
+%The model is organized with a high internal modularity based on physics.
+%For example, each trend (\ie, a term in the RHS of the prognostic equation) for momentum and tracers
+%is computed in a dedicated module.
+%To make it easier for the user to find his way around the code, the module names follow a three-letter rule.
+%For example, \mdl{traldf} is a module related to the TRAcers equation, computing the Lateral DiFfussion.
+%The complete list of module names is presented in \autoref{apdx:coding}.      %====>>>> to be done !
+%Furthermore, modules are organized in a few directories that correspond to their category,
+%as indicated by the first three letters of their name (\autoref{tab:chapters}).
Index: NEMO/trunk/doc/latex/global/document.tex
===================================================================
--- NEMO/trunk/doc/latex/global/document.tex	(revision 14086)
+++ NEMO/trunk/doc/latex/global/document.tex	(revision 14113)
@@ -1,76 +1,68 @@
 
-%% ==============================================================================
-%% Template structure for reference manual
-%% ==============================================================================
+%% =================================================================================================
+%% Template structure for reference manuals
+%% =================================================================================================
 
 %% NEMO release version
-\def \version{4.0rc~}
+\def \version{trunk}
 
 %% Preamble
-%% ==============================================================================
+%% =================================================================================================
 
 %% Document layout
-\documentclass[draft]{scrreprt}
+\documentclass[fontsize = 10pt, twoside, abstract]{scrreprt}
 
-%% Load the configuration of the manual
-\input{../main/definitions}
-
-%% Load global *.tex files
-\input{../../global/preamble}
-
-\dominitoc
-
-%% Launch the creation of the indexes
-\input{../../global/indexes}
-
+%% Load manual configuration
+\input{../../global/prologue}
 
 %% End of common preamble between main and sub-files
 %% Override custom cmds for full manual compilation
-\newcommand{\onlyinsubfile}[1]{#1}
-\newcommand{\notinsubfile}[1]{}
+\newcommand{\subinc}[1]{#1}
+\newcommand{\subexc}[1]{}
 
 \begin{document}
 
-\renewcommand{\onlyinsubfile}[1]{}
-\renewcommand{\notinsubfile}[1]{#1}
-
-\renewcommand{\biblio}{}
-\renewcommand{\pindex}{}
+\renewcommand{\subinc}[1]{}
+\renewcommand{\subexc}[1]{#1}
 
 
 %% Frontmatter
-%% ==============================================================================
+%% =================================================================================================
 
-\pagenumbering{gobble}
+\pagenumbering{gobble}   %% Disable page numbering temporarily
 
 %% Title page
 \input{../../global/frontpage}
 
-\maketitle
-\emptythanks
+%% Footer for introductory parts (no header by cleaning default)
+\ofoot[]{\engine\ Reference Manual} \ifoot[]{\pagemark}
 
 %% Information page (2nd page)
 \input{../../global/info_page}
 
-%% Foreword
-%\frontmatter   %% Chapter numbering off and Roman numerals for page numbers
+\listoffigures
+\listoflistings
+\listoftables
+
+\clearpage
+
 \pagenumbering{roman}
-\input{foreword}
+\ofoot[]{\engine\ Reference Manual} \ifoot[]{\pagemark}
+
+\input{introduction}
 
 %% Table of Contents
 \tableofcontents
-\listoffigures
-\listoftables
-\listoflistings
 
 \clearpage
-%\end{document}
 
 
 %% Mainmatter
-%% ==============================================================================
+%% =================================================================================================
 
-%\mainmatter   %% Chapter numbering on, page numbering is reset with Arabic numerals
+%% Headings for document body
 \pagenumbering{arabic}
+\lohead{Chap.\ \thechapter\ \leftmark} \rehead{Sect.\ \thesection\ \rightmark}
+\ifoot[]{Page\ \pagemark\ of \pageref*{LastPage}}
 
 \include{chapters}
@@ -78,32 +70,19 @@
 
 %% Appendix
-%% ==============================================================================
+%% =================================================================================================
 
-%% Chapter numbering is reset with letters now
-\appendix   
+\appendix   %% Chapter numbering with letters by now
+\lohead{Apdx\ \thechapter\ \leftmark}
+\include{appendices}
 
-\include{appendices}
+%% Append coding rules for every manual
+\input{../../global/coding_rules}
 
 
 %% Backmatter
-%% ==============================================================================
+%% =================================================================================================
 
-%\backmatter   %% Chapter numbering off
-
-%% Bibliography
-\phantomsection
-\addcontentsline{toc}{chapter}{Bibliography}
-\bibliography{../main/bibliography}
-
-%% Index
-\clearpage
-\phantomsection
-\addcontentsline{toc}{chapter}{Indexes}
-\printindex[keys]
-\printindex[modules]
-\printindex[blocks]
-\printindex[parameters]
-\printindex[subroutines]
+%% Bibliography and indexes
+\input{../../global/epilogue}
 
 \end{document}
-
Index: NEMO/trunk/doc/latex/global/epilogue.tex
===================================================================
--- NEMO/trunk/doc/latex/global/epilogue.tex	(revision 14113)
+++ NEMO/trunk/doc/latex/global/epilogue.tex	(revision 14113)
@@ -0,0 +1,20 @@
+
+\clearpage
+
+%% Bibliography
+\phantomsection
+\addcontentsline{toc}{chapter}{Bibliography}
+\lohead{Bibliography} \rehead{Bibliography}
+\bibliography{../main/bibliography}
+
+\clearpage
+
+%% Indexes
+\phantomsection
+\addcontentsline{toc}{chapter}{Indexes}
+\lohead{Indexes} \rehead{Indexes}
+\printindex[blocks]
+\printindex[keys]
+\printindex[modules]
+\printindex[parameters]
+\printindex[subroutines]
Index: NEMO/trunk/doc/latex/global/frontpage.tex
===================================================================
--- NEMO/trunk/doc/latex/global/frontpage.tex	(revision 14086)
+++ NEMO/trunk/doc/latex/global/frontpage.tex	(revision 14113)
@@ -1,49 +1,67 @@
 
-\title{\heading}
-\author{\firstauthor \and \secondauthor\thanks{\protect\input{thanks}}}
-\date{\today}
+\begin{titlepage}
+%  \newgeometry{hmargin = 1.5cm, vmargin = 3cm}
+  \setlength{\parindent}{0pt}
 
-\pretitle{
   \begin{center}
-\begin{figure}[H]
-  \begin{minipage}[c]{0.35\textwidth}
-    \href{http://www.nemo-ocean.eu}{\includegraphics[width=0.7\textwidth]{logos/NEMO_grey}}
+    \begin{minipage}{0.3\textwidth}
+      \includegraphics[height=1.5cm]{logos/NEMO_grey}
+    \end{minipage}\begin{minipage}{0.6\textwidth}
+      \begin{center}
+      \Large\slshape
+      \textbf{N}ucleus for \textbf{E}uropean \textbf{M}odelling of the \textbf{O}cean \\
+      \medskip
+      \hyperref[resources]{\textcolor{black}{
+          \faWordpress \hspace{0.75cm} \faCodeFork      \hspace{0.75cm}
+          \faGithub    \hspace{0.75cm} \faCloudDownload \hspace{0.75cm} \faEnvelope
+        }
+      }
+      \end{center}
+    \end{minipage}
+  \end{center}
+
+  \spacetop
+  \textcolor{white}{\fontsize{0.8cm}{0.8cm}\selectfont\textbf{\heading}}
+  \ifdef{\subheading}{
+    \medskip
+    \par
+    \textcolor{white}{\Huge \subheading}
+  }{}
+  \spacedown
+
+  \begin{center}
+    \LARGE Version \version\ -\ \today \\
+    \medskip
+    \href{http://doi.org/10.5281/zenodo.\zid}{ \includegraphics{badges/zenodo.\zid} }
+  \end{center}
+
+  \vfill
+
+  \begin{minipage}{\authorswidth}
+    \raggedleft
+    \input{authors}
+  \end{minipage}\hspace{15pt}\begin{minipage}{0.02\linewidth}
+    \rule{1pt}{\rulelenght}
+  \end{minipage}\hspace{ 5pt}\begin{minipage}{\abstractwidth}
+    \begin{abstract}
+      \input{abstract}
+    \end{abstract}
   \end{minipage}
-  \hfill
-  \begin{minipage}[c]{0.65\textwidth}
-    \centering
-    \large{\em{{N}ucleus for {E}uropean {M}odelling of the {O}cean}}
-  \end{minipage}
-\end{figure}
-\vfill
-    \Huge
-}
-\posttitle{\par\end{center}\vskip 0.5em}
-\preauthor{\begin{center}\Large\lineskip0.5em\begin{tabular}[t]{c}}
-\postauthor{\end{tabular}\par\end{center}}
-\predate{
+
   \vfill
+
   \begin{center}
-    \large Version \version ---
-}
-\postdate{
-    \par~\\
-    \href{http://doi.org/10.5281/zenodo.\zid}{\includegraphics{{badges/zenodo.\zid}.pdf}}
+    \Large
+    \href{http://www.cmcc.it          }{ \includegraphics[height=1cm]{logos/CMCC} } \hspace{0.25cm}
+    \href{http://www.cnrs.fr          }{ \includegraphics[height=1cm]{logos/CNRS} } \hspace{0.25cm}
+    \href{http://www.mercator-ocean.fr}{ \includegraphics[height=1cm]{logos/MOI}  } \hspace{0.25cm}
+    \href{http://www.metoffice.gov.uk }{ \includegraphics[height=1cm]{logos/UKMO} } \hspace{0.25cm}
+    \href{http://nerc.ukri.org        }{ \includegraphics[height=1cm]{logos/NERC} } \\
+    \medskip
+    \slshape
+    {C}ommunity \hspace{1.5em} {O}cean \hspace{1.5em} {M}odel \\
   \end{center}
-  \vfill
-  \begin{center}
-    \href{http://www.cmcc.it}{          \includegraphics[height=0.055\textheight]{logos/CMCC}}
-    \hspace{0.5em}
-    \href{http://www.cnrs.fr}{          \includegraphics[height=0.055\textheight]{logos/CNRS}}
-    \hspace{0.9em}
-    \href{http://www.mercator-ocean.fr}{\includegraphics[height=0.055\textheight]{logos/MOI} }
-    \hspace{0.45em}
-    \href{http://www.metoffice.gov.uk}{ \includegraphics[height=0.055\textheight]{logos/UKMO}}
-    \hspace{0.5em}
-    \href{http://nerc.ukri.org}{        \includegraphics[height=0.055\textheight]{logos/NERC}} \\
-    \large{{\em{C}ommunity \hspace{1.5em} {O}cean \hspace{1.5em} {M}odel}}
-  \end{center}
-}
 
-\thanksmarkseries{fnsymbol}
+\end{titlepage}
 
+\restoregeometry
Index: NEMO/trunk/doc/latex/global/highlighting.tex
===================================================================
--- NEMO/trunk/doc/latex/global/highlighting.tex	(revision 14086)
+++ NEMO/trunk/doc/latex/global/highlighting.tex	(revision 14113)
@@ -2,10 +2,10 @@
 %% ==============================================================================
 
-\usepackage[outputdir=../build]{minted}
+\usepackage[outputdir=../build, chapter, newfloat]{minted}
 
 %% Global highlighting style
 \definecolor{bg}{HTML}{f8f8f8}
 \usemintedstyle{emacs}
-\setminted{bgcolor=bg, fontsize=\scriptsize, breaklines, frame=leftline}
+\setminted{bgcolor=bg, fontsize=\scriptsize, breaklines}
 \setminted[xml]{style=borland} %% Specific per language
 
@@ -22,12 +22,11 @@
 
 %% File
-\newmintedfile[forfile]{fortran}{}   % \forfile{../namelists/nam...}
+\newmintedfile[forfile]{fortran}{}
 
 %% Inline
-\newmintinline[forcode]{fortran}{fontsize=auto, frame=lines}   % \forcode{...}
-\newmintinline[xmlcode]{xml}{    fontsize=auto, frame=lines}   % \xmlcode{...}
-\newmintinline[snippet]{console}{fontsize=auto, frame=lines}   % \snippet{...}
+\newmintinline[forcode]{fortran}{bgcolor=, fontsize=auto}   % \forcode{...}
+\newmintinline[xmlcode]{xml}{    bgcolor=, fontsize=auto}   % \xmlcode{...}
+\newmintinline[snippet]{console}{bgcolor=, fontsize=auto}   % \snippet{...}
 
 %% Namelists inclusion
 \newcommand{\nlst}[1]{\forfile{../../../namelists/#1}}
-
Index: NEMO/trunk/doc/latex/global/index.ist
===================================================================
--- NEMO/trunk/doc/latex/global/index.ist	(revision 14086)
+++ NEMO/trunk/doc/latex/global/index.ist	(revision 14113)
@@ -1,8 +1,4 @@
 headings_flag 1
-heading_prefix "{\\medskip\\hfill\\large\\textsf{\\textbf{"
-heading_suffix "}}\\hfill}\\medskip\\nopagebreak\n"
-
+heading_prefix "\\medskip\\hfill\\textnormal{"
+heading_suffix "}\\hfill\\smallskip\n"
 delim_0 "\\dotfill~"
-delim_1 "\\dotfill~"
-delim_2 "\\dotfill~"
-
Index: NEMO/trunk/doc/latex/global/index.tex
===================================================================
--- NEMO/trunk/doc/latex/global/index.tex	(revision 14113)
+++ NEMO/trunk/doc/latex/global/index.tex	(revision 14113)
@@ -0,0 +1,25 @@
+
+\usepackage{imakeidx}
+
+%% Naming customization
+\renewcommand{\listingname}{namelist}
+\renewcommand{\listlistingname}{List of Namelists}
+
+%% Index entries (italic font for files, preformat for code)
+\newcommand{\hf}[1]{   \index{h90 files!#1}             \textit{#1.h90}          }
+\newcommand{\ifile}[1]{\index{Input NetCDF files!#1.nc} \textit{#1.nc}           }
+\newcommand{\jp}[1]{   \index{Model parameters!#1}      \texttt{#1}              }
+\newcommand{\key}[1]{  \index[keys]{#1@\texttt{\textbf{key\_#1}}} \texttt{\textbf{key\_#1}}}
+\newcommand{\mdl}[1]{  \index[modules]{#1@\textit{#1.F90}}        \textit{#1.F90}          }
+\newcommand{\nam}[2]{  \index[blocks]{#1@\texttt{\&nam#2}}        \forcode{&nam#1} (\autoref{lst:nam#1})}
+\newcommand{\np}[3][]{ \index[parameters]{#3@\texttt{#3}}         \forcode{#2#1}           }
+\newcommand{\rou}[1]{  \index[subroutines]{#1@\texttt{#1}}        \texttt{#1}              }
+
+
+\indexsetup{toclevel=section, othercode=\small}
+
+\makeindex[intoc=true, name=blocks     , title=Namelist blocks      , columns=3]
+\makeindex[intoc=true, name=keys       , title=CPP keys                        ]
+\makeindex[intoc=true, name=modules    , title=\fortran\ modules    , columns=3]
+\makeindex[intoc=true, name=parameters , title=Namelist parameters  , columns=3]
+\makeindex[intoc=true, name=subroutines, title=\fortran\ subroutines           ]
Index: NEMO/trunk/doc/latex/global/indexes.tex
===================================================================
--- NEMO/trunk/doc/latex/global/indexes.tex	(revision 14086)
+++ 	(revision )
@@ -1,32 +1,0 @@
-
-\usepackage{imakeidx}
-
-%% Index entries (italic font for files, preformat for code)
-\newcommand{\hf}[1]{\textit{#1.h90}   \index{h90 files!#1}}
-\newcommand{\ifile}[1]{\textit{#1.nc} \index{Input NetCDF files!#1.nc}}
-\newcommand{\jp}[1]{\texttt{#1}       \index{Model parameters!#1}}
-\newcommand{\key}[1]{\index[keys]{#1}        \texttt{\textbf{key\_#1}}}
-\newcommand{\mdl}[1]{\index[modules]{#1}     \textit{#1.F90}          }
-\newcommand{\ngn}[1]{\index[blocks]{#1}      \texttt{#1}              }
-\newcommand{\np}[1]{ \index[parameters]{#1}  \texttt{#1}              }
-\newcommand{\rou}[1]{\index[subroutines]{#1} \texttt{#1}              }
-
-\indexsetup{toclevel=section, othercode=\small}
-
-\makeindex[intoc=true, name=keys       , title=CPP keys                      ]
-\makeindex[intoc=true, name=modules    , title=Modules                       ]
-\makeindex[intoc=true, name=blocks     , title=Namelist blocks               ]
-\makeindex[intoc=true, name=parameters , title=Namelist parameters, columns=3]
-\makeindex[intoc=true, name=subroutines, title=Subroutines                   ]
-
-
-%% Load hyperref at the end of the preamble to make it work with other pkgs
-\usepackage{hyperref}                    %% hyper
-\hypersetup{
-%  pdftitle={\heading},
-%  pdfauthor={\firstauthor and \secondauthor},
-  colorlinks,
-  citecolor=olive,
-  linkcolor=blue,
-  urlcolor=gray
-}
Index: NEMO/trunk/doc/latex/global/info_page.tex
===================================================================
--- NEMO/trunk/doc/latex/global/info_page.tex	(revision 14086)
+++ NEMO/trunk/doc/latex/global/info_page.tex	(revision 14113)
@@ -2,14 +2,14 @@
 \thispagestyle{plain}
 
-% ================================================================
-% Disclaimer
-% ================================================================
+%% ================================================================
+%% Disclaimer
+%% ================================================================
 \subsubsection*{Disclaimer}
 
 Like all components of the modelling framework,
-the \engine~core engine is developed under the \href{http://www.cecill.info}{CECILL license},
-which is a French adaptation of the GNU GPL (General Public License).
+the \engine\ core engine is developed under the \href{http://www.cecill.info}{CECILL license},
+which is a French adaptation of the GNU GPL (\textbf{G}eneral \textbf{P}ublic \textbf{L}icense).
 Anyone may use it freely for research purposes, and is encouraged to
-communicate back to the NEMO team its own developments and improvements.
+communicate back to the development team its own developments and improvements.
 
 The model and the present document have been made available as a service to the community.
@@ -18,20 +18,24 @@
 Users are encouraged to bring them to our attention.
 
-The authors assume no responsibility for problems, errors, or incorrect usage of NEMO.
+The authors assume no responsibility for problems, errors, or incorrect usage of \NEMO.
 
-% ================================================================
-% External resources
-% ================================================================
+%% ================================================================
+%% External resources
+%% ================================================================
 \subsubsection*{Other resources}
+\label{resources}
 
 Additional information can be found on:
 \begin{itemize}
-\item the \href{http://www.nemo-ocean.eu}{website} of the project detailing several
+\item \faWordpress\ the \href{http://www.nemo-ocean.eu}{website} of the project detailing several
   associated applications and an exhaustive users bibliography
-\item the \href{http://forge.ipsl.jussieu.fr/nemo}{development platform} of the model with
-  the code repository and some main resources (wiki, ticket system, forums, \ldots)
-\item the \href{http://zenodo.org/communities/nemo-ocean}{online archive}
-  delivering the publications issued by the consortium
-\item two mailing lists:
+\item \faCodeFork\ the \href{http://forge.ipsl.jussieu.fr/nemo}{development platform} of
+  the model with the code repository for the shared reference and some main resources
+  (wiki, ticket system, forums, \ldots) \\
+  \faGithub\ the \href{http://github.com/NEMO-ocean/NEMO-examples}
+  {repository of the demonstration cases} for research or training
+\item \faCloudDownload\ the \href{http://zenodo.org/communities/nemo-ocean}{online archive}
+  delivering the publications issued by the consortium (manuals, reports, datasets, \ldots)
+\item \faEnvelope\ two mailing lists:
   the \href{http://listes.ipsl.fr/sympa/info/nemo-newsletter}{newsletter} for
   top-down communications from the project
@@ -41,25 +45,26 @@
 \end{itemize}
 
-% ================================================================
-% Citation
-% ================================================================
+%% ================================================================
+%% Citation
+%% ================================================================
 \subsubsection*{Citation}
 
 Reference for papers and other publications is as follows:
 
-\vspace{0.5cm}
+\medskip
 
-%% \sloppy: workaround for breaking DOI URL
-\sloppy
-``{\bfseries \heading}'', 
-\firstauthor and \secondauthor, 
-{\em Scientific Notes of Climate Modelling Center}, \textbf{\ipslnum} --- ISSN 1288-1619, 
-Institut Pierre-Simon Laplace (IPSL), 
-\href{https://doi.org/10.5281/zenodo.\zid}{doi:10.5281/zenodo.\zid}
+\begin{sloppypar}
+  ``{\bfseries \heading}\ifdef{\subheading}{ -- \subheading}{}'',
+  {\em Scientific Notes of Climate Modelling Center}, \textbf{\ipslnum} --- ISSN 1288-1619,
+  Institut Pierre-Simon Laplace (IPSL),
+  \href{https://doi.org/10.5281/zenodo.\zid}{doi:10.5281/zenodo.\zid}
+\end{sloppypar}
 
 \begin{figure}[b]
-  \begin{minipage}[c]{0.72\textwidth}
-    \small\ttfamily{Scientific Notes of Climate Modelling Center \\
-      ISSN 1288-1619                                             \\
+  \begin{minipage}[c]{0.7\textwidth}
+    \small
+    \ttfamily{
+      Scientific Notes of Climate Modelling Center \\
+      ISSN 1288-1619                               \\
       Institut Pierre-Simon Laplace (IPSL)
     }
@@ -67,6 +72,5 @@
   \hfill
   \begin{minipage}[c]{0.25\textwidth}
-    \href{http://www.cmc.ipsl.fr}{\includegraphics[width=\textwidth]{logos/IPSL_upright}}
+    \href{http://www.cmc.ipsl.fr}{\includegraphics[width=\textwidth]{logos/IPSL_master}}
   \end{minipage}
 \end{figure}
-
Index: NEMO/trunk/doc/latex/global/latexmk.pl
===================================================================
--- NEMO/trunk/doc/latex/global/latexmk.pl	(revision 14113)
+++ NEMO/trunk/doc/latex/global/latexmk.pl	(revision 14113)
@@ -0,0 +1,13 @@
+
+## Defaults
+$do_cd    = 1;   ## Change to the directory of the main source file
+$silent   = 1;   ## Less verbosity
+
+## Use of 'build' relative directory
+$ENV{'openout_any'}='a';
+$out_dir = '../build';
+
+## Global option
+set_tex_cmds( '-shell-escape' );
+
+$makeindex = "makeindex %O -s ../../global/index -o $out_dir/%D $out_dir/%S";
Index: NEMO/trunk/doc/latex/global/latexmkrc
===================================================================
--- NEMO/trunk/doc/latex/global/latexmkrc	(revision 14086)
+++ 	(revision )
@@ -1,17 +1,0 @@
-
-## Defaults
-$silent   = 1;
-$pdf_mode = 1;
-
-## Using relative paths
-$ENV{'openout_any'}='a';
-$out_dir = '../build';
-
-## Custom cmds
-$makeindex = 'makeindex -s %R.ist %O -o %D %S';
-$pdflatex  = 'pdflatex -shell-escape %O %S';
-
-#@BIBINPUTS=('.', '../main');
-#$bibtex    = 'bibtex %O ../main/bibliography.bib';
-#$kpsewhich = 'kpsewhich bibliography.bib'
-
Index: NEMO/trunk/doc/latex/global/new_cmds.tex
===================================================================
--- NEMO/trunk/doc/latex/global/new_cmds.tex	(revision 14086)
+++ NEMO/trunk/doc/latex/global/new_cmds.tex	(revision 14113)
@@ -2,13 +2,21 @@
 %% ==============================================================================
 
-%% Include references and index for compilation of single subfile 
-\newcommand{\mtoc}{\minitoc}
-\newcommand{\biblio}{\bibliography{../main/bibliography}}
-\newcommand{\pindex}{\printindex}
+%% Same slanted font for NEMO and its core engines
+\newcommand{\NEMO  }{\textsl{NEMO}}
+\newcommand{\OPA   }{\textsl{OPA}}
+\newcommand{\SIcube}{\textsl{SI$^3$}}
+\newcommand{\TOP   }{\textsl{TOP}}
+\newcommand{\PISCES}{\textsl{PISCES}}
+\newcommand{\NEMOVAR}{\textsl{NEMOVAR}}
 
-%% NEMO and Fortran in small capitals
-\newcommand{\NEMO}{\textsc{nemo}~}
-\newcommand{\fortran}{\textsc{Fortran}~}
-\newcommand{\fninety}{\textsc{Fortran 90}~}
+%% Links for external components
+\newcommand{\AGRIF}{\href{http://agrif.imag.fr}{AGRIF}}
+\newcommand{\CICE }{\href{http://github.com/CICE-Consortium/CICE}{CICE}}
+\newcommand{\OASIS}{\href{http://portal.enes.org/oasis}{OASIS}}
+\newcommand{\XIOS }{\href{http://forge.ipsl.jussieu.fr/ioserver}{XIOS}}
+
+%% Fortran in small capitals
+\newcommand{\fortran}{\textsc{Fortran}}
+\newcommand{\fninety}{\textsc{Fortran 90}}
 
 %% Common aliases
@@ -18,6 +26,6 @@
 \newcommand{\ztilde}{\ensuremath{\tilde z}}
 \newcommand{\stilde}{\ensuremath{\tilde s}}
-\newcommand{\ie}{\ensuremath{i.e.}~}
-\newcommand{\eg}{\ensuremath{e.g.}~}
+\newcommand{\ie}{\ensuremath{i.e.}}
+\newcommand{\eg}{\ensuremath{e.g.}}
 
 %% Inline maths
@@ -25,13 +33,37 @@
 \newcommand{\rdt}{\Delta t}
 
-%% Text env. for Gurvan
-\newcommand{\gmcomment}[1]{}
+%% Gurvan's comments
+\newcommand{\cmtgm}[1]{}
 
 %% Maths
 \newcommand{\lt}{\left}
 \newcommand{\rt}{\right}
-\newcommand{\vect}[1]{\ensuremath{\mathbf{#1}}}
+\newcommand{\vect}[1]{\ensuremath{ \mathbf{#1} }}
 \newcommand{\pd}[2][]{\ensuremath{\frac{\partial #1}{\partial #2}}}
 
-%% Workaround for issue with \listoffigures
-\DeclareRobustCommand{\triad}[6][]{\ensuremath{{}_{#2}^{#3}{\mathbb{#4}_{#1}}_{#5}^{\,#6}}}
+%% Convert chapter/section headings to lowercase
+\renewcommand{\chaptermark}[1]{\markboth{#1}{}}
+\renewcommand{\sectionmark}[1]{\markright{#1}{}}
+
+%% Retrieve month name
+\renewcommand{\today}{
+  \ifcase \month\or January\or February\or March\or
+                    April\or   May\or      June\or
+                    July\or    August\or   September\or
+                    October\or November\or December
+  \fi, \number \year
+}
+
+%% Link to orcid profile
+\newcommand{\orcid}[1]{\href{http://orcid.org/#1}{\textcolor{orcidcolor}\aiOrcidSquare}}
+
+%% Workaround for \listoffigures
+\DeclareRobustCommand{\triad}[6][]{\ensuremath{ {}_{#2}^{#3} { \mathbb{#4}_{#1} }_{#5}^{\,#6} }}
+
+%% New command for ToC
+\newcommand{\chaptertoc}[1][Table of contents]{%
+  \thispagestyle{empty}
+  \etocsettocstyle{\addsec*{#1}}{}%
+  \localtableofcontents%
+  \vfill
+}
Index: NEMO/trunk/doc/latex/global/packages.tex
===================================================================
--- NEMO/trunk/doc/latex/global/packages.tex	(revision 14086)
+++ NEMO/trunk/doc/latex/global/packages.tex	(revision 14113)
@@ -3,24 +3,44 @@
 %% ==============================================================================
 
-\usepackage{natbib}                      %% bib
-\usepackage{caption}                     %% caption
-\usepackage{xcolor}                      %% color
-\usepackage{times}                       %% font
-\usepackage{enumitem}                    %% list
-\usepackage{amsmath}                     %% maths
-%\usepackage{fancyhdr}                    %% page
-\usepackage{minitoc}                     %% toc
-\usepackage{subfiles}                    %% subdocs
-\usepackage{draftwatermark}              %% watermark
-\usepackage{titling}                     %% titlepage
+%% 'hyperref' pkg is loaded at the end of the preamble for higher compatibility
 
-%% Extensions in bundle package
-\usepackage{amssymb, graphicx, tabularx, textcomp}
-\usepackage[utf8]{inputenc}              %% input encoding
+%% KOMA-script
+\usepackage[footsepline=0.25pt, headsepline=0.25pt]{scrlayer-scrpage}
+
+%% customization (layout, header/footer styles & contents, background)
+\usepackage{draftwatermark}
+\usepackage[margin = 2cm]{geometry}
+\usepackage[pages = some]{background}   %% 'some' for title page
+\usepackage[Bjornstrup]{fncychap}
+
+%% Fonts
+\usepackage{fontspec}
+%% Issue with fontawesome pkg: path to FontAwesome.otf has to be hard-coded
+\defaultfontfeatures{
+    Path = /home/nicolas/.local/texlive/2020/texmf-dist/fonts/opentype/public/fontawesome/
+}
+\usepackage{academicons, fontawesome, newtxtext}
+
+%% Formatting
+\usepackage[inline]{enumitem}
+\usepackage{etoc, tabularx, xcolor}
+
+%% Graphics
+\usepackage{caption, graphicx, grffile}
+
+%% Labels
+\usepackage{lastpage, natbib}
+
+%% Mathematics
+\usepackage{amsmath, amssymb, mathtools}
+
+%% Versatility
+\usepackage{subfiles}
 
 %% Configuration
-\graphicspath{ {../../figures/} {../../figures/\engine/} }
-%\captionsetup{margin=10pt, font={small}, labelsep=colon, labelfont={bf}}
-\renewcommand{\bibfont}{\small}
-%\renewcommand{\bibsep}{3pt}
+\graphicspath{ {../../../} {../figures/} }
 
+%% Missing utmr8a font
+\usepackage{times}
+
+\usepackage{hyperref}   %% links
Index: NEMO/trunk/doc/latex/global/preamble.tex
===================================================================
--- NEMO/trunk/doc/latex/global/preamble.tex	(revision 14086)
+++ 	(revision )
@@ -1,7 +1,0 @@
-
-\input{../../global/packages}
-\input{../../global/highlighting}
-\input{../../global/new_cmds}
-\input{../../global/styles}
-%\input{../../global/todonotes}
-
Index: NEMO/trunk/doc/latex/global/prologue.tex
===================================================================
--- NEMO/trunk/doc/latex/global/prologue.tex	(revision 14113)
+++ NEMO/trunk/doc/latex/global/prologue.tex	(revision 14113)
@@ -0,0 +1,25 @@
+
+%% Specific configuration
+\input{../main/settings}
+
+%% Global configuration
+\input{../../global/packages}
+\input{../../global/highlighting}
+\input{../../global/index}
+\input{../../global/styles}
+\input{../../global/new_cmds}
+%\input{../../global/todonotes}
+
+%% Load hyperref at the end of the preamble to make it work with other pkgs
+\usepackage{hyperref}   %% links
+\hypersetup{
+  colorlinks,
+  citecolor = manualcolor, linkcolor = manualcolor, urlcolor = manualcolor,
+  final   %% Links even in draft mode
+}
+
+%% `\autoref` uncapitalization
+\renewcommand{\appendixautorefname}{appendix}
+\renewcommand{\equationautorefname}{equation}
+\renewcommand{\figureautorefname}{figure}
+\renewcommand{\tableautorefname}{table}
Index: NEMO/trunk/doc/latex/global/styles.tex
===================================================================
--- NEMO/trunk/doc/latex/global/styles.tex	(revision 14086)
+++ NEMO/trunk/doc/latex/global/styles.tex	(revision 14113)
@@ -3,59 +3,83 @@
 %% ==============================================================================
 
-%\pagestyle{fancy}
-\bibliographystyle{../../global/ametsoc}
-\renewcommand{\bibpreamble}{\begin{multicols}{2}}
-\renewcommand{\bibpostamble}{\end{multicols}}
-
-%% Additional fonts
-\DeclareMathAlphabet{\mathpzc}{OT1}{pzc}{m}{it}
+%% Colors
+\setmanualcolor
+\colorlet{manualcolorshaded}{manualcolor!60}
+\definecolor{orcidcolor}{HTML}{A6CE39}
 
 %% Page layout
-%\fancyhf{}
-%\fancyhead[LE,RO]{\bfseries\thepage}
-%\fancyhead[LO]{\bfseries\hspace{-0em}\rightmark}
-%\renewcommand{\sectionmark}[1]{\markright{\thesection.\ #1}}
-%\fancyhead[RE]{\bfseries\leftmark}
-%\renewcommand{\chaptermark}[1]{\markboth{#1}{}}
-%\renewcommand{\headrulewidth}{0.5pt}
-%\renewcommand{\footrulewidth}{0pt  }
-%\addtolength{\headheight}{2.6pt}
+\pagestyle{scrheadings}
+\addtokomafont{pagehead}{  \sffamily              }
+\addtokomafont{pagefoot}{  \sffamily \footnotesize}
+\addtokomafont{pagenumber}{\sffamily \slshape     }
+\addtokomafont{chapter}{\color{white}}
+\ohead{} \ofoot{}   %% Clear defaults
 
+%% Caption
+\captionsetup{font = footnotesize, justification = justified}
+
+%% Footnote
+\renewcommand{\thefootnote}{\fnsymbol{footnote}}
+
+%% Bibliography
+\bibliographystyle{../../global/ametsoc}
+\renewcommand{\bibfont}{\small}
+\renewcommand{\bibpreamble }{\begin{multicols}{2}}
+\renewcommand{\bibpostamble}{  \end{multicols}   }
 
 %% Catcodes
-%\makeatletter
-%\def\LigneVerticale{\vrule height 5cm depth 2cm\hspace{0.1cm}\relax}
-%\def\LignesVerticales{\let\LV\LigneVerticale\LV\LV\LV\LV\LV\LV\LV\LV\LV\LV}
-%\def\GrosCarreAvecUnChiffre#1{
-%	\rlap{\vrule height 0.8cm width 1cm depth 0.2cm}
-%	\rlap{\hbox to 1cm{\hss\mbox{\color{white} #1}\hss}}
-% 	\vrule height 0pt width 1cm depth 0pt
-%}
-%\def\@makechapterhead#1{
-%	\hbox{
-%		\huge\LignesVerticales\hspace{-0.5cm}
-%		\GrosCarreAvecUnChiffre{\thechapter}\hspace{0.2cm}
-%		\hbox{#1}
-%	}
-%	\par\vskip
-%1cm
-%}
-%\def\@makeschapterhead#1{
-%	\hbox{
-%		\huge\LignesVerticales
-%		\hbox{#1}
-%	}
-%	\par\vskip
-%2cm
-%}
-%\def\cleardoublepage{\clearpage\if@twoside \ifodd\c@page\else
-%  \hbox{}
-%  \vspace*{\fill}
-%  \vspace{\fill}
-%  \thispagestyle{empty}
-%  \newpage
-%  \if@twocolumn\hbox{}\newpage\fi\fi\fi}
-%\def\@seccntformat#1{\protect\makebox[0pt][r]{\csname the#1\endcsname\quad}}
-%\makeatother
+\makeatletter
 
+%% Prevent error with tikz and namelist inclusion
+\global\let\tikz@ensure@dollar@catcode=\relax
 
+%% First page
+\backgroundsetup{
+  firstpage = true,
+  scale = 1, angle = 0, opacity = 1,
+  contents = {
+    \begin{tikzpicture}[remember picture, overlay]
+      \path [fill = manualcolor] (-0.5\paperwidth, 7) rectangle (0.5\paperwidth, 10);
+    \end{tikzpicture}
+  }
+}
+
+%% Apply engine color for chapter headings: tweaking snippets from fncychap.sty
+\renewcommand{\DOCH}{%
+  \settowidth{\py}{\CNoV\thechapter}
+  \addtolength{\py}{-10pt}      % Amount of space by which the
+%                                  % number is shifted right
+  \fboxsep=0pt%
+  \colorbox{manualcolor}{\rule{0pt}{40pt}\parbox[b]{\textwidth}{\hfill}}%
+  \kern-\py\raise20pt%
+  \hbox{\color{manualcolorshaded}\CNoV\thechapter}\\%
+}
+\renewcommand{\DOTI}[1]{%
+  \nointerlineskip\raggedright%
+  \fboxsep=\myhi%
+  \vskip-1ex%
+  \colorbox{manualcolor}{\parbox[t]{\mylen}{\color{white}\CTV\FmTi{#1}}}\par\nobreak%
+  \vskip 40\p@%
+}
+\renewcommand{\DOTIS}[1]{%
+  \fboxsep=0pt
+  \colorbox{manualcolor}{\rule{0pt}{40pt}\parbox[b]{\textwidth}{\hfill}}\\%
+  \nointerlineskip\raggedright%
+  \fboxsep=\myhi%
+  \vskip-1ex% Remove white 1pt line
+  \colorbox{manualcolor}{\parbox[t]{\mylen}{\color{white}\CTV\FmTi{#1}}}\par\nobreak%
+  \vskip 40\p@%
+}
+
+%% Temporary fix
+\def\set@curr@file#1{%
+  \begingroup
+    \escapechar\m@ne
+    \xdef\@curr@file{\expandafter\string\csname #1\endcsname}%
+  \endgroup
+}
+\def\quote@name#1{"\quote@@name#1\@gobble""}
+\def\quote@@name#1"{#1\quote@@name}
+\def\unquote@name#1{\quote@@name#1\@gobble"}
+
+\makeatother
