3 ms·

Steve, TRPL has proven a fantastic resource for learning Rust. I'm wondering if you have a plan for how it will track the advancement of the Rust language itse

by jat850 10y ago

Steve, TRPL has proven a fantastic resource for learning Rust. I'm wondering if you have a plan for how it will track the advancement of the Rust language itself - do you intend to maintain a version of the book for major point releases of Rust, minor point releases, etc? I wish I could cite some specific examples but I didn't keep notes, but I think I've come across a a few instances where, say, something behaved differently in Rust 1.10 versus Rust 1.12. Will the book attempt to tackle this?

steveklabnik 10y ago
This is a great question, with a lot of details. So, let's start from the beginning. In a sense, there _is_ a version for each version of the language: * https://doc.rust-lang.org/1.8.0/book/ * https://doc.rust-lang.org/1.9.0/book/ * https://doc.rust-lang.org/1.10.0/book/ etc. Since the current book is stored in-tree, this is just part of the regular release cycle. That said, I haven't been working on the book because I've been working on the new book, so it's largely the same, just with some typos. The second bit is, thanks to the stability guarantees, these days, the book doesn't really go out of date. Everything works. That said, there are sometimes new features added that it doesn't always cover; this is really tricky in general. There's an overall tension here, since it's an official project: I feel the need to be comprehensive, yet a good text is often defined just as much by what you leave out as what you put in. So the book tries to be _mostly_ comprehensive, but not totally so. So it's okay if new features aren't immediately in the book. This also ties into Rust itself, and something the team has been thinking a lot about. With most languages, you have major releases in order to sort of chronicle the language through history: new idioms, new features, etc. With our release schedule, and no plans to make a "2.0, major breaking changes everything is different" release, we don't have that normal point to tell the story of how Rust is changing. So I can imagine that major updates to the book will happen along these same "epochs", as Rust changes over time. We're still trying to figure that all out, though. But the key is that many Rust releases aren't game-changing: only some features actually change idioms. Finally, No Starch will be publishing the book in paper form. So there's also the question of that, but at the moment, we're mostly interested in shipping this one, but everyone is on board with _some_ sort of periodic refresh of the printed edition as well. We'll see how it goes. Does that make sense?
- ronjouch 10y ago
  Related: I understand the versions hosted at doc.rust-lang.org you mention above, but what's about the version linked in your post? ( http://rust-lang.github.io/book/ http://rust-lang.github.io/book/ ). It's what's in master right now, right? EDIT ah, https://github.com/rust-lang/book https://github.com/rust-lang/book clarifies this, it's a rewrite, and is not (yet) part of the main Rust repository.
  - steveklabnik 10y ago
    The version hosted on docs.rust-lang.org is the current edition of the book, whose source is in-tree. https://github.com/rust-lang/rust/tree/master/src/doc/book https://github.com/rust-lang/rust/tree/master/src/doc/book In order to not trash the book while we're doing the re-write, we've moved it to a new repository, which is the one you've linked. When the new book is ready, we will either merge it into `src/doc/book` or remove the book from the main repository and use rust-lang/book as the new official source, it's not totally clear yet which.
    - carols10cents 10y ago
      > When the new book is ready, we will either merge it into `src/doc/book` or remove the book from the main repository and use rust-lang/book as the new official source, it's not totally clear yet which. Also, no matter which of these two options we choose, we still plan to ship the book inside installations of Rust for offline reading, and host the book on docs.rust-lang.org.
- jat850 10y ago
  Makes perfect sense, and my apologies for not having found that sooner. I'd only ever looked at the main book link found in your post, and missed a bunch of valuable resources. I really appreciate all of the effort put into the documentation, tutorials, examples. It's made Rust the first language I've intentionally sought to learn in quite some time.
saysjonathan 10y ago
Clearly I'm not Steve, and can't speak to his or the teams goals with the content of the book, but you can find the complete source for the book in the Rust repo[0]. Feel free to send some pulls with the content you'd like to see! [0] https://github.com/rust-lang/rust/tree/master/src/doc/book https://github.com/rust-lang/rust/tree/master/src/doc/book
- steveklabnik 10y ago
  It's really the same as any open source project, just with words instead of code. I am extremely happy to accept pull requests with typo fixes, small re-writes for clarity, and paragraphs adding more clarity. I would prefer that for very large changes, interested parties swing by #rust-docs or #rust or email me about them first, and be okay with me doing a lot of editing before merge.

