Changeset 11433


Ignore:
Timestamp:
2019-08-12T21:44:18+02:00 (16 months ago)
Author:
nicolasmartin
Message:

Pre-implementation of new cover page and new headings style for reference manuals

Cover page

The layout of the frontpage has been completely redesigned,
a coloured banner has been added to emphasize the title and easily identify each manual
between them.
The chosen color for each document (blue for NEMO, gray for SI3 and green for TOP) will be
used throughout the manual for the links and in the chapter headings.
The list of authors (writers/editors/reviewers) for the version of the manual is given next to
the abstract, which is now included in the frontpage.
A link to an existing ORCID profile for the author precedes its name.
Few settings have been added to each definitions.tex in order to adjust the rendering of the cover page (vertical spaces above and below the title, a subtitle, the width for authors list and
abstract section)

Headings

  • header: chapter number and title for even pages, same infos for section otherwise
  • footer: name of the manual and page numbering with the total number of pages (reverse order between odd/even pages)

For the chapter heading, a new style 'Bjornstrup' from fncychap package is now use.

Abstract

Split the section in two paragraphs for all manuals

  1. Common description with almost the same sentences only customized by the general infos of the model
  2. Specific part for the characteristics of the model

Troubleshooting

As announced, I have introduced some icons from academicons and fontawesome packages.
It required to switch from pdflatex to xelatex for the compilation and it prevents from now
the building of the whole document.
Also the PDF generated does not look nice due to the font

Work in progress…

Location:
NEMO/trunk/doc/latex
Files:
1 added
20 edited

Legend:

