Some tidying up

Improving the use of 2nd and 3rd person
Adding a few contractions to make the text less formal
Tidying up some notes
Providing a little bit more clarification for Windows users

Author: Dangthrimble

src/doc/trpl/README.md

@@ -1,6 +1,6 @@
 % The Rust Programming Language
 
-Welcome! This book will teach us about the [Rust Programming Language][rust].
+Welcome! This book will teach you about the [Rust Programming Language][rust].
 Rust is a systems programming language focused on three goals: safety, speed,
 and concurrency. It maintains these goals without having a garbage collector,
 making it a useful language for a number of use cases other languages aren’t
@@ -17,7 +17,7 @@ Even then, Rust still allows precise control like a low-level language would.
 “The Rust Programming Language” is split into eight sections. This introduction
 is the first. After this:
 
-* [Getting started][gs] - Set up our computer for Rust development.
+* [Getting started][gs] - Set up your computer for Rust development.
 * [Learn Rust][lr] - Learn Rust programming through small projects.
 * [Effective Rust][er] - Higher-level concepts for writing excellent Rust code.
 * [Syntax and Semantics][ss] - Each bit of Rust, broken down into small chunks.
@@ -33,11 +33,11 @@ is the first. After this:
 [gl]: glossary.html
 [bi]: bibliography.html
 
-After reading this introduction, we’ll want to dive into either ‘Learn Rust’ or
-‘Syntax and Semantics’, depending on our preference: ‘Learn Rust’ if we want to
-dive in with a project, or ‘Syntax and Semantics’ if we prefer to start small,
-and learn a single concept thoroughly before moving onto the next. Copious
-cross-linking connects these parts together.
+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
 
@@ -46,7 +46,7 @@ The source files from which this book is generated can be found on Github:
 
 ## A brief introduction to Rust
 
-Is Rust a language we might be interested in? Let’s examine a few small code
+Is Rust a language you might be interested in? Let’s examine a few small code
 samples to show off a few of its strengths.
 
 The main concept that makes Rust unique is called ‘ownership’. Consider this
@@ -76,7 +76,7 @@ annotating types.
 
 Rust prefers stack allocation to heap allocation: `x` is placed directly on the
 stack. However, the `Vec<T>` type allocates space for the elements of the vector
-on the heap. If we’re not familiar with this distinction, we can ignore it for
+on the heap. If you’re not familiar with this distinction, you can ignore it for
 now, or check out [‘The Stack and the Heap’][heap]. As a systems programming
 language, Rust gives us the ability to control how our memory is allocated, but
 when we’re getting started, it’s less of a big deal.
@@ -104,13 +104,13 @@ fn main() {
 }
 ```
 
-We’ve introduced another binding, `y`. In this case, `y` is a ‘reference’ to
-the first element of the vector. Rust’s references are similar to pointers in
-other languages, but with additional compile-time safety checks. References
-interact with the ownership system by [‘borrowing’][borrowing] what they point
-to, rather than owning it. The difference is, when the reference goes out of
-scope, it will not deallocate the underlying memory. If it did, we’d
-de-allocate twice, which is bad!
+We’ve introduced another binding, `y`. In this case, `y` is a ‘reference’ to the
+first element of the vector. Rust’s references are similar to pointers in other
+languages, but with additional compile-time safety checks. References interact
+with the ownership system by [‘borrowing’][borrowing] what they point to, rather
+than owning it. The difference is, when the reference goes out of scope, it
+won't deallocate the underlying memory. If it did, we’d de-allocate twice, which
+is bad!
 
 [borrowing]: references-and-borrowing.html
 
@@ -146,7 +146,7 @@ fn main() {
 
 Whew! The Rust compiler gives quite detailed errors at times, and this is one
 of those times. As the error explains, while we made our binding mutable, we
-still cannot call `push`. This is because we already have a reference to an
+still can't call `push`. This is because we already have a reference to an
 element of the vector, `y`. Mutating something while another reference exists
 is dangerous, because we may invalidate the reference. In this specific case,
 when we create the vector, we may have only allocated space for two elements.

src/doc/trpl/hello-cargo.md

@@ -13,9 +13,10 @@ any dependencies, so we’ll only be using the first part of its functionality.
 Eventually, we’ll add more. Since we started off by using Cargo, it'll be easy
 to add later.
 
-If we installed Rust via the official installers we will also have Cargo. If we
-installed Rust some other way, we may want to [check the Cargo
-README][cargoreadme] for specific instructions about installing it.
+If you installed Rust via the official installers you will also have Cargo. If
+you installed Rust some other way, you may want to
+[check the Cargo README][cargoreadme] for specific instructions about installing
+it.
 
 [cargoreadme]: https://github.com/rust-lang/cargo#installing-cargo-from-nightlies
 
@@ -30,14 +31,14 @@ old executable (`main.exe` on Windows, `main` everywhere else). Let's do that pa
 ```bash
 $ mkdir src
 $ mv main.rs src/main.rs
