16 files changed, 54 insertions, 47 deletions
diff --git a/src/doc/rust-by-example/src/cargo/conventions.md b/src/doc/rust-by-example/src/cargo/conventions.md
index 6e8196608..2335104f5 100644
--- a/src/doc/rust-by-example/src/cargo/conventions.md
+++ b/src/doc/rust-by-example/src/cargo/conventions.md
@@ -25,9 +25,9 @@ foo
         └── my_other_bin.rs
 ```
 
-To tell `cargo` to compile or run this binary as opposed to the default or other
-binaries, we just pass `cargo` the `--bin my_other_bin` flag, where `my_other_bin`
-is the name of the binary we want to work with.
+To tell `cargo` to only compile or run this binary, we just pass `cargo` the
+`--bin my_other_bin` flag, where `my_other_bin` is the name of the binary we
+want to work with.
 
 In addition to extra binaries, `cargo` supports [more features] such as
 benchmarks, tests, and examples.
diff --git a/src/doc/rust-by-example/src/cargo/deps.md b/src/doc/rust-by-example/src/cargo/deps.md
index 8913e9e38..85f223f98 100644
--- a/src/doc/rust-by-example/src/cargo/deps.md
+++ b/src/doc/rust-by-example/src/cargo/deps.md
@@ -11,8 +11,8 @@ To create a new Rust project,
 # A binary
 cargo new foo
 
-# OR A library
-cargo new --lib foo
+# A library
+cargo new --lib bar
 ```
 
 For the rest of this chapter, let's assume we are making a binary, rather than
@@ -21,14 +21,19 @@ a library, but all of the concepts are the same.
 After the above commands, you should see a file hierarchy like this:
 
 ```txt
-foo
-├── Cargo.toml
-└── src
-    └── main.rs
+.
+├── bar
+│   ├── Cargo.toml
+│   └── src
+│       └── lib.rs
+└── foo
+    ├── Cargo.toml
+    └── src
+        └── main.rs
 ```
 
-The `main.rs` is the root source file for your new project -- nothing new there.
-The `Cargo.toml` is the config file for `cargo` for this project (`foo`). If you
+The `main.rs` is the root source file for your new `foo` project -- nothing new there.
+The `Cargo.toml` is the config file for `cargo` for this project. If you
 look inside it, you should see something like this:
 
 ```toml
diff --git a/src/doc/rust-by-example/src/conversion/from_into.md b/src/doc/rust-by-example/src/conversion/from_into.md
index 266d10f28..47b327142 100644
--- a/src/doc/rust-by-example/src/conversion/from_into.md
+++ b/src/doc/rust-by-example/src/conversion/from_into.md
@@ -66,7 +66,7 @@ impl From<i32> for Number {
 
 fn main() {
     let int = 5;
-    // Try removing the type declaration
+    // Try removing the type annotation
     let num: Number = int.into();
     println!("My number is {:?}", num);
 }
diff --git a/src/doc/rust-by-example/src/error/iter_result.md b/src/doc/rust-by-example/src/error/iter_result.md
index e77e21ff6..288f4fc02 100644
--- a/src/doc/rust-by-example/src/error/iter_result.md
+++ b/src/doc/rust-by-example/src/error/iter_result.md
@@ -51,7 +51,7 @@ fn main() {
 
 ## Fail the entire operation with `collect()`
 
-`Result` implements `FromIter` so that a vector of results (`Vec<Result<T, E>>`)
+`Result` implements `FromIterator` so that a vector of results (`Vec<Result<T, E>>`)
 can be turned into a result with a vector (`Result<Vec<T>, E>`). Once an
 `Result::Err` is found, the iteration will terminate.
 
diff --git a/src/doc/rust-by-example/src/error/option_unwrap/defaults.md b/src/doc/rust-by-example/src/error/option_unwrap/defaults.md
index eb515aee6..117333f12 100644
--- a/src/doc/rust-by-example/src/error/option_unwrap/defaults.md
+++ b/src/doc/rust-by-example/src/error/option_unwrap/defaults.md
@@ -1,6 +1,6 @@
 # Unpacking options and defaults
 
-The is more than one way to unpack an `Option` and fall back on a default if it is `None`. To choose the one that meets our needs, we need to consider the following:
+There is more than one way to unpack an `Option` and fall back on a default if it is `None`. To choose the one that meets our needs, we need to consider the following:
 * do we need eager or lazy evaluation?
 * do we need to keep the original empty value intact, or modify it in place?
 
@@ -60,7 +60,7 @@ fn main() {
 
 ##  `get_or_insert()` evaluates eagerly, modifies empty value in place
 
-To make sure that an `Option` contains a value, we can use `get_or_insert` to modify it in place with a fallback value, as is shown in the following example. Note that `get_or_insert` eagerly evaluaes its parameter, so variable `apple` is moved:
+To make sure that an `Option` contains a value, we can use `get_or_insert` to modify it in place with a fallback value, as is shown in the following example. Note that `get_or_insert` eagerly evaluates its parameter, so variable `apple` is moved:
 
 ```rust,editable
 #[derive(Debug)] 
