LaTeX doc: change layout.

doc/manual/mtime.tex

-\documentclass[BCOR1cm,DIV20,a4paper,mpinclude,headsepline,footsepline]{scrartcl}
+\documentclass[DIV20,a4paper,mpinclude]{scrartcl}
 
 \usepackage[utf8]{inputenc}
 \usepackage[T1]{fontenc}
-
 \usepackage{textcomp}
 \usepackage{gensymb}
-
 \usepackage{lmodern}
-
 \usepackage{xcolor}
+\usepackage{authblk}
+\usepackage{graphicx}
+\usepackage{natbib}
+\usepackage{hyperref}
+\usepackage{enumitem}
+\usepackage{listings}
+\usepackage{xspace}
+\usepackage{lipsum}
+\usepackage{multicol}
+\usepackage[plainheadsepline,plainfootsepline]{scrlayer-scrpage}
+
+\usepackage[
+  tmargin=25mm,bmargin=28.5mm,
+  lmargin=25mm,rmargin=20mm,
+  headheight=36pt% <- entsprechend Warnung von scrlayer-scrpage
+]{geometry}
+
 
+% --------------------------------------------------------------------------------
+% COLORS
+%
 \definecolor{mpggreen}{RGB}{0,119,112}
 \definecolor{mpggrey}{RGB}{209,206,198}
 \definecolor{darkred}{RGB}{184,50,50}
 
-\usepackage{scrpage2}
+\colorlet{UrlColor}{blue}                                % Link colors
+\colorlet{LinkColor}{blue}
+\colorlet{CiteColor}{blue}
+\colorlet{FileColor}{blue}
+% --------------------------------------------------------------------------------
 
-\usepackage{authblk}
 
-\usepackage{graphicx}
+% --------------------------------------------------------------------------------
+% PDF SETUP
+%
+\ifpdf
+\usepackage{hyperref}
+\hypersetup{%
+  pdftitle={The mtime Calendar Library -- Fortran Interface},
+  pdfauthor={L.\ Kornblueh, J.\ F.\ Engels, F.\ Prill},
+  pdfkeywords={ICON, mtime, manual},
+  colorlinks=true,linkcolor=LinkColor,urlcolor=UrlColor %
+                 ,citecolor=CiteColor,menucolor=MenuColor %
+                 ,filecolor=FileColor
+}
+\fi
+% --------------------------------------------------------------------------------
 
-\usepackage{natbib}
 
-\bibliographystyle{copernicus}
+% --------------------------------------------------------------------------------
+% COMMON FORMATTINGS AND MACROS
+%
+\newcommand{\mtime}{\texttt{mtime}\xspace}
+\newcommand{\libmtime}{\texttt{libmtime}\xspace}
+% --------------------------------------------------------------------------------
 
-\usepackage{hyperref}
 
-\usepackage{enumitem}
 
+\bibliographystyle{copernicus}
 \setlist[itemize]{parsep=0pt}
 \setlist[enumerate]{parsep=0pt}
 
