doc: Update dev doc with some org-mode tips.

doc/dev/documentation.org

@@ -40,13 +40,109 @@
 *** TODO Linux
 *** TODO Windows
 * TODO Documentation files
-** TODO The environment
+
+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
-*** TODO Format
-*** TODO Macro
+*** 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\]
+
+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 Export
 * TODO How to contribute?
 ** TODO Contribution rules
 ** TODO Translate