Miscellaneous changes to Rust Guide #19823
Conversation
|
Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @pcwalton (or someone else) soon. If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. The way Github handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes. Please see CONTRIBUTING.md for more information. |
| @@ -1178,7 +1178,7 @@ fn respond(greeting: &str) -> StringResult { | |||
| ``` | |||
|
|
|||
| Notice that we need both the enum name and the variant name: `StringResult::StringOK`, but | |||
| we didn't need to with `Ordering`, we just said `Greater` rather than `Ordering::Greater`. | |||
| we didn't need to with `Ordering` -- we just said `Greater` rather than `Ordering::Greater`. | |||
There was a problem hiding this comment.
It would be nice if this was an em dash rather than two hyphens.
Hey thanks! I think this is true too, I'm not sure there's precident here for one way or the other, but I agree. |
I think this is because Rust style is 100 columns, but the style might be set up for 80... |
|
I just reviewed the first bit of this now, and it mostly looks good! I'll review more in the morning. Thank you! |
|
Thanks for the initial review! I agree with and have addressed the em dash changes. Edit: I realized I used em dashes with adjacent spaces, even though the convention is to use en dashes with spaces or em dashes without spaces. Since most people who edit the document will probably be using monospaced fonts, I think en dashes with spaces would be the better option since they're more easily differentiable from hyphens at a glance. |
|
I concur about the spaces. |
| @@ -4335,7 +4334,7 @@ fn twice(x: int, f: |int| -> int) -> int { | |||
| ``` | |||
|
|
|||
| Since our closure is named `f`, we can call it just like we called our closures | |||
| before. And we pass in our `x` argument to each one. Hence 'twice.' | |||
| before. And we pass in our `x` argument to each one. Hence, 'twice'. | |||
There was a problem hiding this comment.
this isn't a Rust-specific concept and therefore wouldn't be part of the 'punctuation outside' convention we're talking about here.
There was a problem hiding this comment.
Good point. Looking back on this, it seems to make more sense to reference the name of the function using backticks.
|
So, ovearall, this looks good. But, we've sorta ended up with two conventions here: sometimes, with a concept, we mark it in bold, and sometimes we use single quotes. What about moving all of these instances to italics, instead? |
|
I was hesitant to touch too many things since I'm still really new to Rust. To clarify, would the proposed change be to take every instance of |
|
Since they both come out to the same thing, I don't think changing them to the single sytax is worth it. But yeah, let's change them all for now. |
|
I decided on using the underscore syntax since that's what was already in place. Some of the instances of bold or single quotes were legitimate, so I either left them (in the case of bolded text) or changed them to double quotes. Edit: Looks like there's merge conflicts now; I'll work on resolving them. |
|
Actually, I'm thinking that doing the whole bold/quotes to italics change might be out of the scope of this pull request, so I got rid of that commit. I can open a new PR making the discussed changes that covers more files than just Should I squash down these three commits if everything looks good? |
|
yes, r=me with a squash (I think GitHub's rendering is being a bit strange, though...) |
- Various grammatical changes - Place punctuation outside of key term quotes - Change comment placement in 17.2 code block - Replace double hyphens with en dashes
|
@steveklabnik Alright, all squashed down. I'll wait for whatever changes are happening with #19897 to be merged in before working on the bold/quotes to italics change. |
|
Sounds great. Thanks! |
I was reading through the Rust Guide (hopefully looking to learn some Rust), and I figured it would be a good idea to open a pull request with some of the errata I noticed along the way. Most of the changes are pretty mundane, but there are a couple that might raise a bit of discussion. ### Punctuation outside of 'key term' quotes This is something that was inconsistent in the Guide. While the convention in American English is to place punctuation immediately following a quotation mark *inside* the quotation mark, it seems strange to do this with 'key terms', considering they are not a true quotation. ### Changed comment placement in 17.2 code block This is what the code block in [17.2 — Ownership, borrowing, and lifetimes](http://doc.rust-lang.org/guide.html#ownership,-borrowing,-and-lifetimes) looks like in fullscreened Safari 8:  Some of the comments extend *just* too far, causing them to bleed into the next line, so I moved a few of them above the relevant lines of code to avoid this.
Here's my PR for the changes discussed in #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 #19897 being finalized and merged, by the way!)
I was reading through the Rust Guide (hopefully looking to learn some Rust), and I figured it would be a good idea to open a pull request with some of the errata I noticed along the way. Most of the changes are pretty mundane, but there are a couple that might raise a bit of discussion.
Punctuation outside of 'key term' quotes
This is something that was inconsistent in the Guide. While the convention in American English is to place punctuation immediately following a quotation mark inside the quotation mark, it seems strange to do this with 'key terms', considering they are not a true quotation.
Changed comment placement in 17.2 code block
This is what the code block in 17.2 — Ownership, borrowing, and lifetimes looks like in fullscreened Safari 8:
Some of the comments extend just too far, causing them to bleed into the next line, so I moved a few of them above the relevant lines of code to avoid this.