Clarify tutorial based on feedback, fix some Markdown errors

Author: marijnh

doc/tutorial/control.md

@@ -94,8 +94,9 @@ extract the fields from a tuple:
 This will introduce two new variables, `a` and `b`, bound to the
 content of the tuple.
 
-You may only use irrevocable patterns in let bindings, though. Things
-like literals, which only match a specific value, are not allowed.
+You may only use irrevocable patterns—patterns that can never fail to
+match—in let bindings, though. Things like literals, which only match
+a specific value, are not allowed.
 
 ## Loops
 
@@ -114,6 +115,13 @@ to abort the current iteration and continue with the next.
 This code prints out a weird sequence of numbers and stops as soon as
 it finds one that can be divided by five.
 
+There's also `while`'s ugly cousin, `do`/`while`, which does not check
+its condition on the first iteration, using traditional syntax:
+
+    do {
+        eat_cake();
+    } while any_cake_left();
+
 When iterating over a vector, use `for` instead.
 
     for elt in ["red", "green", "blue"] {
@@ -167,3 +175,14 @@ leave them in.
 
 For interactive debugging, you often want unconditional logging. For
 this, use `log_err` instead of `log` [FIXME better name].
+
+## Assertions
+
+The keyword `assert`, followed by an expression with boolean type,
+will check that the given expression results in `true`, and cause a
+failure otherwise. It is typically used to double-check things that
+*should* hold at a certain point in a program.
+
+    let x = 100;
+    while (x > 10) { x -= 10; }
+    assert x == 10;

doc/tutorial/data.md

@@ -33,7 +33,9 @@ error.
 To 'update' an immutable record, you use functional record update
 syntax, by ending a record literal with the keyword `with`:
 
+    let oldpoint = {x: 10f, y: 20f};
     let newpoint = {x: 0f with oldpoint};
+    assert newpoint == {x: 0f, y: 20f};
 
 This will create a new struct, copying all the fields from `oldpoint`
 into it, except for the ones that are explicitly set in the literal.

doc/tutorial/setup.md

@@ -36,7 +36,9 @@ FIXME say something about libs, main, modules, use
 
 There are Vim highlighting and indentation scrips in the Rust source
 distribution under `src/etc/vim/`. An Emacs mode can be found at
-`[https://github.com/marijnh/rust-mode](https://github.com/marijnh/rust-mode)`.
+[https://github.com/marijnh/rust-mode][rust-mode].
+
+[rust-mode]: https://github.com/marijnh/rust-mode
 
 Other editors are not provided for yet. If you end up writing a Rust
 mode for your favorite editor, let us know so that we can link to it.

doc/tutorial/syntax.md

@@ -37,9 +37,9 @@ like `if` and `while` are available:
 
 Though it isn't apparent in most everyday code, there is a fundamental
 difference between Rust's syntax and the predecessors in this family
-of languages. Almost everything in rust is an expression, even things
-that are statements in other languages. This allows for useless things
-like this (which passes nil—the void type—to a function):
+of languages. A lot of thing that are statements in C are expressions
+in Rust. This allows for useless things like this (which passes
+nil—the void type—to a function):
 
     a_function(while false {});
 
@@ -62,11 +62,14 @@ This also works for function bodies. This function returns a boolean:
 
     fn is_four(x: int) -> bool { x == 4 }
 
-If everything is an expression, you might conclude that you have to
-add a terminating semicolon after *every* statement, even ones that
+In short, everything that's not a declaration (`let` for variables,
+`fn` for functions, etcetera) is an expression.
+
+If all those things are expressions, you might conclude that you have
+to add a terminating semicolon after *every* statement, even ones that
 are not traditionally terminated with a semicolon in C (like `while`).
-That is not the case, though. Statements that end in a block only need
-a semicolon if that block contains a trailing expression. `while`
+That is not the case, though. Expressions that end in a block only
+need a semicolon if that block contains a trailing expression. `while`
 loops do not allow trailing expressions, and `if` statements tend to
 only have a trailing expression when you want to use their value for
 something—in which case you'll have embedded it in a bigger statement,
@@ -166,7 +169,7 @@ Integers can be written in decimal (`144`), hexadecimal (`0x90`), and
 binary (`0b10010000`) base. Without suffix, an integer literal is
 considered to be of type `int`. Add a `u` (`144u`) to make it a `uint`
 instead. Literals of the fixed-size integer types can be created by
-the literal with the type name (`i8`, `u64`, etc).
+the literal with the type name (`255u8`, `50i64`, etc).
 
 Note that, in Rust, no implicit conversion between integer types
 happens. If you are adding one to a variable of type `uint`, you must
@@ -188,12 +191,16 @@ character escapes, using the backslash character:
 
 `\n`
 : A newline (unicode character 32).
+
 `\r`
 : A carriage return (13).
+
 `\t`
 : A tab character (9).
+
 `\\`, `\'`, `\"`
 : Simply escapes the following character.
+
 `\xHH`, `\uHHHH`, `\UHHHHHHHH`
 : Unicode escapes, where the `H` characters are the hexadecimal digits that form the character code.