Minimize the edition guide

[nikomatsakis]

This lays out the new, more minimal structure of the edition guide. I copied and pasted the existing content that was still relevant and also copied in the introduction and the descriptions of the changes from @m-ou-se's blog.

cc @rust-lang/project-edition-2021

[ghost]

Changing "without having to wait for" to "while we waited for" might make it clearer that async still becomes a keyword in 2018, even with k# available. (I think that's the intent, if this had been available then)

[m-ou-se]

Thanks! Updated in rust-lang/blog.rust-lang.org#825.

[ehuss]

A few high-level comments:

• I would prefer to keep the filename style using hyphens instead of underscores, to be consistent with the rest of the books.
• I think it would be good to add redirects for the removed pages, otherwise there will be a lot of broken links. mdbook now supports that in book.toml. I think that should work, though the rust-lang linkchecker doesn't work well with it.

It also looks like there are a few errors and broken links here. Let me know if you want help with any of the above.

[nikomatsakis]

@ehuss

I would prefer to keep the filename style using hyphens instead of underscores, to be consistent with the rest of the books.

OK! No opinion here.

I do have a question: this book uses index.md files, is this something we do elsewhere? (vs src/rust-2015.md, for example)

I think it would be good to add redirects for the removed pages, otherwise there will be a lot of broken links. mdbook now supports that in book.toml. I think that should work, though the rust-lang linkchecker doesn't work well with it.

Good point. I'll look into what support mdbook has for that.

[ehuss]

I do have a question: this book uses index.md files, is this something we do elsewhere? (vs src/rust-2015.md, for example)

I think it is fine to use index.md. It is not used commonly elsewhere, but I think that's just an artifact of evolution. For example, the reference had src/types.md as a single file. When it was split into multiple files, I kept the original src/types.md instead of renaming it to src/types/index.md because that would break old links and was too much of a hassle to deal with (and mdbook didn't support renames at the time). Books like TRPL use a flat structure (no directories), though I'm not sure why.

[nikomatsakis]

I guess modifying it would require modifying links, and I have no desire to do that.

[steveklabnik]

Books like TRPL use a flat structure (no directories), though I'm not sure why.

Because the book is older than mdbook is, and the initial build infrastructure was very simple.

[nikomatsakis]

Addressed @ehuss's points:

I would prefer to keep the filename style using hyphens instead of underscores, to be consistent with the rest of the books.

Done!

I think it would be good to add redirects for the removed pages, otherwise there will be a lot of broken links. mdbook now supports that in book.toml. I think that should work, though the rust-lang linkchecker doesn't work well with it.

Done! Since most of that content no longer exists, I tried to map to the "closest relevant thing".

It also looks like there are a few errors and broken links here. Let me know if you want help with any of the above.

mdbook test passes now, if that's what you mean, although I mostly just ignored code examples. Maybe as we revise those chapters we can convert them into tests that actually run.

[nikomatsakis]

I think this is ready to land, then.

[ehuss]

I pushed a commit to fix some of the links here: ehuss@8b6d2d1

I can push it to your branch, or you can maybe copy it if you want.

The CI was a little out of date. Links can't be absolute, since they would break when viewed from the filesystem. Also, I added redirects to pages that might be more relevant to the original content.

[nikomatsakis]

@ehuss feel free to push to my branch!

[nikomatsakis]

Thanks @ehuss! I'm going to go ahead and merge this then.