9 files changed, 33 insertions, 28 deletions
diff --git a/src/doc/rust-by-example/book.toml b/src/doc/rust-by-example/book.toml
index 19db456b6..61fb4057f 100644
--- a/src/doc/rust-by-example/book.toml
+++ b/src/doc/rust-by-example/book.toml
@@ -6,6 +6,7 @@ author = "The Rust Community"
 [output.html.playpen]
 editable = true
 editor = "ace"
+line-numbers = true
 
 [output.html.fold]
 enable = true
diff --git a/src/doc/rust-by-example/src/SUMMARY.md b/src/doc/rust-by-example/src/SUMMARY.md
index 223a5d8dd..9d7001690 100644
--- a/src/doc/rust-by-example/src/SUMMARY.md
+++ b/src/doc/rust-by-example/src/SUMMARY.md
@@ -219,4 +219,4 @@
 
 - [Meta](meta.md)
     - [Documentation](meta/doc.md)
-    - [Playpen](meta/playpen.md)
+    - [Playground](meta/playground.md)
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 c998ad9ad..eb515aee6 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
@@ -8,7 +8,7 @@ The is more than one way to unpack an `Option` and fall back on a default if it
 
 `or()`is chainable and eagerly evaluates its argument, as is shown in the following example. Note that because `or`'s arguments are evaluated eagerly, the variable passed to `or` is moved.
 
-```
+```rust,editable
 #[derive(Debug)] 
 enum Fruit { Apple, Orange, Banana, Kiwi, Lemon }
 
