%-------------------------------------------------------------------------------

% This file is part of Code_Saturne, a general-purpose CFD tool.
%
% Copyright (C) 1998-2019 EDF S.A.
%
% This program is free software; you can redistribute it and/or modify it under
% the terms of the GNU General Public License as published by the Free Software
% Foundation; either version 2 of the License, or (at your option) any later
% version.
%
% This program is distributed in the hope that it will be useful, but WITHOUT
% ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
% FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
% details.
%
% You should have received a copy of the GNU General Public License along with
% this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
% Street, Fifth Floor, Boston, MA 02110-1301, USA.

%-------------------------------------------------------------------------------

\section{Write a part of the theory guide}

\subsection{General rules}

Theses general rules should be seen as basic golden rules helping the whole
documentation to be consistent. They are strongly recommended:

\begin{itemize}
\item Respect a plan where you first present a general overview of the theory
      (what is it about, what is the main goal), then you present the equations
      in general, and finally the specific choices you have made.
\item Use the macros described in \S~\ref{sec:macros} (\emph{i.e} \verb1\usepackage{csmacros}1).
\item Use the notations defined in the nomenclature of the theory guide
      as much as possible.
\item Focus on your specificities and cite the generalities (external to EDF!), which you should add to the \texttt{biblio.bib} file
      located in the \texttt{/doc/style/} directory.
\item Write in English (UK).
\item Use the existing style of \CS, that is to say use the class \texttt{csdoc.csl} (for long documents as a report)
      or the class \texttt{csshortdoc.cls} (for short documents as an article).
\item Respect \LaTeX~philosophy, as it is designed to make sensible spacing decisions
      by itself, do not use explicit horizontal or vertical spacing commands, except in
      a few accepted (mostly mathematical) situation.
\item keep your own macros to an absolute minimum.
\end{itemize}

\subsection{Macros and typos}\label{sec:macros}
This section does not pretend to describe how to write a \LaTeX document, but is to
present the macros defined in \texttt{csmacro.sty} and give some typographic pieces of advice.

\subsubsection{Macros}
The available macros located in the \texttt{csmacros} and \texttt{csvers.tex} package are displayed
in \tablename~\ref{tab:macros_soft} and \tablename~\ref{tab:macros_math}.

\begin{table}[!htbp]
\centering
\begin{tabular}{p{0.25 \textwidth} | p{0.25 \textwidth} }
\LaTeX code & preview \\
\hline
\verb1\CS1 & \CS \\
\verb1\ensight1 & \ensight \\
\verb1\ensightg1 & \ensightg \\
\verb1\fluent1 & \fluent \\
\verb1\bft1 & \bft \\
\verb1\fvm1 & \fvm \\
\verb1\gambit1 & \gambit \\
\verb1\gmsh1 & \gmsh \\
\verb1\harpoon1 & \harpoon \\
\verb1\hexpress1 & \hexpress \\
\verb1\icemcfd1 & \icemcfd \\
\verb1\ideas1 & \ideas \\
\verb1\med1 & \med \\
\verb1\metis1 & \metis \\
\verb1\parmetis1 & \parmetis \\
\verb1\nopo1 & \nopo \\
\verb1\paraview1 & \paraview \\
\verb1\pcs1 & \pcs \\
\verb1\salome1  & \salome   \\
\verb1\scotch1  & \scotch   \\
\verb1\ptscotch1& \ptscotch \\
\verb1\simail1  & \simail   \\
\verb1\starcd1  & \starcd   \\
\verb1\starccmp1& \starccmp \\
\verb1\syrthes1 & \syrthes  \\
\verb1\vtk1     & \vtk
\end{tabular}
\caption{Macros of softwares  defined in \texttt{csmacros.sty}.\label{tab:macros_soft}}
\end{table}

