comments from nostarch

Author: carols10cents

nostarch/chapter01.md

@@ -26,9 +26,12 @@ well as how they work behind the scenes.
 ## Contributing to the book
 
 This book is open source. If you find an error, please don’t hesitate to file an
-issue or send a pull request [on GitHub].
+issue or send a pull request on GitHub at *https://github.com/rust-lang/book*.
 
-[on GitHub]: https://github.com/rust-lang/book
+<!--[on GitHub]: https://github.com/rust-lang/book--> <!-- Where these links
+occur, could you pull the actual link and place it in a sentence, like above?
+That will make it easier for us to know what you want printed in the actual
+book, and what's just going up on the online version -->
 
 ## Installation
 
@@ -65,6 +68,10 @@ If you're on Windows, please download the appropriate [installer][install-page].
 
 [install-page]: https://www.rust-lang.org/install.html
 
+<!-- Are there are options you'd recommend clicking, too? There are two
+download options: GNU and MSVC, what's the difference? What should the reader
+choose? -->
+
 ### Uninstalling
 
 Uninstalling Rust is as easy as installing it. On Linux or Mac, just run
@@ -99,7 +106,7 @@ If you don't and you're on Windows, check that Rust is in your `%PATH%` system
 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 checked.
 
-If not, there are a number of places where you can get help. The easiest is
+If it still isn't working, 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) who can help you out. Other great resources
@@ -126,7 +133,7 @@ tradition.
 
 > Note: This book assumes basic familiarity with the command line. Rust itself
 > makes no specific demands about your editing, tooling, or where your code
-> lives, so if you prefer an IDE to the command line, that's an option.
+> lives, so if you prefer an IDE to the command line, feel free to use your favored IDE.
 
 ### Creating a Project File
 
@@ -146,6 +153,9 @@ $ cd hello_world
 > your home directory may not work.
 > Consult the documentation for your shell for more details.
 
+<!-- Could you be more specific on Windows instructions? For me, I just had to
+remove the tilde and it worked perfectly -->
+
 ### Writing and Running a Rust Program
 
 Next, make a new source file and call it *main.rs*. Rust files always end with
@@ -169,6 +179,9 @@ $ rustc main.rs
 $ ./main
 Hello, world!
 ```
+<!-- On Windows I had to run `rustc main.rs` first to create a main.exe file,
+and just typed "main" without ./ or `exe` to run it. Can you be more specific
+here, maybe just lay out the windows version, since it's so short? -->
 
 On Windows, just replace `main` with `main.exe`. Regardless of your operating
 system, you should see the string `Hello, world!` print to the terminal. If you
@@ -189,12 +202,12 @@ fn main() {
 These lines define a *function* in Rust. The `main` function is special: it's
 the first thing that is run for every executable Rust program. The first line
 says, “I’m declaring a function named `main` that takes no arguments and
-returns nothing.” If there were arguments, they would go inside the parentheses
-(`(` and `)`). We aren’t returning anything from this function, so we have
+returns nothing.” If there were arguments, they would go inside the parentheses,
+`(` and `)`. <!--- We aren’t returning anything from this function, so we have
 omitted the return type entirely. If there was a return type, there would be a
-`->` and the return type after the parentheses.
+`->` and the return type after the parentheses. -->
 
-Also note that the function body is wrapped in curly braces (`{` and `}`). Rust
+Also note that the function body is wrapped in curly braces, `{` and `}`. Rust
 requires these around all function bodies. It's considered good style to put
 the opening curly brace on the same line as the function declaration, with one
 space in between.
@@ -207,7 +220,7 @@ Inside the `main()` function:
 
 This line does all of the work in this little program: it prints text to the
 screen. There are a number of details that are important here. The first is
-that it’s indented with four spaces, not tabs.
+that it’s indented with four spaces, not a tab.
 
 The second important part is `println!()`. This is calling a Rust *macro*,
 which is how metaprogramming is done in Rust. If it were calling a function
@@ -252,6 +265,10 @@ On Windows, you'd enter:
 $ dir
 main.exe  main.rs
 ```
+<!-- This is different for me too -- on windows `ls` worked but `dir` gave me
+different information. However! My colleague also on Windows 10 couldn't get ls
+to work, but dir gave the wrong info. I think we may need to look at getting a
+tech reviewer to test Windows instructions -->
 
 This shows we have two files: the source code, with the `.rs` extension, and the
 executable (`main.exe` on Windows, `main` everywhere else). All that's left to
@@ -260,6 +277,7 @@ do from here is run the `main` or `main.exe` file, like this:
 ```bash
 $ ./main  # or main.exe on Windows
 ```
+<!-- `$ main` worked for me, without `./` or `exe` -->
 
 If *main.rs* were your "Hello, world!" program, this would print `Hello,
 world!` to your terminal.
@@ -285,7 +303,7 @@ Cargo is Rust’s build system and package manager, and Rustaceans use Cargo to
 manage their Rust projects because it makes a lot of tasks easier. For example,
 Cargo takes care of building your code, downloading the libraries your code
 depends on, and building those libraries. We call libraries your code needs
-‘dependencies’ since your code depends on them.
+*dependencies*.
 
 The simplest Rust programs, like the one we've written so far, don’t have any
 dependencies, so right now, you'd only be using the part of Cargo that can take
@@ -304,8 +322,8 @@ $ cargo --version
 ```
 
 If you see a version number, great! If you see an error like `command not
-found`, then you should look at the documentation for the way you installed
-Rust to determine how to install Cargo separately.
+found`, then you should look at the documentation for your method of installation
+to determine how to install Cargo separately.
 
 ### Creating a Project with Cargo
 
@@ -326,8 +344,8 @@ $ cd hello_cargo
 
 We passed the `--bin` argument to `cargo new` because our goal is to make an
 executable application, as opposed to a library. Executables are often called
-*binaries* (as in `/usr/bin`, if you’re on a Unix system). `hello_cargo` is the
-name we've chosen for our project, and Cargo creates its files in a directory
+*binaries* (as in `/usr/bin`, if you’re on a Unix system). We've given `hello_cargo` as the
+name for our project, and Cargo creates its files in a directory
 of the same name that we can then go into.
 
 If we list the files in the `hello_cargo` directory, we can see that Cargo has
@@ -412,6 +430,7 @@ This should have created an executable file in `target/debug/hello_cargo` (or `t
 $ ./target/debug/hello_cargo # or ./target/debug/hello_cargo.exe on Windows
 Hello, world!
 ```
+<!-- Windows needs to use \ without the . -->
 
 Bam! If all goes well, `Hello, world!` should print to the terminal once more.
 
@@ -439,7 +458,7 @@ $ cargo run
 Hello, world!
 ```
 
-Notice that this time, we didn't see the output that Cargo was compiling
+Notice that this time, we didn't see the output telling us that Cargo was compiling
 `hello_cargo`. Cargo figured out that the files haven’t changed, so it just ran
 the binary. If you had modified your source code, Cargo would have rebuilt the
 project before running it, and you would have seen something like this:
@@ -477,7 +496,7 @@ projects composed of multiple crates, it’s much easier to let Cargo coordinate
 the build. With Cargo, you can just run `cargo build`, and it should work the
 right way. Even though this project is simple, it now uses much of the real
 tooling you’ll use for the rest of your Rust career. In fact, you can get
-started with virtually all Rust projects you might find that you want to work
+started with virtually all Rust projects you want to work
 on with the following commands:
 
 ```bash