Update page 'P# 1.0 Draft Specification'

P%23-1.0-Draft-Specification.md

@@ -260,6 +260,42 @@ An example:
         int $integer = 7 + (int) $str; // contains value: 52
     %>
 
+### 5.14. References
+References in P# are a means to access the same variable content by different names. They are not like C pointers; for instance, they does not allow to perform pointer arithmetic using them, they are not actual memory addresses, and so on. Instead, they are symbol table aliases. There are three basic operations performed using references: assigning by reference, passing by reference, and returning by reference.
+
+#### 5.14.1. Assign By Reference
+In the first of these, P# references allow to make two variables refer to the same content.
+
+    <%
+        int &$a, $b;
+        $a = $b;
+    %>
+
+It means that $a and $b point to the same content.
+
+#### 5.14.2. Return Reference
+When a function returns a reference, it returns an implicit pointer to its return value. This way, a function can be used on the left side of an assignment statement.
+
+    <%
+        int $table[] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 0};
+
+        int &refFunc(int $i) {
+            return $table[$i];  // returns a reference to the ith element
+        }
+    %>
+
+#### 5.14.3. Pass By Reference
+This is done by making a local variable in a function and a variable in the calling scope referencing the same content.
+
+    <%
+        int func(int &$val) {
+            $val++;
+        }
+        int $var = 5;
+        func($var);
+        print("\$var = $var"); // outputs "$var = 6"
+    %>
+
 ## 6. Operators
 Expressions are constructed from operands and operators. The operators of an expression indicate which operations to apply to the operands. There are three kinds of operators:
  * Unary operators -  the unary operators take one operand and use either prefix notation (such as –$x) or