Improve documentation

Fix few typos and slightly improve the text

doc/userdoc.org

@@ -195,9 +195,9 @@ There are lots of reasons not to use data files. By data file, we
 refer to a set of options that describe physical models, numerical
 methods or their settings.
 
-- Data files are not flexible. This implies in one hand that
+- Data files are not flexible. This implies in then one hand that
   application scenarios must be known somehow precisely to reflect
-  possible option combinations and on the other hand even defining a
+  possible option combinations and in the other hand even defining a
   specific initial data may require the creation of a new option and
   the associated code (in ~C++~ for instance). \\
   Usually, the last point is addressed by adding a local interpreter
@@ -446,7 +446,7 @@ Let $v\in V$.
 Actually,
 - ~let~ is the declaration keyword,
 - ~v~ is the variable name,
-- ~:~ is a separation token (can be read as "/in/" in this context),
+- ~:~ is a separation token (it can be read as "/in/" in this context),
 - ~V~ is the identifier of the type, and
 - ~;~ marks the end of the instruction.
 
@@ -478,15 +478,15 @@ already been /declared/, one writes simply
 There is not to much to comment, reading is quite natural
 - ~v~ is the variable name,
 - ~=~ is the affectation operator,
-- ~expression~ is some code that provide a value (it can be another
-  variable, an arithmetic expression, the result of a function,...),
-  and
+- ~expression~ is some code that provides a value of the same type as ~v~
+  (it can be another variable, an arithmetic expression, the result of
+  a function,...), and
 - ~;~ marks the end of the instruction.
 
 For instance, one can write
 #+NAME: simple-affectations-example
 #+BEGIN_SRC pugs :exports both :results output
-  import math; // to load sin function
+  import math; // to load the sin function
 
   let a:N;
   let b:N;
@@ -523,7 +523,7 @@ at /compile time/, this is why it is *encouraged* to use variable
 definition (see [[definition-simple-variables]]).
 
 Observe nonetheless that ~pugs~ checks at /run time/ that used variables
-are correctly defined. If not an error is produced.
+are correctly defined. If not, a /runtime/ error is produced.
 #+END_warning
 
 **** Definition of simple variables<<definition-simple-variables>>
@@ -538,14 +538,14 @@ variable ~v~ of a given type ~V~, from an expression one writes
 - ~:~ is a separation token (can be read as "/in/" in this context),
 - ~V~ is the identifier of the type,
 - ~,~ is the separator that indicates the beginning of the affectation,
-- ~expression~ is some code that provides a value (it can be another
-  variable, an expression, the result of a function,...), and
+- ~expression~ is some code that provides a value of type ~V~ (it can be
+  another variable, an expression, the result of a function,...), and
 - ~;~ marks the end of the instruction (here the definition of ~v~).
 
 A practical example is
 #+NAME: simple-definition-example
 #+BEGIN_SRC pugs :exports both :results output
-  import math; // to load sin function
+  import math; // to load the sin function
 
   let a:N, a=3;
   let b:N, b=2+a;
@@ -560,10 +560,10 @@ which produces the result
 
 In pugs scripts, variables have a precise lifetime. They are defined
 within scopes. The main scope is implicitly defined and sub-scopes are
-enclosed between bracket pairs: ~{~ and ~}~. Following ~C++~, a variable
-exits (can be used) as soon as it has been declared and until the end
-of the scope (where it has been declared). At this point we give a few
-examples.
+enclosed between curly bracket pairs: ~{~ and ~}~. Following ~C++~, a
+variable exists (can be used) as soon as it has been declared and
+until the end of the scope (where it has been declared). At this point
+we give a few examples.
 
 **** A variable cannot be used before its declaration
 #+NAME: undeclare-variable
@@ -612,9 +612,9 @@ where the variables defined in blocks follow the same lifetime rules.
 
 *** Basic types<<basic-types>>
 
-Basic types in ~pugs~ are boolean ~B~, natural integers ~N~, integers ~Z~,
-real ~R~, small vectors ~R^1~, ~R^2~ and ~R^3~, small matrices ~R^1x1~, ~R^2x2~
-and ~R^3x3~ and strings ~string~.
+Basic types in ~pugs~ are boolean (~B~), natural integers (~N~), integers (~Z~),
+real (~R~), small vectors (~R^1~, ~R^2~ and ~R^3~), small matrices (~R^1x1~, ~R^2x2~
+and ~R^3x3~) and strings (~string~).
 
 #+BEGIN_note
 Observe that while mathematically, obviously $\mathbb{R} = \mathbb{R}^1