-\usepackage{listings}
-
 \lstnewenvironment{fortran}{
   \lstset{
     backgroundcolor=\color{gray!10},
@@ -53,56 +88,110 @@
 \setlength{\parskip}{1.5em}
 \setlength{\parindent}{0pt}
 
-%\addtolength{\marginparsep}{10pt}
-%\addtolength{\marginparwidth}{0.5\marginparwidth}
 
+% --------------------------------------------------------------------------------
+% FONTS
 \addtokomafont{sectioning}{\color{mpggreen}}
 \setkomafont{pageheadfoot}{\sffamily\normalsize}
 \addtokomafont{pageheadfoot}{\color{mpggreen}}
 \addtokomafont{pagenumber}{\color{mpggreen}}
 \addtokomafont{headsepline}{\color{mpggreen}}
 \addtokomafont{footsepline}{\color{mpggreen}}
-
 \renewcommand\Authfont{\sffamily\normalsize}
 \renewcommand\Affilfont{\sffamily\itshape\small}
+% --------------------------------------------------------------------------------
+
 
-%article: \automark[subsection]{section}
+% --------------------------------------------------------------------------------
+% HEADERS AND FOOTERS:
 \automark[subsection]{section}
-%report:  \automark[section]{chapter}
 \pagestyle{scrheadings}
 \clearscrheadings
 \ohead{\headmark}
 \ofoot{\pagemark}
+% --------------------------------------------------------------------------------
 
-\titlehead{
-  \rule{\textwidth}{1pt}
-  \textsf{Max-Planck-Institut für Meteorologie \hfill Compte rendu CIMD No. 12}
-}
-\title{ICON time control using libmtime 1.0.0}
-\subtitle{Introduction and Getting Started}
-\author{Luis Kornblueh}
-\affil{Max-Planck-Institut für Meteorologie}
-
-\date{
-  \textsf{\today}
-  \rule{\textwidth}{1pt}
-}
+
+% --------------------------------------------------------------------------------
+% TITLE PAGE
+\titlehead{\rule{\textwidth}{1pt}}
+\title{The \mtime Calendar Library -- Fortran Interface}
+\author{L.\ Kornblueh, J.\ F.\ Engels, F.\ Prill}
+\affil{Max Planck Institute for Meteorology / Deutscher Wetterdienst / German Climate Computing Center}
+\date{%
+  \textsf{2019-08-01} % version date: does not make sense to have \today macro here...
+  \rule{\textwidth}{1pt}}
+% --------------------------------------------------------------------------------
 
 \begin{document}
 
-\color{mpggreen}
-\maketitle
-\color{black}
+{
 
-\tableofcontents
+  \thispagestyle{plain}
+  \color{mpggreen}
+  \maketitle
+  \color{black}
+}
 
-\section{Introduction}
 
-libmtime is a model time management library (mtime - model time).
+% --------------------------------------------------------------------------------
+\section{What is \mtime?}
+% --------------------------------------------------------------------------------
+
+\libmtime is a model time management library (\mtime - model time).
 This library provides calendar, time, and event handling for model
 applications.
 
-libmtime provides the following well documented data structures and
+% Requirements
+
+
+
+% --------------------------------------------------------------------------------
+\section{A brief look}
+% --------------------------------------------------------------------------------
+
+
+
+% ================================================================================
+\newpage
+\part*{The \mtime Cheat Sheet}
+\addcontentsline{toc}{section}{The \mtime Cheat Sheet}
+% ================================================================================
+
+\begin{multicols}{2}
+  
+  \lipsum
+  
+\end{multicols}
+
+
+
+
+
+
+% ================================================================================
+\newpage
+\part*{Detailed Introduction to \mtime}
+% ================================================================================
+
+
+\tableofcontents
+
+\newpage
+\KOMAoptions{headsepline=true, footsepline=true}%
+
+
+% --------------------------------------------------------------------------------
+\section{History}
+% --------------------------------------------------------------------------------
+
+
+
+% --------------------------------------------------------------------------------
+\section{Introduction}
+% --------------------------------------------------------------------------------
+
+\libmtime provides the following well documented data structures and
 functions for common use:
 
 \begin{itemize}
@@ -120,18 +209,18 @@ functions for common use:
 \item \textbf{eventgroup} A container allowing grouping events.   
 \end{itemize}
 
-The libmtime manual (not this document!) provides detailed
+The \libmtime manual (not this document!) provides detailed
 descriptions of all data structures and provided functions. The latest
-version can be found in the libmtime source code directory or in the
+version can be found in the \libmtime source code directory or in the
 wiki of the ICON project at
 
 \url{https://code.zmaw.de/attachments/download/13449/libmtime.pdf}
 
-To provide the possibility to add different language bindings to mtime
+To provide the possibility to add different language bindings to \mtime
 the basic implementation of the library is done in C. To be able to
 provide interfaces for interpreted languages like Python an object
 oriented design is required. Therefore, in libmtime-1.0.0 instances of
-the different mtime objects need to be allocated and freed by the
+the different \mtime objects need to be allocated and freed by the
 user. This will change in the Fortran interface of libmtime-2.0.0 to
 simplify usage.
 
@@ -139,21 +228,30 @@ Currently, three language bindings are provided as are C, Fortran, and
 Python.
 
 This introduction and getting started focus on the Fortran language
-binding and the use of mtime in ICON. However, it does not provide
+binding and the use of \mtime in ICON. However, it does not provide
 complete coverage of the available functions. A detailed description of
 all functions can be found in the libmtime-1.0.0 manual.
 
+
+
+% --------------------------------------------------------------------------------
+\section{String representation of date and time spans}
+% --------------------------------------------------------------------------------
+
 \textbf{Note:} To allow adaptation of old scripts and the operational
 set-up of DWD the old namelist interface is supported (mapped) to a
-large extent to the mtime based model variables for some time. The
-new, mtime aware, namelist interface described later requires to use
+large extent to the \mtime based model variables for some time. The
+new, \mtime aware, namelist interface described later requires to use
 ISO 8601-2004 conforming strings. The standard can be downloaded from
 
 \url{https://code.zmaw.de/attachments/download/1458/ISO_8601-2004_E.pdf}
 
+
+% --------------------------------------------------------------------------------
 \section{Definition of calendars}
+% --------------------------------------------------------------------------------
 
-The first thing to do for using a calendar based tool like libmtime is
+The first thing to do for using a calendar based tool like \libmtime is
 to define the calendar for all further date and time calculations. As
 this is an operation which has to be done once only to assure
 consistent behavior through an experiment, this is, therefore, allowed
@@ -173,7 +271,7 @@ The calendar can be selected by variable \texttt{calendar} in
 \end{itemize}
 
 After this initialization step (very early in ICON) it is possible to
-use mtime objects. This initialization takes care that the basic
+use \mtime objects. This initialization takes care that the basic
 algorithms for calculation time differences and the conversion from
 ISO 8601-2400 defined date and time and time difference strings are
 getting used.
@@ -181,11 +279,17 @@ getting used.
 \textbf{Note:} This is already done in the master configuration of
 ICON and there should be no need to change this! 
 
-\section{Create mtime time objects}
 
-\subsection{Available mtime objects}
+% --------------------------------------------------------------------------------
+\section{Create \mtime time objects}
+% --------------------------------------------------------------------------------
+
+
+% --------------------------------------------------------------------------------
+\subsection{Available \mtime objects}
+% --------------------------------------------------------------------------------
 
-To be able to use mtime objects one needs to add the interface definitions by adding
+To be able to use \mtime objects one needs to add the interface definitions by adding
 
 \begin{fortran}
   USE mtime, ONLY: <used mtime entities>
@@ -203,11 +307,17 @@ There are two basic types available:
 
 Both types can cover time spans from ms to billion of years.
 
-\subsection{mtime object constructors and destructors}
+
+% --------------------------------------------------------------------------------
+\subsection{\mtime object constructors and destructors}
+% --------------------------------------------------------------------------------
 
 The current interface requires to define pointer of the available data types.
 
+
+% --------------------------------------------------------------------------------
 \subsection{\label{sec:datetime}date and time}
+% --------------------------------------------------------------------------------
 
 The definition in your code looks like
 
@@ -217,7 +327,7 @@ The definition in your code looks like
 
 In a second step one can setup the variable by calling a constructor
 with an initializer (for the different options have a look in the
-libmtime manual).
+\libmtime manual).
 
 \begin{fortran}
   my_date_and_time => newDatetime(<initializer>)
@@ -256,7 +366,10 @@ out of scope
   CALL deallocateDatetime(my_date_and_time)
 \end{fortran}
 
+
+% --------------------------------------------------------------------------------
 \subsection{time delta}
+% --------------------------------------------------------------------------------
 
 Handling the timedelta object follows the datetime usage style
 
@@ -304,12 +417,15 @@ the ISO 8601-2004, which is available at
 Using this basic data structures we can build the models main time
 loop.
 
-\section{Writing mtime date and time objects}
 
-Writing and printing mtime date and time objects can be done in two
-ways. for an initialized mtime object one can use the corresponding
+% --------------------------------------------------------------------------------
+\section{Writing \mtime date and time objects}
+% --------------------------------------------------------------------------------
+
+Writing and printing \mtime date and time objects can be done in two
+ways. for an initialized \mtime object one can use the corresponding
 ToString subroutine. One hast to define a sufficiently large string
---- a recommend maximum string length can be found in the mtime
+--- a recommend maximum string length can be found in the \mtime
 module. The returned string can be written out as every other string.
 
 \begin{fortran}
@@ -343,13 +459,19 @@ message function to write out.
   CALL print_mtime('<a source>','<a message>', my_date_and_time)
 \end{fortran}
 
+
+% --------------------------------------------------------------------------------
 \section{Building a time loop}
+% --------------------------------------------------------------------------------
 
-Based on the available mtime variables we can build a time
+Based on the available \mtime variables we can build a time
 loop. Before, we define a couple of terms, which are required to gain
 a proper understanding on how the time loop works.
 
+
+% --------------------------------------------------------------------------------
 \subsection{ICON specific variables}
+% --------------------------------------------------------------------------------
 
 Before we start building the time loop one needs to understand, how
 the time handling is build up. The following picture is giving the
@@ -441,7 +563,10 @@ dates:
 Having available now all building blocks we continue with the main time
 loop.
 
+
+% --------------------------------------------------------------------------------
 \subsection{The main loop}
+% --------------------------------------------------------------------------------
 
 As for longer time periods like month and years no consistent step
 based setup can be used due to the different length in steps of this
@@ -485,7 +610,10 @@ much more complicated due to the sub-stepping of the dynamical core,
 the sub-stepping of the optional nests, and the different time steps
 for different physics components.
 
+
+% --------------------------------------------------------------------------------
 \section{Events}
+% --------------------------------------------------------------------------------
 
 To be able to trigger events in the stateless time loop, one needs to
 be able to define recurring events, which can check, if an event has to
@@ -497,7 +625,10 @@ the event manager and event groups is the possibility to have a single
 point to access all events defined in the model for debugging and
 disentangling events in different model components.
 
+
+% --------------------------------------------------------------------------------
 \subsection{The event manager - an ICON module}
+% --------------------------------------------------------------------------------
 
 The event manager can be accessed/used by adding
 
@@ -524,14 +655,17 @@ and, finally, a routine to print an event group
 
 \texttt{src/atm\_dyn\_iconam/mo\_nh\_stepping.f90}
 
-close to the start of the time loop (this is not part of mtime).
+close to the start of the time loop (this is not part of \mtime).
+
 
+% --------------------------------------------------------------------------------
 \subsection{Event groups}
+% --------------------------------------------------------------------------------
 
 As an example we add an event to an event group, which is attached to
 the event manager.
 
-Following the appropriate definitions of the mtime and event manager
+Following the appropriate definitions of the \mtime and event manager
 module use we can define an event group:
 
 \begin{fortran}
@@ -563,7 +697,10 @@ used to access the specific group. In this example a group is defined,
 which does group together the checkpoint and restart events, we are
 going to define and add in the following.
 
+
+% --------------------------------------------------------------------------------
 \subsection{Events}
+% --------------------------------------------------------------------------------
 
 To define single events one needs to define some parameters first:
 
@@ -635,7 +772,10 @@ is adding the event to the previously created checkpoint event group
 
 Now we can use this event inside of the time loop.
 
+
+% --------------------------------------------------------------------------------
 \subsection{Querying events}
+% --------------------------------------------------------------------------------
 
 Inside of the time loop we can now ask, if the event should be triggered at the current date
 
@@ -650,7 +790,7 @@ Inside of the time loop we can now ask, if the event should be triggered at the
 \end{fortran}
 
 There are many more queries for events for the specific description
-consult the libmtime manual. A short list is provided here for convenience
+consult the \libmtime manual. A short list is provided here for convenience
 
 \begin{itemize}
 \item \texttt{isCurrentEventActive} --- is this event true now (trigger)
@@ -673,9 +813,3 @@ years).
 
 \end{document}
 
-
-
-
-
-
-