@@ -75,7 +75,7 @@ fn main() {
     // my_fruit is: Apple
     // first_available_fruit is: Apple
     //println!("Variable named `apple` is moved: {:?}", apple);
-    // TODO: uncomment the line above to see the compliler error
+    // TODO: uncomment the line above to see the compiler error
 }
 ```
 
diff --git a/src/doc/rust-by-example/src/flow_control/match/destructuring/destructure_slice.md b/src/doc/rust-by-example/src/flow_control/match/destructuring/destructure_slice.md
index 54552972a..93b7e4205 100644
--- a/src/doc/rust-by-example/src/flow_control/match/destructuring/destructure_slice.md
+++ b/src/doc/rust-by-example/src/flow_control/match/destructuring/destructure_slice.md
@@ -45,4 +45,4 @@ fn main() {
 
 ### See also:
 
-[Arrays and Slices](../../../primitives/array.md)
+[Arrays and Slices](../../../primitives/array.md) and [Binding](../binding.md) for `@` sigil
diff --git a/src/doc/rust-by-example/src/flow_control/match/guard.md b/src/doc/rust-by-example/src/flow_control/match/guard.md
index 6dba58f13..63008a743 100644
--- a/src/doc/rust-by-example/src/flow_control/match/guard.md
+++ b/src/doc/rust-by-example/src/flow_control/match/guard.md
@@ -5,7 +5,7 @@ A `match` *guard* can be added to filter the arm.
 ```rust,editable
 enum Temperature {
     Celsius(i32),
-    Farenheit(i32),
+    Fahrenheit(i32),
 }
 
 fn main() {
@@ -17,8 +17,8 @@ fn main() {
         // The `if condition` part ^ is a guard
         Temperature::Celsius(t) => println!("{}C is below 30 Celsius", t),
 
-        Temperature::Farenheit(t) if t > 86 => println!("{}F is above 86 Farenheit", t),
-        Temperature::Farenheit(t) => println!("{}F is below 86 Farenheit", t),
+        Temperature::Fahrenheit(t) if t > 86 => println!("{}F is above 86 Fahrenheit", t),
+        Temperature::Fahrenheit(t) => println!("{}F is below 86 Fahrenheit", t),
     }
 }
 ```
diff --git a/src/doc/rust-by-example/src/macros.md b/src/doc/rust-by-example/src/macros.md
index ffeb923e5..3f12fcc41 100644
--- a/src/doc/rust-by-example/src/macros.md
+++ b/src/doc/rust-by-example/src/macros.md
@@ -37,4 +37,4 @@ So why are macros useful?
 
 3. Variadic interfaces. Sometimes you want to define an interface that takes a
    variable number of arguments. An example is `println!` which could take any
-   number of arguments, depending on the format string!. (More on this later)
+   number of arguments, depending on the format string. (More on this later)
diff --git a/src/doc/rust-by-example/src/mod/struct_visibility.md b/src/doc/rust-by-example/src/mod/struct_visibility.md
index e7359413c..8641a7264 100644
--- a/src/doc/rust-by-example/src/mod/struct_visibility.md
+++ b/src/doc/rust-by-example/src/mod/struct_visibility.md
@@ -13,7 +13,6 @@ mod my {
     }
 
     // A public struct with a private field of generic type `T`
-    #[allow(dead_code)]
     pub struct ClosedBox<T> {
         contents: T,
     }
@@ -56,4 +55,4 @@ fn main() {
 [generics][generics] and [methods][methods]
 
 [generics]: ../generics.md
-[methods]: ../fn/methods.md
-\ No newline at end of file
+[methods]: ../fn/methods.md
diff --git a/src/doc/rust-by-example/src/primitives/array.md b/src/doc/rust-by-example/src/primitives/array.md
index 841c71c14..0f56182cd 100644
--- a/src/doc/rust-by-example/src/primitives/array.md
+++ b/src/doc/rust-by-example/src/primitives/array.md
@@ -64,7 +64,7 @@ fn main() {
         }
     }
 
-    // Out of bound indexing causes compile error
+    // Out of bound indexing causes runtime error
     //println!("{}", xs[5]);
 }
 ```