@@ -630,7 +630,7 @@ This may sound strange but there are few reasons for that.
   instead of ~double~ values. To avoid ambiguity that may arise in some
   situations (this can lead to very tricky code), we decided to forbid
   automatic conversions of these types with ~double~. When designing the
-  language we adopt the same rule to avoid ambiguity.
+  language, we adopted the same rule to avoid ambiguity.
 - A second reason is connected to the first one. Since ~pugs~ aims at
   providing numerical methods for problems in dimension $1$, $2$ or
   $3$, this allows to distinguish the nature of the underlying objects.
@@ -662,14 +662,16 @@ expressions.
   12.3E-1;
 #+END_SRC
 - Small vectors values (types ~R^1~, ~R^2~ and ~R^3~) are written through
-  brackets. Each component of vector values must be a scalar.
+  square brackets. Each component of vector values must be a scalar
+  expression.
 #+BEGIN_SRC pugs :exports both
   [1];     // R^1 value
   [1,2];   // R^2 value
   [1,2,3]; // R^3 value
 #+END_SRC
 - Small matrices values (types ~R^1x1~, ~R^2x2~ and ~R^3x3~) are written by
-  lines through brackets. Each line is enclosed between brackets.
+  lines through square brackets. Each line is enclosed between square
+  brackets.
 #+BEGIN_SRC pugs :exports both
   [[1]];                     // R^1x1 value
   [[1,2],[3,4]];             // R^2x2 value
@@ -713,7 +715,7 @@ illustrated in the following example
 #+END_SRC
 which produces the expected result
 #+results: basic-type-value-storage
-When defining ~b~, the *value* contained is ~a~ is copied to set the value
+When defining ~b~, the *value* contained in ~a~ is copied to set the value
 of ~b~. Thus changing ~a~'s value does not impact the variable ~b~.
 
 **** Variables of basic types are mutable
@@ -763,7 +765,7 @@ Here is a table of implicit type conversions *when allowed*.
 | ~R^1~           | ~B~, ~N~, ~Z~, ~R~                                     |
 | ~R^2~           | ~0~ (special value)                              |
 | ~R^3~           | ~0~ (special value)                              |
-| ~R^1x1~         | ~B~, ~N~, ~Z~, ~R~, ~0~ (special value)                  |
+| ~R^1x1~         | ~B~, ~N~, ~Z~, ~R~                                     |
 | ~R^2x2~         | ~0~ (special value)                              |
 | ~R^3x3~         | ~0~ (special value)                              |
 | ~string~        | ~B~, ~N~, ~Z~, ~R~, ~R^1~, ~R^2~, ~R^3~, ~R^1x1~, ~R^2x2~, ~R^3x3~ |
@@ -812,8 +814,8 @@ This cannot happen with ~pugs~. A similar example
 produces the following error
 #+results: no-affectation-result
 
-Actually, affectations are /expressions/ in ~C++~, in ~pugs~ language,
-affectations are /instructions/.
+Actually, affectations are /expressions/ in ~C++~. In ~pugs~, affectations
+are /instructions/.
 
 #+END_note
 
@@ -829,35 +831,35 @@ are sorted by type of left hand side variable.
 
 - ~B~: boolean left hand side variable. One is only allowed to affect boolean
   values.
-  | ~=~ allowed expression type |
-  |---------------------------|
+  | ~B =~ allowed expression type |
+  |-----------------------------|
   | ~B~                           |
 
 - ~N~: natural integer ($\mathbb{N}$ or $\mathbb{Z}_{\ge0}$) left hand side variable.
-  | ~=~ allowed expression type |
-  |---------------------------|
+  | ~N =~ allowed expression type |
+  |-----------------------------|
   | ~B~                           |
   | ~N~                           |
   | ~Z~  (for convenience)        |
 
 - ~Z~: integer ($\mathbb{Z}$) left hand side variable.
-  | ~=~ allowed expression type |
-  |---------------------------|
+  | ~Z =~ allowed expression type |
+  |-----------------------------|
   | ~B~                           |
   | ~N~                           |
   | ~Z~                           |
 
 - ~R~: real ($\mathbb{R}$) left hand side variable.
