Add documentation for tuples (+minor fixes)

doc/userdoc.org

@@ -727,11 +727,12 @@ In order to avoid ambiguities, in ~pugs~, there is *no implicit*
 conversion in general.
 
 #+BEGIN_note
-Actually, there are only two situations for which implicit type
+Actually, there are only three situations for which implicit type
 conversion can occur
 - when the value is given as a parameter of a function, or
 - when the value is used as the returned value of a function.
-This will be detailed in section [[functions]].
+- when the value is used to define a tuple
+This will be detailed in section [[functions]] and [[tuples]]
 #+END_note
 
 This means that all affectation, unary and binary operators are
@@ -1613,6 +1614,33 @@ types. This is transparent to the user and provides the intuitive
 (similar) behavior since data of high-level variables are constant. To
 illustrate this, let us consider the following example.
 
+#+BEGIN_SRC pugs :exports both
+  import mesh;
+
+  let m1:mesh, m1 = cartesian2dMesh(0, (1,1), (10,10));
+  let m2:mesh, m2 = m1;
+  let m3:mesh, m3 = cartesian2dMesh(0, (1,1), (10,10));
+
+  m3 = m1;
+#+END_SRC
+
+In this example, we are dealing with 3 ~mesh~ variables.
+- First ~m1~ is defined as a uniform cartesian mesh in dimension 2 of
+  $]0,1[^2$ made of $10\times10$ identical square cells.
+- Then ~m2~ is a copy of the variable ~m1~. It is a copy of the variable,
+  but the underlying mesh is *the same*! There is no duplication of the
+  mesh in memory.
+- Then the mesh variable ~m3~ is *defined* to refer to a *new* mesh. It is
+  /similar/ to the mesh contained in ~m1~ and ~m2~, but it is *not* the same
+  one! When ~m3~ is defined two meshes, (and two connectivities) are
+  resident in memory. One of the mesh is referred by either ~m1~ or ~m2~
+  and the other one is referred by ~m3~.
+- Finally, the last instruction (~m3 = m1;~) sets ~m3~ to also refer the
+  mesh referred by ~m1~ and ~m2~. Since no other variable refers to its
+  former mesh, it is destroyed (memory is freed). At the end of the
+  program, all the variables ~m1~, ~m2~ and ~m3~ are referring to the same
+  mesh, and there is only one mesh that resides in memory.
+
 *** Compound types
 
 The ~pugs~ language allow to deal with compound types. The idea is to
@@ -1638,6 +1666,12 @@ the output is
 This is completely equivalent to declaring the variables one after the
 other.
 
+#+BEGIN_note
+Observe that there is no implicit conversion when dealing with
+compound types. The ~=~ operators are used sequentially to set the
+different variables.
+#+END_note
+
 **** Compound definition
 
 One can also use the following definition instruction
@@ -1708,7 +1742,53 @@ section [[functions]], functions can return compound values, thus compound
 affectations (or definitions) are needed to get returned values in
 that case.
 
-*** TODO Tuples types
+*** TODO Tuple types<<tuples>>
+
+The last special type construction is the ability to deal with tuples
+in the ~pugs~ language. The tuples we are describing here are lists of
+data of a *unique* and *simple* type (one cannot use compound types to
+define tuples).
+
+The list of values given to the tuple must be *implicitly* convertible
+to the type of tuple elements. There is no ambiguity, the implicit
+conversions follow the rules of operator ~=~.
+
+**** Tuple declaration and affectation
+
+For instance, one may write
+#+NAME: tuple-declaration-affectation
+#+BEGIN_SRC pugs :exports both :results output
+  let x:(R);
+  x = (1,2,3.4,2);
+  cout << x << "\n";
+#+END_SRC
+Executing this code, one gets
+#+results: tuple-declaration-affectation
+
+**** Tuple definition
+
+The definition syntax is also possible.
+#+NAME: tuple-definition
+#+BEGIN_SRC pugs :exports both :results output
+  let x:(R^2), x = ((1,2),(3.4,2), 0, (2,3));
+  cout << x << "\n";
+#+END_SRC
+This code gives
+#+results: tuple-definition
+
+Observe that the special value ~0~ is used there.
+
+**** Tuple purpose
+
+Tuples variables are just lists of data of the same type. In the ~pugs~
+language, one cannot access to a specific value of the list nor alter
+one of them. This is not something that should ever change. Tuples are
+not arrays! The ~pugs~ language is not meant to allow low-level
+instructions.
+
+ The use case of tuples is to provide lists of data to the ~C++~
+underlying methods. A classical example is to provide a set of
+boundary conditions to a method.
 
 ** TODO Statements