Unmodified
Added
Removed
  • NEMO/trunk/doc/latex/NEMO/main/definitions.tex

    r11176 r11433  
    1 %% Engine (folder name) 
     1%% Engine (subfolder name) 
    22\def \engine{NEMO} 
    33 
    4 %% Title (variable name already use by 'titling' pkg) 
     4%% Title and cover page settings 
     5\def \spacetop{  \vspace*{1.85cm} } 
    56\def \heading{NEMO ocean engine} 
     7\def \subheading{} 
     8\def \spacedown{ \vspace*{0.75cm } } 
     9\def \authorswidth{ 0.3\linewidth} 
     10\def \rulelenght{270pt} 
     11\def \abstractwidth{0.6\linewidth} 
    612 
    7 %% Authors (thanks will apply to the second author) 
    8 \def \firstauthor{Gurvan Madec~} 
    9 \def \secondauthor{NEMO System Team} 
     13%% Color for document (frontpage banner, links  and chapter boxes) 
     14\def \setcolor{ \definecolor{manualcolor}{cmyk}{1, .60, 0, .40} } 
    1015 
    1116%% IPSL publication number 
  • NEMO/trunk/doc/latex/NEMO/main/foreword.tex

    r11176 r11433  
    1 % ================================================================ 
    2 % Foreword 
    3 % ================================================================ 
    4 \chapter*{Foreword} 
     1%% ================================================================ 
     2%% Abstract 
     3%% ================================================================ 
    54 
    6 The ocean engine of NEMO (Nucleus for European Modelling of the Ocean) is a primitive equation model adapted to 
    7 regional and global ocean circulation problems. 
    8 It is intended to be a flexible tool for studying the ocean and its interactions with the others components of 
    9 the earth climate system over a wide range of space and time scales. 
     5%% Common part between NEMO-SI3-TOP 
     6\NEMO\ (``Nucleus for European Modelling of the Ocean'') is a framework of ocean-related engines. 
     7It is intended to be a flexible tool for studying the ocean dynamics and thermodynamics (``blue ocean''), 
     8as well as its interactions with the components of the Earth climate system over 
     9a wide range of space and time scales. 
     10Within \NEMO, the ocean engine is interfaced with a sea-ice model (\SIcube\ or 
     11\href{http://github.com/CICE-Consortium/CICE}{CICE}), 
     12passive tracers and biogeochemical models (\TOP) and, 
     13via the \href{http://portal.enes.org/oasis}{OASIS} coupler, 
     14with several atmospheric general circulation models. 
     15It also supports two-way grid embedding by means of the \href{http://agrif.imag.fr}{AGRIF} software. 
    1016 
     17%% Specific part 
     18The primitive equation model is adapted to regional and global ocean circulation problems down to 
     19kilometric scale. 
    1120Prognostic variables are the three-dimensional velocity field, a non-linear sea surface height, 
    1221the \textit{Conservative} Temperature and the \textit{Absolute} Salinity. 
    13 In the horizontal direction, the model uses a curvilinear orthogonal grid and in the vertical direction, 
    14 a full or partial step $z$-coordinate, or $s$-coordinate, or a mixture of the two. 
     22In the horizontal direction, the model uses a curvilinear orthogonal grid and 
     23in the vertical direction, a full or partial step $z$-coordinate, or $s$-coordinate, or 
     24a mixture of the two. 
    1525The distribution of variables is a three-dimensional Arakawa C-type grid. 
    16 Various physical choices are available to describe ocean physics, including TKE, and GLS vertical physics. 
    17  
    18 Within NEMO, the ocean is interfaced with a sea-ice model (SI$^3$) 
    19  %or \href{https://github.com/CICE-Consortium/CICE}{CICE}), 
    20 passive tracer and biogeochemical models (TOP-PISCES) and, 
    21 via the \href{https://portal.enes.org/oasis}{OASIS} coupler, with several atmospheric general circulation models. 
    22 It also support two-way grid embedding via the \href{http://agrif.imag.fr}{AGRIF} software. 
     26Various physical choices are available to describe ocean physics, 
     27so as various HPC functionalities to improve performances. 
  • NEMO/trunk/doc/latex/NEMO/main/thanks.tex

    r11212 r11433  
    1 J\'{e}r\^{o}me Chanut, 
    2 Silvia Mocavero 
     1%Romain Bourdall\'{e}-Badie 
     2%\orcid{0000-0002-8742-3289} \\ 
     3%Mike Bell                   \\ 
     4%J\'{e}r\^{o}me Chanut       \\ 
     5%Emanuela Clementi 
     6%\orcid{0000-0002-5752-1849} \\ 
     7%Andrew Coward 
     8%\orcid{0000-0002-0456-129X} \\ 
     9%Massimiliano Drudi 
     10%\orcid{0000-0002-9951-740X} \\ 
     11%Christian \'{E}th\'{e}      \\ 
     12%Doroteaciro Iovino 
     13%\orcid{0000-0001-5132-7255} \\ 
     14%Dan Lea                     \\ 
     15%Claire L\'{e}vy 
     16%\orcid{0000-0003-2518-6692} \\ 
     17%Gurvan Madec 
     18%\orcid{0000-0002-6447-4198} \\ 
     19%Nicolas Martin              \\ 
     20%S\'{e}bastien Masson 
     21%\orcid{0000-0002-1694-8117} \\ 
     22%Pierre Mathiot              \\ 
     23%Silvia Mocavero 
     24%\orcid{0000-0002-6309-8282} \\ 
     25%Simon M\"{u}ller            \\ 
     26%George Nurser               \\ 
     27%Guillaume Samson 
     28%\orcid{0000-0001-7481-6369} \\ 
     29%Dave Storkey 
     30 
     31\orcid{0000-0002-8742-3289} Romain Bourdall\'{e}-Badie  \\ 
     32                            Mike Bell                   \\ 
     33                            J\'{e}r\^{o}me Chanut       \\ 
     34\orcid{0000-0002-5752-1849} Emanuela Clementi           \\ 
     35\orcid{0000-0002-0456-129X} Andrew Coward               \\ 
     36\orcid{0000-0002-9951-740X} Massimiliano Drudi          \\ 
     37                            Christian \'{E}th\'{e}      \\ 
     38\orcid{0000-0001-5132-7255} Doroteaciro Iovino          \\ 
     39                            Dan Lea                     \\ 
     40\orcid{0000-0003-2518-6692} Claire L\'{e}vy             \\ 
     41\orcid{0000-0002-6447-4198} Gurvan Madec                \\ 
     42                            Nicolas Martin              \\ 
     43\orcid{0000-0002-1694-8117} S\'{e}bastien Masson        \\ 
     44                            Pierre Mathiot              \\ 
     45\orcid{0000-0002-6309-8282} Silvia Mocavero             \\ 
     46                            Simon M\"{u}ller            \\ 
     47                            George Nurser               \\ 
     48\orcid{0000-0001-7481-6369} Guillaume Samson            \\ 
     49                            Dave Storkey 
  • NEMO/trunk/doc/latex/SI3/main/definitions.tex

    r11181 r11433  
    22\def \engine{SI3} 
    33 
    4 %% Title (variable name already use by 'titling' pkg) 
    5 \def \heading{Sea Ice modelling Integrated Initiative (SI$^3$) \\ The NEMO sea ice engine} 
     4%% Title and cover page settings 
     5\def \spacetop{  \vspace*{1.2cm} } 
     6\def \heading{Sea Ice modelling Integrated Initiative (SI$^3$)} 
     7\def \subheading{The NEMO sea ice engine} 
     8\def \spacedown{ \vspace*{1cm  } } 
     9\def \authorswidth{0.2\linewidth} 
     10\def \rulelenght{230pt} 
     11\def \abstractwidth{0.65\linewidth} 
    612 
    7 %% Authors (thanks will apply to the second author) 
    8 \def \firstauthor{} 
    9 \def \secondauthor{NEMO Sea Ice Working Group} 
     13%% Color for document (frontpage banner, links and chapter boxes) 
     14\def \setcolor{ \definecolor{manualcolor}{cmyk}{0, 0, 0, 0.4} } 
    1015 
    1116%% IPSL publication number 
  • NEMO/trunk/doc/latex/SI3/main/foreword.tex

    r11181 r11433  
     1%% ================================================================ 
     2%% Abstract 
     3%% ================================================================ 
     4 
     5%% Common part between NEMO-SI3-TOP 
     6``Sea Ice Modelling Integrated Initiative'' (\SIcube) is the sea ice engine of 
     7the \NEMO\ ocean model (``Nucleus for European Modelling of the Ocean''). 
     8It is intended to be a flexible tool for studying the sea ice dynamics and thermodynamics, 
     9brine inclusions and subgrid-scale thickness variations (``white ocean''), 
     10as well as its interactions with the other components of the Earth climate system over 
     11a wide range of space and time scales. 
     12\SIcube\ is interfaced with the \NEMO\ ocean engine, and, 
     13via the \href{http://portal.enes.org/oasis}{OASIS} coupler, 
     14with several atmospheric general circulation models. 
     15It also supports two-way grid embedding by means of the \href{http://agrif.imag.fr}{AGRIF} software. 
     16 
     17%% Specific part 
     18Designed for global to regional applications up to $~$10 km of effective resolution, 
     19\SIcube\ is a curvilinear grid, finite-difference implementation of the classical AIDJEX model 
     20(Arctic Ice Dynamics Joint EXperiment), 
     21combining the conservation of momentum for viscous-plastic continuum, 
     22energy and salt-conserving halo-thermodynamics, 
     23an explicit representation of subgrid-scale ice thickness variations, snow and melt ponds. 
     24An option to switch back to the \textit{single-category} (or \textit{2-level}) framework provides 
     25a cheap sea ice modelling solution. 
  • NEMO/trunk/doc/latex/SI3/main/thanks.tex

    r11171 r11433  
    1 TBD 
     1Yevgeny Aksenov       \\ 
     2Ed Blockley           \\ 
     3Matthieu Chevallier   \\ 
     4Danny Feltham         \\ 
     5Thierry Fichefet      \\ 
     6Gilles Garric         \\ 
     7Paul Holland          \\ 
     8Dorotea Iovino        \\ 
     9Gurvan Madec          \\ 
     10Fran\c cois Massonnet \\ 
     11Jeff Ridley           \\ 
     12Cl\'ement Rousset     \\ 
     13David Salas           \\ 
     14David Schroeder       \\ 
     15Steffen Tietsche      \\ 
     16Martin Vancoppenolle 
  • NEMO/trunk/doc/latex/SI3/subfiles/introduction.tex

    r11043 r11433  
    88\textcolor{red}{[ \textit{July 2018} ]} \\ 
    99 
    10 %Near the poles of the Earth, the seas and oceans freeze when seawater at the freezing point loses heat. The resulting forms of saline ice are collectively called \textit{sea ice} \citep{WMO70}, reaching up to a few meters in thickness, where as sea ice coverage is about 5\% of the global ocean, about 30 million square kilometers. All sea ice characteristics vary over a wide range of spatio-temporal scales, reflecting changes in heat, mass and momentum exchanges with the atmosphere and the ocean; the clearest temporal signal being an ample seasonal cycle. Sea ice formation and melting affects water mass formation in the ocean \citep{goosse_1999}. It not only impacts, but also reflects the state of the climate system \citep{budyko_1969,notz_2016}.  Sea ice also affects marine life, water chemistry and human activities in polar regions. Local populations use sea ice for travelling and hunting, whereas navigation and resource exploitation are dependent on sea ice conditions. For such reasons, ocean modelling systems, including NEMO, must include a sea ice component. 
     10%Near the poles of the Earth, the seas and oceans freeze when seawater at the freezing point loses heat. The resulting forms of saline ice are collectively called \textit{sea ice} \citep{WMO70}, reaching up to a few meters in thickness, where as sea ice coverage is about 5\% of the global ocean, about 30 million square kilometers. All sea ice characteristics vary over a wide range of spatio-temporal scales, reflecting changes in heat, mass and momentum exchanges with the atmosphere and the ocean; the clearest temporal signal being an ample seasonal cycle. Sea ice formation and melting affects water mass formation in the ocean \citep{goosse_1999}. It not only impacts, but also reflects the state of the climate system \citep{budyko_1969,notz_2016}.  Sea ice also affects marine life, water chemistry and human activities in polar regions. Local populations use sea ice for travelling and hunting, whereas navigation and resource exploitation are dependent on sea ice conditions. For such reasons, ocean modelling systems, including \NEMO, must include a sea ice component. 
    1111 
    12 The sea Ice Modelling Integrated Initiative (SI$^3$) is the sea ice engine of the Nucleus for European Modelling of the Ocean (NEMO). It is intended to be a flexible tool for studying sea ice and its interactions with the other components of the Earth System over a wide range of space and time scales. SI$^3$ is a curvilinear grid, finite-difference implementation of the classical AIDJEX\footnote{AIDJEX=\textbf{A}rctic \textbf{I}ce \textbf{D}ynamics \textbf{J}oint \textbf{EX}periment} model \citep{coon_1974}, combining the conservation of momentum for viscous-plastic continuum, energy and salt-conserving halo-thermodynamics, an explicit representation of subgrid-scale ice thickness variations, snow and melt ponds. An option to switch back to the \textit{single-category} (or \textit{2-level}) framework of \cite{hibler_1979} provides a cheap sea ice modelling solution. 
    13  
    14 SI$^3$ is the result of the recommendation of the Sea Ice Working Group (SIWG) to reduce duplication and better use development resources. SI$^3$ merges the capabilities of the 3 formerly used NEMO sea ice models (CICE, GELATO and LIM). The \textbf{3} in SI$^3$ refers to the three formerly used sea ice models. It also refers to linkages between 3 different media (ocean, ice, snow). The model can be spelt 'SI3' in situations where the superscript could be problematic (i.e., within code and svn repository etc.) The model name would be pronounced as 'si-cube' for short (or 'sea ice cubed' for slightly longer).  
     12\SIcube\ is the result of the recommendation of the Sea Ice Working Group (SIWG) to 
     13reduce duplication and better use development resources. 
     14\SIcube\ merges the capabilities of the 3 formerly sea ice models used in \NEMO\ (CICE, GELATO and LIM). 
     15The \textbf{3} in \SIcube\ refers either to the three formerly used sea ice models and 
     16linkages between 3 different media (ocean-ice-snow). 
     17The model would be pronounced as ``SI cube'' for short (or ``Sea Ice cubed'' for slightly longer), 
     18otherwise it can be spelt ``SI three'' in situations where the superscript could be problematic. 
    1519 
    1620% Limitations & scope 
    17 %There are limitations to the applicability of models such as SI$^3$. The continuum approach is not invalid for grid cell size above at least 1 km, below which sea ice particles may include just a few floes, which is not sufficient \citep{lepparanta_2011}. Second, one must remember that our current knowledge of sea ice is not as complete as for the ocean: there are no fundamental equations such as Navier Stokes equations for sea ice. Besides, important features and processes span widely different scales, such as brine inclusions (1 $\mu$m-1 mm) \citep{perovich_1996}, horizontal thickness variations (1 m-100 km) \citep{percival_2008}, deformation and fracturing (10 m-1000 km) \citep{marsan_2004}. These impose complicated and often subjective subgrid-scale treatments. All in all, there is more empirism in sea ice models than in ocean models.  
     21%There are limitations to the applicability of models such as \SIcube. The continuum approach is not invalid for grid cell size above at least 1 km, below which sea ice particles may include just a few floes, which is not sufficient \citep{lepparanta_2011}. Second, one must remember that our current knowledge of sea ice is not as complete as for the ocean: there are no fundamental equations such as Navier Stokes equations for sea ice. Besides, important features and processes span widely different scales, such as brine inclusions (1 $\mu$m-1 mm) \citep{perovich_1996}, horizontal thickness variations (1 m-100 km) \citep{percival_2008}, deformation and fracturing (10 m-1000 km) \citep{marsan_2004}. These impose complicated and often subjective subgrid-scale treatments. All in all, there is more empiricism in sea ice models than in ocean models. 
    1822 
    1923In order to handle all the subsequent required subjective choices, we applied the following guidelines or principles: 
    2024\begin{itemize} 
    21 \item Sea ice is frozen seawater that is in tight interaction with the underlying ocean. This close connexion suggests that the sea ice and ocean model components must be as consistent as possible. In practice, this is materialized by the close match between LIM and NEMO, in terms of numerical choices, regarding the grid (Arakawa C-type) and the numerical discretization (finite differences with NEMO scale factors). 
     25\item Sea ice is frozen seawater that is in tight interaction with the underlying ocean. This close connexion suggests that the sea ice and ocean model components must be as consistent as possible. In practice, this is materialized by the close match between LIM and \NEMO, in terms of numerical choices, regarding the grid (Arakawa C-type) and the numerical discretization (finite differences with \NEMO\ scale factors). 
    2226\item It is useful to be able to either prescribe the atmospheric state or to use an atmospheric model. For consistency and simplicity of the code, we choose to use formulations as close as possible in both cases. 
    23 \item Different resolutions and time steps can be used. There are parameters that depend on such choices. We thrieved to achieve a resolution and time-step independent code, by imposing a priori scaling on the resolution / time step dependence of such parameters. 
     27\item Different resolutions and time steps can be used. There are parameters that depend on such choices. We thrived to achieve a resolution and time-step independent code, by imposing a priori scaling on the resolution / time step dependence of such parameters. 
    2428\item Energy, mass and salt must be conserved as much as possible. 
    2529\end{itemize} 
     
    3135There are no more CPP keys in the code. \\ 
    3236 
    33 Namelists and output management follow NEMO guidelines. \\ 
     37Namelists and output management follow \NEMO\ guidelines. \\ 
    3438 
    3539Changes between releases. \\ 
     
    5559\item David Schroeder (CPOM, Reading, UK) 
    5660\item Steffen Tietsche (ECMWF, Reading, UK) 
    57 \item Martin Vancoppenolle (LOCEAN, CNRS, Paris, France, co-chair)  
     61\item Martin Vancoppenolle (LOCEAN, CNRS, Paris, France, co-chair) 
    5862\end{footnotesize} 
    5963\end{itemize} 
  • NEMO/trunk/doc/latex/TOP/main/definitions.tex

    r11181 r11433  
    22\def \engine{TOP} 
    33 
    4 %% Title (variable name already use by 'titling' pkg) 
    5 \def \heading{Tracers in Ocean Paradigm (TOP) \\ The NEMO passive tracers engine} 
     4%% Title and cover page settings 
     5\def \spacetop{  \vspace*{1.3cm} } 
     6\def \heading{Tracers in Ocean Paradigm (TOP) 
     7\def \subheading{The NEMO passive tracers engine} 
     8\def \spacedown{ \vspace*{1cm  } } 
     9\def \authorswidth{0.15\linewidth} 
     10\def \rulelenght{110pt} 
     11\def \abstractwidth{0.7\linewidth} 
    612 
    7 %% Authors (thanks will apply to the second author) 
    8 \def \firstauthor{} 
    9 \def \secondauthor{NEMO TOP Working Group} 
     13%% Color for document (frontpage banner, links and chapter boxes) 
     14\def \setcolor{ \definecolor{manualcolor}{cmyk}{1, 0, 1, 0.4} } 
    1015 
    1116%% IPSL publication number 
  • NEMO/trunk/doc/latex/TOP/main/foreword.tex

    r11181 r11433  
     1%% ================================================================ 
     2%% Abstract 
     3%% ================================================================ 
     4 
     5%% Common part between NEMO-SI3-TOP 
     6``Tracers in Ocean Paradigm'' (\TOP) is the passive tracers engine of 
     7the \NEMO\ ocean model (``Nucleus for European Modelling of the Ocean''). 
     8It is intended to be a flexible tool for studying the on/offline oceanic tracers transport and 
     9the biogeochemical processes (``green ocean''), 
     10as well as its interactions with the other components of the Earth climate system over 
     11a wide range of space and time scales. 
     12\TOP\ is interfaced with the \NEMO\ ocean engine, and, 
     13via the \href{http://portal.enes.org/oasis}{OASIS} coupler, 
     14with several atmospheric general circulation models. 
     15%It also supports two-way grid embedding by means of the \href{http://agrif.imag.fr}{AGRIF} software. 
     16 
     17%% Specific part 
     18This component provides the physical constraints and boundaries conditions for 
     19oceanic tracers transport and represents a generalized, hardwired interface toward 
     20biogeochemical models to enable a seamless coupling. 
     21In particular, transport dynamics are supplied by the ocean dynamical core thus 
     22enabling the use of all available advection and diffusion schemes in both on- and off-line modes. 
     23\TOP\ is designed to handle multiple oceanic tracers through a modular approach and 
     24it includes different sub-modules: ocean water age, inorganic carbon (CFCs) \& radiocarbon (C14b), 
     25built-in biogeochemical model (PISCES), and prototype for user-defined cases or 
     26coupling with alternative biogeochemical models (\eg \href{http://www.bfm-community.eu}{BFM}). 
  • NEMO/trunk/doc/latex/TOP/main/thanks.tex

    r11171 r11433  
    1 \'{E}th\'{e} Christian,  
    2 Lovato Tomas,  
    3 Aumont Olivier,  
    4 Palmi\'{e}ri Julien,  
    5 Mouchet Anne,  
    6 Nurser Georges,  
    7 Yool Andrew 
    8  
     1Olivier Aumont         \\ 
     2Christian \'{E}th\'{e} \\ 
     3Tomas Lovato           \\ 
     4Anne Mouchet           \\ 
     5Georges Nurser         \\ 
     6Julien Palmi\'{e}ri    \\ 
     7Andrew Yool 
  • NEMO/trunk/doc/latex/global/coding_rules.tex

    r11299 r11433  
    1 %\documentclass{article} 
    2  
    3 %\usepackage{fancyhdr} 
    4 %\usepackage{times} 
    5 %\usepackage{graphicx} 
    6 %\usepackage{hyperref} 
    7 %\usepackage{minted} 
    8 %\usepackage[normalem]{ulem}   % striketrough style with \sout{...} 
    9  
    10 %\hypersetup{pdftitle={NEMO coding conventions}, pdfauthor={NEMO System Team}, colorlinks} 
    11 %\setminted{style=emacs, breaklines, frame=leftline} 
    12 %\newmintinline[forcode]{fortran}{fontsize=auto, frame=lines}   % \forcode{...} 
    13 %\newminted[forlines]{fortran}{}                                % \begin{forlines} 
    14  
    15 %\pagestyle{empty} 
    16 %\setlength{\leftmargin}{1 cm} 
    17 %\setlength{\rightmargin}{1 cm} 
    18 %\setlength{\oddsidemargin}{0 cm} 
    19 %\setlength{\evensidemargin}{0 cm} 
    20 %\setlength{\topmargin}{-1cm} 
    21 %\setlength{\textwidth}{16 cm} 
    22 %\setlength{\textheight}{25cm} 
    23 %\pagestyle{fancy} 
    24  
    25 %\title{ 
    26 %  \includegraphics[width=0.3\textwidth]{../../../figures/NEMO_grey} \\ 
    27 %  \vspace{1.0cm} \rule{345pt}{1.5pt} \\ 
    28 %  \vspace{0.45cm} {\Huge NEMO coding conventions} \rule{345pt}{1.5pt} \\ 
    29 %} 
    30 %\title{NEMO coding conventions} 
    31 %\author{\Large NEMO System Team 
    32 %  \thanks{ 
    33 %    To be completed 
    34 %  } 
    35 %} 
    36 %\date{version X.X -- month year} 
    37  
    38 %\begin{document} 
    39  
    40 %\maketitle 
    41  
    42 %\newpage 
    43  
    44 %\tableofcontents 
    45  
    46 %\newpage 
    47  
    48 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
     1 
    492\chapter{Coding Rules} 
    503\label{apdx:coding} 
     
    6013produces fewer bugs and is easier to maintain. 
    6114Therefore, it is essential that the model development follows some rules: 
    62  
    63 - well planned and designed 
    64  
    65 - well written 
    66  
    67 - well documented (both on- and off-line) 
    68  
    69 - maintainable 
    70  
    71 - easily portable 
    72  
    73 - flexible. 
     15\begin{itemize} 
     16   \item well planned and designed 
     17   \item well written 
     18   \item well documented (both on- and off-line) 
     19   \item maintainable 
     20   \item easily portable 
     21   \item flexible. 
     22\end{itemize} 
    7423 
    7524To satisfy part of these aims, \NEMO is written with a coding standard which is close to the ECMWF rules, 
    7625named DOCTOR \citep{gibson_rpt86}.  
    7726These rules present some advantages like: 
    78  
    79 - to provide a well presented program 
    80  
    81 - to use rules for variable names which allow recognition of their type 
    82 (integer, real, parameter, local or shared variables, etc. ).  
     27\begin{itemize} 
     28   \item to provide a well presented program 
     29   \item to use rules for variable names which allow recognition of their type 
     30   (integer, real, parameter, local or shared variables, etc. ).  
     31\end{itemize} 
    8332 
    8433This facilitates both the understanding and the debugging of an algorithm. 
     
    8635\section{Introduction} 
    8736 
    88 This document describes conventions\index{conventions} used in NEMO coding and suggested for its development. 
    89 The objectives are to offer a guide to all readers of the NEMO code, and to facilitate the work of 
     37This document describes conventions used in \NEMO coding and suggested for its development. 
     38The objectives are to offer a guide to all readers of the \NEMO code, and to facilitate the work of 
    9039all the developers, including the validation of their developments, and 
    91 eventually the implementation of these developments within the NEMO platform. 
     40eventually the implementation of these developments within the \NEMO platform. 
    9241 
    9342A first approach of these rules can be found in the code in \path{./src/OCE/module_example} where 
     
    9847\footnote {\href{http://www.cesm.ucar.edu/working_groups/Software/dev_guide/dev_guide/node7.html}{UCAR conventions}},  
    9948the previous version of this document (``FORTRAN coding standard in the OPA System'') and 
    100 the expertise of the NEMO System Team. 
     49the expertise of the \NEMO System Team. 
    10150After a general overview below, this document will describe: 
    10251 
    10352\begin{itemize} 
    104 \item 
    105   The style rules, $i.e.$ the syntax, appearance and naming conventions chosen to improve readability of the code; 
    106 \item 
    107   The content rules, $i.e.$ the conventions to improve the reliability of the different parts of the code; 
    108 \item 
    109   The package rules to go a step further by improving the reliability of the whole and 
    110   interfaces between routines and modules. 
     53   \item The style rules, $i.e.$ the syntax, appearance and naming conventions chosen to improve readability of the code; 
     54   \item The content rules, $i.e.$ the conventions to improve the reliability of the different parts of the code; 
     55   \item The package rules to go a step further by improving the reliability of the whole and 
     56   interfaces between routines and modules. 
    11157\end{itemize} 
    11258 
    113 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    11459\section{Overview and general conventions} 
    11560 
    116 NEMO has 3 major components: ocean dynamics (\path{./src/OCE}), sea-ice (\path{./src/ICE}) and 
     61\NEMO has 3 major components: ocean dynamics (\path{./src/OCE}), sea-ice (\path{./src/ICE}) and 
    11762marine biogeochemistry (\path{./src/MBG}). 
    11863%, linear-tangent and adjoint of the dynamics ($TAM$) each of them corresponding to a directory. 
     
    12671See \path{.src/OCE/DOM/phycst.F90} files for conversions. 
    12772 
    128 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    12973\section{Architecture} 
    13074 
    131 Within each directory, organisation of files is driven by orthogonality\index{orthogonality}, 
     75Within each directory, organisation of files is driven by orthogonality, 
    13276$i.e.$ one functionality of the code is intended to be in one and only one directory, and 
    13377one module and all its related routines are in one file. 
    134 The functional modules\index{module} are: 
     78The functional modules are: 
    13579 
    13680\begin{itemize} 
    137 \item \path{SBC}             surface module 
    138 \item \path{IOM}             management of the I/O 
    139 \item \path{NST}             interface to AGRIF (nesting model) for dynamics and biogeochemistry 
    140 \item \path{OBC}, \path{BDY} management of structured and unstructured open boundaries  
    141 \item \path{C1D}             1D (vertical) configuration for dynamics, sea-ice and biogeochemistry 
    142 \item \path{OFF}             off-line module: passive tracer or biogeochemistry alone 
    143 \item \path{...} 
     81   \item \path{SBC}             surface module 
     82   \item \path{IOM}             management of the I/O 
     83   \item \path{NST}             interface to AGRIF (nesting model) for dynamics and biogeochemistry 
     84   \item \path{OBC}, \path{BDY} management of structured and unstructured open boundaries  
     85   \item \path{C1D}             1D (vertical) configuration for dynamics, sea-ice and biogeochemistry 
     86   \item \path{OFF}             off-line module: passive tracer or biogeochemistry alone 
     87   \item \path{...} 
    14488\end{itemize} 
    14589 
     
    14791this module (\texttt{dom\_init, dom\_nam, dom\_ctl}). 
    14892 
    149 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    15093\section{Style rules} 
    15194 
    152 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    15395\subsection{Argument list format} 
    15496 
    155 Routine argument lists will contain a maximum 5 variables\index{variable} per line, 
     97Routine argument lists will contain a maximum 5 variables per line, 
    15698whilst continuation lines can be used. 
    15799This applies both to the calling routine and the dummy argument list in the routine being called. 
     
    164106\end{forlines} 
    165107 
    166 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    167108\subsection{Array syntax} 
    168109 
     
    198139\end{forlines} 
    199140 
    200 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    201141\subsection{Case} 
    202142 
    203143All FORTRAN keywords are in capital: \forcode{DIMENSION}, \forcode{WRITE}, \forcode{DO}, \forcode{END DO}, 
    204 \forcode{NAMELIST}, ... All other parts of the NEMO code will be written in lower case. 
    205  
    206 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
     144\forcode{NAMELIST}, ... All other parts of the \NEMO code will be written in lower case. 
     145 
    207146\subsection{Comments} 
    208147 
     
    248187\end{enumerate} 
    249188 
    250 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    251189\subsection{Continuation lines} 
    252190 
     
    265203use a ``\&'' as first character of the continuing lines to maintain the alignment. 
    266204 
    267 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    268205\subsection{Declaration of arguments and local variables} 
    269206 
     
    277214\end{forlines} 
    278215 
    279 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    280216\subsection{F90 Standard} 
    281217 
    282 NEMO software adheres to the FORTRAN 95 language standard and does not rely on any specific language or 
     218\NEMO software adheres to the \fninety language standard and does not rely on any specific language or 
    283219vendor extensions. 
    284220 
    285  
    286 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    287221\subsection{Free-Form Source} 
    288222 
     
    292226Multi-line comments that extend to column 100 are unacceptable. 
    293227 
    294 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    295228\subsection{Indentation} 
    296229 
     
    310243\end{forlines} 
    311244 
    312 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    313245\subsection{Loops} 
    314246 
     
    317249In the case of a long loop, a self-descriptive label can be used ($i.e.$ not just a number). 
    318250 
    319 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    320251\subsection{Naming Conventions: files} 
    321252 
     
    331262} 
    332263 
    333 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    334264\subsection{Naming Conventions: modules} 
    335265 
     
    338268For example, zdftke, where ``zdf'' stands for vertical diffusion, and ``tke'' for turbulent kinetic energy. \\ 
    339269Note that by implication multiple modules are not allowed in a single file. 
    340 The use of common blocks is deprecated in Fortran 90 and their use in NEMO is strongly discouraged. 
     270The use of common blocks is deprecated in \fortran 90 and their use in \NEMO is strongly discouraged. 
    341271Modules are a better way to declare static data. 
    342272Among the advantages of modules is the ability to freely mix data of various types, and 
    343273to limit access to contained variables through the use of the \forcode{ONLY} and \forcode{PRIVATE} attributes. 
    344274 
    345 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    346275\subsection{Naming Conventions: variables} 
    347276 
    348277All variable should be named as explicitly as possible in English. 
    349278The naming convention concerns prefix letters of these name, in order to identify the variable type and status. \\ 
    350 Never use a FORTRAN keyword as a routine or variable name. \\ 
     279Never use a \fortran keyword as a routine or variable name. \\ 
    351280The table below lists the starting letter(s) to be used for variable naming, depending on their type and status: 
    352281%--------------------------------------------------TABLE-------------------------------------------------- 
     
    355284    \begin{tabular}{|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|} 
    356285      \hline 
    357       Type \par / Status &   integer&   real&   logical &   character&   double \par precision&   complex \\ 
    358       \hline 
    359       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} \\ 
    360       \hline 
    361       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} \\ 
    362       \hline 
    363       local \par variable& \textbf{i}& \textbf{z}& \textbf{ll}& \textbf{cl}& \textbf{cd}& \textbf{yl} \\ 
    364       \hline 
    365       loop \par control& \textbf{j} \par \textit{but not } \par \textbf{jp}& & & & &  \\ 
    366       \hline 
    367       parameter& \textbf{jp}& \textbf{pp}& \textbf{lp}& \textbf{cp}& \textbf{dp}& \textbf{yp} \\ 
    368       \hline 
    369       namelist& \textbf{nn\_}& \textbf{rn\_}& \textbf{ln\_}& \textbf{cn\_}& \textbf{dn\_}& \\ 
    370       \hline 
    371       CPP \par macro& \textbf{kf}& \textbf{sf} \par & & & & \\ 
     286      Type \par / Status                                                                          & 
     287      integer                                                                                     & 
     288      real                                                                                        & 
     289      logical                                                                                     & 
     290      character                                                                                   & 
     291      double \par precision                                                                       & 
     292      complex                                                                                     \\ 
     293      \hline 
     294      public \par or \par module variable                                                         &  
     295      \textbf{m n} \par \textit{but not} \par \textbf{nn\_}                                       &  
     296      \textbf{a b e f g h o} \textbf{q} \textit{to} \textbf{x} \par but not \par \textbf{fs rn\_} & 
     297      \textbf{l} \par \textit{but not} \par \textbf{lp ld ll ln\_}                                & 
     298      \textbf{c} \par \textit{but not} \par \textbf{cp cd cl cn\_}                                & 
     299      \textbf{d} \par \textit{but not} \par \textbf{dp dd dl dn\_}                                & 
     300      \textbf{y} \par \textit{but not} \par \textbf{yp yd yl}                                     \\ 
     301      \hline 
     302      dummy \par argument                                                                         & 
     303      \textbf{k} \par \textit{but not} \par \textbf{kf}                                           &  
     304      \textbf{p} \par \textit{but not} \par \textbf{pp pf}                                        &  
     305      \textbf{ld}                                                                                 & 
     306      \textbf{cd}                                                                                 & 
     307      \textbf{dd}                                                                                 & 
     308      \textbf{yd}                                                                                 \\ 
     309      \hline 
     310      local \par variable                                                                         & 
     311      \textbf{i}                                                                                  &  
     312      \textbf{z}                                                                                  & 
     313      \textbf{ll}                                                                                 & 
     314      \textbf{cl}                                                                                 & 
     315      \textbf{cd}                                                                                 & 
     316      \textbf{yl}                                                                                 \\ 
     317      \hline 
     318      loop \par control                                                                           & 
     319      \textbf{j} \par \textit{but not} \par \textbf{jp}                                           & 
     320                                                                                                  & 
     321                                                                                                  & 
     322                                                                                                  & 
     323                                                                                                  & 
     324                                                                                                  \\ 
     325      \hline 
     326      parameter                                                                                   & 
     327      \textbf{jp}                                                                                 & 
     328      \textbf{pp}                                                                                 & 
     329      \textbf{lp}                                                                                 & 
     330      \textbf{cp}                                                                                 & 
     331      \textbf{dp}                                                                                 & 
     332      \textbf{yp}                                                                                 \\ 
     333      \hline 
     334      namelist                                                                                    & 
     335      \textbf{nn\_}                                                                               &  
     336      \textbf{rn\_}                                                                               & 
     337      \textbf{ln\_}                                                                               & 
     338      \textbf{cn\_}                                                                               & 
     339      \textbf{dn\_}                                                                               & 
     340                                                                                                  \\ 
     341      \hline 
     342      CPP \par macro                                                                              & 
     343      \textbf{kf}                                                                                 & 
     344      \textbf{sf}                                                                                 & 
     345                                                                                                  & 
     346                                                                                                  & 
     347                                                                                                  & 
     348                                                                                                  \\ 
    372349      \hline 
    373350    \end{tabular} 
     
    377354%-------------------------------------------------------------------------------------------------------------- 
    378355 
    379 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    380356\subsection{Operators} 
    381357 
     
    385361In general use the notation: \\ 
    386362$<Blank><Operator><Blank>$ 
    387 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
     363 
    388364\subsection{Pre processor} 
    389365 
     
    412388Is to be used rather than the \#ifdef abbreviate form since it may have conflicts with some Unix scripts. 
    413389 
    414 Tests on cpp keys included in NEMO at compilation step: 
     390Tests on cpp keys included in \NEMO at compilation step: 
    415391 
    416392\begin{itemize} 
     
    421397  If a change occurs in the CPP keys used for a given experiment, the whole compilation phase is done again. 
    422398\end{itemize} 
    423 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
     399 
    424400\section{Content rules} 
    425401 
    426 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    427402\subsection{Configurations} 
    428403 
    429 The configuration defines the domain and the grid on which NEMO is running. 
    430 It may be useful to associate a cpp key and some variables to a given configuration, although 
     404The configuration defines the domain and the grid on which \NEMO is running. 
     405It may be useful to associate a CPP key and some variables to a given configuration, although 
    431406the part of the code changed under each of those keys should be minimized. 
    432407As an example, the "ORCA2" configuration (global ocean, 2 degrees grid size) is associated with 
     
    438413\end{forlines} 
    439414 
    440 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    441415\subsection{Constants} 
    442416 
    443 Physical constants ($e.g.$ $\pi$, gas constants) must never be hardwired into the executable portion of a code. 
     417Physical constants ($e.g.$ $\pi$, gas constants) must never be hard-wired into the executable portion of a code. 
    444418Instead, a mnemonically named variable or parameter should be set to the appropriate value, 
    445 in the setup routine for the package\index{package}. 
     419in the setup routine for the package. 
    446420We realize than many parameterizations rely on empirically derived constants or fudge factors, 
    447421which are not easy to name. 
     
    450424Hard-coded numbers should never be passed through argument lists. 
    451425 
    452 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    453426\subsection{Declaration for variables and constants} 
    454427 
     
    512485improve control of variables in routine calls. 
    513486 
    514 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    515487\subsection{Headers} 
    516488 
    517 Prologues are not used in NEMO for now, although it may become an interesting tool in combination with 
     489Prologues are not used in \NEMO for now, although it may become an interesting tool in combination with 
    518490ProTeX auto documentation script in the future. 
    519491Rules to code the headers and layout of a module or a routine are illustrated in the example module available with 
    520492the code: \path{./src/OCE/module_example} 
    521493 
    522 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    523494\subsection{Interface blocks} 
    524495 
     
    528499FORTRAN 95 compilers can automatically provide explicit interface blocks for routines contained in a module. 
    529500 
    530 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    531501\subsection{I/O Error Conditions} 
    532502 
     
    536506a negative value means the end of record or end of file was encountered. 
    537507 
    538 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    539508\subsection{PRINT - ASCII output files} 
    540509 
     
    551520\end{forlines} 
    552521 
    553 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    554522\subsection{Precision} 
    555523 
     
    570538\end{forlines} 
    571539 
    572 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    573540\subsection{Structures} 
    574541 
    575 The \forcode{TYPE} structure allowing to declare some variables is more often used in NEMO, 
     542The \forcode{TYPE} structure allowing to declare some variables is more often used in \NEMO, 
    576543especially in the modules dealing with reading fields, or interfaces. 
    577544For example: 
     
    592559Missing rule on structure name?? 
    593560 
    594 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    595561\section{Packages coding rules} 
    596562 
    597 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    598563\subsection{Bounds checking} 
    599564 
    600 NEMO is able to run when an array bounds checking option is enabled 
     565\NEMO is able to run when an array bounds checking option is enabled 
    601566(provided the cpp key \texttt{key\_vectopt\_loop} is not defined). \\ 
    602567Thus, constructs of the following form are disallowed: 
     
    610575it effectively disables array bounds checking. 
    611576 
    612 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    613577\subsection{Communication} 
    614578 
     
    624588} 
    625589 
    626 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    627590\subsection{Error conditions} 
    628591 
     
    634597see \textit{stpctl.F90}. 
    635598 
    636 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    637599\subsection{Memory management} 
    638600 
    639601The main action is to identify and declare which arrays are \forcode{PUBLIC} and which are \forcode{PRIVATE}. \\ 
    640 As of version 3.3.1 of NEMO, the use of static arrays (size fixed at compile time) has been deprecated. 
     602As of version 3.3.1 of \NEMO, the use of static arrays (size fixed at compile time) has been deprecated. 
    641603All module arrays are now declared \forcode{ALLOCATABLE} and 
    642604allocated in either the \texttt{<module\_name>\_alloc()} or \texttt{<module\_name>\_init()} routines. 
     
    644606the \texttt{stat=<integer\ variable>} optional argument. \\ 
    645607 
    646 In addition to arrays contained within modules, many routines in NEMO require local, ``workspace'' arrays to 
     608In addition to arrays contained within modules, many routines in \NEMO require local, ``workspace'' arrays to 
    647609hold the intermediate results of calculations. 
    648 In previous versions of NEMO, these arrays were declared in such a way as to be automatically allocated on 
     610In previous versions of \NEMO, these arrays were declared in such a way as to be automatically allocated on 
    649611the stack when the routine was called. 
    650612An example of an automatic array is: 
     
    735697It is then associated with a sub-array of \texttt{wrk\_3d\_5} once the call to 
    736698\texttt{wrk\_in\_use()} has completed successfully. 
    737 Note that in F95 (to which NEMO conforms) it is not possible for either the upper or lower array bounds of 
     699Note that in F95 (to which \NEMO conforms) it is not possible for either the upper or lower array bounds of 
    738700the pointer object to differ from those of the target array. \\ 
    739701 
     
    748710This should enable the developer to choose alternatives for use in the subroutine being worked on. \\ 
    749711 
    750 When compiling NEMO for production runs, 
     712When compiling \NEMO for production runs, 
    751713the calls to {\texttt{wrk\_in\_use()} / \texttt{wrk\_not\_released()} can be reduced to stubs that just 
    752714return \forcode{.false.} by setting the cpp key \texttt{key\_no\_workspace\_check}. 
    753 These stubs may then be inlined (and thus effectively removed altogether) by setting appropriate compiler flags 
     715These stubs may then be in-lined (and thus effectively removed altogether) by setting appropriate compiler flags 
    754716($e.g.$ ``-finline'' for the Intel compiler or ``-Q'' for the IBM compiler). 
    755717 
    756 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    757718\subsection{Optimisation} 
    758719 
    759720Considering the new computer architecture, optimisation cannot be considered independently from the computer type. 
    760 In NEMO, portability is a priority, before any too specific optimisation. 
     721In \NEMO, portability is a priority, before any too specific optimisation. 
    761722 
    762723Some tools are available to help: for vector computers, \texttt{key\_vectopt\_loop} allows to unroll a loop 
    763724 
    764 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    765725\subsection{Package attribute: \forcode{PRIVATE}, \forcode{PUBLIC}, \forcode{USE}, \forcode{ONLY}} 
    766726 
     
    770730defined in a module are to be made available to the using routine. 
    771731 
    772 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    773 \subsection {Parallelism using MPI} 
    774  
    775 NEMO is written in order to be able to run on one processor, or on one or more using MPI 
     732\subsection{Parallelism using MPI} 
     733 
     734\NEMO is written in order to be able to run on one processor, or on one or more using MPI 
    776735($i.e.$ activating the cpp key $key\_mpp\_mpi$). 
    777 The domain decomposition divides the global domain in cubes (see NEMO reference manual). 
     736The domain decomposition divides the global domain in cubes (see \NEMO reference manual). 
    778737Whilst coding a new development, the MPI compatibility has to be taken in account 
    779738(see \path{./src/LBC/lib_mpp.F90}) and should be tested. 
    780739By default, the $x$-$z$ part of the decomposition is chosen to be as square as possible. 
    781 However, this may be overriden by specifying the number of subdomains in latitude and longitude in 
     740However, this may be overriden by specifying the number of sub-domains in latitude and longitude in 
    782741the \texttt{nammpp} section of the namelist file. 
    783742 
    784 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    785743\section{Features to be avoided} 
    786744 
     
    804762  \forcode{SELECT CASE} construct instead) 
    805763\item 
    806   Labeled \forcode{DO} construct 
    807   (use unlabeled \forcode{END DO} instead) 
     764  Labelled \forcode{DO} construct 
     765  (use unlabelled \forcode{END DO} instead) 
    808766\item 
    809767  \forcode{FORMAT} statement 
     
    817775  \forcode{PAUSE} 
    818776\item 
    819   \forcode{ENTRY} statement: a subprogram must only have one entry point. 
     777  \forcode{ENTRY} statement: a sub-program must only have one entry point. 
    820778\item 
    821779  \forcode{RETURN} is obsolete and so not necessary at the end of program units 
     
    837795\end{itemize} 
    838796 
    839 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    840  
    841 % \printindex 
    842 % \input NEMO_coding.conv.ind 
    843  
    844 %\end{document} 
  • NEMO/trunk/doc/latex/global/document.tex

    r11299 r11433  
    55 
    66%% NEMO release version 
    7 \def \version{4.0rc~} 
     7\def \version{trunk} 
    88 
    99%% Preamble 
     
    1111 
    1212%% Document layout 
    13 \documentclass[draft]{scrreprt} 
     13\documentclass[twoside = semi, abstract = on]{scrreprt} 
    1414 
    15 %% Load the configuration of the manual 
    16 \input{../main/definitions} 
    17  
    18 %% Load global *.tex files 
     15%% Load configurations 
    1916\input{../../global/preamble} 
    2017 
    2118\dominitoc 
    22  
    23 %% Launch the creation of the indexes 
    24 \input{../../global/indexes} 
    25  
    2619 
    2720%% End of common preamble between main and sub-files 
     
    4235%% ============================================================================== 
    4336 
     37%% Disable page numbering temporarily 
    4438\pagenumbering{gobble} 
    4539 
    4640%% Title page 
    47 \input{../../global/frontpage} 
     41%\input{../../global/frontpage} 
     42\input{../../global/frontpage_new} 
    4843 
    49 \maketitle 
    50 \emptythanks 
     44%\maketitle 
     45%\emptythanks 
    5146 
    5247%% Information page (2nd page) 
    5348\input{../../global/info_page} 
    5449 
     50%% Headings for introductory parts (no header, simple footer) 
     51\ofoot{\engine\ Reference Manual}\ifoot{\pagemark} 
     52\pagenumbering{roman} 
     53 
    5554%% Foreword 
    56 %\frontmatter   %% Chapter numbering off and Roman numerals for page numbers 
    57 \pagenumbering{roman} 
    58 \input{foreword} 
     55%\input{foreword} 
    5956 
    6057%% Table of Contents 
    6158\tableofcontents 
    62 \listoffigures 
    63 \listoftables 
    64 \listoflistings 
     59%\listoffigures 
     60%\listoftables 
     61%\listoflistings 
    6562 
    6663\clearpage 
    67 %\end{document} 
    6864 
    6965 
     
    7167%% ============================================================================== 
    7268 
    73 %\mainmatter   %% Chapter numbering on, page numbering is reset with Arabic numerals 
     69%% Headings for document body 
     70\lohead{Chap.\ \thechapter\ \leftmark}\rehead{Sect.\ \thesection\ \rightmark} 
     71\ifoot{Page\ \pagemark\ of \pageref*{LastPage}} 
    7472\pagenumbering{arabic} 
    7573 
     
    8179 
    8280%% Chapter numbering is reset with letters now 
    83 \appendix    
     81\appendix 
    8482 
    8583\include{appendices} 
     
    110108 
    111109\end{document} 
    112  
  • NEMO/trunk/doc/latex/global/frontpage.tex

    r11176 r11433  
    11 
    22\title{\heading} 
    3 \author{\firstauthor \and \secondauthor\thanks{\protect\input{thanks}}} 
    43\date{\today} 
     4\author{\protect\input{thanks}} 
    55 
    66\pretitle{ 
    77  \begin{center} 
    8 \begin{figure}[H] 
    9   \begin{minipage}[c]{0.35\textwidth} 
    10     \href{http://www.nemo-ocean.eu}{\includegraphics[width=0.7\textwidth]{logos/NEMO_grey}} 
    11   \end{minipage} 
    12   \hfill 
    13   \begin{minipage}[c]{0.65\textwidth} 
    14     \centering 
    15     \large{\em{{N}ucleus for {E}uropean {M}odelling of the {O}cean}} 
    16   \end{minipage} 
    17 \end{figure} 
    18 \vfill 
     8    \begin{figure}[H] 
     9      \begin{minipage}[c]{0.35\textwidth} 
     10        \href{http://www.nemo-ocean.eu}{\includegraphics[width=0.7\textwidth]{logos/NEMO_grey}} 
     11      \end{minipage} 
     12      \hfill 
     13      \begin{minipage}[c]{0.65\textwidth} 
     14        \centering 
     15        \large{\em{{N}ucleus for {E}uropean {M}odelling of the {O}cean}} 
     16      \end{minipage} 
     17    \end{figure} 
     18    \vfill 
    1919    \Huge 
    2020} 
    21 \posttitle{\par\end{center}\vskip 0.5em} 
    22 \preauthor{\begin{center}\Large\lineskip0.5em\begin{tabular}[t]{c}} 
    23 \postauthor{\end{tabular}\par\end{center}} 
     21\posttitle{ 
     22  \par 
     23  \end{center} 
     24  \vskip 0.5em 
     25} 
    2426\predate{ 
    2527  \vfill 
     
    4648} 
    4749 
     50\preauthor{ 
     51  \begin{center} 
     52    \Large 
     53    \lineskip 0.5em 
     54    \begin{tabular}[t]{c c c} 
     55} 
     56\postauthor{ 
     57    \end{tabular} 
     58    \par 
     59  \end{center} 
     60} 
     61 
    4862\thanksmarkseries{fnsymbol} 
    49  
  • NEMO/trunk/doc/latex/global/indexes.tex

    r11212 r11433  
    88\newcommand{\key}[1]{\index[keys]{#1}        \texttt{\textbf{key\_#1}}} 
    99\newcommand{\mdl}[1]{\index[modules]{#1}     \textit{#1.F90}          } 
    10 \newcommand{\ngn}[1]{\index[blocks]{#1}      \texttt{#1}              } 
     10\newcommand{\nam}[1]{\index[blocks]{#1}      \texttt{nam#1}           } 
    1111\newcommand{\np}[1]{ \index[parameters]{#1}  \texttt{#1}              } 
    1212\newcommand{\rou}[1]{\index[subroutines]{#1} \texttt{#1}              } 
     
    1414\indexsetup{toclevel=section, othercode=\small} 
    1515 
    16 \makeindex[intoc=true, name=keys       , title=CPP keys                      ] 
    17 \makeindex[intoc=true, name=modules    , title=Modules                       ] 
    18 \makeindex[intoc=true, name=blocks     , title=Namelist blocks               ] 
    19 \makeindex[intoc=true, name=parameters , title=Namelist parameters, columns=3] 
    20 \makeindex[intoc=true, name=subroutines, title=Subroutines                   ] 
    21  
    22  
    23 %% Load hyperref at the end of the preamble to make it work with other pkgs 
    24 \usepackage{hyperref}                    %% hyper 
    25 \hypersetup{ 
    26 %  pdftitle={\heading}, 
    27 %  pdfauthor={\firstauthor and \secondauthor}, 
    28   colorlinks, 
    29   citecolor=olive, 
    30   linkcolor=blue, 
    31   urlcolor=gray 
    32 } 
     16\makeindex[intoc=true, name=keys       , title=CPP keys            ({\em key\_     } prefix)           ] 
     17\makeindex[intoc=true, name=modules    , title=\fortran modules                                        ] 
     18\makeindex[intoc=true, name=blocks     , title=Namelist blocks     ({\em nam       } prefix), columns=3] 
     19\makeindex[intoc=true, name=parameters , title=Namelist parameters ({\em [cdlnr]n\_}       ), columns=3] 
     20\makeindex[intoc=true, name=subroutines, title=Subroutines                                             ] 
  • NEMO/trunk/doc/latex/global/info_page.tex

    r11176 r11433  
    88 
    99Like all components of the modelling framework, 
    10 the \engine~core engine is developed under the \href{http://www.cecill.info}{CECILL license}, 
    11 which is a French adaptation of the GNU GPL (General Public License). 
     10the \engine\ core engine is developed under the \href{http://www.cecill.info}{CECILL license}, 
     11which is a French adaptation of the GNU GPL (\textbf{G}eneral \textbf{P}ublic \textbf{L}icense). 
    1212Anyone may use it freely for research purposes, and is encouraged to 
    13 communicate back to the NEMO team its own developments and improvements. 
     13communicate back to the \NEMO\ team its own developments and improvements. 
    1414 
    1515The model and the present document have been made available as a service to the community. 
     
    2727Additional information can be found on: 
    2828\begin{itemize} 
    29 \item the \href{http://www.nemo-ocean.eu}{website} of the project detailing several 
     29\item \faWordpress\ the \href{http://www.nemo-ocean.eu}{website} of the project detailing several 
    3030  associated applications and an exhaustive users bibliography 
    31 \item the \href{http://forge.ipsl.jussieu.fr/nemo}{development platform} of the model with 
    32   the code repository and some main resources (wiki, ticket system, forums, \ldots) 
    33 \item the \href{http://zenodo.org/communities/nemo-ocean}{online archive} 
    34   delivering the publications issued by the consortium 
    35 \item two mailing lists: 
     31\item \faCodeFork\ the \href{http://forge.ipsl.jussieu.fr/nemo}{development platform} of 
     32  the model with the code repository for the shared reference and some main resources 
     33  (wiki, ticket system, forums, \ldots) \\ 
     34  \faGithub\ the \href{http://github.com/NEMO-ocean/NEMO-examples} 
     35  {repository of the demonstration cases} for research or training 
     36\item \faCloudDownload\ the \href{http://zenodo.org/communities/nemo-ocean}{online archive} 
     37  delivering the publications issued by the consortium (manuals, reports, datasets, \ldots) 
     38\item \faEnvelope\ two mailing lists: 
    3639  the \href{http://listes.ipsl.fr/sympa/info/nemo-newsletter}{newsletter} for 
    3740  top-down communications from the project 
     
    4851Reference for papers and other publications is as follows: 
    4952 
    50 \vspace{0.5cm} 
    51  
    52 %% \sloppy: workaround for breaking DOI URL 
    53 \sloppy 
    54 ``{\bfseries \heading}'',  
    55 \firstauthor and \secondauthor,  
    56 {\em Scientific Notes of Climate Modelling Center}, \textbf{\ipslnum} --- ISSN 1288-1619,  
    57 Institut Pierre-Simon Laplace (IPSL),  
     53``{\bfseries \heading}'', 
     54%\firstauthor and \secondauthor, 
     55{\em Scientific Notes of Climate Modelling Center}, \textbf{\ipslnum} --- ISSN 1288-1619, 
     56Institut Pierre-Simon Laplace (IPSL), 
    5857\href{https://doi.org/10.5281/zenodo.\zid}{doi:10.5281/zenodo.\zid} 
    5958 
    6059\begin{figure}[b] 
    61   \begin{minipage}[c]{0.72\textwidth} 
    62     \small\ttfamily{Scientific Notes of Climate Modelling Center \\ 
    63       ISSN 1288-1619                                             \\ 
     60  \begin{minipage}[c]{0.7\textwidth} 
     61    \small 
     62    \ttfamily{ 
     63      Scientific Notes of Climate Modelling Center \\ 
     64      ISSN 1288-1619                               \\ 
    6465      Institut Pierre-Simon Laplace (IPSL) 
    6566    } 
     
    7172\end{figure} 
    7273 
     74\end{document} 
  • NEMO/trunk/doc/latex/global/latexmkrc

    r11212 r11433  
    1010## Custom cmds 
    1111$makeindex = 'makeindex -s %R.ist %O -o %D %S'; 
    12 $pdflatex  = 'pdflatex -shell-escape %O %S'; 
     12#$pdflatex  = 'pdflatex -shell-escape %O %S'; 
     13$pdflatex  = 'xelatex -shell-escape %O %S'; 
    1314 
    1415#@BIBINPUTS=('.', '../main'); 
    1516#$bibtex    = 'bibtex %O ../main/bibliography.bib'; 
    1617#$kpsewhich = 'kpsewhich bibliography.bib' 
    17  
  • NEMO/trunk/doc/latex/global/new_cmds.tex

    r11212 r11433  
    22%% ============================================================================== 
    33 
    4 %% Include references and index for compilation of single subfile  
     4%% Include references and index for compilation of single subfile 
    55\newcommand{\mtoc}{\minitoc} 
    6 \newcommand{\biblio}{\bibliography{../main/bibliography}} 
     6\newcommand{\biblio}{ \bibliography{../main/bibliography} } 
    77\newcommand{\pindex}{\printindex} 
    88 
    99%% NEMO and Fortran in small capitals 
    10 \newcommand{\NEMO}{\textsc{nemo}~} 
    11 \newcommand{\fortran}{\textsc{Fortran}~} 
    12 \newcommand{\fninety}{\textsc{Fortran 90}~} 
     10\newcommand{\NEMO   }{\textsc{nemo}} 
     11\newcommand{\SIcube }{\textsc{si$^3$}} 
     12\newcommand{\TOP    }{\textsc{top}} 
     13\newcommand{\fortran}{\textsc{Fortran}} 
     14\newcommand{\fninety}{\textsc{Fortran 90}} 
    1315 
    1416%% Common aliases 
     
    1820\newcommand{\ztilde}{\ensuremath{\tilde z}} 
    1921\newcommand{\stilde}{\ensuremath{\tilde s}} 
    20 \newcommand{\ie}{\ensuremath{i.e.}~} 
    21 \newcommand{\eg}{\ensuremath{e.g.}~} 
     22\newcommand{\ie}{\ensuremath{i.e.}} 
     23\newcommand{\eg}{\ensuremath{e.g.}} 
    2224 
    2325%% Inline maths 
     
    2527\newcommand{\rdt}{\Delta t} 
    2628 
    27 %% Text env. for Gurvan 
     29%% Gurvan's comments 
    2830\newcommand{\gmcomment}[1]{} 
    2931 
     
    3133\newcommand{\lt}{\left} 
    3234\newcommand{\rt}{\right} 
    33 \newcommand{\vect}[1]{\ensuremath{\mathbf{#1}}} 
     35\newcommand{\vect}[1]{\ensuremath{ \mathbf{#1} }} 
    3436\newcommand{\pd}[2][]{\ensuremath{\frac{\partial #1}{\partial #2}}} 
    3537 
     38%% Convert chapter/section headings to lowercase 
     39\renewcommand{\chaptermark}[1]{\markboth{#1}{}} 
     40\renewcommand{\sectionmark}[1]{\markright{#1}{}} 
     41 
     42%% Retrieve month name 
     43\renewcommand{\today}{ 
     44  \ifcase \month\or January\or February\or March\or 
     45                    April\or   May\or      June\or 
     46                    July\or    August\or   September\or 
     47                    October\or November\or December 
     48  \fi, \number \year 
     49} 
     50 
     51%% Macro for link to orcid profile 
     52\newcommand{\orcid}[1]{ \href{http://orcid.org/#1}{\textcolor{orcidcolor} \aiOrcidSquare} } 
     53 
    3654%% Workaround for issue with \listoffigures 
    37 \DeclareRobustCommand{\triad}[6][]{\ensuremath{{}_{#2}^{#3}{\mathbb{#4}_{#1}}_{#5}^{\,#6}}} 
     55\DeclareRobustCommand{\triad}[6][]{\ensuremath{ {}_{#2}^{#3} { \mathbb{#4}_{#1} }_{#5}^{\,#6} }} 
  • NEMO/trunk/doc/latex/global/packages.tex

    r11189 r11433  
    33%% ============================================================================== 
    44 
    5 \usepackage{natbib}                      %% bib 
    6 \usepackage{caption}                     %% caption 
    7 \usepackage{xcolor}                      %% color 
    8 \usepackage{times}                       %% font 
    9 \usepackage{enumitem}                    %% list 
    10 \usepackage{amsmath}                     %% maths 
    11 %\usepackage{fancyhdr}                    %% page 
    12 \usepackage{minitoc}                     %% toc 
    13 \usepackage{subfiles}                    %% subdocs 
    14 \usepackage{draftwatermark}              %% watermark 
    15 \usepackage{titling}                     %% titlepage 
     5%% 'hyperref' pkg is loaded at the end of the preamble 
     6\usepackage{natbib}                 %% bibtex 
     7\usepackage{caption}                %% caption 
     8\usepackage{xcolor}                 %% colour 
     9\usepackage{times}                  %% font 
     10\usepackage{enumitem}               %% list 
     11\usepackage{amsmath}                %% maths 
     12\usepackage{minitoc}                %% toc 
     13\usepackage{subfiles}               %% subdocs 
     14\usepackage{draftwatermark}         %% watermark 
     15\usepackage[Bjornstrup]{fncychap}   %% headings 
     16\usepackage{fontspec} 
     17%\setmainfont[Ligatures=TeX]{Georgia} 
     18%\setsansfont[Ligatures=TeX]{Arial} 
     19\defaultfontfeatures{ 
     20    Path = /home/ntmlod/.local/texlive2019/texmf-dist/fonts/opentype/public/fontawesome/ 
     21} 
     22\usepackage{academicons}            %% font 
     23\usepackage{fontawesome}            %% font 
     24\usepackage{lastpage}               %% label 
     25\usepackage[pages = some]{background}             %% decoration 
     26\usepackage{geometry}               %% margin 
    1627 
    1728%% Extensions in bundle package 
    1829\usepackage{amssymb, graphicx, tabularx, textcomp} 
    19 \usepackage[utf8]{inputenc}              %% input encoding 
     30%\usepackage[utf8]{inputenc}         %% encoding 
     31\usepackage[footsepline=0.25pt, 
     32headsepline=0.25pt]{scrlayer-scrpage}   %% page layout 
    2033 
    2134%% Configuration 
    2235\graphicspath{ {../../figures/} {../../figures/\engine/} } 
    23 %\captionsetup{margin=10pt, font={small}, labelsep=colon, labelfont={bf}} 
    24 \renewcommand{\bibfont}{\small} 
    25 %\renewcommand{\bibsep}{3pt} 
    26  
     36\geometry{showframe} 
  • NEMO/trunk/doc/latex/global/preamble.tex

    r11187 r11433  
    11 
     2%% Specific configuration 
     3\input{../main/definitions} 
     4 
     5%% Global configuration 
    26\input{../../global/packages} 
    37\input{../../global/highlighting} 
     8\input{../../global/indexes} 
     9\input{../../global/styles} 
     10\backgroundsetup{ 
     11  firstpage = true, 
     12  scale = 1, angle = 0, opacity = 1, 
     13  contents = { 
     14    \begin{tikzpicture}[remember picture, overlay] 
     15      \path [fill = manualcolor] (-0.5\paperwidth, 7) rectangle (0.5\paperwidth, 10); 
     16    \end{tikzpicture} 
     17  } 
     18} 
    419\input{../../global/new_cmds} 
    5 \input{../../global/styles} 
    620%\input{../../global/todonotes} 
    721 
     22%% Load hyperref at the end of the preamble to make it work with other pkgs 
     23\usepackage{hyperref}   %% links 
     24\hypersetup{ 
     25  colorlinks, 
     26  citecolor = manualcolor, linkcolor = manualcolor, urlcolor = manualcolor, 
     27  final   %% Links even with draft building 
     28} 
  • NEMO/trunk/doc/latex/global/styles.tex

    r11212 r11433  
    33%% ============================================================================== 
    44 
    5 %\pagestyle{fancy} 
    6 \bibliographystyle{../../global/ametsoc} 
    7 \renewcommand{\bibpreamble}{\begin{multicols}{2}} 
    8 \renewcommand{\bibpostamble}{\end{multicols}} 
     5\setcolor 
     6%\definecolor{ghcolor}{HTML}{000333} 
     7\definecolor{orcidcolor}{HTML}{A6CE39} 
     8%\definecolor{wpcolor}{HTML}{464646} 
     9 
     10%% Page layout 
     11\pagestyle{scrheadings} 
     12\addtokomafont{pagehead}{  \sffamily              } 
     13\addtokomafont{pagefoot}{  \sffamily \footnotesize} 
     14\addtokomafont{pagenumber}{\sffamily \slshape     } 
     15\ohead{} \ofoot{}   %% Clear defaults 
     16 
     17%% Caption 
     18\captionsetup{font = footnotesize, justification = justified} 
    919 
    1020%% Additional fonts 
    1121\DeclareMathAlphabet{\mathpzc}{OT1}{pzc}{m}{it} 
    1222 
    13 %% Page layout 
    14 %\fancyhf{} 
    15 %\fancyhead[LE,RO]{\bfseries\thepage} 
    16 %\fancyhead[LO]{\bfseries\hspace{-0em}\rightmark} 
    17 %\renewcommand{\sectionmark}[1]{\markright{\thesection.\ #1}} 
    18 %\fancyhead[RE]{\bfseries\leftmark} 
    19 %\renewcommand{\chaptermark}[1]{\markboth{#1}{}} 
    20 %\renewcommand{\headrulewidth}{0.5pt} 
    21 %\renewcommand{\footrulewidth}{0pt  } 
    22 %\addtolength{\headheight}{2.6pt} 
    23  
     23%% Bibliography 
     24\bibliographystyle{../../global/ametsoc} 
     25\renewcommand{\bibfont}{\small} 
     26\renewcommand{\bibpreamble }{\begin{multicols}{2}} 
     27\renewcommand{\bibpostamble}{  \end{multicols}   } 
    2428 
    2529%% Catcodes 
    26 %\makeatletter 
    27 %\def\LigneVerticale{\vrule height 5cm depth 2cm\hspace{0.1cm}\relax} 
    28 %\def\LignesVerticales{\let\LV\LigneVerticale\LV\LV\LV\LV\LV\LV\LV\LV\LV\LV} 
    29 %\def\GrosCarreAvecUnChiffre#1{ 
    30 %  \rlap{\vrule height 0.8cm width 1cm depth 0.2cm} 
    31 %  \rlap{\hbox to 1cm{\hss\mbox{\color{white} #1}\hss}} 
    32 %  \vrule height 0pt width 1cm depth 0pt 
     30\makeatletter 
     31 
     32%% Prevent error with tikz and namelist inclusion 
     33\global\let\tikz@ensure@dollar@catcode=\relax 
     34 
     35%% Apply engine color for chapter boxes (code from fncychap.sty) 
     36%\renewcommand{\DOTI}[1]{ 
     37%  \nointerlineskip\raggedright 
     38%  \fboxsep=\myhi 
     39%  \vskip-1ex 
     40%  \colorbox[manualcolor]{.85}{\parbox[t]{\mylen}{\CTV\FmTi{#1}}}\par\nobreak 
     41%  \vskip 40\p@ 
    3342%} 
    34 %\def\@makechapterhead#1{ 
    35 %  \hbox{ 
    36 %     \huge\LignesVerticales\hspace{-0.5cm} 
    37 %     \GrosCarreAvecUnChiffre{\thechapter}\hspace{0.2cm} 
    38 %     \hbox{#1} 
    39 %  } 
    40 %  \par\vskip 
    41 %1cm 
    42 %} 
    43 %\def\@makeschapterhead#1{ 
    44 %  \hbox{ 
    45 %     \huge\LignesVerticales 
    46 %     \hbox{#1} 
    47 %  } 
    48 %  \par\vskip 
    49 %2cm 
    50 %} 
    51 %\def\cleardoublepage{\clearpage\if@twoside \ifodd\c@page\else 
    52 %  \hbox{} 
    53 %  \vspace*{\fill} 
    54 %  \vspace{\fill} 
    55 %  \thispagestyle{empty} 
    56 %  \newpage 
    57 %  \if@twocolumn\hbox{}\newpage\fi\fi\fi} 
    58 %\def\@seccntformat#1{\protect\makebox[0pt][r]{\csname the#1\endcsname\quad}} 
    59 %\makeatother 
    6043 
    61  
     44\makeatother 
Note: See TracChangeset for help on using the changeset viewer.