8.2
general documentation
Writing the theory documentation

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