Theses general rules should be seen as basic golden rules helping the whole documentation to be consistent. They are strongly recommended:
Follow 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.
Use the macros described in the macros section
*i.e* usepackage{csmacros}).
Use the notations defined in the nomenclature of the theory guide
as much as possible.
Focus on your specificities and cite the generalities (external to EDF!), which
you should add to the csbiblio.bib file located in the doc/style directory.
Write in English (UK for the theory manual, US for the rest,
for consistence with existing documentation).
Use the existing style of code_saturne, that is to say use the csdoc.csl
class (for long documents as a report) csshortdoc.cls` class (for short documents as an article).
Respect 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) situations.
keep your own macros to an absolute minimum.
Macros and typography
This section does not pretend to describe how to write a document, but is to present the macros defined in csmacro.sty and give some typographic pieces of advice.
Macros
The \CS macro in the csdoc.sty package is used to allow a short syntax and typeset the code_saturne name in a proper and consistant manner.
The available macros for mathematical symbols are available through the csmacros.sty package.
Mathematical operators defined in csmacros
code
preview
comment
$\divs$
$\divv$
$\divt$
$\grad$
$\ggrad$
$\gradv$
$\gradt$
$\gradtt$
$\mat{M}$
$\matt{M}$
$\rot$
$\vect{V}$
$\tens{T}$
$\transpose{M}$
$\symmetric{M}$
$\trace$
$\deviator{M}$
$\norm{M}$
$\rans{M}$
$\fluct{M}$
$\fluctt{M}$
$\favre{M}$
$\ints{M}{N}$
$\intss{M}{N}$
$\intt{M}{N}$
\degresC
$\Max$
$\Min$
$\dd$
total derivative
Many macros are dedicated to discretized quantity notations used throughout code_saturne. The following table lists the main ones, but may not be complete, so checking the actual contents of csmacros.sty is always recommened.
Discretized quanties defined in csmacros
code
preview
comment
$\Facei{\celli}$
set of internal faces
$\Faceb{\cellj}$
set of boundary faces
$\Face{\celli}$
set of faces
$\face$
face
$\fij$
internal face
$\fib$
boundary face
$\iface$
oriented face
$\ij$
oriented internal face
$\ib$
oriented boundary face
$\celli$
name of the current cell
$\cellj$
name of the adjacent cell
$\ipf$
orthogonal center index of the current cell
$\jpf$
orthogonal center index of the adjacent cell
$\centi$
center of the current cell
$\centj$
center of the adjacent cell
$\centip$
orthogonal center of the current cell
$\centjp$
orthogonal center of the adjacent cell
$\cento$
intersection between the cell centers and the face
$\centf$
center of the face
Typography
Here are some useful tricks:
If you want to describe multiple topics, use the \begin{itemize} \item \end{itemize} environment.
You can use blue and orange EDF colors with the blue \textcolor{blueedf}{text}, its darker version \textcolor{bluededf}{text}, or the orange \textcolor{orangeedf}{text} and its the dark version \textcolor{orangededf}{text}.
Use label and references, and dissociate equations with sections and appendices and figures and tables using \label{eq:label}, \label{sec:label}, \label{ap:label}, \label{fig:label} and \label{tab:label} prefixes.
Use the \emph{} mode for acronyms (e.g., EDF).
Use the \emph{} mode for Latin words (e.g., i.e., a priori, etc.).
Use \left( instead of ( and \right) instead of ) in math mode.
DO NOT put a space before the ":" symbol. In English the rule is no space, never.
DO NOT use \newline or \\ except in a tabular environment or an array.
Write "Equation" with a first upper case letter. Use \figurename~ and \tablename~ to write and .