8.2
general documentation
Writing the theory documentation

Table of Contents

General rules

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 $ \mbox{\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) situations.
  • keep your own macros to an absolute minimum.

Macros and typography

This section does not pretend to describe how to write a $ \mbox{\LaTeX} $ 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
$ \mbox{\LaTeX} $ code preview comment
$\divs$ $ \divs $
$\divv$ $ \divv $
$\divt$ $ \divt $
$\grad$ $ \grad $
$\ggrad$ $ \ggrad $
$\gradv$ $ \gradv $
$\gradt$ $ \gradt $
$\gradtt$ $ \gradtt $
$\mat{M}$ $ \mat{M} $
$\matt{M}$ $ \matt{M} $
$\rot$ $ \rot $
$\vect{V}$ $ \vect{V} $
$\tens{T}$ $ \tens{T} $
$\transpose{M}$ $ \transpose{M} $
$\symmetric{M}$ $ \symmetric{M} $
$\trace$ $ \trace $
$\deviator{M}$ $ \deviator{M} $
$\norm{M}$ $ \norm{M} $
$\rans{M}$ $ \rans{M} $
$\fluct{M}$ $ \fluct{M} $
$\fluctt{M}$ $ \fluctt{M} $
$\favre{M}$ $ \favre{M} $
$\ints{M}{N}$ $ \int{M}{N} $
$\intss{M}{N}$ $ \intss{M}{N} $
$\intt{M}{N}$ $ \intt{M}{N} $
\degresC $\mbox{\degresC}$
$\Max$ $ \Max $
$\Min$ $ \Min $
$\dd$ $ \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
$ \mbox{\LaTeX} $ code preview comment
$\Facei{\celli}$ $ \Facei{\celli} $ set of internal faces
$\Faceb{\cellj}$ $ \Faceb{\cellj} $ set of boundary faces
$\Face{\celli}$ $ \Face{\celli} $ set of faces
$\face$ $ \face $ face
$\fij$ $ \fij $ internal face
$\fib$ $ \fib $ boundary face
$\iface$ $ \iface $ oriented face
$\ij$ $ \ij $ oriented internal face
$\ib$ $ \ib $ oriented boundary face
$\celli$ $ \celli $ name of the current cell
$\cellj$ $ \cellj $ name of the adjacent cell
$\ipf$ $ \ipf $ orthogonal center index of the current cell
$\jpf$ $ \jpf $ orthogonal center index of the adjacent cell
$\centi$ $ \centi $ center of the current cell
$\centj$ $ \centj $ center of the adjacent cell
$\centip$ $ \centip $ orthogonal center of the current cell
$\centjp$ $ \centjp $ orthogonal center of the adjacent cell
$\cento$ $ \cento $ intersection between the cell centers and the face
$\centf$ $ \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 $ \figurename $ and $ \tablename $.
  • Use the enumerate environment:
    \begin{enumerate}[ label=\roman{*}/, ref=(\roman{*})]
    \item $1^{st}$ item
    \item $2^{nd}$ item
    \end{enumerate}
    i/ 1st item
    ii/ 2nd item
  • Use the remarks \begin{remark} \end{remark} and example \begin{example} \end{example} environments defined in csdoc.cls:
    \begin{remark}
    A remark
    \end{remark}
    \begin{example}
    An example
    \end{example}}
    Remark 1.1 A remark
    Example 1.1 _An example