Restructure the book

[japaric]

I'm thinking of doing some changes to the book structure:

• Break some "chapters" into "subchapters". For example, the borrowing chapter is very long because it contains 5 (!) concepts, and each concept has one example, I think it'll be easier for the reader if we break it down like this:

Borrowing
|-- References
|-- Mutability
|-- Freezing
|-- Aliasing
`-- The `ref` pattern

• Because of the previous point and with the upcoming of the live code editor (Embed a playpen-like editor inside the book #73), I think it'll be better to have only one program (i.e. one editor) per page.

The goal is to keep each page bite-sized, i.e. one concept/idea/example/editor per page.

I'll like to know if others think this is a good idea, or if you have any suggestion.

cc @kud1ing @vojtechkral @vks @zslayton

[kud1ing]

The goal is to keep each page bite-sized

I am a big fan of this. It could allow to interlink between topics so that readers could follow their own flow.

[zslayton]

+1 from me too! Keeping it to a single editor per page is a good idea.

On Fri, Jun 6, 2014 at 1:51 PM, kud1ing notifications@github.com wrote:

The goal is to keep each page bite-sized

I am a big fan of this. It could allow to interlink between topics so that
readers could follow their own flow.

—
Reply to this email directly or view it on GitHub
#80 (comment)
.

[vojtechkral]

Sounds good 👍

[japaric]

I'll be working on this today. I still have two concerns:

There are some cases where running the code in the editor will always fail, for example File I/O, because reading/writing files is not allowed by the playpen. In that case, I can think of two possible scenarios:

• We show static code ({file.rs}), and the output ({file.out} or some hardcoded output), or
• We show the editor (even when it's not useful, because executing the code will result in an error), and the output.

The other concern is that we can't pass arguments to the program generated by the playpen, so the editor is not too useful in those cases (#76). This concern can also be addressed with the two scenarios I mentioned before.

Should we use the former or the latter scenario?

I'm leaning towards the latter, as it'll make the look of the book consistent, and we can probably add a note explaining why running the code fails.

[vks]

@japaric Are you sure you want every code to be executable/editable? Sometimes you might want to have a small code snippet that can't be compiled without a lot of boilerplate. (Though I'm not aware of such a thing in the current examples.)

[japaric]

@vks

Are you sure you want every code to be executable/editable?

I don't think that's possible for all the examples, but I'd prefer most of the examples to be executable, and if that's not possible I'm using static code + output. But the static code is still compilable.

Sometimes you might want to have a small code snippet that can't be compiled without a lot of boilerplate

We don't have any of these at the moment.

---

Ok guys, I'm almost done with the restructuring (I also added some new content, no new topics though). It certainly took me longer than I expected (but that always seems to happen ;-))

You can head to the preview site to see how it looks so far

One extra thing I ended up doing is adding FIXME/TODO comments to the editable examples (look at the preview site, to see what I mean). The idea is to get the reader more involved by having him/her hack the code. I would like to get feedback on this addition! (The FIXMEs may be a little discouraging, but I'm not sure...)

@vks @FreeFull I already took care of #81 (locally, along with the restructuring)
@kud1ing After this lands, you can add links to your heart content. The markdown links look like [hello](/hello.html) and [freezing](/borrowing/freeze.html). I have already add some links like that.
@mdinger @Arcnor you are invited to take a sneak peek of the new rustbyexample version (see link above)
@japaric -> bed

[Arcnor]

Will do, thanks!

[mdinger]

First thoughts:
Edit and run in place is super super cool! I really like that you don't have to include the compiler errors and results. You just run it to see for yourself.

[mdinger]

On this page, &, ::, and std::mem:: may be very unclear if you're completely new to programming. A comment briefly explaining their purpose might be warranted to forestall until the topics are properly introduced.

println!("size of `x` in bytes: {}", std::mem::size_of_val(&x));

On this page, you use l-value and r-value. It would be nice if they were explained somewhere.

[Arcnor]

It looks very nice 😄

Just a minor detail. I look at the book in my tablet, and when clicking on Run it seems that nothing happens, until you scroll down to see the result or the errors. Maybe it can be scrolled down automatically?

Anyway, a great improvement!