Improve redirects

[passcod]

^{(Following these tweets with @steveklabnik.)}

The general idea / guiding thought is this: redirects are where many people land (right now), and we're trying to retain their attention while pointing them elsewhere. At the same time, eventually the redirects will all but disappear as links are updated.

I think the current design does this poorly.

1. It is extremely generic. It is so generic that nowhere in the actual copy does it say where you've landed, or where you're going, in more precise terms than "The Rust Book first or second edition".
2. Many redirect pages point people to the index, which is likely one of the least useful place to go when looking for specific information.
3. It provides no value to people beyond two links which may or may not provide the right information, which the visitor has no way of figuring out without actually clicking on.

The fact is, there is no 1:1 correspondence between 1st-ed and 2nd-ed chapters. There are a few N:1 (1st-ed to 2nd-ed), a large number of 1:N, and indeed some 1:nowhere. So it is impossible to automatically redirect people, which is the entire problem and why these redirects exist.

Hence, this Pull Request. I applied 5 incremental modifications to every redirect page:

Replace the generic title with the title of the chapter in 1st-ed

and reword the blurb to include what was previously in the title. This makes it easier to see that one has arrived to the right place.

Always go somewhere meaningful

Unless it is the correct place to go, never link to the index of the second edition as fallback. Point instead to different books, to the reference, to the API documentation, etc.

Include the title of the link's target into its text

To make it clearer where links are going, eliminate entirely the language of "Related" or the long verbose book titles. Instead, simply prefix with "In the first/second edition" as needed, and in similar style for other resources like the reference or the Unsafe book. Additionally, include the target's title, i.e. chapter number, name, and sometimes subsection, directly to the link copy.

Add a quick summary and code sample

To improve immediate value and reduce discard-because-not-useful factor upon arriving at a page which does not contain the content you were expecting, add a small blurb taken/adapted from the newer source (except in the case of pages that do not exist at all), optionally accompanied by a code sample describing the feature (or as relevant).

Keeping in mind that due to the transitive nature of the redirects, there must be no content there that isn't available elsewhere.

Highlight the recommended path and "lowlight" the old path

Instead of placing the link to the recommended resource i.e. the second edition in second place, push it up to the top of the list. In fact, push the link to the first edition always at the bottom. To emphasise even more that's where new visitors should go, bolden the first link, and make the first-ed link smaller.

This provides a clear recommendation of where to go, without completely hiding the old resource (which would be detrimental as there is value in the first-ed still).

Result

(Note that the code sample should actually be a yellow runnable syntax-highlighted Rust code block, but there is no script or means to build the redirects, so I had to do the preview by manually inserting rendered HTML into an existing page, which means it lacks the fanciness.)

[steveklabnik]

this looks great to me. thanks a ton.

[carols10cents]

Thank you for doing this! Also just a note that the book rides the release trains, so this won't hit doc.rust-lang.org/book for a while (beta backport to get it in sooner maybe, @steveklabnik ?)

[steveklabnik]

I'm thinking of sending in a PR to the book shortly after the branch so that it does appear on nightly so we can get a feel for it.