@@ -33,7 +33,7 @@ fn main() {
 
 Another alternative is to use `or_else`, which is also chainable, and evaluates lazily, as is shown in the following example:
 
-```
+```rust,editable
 #[derive(Debug)] 
 enum Fruit { Apple, Orange, Banana, Kiwi, Lemon }
 
@@ -58,11 +58,11 @@ fn main() {
 }
 ```
 
-##  `get_or_insert()` evaluates eagerly, modifies empty value im place
+##  `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:
 
-```
+```rust,editable
 #[derive(Debug)] 
 enum Fruit { Apple, Orange, Banana, Kiwi, Lemon }
 
@@ -79,10 +79,10 @@ fn main() {
 }
 ```
 
-##  `get_or_insert_with()` evaluates lazily, modifies empty value im place
+##  `get_or_insert_with()` evaluates lazily, modifies empty value in place
 
 Instead of explicitly providing a value to fall back on, we can pass a closure to `get_or_insert_with`, as follows:
-```
+```rust,editable
 #[derive(Debug)] 
 enum Fruit { Apple, Orange, Banana, Kiwi, Lemon }
 
diff --git a/src/doc/rust-by-example/src/flow_control.md b/src/doc/rust-by-example/src/flow_control.md
index c8a2f9ed8..79ef7e1f6 100644
--- a/src/doc/rust-by-example/src/flow_control.md
+++ b/src/doc/rust-by-example/src/flow_control.md
@@ -1,4 +1,4 @@
 # Flow of Control
 
-An essential part of any programming languages are ways to modify control flow:
+An integral part of any programming language are ways to modify control flow:
 `if`/`else`, `for`, and others. Let's talk about them in Rust.
diff --git a/src/doc/rust-by-example/src/hello/print.md b/src/doc/rust-by-example/src/hello/print.md
index 34dc9f0dd..c28dd9125 100644
--- a/src/doc/rust-by-example/src/hello/print.md
+++ b/src/doc/rust-by-example/src/hello/print.md
@@ -31,18 +31,20 @@ fn main() {
 
     // Different formatting can be invoked by specifying the format character after a
     // `:`.
-    println!("Base 10 repr:               {}",   69420);
-    println!("Base 2 (binary) repr:       {:b}", 69420);
-    println!("Base 8 (octal) repr:        {:o}", 69420);
-    println!("Base 16 (hexadecimal) repr: {:x}", 69420);
-    println!("Base 16 (hexadecimal) repr: {:X}", 69420);
-
-    // You can right-align text with a specified width. This will output
-    // "    1". 4 white spaces and a "1", for a total width of 5.
+    println!("Base 10:               {}",   69420); //69420
+    println!("Base 2 (binary):       {:b}", 69420); //10000111100101100
+    println!("Base 8 (octal):        {:o}", 69420); //207454
+    println!("Base 16 (hexadecimal): {:x}", 69420); //10f2c
+    println!("Base 16 (hexadecimal): {:X}", 69420); //10F2C
+
+
+    // You can right-justify text with a specified width. This will
+    // output "    1". (Four white spaces and a "1", for a total width of 5.)
     println!("{number:>5}", number=1);
 
-    // You can pad numbers with extra zeroes. This will output "00001".
-    println!("{number:0>5}", number=1);
+    // You can pad numbers with extra zeroes,
+    //and left-adjust by flipping the sign. This will output "10000".
+    println!("{number:0<5}", number=1);
 
     // You can use named arguments in the format specifier by appending a `$`
     println!("{number:0>width$}", number=1, width=5);
diff --git a/src/doc/rust-by-example/src/meta.md b/src/doc/rust-by-example/src/meta.md
index 367c7e121..8fcea1df0 100644
--- a/src/doc/rust-by-example/src/meta.md
+++ b/src/doc/rust-by-example/src/meta.md
@@ -6,7 +6,7 @@ everyone. These topics include:
 
 - [Documentation][doc]: Generate library documentation for users via the included
   `rustdoc`.
-- [Playpen][playpen]: Integrate the Rust Playpen (also known as the Rust Playground) in your documentation.
+- [Playground][playground]: Integrate the Rust Playground in your documentation.
 
 [doc]: meta/doc.md
-[playpen]: meta/playpen.md
+[playground]: meta/playground.md
diff --git a/src/doc/rust-by-example/src/meta/doc.md b/src/doc/rust-by-example/src/meta/doc.md
index 63e0b4101..e9e51186f 100644
--- a/src/doc/rust-by-example/src/meta/doc.md
+++ b/src/doc/rust-by-example/src/meta/doc.md
@@ -44,7 +44,7 @@ impl Person {
 
     /// Gives a friendly hello!
     ///
-    /// Says "Hello, [name]" to the `Person` it is called on.
+    /// Says "Hello, [name](Person::name)" to the `Person` it is called on.
     pub fn hello(& self) {
         println!("Hello, {}!", self.name);
     }
diff --git a/src/doc/rust-by-example/src/meta/playpen.md b/src/doc/rust-by-example/src/meta/playground.md
index a125f139d..7fcfad1a7 100644
--- a/src/doc/rust-by-example/src/meta/playpen.md
+++ b/src/doc/rust-by-example/src/meta/playground.md
@@ -1,6 +1,6 @@
-# Playpen
+# Playground
 
-The [Rust Playpen](https://github.com/rust-lang/rust-playpen) is a way to experiment with Rust code through a web interface. This project is now commonly referred to as [Rust Playground](https://play.rust-lang.org/).
+The [Rust Playground](https://play.rust-lang.org/) is a way to experiment with Rust code through a web interface.
 
 ## Using it with `mdbook`
 
@@ -35,11 +35,11 @@ You may have noticed in some of the [official Rust docs][official-rust-docs] a b
 ### See also:
 
 - [The Rust Playground][rust-playground]
-- [The next-gen playpen][next-gen-playpen]
+- [rust-playground][rust-playground]
 - [The rustdoc Book][rustdoc-book]
 
 [rust-playground]: https://play.rust-lang.org/
-[next-gen-playpen]: https://github.com/integer32llc/rust-playground/
+[rust-playground]: https://github.com/integer32llc/rust-playground/
 [mdbook]: https://github.com/rust-lang/mdBook
 [official-rust-docs]: https://doc.rust-lang.org/core/
 [rustdoc-book]: https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html
diff --git a/src/doc/rust-by-example/src/std_misc/threads/testcase_mapreduce.md b/src/doc/rust-by-example/src/std_misc/threads/testcase_mapreduce.md
index 28075164f..ee25b1661 100644
--- a/src/doc/rust-by-example/src/std_misc/threads/testcase_mapreduce.md
+++ b/src/doc/rust-by-example/src/std_misc/threads/testcase_mapreduce.md
@@ -17,9 +17,11 @@ its tiny block of digits, and subsequently we will sum the intermediate sums pro
 thread.
 
 Note that, although we're passing references across thread boundaries, Rust understands that we're
-only passing read-only references, and that thus no unsafety or data races can occur. Because
-we're `move`-ing the data segments into the thread, Rust will also ensure the data is kept alive
-until the threads exit, so no dangling pointers occur.
+only passing read-only references, and that thus no unsafety or data races can occur. Also because
+the references we're passing have `'static` lifetimes, Rust understands that our data won't be
+destroyed while these threads are still running. (When you need to share non-`static` data between
+threads, you can use a smart pointer like `Arc` to keep the data alive and avoid non-`static`
+lifetimes.)
 
 ```rust,editable
 use std::thread;