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

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

@@ -53 +53 @@
 \begin{itemize}
 
-\item Add \texttt{e1e2u} and \texttt{e1e2v} arrays to the \np{cn\_domcfg} file. These 2D
+\item Add \texttt{e1e2u} and \texttt{e1e2v} arrays to the \np{cn_domcfg}{cn\_domcfg} file. These 2D
 arrays should contain the products of the unaltered values of: $\texttt{e1u}*\texttt{e2u}$
 and $\texttt{e1u}*\texttt{e2v}$ respectively. That is the original surface areas of $u$-
 and $v$- cells respectively.  These areas are usually defined by the corresponding product
 within the \NEMO\ code but the presence of \texttt{e1e2u} and \texttt{e1e2v} in the
-\np{cn\_domcfg} file will suppress this calculation and use the supplied fields instead.
+\np{cn_domcfg}{cn\_domcfg} file will suppress this calculation and use the supplied fields instead.
 If the model domain is provided by user-supplied code in \mdl{usrdef\_hgr}, then this
 routine should also return \texttt{e1e2u} and \texttt{e1e2v} and set the integer return
@@ -64 +64 @@
 will suppress the calculation of the areas.
 
-\item Change values of \texttt{e2u} or \texttt{e1v} (either in the \np{cn\_domcfg} file or
+\item Change values of \texttt{e2u} or \texttt{e1v} (either in the \np{cn_domcfg}{cn\_domcfg} file or
 via code in  \mdl{usrdef\_hgr}), whereever a Strait reduction is required. The choice of
 whether to alter \texttt{e2u} or \texttt{e1v} depends. respectively,  on whether the
@@ -198 +198 @@
 maintain different sets of input fields for use with or without active ice cavities.  This
 subsetting operates for the j-direction only and works by optionally looking for and using
-a global file attribute (named: \np{open\_ocean\_jstart}) to determine the starting j-row
+a global file attribute (named: \np{open_ocean_jstart}{open\_ocean\_jstart}) to determine the starting j-row
 for input.  The use of this option is best explained with an example:
 \medskip
@@ -206 +206 @@
 This file define a horizontal domain of 362x332.  The first row with
 open ocean wet points in the non-isf bathymetry for this set is row 42 (\fortran\ indexing)
-then the formally correct setting for \np{open\_ocean\_jstart} is 41.  Using this value as
+then the formally correct setting for \np{open_ocean_jstart}{open\_ocean\_jstart} is 41.  Using this value as
 the first row to be read will result in a 362x292 domain which is the same size as the
 original ORCA1 domain.  Thus the extended domain configuration file can be used with all
@@ -218 +218 @@
 \end{cmds}
 
-\item Add the logical switch \np{ln\_use\_jattr} to \nam{cfg} in the configuration
-namelist (if it is not already there) and set \np{.true.}
+\item Add the logical switch \np{ln_use_jattr}{ln\_use\_jattr} to \nam{cfg} in the configuration
+namelist (if it is not already there) and set \forcode{.true.}
 \end{itemize}
 
 \noindent Note that with this option, the j-size of the global domain is (extended
-j-size minus \np{open\_ocean\_jstart} + 1 ) and this must match the \texttt{jpjglo} value
+j-size minus \np{open_ocean_jstart}{open\_ocean\_jstart} + 1 ) and this must match the \texttt{jpjglo} value
 for the configuration. This means an alternative version of \ifile{eORCA1\_domcfg.nc} must
-be created for when \np{ln\_use\_jattr} is active. The \texttt{ncap2} tool provides a
+be created for when \np{ln_use_jattr}{ln\_use\_jattr} is active. The \texttt{ncap2} tool provides a
 convenient way of achieving this:
 
@@ -237 +237 @@
 \texttt{open\_ocean\_jstart} attribute to the file's global attributes.
 In particular this is true for any field that is read by \NEMO\ using the following optional argument to
-the appropriate call to \np{iom\_get}.
+the appropriate call to \np{iom_get}{iom\_get}.
 
 \begin{forlines}
@@ -332 +332 @@
 This alternative method should give identical results to the default \textsc{ALLGATHER} method and
 is recommended for large values of \np{jpni}.
-The new method is activated by setting \np{ln\_nnogather} to be true (\nam{mpp}).
+The new method is activated by setting \np{ln_nnogather}{ln\_nnogather} to be true (\nam{mpp}).
 The reproducibility of results using the two methods should be confirmed for each new,
 non-reference configuration.
@@ -364 +364 @@
 \subsection{Control print}
 
-The \np{ln\_ctl} switch was originally used as a debugging option in two modes:
+The \np{ln_ctl}{ln\_ctl} switch was originally used as a debugging option in two modes:
 
 \begin{enumerate}
-\item{\np{ln\_ctl}: compute and print the trends averaged over the interior domain in all TRA, DYN, LDF and
+\item{\np{ln_ctl}{ln\_ctl}: compute and print the trends averaged over the interior domain in all TRA, DYN, LDF and
 ZDF modules.
 This option is very helpful when diagnosing the origin of an undesired change in model results. }
 
-\item{also \np{ln\_ctl} but using the nictl and njctl namelist parameters to check the source of differences between
+\item{also \np{ln_ctl}{ln\_ctl} but using the nictl and njctl namelist parameters to check the source of differences between
 mono and multi processor runs.}
 \end{enumerate}
 
 However, in recent versions it has also been used to force all processors to assume the
-reporting role. Thus when \np{ln\_ctl} is true all processors produce their own versions
+reporting role. Thus when \np{ln_ctl}{ln\_ctl} is true all processors produce their own versions
 of files such as: ocean.output, layout.dat, etc.  All such files, beyond the the normal
 reporting processor (narea == 1), are named with a \_XXXX extension to their name, where
@@ -382 +382 @@
 such as run.stat (and its netCDF counterpart: run.stat.nc) and tracer.stat contain global
 information and are only ever produced by the reporting master (narea == 1). For version
-4.0 a start has been made to return \np{ln\_ctl} to its original function by introducing
+4.0 a start has been made to return \np{ln_ctl}{ln\_ctl} to its original function by introducing
 a new control structure which allows finer control over which files are produced. This
 feature is still evolving but it does already allow the user to: select individually the