-$ rm main  # or main.exe on Windows
+$ rm main  # or 'rm main.exe' on Windows
 ```
 
-Note that since we're creating an executable, we retain `main.rs` as the source
-filename. If we want to make a library instead, we should use `lib.rs`. This
-convention is used by Cargo to successfully compile our projects, but it can be
-overridden if we wish. Custom file locations for the entry point can be
-specified with a [`[lib]` or `[[bin]]`][crates-custom] key in the TOML file.
+> Note: since we're creating an executable, we retain `main.rs` as the source
+> filename. If we want to make a library instead, we should use `lib.rs`. This
+> convention is used by Cargo to successfully compile our projects, but it can
+> be overridden if we wish. Custom file locations for the entry point can be
+> specified with a [`[lib]` or `[[bin]]`][crates-custom] key in the TOML file.
 
 [crates-custom]: http://doc.crates.io/manifest.html#configuring-a-target
 
@@ -49,7 +50,7 @@ everything, and everything in its place.
 Next, our configuration file:
 
 ```bash
-$ editor Cargo.toml
+$ editor Cargo.toml # or 'notepad Cargo.toml' on Windows
 ```
 
 Make sure to get this name right: we need the capital `C`!
@@ -112,7 +113,7 @@ grows, we can just run `cargo build`, and it’ll work the right way.
 When our project is finally ready for release, we can use `cargo build
 --release` to compile our project with optimizations.
 
-We'll also notice that Cargo has created a new file: `Cargo.lock`.
+You'll also notice that Cargo has created a new file: `Cargo.lock`.
 
 ```toml
 [root]
@@ -141,7 +142,7 @@ We don’t have to go through this whole process every time we want to start a n
 project! Cargo has the ability to make a bare-bones project directory in which
 we can start developing right away.
 
-To start a new project with Cargo, use `cargo new`:
+To start a new project with Cargo, we use `cargo new`:
 
 ```bash
 $ cargo new hello_world --bin
@@ -178,8 +179,8 @@ authors = ["Your Name <you@example.com>"]
 ```
 
 Cargo has populated this file with reasonable defaults based off the arguments
-we gave it and our `git` global configuration. We may notice that Cargo has also
-initialized the `hello_world` directory as a `git` repository.
+we gave it and our `git` global configuration. You may notice that Cargo has
+also initialized the `hello_world` directory as a `git` repository.
 
 Here’s what’s in `src/main.rs`:
 
@@ -199,11 +200,11 @@ Now that we’ve got the tools down, let’s actually learn more about the Rust
 language itself. These are the basics that will serve us well through the rest
 of our time with Rust.
 
-We have two options: Dive into a project with ‘[Learn Rust][learnrust]’, or
-start from the bottom and work our way up with ‘[Syntax and Semantics][syntax]’.
-More experienced systems programmers will probably prefer ‘Learn Rust’, while
-those from dynamic backgrounds may enjoy either. Different people learn
-differently! Choose whatever’s right for us.
+You have two options: Dive into a project with ‘[Learn Rust][learnrust]’, or
+start from the bottom and work your way up with
+‘[Syntax and Semantics][syntax]’. More experienced systems programmers will
+probably prefer ‘Learn Rust’, while those from dynamic backgrounds may enjoy
+either. Different people learn differently! Choose whatever’s right for you.
 
 [learnrust]: learn-rust.html
 [syntax]: syntax-and-semantics.html

