Changeset 11577 for NEMO/trunk/doc/latex/NEMO/subfiles/apdx_DOMAINcfg.tex

Timestamp:

2019-09-19T19:01:38+02:00 (5 years ago)

Author:

nicolasmartin

Message:

New LaTeX commands \nam and \np to mention namelist content
(Partial commit to serve as a backup before other large edits)
In order to benefit of the syntax highlighting and to have a simpler syntax for
citing namelist block (\nam) and parameter (\np) with an optional variable assignment (\forcode{...}),
at this time the only viable solution I found is to require a double marker for
what it looks like the same item:

1. Marker with the real name: 'tra_adv' block or 'ln_flx' parameter
2. Marker with underscore character escaping: 'tra\_adv' block or 'ln\_flx' parameter

Despite many searches and attempts, I did not find a workaround to edit on-the-fly one or
the other marker.
In fact, the problem is on one side that the LaTeX index interprets '_' as a switch for lowering like
in math mode while on the other hand the backslash is considered for Pygments as a typo in Fortran
(red box).

For instance, \nam and \np have as of now the aforementioned 2 mandatory arguments in
the previous order (between braces) + an optional argument for \np when the parameter is defined
(between brackets at the first position):

• \nam: LaTeX code in the \nam{tra_adv}{tra\_adv} -> PDF ' in the &namtra_adv (namelist X.X) ' with syntax highlighting, the hyperlink and the index entry
• \np: LaTeX code \np[=.true.]{ln_flx}{ln\_flx} -> PDF ln_flux=.true. with syntax highlighting for the whole string and the entry in the 'parameters' index

File:

• NEMO/trunk/doc/latex/NEMO/subfiles/apdx_DOMAINcfg.tex (modified) (20 diffs)

NEMO/trunk/doc/latex/NEMO/subfiles/apdx_DOMAINcfg.tex

@@ -51 +51 @@
 
 The user has three options available in defining a horizontal grid, which involve the
-namelist variable \np{jphgr\_mesh} of the \nam{dom} (\texttt{DOMAINcfg} variant only)
+namelist variable \np{jphgr_mesh}{jphgr\_mesh} of the \nam{dom} (\texttt{DOMAINcfg} variant only)
 namelist.
 
 \begin{description}
- \item[\np{jphgr\_mesh}=0]  The most general curvilinear orthogonal grids.
+ \item[\np{jphgr_mesh}{jphgr\_mesh}=0]  The most general curvilinear orthogonal grids.
   The coordinates and their first derivatives with respect to $i$ and $j$ are provided
   in a input file (\ifile{coordinates}), read in \rou{hgr\_read} subroutine of the domhgr module.
   This is now the only option available within \NEMO\ itself from v4.0 onwards.
-\item[\np{jphgr\_mesh}=1 to 5] A few simple analytical grids are provided (see below).
+\item[\np{jphgr_mesh}{jphgr\_mesh}=1 to 5] A few simple analytical grids are provided (see below).
   For other analytical grids, the \mdl{domhgr} module (\texttt{DOMAINcfg} variant) must be
   modified by the user. In most cases, modifying the \mdl{usrdef\_hgr} module of \NEMO\ is
@@ -67 +67 @@
 
 There are two simple cases of geographical grids on the sphere. With
-\np{jphgr\_mesh}=1, the grid (expressed in degrees) is regular in space,
-with grid sizes specified by parameters \np{ppe1\_deg} and \np{ppe2\_deg},
+\np{jphgr_mesh}{jphgr\_mesh}=1, the grid (expressed in degrees) is regular in space,
+with grid sizes specified by parameters \np{ppe1_deg}{ppe1\_deg} and \np{ppe2_deg}{ppe2\_deg},
 respectively. Such a geographical grid can be very anisotropic at high latitudes
 because of the convergence of meridians (the zonal scale factors $e_1$
 become much smaller than the meridional scale factors $e_2$). The Mercator
-grid (\np{jphgr\_mesh}=4) avoids this anisotropy by refining the meridional scale
+grid (\np{jphgr_mesh}{jphgr\_mesh}=4) avoids this anisotropy by refining the meridional scale
 factors in the same way as the zonal ones. In this case, meridional scale factors
 and latitudes are calculated analytically using the formulae appropriate for
