More from the wiki.

README.md

@@ -107,3 +107,122 @@ These are quite flexible, for example:
       bytes = bytes + 1
     endwhile
 
+### Simple Subroutine Declaration
+
+EightBall allows named subroutines to be defined, for example:
+
+    sub myFirstSubroutine()
+      pr.msg "Hello"; pr.nl
+    endsub
+
+All subroutines must end with `endsub` statement.
+
+A subroutine may have more than one `return` statement returning a numeric value:
+
+    sub mySecondSubroutine()
+      return 2
+    endsub
+
+If the flow of execution hits the `endsub` then 0 is returned to the caller.
+
+### Simple Subroutine Invocation
+
+The subroutine above can be called as follows:
+
+    call myFirstSubroutine()
+
+When `myFirstSubroutine` hits a `return` statement, the flow of execution will return to the statement immediately following the `call`.
+
+### Local Variables
+
+Each subroutine has its own local variable scope.  If a local variable is declared with the same name as a global variable, the global will not be available within the scope of the subroutine.  When the subroutine returns, the local variables are destroyed.
+
+    sub myThirdSubroutine()
+      word w[10] = 0;  ' Local array
+    endsub
+
+### Argument Passing
+
+Subroutines may take `byte` or `word` arguments, using the following syntax:
+
+    sub withArgs(byte flag, word val1, word val2)
+      ' Do stuff
+      return 0
+    endsub
+
+This could be called as follows:
+
+    word ww = 0; byte b = 0;
+    call withArgs(b, ww, ww+10)
+
+When `withArgs` runs, the expression passed as the first argument (`b`) will be evaluated and the value assigned to the first formal argument `flag`, which will be created in the subroutine's local scope.  Similarly, the second argument (`ww`) will be evaluated and the result assigned to `val1`. Finally, `ww+10` will be evaluated and assigned to `val2`.
+
+Argument passing is by value, which means that `withArgs` can modify `flag`, `val1` or `val2` freely without the changes being visible to the caller.
+
+### Function Invocation
+
+Subroutines may be invoked within an expression.  For example, the following subroutine:
+
+    sub adder(word a, word b)
+      return a+b
+    endsub
+
+Could be used in an expression like this:
+
+    pr.dec adder(10, 5); ' Prints 15
+
+Functions may invoke themselves recursively (but you will run out of stack quite fast!)
+
+### Passing by Reference
+
+Passing by reference allows a subroutine to modify a value passed to it.  EightBall does this using pointers, in a manner that will be familiar to C programmers.  Here is `adder` implemented using this pattern:
+
+    sub adder(word a, word b, word resptr)
+      *resptr = a+b
+    endsub
+
+Then to call it:
+
+    word result
+    call adder(10, 20, &result)
+
+This code takes the address of variable `result` using the ampersand operator and passes it to subroutine `adder` as `resptr`.  The subroutine then uses the star operator to write the result of the addition of the first two arguments (10 + 20 in this example) to the word pointed to by `resptr`.
+
+Unlike C, there are no special pointer types.  Pointers must be stored in a `word` variable, since they do not fit in a `byte`.
+
+### Passing an Array by Reference
+
+**Warning: This is currently not implemented in the compiler, only the interpreter.**
+
+It is frequently useful to pass an array into a subroutine.  It is not very useful to use pass by value for arrays, since this may mean copying a large object onto the stack.  For these reasons, EightBall implements a special pass by reference mode for array variables, which operates in a manner similar to C.
+
+Here is an example of a function which takes a regular variable and an array:
+
+    sub clearArray(byte arr[], word sz)
+      word i = 0
+      for i = 0 : sz-1
+        arr[i] = 0
+      endfor
+    endsub
+
+This may be invoked like this:
+
+    word n = 10
+    byte A[n] = 99
+    call clearArray(A, n)
+
+Note that the size of the array is not specified in the subroutine definition - any size array may be passed.  Note also that the corresponding argument in the `call` is simply the array name (no [] or other annotation is permitted.)
+
+This mechanism effectively passes a pointer to the array contents 'behind the scenes'.
+
+### End Statement
+The `end` statement marks the normal end of execution.  This is often used to stop the flow of execution running off the end of the main program and into the subroutines (which causes an error):
+
+    call foo()
+    pr.msg "Done!"; pr.nl
+    end
+    sub foo()
+      pr.msg "foo"; pr.nl
+    endsub
+
+