diff --git a/src/doc/rust-by-example/src/std/box.md b/src/doc/rust-by-example/src/std/box.md
index 0740c07d6..ebc8ff430 100644
--- a/src/doc/rust-by-example/src/std/box.md
+++ b/src/doc/rust-by-example/src/std/box.md
@@ -62,11 +62,11 @@ fn main() {
              mem::size_of_val(&rectangle));
 
     // box size == pointer size
-    println!("Boxed point occupies {} bytes on the heap",
+    println!("Boxed point occupies {} bytes on the stack",
              mem::size_of_val(&boxed_point));
-    println!("Boxed rectangle occupies {} bytes on the heap",
+    println!("Boxed rectangle occupies {} bytes on the stack",
              mem::size_of_val(&boxed_rectangle));
-    println!("Boxed box occupies {} bytes on the heap",
+    println!("Boxed box occupies {} bytes on the stack",
              mem::size_of_val(&box_in_a_box));
 
     // Copy the data contained in `boxed_point` into `unboxed_point`
diff --git a/src/doc/rust-by-example/src/std/str.md b/src/doc/rust-by-example/src/std/str.md
index 26d8fd109..a15038b90 100644
--- a/src/doc/rust-by-example/src/std/str.md
+++ b/src/doc/rust-by-example/src/std/str.md
@@ -69,7 +69,7 @@ This way you can add any character to your string, even unprintable ones
 and ones that you don't know how to type. If you want a literal backslash,
 escape it with another one: `\\`
 
-String or character literal delimiters occuring within a literal must be escaped: `"\""`, `'\''`.
+String or character literal delimiters occurring within a literal must be escaped: `"\""`, `'\''`.
 
 ```rust,editable
 fn main() {
diff --git a/src/doc/rust-by-example/src/std_misc/path.md b/src/doc/rust-by-example/src/std_misc/path.md
index 48d85c144..af0f3d388 100644
--- a/src/doc/rust-by-example/src/std_misc/path.md
+++ b/src/doc/rust-by-example/src/std_misc/path.md
@@ -13,8 +13,10 @@ between `Path` and `PathBuf` is similar to that of `str` and `String`:
 a `PathBuf` can be mutated in-place, and can be dereferenced to a `Path`.
 
 Note that a `Path` is *not* internally represented as an UTF-8 string, but
-instead is stored as a vector of bytes (`Vec<u8>`). Therefore, converting a
-`Path` to a `&str` is *not* free and may fail (an `Option` is returned).
+instead is stored as an `OsString`. Therefore, converting a `Path` to a `&str`
+is *not* free and may fail (an `Option` is returned). However, a `Path` can be 
+freely converted to an `OsString` or `&OsStr` using `into_os_string` and
+`as_os_str`, respectively.
 
 ```rust,editable
 use std::path::Path;
diff --git a/src/doc/rust-by-example/src/testing/doc_testing.md b/src/doc/rust-by-example/src/testing/doc_testing.md
index 2fac440f9..1d6cd46ad 100644
--- a/src/doc/rust-by-example/src/testing/doc_testing.md
+++ b/src/doc/rust-by-example/src/testing/doc_testing.md
@@ -1,9 +1,10 @@
 # Documentation testing
 
 The primary way of documenting a Rust project is through annotating the source
-code. Documentation comments are written in [markdown] and support code
-blocks in them. Rust takes care about correctness, so these code blocks are
-compiled and used as documentation tests.
+code. Documentation comments are written in 
+[CommonMark Markdown specification][commonmark] and support code blocks in them.
+Rust takes care about correctness, so these code blocks are compiled and used 
+as documentation tests.
 
 ```rust,ignore
 /// First line is a short summary describing function.
@@ -83,7 +84,7 @@ and `unwrap` it in hidden `main`. Sounds complicated? Here's an example:
 /// ```
 /// # // hidden lines start with `#` symbol, but they're still compilable!
 /// # fn try_main() -> Result<(), String> { // line that wraps the body shown in doc
-/// let res = try::try_div(10, 2)?;
+/// let res = doccomments::try_div(10, 2)?;
 /// # Ok(()) // returning from try_main
 /// # }
 /// # fn main() { // starting main that'll unwrap()
@@ -106,6 +107,6 @@ pub fn try_div(a: i32, b: i32) -> Result<i32, String> {
 * [API Guidelines][doc-nursery] on documentation guidelines
 
 [doc-nursery]: https://rust-lang-nursery.github.io/api-guidelines/documentation.html
-[markdown]: https://daringfireball.net/projects/markdown/
+[commonmark]: https://commonmark.org/
 [RFC505]: https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md
 [question-instead-of-unwrap]: https://rust-lang-nursery.github.io/api-guidelines/documentation.html#examples-use--not-try-not-unwrap-c-question-mark
diff --git a/src/doc/rust-by-example/src/types/cast.md b/src/doc/rust-by-example/src/types/cast.md
index 6182874cd..deed34cf7 100644
--- a/src/doc/rust-by-example/src/types/cast.md
+++ b/src/doc/rust-by-example/src/types/cast.md
@@ -53,13 +53,13 @@ fn main() {
     // Unless it already fits, of course.
     println!(" 128 as a i16 is: {}", 128 as i16);
     
-    // 128 as i8 -> -128, whose two's complement in eight bits is:
+    // 128 as u8 -> 128, whose value in 8-bit two's complement representation is:
     println!(" 128 as a i8 is : {}", 128 as i8);
 
     // repeating the example above
     // 1000 as u8 -> 232
     println!("1000 as a u8 is : {}", 1000 as u8);
-    // and the two's complement of 232 is -24
+    // and the value of 232 in 8-bit two's complement representation is -24
     println!(" 232 as a i8 is : {}", 232 as i8);
     
     // Since Rust 1.45, the `as` keyword performs a *saturating cast* 
@@ -67,23 +67,23 @@ fn main() {
     // the upper bound or is less than the lower bound, the returned value 
     // will be equal to the bound crossed.
     
-    // 300.0 is 255
-    println!("300.0 is {}", 300.0_f32 as u8);
+    // 300.0 as u8 is 255
+    println!(" 300.0 as u8 is : {}", 300.0_f32 as u8);
     // -100.0 as u8 is 0
-    println!("-100.0 as u8 is {}", -100.0_f32 as u8);
+    println!("-100.0 as u8 is : {}", -100.0_f32 as u8);
     // nan as u8 is 0
-    println!("nan as u8 is {}", f32::NAN as u8);
+    println!("   nan as u8 is : {}", f32::NAN as u8);
     
     // This behavior incurs a small runtime cost and can be avoided 
     // with unsafe methods, however the results might overflow and 
     // return **unsound values**. Use these methods wisely:
     unsafe {
-        // 300.0 is 44
-        println!("300.0 is {}", 300.0_f32.to_int_unchecked::<u8>());
+        // 300.0 as u8 is 44
+        println!(" 300.0 as u8 is : {}", 300.0_f32.to_int_unchecked::<u8>());
         // -100.0 as u8 is 156
-        println!("-100.0 as u8 is {}", (-100.0_f32).to_int_unchecked::<u8>());
+        println!("-100.0 as u8 is : {}", (-100.0_f32).to_int_unchecked::<u8>());
         // nan as u8 is 0
-        println!("nan as u8 is {}", f32::NAN.to_int_unchecked::<u8>());
+        println!("   nan as u8 is : {}", f32::NAN.to_int_unchecked::<u8>());
     }
 }
 ```
diff --git a/src/doc/rust-by-example/src/unsafe/asm.md b/src/doc/rust-by-example/src/unsafe/asm.md
index ee6b8088a..7ad6e0c5e 100644
--- a/src/doc/rust-by-example/src/unsafe/asm.md
+++ b/src/doc/rust-by-example/src/unsafe/asm.md
@@ -227,7 +227,7 @@ This state is generally referred to as being "clobbered".
 We need to tell the compiler about this since it may need to save and restore this state around the inline assembly block.
 
 ```rust
-use core::arch::asm;
+use std::arch::asm;
 
 fn main() {
     // three entries of four bytes each
@@ -333,7 +333,7 @@ In some cases, fine control is needed over the way a register name is formatted
 
 By default the compiler will always choose the name that refers to the full register size (e.g. `rax` on x86-64, `eax` on x86, etc).
 
-This default can be overriden by using modifiers on the template string operands, just like you would with format strings:
+This default can be overridden by using modifiers on the template string operands, just like you would with format strings:
 
 ```rust
 use std::arch::asm;