by jat850 10y ago

steveklabnik 10y ago

This is a great question, with a lot of details. So, let's start from the beginning. In a sense, there _is_ a version for each version of the language: * https://doc.rust-lang.org/1.8.0/book/ * https://doc.rust-lang.org/1.9.0/book/ * https://doc.rust-lang.org/1.10.0/book/ etc. Since the current book is stored in-tree, this is just part of the regular release cycle. That said, I haven't been working on the book because I've been working on the new book, so it's largely the same, just with some typos. The second bit is, thanks to the stability guarantees, these days, the book doesn't really go out of date. Everything works. That said, there are sometimes new features added that it doesn't always cover; this is really tricky in general. There's an overall tension here, since it's an official project: I feel the need to be comprehensive, yet a good text is often defined just as much by what you leave out as what you put in. So the book tries to be _mostly_ comprehensive, but not totally so. So it's okay if new features aren't immediately in the book. This also ties into Rust itself, and something the team has been thinking a lot about. With most languages, you have major releases in order to sort of chronicle the language through history: new idioms, new features, etc. With our release schedule, and no plans to make a "2.0, major breaking changes everything is different" release, we don't have that normal point to tell the story of how Rust is changing. So I can imagine that major updates to the book will happen along these same "epochs", as Rust changes over time. We're still trying to figure that all out, though. But the key is that many Rust releases aren't game-changing: only some features actually change idioms. Finally, No Starch will be publishing the book in paper form. So there's also the question of that, but at the moment, we're mostly interested in shipping this one, but everyone is on board with _some_ sort of periodic refresh of the printed edition as well. We'll see how it goes. Does that make sense?

ronjouch 10y ago
Related: I understand the versions hosted at doc.rust-lang.org you mention above, but what's about the version linked in your post? ( http://rust-lang.github.io/book/ http://rust-lang.github.io/book/ ). It's what's in master right now, right? EDIT ah, https://github.com/rust-lang/book https://github.com/rust-lang/book clarifies this, it's a rewrite, and is not (yet) part of the main Rust repository.
- steveklabnik 10y ago
  The version hosted on docs.rust-lang.org is the current edition of the book, whose source is in-tree. https://github.com/rust-lang/rust/tree/master/src/doc/book https://github.com/rust-lang/rust/tree/master/src/doc/book In order to not trash the book while we're doing the re-write, we've moved it to a new repository, which is the one you've linked. When the new book is ready, we will either merge it into `src/doc/book` or remove the book from the main repository and use rust-lang/book as the new official source, it's not totally clear yet which.
  - carols10cents 10y ago
    > When the new book is ready, we will either merge it into `src/doc/book` or remove the book from the main repository and use rust-lang/book as the new official source, it's not totally clear yet which. Also, no matter which of these two options we choose, we still plan to ship the book inside installations of Rust for offline reading, and host the book on docs.rust-lang.org.
jat850 10y ago
Makes perfect sense, and my apologies for not having found that sooner. I'd only ever looked at the main book link found in your post, and missed a bunch of valuable resources. I really appreciate all of the effort put into the documentation, tutorials, examples. It's made Rust the first language I've intentionally sought to learn in quite some time.

saysjonathan 10y ago

Clearly I'm not Steve, and can't speak to his or the teams goals with the content of the book, but you can find the complete source for the book in the Rust repo[0]. Feel free to send some pulls with the content you'd like to see! [0] https://github.com/rust-lang/rust/tree/master/src/doc/book https://github.com/rust-lang/rust/tree/master/src/doc/book

steveklabnik 10y ago
It's really the same as any open source project, just with words instead of code. I am extremely happy to accept pull requests with typo fixes, small re-writes for clarity, and paragraphs adding more clarity. I would prefer that for very large changes, interested parties swing by #rust-docs or #rust or email me about them first, and be okay with me doing a lot of editing before merge.