Auto merge of #28930 - steveklabnik:update_pr, r=steveklabnik

#27813 (comment)

Author: bors

src/doc/trpl/README.md

@@ -9,9 +9,8 @@ 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 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.
+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.
 
 [rust]: https://www.rust-lang.org
 
@@ -34,10 +33,10 @@ is the first. After this:
 [gl]: glossary.html
 [bi]: bibliography.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.
+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
@@ -76,11 +75,11 @@ type inference to balance out the power of static typing with the verbosity of
 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 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 you the ability to control how your memory is
-allocated, but when we’re getting started, it’s less of a big deal.
+stack. However, the `Vec<T>` type allocates space for the elements of the vector
+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.
 
 [var]: variable-bindings.html
 [macro]: macros.html
@@ -90,10 +89,10 @@ Earlier, we mentioned that ‘ownership’ is the key new concept in Rust. In Ru
 parlance, `x` is said to ‘own’ the vector. This means that when `x` goes out of
 scope, the vector’s memory will be de-allocated. This is done deterministically
 by the Rust compiler, rather than through a mechanism such as a garbage
-collector. In other words, in Rust, you don’t call functions like `malloc` and
-`free` yourself: the compiler statically determines when you need to allocate
-or deallocate memory, and inserts those calls itself. To err is to be human,
-but compilers never forget.
+collector. In other words, in Rust, we don’t call functions like `malloc` and
+`free` ourselves: the compiler statically determines when we need to allocate or
+deallocate memory, and inserts those calls itself. To err is to be human, but
+compilers never forget.
 
 Let’s add another line to our example:
 
@@ -105,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
 
@@ -147,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/getting-started.md

@@ -1,5 +1,5 @@
 % Getting Started
 
-This first section of the book will get you going with Rust and its tooling.
+This first section of the book will get us going with Rust and its tooling.
 First, we’ll install Rust. Then, the classic ‘Hello World’ program. Finally,
 we’ll talk about Cargo, Rust’s build system and package manager.

src/doc/trpl/hello-cargo.md

@@ -7,15 +7,16 @@ so it is assumed that Rust projects will use Cargo from the beginning.
 
 [cratesio]: http://doc.crates.io
 
-Cargo manages three things: building your code, downloading the dependencies
-your code needs, and building those dependencies. At first, your program doesn’t
-have 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.
+Cargo manages three things: building our code, downloading the dependencies our
+code needs, and building those dependencies. At first, our program doesn’t have
+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,29 +31,29 @@ 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
 
-Cargo expects your source files to live inside a `src` directory. That leaves
-the top level for other things, like READMEs, license information, and anything
-not related to your code. Cargo helps us keep our projects nice and tidy. A
-place for everything, and everything in its place.
+Cargo expects our source files to live inside a `src` directory. That leaves the
+top level for other things, like READMEs, license information, and anything not
+related to our code. Cargo helps us keep our projects nice and tidy. A place for
+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: you need the capital `C`!
+Make sure to get this name right: we need the capital `C`!
 
 Put this inside:
 
@@ -109,8 +110,8 @@ about the future: when our project gets more complex, we need to do more
 things to get all of the parts to properly compile. With Cargo, as our project
 grows, we can just run `cargo build`, and it’ll work the right way.
 
-When your project is finally ready for release, you can use
-`cargo build --release` to compile your project with optimizations.
+When our project is finally ready for release, we can use `cargo build
+--release` to compile our project with optimizations.
 
 You'll also notice that Cargo has created a new file: `Cargo.lock`.
 
@@ -120,14 +121,14 @@ name = "hello_world"
 version = "0.0.1"
 ```
 
-The `Cargo.lock` file is used by Cargo to keep track of dependencies in your application.
-Right now, we don’t have any, so it’s a bit sparse. You won't ever need
-to touch this file yourself, just let Cargo handle it.
+The `Cargo.lock` file is used by Cargo to keep track of dependencies in our
+application. Right now, we don’t have any, so it’s a bit sparse. We won't ever
+need to touch this file ourselves, just let Cargo handle it.
 
 That’s it! We’ve successfully built `hello_world` with Cargo. Even though our
-program is simple, it’s using much of the real tooling that you’ll use for the
-rest of your Rust career. You can expect to do this to get started with
-virtually all Rust projects:
+program is simple, it’s using much of the real tooling that we’ll use for the
+rest of our Rust career. We can expect to do this to get started with virtually
+all Rust projects:
 
 ```bash
 $ git clone someurl.com/foo
@@ -137,17 +138,19 @@ $ cargo build
 
 ## A New Project
 
-You don’t have to go through this whole process every time you want to start a
-new project! Cargo has the ability to make a bare-bones project directory in
-which you can start developing right away.
+We don’t have to go through this whole process every time we want to start a new
+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
 ```
 
-We’re passing `--bin` because our goal is to get straight to making an executable application, as opposed to a library. Executables are often called ‘binaries.’ (as in `/usr/bin`, if you’re on a Unix system)
+We’re passing `--bin` because our goal is to get straight to making an
+executable application, as opposed to a library. Executables are often called
+‘binaries.’ (as in `/usr/bin`, if we’re on a Unix system)
 
 Let's check out what Cargo has generated for us:
 
@@ -162,7 +165,7 @@ $ tree .
 1 directory, 2 files
 ```
 
-If you don't have the `tree` command, you can probably get it from your
+If we don't have the `tree` command, we can probably get it from our
 distribution’s package manager. It’s not necessary, but it’s certainly useful.
 
 This is all we need to get started. First, let’s check out `Cargo.toml`:
@@ -176,7 +179,7 @@ authors = ["Your Name <[email protected]>"]
 ```
 
 Cargo has populated this file with reasonable defaults based off the arguments
-you gave it and your `git` global configuration. You may notice that Cargo has
+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`:
@@ -187,20 +190,21 @@ fn main() {
 }
 ```
 
-Cargo has generated a "Hello World!" for us, and you’re ready to start coding! Cargo
-has its own [guide][guide] which covers Cargo’s features in much more depth.
+Cargo has generated a "Hello World!" for us, and we’re ready to start coding!
+Cargo has its own [guide][guide] which covers Cargo’s features in much more
+depth.
 
 [guide]: http://doc.crates.io/guide.html
 
-Now that you’ve got the tools down, let’s actually learn more about the Rust
-language itself. These are the basics that will serve you well through the rest
-of your time with Rust.
+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.
 
 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.
+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