-  | ~=~ allowed expression type |
-  |---------------------------|
+  | ~R =~ allowed expression type |
+  |-----------------------------|
   | ~B~                           |
   | ~N~                           |
   | ~Z~                           |
   | ~R~                           |
 
 - ~R^1~: vector of dimension 1 ($\mathbb{R}^1$) left hand side variable.
-  | ~=~ allowed expression type |
-  |---------------------------|
+  | ~R^1 =~ allowed expression type |
+  |-------------------------------|
   | ~B~                             |
   | ~N~                             |
   | ~Z~                             |
@@ -865,7 +867,7 @@ are sorted by type of left hand side variable.
   | ~R^1~                           |
 
 - ~R^2~: vector of dimension 2 ($\mathbb{R}^2$) left hand side variable.
-  | ~=~ allowed expression type                   |
+  | ~R^2 =~ allowed expression type               |
   |---------------------------------------------|
   | ~R^2~                                         |
   | ~0~  (special value)                          |
@@ -890,7 +892,7 @@ are sorted by type of left hand side variable.
   #+results: R2-invalid-integer-affectation
 
 - ~R^3~: vector of dimension 3 ($\mathbb{R}^3$) left hand side variable.
-  | ~=~ allowed expression type                   |
+  | ~R^3 =~ allowed expression type               |
   |---------------------------------------------|
   | ~R^3~                                         |
   | ~0~  (special value)                          |
@@ -907,8 +909,8 @@ are sorted by type of left hand side variable.
   #+RESULTS: affectation-to-R3-from-list
 
 - ~R^1x1~: matrix of dimensions $1\times1$ ($\mathbb{R}^{1\times1}$) left hand side variable.
-  | ~=~ allowed expression type |
-  |---------------------------|
+  | ~R^1x1 =~ allowed expression type |
+  |---------------------------------|
   | ~B~                               |
   | ~N~                               |
   | ~Z~                               |
@@ -916,7 +918,7 @@ are sorted by type of left hand side variable.
   | ~R^1x1~                           |
 
 - ~R^2x2~: matrix of dimension $2\times2$ ($\mathbb{R}^{2\times2}$) left hand side variable.
-  | ~=~ allowed expression type                   |
+  | ~R^2x2 =~ allowed expression type             |
   |---------------------------------------------|
   | ~R^2x2~                                       |
   | ~0~  (special value)                          |
@@ -935,7 +937,7 @@ are sorted by type of left hand side variable.
   #+RESULTS: affectation-to-R2x2-from-list
 
 - ~R^3x3~: matrix of dimension $3\times3$ ($\mathbb{R}^{3\times3}$) left hand side variable.
-  | ~=~ allowed expression type                   |
+  | ~R^3x3 =~ allowed expression type             |
   |---------------------------------------------|
   | ~R^3x3~                                       |
   | ~0~  (special value)                          |
@@ -955,8 +957,8 @@ are sorted by type of left hand side variable.
 
 - ~string~ left hand side variable. Expressions of any basic type can be
   used as the right hand side.
-  | ~=~ allowed expression type |
-  |---------------------------|
+  | ~string =~ allowed expression type |
+  |----------------------------------|
   | ~B~                                |
   | ~N~                                |
   | ~Z~                                |
@@ -975,61 +977,61 @@ are sorted by type of left hand side variable.
   variables.
 
 - ~N~: natural integer ($\mathbb{N}$ or $\mathbb{Z}_{\ge0}$) left hand side variable.
-  | ~+=~ allowed expression type |
-  |----------------------------|
+  | ~N +=~ allowed expression type |
+  |------------------------------|
   | ~B~                            |
   | ~N~                            |
   | ~Z~  (for convenience)         |
 
 - ~Z~: integer ($\mathbb{Z}$) left hand side variable.
-  | ~+=~ allowed expression type |
-  |----------------------------|
+  | ~Z +=~ allowed expression type |
+  |------------------------------|
   | ~B~                            |
   | ~N~                            |
   | ~Z~                            |
 
 - ~R~: real ($\mathbb{R}$) left hand side variable.
