Merge pull request #1088 from passcod/improve-redirects

Improve redirects

Author: steveklabnik

redirects/associated-types.md

@@ -1,11 +1,22 @@
-% There is a new edition of the book
+% Associated Types
 
-This is an old link. You can [continue to the exact older page][1].
-If you're trying to learn Rust, checking out [the second edition][2] might be a better choice.
+<small>There is a new edition of the book and this is an old link.</small>
 
-* [This page in the first edition of the The Rust Programming Language][1]
+> Associated types are a way of associating a type placeholder with a trait such that the trait method definitions can use these placeholder types in their signatures.
 
-* [Related page in the second edition of The Rust Programming Language][2]
+```rust
+pub trait Iterator {
+    type Item;
+    fn next(&mut self) -> Option<Self::Item>;
+}
+```
+
+---
+
+Here are the relevant sections in the new and old books:
+
+* **[In the second edition: Ch 19.03 — Advanced Traits][2]**
+* <small>[In the first edition: Ch 3.30 — Associated Types][1]</small>
 
 
 [1]: first-edition/associated-types.html

redirects/attributes.md

@@ -1,12 +1,24 @@
-% There is a new edition of the book
+% Attributes
 
-This is an old link. You can [continue to the exact older page][1].
-If you're trying to learn Rust, checking out [the second edition][2] might be a better choice.
+<small>There is a new edition of the book and this is an old link.</small>
 
-* [This page in the first edition of the The Rust Programming Language][1]
+> Any item declaration may have an attribute applied to it.
 
-* [Index of the second edition of The Rust Programming Language][2]
+```rust
+// A function marked as a unit test
+#[test]
+fn test_foo() {
+    /* ... */
+}
+```
+
+---
+
+Here are the relevant sections in the new and old books:
+
+* **[In the Rust Reference: Ch 5.3 — Attributes][2]**
+* <small>[In the first edition: Ch 3.27 — Attributes][1]</small>
 
 
 [1]: first-edition/attributes.html
-[2]: second-edition/index.html
+[2]: ../reference/attributes.html

redirects/bibliography.md

@@ -1,12 +1,14 @@
-% There is a new edition of the book
+% Bibliography
 
-This is an old link. You can [continue to the exact older page][1].
-If you're trying to learn Rust, checking out [the second edition][2] might be a better choice.
+<small>There is a new edition of the book and this is an old link.</small>
 
-* [This page in the first edition of the The Rust Programming Language][1]
+This page does not exist in [the second edition][2].
+You might be interested in a similar page in [the Rust Reference][3].
 
-* [Index of the second edition of The Rust Programming Language][2]
+* **[In the Rust Reference: Appendix — Influences][3]**
+* <small>[In the first edition: Section 7 — Bibliography][1]</small>
 
 
 [1]: first-edition/bibliography.html
 [2]: second-edition/index.html
+[3]: ../reference/influences.html

redirects/borrow-and-asref.md

@@ -1,12 +1,25 @@
-% There is a new edition of the book
+% Borrow and AsRef
 
-This is an old link. You can [continue to the exact older page][1].
-If you're trying to learn Rust, checking out [the second edition][2] might be a better choice.
+<small>There is a new edition of the book and this is an old link.</small>
 
-* [This page in the first edition of the The Rust Programming Language][1]
+> A cheap reference-to-reference conversion.
+> Used to convert a value to a reference value within generic code.
 
-* [Index of the second edition of The Rust Programming Language][2]
+```rust
+fn is_hello<T: AsRef<str>>(s: T) {
+   assert_eq!("hello", s.as_ref());
+}
+```
+
+---
+
+This chapter does not exist in [the second edition][2].
+The best place to learn more about this is [the Rust documentation][3].
+
+* **[In the Rust documentation: `convert::AsRef`][3]**
+* <small>[In the first edition: Ch 4.10 — Borrow and AsRef][1]</small>
 
 
 [1]: first-edition/borrow-and-asref.html
 [2]: second-edition/index.html
+[3]: ../std/convert/trait.AsRef.html

redirects/casting-between-types.md

@@ -1,12 +1,32 @@
-% There is a new edition of the book
+% Casting between types
 
-This is an old link. You can [continue to the exact older page][1].
-If you're trying to learn Rust, checking out [the second edition][2] might be a better choice.
+<small>There is a new edition of the book and this is an old link.</small>
 
-* [This page in the first edition of the The Rust Programming Language][1]
+> A type cast expression is denoted with the binary operator `as`.
+> Executing an `as` expression casts the value on the left-hand side to the type on the right-hand side.
 
