copyedits: patterns

This also puts slice patterns in nightly docs, where they belong.

3 files changed, 66 insertions, 51 deletions

diff --git a/src/doc/trpl/SUMMARY.md b/src/doc/trpl/SUMMARY.md
index 29210fa6c16..fb042b2704b 100644
--- a/src/doc/trpl/SUMMARY.md
+++ b/src/doc/trpl/SUMMARY.md
@@ -67,4 +67,5 @@
     * [Link args](link-args.md)
     * [Benchmark Tests](benchmark-tests.md)
     * [Box Syntax and Patterns](box-syntax-and-patterns.md)
+    * [Slice Patterns](slice-patterns.md)
 * [Glossary](glossary.md)
diff --git a/src/doc/trpl/patterns.md b/src/doc/trpl/patterns.md
index 4ebf696aa57..c88e3a0f9ed 100644
--- a/src/doc/trpl/patterns.md
+++ b/src/doc/trpl/patterns.md
@@ -1,13 +1,16 @@
 % Patterns
 
-We've made use of patterns a few times in the guide: first with `let` bindings,
-then with `match` statements. Let's go on a whirlwind tour of all of the things
-patterns can do!
+Patterns are quite common in Rust. We use them in [variable
+bindings][bindings], [match statements][match], and other places, too. Let’s go
+on a whirlwind tour of all of the things patterns can do!
+
+[bindings]: variable-bindings.html
+[match]: match.html
 
 A quick refresher: you can match against literals directly, and `_` acts as an
-*any* case:
+‘any’ case:
 
-```{rust}
+```rust
 let x = 1;
 
 match x {
@@ -18,9 +21,11 @@ match x {
 }
 ```
 
+# Multiple patterns
+
 You can match multiple patterns with `|`:
 
-```{rust}
+```rust
 let x = 1;
 
 match x {
@@ -30,9 +35,11 @@ match x {
 }
 ```
 
+# Ranges
+
 You can match a range of values with `...`:
 
-```{rust}
+```rust
 let x = 1;
 
 match x {
@@ -43,10 +50,12 @@ match x {
 
 Ranges are mostly used with integers and single characters.
 
-If you're matching multiple things, via a `|` or a `...`, you can bind
+# Bindings
+
+If you’re matching multiple things, via a `|` or a `...`, you can bind
 the value to a name with `@`:
 
-```{rust}
+```rust
 let x = 1;
 
 match x {
@@ -55,10 +64,12 @@ match x {
 }
 ```
 
-If you're matching on an enum which has variants, you can use `..` to
+# Ignoring variants
+
+If you’re matching on an enum which has variants, you can use `..` to
 ignore the value and type in the variant:
 
-```{rust}
+```rust
 enum OptionalInt {
     Value(i32),
     Missing,
@@ -72,9 +83,11 @@ match x {
 }
 ```
 
-You can introduce *match guards* with `if`:
+# Guards
+
+You can introduce ‘match guards’ with `if`:
 
-```{rust}
+```rust
 enum OptionalInt {
     Value(i32),
     Missing,
@@ -89,24 +102,11 @@ match x {
 }
 ```
 
-If you're matching on a pointer, you can use the same syntax as you declared it
-with. First, `&`:
-
-```{rust}
-let x = &5;
-
-match x {
-    &val => println!("Got a value: {}", val),
-}
-```
-
-Here, the `val` inside the `match` has type `i32`. In other words, the left-hand
-side of the pattern destructures the value. If we have `&5`, then in `&val`, `val`
-would be `5`.
+# ref and ref mut
 
-If you want to get a reference, use the `ref` keyword:
+If you want to get a [reference][ref], use the `ref` keyword:
 
-```{rust}
+```rust
 let x = 5;
 
 match x {
@@ -114,11 +114,13 @@ match x {
 }
 ```
 
+[ref]: references-and-borrowing.html
+
 Here, the `r` inside the `match` has the type `&i32`. In other words, the `ref`
 keyword _creates_ a reference, for use in the pattern. If you need a mutable
 reference, `ref mut` will work in the same way:
 
-```{rust}
+```rust
 let mut x = 5;
 
 match x {
@@ -126,10 +128,12 @@ match x {
 }
 ```
 
-If you have a struct, you can destructure it inside of a pattern:
+# Destructuring
+
+If you have a compound data type, like a `struct`, you can destructure it
+inside of a pattern:
 
-```{rust}
-# #![allow(non_shorthand_field_patterns)]
+```rust
 struct Point {
     x: i32,
     y: i32,
@@ -142,10 +146,9 @@ match origin {
 }
 ```
 
-If we only care about some of the values, we don't have to give them all names:
+If we only care about some of the values, we don’t have to give them all names:
 
-```{rust}
-# #![allow(non_shorthand_field_patterns)]
+```rust
 struct Point {
     x: i32,
     y: i32,
@@ -160,8 +163,7 @@ match origin {
 
 You can do this kind of match on any member, not just the first:
 
-```{rust}
-# #![allow(non_shorthand_field_patterns)]
+```rust
 struct Point {
     x: i32,
     y: i32,
@@ -174,22 +176,16 @@ match origin {
 }
 ```
 
-If you want to match against a slice or array, you can use `&`:
+This ‘destructuring’ behavior works on any compound data type, like
+[tuples][tuples] or [enums][enums].
 
-```{rust}
-# #![feature(slice_patterns)]
-fn main() {
-    let v = vec!["match_this", "1"];
+[tuples]: primitive-types.html#tuples
+[enums]: enums.html
 
-    match &v[..] {
-        ["match_this", second] => println!("The second element is {}", second),
-        _ => {},
-    }
-}
-```
+# Mix and Match
 
-Whew! That's a lot of different ways to match things, and they can all be
-mixed and matched, depending on what you're doing:
+Whew! That’s a lot of different ways to match things, and they can all be
+mixed and matched, depending on what you’re doing:
 
 ```{rust,ignore}
 match x {
diff --git a/src/doc/trpl/slice-patterns.md b/src/doc/trpl/slice-patterns.md
new file mode 100644
index 00000000000..4599333a77a
--- /dev/null
+++ b/src/doc/trpl/slice-patterns.md
@@ -0,0 +1,18 @@
+% Slice patterns
+
+If you want to match against a slice or array, you can use `&` with the
+`slice_patterns` feature:
+
+```rust
+#![feature(slice_patterns)]
+
+fn main() {
+    let v = vec!["match_this", "1"];
+
+    match &v[..] {
+        ["match_this", second] => println!("The second element is {}", second),
+        _ => {},
+    }
+}
+```
+