-  | ~+=~ allowed expression type |
-  |----------------------------|
+  | ~R +=~ allowed expression type |
+  |------------------------------|
   | ~B~                            |
   | ~N~                            |
   | ~Z~                            |
   | ~R~                            |
 
 - ~R^1~: vector of dimension 1 ($\mathbb{R}^1$) left hand side variable.
-  | ~+=~ allowed expression type |
-  |----------------------------|
+  | ~R^1 +=~ allowed expression type |
+  |--------------------------------|
   | ~R^1~                            |
 
 - ~R^2~: vector of dimension 2 ($\mathbb{R}^2$) left hand side variable.
-  | ~+=~ allowed expression type |
-  |----------------------------|
+  | ~R^2 +=~ allowed expression type |
+  |--------------------------------|
   | ~R^2~                            |
 
 - ~R^3~: vector of dimension 3 ($\mathbb{R}^3$) left hand side variable.
-  | ~+=~ allowed expression type |
-  |----------------------------|
+  | ~R^3 +=~ allowed expression type |
+  |--------------------------------|
   | ~R^3~                            |
 
 - ~R^1x1~: matrix of dimensions $1\times1$ ($\mathbb{R}^{1\times1}$) left hand side variable.
-  | ~+=~ allowed expression type |
-  |----------------------------|
+  | ~R^1x1 +=~ allowed expression type |
+  |----------------------------------|
   | ~R^1x1~                            |
 
 - ~R^2x2~: matrix of dimension $2\times2$ ($\mathbb{R}^{2\times2}$) left hand side variable.
-  | ~+=~ allowed expression type |
-  |----------------------------|
+  | ~R^2x2 +=~ allowed expression type |
+  |----------------------------------|
   | ~R^2x2~                            |
 
 - ~R^3x3~: matrix of dimension $3\times3$ ($\mathbb{R}^{3\times3}$) left hand side variable.
-  | ~+=~ allowed expression type |
-  |----------------------------|
+  | ~R^3x3 +=~ allowed expression type |
+  |----------------------------------|
   | ~R^3x3~                            |
 
 - ~string~ left hand side variable. Expressions of any basic type can be
   used as the right hand side.
-  | ~+=~ allowed expression type |
-  |----------------------------|
+  | ~string +=~ allowed expression type |
+  |-----------------------------------|
   | ~B~                                 |
   | ~N~                                 |
   | ~Z~                                 |
@@ -1047,55 +1049,55 @@ are sorted by type of left hand side variable.
 - ~B~: the ~-=~ operator is not defined for left hand side boolean variables.
 
 - ~N~: natural integer ($\mathbb{N}$ or $\mathbb{Z}_{\ge0}$) left hand side variable.
-  | ~-=~ allowed expression type |
-  |----------------------------|
+  | ~N -=~ allowed expression type |
+  |------------------------------|
   | ~B~                            |
   | ~N~                            |
   | ~Z~  (for convenience)         |
 
 - ~Z~: integer ($\mathbb{Z}$) left hand side variable.
-  | ~-=~ allowed expression type |
-  |----------------------------|
+  | ~Z -=~ allowed expression type |
+  |------------------------------|
   | ~B~                            |
   | ~N~                            |
   | ~Z~                            |
 
 - ~R~: real ($\mathbb{R}$) left hand side variable.
-  | ~-=~ allowed expression type |
-  |----------------------------|
+  | ~R -=~ allowed expression type |
+  |------------------------------|
   | ~B~                            |
   | ~N~                            |
   | ~Z~                            |
   | ~R~                            |
 
 - ~R^1~: vector of dimension 1 ($\mathbb{R}^1$) left hand side variable.
-  | ~-=~ allowed expression type |
-  |----------------------------|
+  | ~R^1 -=~ allowed expression type |
+  |--------------------------------|
   | ~R^1~                            |
 
 - ~R^2~: vector of dimension 2 ($\mathbb{R}^2$) left hand side variable.
-  | ~-=~ allowed expression type |
-  |----------------------------|
+  | ~R^2 -=~ allowed expression type |
+  |--------------------------------|
   | ~R^2~                            |
 
 - ~R^3~: vector of dimension 3 ($\mathbb{R}^3$) left hand side variable.
-  | ~-=~ allowed expression type |
-  |----------------------------|
+  | ~R^3 -=~ allowed expression type |
+  |--------------------------------|
   | ~R^3~                            |
 
 - ~R^1x1~: matrix of dimensions $1\times1$ ($\mathbb{R}^{1\times1}$) left hand side variable.
-  | ~-=~ allowed expression type |
-  |----------------------------|
+  | ~R^1x1 -=~ allowed expression type |
+  |----------------------------------|
   | ~R^1x1~                            |
 
 - ~R^2x2~: matrix of dimension $2\times2$ ($\mathbb{R}^{2\times2}$) left hand side variable.
-  | ~-=~ allowed expression type |
-  |----------------------------|
+  | ~R^2x2 -=~ allowed expression type |
+  |----------------------------------|
   | ~R^2x2~                            |
 
 - ~R^3x3~: matrix of dimension $3\times3$ ($\mathbb{R}^{3\times3}$) left hand side variable.
-  | ~-=~ allowed expression type |
-  |----------------------------|
+  | ~R^3x3 -=~ allowed expression type |
+  |----------------------------------|
   | ~R^3x3~                            |
 
 - ~string~: the ~-=~ operator is not defined for left hand side string variables.
@@ -1105,70 +1107,70 @@ are sorted by type of left hand side variable.
 - ~B~: the ~*=~ operator is not defined for left hand side boolean variables.
 
 - ~N~: natural integer ($\mathbb{N}$ or $\mathbb{Z}_{\ge0}$) left hand side variable.
-  | ~*=~ allowed expression type |
-  |----------------------------|
+  | ~N *=~ allowed expression type |
+  |------------------------------|
   | ~B~                            |
   | ~N~                            |
   | ~Z~  (for convenience)         |
 
 - ~Z~: integer ($\mathbb{Z}$) left hand side variable.
-  | ~*=~ allowed expression type |
-  |----------------------------|
+  | ~Z *=~ allowed expression type |
+  |------------------------------|
   | ~B~                            |
   | ~N~                            |
   | ~Z~                            |
 
 - ~R~: real ($\mathbb{R}$) left hand side variable.
-  | ~*=~ allowed expression type |
-  |----------------------------|
+  | ~R *=~ allowed expression type |
+  |------------------------------|
   | ~B~                            |
   | ~N~                            |
   | ~Z~                            |
   | ~R~                            |
 
 - ~R^1~: vector of dimension 1 ($\mathbb{R}^1$) left hand side variable.
-  | ~*=~ allowed expression type |
-  |----------------------------|
+  | ~R^1 *=~ allowed expression type |
+  |--------------------------------|
   | ~B~                              |
   | ~N~                              |
   | ~Z~                              |
   | ~R~                              |
 
 - ~R^2~: vector of dimension 2 ($\mathbb{R}^2$) left hand side variable.
-  | ~*=~ allowed expression type |
-  |----------------------------|
+  | ~R^2 *=~ allowed expression type |
+  |--------------------------------|
   | ~B~                              |
   | ~N~                              |
   | ~Z~                              |
   | ~R~                              |
 
 - ~R^3~: vector of dimension 3 ($\mathbb{R}^3$) left hand side variable.
-  | ~*=~ allowed expression type |
-  |----------------------------|
+  | ~R^3 *=~ allowed expression type |
+  |--------------------------------|
   | ~B~                              |
   | ~N~                              |
   | ~Z~                              |
   | ~R~                              |
 
 - ~R^1x1~: matrix of dimensions $1\times1$ ($\mathbb{R}^{1\times1}$) left hand side variable.
-  | ~*=~ allowed expression type |
-  |----------------------------|
+  | ~R^1x1 *=~ allowed expression type |
+  |----------------------------------|
   | ~B~                                |
   | ~N~                                |
   | ~Z~                                |
   | ~R~                                |
 
 - ~R^2x2~: matrix of dimension $2\times2$ ($\mathbb{R}^{2\times2}$) left hand side variable.
-  | ~*=~ allowed expression type |
-  |----------------------------|
+  | ~R^2x2 *=~ allowed expression type |
+  |----------------------------------|
   | ~B~                                |
   | ~N~                                |
   | ~Z~                                |
   | ~R~                                |
 
 - ~R^3x3~: matrix of dimension $3\times3$ ($\mathbb{R}^{3\times3}$) left hand side variable.
-  | ~*=~ allowed expression type |
-  |----------------------------|
+  | ~R^3x3 *=~ allowed expression type |
+  |----------------------------------|
   | ~B~                                |
   | ~N~                                |
   | ~Z~                                |
@@ -1176,9 +1178,10 @@ are sorted by type of left hand side variable.
 
 #+BEGIN_note
 Observe that for these small matrix types ($\mathbb{R}^{d\times d}$) the
-construction ~A *= B;~ is not allowed. The main reason for that is that
-for $d>1$ this operation has no interests since it requires a
-temporary. One will see bellow that one can write ~A = A*B;~ if needed.
+construction ~A *= B;~ where ~B~ is a matrix of the same type as ~A~ is not
+allowed. The main reason for that is that for $d>1$ this operation has
+no interests since it requires a temporary. One will see bellow that
+it is possible to write ~A = A*B;~ if needed.
 #+END_note
 
 - ~string~: the ~*=~ operator is not defined for left hand side string variables.
@@ -1188,20 +1191,20 @@ temporary. One will see bellow that one can write ~A = A*B;~ if needed.
 - ~B~: the ~/=~ operator is not defined for left hand side boolean variables.
 
 - ~N~: natural integer ($\mathbb{N}$ or $\mathbb{Z}_{\ge0}$) left hand side variable.
-  | ~/=~ allowed expression type |
-  |----------------------------|
+  | ~N /=~ allowed expression type |
+  |------------------------------|
   | ~N~                            |
   | ~Z~  (for convenience)         |
 
 - ~Z~: integer ($\mathbb{Z}$) left hand side variable.
-  | ~/=~ allowed expression type |
-  |----------------------------|
+  | ~Z /=~ allowed expression type |
+  |------------------------------|
   | ~N~                            |
   | ~Z~                            |
 
 - ~R~: real ($\mathbb{R}$) left hand side variable.
-  | ~/=~ allowed expression type |
-  |----------------------------|
+  | ~R /=~ allowed expression type |
+  |------------------------------|
   | ~N~                            |
   | ~Z~                            |
   | ~R~                            |
@@ -1228,7 +1231,7 @@ The ~pugs~ language allows the following tokens as unary operators
 
 The ~not~, ~+~ and ~-~ operators apply to the *expression* on their right. ~++~
 and ~--~ operators apply only to a *variable* that can be positioned
-before (post increment/decrement) or after the token (pre
+before (pre increment/decrement) or after the token (post
 increment/decrement). These operators are also inspired from their ~C++~
 counterparts for commodity.
 
@@ -1237,8 +1240,8 @@ parsing the script.
 
 For basic types, when the operators ~not~, ~+~, ~-~, ~++~ or ~--~ are defined,
 they return a value of the same type as the argument (except for the
-operator ~-~ if the argument is a ~N~, then the result is a ~Z~). These
-operators can be defined for high-level types.
+operator ~-~ if the argument is a ~B~ or a ~N~, then the result is a
+~Z~). These operators can be defined for high-level types.
 - The ~not~ operator is only defined for boolean values (~B~).
 - The ~-~ unary operator is defined for numeric basic types: ~B~,
   ~N~, ~Z~, ~R~, ~R^1~, ~R^2~, ~R^3~, ~R^1x1~, ~R^2x2~ and ~R^3x3~. It is not defined
@@ -1282,7 +1285,7 @@ This code produces
 
 **** Binary operators
 
-Syntax for binary operators follows again a classical structure if
+Syntax for binary operators follows again a classical structure: if
 ~exp1~ and ~exp2~ denotes two expressions and if ~op~ denotes a binary
 operator, one simply writes ~exp1 op exp2~.
 
@@ -1657,7 +1660,7 @@ In this example, we are dealing with 3 ~mesh~ variables.
 
 *** Compound types
 
-The ~pugs~ language allow to deal with compound types. The idea is to
+The ~pugs~ language allows to deal with compound types. The idea is to
 define a list of variables as a member of a product space (each
 variable belongs to one of them, each variable has a simple type:
 basic or high-level).
@@ -1813,9 +1816,9 @@ The ~pugs~ language supports classical statements to control the data
 flow. For simplicity, these statements syntax follow their ~C++~
 counterpart. The only statement that is not implemented in ~pugs~ is the
 ~switch...case~. This may change but in the one hand, up to now it was
