Changeset 11577 for NEMO/trunk/doc/latex/NEMO/subfiles/chap_DOM.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/chap_DOM.tex (modified) (12 diffs)

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

@@ -335 +335 @@
 
 Two typical methods are available to specify the spatial domain configuration;
-they can be selected using parameter \np{ln\_read\_cfg} parameter in namelist \nam{cfg}.
-
-If \np{ln\_read\_cfg} is set to \forcode{.true.},
+they can be selected using parameter \np{ln_read_cfg}{ln\_read\_cfg} parameter in namelist \nam{cfg}.
+
+If \np{ln_read_cfg}{ln\_read\_cfg} is set to \forcode{.true.},
 the domain-specific parameters and fields are read from a netCDF input file,
-whose name (without its .nc suffix) can be specified as the value of the \np{cn\_domcfg} parameter in namelist \nam{cfg}.
-
-If \np{ln\_read\_cfg} is set to \forcode{.false.},
+whose name (without its .nc suffix) can be specified as the value of the \np{cn_domcfg}{cn\_domcfg} parameter in namelist \nam{cfg}.
+
+If \np{ln_read_cfg}{ln\_read\_cfg} is set to \forcode{.false.},
 the domain-specific parameters and fields can be provided (\eg\ analytically computed) by
 subroutines \mdl{usrdef\_hgr} and \mdl{usrdef\_zgr}.
@@ -359 +359 @@
 
 The next subsections summarise the parameter and fields related to the configuration of the whole model domain.
-These represent the minimum information that must be provided either via the \np{cn\_domcfg} file or set by code
+These represent the minimum information that must be provided either via the \np{cn_domcfg}{cn\_domcfg} file or set by code
 inserted into user-supplied versions of the \texttt{usrdef\_*} subroutines.
 The requirements are presented in three sections:
@@ -377 +377 @@
 see \autoref{sec:LBC_mpp}).
 
-The name of the configuration is set through parameter \np{cn\_cfg},
-and the nominal resolution through parameter \np{nn\_cfg}
+The name of the configuration is set through parameter \np{cn_cfg}{cn\_cfg},
+and the nominal resolution through parameter \np{nn_cfg}{nn\_cfg}
 (unless in the input file both of variables \texttt{ORCA} and \texttt{ORCA\_index} are present,
-in which case \np{cn\_cfg} and \np{nn\_cfg} are set from these values accordingly).
+in which case \np{cn_cfg}{cn\_cfg} and \np{nn_cfg}{nn\_cfg} are set from these values accordingly).
 
 The global lateral boundary condition type is selected from 8 options using parameter \jp{jperio}.
@@ -436 +436 @@
 the unaltered surface areas at $u$ and $v$ grid points (\texttt{e1e2u} and \texttt{e1e2v}, respectively) must be read or
 pre-computed in \mdl{usrdef\_hgr}.
-If these arrays are present in the \np{cn\_domcfg} file they are read and the internal computation is suppressed.
+If these arrays are present in the \np{cn_domcfg}{cn\_domcfg} file they are read and the internal computation is suppressed.
 Versions of \mdl{usrdef\_hgr} which set their own values of \texttt{e1e2u} and \texttt{e1e2v} should set
 the surface-area computation flag:
@@ -487 +487 @@
     (d) hybrid $s-z$ coordinate,
     (e) hybrid $s-z$ coordinate with partial step, and
-    (f) same as (e) but in the non-linear free surface (\protect\np{ln\_linssh}\forcode{=.false.}).
+    (f) same as (e) but in the non-linear free surface (\protect\np{ln_linssh}{ln\_linssh}\forcode{=.false.}).
     Note that the non-linear free surface can be used with any of the 5 coordinates (a) to (e).}
   \label{fig:DOM_z_zps_s_sps}
@@ -502 +502 @@
 a single configuration file can support both options.
 
-By default a non-linear free surface is used (\np{ln\_linssh} set to \forcode{=.false.} in \nam{dom}):
+By default a non-linear free surface is used (\np{ln_linssh}{ln\_linssh} set to \forcode{=.false.} in \nam{dom}):
 the coordinate follow the time-variation of the free surface so that the transformation is time dependent:
 $z(i,j,k,t)$ (\eg\ \autoref{fig:DOM_z_zps_s_sps}f).
-When a linear free surface is assumed (\np{ln\_linssh} set to \forcode{=.true.} in \nam{dom}),
+When a linear free surface is assumed (\np{ln_linssh}{ln\_linssh} set to \forcode{=.true.} in \nam{dom}),
 the vertical coordinates are fixed in time, but the seawater can move up and down across the $z_0$ surface
 (in other words, the top of the ocean in not a rigid lid).
 
 Note that settings:
-\np{ln\_zco}, \np{ln\_zps}, \np{ln\_sco} and \np{ln\_isfcav} mentioned in the following sections
+\np{ln_zco}{ln\_zco}, \np{ln_zps}{ln\_zps}, \np{ln_sco}{ln\_sco} and \np{ln_isfcav}{ln\_isfcav} mentioned in the following sections
 appear to be namelist options but they are no longer truly namelist options for \NEMO.
 Their value is written to and read from the domain configuration file and
