# documentation.org -- Pamhyr developers documentation
# Copyright (C) 2023  INRAE
#
# 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 3 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, see <https://www.gnu.org/licenses/>.

# -*- coding: utf-8 -*-

#+STARTUP: indent

#+INCLUDE: ../tools/macro.org
#+INCLUDE: ../tools/latex.org

#+TITLE: Developers documentation
#+SUBTITLE: Version: {{{version}}}
#+AUTHOR: {{{INRAE}}}

#+OPTIONS: toc:t
#+LANGUAGE: UKenglish

* TODO The environment
* TODO Architecture
** TODO Model
** TODO Solver
** TODO View
** TODO Unit tests
** TODO The debug mode
* TODO Build the project
** TODO Building packages
*** TODO Linux
*** TODO Windows
* TODO Documentation files

This document and the user documentation are org[fn:org] files. This text file
format is formatted so that it can be exported in different formats:
PDF (with latex), ODT, HTML, etc. It was originally designed for the
GNUEmacs[fn:emacs] text editor, but can be edited with any text editor. Here we
take a look at the different features used in these documents.

[fn:org] The org-mode website: https://orgmode.org/
[fn:emacs] The GNUEmacs project website: https://gnu.org/s/emacs/

** TODO Org-mode
*** Document structure

Org uses the =*= character to define a new document section. To add a
sub-section, you can add an additional =*= to the current section[fn::
See document structure documentation:
https://orgmode.org/org.html#Headlines].

#+BEGIN_EXAMPLE
 * Top level headline
 ** Second level
 *** Third level
     some text
 *** Third level
     more text
 * Another top level headline
#+END_EXAMPLE

*** Format

Org-mode is a markup file, using markup in the text to modify the
appearance of a portion of text[fn:: See markup documentation:
https://orgmode.org/org.html#Emphasis-and-Monospace].

| Markup             | Results          |
|--------------------+------------------|
| =*Bolt*=           | *Bolt*           |
| =/Italic/=         | /Italic/         |
| =_underline_=      | _underline_      |
| ==verbatim==       | =verbatim=       |
| =~code~=           | ~code~           |
| =+strike-through+= | +strike-through+ |

*** TODO Code block

*** Latex

If we export the file to PDF, org-mode use \LaTeX. So we can add some
piece of \LaTeX into the document[fn:: See \LaTeX part in
documentation: https://orgmode.org/org.html#Embedded-LaTeX]. For
exemple, we can add math formula like =$E=mc^2$= ($E=mc^2$) or
=\[E=mc^2\]=:

\[E=mc^2\]

But we can also add every type of \LaTeX:

#+BEGIN_EXAMPLE
# Add latex in line
#+LATEX: <my line of latex>

# Add multiple line of LaTeX
#+BEGIN_EXPORT latex
<my latex here>
#+END_EXPORT
#+END_EXAMPLE

It is also possible to add specific \LaTeX file header with
=#+LATEX_HEADER=. In this document we use the file
{{{file(doc/tools/latex.org)}}} for all \LaTeX headers.

*** Macro

In this document, we use a few macros[fn:: See marcos documentation
https://orgmode.org/org.html#Macro-Replacement] to simplify
writing. They allow you to define sequences of text to be replaced, so
that the macro name is replaced by its value. They are defined in the
{{{file(doc/tools/macro.org)}}} file. Once defined, they can be used
in the document as follows: ={{{<macro-name>}}}=. You can also have
macros with arguments, in this case:
={{{<macro-name>(arg1,...)}}}=. Les macros peuvent aussi utiliser du
code emacs-lisp.

#+BEGIN_EXAMPLE
# Exemple of macro définition

#+MACRO: toto               tata
#+MACRO: add                \(($1 + $2)\)
#+MACRO: emacs-version      (eval (nth 2 (split-string (emacs-version))))
#+END_EXAMPLE

#+MACRO: toto               tata
#+MACRO: add                \(($1 + $2)\)
#+MACRO: emacs-version      (eval (nth 2 (split-string (emacs-version))))

Macro apply:
- Marco ={{{toto}}}=: {{{toto}}}
- Marco ={{{add(x,y)}}}=: {{{add(x,y)}}}
- Marco ={{{emacs-version}}}=: {{{emacs-version}}}

*** TODO Footnote
*** TODO References

** TODO Export
* TODO How to contribute?
** TODO Contribution rules
** TODO Translate
** TODO Code contribution

{{{biblio}}}