https://github.com/rust-lang/rust/pull/116412 will remove support for
compiler plugins from rustc, which includes the entry in The Rust
Unstable Book. This commit removes a link to that entry so it won't be
broken when that PR merges.
Per https://github.com/rust-lang/book/issues/3047, use captured identifiers instead of the positional ones for some examples, e.g.
```diff
- println!("Worker {} got a job; executing.", id);
+ println!("Worker {id} got a job; executing.");
```
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.
All this as well as a slight edit and simplification of the copy is
designed to make the new and recommended resources the primary path
readers take, without hiding the old resource completely.
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,
optionally accompanied by a code sample describing the feature.
However, due to the transitive nature of this resource, there must be no
content here that isn't available elsewhere.
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.
Add the target's title, i.e. chapter number, name, and sometimes
subsection, directly to the link copy.
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.
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:
beforehand, the only indication was through the link target for the
first edition; it was nowhere in the copy itself for most pages.
Search engines often show the redirect page for search terms like "rust
topic" or "rust book topic". Currently the redirect targets all go to the
index.html of the second edition of the book. This discourages users
to use the second edition, because many will click on the direct link to
the first edition out of laziness. In addition, as long as the pages of
the second edition are not well linked, the old pages will probably stay
at the top of the search results.
To fix this, this commit changes the target links to go to the related
content in the second edition, in the following way:
Old content maps in different ways to new content:
1. 1:1 mapping
content is comprehensively covered in a single location of the
second edition
2. basic/advanced mapping
content is comprehensively covered in two locations of the second
edition; first location covers the basics, second location covers
advanced topics
3. split mapping
content is covered in muliple locations of the second edition
4. moved
content has moved to another place
5. removed
content doesn't exist in the second edition
This commit handles these cases in the following way:
1. Mapping type 1: 1:1 mapping
Change the link target from "second-edition/index.html" to the
respective chapter, page or section of the second edition.
Change the link text from "Index of the second edition..." to
either of:
- "Related chapter in the second edition"
- "Related page in the second edition"
- "Related section in the second edition"
"Related" was chosen because content of two versions is at least
related but not necessarily equivalent.
Example: closures.md
2. Mapping type 2: basic/advanced mapping
Change the link target from "second-edition/index.html" to the
respective chapter, page or section of the second edition. Add
a second link target for the advanced chapter, page or section.
Change the link text like for type 1. Add the second link with
the following text: "Related chapter in the second edition
of The Rust Programming Language (covering more advanced
topics)". Similar to the messages of type 2 there are variants
with "page" and "section".
Example: lifetimes.md
3. Mapping type 3: split mapping
Change similar to changes for type 2. but add multiple links
with text in parens describing relationship.
4. Mapping type 4: moved
No changes.
Example: compiler-plugins.md
5. Mapping type 5: removed
No changes. See "Improvements" below.
Example: attributes.md
Improvements:
This commit tries to introduce the target links with a minimum of changes.
Copy was adapted only to the extent absolutely necessary. This leaves room
for improvements:
- Better deal with case 3. Describe mapping in copy not only link text.
Actually refer to the links in the body copy.
- Redirect pages of type 5 (content doesn't exist in second edition)
should distinguish between "Content removed for good" and "Content
not ready yet". For the latter category we could link to stub pages.
All the new links were tested manually. The html was produced by a
little script that invokes rustdoc, builds the book and copies
everything into place. The script is not part of this commit.
Here is a list with all mappings:
associated-types.html -1-> ch19-03-advanced-traits.html#associated-types
attributes.html -5-> index.html
bibliography.html -5-> index.html
borrow-and-asref.html -5-> index.html
casting-between-types.html -5-> index.html
choosing-your-guarantees.html ~1~> ch15-00-smart-pointers.html
closures.html -1-> ch13-01-closures.html
comments.html -1-> ch03-04-comments.html
compiler-plugins.html -4-> ../unstable-book/language-features/plugin.html
concurrency.html -1-> ch16-00-concurrency.html
conditional-compilation.html -5-> index.html
const-and-static.html ~1~> ch19-01-unsafe-rust.html#accessing-or-modifying-a-mutable-static-variable
crates-and-modules.html -3-> Modules: ch07-00-modules.html
Crates: ch14-00-more-about-cargo.html
deref-coercions.html ~1~> ch15-02-deref.html#implicit-deref-coercions-with-functions-and-methods
documentation.html ~1~> ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments
drop.html -1-> ch15-03-drop.html
effective-rust.html -5-> index.html
enums.html -1-> ch06-01-defining-an-enum.html
error-handling.html -1-> ch09-00-error-handling.html
ffi.html -1-> ch19-01-unsafe-rust.html#calling-an-unsafe-function-or-method
functions.html -1-> ch03-03-how-functions-work.html
generics.html -1-> ch10-00-generics.html
getting-started.html ~1~> ch01-00-introduction.html
glossary.html -5-> index.html
guessing-game.html -1-> ch02-00-guessing-game-tutorial.html
if-let.html -1-> ch06-03-if-let.html
if.html -1-> ch03-05-control-flow.html#if-expressions
iterators.html -1-> ch13-02-iterators.html
lifetimes.html -2-> ch10-03-lifetime-syntax.html
ch19-02-advanced-lifetimes.html
loops.html -1-> ch03-05-control-flow.html#repetition-with-loops
macros.html -5-> index.html (appendix-05-macros.html is in TOC, but doesn't exist)
match.html -2-> ch06-02-match.html
-2-> ch18-00-patterns.html
method-syntax.html -1-> ch05-03-method-syntax.html
mutability.html -1-> ch03-01-variables-and-mutability.html
operators-and-overloading.html -1-> ch19-03-advanced-traits.html#operator-overloading-and-default-type-parameters
ownership.html -1-> ch04-00-understanding-ownership.html
patterns.html -2-> ch06-02-match.html#patterns-that-bind-to-values
ch18-03-pattern-syntax.html
primitive-types.html ~1~> ch03-02-data-types.html
procedural-macros.html -5-> index.html (appendix-05-macros.html is in TOC, but doesn't exist)
raw-pointers.html ~1~> ch19-01-unsafe-rust.html#dereferencing-a-raw-pointer
references-and-borrowing.html -1-> ch04-02-references-and-borrowing.html
release-channels.html -5-> index.hmtl
strings.html ~2~> ch04-03-slices.html#string-slices [Should be type 3 maybe with distinction &str and String]
~2~> ch08-02-strings.html
structs.html -1-> ch05-00-structs.html
syntax-and-semantics.html ~3~> ch03-00-common-programming-concepts.html
appendix-01-keywords.html
appendix-02-operators.html
appendix-05-macros.html [WIP]
syntax-index.html -5-> index.html
testing.html -1-> ch11-00-testing.html
the-stack-and-the-heap.html -5-> index.html
trait-objects.html -1-> ch17-02-trait-objects.html
traits.html -2-> ch10-02-traits.html
ch19-03-advanced-traits.html
type-aliases.html ~1~> ch19-04-advanced-types.html#type-aliases-create-type-synonyms
ufcs.html -5-> index.html
unsafe.html ~1~> ch19-01-unsafe-rust.html
unsized-types.html ~1~> ch19-04-advanced-types.html#dynamically-sized-types--sized
using-rust-without-the[..].html -5-> index.html
variable-bindings.html -5-> index.html
vectors.html -1-> ch08-01-vectors.html
Yuri Astrakhan
Chris Krycho
Nicholas Nethercote
kadiwa
Eric Huss
Carol (Nichols || Goulding)
Kornel
Carol (Nichols || Goulding)
Dmitry Borodin
Matt Brubeck
psincf
Steve Klabnik
Lireer
Félix Saparelli
Ludwig Weinzierl
John Keiser
Corey Farwell