\begin{table}[!htbp]
\begin{tabular}{p{0.5 \textwidth} | p{0.5 \textwidth} }
\LaTeX code & preview \\
\hline
\verb1$\divs$1   &  $ \divs    $\\
\verb1$\divv$1   &  $ \divv    $\\
\verb1$\divt$1   &  $ \divt    $\\
\verb1$\grad$1   &  $ \grad    $\\
\verb1$\gradv$1  &  $ \gradv   $\\
\verb1$\gradt$1  &  $ \gradt   $\\
\verb1$\rot$1    &  $ \rot     $\\
\verb1$\vect{V}$1   &  $ \vect{V}    $\\
\verb1$\tens{T}$1   &  $ \tens{T}    $\\
\verb1\degresC1   &   \degresC \\
\verb1$\Max$1    &  $ \Max     $\\
\verb1$\Min$1    &  $ \Min     $\\
\verb1$\trace$1    &  $ \trace     $\\
\verb1$\transpose{M}$1    &  $ \transpose{M} $\\
\verb1$\deviator{M}$1    &  $ \deviator{M} $\\
\verb1$\symmetric{M}$1    &  $ \symmetric{M} $\\
\verb1$\dd$1    &  $ \dd     $
\end{tabular}
\caption{Macros of some mathematical symbols defined in \texttt{csmacros.sty}.\label{tab:macros_math}}
\end{table}

%
\begin{table}[!htbp]
\begin{tabular}{p{0.5 \textwidth} | p{0.5 \textwidth} }
\LaTeX code & preview \\
\hline
\verb1$\Facei{\celli}$1   &  $ \Facei{\celli}    $\\
\verb1$\Faceb{\cellj}$1   &  $ \Faceb{\cellj}    $\\
\verb1$\Face{\celli}$1   &  $ \Face{\celli}    $\\
\verb1$\fij$1   &  $ \fij    $\\
\verb1$\fib$1  &  $ \fib   $\\
\verb1$\ij$1  &  $ \ij   $\\
\verb1$\ib$1    &  $ \ib     $\\
\verb1$\celli$1   &  $ \celli    $\\
\verb1$\cellj$1   &  $ \cellj    $\\
\verb1$\ipf$1    &  $ \ipf     $\\
\verb1$\jpf$1    &  $ \jpf     $\\
\verb1$\centi$1    &  $ \centi $\\
\verb1$\centj$1    &  $ \centj $\\
\verb1$\centip$1    &  $ \centip $\\
\verb1$\centjp$1    &  $ \centjp $\\
\verb1$\cento$1    &  $ \cento $\\
\verb1$\centf$1    &  $ \centf $
\end{tabular}
\caption{Macros of discretized quantities defined in \texttt{csmacros.sty}.\label{tab:macros_discretize}}
\end{table}

\subsubsection{Typography}
Here are some useful tricks:
\begin{itemize}
\item If you want to make a description many topics, use the \verb1\begin{itemize} \item \end{itemize}1 environment.
\item You can use blue and orange EDF colours with the blue \verb1\textcolor{blueedf}{text}1, its the darkened version
\verb1\textcolor{bluededf}{text}1, or the orange \verb1\textcolor{orangeedf}{text}1 and its the darkened version
\verb1\textcolor{orangededf}{text}1.
\item Use label and references, and dissociate equations with sections and appendices and figures and tables using \verb1\label{eq:label}1, \verb1\label{sec:label}1, \verb1\label{ap:label}1,
\verb1\label{fig:label}1 and \verb1\label{tab:label}1 prefixes.
\item Use the \verb1\emph{}1 mode for acronyms (\emph{e.g.} \emph{EDF}).
\item Use the \verb1\emph{}1 mode for Latin words(\emph{e.g.}, \emph{i.e}, \emph{a priori}, \emph{etc.}).
\item Use \verb1\left(1 instead of \verb1(1 and \verb1\right)1 instead of \verb1)1 in math mode.
\item DO NOT put a space before the symbol ``:''. In English the rule is no space, never.
\item DO NOT use \verb1\newline1 or \verb1\\1 except in a tabular environment or an array.
\item Write ``Equation'' with a  first upper case letter. Use \verb1\figurename~1 and to \verb1\tablename~1 write \figurename~ and \tablename.
\item Use the enumerate environment:
\begin{verbatim}
\begin{enumerate}[ label=\roman{*}/, ref=(\roman{*})]
\item $1^{st}$ item
\item $2^{nd}$ item
\end{enumerate}
\end{verbatim}
\begin{enumerate}[ label=\roman{*}/, ref=(\roman{*})]
\item $1^{st}$ item
\item $2^{nd}$ item
\end{enumerate}
\item Use the remarks \verb1\begin{remark} \end{remark}1
and example \verb1\begin{example} \end{example}1 environments defined in \texttt{csdoc.csl}:
\begin{remark}
A remark
\end{remark}
\begin{example}
An example
\end{example}
\end{itemize}