@@ -517 +517 @@
 serve both to provide a record of the choices made whilst building the configuration and
 to trigger appropriate code blocks within \NEMO.
-These values should not be altered in the \np{cn\_domcfg} file.
+These values should not be altered in the \np{cn_domcfg}{cn\_domcfg} file.
 
 \medskip
-The decision on these choices must be made when the \np{cn\_domcfg} file is constructed.
+The decision on these choices must be made when the \np{cn_domcfg}{cn\_domcfg} file is constructed.
 Three main choices are offered (\autoref{fig:DOM_z_zps_s_sps}a-c):
 
 \begin{itemize}
-\item $z$-coordinate with full step bathymetry (\np{ln\_zco}\forcode{=.true.}),
-\item $z$-coordinate with partial step ($zps$) bathymetry (\np{ln\_zps}\forcode{=.true.}),
-\item Generalized, $s$-coordinate (\np{ln\_sco}\forcode{=.true.}).
+\item $z$-coordinate with full step bathymetry (\np{ln_zco}{ln\_zco}\forcode{=.true.}),
+\item $z$-coordinate with partial step ($zps$) bathymetry (\np{ln_zps}{ln\_zps}\forcode{=.true.}),
+\item Generalized, $s$-coordinate (\np{ln_sco}{ln\_sco}\forcode{=.true.}).
 \end{itemize}
 
@@ -534 +534 @@
 A further choice related to vertical coordinate concerns
 the presence (or not) of ocean cavities beneath ice shelves within the model domain.
-A setting of \np{ln\_isfcav} as \forcode{.true.} indicates that the domain contains ocean cavities,
+A setting of \np{ln_isfcav}{ln\_isfcav} as \forcode{.true.} indicates that the domain contains ocean cavities,
 otherwise the top, wet layer of the ocean will always be at the ocean surface.
 This option is currently only available for $z$- or $zps$-coordinates.
@@ -544 +544 @@
 They are updated at each model time step.
 The initial fixed reference coordinate system is held in variable names with a $\_0$ suffix.
-When the linear free surface option is used (\np{ln\_linssh}\forcode{=.true.}),
+When the linear free surface option is used (\np{ln_linssh}{ln\_linssh}\forcode{=.true.}),
 \textit{before}, \textit{now} and \textit{after} arrays are initially set to
 their reference counterpart and remain fixed.
@@ -652 +652 @@
 (grid-point position, scale factors)
 can be saved in a file if
-namelist parameter \np{ln\_write\_cfg} (namelist \nam{cfg}) is set to \forcode{.true.};
-the output filename is set through parameter \np{cn\_domcfg\_out}.
+namelist parameter \np{ln_write_cfg}{ln\_write\_cfg} (namelist \nam{cfg}) is set to \forcode{.true.};
+the output filename is set through parameter \np{cn_domcfg_out}{cn\_domcfg\_out}.
 This is only really useful if
 the fields are computed in subroutines \mdl{usrdef\_hgr} or \mdl{usrdef\_zgr} and
@@ -661 +661 @@
 (grid-point position, scale factors, depths and masks)
 can be saved in a file called \texttt{mesh\_mask} if
-namelist parameter \np{ln\_meshmask} (namelist \nam{dom}) is set to \forcode{.true.}.
+namelist parameter \np{ln_meshmask}{ln\_meshmask} (namelist \nam{dom}) is set to \forcode{.true.}.
 This file contains additional fields that can be useful for post-processing applications.
 
@@ -679 +679 @@
 Basic initial state options are defined in \nam{tsd}.
 By default, the ocean starts from rest (the velocity field is set to zero) and
-the initialization of temperature and salinity fields is controlled through the \np{ln\_tsd\_init} namelist parameter.
+the initialization of temperature and salinity fields is controlled through the \np{ln_tsd_init}{ln\_tsd\_init} namelist parameter.
 
 \begin{description}
-\item[\np{ln\_tsd\_init}\forcode{= .true.}]
+\item[\np{ln_tsd_init}{ln\_tsd\_init}\forcode{= .true.}]
   Use T and S input files that can be given on the model grid itself or on their native input data grids.
   In the latter case, the data will be interpolated on-the-fly both in the horizontal and the vertical to the model grid
   (see \autoref{subsec:SBC_iof}).
-  The information relating to the input files are specified in the \np{sn\_tem} and \np{sn\_sal} structures.
+  The information relating to the input files are specified in the \np{sn_tem}{sn\_tem} and \np{sn_sal}{sn\_sal} structures.
   The computation is done in the \mdl{dtatsd} module.
-\item[\np{ln\_tsd\_init}\forcode{= .false.}]
+\item[\np{ln_tsd_init}{ln\_tsd\_init}\forcode{= .false.}]
   Initial values for T and S are set via a user supplied \rou{usr\_def\_istate} routine contained in \mdl{userdef\_istate}.
   The default version sets horizontally uniform T and profiles as used in the GYRE configuration