-
Notifications
You must be signed in to change notification settings - Fork 3.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Formatting of Code in Book is Sometimes Inconsistent with rustfmt #1690
Comments
The intention is to follow rustfmt's defaults, for sure. I'd love to accept some PRs to fix this! Ideally, we'd have some way to be able to format them all automatically... |
I will get on formatting some chapters with rustfmt and submitting them. It would be great to have a tool to do it, although not sure how to do it with the code being mixed in markdown files. |
After inspecting some chapters, I don’t think it would be easy to make a tool to automate the process, as there specifically are examples within the book of how code should not look. Unless there was some sort of flagging system to flag those code chunks, they would be corrected. Although tedious, I think manual corrections will be the way to go. |
Yep! Agree 100%.
… On Dec 15, 2018, at 12:06 PM, Joseph T Lyons ***@***.***> wrote:
After inspecting some chapters, I don’t think it would be easy to make a tool to automate the process, as there are specifically examples within the book of how code should not look. Unless there was some sort of flagging system to flag those code chunks, they would corrected. Although tedious, I think manual corrections will be the way to go.
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub, or mute the thread.
|
I'd be happy to help with this. I'm very new to rust, but catching formatting issues is one way that even I can contribute—and free up other for more substantive work. I took a look at it and I think it's possible to partly automate it with vim macros. Using that method, I was able to check that there aren't any issues in Ch1 and find a few minor changes Ch2. (All the changes I found were either adding line-breaks or alphabetizing the |
This task is a bit more challenging that I initially expected. There are various aspects to consider. For instance, there seems to be some things fn main() {
} but fn main() {
} So I encounter these issues where I'm not sure if I should just entirely allow all formatting changes by Other things you have to consider is this isn't just about formatting code and moving on, you have to read the text that refers to that code to see if you need to adjust what is being said that may no longer be correct; I've had to do this already in a spot or two, as the changes made the text following it inaccurate. All of this to say that this isn't a quick thing. As mentioned by @codesections , most of the changes in the first few chapters are line breaks and alphabetizing Another thing we have to consider is how often we apply Last question, @steveklabnik , would you be against the idea of me creating a simple Here's a sample: |
So, one interesting and related thing: https://rust-lang-nursery.github.io/mdBook/format/mdbook.html#including-files I wonder if we could do something where we pull the code examples out into their own files, and then we'd be able to @carols10cents what do you think about that?
Yeah, that's tricky...
I'm not opposed. Carol? |
@JosephTLyons if you put together a table, just let me know how/where I can help. I'm very new to rust and will happily defer to any of y'all, but would be happy to be helpful without duplicating work others have done. |
OOH! I didn't know mdbook could do that! We need to provide standalone code for the examples too, so win-win-win! |
If we can go this route of extracting the code into files, then we should be able to run rustfmt on everything pretty easily, right? Ugh one wrinkle might be the mdbook hiding with |
I have a table done and will have it ready to go as soon as I get some direction of where to place it in this repo :) |
@carols10cents I noticed that a lot of code doesn’t instantly format with rustfmt. Many code chunks are not complete pieces of code, missing the main function and such. I had to manually copy and paste code into another more complete file to run rustfmt many times (being extremely careful when copying back only to include original code ((heavily checking diffs)). So I’m not entirely sure how much easier putting the code into their own files will make it. I know it will remove the markdown around them, but it will still require a lot of manual setup to run rustfmt I think. |
We actually want to extract examples into runnable files so that we have a directory of just the code in the book that people can run without having to type in, and to reference if they do type it in and theirs doesn't work. The "include" mdbook feature looks like it lets you specify which lines from a file you'd like to include, which might work for, say, putting I started trying out pulling code into files in this branch. Unfortunately, I want to also retain |
Understandable. I won't waste the maintainer's time by opening a PR then for the new table I created, but I'll leave a link here in case you or Steve decide you'd like to use it for either the automatic or manual formatting. |
This should be fixed now! Please open new issues if there's still some things incorrect. |
I've been reading the Rust book much more recently and have come to notice that some examples do not follow the way in which rustfmt formats code. For example, in the Method Syntax chapter of the book, an instance of the
Rectangle
struct is formatted as such:but rustfmt would format it as such:
I've found other discrepancies between the book's formatting and rustfmt. Rustfmt seems to be a tool that was made to help Rustaceans put their code in the exact format agreed upon by the creators, so I think it would be fit to format the code in the book with rustfmt. If there is any interest in this happening, but the task is considered large, I would be happy to help.
The text was updated successfully, but these errors were encountered: