Forward reference computation section (#1044)

Resolves effekt-lang/effekt-website#116

Author: dvdvgt

examples/tour/computation.effekt.md

@@ -1,20 +1,20 @@
 ---
-title: Computation
+title: Computations
 permalink: tour/computation
 ---
 
-# Computation
+# Computations
 
-## Values vs. Computation
+## Values vs. Computations
 
-Following Paul Levy's [Call-By-Push-Value](https://www.cs.bham.ac.uk/~pbl/papers/thesisqmwphd.pdf), Effekt distinguishes between **values** (such as `42`, `true`, or instances of datatypes) and **computation**.
+Following Paul Levy's [Call-By-Push-Value](https://www.cs.bham.ac.uk/~pbl/papers/thesisqmwphd.pdf), Effekt distinguishes between **values** (such as `42`, `true`, or instances of datatypes) and **computations**.
 
-Examples of "computation" in Effekt are:
+Examples of "computations" in Effekt are:
 - blocks (this is what we call functions),
 - instances of interfaces (also known as "objects"), and
 - regions
 
-Functions (and all other computation types) are _second-class_ in Effekt. To make this difference explicit, we pass values in parentheses (e.g. `f(42)`) and computation in braces (e.g. `f { x => println(x) }`).
+Functions (and all other computation types) are _second-class_ in Effekt. To make this difference explicit, we pass values in parentheses (e.g. `f(42)`) and computations in braces (e.g. `f { x => println(x) }`).
 
 ```
 def myMap[A, B](xs: List[A]) { f: A => B }: List[B] =
@@ -58,7 +58,7 @@ The effects used in the passed block thus need to be handled exactly where the b
 
 ## Comparison
 
-|   | Values (First-class) | Computation (Second-class) |
+|   | Values (First-class) | Computations (Second-class) |
 |---|:---|---:|
 | Term-level | `42`, `"hello"`, `true`, `Cons(1, Nil)`, `box { [A](x: A) => x }` ... | `{ [A](x: A) => x }`, `new Exception`, `region r`, `unbox exc`  |
 | | Literals, instances of datatypes and boxed computations | Blocks, objects and regions |

examples/tour/effect-handlers.effekt.md

@@ -111,6 +111,7 @@ genFibs(15).foreach { x => println(x) }
 ## Singleton operation
 
 Often, we want to declare an interface that is entirely defined by just one operation (like a "single-abstract-method" in Java). In this case, you can declare it as a singleton operation:
+
 ```
 effect tell(): Int
 ```
@@ -127,6 +128,11 @@ def tellTime[A] { prog: () => A / tell }: A =
   }
 ```
 
+Here, `prog` is expected to be passed a computation (block) and not as a value.
+You can read more about their distinction in the section about [computations](computation).
+
+Using the function `tellTime` that _handles_ the effect `tell` of `prog`, we can write the following program for measuring the execution time for computing the first 1500 Fibonacci Numbers:
+
 ```effekt:repl
 tellTime {
   val start = do tell()
@@ -137,8 +143,10 @@ tellTime {
 ```
 
 ## `with` handler
+
 We can decompose `genFibs` into a more general helper function `collect` that collects the
 yielded values by abstracting over the generating program:
+
 ```
 def collect[A](n: Int) { prog: () => Unit / Yield[A] }: List[A] = {
   var yielded: List[A] = []
@@ -156,7 +164,9 @@ def collect[A](n: Int) { prog: () => Unit / Yield[A] }: List[A] = {
   yielded
 }
 ```
+
 Let us define another handler for `Yield` to filter values:
+
 ```
 def filter[A] { keep: A => Bool } { prog: () => Unit / Yield[A] }: Unit / Yield[A] =
   try prog()
@@ -166,6 +176,7 @@ def filter[A] { keep: A => Bool } { prog: () => Unit / Yield[A] }: Unit / Yield[
 ```
 
 We can avoid the nesting of higher-order function calls like `collect[Int](limit) { filter { x => x.mod(2) == 0 } { fib() } }` and write:
+
 ```
 def evenFibs(limit: Int): List[Int] = {
   with collect(limit)
@@ -174,8 +185,6 @@ def evenFibs(limit: Int): List[Int] = {
 }
 ```
 
-
-
 ```effekt:repl
 evenFibs(15).foreach { x => println(x) }
 ```

examples/tour/functions.effekt.md

@@ -28,6 +28,7 @@ Perhaps unusual, you can also call `fib` using Effekt's implementation of [Unifo
 ```effekt:repl
 5.fib()
 ```
+
 Here, the receiver (before the `.`) is simply passed as the first argument to the function `fib`. If there are no additional arguments, you can also omit the parenthesis:
 
 ```effekt:repl
@@ -68,3 +69,7 @@ def odd(n: Int): Bool = if (n <= 0) false else even(n - 1)
 ```effekt:repl
 7.even
 ```
+
+Of course, it is also possible to implement higher-order functions in Effekt.
+However, we distinguish between first-class values and second-class computations.
+You can read more about this in the section about [computations](computation).