-a Mercator projection, based on \np{ppe1\_deg} which is a reference grid spacing
+a Mercator projection, based on \np{ppe1_deg}{ppe1\_deg} which is a reference grid spacing
 at the equator (this applies even when the geographical equator is situated outside
 the model domain).
 
-In these two cases (\np{jphgr\_mesh}=1 or 4), the grid position is defined by the
+In these two cases (\np{jphgr_mesh}{jphgr\_mesh}=1 or 4), the grid position is defined by the
 longitude and latitude of the south-westernmost point (\np{ppglamt0}
 and \np{ppgphi0}). Note that for the Mercator grid the user need only provide
@@ -87 +87 @@
 
 Rectangular grids ignoring the spherical geometry are defined with
-\np{jphgr\_mesh} = 2, 3, 5. The domain is either an $f$-plane (\np{jphgr\_mesh} = 2,
-Coriolis factor is constant) or a beta-plane (\np{jphgr\_mesh} = 3, the Coriolis factor
+\np{jphgr_mesh}{jphgr\_mesh} = 2, 3, 5. The domain is either an $f$-plane (\np{jphgr\_mesh} = 2,
+Coriolis factor is constant) or a beta-plane (\np{jphgr_mesh}{jphgr\_mesh} = 3, the Coriolis factor
 is linear in the $j$-direction). The grid size is uniform in meter in each direction,
-and given by the parameters \np{ppe1\_m} and \np{ppe2\_m} respectively.
+and given by the parameters \np{ppe1_m}{ppe1\_m} and \np{ppe2_m}{ppe2\_m} respectively.
 The zonal grid coordinate (\textit{glam} arrays) is in kilometers, starting at zero
 with the first $t$-point. The meridional coordinate (gphi. arrays) is in kilometers,
@@ -97 +97 @@
 latitude for computation of the Coriolis parameter. In the case of the beta plane,
 \np{ppgphi0} corresponds to the center of the domain. Finally, the special case
-\np{jphgr\_mesh}=5 corresponds to a beta plane in a rotated domain for the
+\np{jphgr_mesh}{jphgr\_mesh}=5 corresponds to a beta plane in a rotated domain for the
 GYRE configuration, representing a classical mid-latitude double gyre system.
 The rotation allows us to maximize the jet length relative to the gyre areas
@@ -170 +170 @@
 \end{gather}
 
-If the ice shelf cavities are opened (\np{ln\_isfcav}\forcode{ = .true.}), the definition
+If the ice shelf cavities are opened (\np{ln_isfcav}{ln\_isfcav}\forcode{ = .true.}), the definition
 of $z_0$ is the same.  However, definition of $e_3^0$ at $t$- and $w$-points is
 respectively changed to:
@@ -312 +312 @@
 
 Three options are possible for defining the bathymetry, according to the namelist variable
-\np{nn\_bathy} (found in \nam{dom} namelist (\texttt{DOMAINCFG} variant) ):
+\np{nn_bathy}{nn\_bathy} (found in \nam{dom} namelist (\texttt{DOMAINCFG} variant) ):
 \begin{description}
-\item[\np{nn\_bathy}\forcode{ = 0}]:
+\item[\np{nn_bathy}{nn\_bathy}\forcode{ = 0}]:
   a flat-bottom domain is defined.
   The total depth $z_w (jpk)$ is given by the coordinate transformation.
   The domain can either be a closed basin or a periodic channel depending on the parameter \np{jperio}.
-\item[\np{nn\_bathy}\forcode{ = -1}]:
+\item[\np{nn_bathy}{nn\_bathy}\forcode{ = -1}]:
   a domain with a bump of topography one third of the domain width at the central latitude.
   This is meant for the "EEL-R5" configuration, a periodic or open boundary channel with a seamount.
-\item[\np{nn\_bathy}\forcode{ = 1}]:
+\item[\np{nn_bathy}{nn\_bathy}\forcode{ = 1}]:
   read a bathymetry and ice shelf draft (if needed).
   The \ifile{bathy\_meter} file (Netcdf format) provides the ocean depth (positive, in meters) at
@@ -332 +332 @@
   The \ifile{isfdraft\_meter} file (Netcdf format) provides the ice shelf draft (positive, in meters) at
   each grid point of the model grid.
-  This file is only needed if \np{ln\_isfcav}\forcode{ = .true.}.
+  This file is only needed if \np{ln_isfcav}{ln\_isfcav}\forcode{ = .true.}.
   Defining the ice shelf draft will also define the ice shelf edge and the grounding line position.
 \end{description}
@@ -359 +359 @@
 %        z-coordinate with constant thickness
 % -------------------------------------------------------------------------------------------------------------
-\subsubsection[$Z$-coordinate with uniform thickness levels (\forcode{ln_zco})]{$Z$-coordinate with uniform thickness levels (\protect\np{ln\_zco})}
+\subsubsection[$Z$-coordinate with uniform thickness levels (\forcode{ln_zco})]{$Z$-coordinate with uniform thickness levels (\protect\np{ln_zco}{ln\_zco})}
 \label{subsec:DOMCFG_zco}
 
@@ -371 +371 @@
 %        z-coordinate with partial step
 % -------------------------------------------------------------------------------------------------------------
-\subsubsection[$Z$-coordinate with partial step (\forcode{ln_zps})]{$Z$-coordinate with partial step (\protect\np{ln\_zps})}
+\subsubsection[$Z$-coordinate with partial step (\forcode{ln_zps})]{$Z$-coordinate with partial step (\protect\np{ln_zps}{ln\_zps})}
 \label{subsec:DOMCFG_zps}
 
@@ -394 +394 @@
 $250~m$).  Two variables in the namdom namelist are used to define the partial step
 vertical grid.  The mimimum water thickness (in meters) allowed for a cell partially
