diff --git a/doc/dev/documentation.org b/doc/dev/documentation.org index 99867b084f1a54c5b43832da2bc6300906ebc32b..03d3c4b65e8c9dc65a98eff8f94d2fd5ff32c4a8 100644 --- a/doc/dev/documentation.org +++ b/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