Fix merge conflict and also add markdown formatting

Author: cactorium

configure

@@ -106,8 +106,8 @@ probe() {
         T=$(command -v $P 2>&1)
         if [ $? -eq 0 ]
         then
-            VER0=$($P --version 2>/dev/null | head -1 \
-                |  sed -e 's/[^0-9]*\([vV]\?[0-9.]\+[^ ]*\).*/\1/' )
+            VER0=$($P --version 2>/dev/null \
+                |  grep -o '[vV]\?[0-9][0-9.][a-z0-9.-]*' | head -1 )
             if [ $? -eq 0 -a "x${VER0}" != "x" ]
             then
               VER="($VER0)"
@@ -711,6 +711,20 @@ else
     probe_need CFG_GIT     git
 fi
 
+# Use `md5sum` on GNU platforms, or `md5 -q` on BSD
+probe CFG_MD5              md5
+probe CFG_MD5SUM           md5sum
+if [ -n "$CFG_MD5" ]
+then
+    CFG_HASH_COMMAND="$CFG_MD5 -q | head -c 8"
+elif [ -n "$CFG_MD5SUM" ]
+then
+    CFG_HASH_COMMAND="$CFG_MD5SUM | head -c 8"
+else
+    err 'could not find one of: md5 md5sum'
+fi
+putvar CFG_HASH_COMMAND
+
 probe CFG_CLANG            clang++
 probe CFG_CCACHE           ccache
 probe CFG_GCC              gcc

mk/main.mk

@@ -20,7 +20,9 @@ CFG_RELEASE_NUM=1.1.0
 # versions (section 9)
 CFG_PRERELEASE_VERSION=.1
 
-CFG_FILENAME_EXTRA=4e7c5e5c
+# Append a version-dependent hash to each library, so we can install different
+# versions in the same place
+CFG_FILENAME_EXTRA=$(shell printf '%s' $(CFG_RELEASE) | $(CFG_HASH_COMMAND))
 
 ifeq ($(CFG_RELEASE_CHANNEL),stable)
 # This is the normal semver version string, e.g. "0.12.0", "0.12.0-nightly"

src/doc/reference.md

@@ -1346,6 +1346,8 @@ vtable when the trait is used as a [trait object](#trait-objects).
 Traits are implemented for specific types through separate
 [implementations](#implementations).
 
+Consider the following trait:
+
 ```
 # type Surface = i32;
 # type BoundingBox = i32;
@@ -1360,6 +1362,20 @@ This defines a trait with two methods. All values that have
 `draw` and `bounding_box` methods called, using `value.bounding_box()`
 [syntax](#method-call-expressions).
 
+Traits can include default implementations of methods, as in:
+
+```
+trait Foo {
+    fn bar(&self);
+
+    fn baz(&self) { println!("We called baz."); }
+}
+```
+
+Here the `baz` method has a default implementation, so types that implement
+`Foo` need only implement `bar`. It is also possible for implementing types
+to override a method that has a default implementation.
+
 Type parameters can be specified for a trait to make it generic. These appear
 after the trait name, using the same syntax used in [generic
 functions](#generic-functions).
@@ -1372,6 +1388,35 @@ trait Seq<T> {
 }
 ```
 
+It is also possible to define associated types for a trait. Consider the
+following example of a `Container` trait. Notice how the type is available
+for use in the method signatures:
+
+```
+trait Container {
+    type E;
+    fn empty() -> Self;
+    fn insert(&mut self, Self::E);
+}
+```
+
+In order for a type to implement this trait, it must not only provide
+implementations for every method, but it must specify the type `E`. Here's
+an implementation of `Container` for the standard library type `Vec`:
+
+```
+# trait Container {
+#     type E;
+#     fn empty() -> Self;
+#     fn insert(&mut self, Self::E);
+# }
+impl<T> Container for Vec<T> {
+    type E = T;
+    fn empty() -> Vec<T> { Vec::new() }
+    fn insert(&mut self, x: T) { self.push(x); }
+}
+```
+
 Generic functions may use traits as _bounds_ on their type parameters. This
 will have two effects: only types that have the trait may instantiate the
 parameter, and within the generic function, the methods of the trait can be
@@ -3470,13 +3515,23 @@ more of the closure traits:
 
 ### Trait objects
 
-Every trait item (see [traits](#traits)) defines a type with the same name as
-the trait. This type is called the _trait object_ of the trait. Trait objects
-permit "late binding" of methods, dispatched using _virtual method tables_
-("vtables"). Whereas most calls to trait methods are "early bound" (statically
-resolved) to specific implementations at compile time, a call to a method on an
-trait objects is only resolved to a vtable entry at compile time. The actual
-implementation for each vtable entry can vary on an object-by-object basis.
+In Rust, a type like `&SomeTrait` or `Box<SomeTrait>` is called a _trait object_.
+Each instance of a trait object includes:
+
+ - a pointer to an instance of a type `T` that implements `SomeTrait`
+ - a _virtual method table_, often just called a _vtable_, which contains, for
+   each method of `SomeTrait` that `T` implements, a pointer to `T`'s
+   implementation (i.e. a function pointer).
+
+The purpose of trait objects is to permit "late binding" of methods. A call to
+a method on a trait object is only resolved to a vtable entry at compile time.
+The actual implementation for each vtable entry can vary on an object-by-object
+basis.
+
+Note that for a trait object to be instantiated, the trait must be
+_object-safe_. Object safety rules are defined in [RFC 255].
+
+[RFC 255]: https://github.com/rust-lang/rfcs/blob/master/text/0255-object-safety.md
 
 Given a pointer-typed expression `E` of type `&T` or `Box<T>`, where `T`
 implements trait `R`, casting `E` to the corresponding pointer type `&R` or

src/doc/trpl/README.md

@@ -175,7 +175,7 @@ data, we call the `clone()` method. In this example, `y` is no longer a referenc
 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
+[move]: ownership.html#move-semantics
 
 If we truly want a reference, we need the other option: ensure that our reference
 goes out of scope before we try to do the mutation. That looks like this:

src/doc/trpl/dining-philosophers.md

@@ -450,7 +450,7 @@ which blocks execution until the thread has completed execution. This ensures
 that the threads complete their work before the program exits.
 
 If you run this program, you’ll see that the philosophers eat out of order!
-We have mult-threading!
+We have multi-threading!
 
 ```text
 Gilles Deleuze is eating.

src/doc/trpl/error-handling.md

@@ -181,6 +181,8 @@ match version {
 This function makes use of an enum, `ParseError`, to enumerate the various
 errors that can occur.
 
+The [`Debug`](../std/fmt/trait.Debug.html) trait is what lets us print the enum value using the `{:?}` format operation.
+
 # Non-recoverable errors with `panic!`
 
 In the case of an error that is unexpected and not recoverable, the `panic!`

src/doc/trpl/iterators.md

@@ -42,7 +42,7 @@ loop is just a handy way to write this `loop`/`match`/`break` construct.
 `for` loops aren't the only thing that uses iterators, however. Writing your
 own iterator involves implementing the `Iterator` trait. While doing that is
 outside of the scope of this guide, Rust provides a number of useful iterators
-to accomplish various threads. Before we talk about those, we should talk about a
+to accomplish various tasks. Before we talk about those, we should talk about a
 Rust anti-pattern. And that's using ranges like this.
 
 Yes, we just talked about how ranges are cool. But ranges are also very

src/doc/trpl/the-stack-and-the-heap.md

@@ -80,15 +80,15 @@ This memory is kind of like a giant array: addresses start at zero and go
 up to the final number. So here’s a diagram of our first stack frame:
 
 | Address | Name | Value |
-+---------+------+-------+
+|---------|------|-------|
 | 0       | x    | 42    |
 
 We’ve got `x` located at address `0`, with the value `42`.
 
 When `foo()` is called, a new stack frame is allocated:
 
 | Address | Name | Value |
-+---------+------+-------+
+|---------|------|-------|
 | 2       | z    | 100   |
 | 1       | y    | 5     |
 | 0       | x    | 42    |
@@ -107,7 +107,7 @@ value being stored.
 After `foo()` is over, its frame is deallocated:
 
 | Address | Name | Value |
-+---------+------+-------+
+|---------|------|-------|
 | 0       | x    | 42    |
 
 And then, after `main()`, even this last value goes away. Easy!
@@ -142,13 +142,13 @@ fn main() {
 Okay, first, we call `main()`:
 
 | Address | Name | Value |
-+---------+------+-------+
+|---------|------|-------|
 | 0       | x    | 42    |
 
 Next up, `main()` calls `foo()`:
 
 | Address | Name | Value |
-+---------+------+-------+
+|---------|------|-------|
 | 3       | c    | 1     |
 | 2       | b    | 100   |
 | 1       | a    | 5     |
@@ -157,7 +157,7 @@ Next up, `main()` calls `foo()`:
 And then `foo()` calls `bar()`:
 
 | Address | Name | Value |
-+---------+------+-------+
+|---------|------|-------|
 | 4       | i    | 6     |
 | 3       | c    | 1     |
 | 2       | b    | 100   |
@@ -170,7 +170,7 @@ After `bar()` is over, its frame is deallocated, leaving just `foo()` and
 `main()`:
 
 | Address | Name | Value |
-+---------+------+-------+
+|---------|------|-------|
 | 3       | c    | 1     |
 | 2       | b    | 100   |
 | 1       | a    | 5     |
@@ -179,7 +179,7 @@ After `bar()` is over, its frame is deallocated, leaving just `foo()` and
 And then `foo()` ends, leaving just `main()`
 
 | Address | Name | Value |
-+---------+------+-------+
+|---------|------|-------|
 | 0       | x    | 42    |
 
 And then we’re done. Getting the hang of it? It’s like piling up dishes: you
@@ -206,7 +206,7 @@ fn main() {
 Here’s what happens in memory when `main()` is called:
 
 | Address | Name | Value  |
-+---------+------+--------+
+|---------|------|--------|
 | 1       | y    | 42     |
 | 0       | x    | ?????? |
 
@@ -218,7 +218,7 @@ it allocates some memory for the heap, and puts `5` there. The memory now looks
 like this:
 
 | Address         | Name | Value          |
-+-----------------+------+----------------+
+|-----------------|------|----------------|
 | 2<sup>30</sup>  |      | 5              |
 | ...             | ...  | ...            |
 | 1               | y    | 42             |
@@ -243,7 +243,7 @@ layout of a program which has been running for a while now:
 
 
 | Address              | Name | Value                |
-+----------------------+------+----------------------+
+|----------------------|------|----------------------|
 | 2<sup>30</sup>       |      | 5                    |
 | (2<sup>30</sup>) - 1 |      |                      |
 | (2<sup>30</sup>) - 2 |      |                      |
@@ -266,13 +266,13 @@ Rust programs use [jemalloc][jemalloc] for this purpose.
 Anyway, back to our example. Since this memory is on the heap, it can stay
 alive longer than the function which allocates the box. In this case, however,
 it doesn’t.[^moving] When the function is over, we need to free the stack frame
-for `main()`. `Box<T>`, though, has a trick up its sleve: [Drop][drop]. The
+for `main()`. `Box<T>`, though, has a trick up its sleeve: [Drop][drop]. The
 implementation of `Drop` for `Box` deallocates the memory that was allocated
 when it was created. Great! So when `x` goes away, it first frees the memory
 allocated on the heap:
 
 | Address | Name | Value  |
-+---------+------+--------+
+|---------|------|--------|
 | 1       | y    | 42     |
 | 0       | x    | ?????? |
 
@@ -305,7 +305,7 @@ fn main() {
 When we enter `main()`, memory looks like this:
 
 | Address | Name | Value |
-+---------+------+-------+
+|---------|------|-------|
 | 1       | y    | 0     |
 | 0       | x    | 5     |
 
@@ -315,7 +315,7 @@ memory location that `x` lives at, which in this case is `0`.
 What about when we call `foo()`, passing `y` as an argument?
 
 | Address | Name | Value |
-+---------+------+-------+
+|---------|------|-------|
 | 3       | z    | 42    |
 | 2       | i    | 0     |
 | 1       | y    | 0     |
@@ -367,7 +367,7 @@ fn main() {
 First, we call `main()`:
 
 | Address         | Name | Value          |
-+-----------------+------+----------------+
+|-----------------|------|----------------|
 | 2<sup>30</sup>  |      | 20             |
 | ...             | ...  | ...            |
 | 2               | j    | 0              |
@@ -380,7 +380,7 @@ value pointing there.
 Next, at the end of `main()`, `foo()` gets called:
 
 | Address         | Name | Value          |
-+-----------------+------+----------------+
+|-----------------|------|----------------|
 | 2<sup>30</sup>  |      | 20             |
 | ...             | ...  | ...            |
 | 5               | z    | 4              |
@@ -397,7 +397,7 @@ since `j` points at `h`.
 Next, `foo()` calls `baz()`, passing `z`:
 
 | Address         | Name | Value          |
-+-----------------+------+----------------+
+|-----------------|------|----------------|
 | 2<sup>30</sup>  |      | 20             |
 | ...             | ...  | ...            |
 | 7               | g    | 100            |
@@ -413,7 +413,7 @@ We’ve allocated memory for `f` and `g`. `baz()` is very short, so when it’s
 over, we get rid of its stack frame:
 
 | Address         | Name | Value          |
-+-----------------+------+----------------+
+|-----------------|------|----------------|
 | 2<sup>30</sup>  |      | 20             |
 | ...             | ...  | ...            |
 | 5               | z    | 4              |
@@ -426,7 +426,7 @@ over, we get rid of its stack frame:
 Next, `foo()` calls `bar()` with `x` and `z`:
 
 | Address              | Name | Value                |
-+----------------------+------+----------------------+
+|----------------------|------|----------------------|
 |  2<sup>30</sup>      |      | 20                   |
 | (2<sup>30</sup>) - 1 |      | 5                    |
 | ...                  | ...  | ...                  |
@@ -449,7 +449,7 @@ case, we set up the variables as usual.
 At the end of `bar()`, it calls `baz()`:
 
 | Address              | Name | Value                |
-+----------------------+------+----------------------+
+|----------------------|------|----------------------|
 |  2<sup>30</sup>      |      | 20                   |
 | (2<sup>30</sup>) - 1 |      | 5                    |
 | ...                  | ...  | ...                  |
@@ -473,7 +473,7 @@ far.
 After `baz()` is over, we get rid of `f` and `g`:
 
 | Address              | Name | Value                |
-+----------------------+------+----------------------+
+|----------------------|------|----------------------|
 |  2<sup>30</sup>      |      | 20                   |
 | (2<sup>30</sup>) - 1 |      | 5                    |
 | ...                  | ...  | ...                  |
@@ -493,7 +493,7 @@ Next, we return from `bar()`. `d` in this case is a `Box<T>`, so it also frees
 what it points to: (2<sup>30</sup>) - 1.
 
 | Address         | Name | Value          |
-+-----------------+------+----------------+
+|-----------------|------|----------------|
 |  2<sup>30</sup> |      | 20             |
 | ...             | ...  | ...            |
 | 5               | z    | 4              |
@@ -506,7 +506,7 @@ what it points to: (2<sup>30</sup>) - 1.
 And after that, `foo()` returns:
 
 | Address         | Name | Value          |
-+-----------------+------+----------------+
+|-----------------|------|----------------|
 |  2<sup>30</sup> |      | 20             |
 | ...             | ...  | ...            |
 | 2               | j    | 0              |