From f116ab58b2d7e600d1530a25a41a64af2ca19c91 Mon Sep 17 00:00:00 2001 From: Jonathan Hansford Date: Thu, 13 Aug 2015 18:22:16 +0100 Subject: [PATCH] 2nd to 3rd person Replacing all references to the 2nd person with references to the 3rd person (excluding `authors = [ "Your name " ]` and `file:///home/yourname/projects/hello_world` in `hello-cargo.md`) --- src/doc/trpl/README.md | 39 ++++++------ src/doc/trpl/getting-started.md | 2 +- src/doc/trpl/hello-cargo.md | 75 +++++++++++----------- src/doc/trpl/hello-world.md | 106 ++++++++++++++++---------------- src/doc/trpl/installing-rust.md | 61 +++++++++--------- 5 files changed, 142 insertions(+), 141 deletions(-) diff --git a/src/doc/trpl/README.md b/src/doc/trpl/README.md index 0feaf9c6bbf..866a529dc18 100644 --- a/src/doc/trpl/README.md +++ b/src/doc/trpl/README.md @@ -1,6 +1,6 @@ % The Rust Programming Language -Welcome! This book will teach you about the [Rust Programming Language][rust]. +Welcome! This book will teach us 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 @@ -9,16 +9,15 @@ 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 “The Rust Programming Language” is split into eight sections. This introduction is the first. After this: -* [Getting started][gs] - Set up your computer for Rust development. +* [Getting started][gs] - Set up our 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. @@ -34,11 +33,11 @@ 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. -Copious cross-linking connects these parts together. +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. ### Contributing @@ -47,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 you might be interested in? Let’s examine a few small code +Is Rust a language we 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,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` 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` 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 +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: diff --git a/src/doc/trpl/getting-started.md b/src/doc/trpl/getting-started.md index d0825e543f2..549f8c3ca57 100644 --- a/src/doc/trpl/getting-started.md +++ b/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. diff --git a/src/doc/trpl/hello-cargo.md b/src/doc/trpl/hello-cargo.md index 4bd7de23f0c..939392466c0 100644 --- a/src/doc/trpl/hello-cargo.md +++ b/src/doc/trpl/hello-cargo.md @@ -7,11 +7,11 @@ 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 @@ -41,10 +41,10 @@ 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: @@ -52,7 +52,7 @@ Next, our configuration file: $ editor Cargo.toml ``` -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,10 +109,10 @@ 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`. +We'll also notice that Cargo has created a new file: `Cargo.lock`. ```toml [root] @@ -120,14 +120,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,9 +137,9 @@ $ 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`: @@ -147,7 +147,9 @@ To start a new project with Cargo, use `cargo new`: $ 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 +164,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,8 +178,8 @@ authors = ["Your Name "] ``` 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 -also initialized the `hello_world` directory as a `git` repository. +we gave it and our `git` global configuration. We 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 +189,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. +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. [learnrust]: learn-rust.html [syntax]: syntax-and-semantics.html diff --git a/src/doc/trpl/hello-world.md b/src/doc/trpl/hello-world.md index f04a9132b52..4c5300d7ac3 100644 --- a/src/doc/trpl/hello-world.md +++ b/src/doc/trpl/hello-world.md @@ -1,25 +1,25 @@ % Hello, world! -Now that you have Rust installed, let’s write your first Rust program. It’s -traditional to make your first program in any new language one that prints the +Now that we have Rust installed, let’s write our first Rust program. It’s +traditional to make our first program in any new language one that prints the text “Hello, world!” to the screen. The nice thing about starting with such a -simple program is that you can verify that your compiler isn’t just installed, -but also working properly. And printing information to the screen is a pretty -common thing to do. +simple program is that we can verify that our compiler isn’t just installed, but +also working properly. And printing information to the screen is a pretty common +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 your code lives. +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. This actually leads to one other concern we should address: this guide will -assume that you have basic familiarity with the command line. Rust itself makes -no specific demands on your editing tooling, or where your code lives. If you -prefer an IDE to the command line, you may want to check out -[SolidOak][solidoak], or wherever plugins are for your favorite IDE. There are -a number of extensions of varying quality in development by the community. The -Rust team also ships [plugins for various editors][plugins]. Configuring your +assume that we have basic familiarity with the command line. Rust itself makes +no specific demands on our editing tooling, or where our code lives. If we +prefer an IDE to the command line, we may want to check out +[SolidOak][solidoak], or wherever plugins are for our favorite IDE. There are a +number of extensions of varying quality in development by the community. The +Rust team also ships [plugins for various editors][plugins]. Configuring our editor or IDE is out of the scope of this tutorial, so check the documentation -for your setup, specifically. +for our setup, specifically. [solidoak]: https://github.com/oakes/SolidOak [plugins]: https://github.com/rust-lang/rust/blob/master/src/etc/CONFIGS.md @@ -33,14 +33,14 @@ $ mkdir hello_world $ cd hello_world ``` -If you’re on Windows and not using PowerShell, the `~` may not work. Consult -the documentation for your shell for more details. +If we’re on Windows and not using PowerShell, the `~` may not work. Consult the +documentation for our shell for more details. Let’s make a new source file next. We’ll call our file `main.rs`. Rust files -always end in a `.rs` extension. If you’re using more than one word in your +always end in a `.rs` extension. If we’re using more than one word in our filename, use an underscore: `hello_world.rs` rather than `helloworld.rs`. -Now that you’ve got your file open, type this in: +Now that we’ve got our file open, type this in: ```rust fn main() { @@ -48,7 +48,7 @@ fn main() { } ``` -Save the file, and then type this into your terminal window: +Save the file, and then type this into our terminal window: ```bash $ rustc main.rs @@ -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. -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. +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. Next up is this line: @@ -84,30 +84,31 @@ 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 your editor of choice to insert four spaces +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]. [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, you’ll see a `!`, and that -means that you’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 trust us for now. +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. [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 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! +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 +pass this string as an argument to `println!`, which prints the string to the +screen. Easy enough! [allocation]: the-stack-and-the-heap.html @@ -126,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 you come from a C or C++ background. Rust -will output a binary executable. You can see it with `ls`: +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`: ```bash $ ls @@ -150,20 +151,19 @@ $ ./main # or main.exe on Windows This prints out our `Hello, world!` text to our terminal. -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 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 a -Ruby/Python/JavaScript implementation installed, but you just need one command -to both compile and run your program. Everything is a tradeoff in language -design, and Rust has made its choice. +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. -Congratulations! You have officially written a Rust program. That makes you a -Rust programmer! Welcome. 🎊🎉👍 +Congratulations! We have officially written a Rust program. That makes us Rust +programmers! Welcome. 🎊🎉👍 -Next, I'd like to introduce you to another tool, Cargo, which is used to write +Next, I'd like to introduce us to another tool, Cargo, which is used to write real-world Rust programs. Just using `rustc` is nice for simple things, but as -your project grows, you'll want something to help you manage all of the options -that it has, and to make it easy to share your code with other people and +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 projects. diff --git a/src/doc/trpl/installing-rust.md b/src/doc/trpl/installing-rust.md index 8095db54a38..ef6bd20ae7f 100644 --- a/src/doc/trpl/installing-rust.md +++ b/src/doc/trpl/installing-rust.md @@ -1,21 +1,21 @@ % Installing Rust The first step to using Rust is to install it! There are a number of ways to -install Rust, but the easiest is to use the `rustup` script. If you're on Linux -or a Mac, all you need to do is this: +install Rust, but the easiest is to use the `rustup` script. If we're on Linux +or a Mac, all we need to do is this: -> Note: you don't need to type in the `$`s, they just indicate the start of -> each command. You’ll see many tutorials and examples around the web that -> follow this convention: `$` for commands run as your regular user, and -> `#` for commands you should be running as an administrator. +> Note: we don't need to type in the `$`s, they just indicate the start of +> each command. We’ll see many tutorials and examples around the web that +> follow this convention: `$` for commands run as our regular user, and `#` for +> commands we should be running as an administrator. ```bash $ curl -sf -L https://static.rust-lang.org/rustup.sh | sh ``` -If you're concerned about the [potential insecurity][insecurity] of using `curl -| sh`, please keep reading and see our disclaimer below. And feel free to -use a two-step version of the installation and examine our installation script: +If we're concerned about the [potential insecurity][insecurity] of using `curl | +sh`, please keep reading and see our disclaimer below. And feel free to use a +two-step version of the installation and examine our installation script: ```bash $ curl -f -L https://static.rust-lang.org/rustup.sh -O @@ -24,9 +24,9 @@ $ sh rustup.sh [insecurity]: http://curlpipesh.tumblr.com -If you're on Windows, please download the appropriate [installer][install-page]. +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 you are installing and you +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. @@ -36,7 +36,7 @@ installed on the local hard drive. ## Uninstalling -If you decide you don't want Rust anymore, we'll be a bit sad, but that's okay. +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: @@ -44,17 +44,17 @@ script: $ sudo /usr/local/lib/rustlib/uninstall.sh ``` -If you used the Windows installer, just re-run the `.msi` and it will give you -an uninstall option. +If we used the Windows installer, 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 you to -`curl | sh`. Basically, when you do this, you are trusting that the good -people who maintain Rust aren't going to hack your 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]. +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]. [from-source]: https://github.com/rust-lang/rust#building-from-source @@ -78,7 +78,7 @@ commit is tested against Windows just like any other platform. ## After installation -If you've got Rust installed, you can open up a shell, and type this: +If we've got Rust installed, we can open up a shell, and type this: ```bash $ rustc --version @@ -93,17 +93,16 @@ variable. If it isn't, run the installer again, select "Change" on the "Change, repair, or remove installation" page and ensure "Add to PATH" is installed on the local hard drive. -This installer also installs a copy of the documentation locally, so you can -read it offline. On UNIX systems, `/usr/local/share/doc/rust` is the location. -On Windows, it's in a `share/doc` directory, inside wherever you installed Rust -to. +This installer also installs a copy of the documentation locally, so we can read +it offline. On UNIX systems, `/usr/local/share/doc/rust` is the location. On +Windows, it's in a `share/doc` directory, inside the directory to which Rust was +installed. -If not, there are a number of places where you can get help. The easiest is -[the #rust IRC channel on irc.mozilla.org][irc], which you can access through -[Mibbit][mibbit]. Click that link, and you'll be chatting with other Rustaceans -(a silly nickname we call ourselves), and we can help you out. Other great -resources include [the user’s forum][users], and -[Stack Overflow][stackoverflow]. +If not, there are a number of places where we can get help. The easiest is +[the #rust IRC channel on irc.mozilla.org][irc], which we can access through +[Mibbit][mibbit]. Click that link, and we'll be chatting with other Rustaceans +(a silly nickname we call ourselves) who can help us out. Other great resources +include [the user’s forum][users], and [Stack Overflow][stackoverflow]. [irc]: irc://irc.mozilla.org/#rust [mibbit]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust