1 files changed, 28 insertions, 0 deletions
diff --git a/doc/manual.txt b/doc/manual.txt
index 3437e3e44..2cbf50f2c 100644
--- a/doc/manual.txt
+++ b/doc/manual.txt
@@ -25,6 +25,9 @@ The language constructs are explained using an extended BNF, in
 which ``(a)*`` means 0 or more ``a``'s, ``a+`` means 1 or more ``a``'s, and
 ``(a)?`` means an optional *a*. Parentheses may be used to group elements.
 
+``&`` is the lookahead operator; ``&a`` means that an ``a`` is expected but
+not consumed. It will be consumed in the following rule.
+
 The ``|``, ``/`` symbols are used to mark alternatives and have the lowest 
 precedence. ``/`` is the ordered choice that requires the parser to try the 
 alternatives in the given order. ``/`` is often used to ensure the grammar
@@ -1726,6 +1729,17 @@ contain other statements. To avoid the `dangling else problem`:idx:, complex
 statements always have to be intended. The details can be found in the grammar.
 
 
+Statement list expression
+-------------------------
+
+Statements can also occur in an expression context that looks 
+like ``(stmt1; stmt2; ...; ex)``. This is called
+an `statement list expression`:idx: or ``(;)``. The type 
+of ``(stmt1; stmt2; ...; ex)`` is the type of ``ex``. All the other statements
+must be of type ``void``. (One can use ``discard`` to produce a ``void`` type.)
+``(;)`` does not introduce a new scope.
+
+
 Discard statement
 -----------------
 
@@ -1892,6 +1906,20 @@ the ``:`` are executed. This goes on until the last ``elif``. If all
 conditions fail, the ``else`` part is executed. If there is no ``else``
 part, execution continues with the statement after the ``if`` statement.
 
+The scoping for an ``if`` statement is slightly subtle to support an important 
+use case. A new scope starts for the ``if``/``elif`` condition and ends after
+the corresponding *then* block:
+
+.. code-block:: nimrod
+  if {| (let m = input =~ re"(\w+)=\w+"; m.isMatch):
+    echo "key ", m[0], " value ", m[1]  |}
+  elif {| (let m = input =~ re""; m.isMatch):
+    echo "new m in this scope" |}
+  else:
+    # 'm' not declared here
+
+In the example the scopes have been enclosed in ``{|  |}``.
+
 
 Case statement
 --------------