-filled with bathymetry at level jk is the minimum of \np{rn\_e3zps\_min} (thickness in
-meters, usually $20~m$) or $e_{3t}(jk)*$\np{rn\_e3zps\_rat} (a fraction, usually 10\%, of
+filled with bathymetry at level jk is the minimum of \np{rn_e3zps_min}{rn\_e3zps\_min} (thickness in
+meters, usually $20~m$) or $e_{3t}(jk)*$\np{rn_e3zps_rat}{rn\_e3zps\_rat} (a fraction, usually 10\%, of
 the default thickness $e_{3t}(jk)$).
 
@@ -401 +401 @@
 %        s-coordinate
 % -------------------------------------------------------------------------------------------------------------
-\subsubsection[$S$-coordinate (\forcode{ln_sco})]{$S$-coordinate (\protect\np{ln\_sco})}
+\subsubsection[$S$-coordinate (\forcode{ln_sco})]{$S$-coordinate (\protect\np{ln_sco}{ln\_sco})}
 \label{sec:DOMCFG_sco}
 %------------------------------------------nam_zgr_sco---------------------------------------------------
@@ -411 +411 @@
 \end{listing}
 %--------------------------------------------------------------------------------------------------------------
-Options are defined in \nam{zgr\_sco} (\texttt{DOMAINcfg} only).
-In $s$-coordinate (\np{ln\_sco}\forcode{ = .true.}), the depth and thickness of the model levels are defined from
+Options are defined in \nam{zgr_sco}{zgr\_sco} (\texttt{DOMAINcfg} only).
+In $s$-coordinate (\np{ln_sco}{ln\_sco}\forcode{ = .true.}), the depth and thickness of the model levels are defined from
 the product of a depth field and either a stretching function or its derivative, respectively:
 
@@ -426 +426 @@
 since a mixed step-like and bottom-following representation of the topography can be used
 (\autoref{fig:DOM_z_zps_s_sps}) or an envelop bathymetry can be defined (\autoref{fig:DOM_z_zps_s_sps}).
-The namelist parameter \np{rn\_rmax} determines the slope at which
+The namelist parameter \np{rn_rmax}{rn\_rmax} determines the slope at which
 the terrain-following coordinate intersects the sea bed and becomes a pseudo z-coordinate.
-The coordinate can also be hybridised by specifying \np{rn\_sbot\_min} and \np{rn\_sbot\_max} as
+The coordinate can also be hybridised by specifying \np{rn_sbot_min}{rn\_sbot\_min} and \np{rn_sbot_max}{rn\_sbot\_max} as
 the minimum and maximum depths at which the terrain-following vertical coordinate is calculated.
 
@@ -435 +435 @@
 
 The original default \NEMO\ s-coordinate stretching is available if neither of the other options are specified as true
-(\np{ln\_s\_SH94}\forcode{ = .false.} and \np{ln\_s\_SF12}\forcode{ = .false.}).
+(\np{ln_s_SH94}{ln\_s\_SH94}\forcode{ = .false.} and \np{ln_s_SF12}{ln\_s\_SF12}\forcode{ = .false.}).
 This uses a depth independent $\tanh$ function for the stretching \citep{madec.delecluse.ea_JPO96}:
 
@@ -455 +455 @@
 
 A stretching function,
-modified from the commonly used \citet{song.haidvogel_JCP94} stretching (\np{ln\_s\_SH94}\forcode{ = .true.}),
+modified from the commonly used \citet{song.haidvogel_JCP94} stretching (\np{ln_s_SH94}{ln\_s\_SH94}\forcode{ = .true.}),
 is also available and is more commonly used for shelf seas modelling:
 
@@ -476 +476 @@
 %% %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 
-where $H_c$ is the critical depth (\np{rn\_hc}) at which the coordinate transitions from pure $\sigma$ to
-the stretched coordinate, and $\theta$ (\np{rn\_theta}) and $b$ (\np{rn\_bb}) are the surface and
+where $H_c$ is the critical depth (\np{rn_hc}{rn\_hc}) at which the coordinate transitions from pure $\sigma$ to
+the stretched coordinate, and $\theta$ (\np{rn_theta}{rn\_theta}) and $b$ (\np{rn_bb}{rn\_bb}) are the surface and
 bottom control parameters such that $0 \leqslant \theta \leqslant 20$, and $0 \leqslant b \leqslant 1$.
 $b$ has been designed to allow surface and/or bottom increase of the vertical resolution
 (\autoref{fig:DOMCFG_sco_function}).
 
-Another example has been provided at version 3.5 (\np{ln\_s\_SF12}) that allows a fixed surface resolution in
+Another example has been provided at version 3.5 (\np{ln_s_SF12}{ln\_s\_SF12}) that allows a fixed surface resolution in
 an analytical terrain-following stretching \citet{siddorn.furner_OM13}.
 In this case the a stretching function $\gamma$ is defined such that:
@@ -504 +504 @@
 
 This gives an analytical stretching of $\sigma$ that is solvable in $A$ and $B$ as a function of
-the user prescribed stretching parameter $\alpha$ (\np{rn\_alpha}) that stretches towards
+the user prescribed stretching parameter $\alpha$ (\np{rn_alpha}{rn\_alpha}) that stretches towards
 the surface ($\alpha > 1.0$) or the bottom ($\alpha < 1.0$) and
-user prescribed surface (\np{rn\_zs}) and bottom depths.
+user prescribed surface (\np{rn_zs}{rn\_zs}) and bottom depths.
 The bottom cell depth in this example is given as a function of water depth:
 
@@ -514 +514 @@
 \]
 