-never necessary (we did not use chained ~if...else~ statements), and on
-the other hand, keeping the language as simple as possible remains the
-policy in ~pugs~ development.
+never necessary (up to now, we did not encountered the need to chain
+~if...else~ statements), and on the other hand, keeping the language as
+simple as possible remains the policy in ~pugs~ development.
 
 *** ~if...else~ statement
 
@@ -1894,8 +1897,9 @@ We give a final illustration
   for (declarationinstruction ; condition ; postinstruction) statement
 #+END_SRC
 Following ~C++~, ~declarationinstruction~, ~condition~ and ~postinstruction~
-are optional. The ~condition~ argument if present *must* be a boolean
-value (type ~B~), if it is absent, the default value ~true~ is used.
+are optional. The ~condition~ argument, if it is present, *must* be a
+boolean value (type ~B~). If it is absent, the default value ~true~ is
+used.
 
 - The ~declarationinstruction~ is execute only *once* /before/ the beginning
   of the loop. The lifetime of the variable declared here is defined
@@ -1923,7 +1927,7 @@ which gives as expected
 #+results: for-block
 
 The lifetime of the declared variable (in the ~declarationinstruction~
-statement) is illustrate by the following example
+statement) is illustrated by the following example
 #+NAME: for-scope-error
 #+BEGIN_SRC pugs-error :exports both :results output
   for (let i:N, i=0; i<2; ++i) {
@@ -2043,7 +2047,7 @@ Obviously the behavior is the same using ~do...while~ or ~while~ loops.
 
 ** Functions<<functions>>
 
-The ~pugs~ language allow the manipulation and definition of
+The ~pugs~ language allows the manipulation and definition of
 functions. These are *mathematical functions* and are not functions as
 functions in ~C++~: functions in the ~pugs~ language are *not subroutines*.
 
@@ -2052,11 +2056,10 @@ To be more precise, a function $f$ follows the following structure
     \mbox{let }f:& X_1\times \cdots \times X_n \to Y_1\times \cdots \times Y_m,\\
                  & (x_1,\ldots,x_n)\mapsto (y_1,\ldots,y_m)=f(x_1,\ldots,x_n),
 \end{align*}
-where $n,m\in\mathbb{N}_{\ge1}$, and where ${(X_i)}_{0\le i\le n}$ and ${(Y_i)}_{0\le
+where $n,m\in\mathbb{N}_{\ge1}$, and where ${(X_i)}_{1\le i\le n}$ and ${(Y_i)}_{1\le
 i\le m}$ are /simple/ types. Actually $X_1\times \cdots \times X_n$ and
 $Y_1\times \cdots \times Y_m$ are /compound/ types.
 
-
 Thus assuming that the function $f$ is defined in the language as ~f~,
 one can use the following syntax to evaluate it. This is a
 pseudo-code, real examples will follow. Assuming that ~(x1...,xn)~ has
@@ -2064,7 +2067,7 @@ been properly defined in ~X1*...*Xn~ one can write
 #+BEGIN_SRC pugs :exports code
   let (y1,...,ym):Y1*...*Ym, (y1,...,ym) = f(x1,...,xn);
 #+END_SRC
-or if ~(y1,...,ym)~ has already been defined in  ~Y1*...*Ym~
+or if ~(y1,...,ym)~ has already been declared in  ~Y1*...*Ym~
 #+BEGIN_SRC pugs :exports code
   (y1,...,ym) = f(x1,...,xn);
 #+END_SRC
@@ -2078,8 +2081,8 @@ modify a function.
 *** Pure functions
 
 In the ~pugs~ language, functions are *pure functions* in the sense that
-arguments given to the function are *never* modified by the
-functions. They act as operators.
+arguments given to a function are *never* modified by the function. They
+act as operators.
 
 #+BEGIN_note
 Actually these functions are not strictly /pure functions/ in the
@@ -2093,8 +2096,8 @@ of the language itself but the internal random seed.
 
 As already said, in general, there is no implicit type conversion in
 the ~pugs~ language. The only exceptions are when initializing tuples
-(see [[tuples]]) and for functions arguments and returned values.  See the
-conversion table in section [[implicit-conversion]].
+(see [[tuples]]), passing arguments to functions and dealing with returned
+values. See the conversion table in section [[implicit-conversion]].
 
 *** User-defined functions<<user-defined-functions>>