Backport TRPL, reference, and grammar.

Rather than port each individual change to these files, for the release,
I just waited to do it all at the end, in this commit. Since individual
comits made it to master, everyone should get proper credit in the
main tree, and AUTHORS includes those whose changes are here.

Author: steveklabnik

src/doc/grammar.md

@@ -8,7 +8,7 @@ good at: embedding in other languages, programs with specific space and time
 requirements, and writing low-level code, like device drivers and operating
 systems. It improves on current languages targeting this space by having a
 number of compile-time safety checks that produce no runtime overhead, while
-eliminating all data races. Rust also aims to achieve ‘zero-cost abstrations’
+eliminating all data races. Rust also aims to achieve ‘zero-cost abstractions’
 even though some of these abstractions feel like those of a high-level
 language. Even then, Rust still allows precise control like a low-level
 language would.
@@ -24,20 +24,27 @@ is the first. After this:
 * [Syntax and Semantics][ss] - Each bit of Rust, broken down into small chunks.
 * [Nightly Rust][nr] - Cutting-edge features that aren’t in stable builds yet.
 * [Glossary][gl] - A reference of terms used in the book.
+* [Academic Research][ar] - Literature that influenced Rust.
 
 [gs]: getting-started.html
 [lr]: learn-rust.html
 [er]: effective-rust.html
 [ss]: syntax-and-semantics.html
 [nr]: nightly-rust.html
 [gl]: glossary.html
+[ar]: academic-research.html
 
 After reading this introduction, you’ll want to dive into either ‘Learn Rust’
 or ‘Syntax and Semantics’, depending on your preference: ‘Learn Rust’ if you
 want to dive in with a project, or ‘Syntax and Semantics’ if you prefer to
 start small, and learn a single concept thoroughly before moving onto the next.
 Copious cross-linking connects these parts together.
 
