Restructure the book, normalize style, clean example outputs

.gitignore

@@ -1 +1,2 @@
+bin/*
 stage/*

Makefile

@@ -2,33 +2,41 @@ GITBOOK = gitbook
 RUSTC = rustc
 QUIET = -A unused-variable -A dead-code -A dead-assignment -A experimental
 RUSTC_NT = $(RUSTC) --no-trans --test $(QUIET)
-WHITELIST = examples/borrow/freeze.rs \
-						examples/attribute/custom.rs \
-						examples/crates/executable.rs \
-						examples/lifetime/lifetime.rs \
-						examples/lifetime/reference-bad.rs \
-						examples/mod/nested.rs \
-						examples/move/assignment.rs \
-						examples/move/pass-by-value.rs \
-						examples/variables/declare.rs \
-            examples/variables/variables.rs
+WHITELIST = examples/attribute/cfg/custom/custom.rs \
+						examples/borrow/borrow.rs \
+	 					examples/borrow/freeze/freeze.rs \
+	 					examples/borrow/mut/mut.rs \
+	 					examples/bounds/bounds.rs \
+	 					examples/constants/constants.rs \
+	 					examples/crates/link/executable.rs \
+	 					examples/lifetime/lifetime.rs \
+	 					examples/mod/mod.rs \
+	 					examples/print/print.rs \
+	 					examples/type/cast/cast.rs \
+	 					examples/type/type.rs \
+	 					examples/variables/declare/declare.rs \
+	 					examples/variables/mut/mut.rs \
+	 					examples/variables/scope/scope.rs \
+	 					examples/vec/vec.rs \
+						temporary-whitelist-below-this-point-remove-later \
+						examples/lifetime/reference-bad.rs
+
 srcs = $(filter-out $(WHITELIST),$(shell find examples -name '*.rs'))
 
 .PHONY: all book clean test serve
 
 all:
 	./setup-stage.sh
-	$(RUSTC) src/update.rs
-	./update
-	rm update
+	$(RUSTC) src/update.rs --out-dir bin
+	bin/update
 
 book:
 	cd stage && $(GITBOOK) build
 	./fix-edit-button.sh
 	./add-relinks.sh
 
 clean:
-	rm -rf stage
+	rm -rf {bin,stage}
 
 test:
 	$(foreach src,$(srcs),$(RUSTC_NT) $(src) || exit;)

examples/array/array.rs

@@ -1,4 +1,4 @@
-use std::mem::size_of_val;
+use std::mem;
 
 // This function borrows a slice
 fn analyze_slice(slice: &[int]) {
@@ -7,27 +7,27 @@ fn analyze_slice(slice: &[int]) {
 }
 
 fn main() {
-    // fixed-size array (type signature is superfluous)
+    // Fixed-size array (type signature is superfluous)
     let xs: [int, ..5] = [1, 2, 3, 4, 5];
 
-    // indexing starts at 0
+    // Indexing starts at 0
     println!("first element of the array: {}", xs[0]);
     println!("second element of the array: {}", xs[1]);
 
-    // len() returns the size of the array
+    // `len` returns the size of the array
     println!("array size: {}", xs.len());
 
-    // arrays are stack allocated
-    println!("array occupies {} bytes", size_of_val(&xs));
+    // Arrays are stack allocated
+    println!("array occupies {} bytes", mem::size_of_val(&xs));
 
-    // arrays can be automatically borrowed as slices
+    // Arrays can be automatically borrowed as slices
     println!("borrow the whole array as a slice");
     analyze_slice(xs);
 
-    // slices can point to a section of an array
+    // Slices can point to a section of an array
     println!("borrow a section of the array as a slice");
     analyze_slice(xs.slice(1, 4));
 
-    // out of bound indexing yields a runtime failure
+    // Out of bound indexing yields a task failure
     println!("{}", xs[5]);
 }

examples/attribute/conditional.rs → examples/attribute/cfg/cfg.rs

@@ -1,10 +1,10 @@
-// this function only gets compiled if the target OS is linux
+// This function only gets compiled if the target OS is linux
 #[cfg(target_os = "linux")]
 fn are_you_on_linux() {
     println!("You are running linux!")
 }
 
-// this function only gets compiled if the target OS is *not* linux
+// And this function only gets compiled if the target OS is *not* linux
 #[cfg(not(target_os = "linux"))]
 fn are_you_on_linux() {
     println!("You are *not* running linux!")

examples/attribute/cfg/custom/input.md

@@ -0,0 +1,15 @@
+Some conditionals like `target_os` are implicitly provided by `rustc`, but
+custom conditionals must be passed to `rustc` using the `--cfg` flag.
+
+{custom.rs}
+
+Without the custom `cfg` flag:
+
+{custom.out}
+
+With the custom `cfg` flag:
+
+```
+$ rustc --cfg some_condition custom.rs && ./custom
+condition met!
+```

examples/attribute/cfg/input.md

@@ -0,0 +1,3 @@
+The `cfg` attribute can be use to achieve conditional compilation.
+
+{cfg.play}

examples/attribute/crate/input.md

@@ -0,0 +1,14 @@
+The `crate_type` attribute can be used to tell the compiler whether a crate is
+a binary or a library (and even which type of library). And the `crate_id`
+attribute can be used to set the name and the version of the crate.
+
+{lib.rs}
+
+When the `crate_type` attribute is used, we no longer need to pass the
+`--crate-type` flag to `rustc`.
+
+```
+$ rustc lib.rs
+$ ls lib*
+liberty-a1e7dc98-0.1.rlib
+```

examples/attribute/crate/lib.rs

@@ -0,0 +1,18 @@
+// This crate is a library
+#![crate_type = "lib"]
+// The library is named "erty", and its version is 0.1
+#![crate_id = "erty#0.1"]
+
+pub fn public_function() {
+    println!("called erty's `public_function()`");
+}
+
+fn private_function() {
+    println!("called erty's `private_function()`");
+}
+
+pub fn indirect_access() {
+    print!("called erty's `indirect_access()`, that\n> ");
+
+    private_function();
+}

examples/attribute/input.md

@@ -1,48 +1,22 @@
 An attribute is metadata applied to some module, crate or item. This metadata
 can be used to/for:
 
-* conditional compilation of code
+<!-- TODO: Link these to their respective examples -->
+* [conditional compilation of code](/attribute/cfg.html)
+* [set crate name, version and type (binary or library)](/attribute/crate.html)
 * disable lints (warnings)
 * enable compiler features (macros, glob imports, etc.)
 * link to a foreign library
 * mark functions as unit tests
 * mark functions that will be part of a benchmark
-* select crate type
-* set library name and version
+* set name and version of a crate
 
 When attributes apply to a whole crate, their syntax is `#![crate_attribute]`,
 and when they apply to a module or item, the syntax is `#[item_attribute]`
-(notice the missing bang `!`). Some attributes can take key-value arguments
-like `#[attribute(key = "value")]`, or string arguments like
-`#[attribute = "value"]`.
+(notice the missing bang `!`).
 
-Let's add metadata to the library we created in the previous chapter.
+Attributes can take arguments with different syntaxes:
 
-{lib.rs}
-
-```
-# we don't need the --crate-type flag this time
-$ rustc lib.rs
-$ ls lib*
-liberty-a1e7dc98-0.1.rlib
-```
-
-Here's an example of conditional compilation.
-
-{conditional.rs}
-
-{conditional.out}
-
-Some conditionals like `target_os` are implicitly provided by `rustc`, but
-custom conditionals must be passed to `rustc` using the `--cfg` flag.
-
-{custom.rs}
-
-{custom.out}
-
-```
-$ rustc --cfg some_condition custom.rs && ./custom
-condition met!
-```
-
-More usages of attributes will be covered in other chapters.
+* `#[attribute = "value"]`
+* `#[attribute(key = "value")]`
+* `#[attribute(value)]`

examples/borrow/alias/alias.rs

@@ -0,0 +1,43 @@
+struct Point { x: int, y: int, z: int }
+
+fn main() {
+    let mut point = Point { x: 0, y: 0, z: 0 };
+
+    {
+        let borrowed_point = &point;
+        let another_borrow = &point;
+
+        // Data can be accessed via the references and the original owner
+        println!("Point has coordinates: ({}, {}, {})",
+                 borrowed_point.x, another_borrow.y, point.z);
+
+        // Error! Can't borrow point as mutable because it's also borrowed as
+        // immutable
+        //let mutable_borrow = &mut point;
+        // TODO ^ Try uncommenting this line
+
+        // Immutable references go out of scope
+    }
+
+    {
+        let mutable_borrow = &mut point;
+
+        // Change data via mutable reference
+        mutable_borrow.x = 5;
+
+        // Error! Can't borrow `point` as immutable because it's also borrowed
+        // as mutable
+        //let y = &point.y;
+        // TODO ^ Try uncommenting this line
+
+        // Error! Can't print, because println! takes an immutable reference
+        //println!("Point Z coordinate is {}", point.z);
+        // TODO ^ Try uncommenting this line
+
+        // Mutable reference goes out of scope
+    }
+
+    // Immutable references to point are allowed again
+    println!("Point now has coordinates: ({}, {}, {})",
+             point.x, point.y, point.z);
+}

examples/borrow/alias/input.md

@@ -0,0 +1,6 @@
+Data can be immutably borrowed any number of times, but once immutably
+borrowed, the original data can't be mutably borrowed. On the other side, data
+can be mutably borrowed *once*, and until the mutable reference goes out of
+scope, the original data can't be borrowed again.
+
+{alias.play}

examples/borrow/borrow.rs

@@ -1,22 +1,35 @@
-use std::owned::Box;
-
-// this function takes ownership of the box
+// This function takes ownership of the box
 fn eat_box(boxed_int: Box<int>) {
-    // the box gets destroyed in this scope
+    println!("destroying box that contains {}", boxed_int);
 }
 
-// this function borrows the box
+// This function borrows the box
 fn peep_inside_box(borrowed_box: &Box<int>) {
     println!("This box contains {}", borrowed_box);
 }
 
 fn main() {
-    // boxed integer
+    // A boxed integer
     let boxed_int = box 5;
 
-    // borrow the box, ownership is not taken
+    // Borrow the box, ownership is not taken
+    peep_inside_box(&boxed_int);
+
+    // The box can be borrowed again
     peep_inside_box(&boxed_int);
 
-    // give up ownership of the box
+    {
+        // Take a reference to the data contained inside the box
+        let _ref_to_int: &int = &*boxed_int;
+
+        // Error! Can't destroy boxed_int, while the inner value has been
+        // borrowed
+        eat_box(boxed_int);
+        // FIXME ^ Comment out this line
+
+        // `_ref_to_int` goes out of scope
+    }
+
+    // Give up ownership of the box
     eat_box(boxed_int);
 }

examples/borrow/freeze/freeze.rs

@@ -0,0 +1,17 @@
+fn main() {
+    let mut _integer = 5;
+
+    {
+        // Borrow `integer`
+        let _ref_to_integer = &_integer;
+
+        // Error! `integer` is frozen in this scope
+        _integer = 4;
+        // FIXME ^ Comment out this line
+
+        // `ref_to_integer` goes out of scope
+    }
+
+    // Ok! `integer` is not frozen in this scope
+    _integer = 4;
+}

examples/borrow/freeze/input.md

@@ -0,0 +1,4 @@
+When data is borrowed, it also *freezes*. *Frozen* data can't be modified via
+the original object, until all the references to it go out of scope.
+
+{freeze.play}