-* [Index of the second edition of The Rust Programming Language][2]
+```rust
+# fn sum(values: &[f64]) -> f64 { 0.0 }
+# fn len(values: &[f64]) -> i32 { 0 }
+
+fn average(values: &[f64]) -> f64 {
+    let sum: f64 = sum(values);
+    let size: f64 = len(values) as f64;
+    sum / size
+}
+```
+
+---
+
+Here are the relevant sections in the new and old books:
+
+* **[In the second edition: Appendix B — Operators, section Type Cast Expressions][2]**
+* [In the Rust Reference: Type Cast Expressions][3]
+* [In the Rust documentation: `mem::transmute`][4]
+* <small>[In the first edition: Ch 3.29 — Casting between types][1]</small>
 
 
 [1]: first-edition/casting-between-types.html
-[2]: second-edition/index.html
+[2]: second-edition/appendix-02-operators.html#type-cast-expressions
+[3]: ../reference/expressions/operator-expr.html#type-cast-expressions
+[4]: ../std/mem/fn.transmute.html

redirects/choosing-your-guarantees.md

@@ -1,11 +1,21 @@
-% There is a new edition of the book
+% Choosing your Guarantees
 
-This is an old link. You can [continue to the exact older page][1].
-If you're trying to learn Rust, checking out [the second edition][2] might be a better choice.
+<small>There is a new edition of the book and this is an old link.</small>
 
-* [This page in the first edition of the The Rust Programming Language][1]
+> Smart pointers are data structures that act like a pointer, but they also have additional metadata and capabilities.
+> The different smart pointers defined in Rust’s standard library provide extra functionality beyond what references provide.
 
-* [Related chapter in the second edition of The Rust Programming Language][2]
+```rust
+let b = Box::new(5);
+println!("b = {}", b);
+```
+
+---
+
+Here are the relevant sections in the new and old books:
+
+* **[In the second edition: Ch 15.00 — Smart Pointers][2]**
+* <small>[In the first edition: Ch 4.8 — Choosing your Guarantees][1]</small>
 
 
 [1]: first-edition/choosing-your-guarantees.html

redirects/closures.md

@@ -1,11 +1,27 @@
-% There is a new edition of the book
+% Closures
 
-This is an old link. You can [continue to the exact older page][1].
-If you're trying to learn Rust, checking out [the second edition][2] might be a better choice.
+<small>There is a new edition of the book and this is an old link.</small>
 
-* [This page in the first edition of the The Rust Programming Language][1]
+> Anonymous functions you can save in a variable or pass as arguments to other functions.
 
-* [Related page in the second edition of The Rust Programming Language][2]
+```rust
+# use std::thread;
+# use std::time::Duration;
+
+let expensive_closure = |num| {
+    println!("calculating slowly...");
+    thread::sleep(Duration::from_secs(2));
+    num
+};
+#expensive_closure(5);
+```
+
+---
+
+Here are the relevant sections in the new and old books:
+
+* **[In the second edition: Ch 13.01 — Closures][2]**
+* <small>[In the first edition: Ch 3.23 — Closures][1]</small>
 
 
 [1]: first-edition/closures.html

redirects/comments.md

@@ -1,11 +1,22 @@
-% There is a new edition of the book
+% Comments
 
-This is an old link. You can [continue to the exact older page][1].
-If you're trying to learn Rust, checking out [the second edition][2] might be a better choice.
+<small>There is a new edition of the book and this is an old link.</small>
 
-* [This page in the first edition of the The Rust Programming Language][1]
+> Comments must start with two slashes and continue until the end of the line.
+> For comments that extend beyond a single line, you’ll need to include // on each line.
 
-* [Related page in the second edition of The Rust Programming Language][2]
+```rust
+// So we’re doing something complicated here, long enough that we need
+// multiple lines of comments to do it! Whew! Hopefully, this comment will
+// explain what’s going on.
+```
+
+---
+
+Here are the relevant sections in the new and old books:
+
+* **[In the second edition: Ch 3.04 — Comments][2]**
+* <small>[In the first edition: Ch 3.4 — Comments][1]</small>
 
 
 [1]: first-edition/comments.html

redirects/compiler-plugins.md

@@ -1,6 +1,16 @@
-% The Rust Programming Language Has Moved
+% Compiler Plugins
 
-This chapter of the book has moved to [a chapter in the Unstable
-Book][unstable book plugins]. Please check it out there.
+<small>There is a new edition of the book and this is an old link.</small>
 
-[unstable book plugins]: ../unstable-book/language-features/plugin.html
+> Compiler plugins are user-provided libraries that extend the compiler's behavior with new syntax extensions, lint checks, etc.
+
+---
+
+This particular chapter has moved to [the Unstable Book][2].
+
+* **[In the Unstable Rust Book: `plugin`][2]**
+* <small><del>[In the first edition: Compiler Plugins][1]</del> (does not exist anymore)</small>
+
+
+[1]: first-edition/compiler-plugins.html
+[2]: ../unstable-book/language-features/plugin.html

redirects/concurrency.md

@@ -1,11 +1,16 @@
-% There is a new edition of the book
+% Concurrency
 
-This is an old link. You can [continue to the exact older page][1].
-If you're trying to learn Rust, checking out [the second edition][2] might be a better choice.
+<small>There is a new edition of the book and this is an old link.</small>
 