src/doc/trpl/hello-world.md

@@ -9,7 +9,7 @@ thing to do.
 
 The first thing that we need to do is make a file to put our code in. I like to
 make a `projects` directory in my home directory, and keep all my projects
-there. Rust does not care where our code lives.
+there. Rust doesn't care where our code lives.
 
 This actually leads to one other concern we should address: this guide will
 assume that we have basic familiarity with the command line. Rust itself makes
@@ -71,10 +71,10 @@ were arguments, they would go inside the parentheses (`(` and `)`), and because
 we aren’t returning anything from this function, we can omit the return type
 entirely. We’ll get to it later.
 
-We’ll also note that the function is wrapped in curly braces (`{` and `}`). Rust
-requires these around all function bodies. It is also considered good style to
-put the opening curly brace on the same line as the function declaration, with
-one space in between.
+You’ll also note that the function is wrapped in curly braces (`{` and `}`).
+Rust requires these around all function bodies. It is also considered good style
+to put the opening curly brace on the same line as the function declaration,
+with one space in between.
 
 Next up is this line:
 
@@ -84,29 +84,29 @@ Next up is this line:
 
 This line does all of the work in our little program. There are a number of
 details that are important here. The first is that it’s indented with four
-spaces, not tabs. Please configure our editor of choice to insert four spaces
-with the tab key. We provide some [sample configurations for various
-editors][configs].
+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][configs].
 
 [configs]: https://github.com/rust-lang/rust/tree/master/src/etc/CONFIGS.md
 
 The second point is the `println!()` part. This is calling a Rust
 [macro][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, we’ll see a `!`,
-and that means that we’re calling a macro instead of a normal function. Rust
-implements `println!` as a macro rather than a function for good reasons, but
-that's an advanced topic. One last thing to mention: Rust’s macros are
-significantly different from C macros, if we’ve used those. Don’t be scared of
-using macros. We’ll get to the details eventually, we’ll just have to take it on
-trust for now.
+don’t need to worry about this difference. Just know that sometimes, we’ll see a
+`!`, and that means that we’re calling a macro instead of a normal function.
+Rust implements `println!` as a macro rather than a function for good reasons,
+but that's an advanced topic. One 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 take it
+on trust for now.
 
 [macro]: macros.html
 
 Next, `"Hello, world!"` is a ‘string’. Strings are a surprisingly complicated
 topic in a systems programming language, and this is a ‘statically allocated’
-string. If we want to read further about allocation, check out [the stack and
-the heap][allocation], but we don’t need to right now if we don’t want to. We
+string. If you want to read further about allocation, check out [the stack and
+the heap][allocation], but you don’t need to right now if you don’t want to. We
 pass this string as an argument to `println!`, which prints the string to the
 screen. Easy enough!
 
@@ -127,8 +127,8 @@ compiler, `rustc`, by passing it the name of our source file:
 $ rustc main.rs
 ```
 
-This is similar to `gcc` or `clang`, if we come from a C or C++ background. Rust
-will output a binary executable. We can see it with `ls`:
+This is similar to `gcc` or `clang`, if you come from a C or C++ background.
+Rust will output a binary executable. We can see it with `ls`:
 
 ```bash
 $ ls
@@ -151,18 +151,19 @@ $ ./main  # or main.exe on Windows
 
 This prints out our `Hello, world!` text to our terminal.
 
-If we come from a dynamic language like Ruby, Python, or JavaScript, we may not
-be used to these two steps being separate. Rust is an ‘ahead-of-time compiled
-language’, which means that we can compile a program, give it to someone else,
-and they don't need to have Rust installed. If we give someone a `.rb` or `.py`
-or `.js` file, they need to have a Ruby/Python/JavaScript implementation
-installed, but we just need one command to both compile and run our program.
-Everything is a tradeoff in language design, and Rust has made its choice.
+If you come from a dynamic 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 we can compile a program, give it to
+someone else, and they don't need to have Rust installed. If we give someone a
+`.rb` or `.py` or `.js` file, they need to have a Ruby/Python/JavaScript
+implementation installed, but we just need one command to both compile and run
+our program. Everything is a tradeoff in language design, and Rust has made its
+choice.
 
-Congratulations! We have officially written a Rust program. That makes us Rust
-programmers! Welcome. 🎊🎉👍
+Congratulations! You have officially written a Rust program. That makes you a
+Rust programmer! Welcome. 🎊🎉👍
 
-Next, I'd like to introduce us to another tool, Cargo, which is used to write
+Next, I'd like to introduce you to another tool, Cargo, which is used to write
 real-world Rust programs. Just using `rustc` is nice for simple things, but as
 our project grows, we'll want something to help us manage all of the options
 that it has, and to make it easy to share our code with other people and

src/doc/trpl/installing-rust.md

@@ -24,45 +24,46 @@ $ sh rustup.sh
 
 [insecurity]: http://curlpipesh.tumblr.com
 
-If we're on Windows, please download the appropriate [installer][install-page].
-**NOTE:** By default, the Windows installer will not add Rust to the %PATH%
-system variable. If this is the only version of Rust we are installing and we
-want to be able to run it from the command line, click on "Advanced" on the
-install dialog and on the "Product Features" page ensure "Add to PATH" is
-installed on the local hard drive.
+If you're on Windows, please download the appropriate [installer][install-page].
+
+> Note: By default, the Windows installer won't add Rust to the %PATH% system
+> variable. If this is the only version of Rust we are installing and we want to
+> be able to run it from the command line, click on "Advanced" on the install
+> dialog and on the "Product Features" page ensure "Add to PATH" is installed on
+> the local hard drive.
 
 
 [install-page]: https://www.rust-lang.org/install.html
 
 ## Uninstalling
 
-If we decide we don't want Rust anymore, we'll be a bit sad, but that's okay.
-Not every programming language is great for everyone. Just run the uninstall
-script:
+If you decide you don't want Rust anymore, we'll be a bit sad, but that's okay.
+Not every programming language is great for everyone. We'll just run the
+uninstall script:
 
 ```bash
 $ sudo /usr/local/lib/rustlib/uninstall.sh
 ```
 
-If we used the Windows installer, just re-run the `.msi` and it will give us an
-uninstall option.
+If we used the Windows installer, we'll just re-run the `.msi` and it will give
+us an uninstall option.
 
 ## That disclaimer we promised
 
 Some people, and somewhat rightfully so, get very upset when we tell them to
-`curl | sh`. Basically, when we do this, we are trusting that the good people
-who maintain Rust aren't going to hack our computer and do bad things. That's a
-good instinct! If we're one of those people, please check out the documentation
-on [building Rust from Source][from-source], or [the official binary
-downloads][install-page].
+`curl | sh`. Basically, when they do this, they are trusting that the good
+people who maintain Rust aren't going to hack their computer and do bad things.
+That's a good instinct! If you're one of those people, please check out the
+documentation on [building Rust from Source][from-source], or [the official
+binary downloads][install-page].
 
 [from-source]: https://github.com/rust-lang/rust#building-from-source
 
 ## Platform support
 
 Oh, we should also mention the officially supported platforms:
 
-* Windows (7, 8, Server 2008 R2)
+* Windows (7 or later, Server 2008 R2)
 * Linux (2.6.18 or later, various distributions), x86 and x86-64
 * OSX 10.7 (Lion) or later, x86 and x86-64
 
@@ -73,7 +74,7 @@ testing.
 Finally, a comment about Windows. Rust considers Windows to be a first-class
 platform upon release, but if we're honest, the Windows experience isn't as
 integrated as the Linux/OS X experience is. We're working on it! If anything
-does not work, it is a bug. Please let us know if that happens. Each and every
+doesn't work, it is a bug. Please let us know if that happens. Each and every
 commit is tested against Windows just like any other platform.
 
 ## After installation