auto merge of rust-lang#20782 : iKevinY/rust/trpl-formatting, r=steve…

…klabnik

Here's my PR for the changes discussed in rust-lang#19823. I decided to leave `_these_` types of italics the way there were because it differentiates the use of italics for emphasis from `*key term*` italics. Otherwise, bolded terms have been changed to italics, and single and double quotes have been changed appropriately, depending on their context (my judgement may not be the best, though).

r? @steveklabnik (congratulations on rust-lang#19897 being finalized and merged, by the way!)

src/doc/trpl/arrays-vectors-and-slices.md

@@ -1,7 +1,7 @@
 % Arrays, Vectors, and Slices
 
 Like many programming languages, Rust has list types to represent a sequence of
-things. The most basic is the **array**, a fixed-size list of elements of the
+things. The most basic is the *array*, a fixed-size list of elements of the
 same type. By default, arrays are immutable.
 
 ```{rust}
@@ -32,7 +32,7 @@ for e in a.iter() {
 }
 ```
 
-You can access a particular element of an array with **subscript notation**:
+You can access a particular element of an array with *subscript notation*:
 
 ```{rust}
 let names = ["Graydon", "Brian", "Niko"]; // names: [&str; 3]
@@ -47,7 +47,7 @@ array, you will get an error: array access is bounds-checked at run-time. Such
 errant access is the source of many bugs in other systems programming
 languages.
 
-A **vector** is a dynamic or "growable" array, implemented as the standard
+A *vector* is a dynamic or "growable" array, implemented as the standard
 library type [`Vec<T>`](../std/vec/) (we'll talk about what the `<T>` means
 later). Vectors are to arrays what `String` is to `&str`. You can create them
 with the `vec!` macro:
@@ -73,7 +73,7 @@ println!("The length of nums is now {}", nums.len());   // Prints 4
 
 Vectors have many more useful methods.
 
-A **slice** is a reference to (or "view" into) an array. They are useful for
+A *slice* is a reference to (or "view" into) an array. They are useful for
 allowing safe, efficient access to a portion of an array without copying. For
 example, you might want to reference just one line of a file read into memory.
 By nature, a slice is not created directly, but from an existing variable.

src/doc/trpl/closures.md

@@ -2,7 +2,7 @@
 
 So far, we've made lots of functions in Rust, but we've given them all names.
 Rust also allows us to create anonymous functions. Rust's anonymous
-functions are called **closure**s. By themselves, closures aren't all that
+functions are called *closures*. By themselves, closures aren't all that
 interesting, but when you combine them with functions that take closures as
 arguments, really powerful things are possible.
 
@@ -61,7 +61,7 @@ fn main() {
 
 ## Moving closures
 
-Rust has a second type of closure, called a **moving closure**. Moving
+Rust has a second type of closure, called a *moving closure*. Moving
 closures are indicated using the `move` keyword (e.g., `move || x *
 x`). The difference between a moving closure and an ordinary closure
 is that a moving closure always takes ownership of all variables that

src/doc/trpl/comments.md

@@ -4,8 +4,8 @@ Now that we have some functions, it's a good idea to learn about comments.
 Comments are notes that you leave to other programmers to help explain things
 about your code. The compiler mostly ignores them.
 
-Rust has two kinds of comments that you should care about: **line comment**s
-and **doc comment**s.
+Rust has two kinds of comments that you should care about: *line comments*
+and *doc comments*.
 
 ```{rust}
 // Line comments are anything after '//' and extend to the end of the line.

src/doc/trpl/compound-data-types.md

@@ -6,7 +6,7 @@ strings, but next, let's talk about some more complicated ways of storing data.
 
 ## Tuples
 
-The first compound data type we're going to talk about are called **tuple**s.
+The first compound data type we're going to talk about are called *tuples*.
 Tuples are an ordered list of a fixed size. Like this:
 
 ```rust
@@ -25,10 +25,10 @@ position having a type name rather than the value. Careful readers will also
 note that tuples are heterogeneous: we have an `i32` and a `&str` in this tuple.
 You haven't seen `&str` as a type before, and we'll discuss the details of
 strings later. In systems programming languages, strings are a bit more complex
-than in other languages. For now, just read `&str` as "a string slice," and
+than in other languages. For now, just read `&str` as a *string slice*, and
 we'll learn more soon.
 
-You can access the fields in a tuple through a **destructuring let**. Here's
+You can access the fields in a tuple through a *destructuring let*. Here's
 an example:
 
 ```rust
@@ -40,8 +40,8 @@ println!("x is {}", x);
 Remember before when I said the left-hand side of a `let` statement was more
 powerful than just assigning a binding? Here we are. We can put a pattern on
 the left-hand side of the `let`, and if it matches up to the right-hand side,
-we can assign multiple bindings at once. In this case, `let` 'destructures,'
-or 'breaks up,' the tuple, and assigns the bits to three bindings.
+we can assign multiple bindings at once. In this case, `let` "destructures,"
+or "breaks up," the tuple, and assigns the bits to three bindings.
 
 This pattern is very powerful, and we'll see it repeated more later.
 
@@ -83,18 +83,18 @@ fn main() {
 }
 ```
 
-Even though Rust functions can only return one value, a tuple _is_ one value,
-that happens to be made up of more than one value. You can also see in this example how you
-can destructure a pattern returned by a function, as well.
+Even though Rust functions can only return one value, a tuple *is* one value,
+that happens to be made up of more than one value. You can also see in this
+example how you can destructure a pattern returned by a function, as well.
 
 Tuples are a very simple data structure, and so are not often what you want.
 Let's move on to their bigger sibling, structs.
 
 ## Structs
 
-A struct is another form of a 'record type,' just like a tuple. There's a
+A struct is another form of a *record type*, just like a tuple. There's a
 difference: structs give each element that they contain a name, called a
-'field' or a 'member.' Check it out:
+*field* or a *member*. Check it out:
 
 ```rust
 struct Point {
@@ -143,8 +143,7 @@ This will print `The point is at (5, 0)`.
 ## Tuple Structs and Newtypes
 
 Rust has another data type that's like a hybrid between a tuple and a struct,
-called a **tuple struct**. Tuple structs do have a name, but their fields
-don't:
+called a *tuple struct*. Tuple structs do have a name, but their fields don't:
 
 
 ```{rust}
@@ -182,7 +181,7 @@ Now, we have actual names, rather than positions. Good names are important,
 and with a struct, we have actual names.
 
 There _is_ one case when a tuple struct is very useful, though, and that's a
-tuple struct with only one element. We call this a 'newtype,' because it lets
+tuple struct with only one element. We call this a *newtype*, because it lets
 you create a new type that's a synonym for another one:
 
 ```{rust}
@@ -199,7 +198,7 @@ destructuring `let`.
 
 ## Enums
 
-Finally, Rust has a "sum type", an **enum**. Enums are an incredibly useful
+Finally, Rust has a "sum type", an *enum*. Enums are an incredibly useful
 feature of Rust, and are used throughout the standard library. This is an enum
 that is provided by the Rust standard library:
 

src/doc/trpl/crates-and-modules.md

@@ -8,17 +8,17 @@ these kinds of things, Rust has a module system.
 
 # Basic terminology: Crates and Modules
 
-Rust has two distinct terms that relate to the module system: "crate" and
-"module." A crate is synonymous with a 'library' or 'package' in other
+Rust has two distinct terms that relate to the module system: *crate* and
+*module*. A crate is synonymous with a *library* or *package* in other
 languages. Hence "Cargo" as the name of Rust's package management tool: you
 ship your crates to others with Cargo. Crates can produce an executable or a
 shared library, depending on the project.
 
-Each crate has an implicit "root module" that contains the code for that crate.
+Each crate has an implicit *root module* that contains the code for that crate.
 You can then define a tree of sub-modules under that root module. Modules allow
 you to partition your code within the crate itself.
 
-As an example, let's make a "phrases" crate, which will give us various phrases
+As an example, let's make a *phrases* crate, which will give us various phrases
 in different languages. To keep things simple, we'll stick to "greetings" and
 "farewells" as two kinds of phrases, and use English and Japanese (日本語） as
 two languages for those phrases to be in. We'll use this module layout:
@@ -45,7 +45,7 @@ two languages for those phrases to be in. We'll use this module layout:
 
 In this example, `phrases` is the name of our crate. All of the rest are
 modules.  You can see that they form a tree, branching out from the crate
-"root", which is the root of the tree: `phrases` itself.
+*root*, which is the root of the tree: `phrases` itself.
 
 Now that we have a plan, let's define these modules in code. To start,
 generate a new crate with Cargo:

src/doc/trpl/error-handling.md

@@ -16,10 +16,10 @@ how to handle each. Then, we'll discuss upgrading failures to panics.
 # Failure vs. Panic
 
 Rust uses two terms to differentiate between two forms of error: failure, and
-panic. A **failure** is an error that can be recovered from in some way. A
-**panic** is an error that cannot be recovered from.
+panic. A *failure* is an error that can be recovered from in some way. A
+*panic* is an error that cannot be recovered from.
 
-What do we mean by 'recover'? Well, in most cases, the possibility of an error
+What do we mean by "recover"? Well, in most cases, the possibility of an error
 is expected. For example, consider the `from_str` function:
 
 ```{rust,ignore}
@@ -35,7 +35,7 @@ from_str("hello5world");
 ```
 
 This won't work. So we know that this function will only work properly for some
-inputs. It's expected behavior. We call this kind of error 'failure.'
+inputs. It's expected behavior. We call this kind of error a *failure*.
 
 On the other hand, sometimes, there are errors that are unexpected, or which
 we cannot recover from. A classic example is an `assert!`:
@@ -46,7 +46,7 @@ assert!(x == 5);
 
 We use `assert!` to declare that something is true. If it's not true, something
 is very wrong. Wrong enough that we can't continue with things in the current
-state. Another example is using the `unreachable!()` macro
+state. Another example is using the `unreachable!()` macro:
 
 ```{rust,ignore}
 enum Event {
@@ -114,7 +114,7 @@ fn main() {
 
 We shouldn't ever hit the `_` case, so we use the `unreachable!()` macro to
 indicate this. `unreachable!()` gives a different kind of error than `Result`.
-Rust calls these sorts of errors 'panics.'
+Rust calls these sorts of errors *panics*.
 
 # Handling errors with `Option` and `Result`
 

src/doc/trpl/ffi.md

@@ -166,7 +166,7 @@ GitHub](https://github.com/thestinger/rust-snappy).
 
 # Stack management
 
-Rust tasks by default run on a "large stack". This is actually implemented as a
+Rust tasks by default run on a *large stack*. This is actually implemented as a
 reserving a large segment of the address space and then lazily mapping in pages
 as they are needed. When calling an external C function, the code is invoked on
 the same stack as the rust stack. This means that there is no extra

src/doc/trpl/functions.md

@@ -8,7 +8,7 @@ fn main() {
 ```
 
 This is the simplest possible function declaration. As we mentioned before,
-`fn` says 'this is a function,' followed by the name, some parentheses because
+`fn` says "this is a function," followed by the name, some parentheses because
 this function takes no arguments, and then some curly braces to indicate the
 body. Here's a function named `foo`:
 
@@ -86,7 +86,7 @@ fn add_one(x: i32) -> i32 {
 ```
 
 Rust functions return exactly one value, and you declare the type after an
-'arrow', which is a dash (`-`) followed by a greater-than sign (`>`).
+"arrow," which is a dash (`-`) followed by a greater-than sign (`>`).
 
 You'll note the lack of a semicolon here. If we added it in:
 

src/doc/trpl/generics.md

@@ -20,9 +20,9 @@ enum OptionalFloat64 {
 ```
 
 This is really unfortunate. Luckily, Rust has a feature that gives us a better
-way: generics. Generics are called **parametric polymorphism** in type theory,
-which means that they are types or functions that have multiple forms ("poly"
-is multiple, "morph" is form) over a given parameter ("parametric").
+way: generics. Generics are called *parametric polymorphism* in type theory,
+which means that they are types or functions that have multiple forms (*poly*
+is multiple, *morph* is form) over a given parameter (*parametric*).
 
 Anyway, enough with type theory declarations, let's check out the generic form
 of `OptionalInt`. It is actually provided by Rust itself, and looks like this:
@@ -150,7 +150,7 @@ fn inverse32(x: f32) -> Result<f32, String> {
 }
 ```
 
-Bummer. What we need is a **generic function**. Luckily, we can write one!
+Bummer. What we need is a *generic function*. Luckily, we can write one!
 However, it won't _quite_ work yet. Before we get into that, let's talk syntax.
 A generic version of `inverse` would look something like this:
 

src/doc/trpl/guessing-game.md

@@ -111,7 +111,7 @@ Enter the docs. Rust has a page specifically to document the standard library.
 You can find that page [here](../std/index.html). There's a lot of information on
 that page, but the best part is the search bar. Right up at the top, there's
 a box that you can enter in a search term. The search is pretty primitive
-right now, but is getting better all the time. If you type 'random' in that
+right now, but is getting better all the time. If you type "random" in that
 box, the page will update to [this one](../std/index.html?search=random). The very
 first result is a link to [`std::rand::random`](../std/rand/fn.random.html). If we
 click on that result, we'll be taken to its documentation page.
@@ -147,7 +147,7 @@ explained.  We then added in a `let` expression to create a variable binding
 named `secret_number`, and we printed out its result.
 
 Also, you may wonder why we are using `%` on the result of `rand::random()`.
-This operator is called 'modulo', and it returns the remainder of a division.
+This operator is called *modulo*, and it returns the remainder of a division.
 By taking the modulo of the result of `rand::random()`, we're limiting the
 values to be between 0 and 99. Then, we add one to the result, making it from 1
 to 100. Using modulo can give you a very, very small bias in the result, but
@@ -608,8 +608,8 @@ out that I guessed 76. Run the program a few times, and verify that guessing
 the number works, as well as guessing a number too small.
 
 The Rust compiler helped us out quite a bit there! This technique is called
-"lean on the compiler", and it's often useful when working on some code. Let
-the error messages help guide you towards the correct types.
+"leaning on the compiler", and it's often useful when working on some code.
+Let the error messages help guide you towards the correct types.
 
 Now we've got most of the game working, but we can only make one guess. Let's
 change that by adding loops!

src/doc/trpl/hello-cargo.md

@@ -66,7 +66,7 @@ it explain itself to you:
 
 TOML is very similar to INI, but with some extra goodies.
 
-Anyway, there are two **table**s in this file: `package` and `bin`. The first
+Anyway, there are two *tables* in this file: `package` and `bin`. The first
 tells Cargo metadata about your package. The second tells Cargo that we're
 interested in building a binary, not a library (though we could do both!), as
 well as what it is named.

src/doc/trpl/hello-world.md

@@ -67,7 +67,7 @@ fn main() {
 }
 ```
 
-These lines define a **function** in Rust. The `main` function is special:
+These lines define a *function* in Rust. The `main` function is special:
 it's the beginning of every Rust program. The first line says "I'm declaring a
 function named `main`, which takes no arguments and returns nothing." If there
 were arguments, they would go inside the parentheses (`(` and `)`), and because
@@ -91,7 +91,7 @@ spaces, not tabs. Please configure your editor of choice to insert four spaces
 with the tab key. We provide some [sample configurations for various
 editors](https://github.com/rust-lang/rust/tree/master/src/etc).
 
-The second point is the `println!()` part. This is calling a Rust **macro**,
+The second point is the `println!()` part. This is calling a Rust *macro*,
 which is how metaprogramming is done in Rust. If it were a function instead, it
 would look like this: `println()`. For our purposes, we don't need to worry
 about this difference. Just know that sometimes, you'll see a `!`, and that
@@ -102,19 +102,19 @@ last thing to mention: Rust's macros are significantly different from C macros,
 if you've used those. Don't be scared of using macros. We'll get to the details
 eventually, you'll just have to trust us for now.
 
-Next, `"Hello, world!"` is a **string**. Strings are a surprisingly complicated
-topic in a systems programming language, and this is a **statically allocated**
+Next, `"Hello, world!"` is a *string*. Strings are a surprisingly complicated
+topic in a systems programming language, and this is a *statically allocated*
 string. We will talk more about different kinds of allocation later. We pass
 this string as an argument to `println!`, which prints the string to the
 screen. Easy enough!
 
-Finally, the line ends with a semicolon (`;`). Rust is an **expression
-oriented** language, which means that most things are expressions. The `;` is
+Finally, the line ends with a semicolon (`;`). Rust is an *expression
+oriented* language, which means that most things are expressions. The `;` is
 used to indicate that this expression is over, and the next one is ready to
 begin. Most lines of Rust code end with a `;`. We will cover this in-depth
 later in the guide.
 
-Finally, actually **compiling** and **running** our program. We can compile
+Finally, actually *compiling* and *running* our program. We can compile
 with our compiler, `rustc`, by passing it the name of our source file:
 
 ```{bash}
@@ -147,7 +147,7 @@ This prints out our `Hello, world!` text to our terminal.
 
 If you come from a dynamically typed language like Ruby, Python, or JavaScript,
 you may not be used to these two steps being separate. Rust is an
-**ahead-of-time compiled language**, which means that you can compile a
+*ahead-of-time compiled language*, which means that you can compile a
 program, give it to someone else, and they don't need to have Rust installed.
 If you give someone a `.rb` or `.py` or `.js` file, they need to have
 Ruby/Python/JavaScript installed, but you just need one command to both compile