+### Contributing
+
+The source files from which this book is generated can be found on Github:
+[github.com/rust-lang/rust/tree/master/src/doc/trpl](https://github.com/rust-lang/rust/tree/master/src/doc/trpl)
+
 ## A brief introduction to Rust
 
 Is Rust a language you might be interested in? Let’s examine a few small code
@@ -125,7 +132,7 @@ vector. When we try to compile this program, we get an error:
 
 ```text
 error: cannot borrow `x` as mutable because it is also borrowed as immutable
-    x.push(4);
+    x.push("foo");
     ^
 note: previous borrow of `x` occurs here; the immutable borrow prevents
 subsequent moves or mutable borrows of `x` until the borrow ends
@@ -165,7 +172,7 @@ fn main() {
 
 Rust has [move semantics][move] by default, so if we want to make a copy of some
 data, we call the `clone()` method. In this example, `y` is no longer a reference
-to the vector stored in `x`, but a copy of its first element, `"hello"`. Now
+to the vector stored in `x`, but a copy of its first element, `"Hello"`. Now
 that we don’t have a reference, our `push()` works just fine.
 
 [move]: move-semantics.html
@@ -188,5 +195,5 @@ fn main() {
 We created an inner scope with an additional set of curly braces. `y` will go out of
 scope before we call `push()`, and so we’re all good.
 
-This concept of ownership isn’t just good for preventing danging pointers, but an
+This concept of ownership isn’t just good for preventing dangling pointers, but an
 entire set of related problems, like iterator invalidation, concurrency, and more.

src/doc/reference.md

@@ -5,16 +5,20 @@
     * [Hello, world!](hello-world.md)
     * [Hello, Cargo!](hello-cargo.md)
 * [Learn Rust](learn-rust.md)
+    * [Guessing Game](guessing-game.md)
+    * [Dining Philosophers](dining-philosophers.md)
+    * [Rust inside other languages](rust-inside-other-languages.md)
 * [Effective Rust](effective-rust.md)
     * [The Stack and the Heap](the-stack-and-the-heap.md)
-    * [Debug and Display](debug-and-display.md)
     * [Testing](testing.md)
+    * [Conditional Compilation](conditional-compilation.md)
     * [Documentation](documentation.md)
     * [Iterators](iterators.md)
     * [Concurrency](concurrency.md)
     * [Error Handling](error-handling.md)
     * [FFI](ffi.md)
-    * [Deref coercions](deref-coercions.md)
+    * [Borrow and AsRef](borrow-and-asref.md)
+    * [Release Channels](release-channels.md)
 * [Syntax and Semantics](syntax-and-semantics.md)
     * [Variable Bindings](variable-bindings.md)
     * [Functions](functions.md)
@@ -27,34 +31,32 @@
     * [References and Borrowing](references-and-borrowing.md)
     * [Lifetimes](lifetimes.md)
     * [Mutability](mutability.md)
-    * [Move semantics](move-semantics.md)
+    * [Structs](structs.md)
     * [Enums](enums.md)
     * [Match](match.md)
     * [Patterns](patterns.md)
-    * [Structs](structs.md)
     * [Method Syntax](method-syntax.md)
-    * [Drop](drop.md)
     * [Vectors](vectors.md)
     * [Strings](strings.md)
-    * [Traits](traits.md)
-    * [Operators and Overloading](operators-and-overloading.md)
     * [Generics](generics.md)
+    * [Traits](traits.md)
+    * [Drop](drop.md)
     * [if let](if-let.md)
     * [Trait Objects](trait-objects.md)
     * [Closures](closures.md)
     * [Universal Function Call Syntax](ufcs.md)
     * [Crates and Modules](crates-and-modules.md)
-    * [`static`](static.md)
-    * [`const`](const.md)
-    * [Tuple Structs](tuple-structs.md)
+    * [`const` and `static`](const-and-static.md)
     * [Attributes](attributes.md)
-    * [Conditional Compilation](conditional-compilation.md)
     * [`type` aliases](type-aliases.md)
     * [Casting between types](casting-between-types.md)
     * [Associated Types](associated-types.md)
     * [Unsized Types](unsized-types.md)
+    * [Operators and Overloading](operators-and-overloading.md)
+    * [Deref coercions](deref-coercions.md)
     * [Macros](macros.md)
-    * [`unsafe` Code](unsafe-code.md)
+    * [Raw Pointers](raw-pointers.md)
+    * [`unsafe`](unsafe.md)
 * [Nightly Rust](nightly-rust.md)
     * [Compiler Plugins](compiler-plugins.md)
     * [Inline Assembly](inline-assembly.md)
@@ -65,5 +67,6 @@
     * [Benchmark Tests](benchmark-tests.md)
     * [Box Syntax and Patterns](box-syntax-and-patterns.md)
     * [Slice Patterns](slice-patterns.md)
+    * [Associated Constants](associated-constants.md)
 * [Glossary](glossary.md)
 * [Academic Research](academic-research.md)

src/doc/trpl/README.md

@@ -0,0 +1,79 @@
+% Associated Constants
+
+With the `associated_consts` feature, you can define constants like this:
+
+```rust
+#![feature(associated_consts)]
+
+trait Foo {
+    const ID: i32;
+}
+
+impl Foo for i32 {
+    const ID: i32 = 1;
+}
+
+fn main() {
+    assert_eq!(1, i32::ID);
+}
+```
+
+Any implementor of `Foo` will have to define `ID`. Without the definition:
+
+```rust,ignore
+#![feature(associated_consts)]
+
+trait Foo {
+    const ID: i32;
+}
+
+impl Foo for i32 {
+}
+```
+
+gives
+
+```text
+error: not all trait items implemented, missing: `ID` [E0046]
+     impl Foo for i32 {
+     }
+```
+
+A default value can be implemented as well:
+
+```rust
+#![feature(associated_consts)]
+
+trait Foo {
+    const ID: i32 = 1;
+}
+
+impl Foo for i32 {
+}
+
+impl Foo for i64 {
+    const ID: i32 = 5;
+}
+
+fn main() {
+    assert_eq!(1, i32::ID);
+    assert_eq!(5, i64::ID);
+}
+```
+
+As you can see, when implementing `Foo`, you can leave it unimplemented, as
+with `i32`. It will then use the default value. But, as in `i64`, we can also
+add our own definition.
+
+Associated constants don’t have to be associated with a trait. An `impl` block
+for a `struct` works fine too:
+
+```rust
+#![feature(associated_consts)]
+
+struct Foo;
+
+impl Foo {
+    pub const FOO: u32 = 3;
+}
+```

src/doc/trpl/SUMMARY.md

@@ -1,8 +1,8 @@
 % Associated Types
 
-Associated types are a powerful part of Rust's type system. They're related to
-the idea of a 'type family', in other words, grouping multiple types together. That
-description is a bit abstract, so let's dive right into an example. If you want
+Associated types are a powerful part of Rust’s type system. They’re related to
+the idea of a ‘type family’, in other words, grouping multiple types together. That
+description is a bit abstract, so let’s dive right into an example. If you want
 to write a `Graph` trait, you have two types to be generic over: the node type
 and the edge type. So you might write a trait, `Graph<N, E>`, that looks like
 this:
@@ -48,11 +48,11 @@ fn distance<G: Graph>(graph: &G, start: &G::N, end: &G::N) -> uint { ... }
 
 No need to deal with the `E`dge type here!
 
-Let's go over all this in more detail.
+Let’s go over all this in more detail.
 
 ## Defining associated types
 
-Let's build that `Graph` trait. Here's the definition:
+Let’s build that `Graph` trait. Here’s the definition:
 
 ```rust
 trait Graph {
@@ -86,7 +86,7 @@ trait Graph {
 ## Implementing associated types
 
 Just like any trait, traits that use associated types use the `impl` keyword to
-provide implementations. Here's a simple implementation of Graph:
+provide implementations. Here’s a simple implementation of Graph:
 
 ```rust
 # trait Graph {
@@ -118,13 +118,13 @@ impl Graph for MyGraph {
 This silly implementation always returns `true` and an empty `Vec<Edge>`, but it
 gives you an idea of how to implement this kind of thing. We first need three
 `struct`s, one for the graph, one for the node, and one for the edge. If it made
-more sense to use a different type, that would work as well, we're just going to
+more sense to use a different type, that would work as well, we’re just going to
 use `struct`s for all three here.
 
 Next is the `impl` line, which is just like implementing any other trait.
 
 From here, we use `=` to define our associated types. The name the trait uses
-goes on the left of the `=`, and the concrete type we're `impl`ementing this
+goes on the left of the `=`, and the concrete type we’re `impl`ementing this
 for goes on the right. Finally, we use the concrete types in our function
 declarations.
 

src/doc/trpl/associated-constants.md

@@ -1,3 +1,70 @@
 % Attributes
 
-Coming Soon!
+Declarations can be annotated with ‘attributes’ in Rust. They look like this:
+
+```rust
+#[test]
+# fn foo() {}
+```
+
+or like this:
+
+```rust
+# mod foo {
+#![test]
+# }
+```
+
+The difference between the two is the `!`, which changes what the attribute
+applies to:
+
+```rust,ignore
+#[foo]
+struct Foo;
+
+mod bar {
+    #![bar]
+}
+```
+
+The `#[foo]` attribute applies to the next item, which is the `struct`
+declaration. The `#![bar]` attribute applies to the item enclosing it, which is
+the `mod` declaration. Otherwise, they’re the same. Both change the meaning of
+the item they’re attached to somehow.
+
+For example, consider a function like this:
+
+```rust
+#[test]
+fn check() {
+    assert_eq!(2, 1 + 1);
+}
+```
+
+It is marked with `#[test]`. This means it’s special: when you run
+[tests][tests], this function will execute. When you compile as usual, it won’t
+even be included. This function is now a test function.
+
+[tests]: testing.html
+
+Attributes may also have additional data:
+
+```rust
+#[inline(always)]
+fn super_fast_fn() {
+# }
+```
+
+Or even keys and values:
+
+```rust
+#[cfg(target_os = "macos")]
+mod macos_only {
+# }
+```
+
+Rust attributes are used for a number of different things. There is a full list
+of attributes [in the reference][reference]. Currently, you are not allowed to
+create your own attributes, the Rust compiler defines them.
+
+[reference]: ../reference.html#attributes

src/doc/trpl/associated-types.md

@@ -13,7 +13,7 @@ pub fn add_two(a: i32) -> i32 {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::*;
     use test::Bencher;