Start the outline of the user documentation [ci-skip]

doc/userdoc.org

@@ -138,33 +138,61 @@ already be discussed.
   builtin functions and are generally defined when importing a
   module. These functions behave similarly, one should refer to
   [[functions]] for details.
-- The language does not allow low-level manipulations of high-level
-  type variables. This means that for instance, one cannot modify a
-  specific cell value of a piecewise constant function. This allows to
-  write algorithms (within the pugs language) that can be executed in
-  parallel naturally. Observe that the resulting mesh of the previous
-  does not depend on the number of ~MPI~ processes nor on the number of
-  threads used while running ~pugs~.
 
-*  Language
+** Concepts and design
 
-** Variables
+*** TODO A C++ toolbox driven by a user friendly language
 
-*** Types<<variable-types>>
+- Why? divide and conquer
+  - the language is used to assemble the provided C++ tools
+  - small independent C++ methods are easy to test/validate.
+  - new numerical method brings a new C++ code: not a patched code.
+    A previously validated method is unchanged!
+    - much more difficult to introduce bugs in existing methods
+    - existing methods performances are a unchanged by new
+      developments
+- Why not python or any other scripting language?
+  - provide a language close to the application: a DSL is made for
+    that
+  - do not deal with the difficulty of parallelism within the
+    scripting language
+- Following the success of ~FreeFEM~
 
-**** Basic types
+*** TODO A high-level language
 
-**** High-level types
+Defining a suitable language
 
-*** Life time
+**** TODO Keep it simple
 
-** Statements
+**** TODO Performances and parallelism
 
-** Functions<<functions>>
+The language *does not allow* low-level manipulations of high-level type
+variables. This means that for instance, one cannot access or modify
+specific cell or node value. A consequence of such a choice is that
+this *constrained framework* allows to write algorithms (within the pugs
+language) that can be executed in parallel naturally. To achieve that,
+there should *never* be parallel instructions or instructions that
+require *explicit parallel* actions in the ~pugs~ language.
 
-*** User-defined functions
+* TODO Language
 
-*** Builtin functions
+** TODO Variables
+
+*** TODO Types<<variable-types>>
+
+**** TODO Basic types
+
+**** TODO High-level types
+
+*** TODO Life time
+
+** TODO Statements
+
+** TODO Functions<<functions>>
+
+*** TODO User-defined functions
+
+*** TODO Builtin functions