Update documentation wrt tuple -> variable/compound affectations

doc/userdoc.org

@@ -1852,6 +1852,72 @@ 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.
 
+**** Tuple and other variables
+
+If one cannot access to specific values of tuple variables, one can
+however dispatch their values to compound variable lists or to simple
+variable. To do so the tuple content must be convertible to each of
+the compound variable using the operator ~=~ rules (see the conversion
+table in section [[implicit-conversion]]). The one to one matching is
+checked at runtime.
+#+NAME: tuple-to-compound
+#+BEGIN_SRC pugs :exports both :results output
+  let t:(R), t = (1, 2, 3.4, -5);
+
+  let (x, y, u, A):R*R*R^1*R^1x1, (x, y, u, A) = t;
+
+  cout << "t = " << t << "\n";
+  cout << "x = " << x << "\n";
+  cout << "y = " << y << "\n";
+  cout << "u = " << u << "\n";
+  cout << "A = " << A << "\n";
+#+END_SRC
+This code gives
+#+results: tuple-to-compound
+
+#+BEGIN_note
+One could have separate the declarations of ~x~, ~y~, ~u~ and ~A~ from the
+affectation. Writing simply at some point
+
+#+BEGIN_SRC pugs :exports code
+  (x, y, u, A) = t;
+#+END_SRC
+
+#+END_note
+
+If the tuple contains only one entry, one can assign its value to a
+simple variable.
+#+NAME: tuple-to-variable
+#+BEGIN_SRC pugs :exports both :results output
+  let t:(R^3), t = [1, 2, 3];
+
+  let x:R^3, x = t;
+
+  cout << "t = " << t << "\n";
+  cout << "x = " << x << "\n";
+#+END_SRC
+One gets
+#+results: tuple-to-variable
+
+If the size of the tuple does not match the number of space defining
+the compound type, one gets a runtime error. For instance
+#+NAME: tuple-to-compound-wrong-size
+#+BEGIN_SRC pugs-error :exports both :results output
+  let t:(Z), t = (1, 2);
+  let (a, b, c):R*R*R, (a, b, c) = t;
+#+END_SRC
+produces
+#+results: tuple-to-compound-wrong-size
+or
+#+NAME: tuple-to-variable-wrong-size
+#+BEGIN_SRC pugs-error :exports both :results output
+  let t:(Z), t = (1, 2);
+  let a:R, a = t;
+#+END_SRC
+which gives
+#+results: tuple-to-variable-wrong-size
+
+
 ** Statements
 
 The ~pugs~ language supports classical statements to control the data