-where the namelist parameters \np{rn\_zb\_a} and \np{rn\_zb\_b} are $a$ and $b$ respectively.
+where the namelist parameters \np{rn_zb_a}{rn\_zb\_a} and \np{rn_zb_b}{rn\_zb\_b} are $a$ and $b$ respectively.
 
 %% %>>>>>>>>>>>>>>>>>>>>>>>>>>>>
@@ -542 +542 @@
 the critical depth $h_c$.
 In this example two options are available in depths shallower than $h_c$,
-with pure sigma being applied if the \np{ln\_sigcrit} is true and pure z-coordinates if it is false
+with pure sigma being applied if the \np{ln_sigcrit}{ln\_sigcrit} is true and pure z-coordinates if it is false
 (the z-coordinate being equal to the depths of the stretched coordinate at $h_c$).
 
@@ -553 +553 @@
 %        z*- or s*-coordinate
 % -------------------------------------------------------------------------------------------------------------
-\subsubsection[\zstar- or \sstar-coordinate (\forcode{ln_linssh})]{\zstar- or \sstar-coordinate (\protect\np{ln\_linssh})}
+\subsubsection[\zstar- or \sstar-coordinate (\forcode{ln_linssh})]{\zstar- or \sstar-coordinate (\protect\np{ln_linssh}{ln\_linssh})}
 \label{subsec:DOMCFG_zgr_star}