-* [This page in the first edition of the The Rust Programming Language][1]
+> Historically, programming [concurrency] has been difficult and error prone: Rust hopes to change that.
+> Fearless concurrency allows you to write code that’s free of subtle bugs and is easy to refactor without introducing new bugs.
 
-* [Related chapter in the second edition of The Rust Programming Language][2]
+---
+
+Here are the relevant sections in the new and old books:
+
+* **[In the second edition: Ch 16.00 — Fearless Concurrency][2]**
+* <small>[In the first edition: Ch 4.6 — Concurrency][1]</small>
 
 
 [1]: first-edition/concurrency.html

redirects/conditional-compilation.md

@@ -1,12 +1,28 @@
-% There is a new edition of the book
+% Conditional Compilation
 
-This is an old link. You can [continue to the exact older page][1].
-If you're trying to learn Rust, checking out [the second edition][2] might be a better choice.
+<small>There is a new edition of the book and this is an old link.</small>
 
-* [This page in the first edition of the The Rust Programming Language][1]
+> Sometimes one wants to have different compiler outputs from the same code, depending on build target, such as targeted operating system, or to enable release builds.
+> Configuration options are either provided by the compiler or passed in on the command line using.
+> Rust code then checks for their presence using the `#[cfg(...)]` attribute
 
-* [Index of the second edition of The Rust Programming Language][2]
+```rust
+// The function is only included in the build when compiling for macOS
+#[cfg(target_os = "macos")]
+fn macos_only() {
+  // ...
+}
+```
+
+---
+
+This particular chapter does not exist in [the second edition][2].
+The best place to learn about it is [the Rust Reference][3].
+
+* **[In the Rust Reference: Ch 5.3 — Attributes, Conditional Compilation section][3]**
+* <small>[In the first edition: Ch 4.3 — Conditional Compilation][1]</small>
 
 
 [1]: first-edition/conditional-compilation.html
-[2]: second-edition/index.html
+[2]: second-edition/
+[3]: ../reference/attributes.html#conditional-compilation

redirects/const-and-static.md

@@ -1,12 +1,23 @@
-% There is a new edition of the book
+% `const` and `static`
 
-This is an old link. You can [continue to the exact older page][1].
-If you're trying to learn Rust, checking out [the second edition][2] might be a better choice.
+<small>There is a new edition of the book and this is an old link.</small>
 
-* [This page in the first edition of the The Rust Programming Language][1]
+> Constants are _always_ immutable, and may only be set to a constant expression, not the result of a function call or any other value that could only be computed at runtime.
+>
+> Global variables are called `static` in Rust.
 
-* [Related section about `const` in the second edition of The Rust Programming Language][2]
-* [Related section about `static` in the second edition of The Rust Programming Language][3]
+```rust
+const MAX_POINTS: u32 = 100_000;
+static HELLO_WORLD: &str = "Hello, world!";
+```
+
+---
+
+Here are the relevant sections in the new and old books:
+
+* **[In the second edition: Ch 3.01 — Variables and Mutability, section Constants][2]**
+* **[In the second edition: Ch 19.01 — Unsafe Rust, section Static Variables][3]**
+* <small>[In the first edition: Ch 3.26 — `const` and `static`][1]</small>
 
 
 [1]: first-edition/const-and-static.html

redirects/crates-and-modules.md

@@ -1,15 +1,28 @@
-% There is a new edition of the book
+% Crates and Modules
 
-This is an old link. You can [continue to the exact older page][1].
-If you're trying to learn Rust, checking out [the second edition][2] might be a better choice.
+<small>There is a new edition of the book and this is an old link.</small>
 
-* [This page in the first edition of the The Rust Programming Language][1]
+> Rust has a module system that enables the reuse of code in an organized fashion.
+> A module is a namespace that contains definitions of functions or types, and you can choose whether those definitions are visible outside their module (public) or not (private).
+>
+> A crate is a project that other people can pull into their projects as a dependency.
 
-* [Related chapter about modules in the second edition of The Rust Programming Language][2]
+```rust
+mod network {
+    fn connect() {
+    }
+}
+```
 
-* [Related chapter about crates in the second edition of The Rust Programming Language][3]
+---
+
+Here are the relevant sections in the new and old books:
+
+* **[In the second edition: Ch 7.01 — `mod` and the Filesystem][2]**
+* [In the second edition: Ch 14.02 — Publishing a Crate to Crates.io][2]
+* <small>[In the first edition: Ch 3.25 — Crates and Modules][1]</small>
 
 
 [1]: first-edition/crates-and-modules.html
-[2]: second-edition/ch07-00-modules.html
-[3]: second-edition/ch14-00-more-about-cargo.html
+[2]: second-edition/ch07-01-mod-and-the-filesystem.html
+[3]: second-edition/ch14-02-publishing-to-crates-io.html