mirror of https://gitlab.com/pamhyr/pamhyr2
153 lines
4.4 KiB
Org Mode
153 lines
4.4 KiB
Org Mode
# 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}}}
|