rust-lang / rust-lang/book

Add links when referencing other chapters?

Open
#4,535 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
18.3k
Forks
4.1k
Avg merge
14m
Merged PRs (30d)
1

Description

  • I have searched open and closed issues and pull requests for duplicates, using these search terms:
    • links to other chapters
    • (this is really hard to think of good keywords for)
  • I have checked the latest main branch to see if this has already been fixed, in this file:
    -/src/ch18-01-what-is-oo.md

In many occasions in the latter half of the book, previous listings are mentioned. This is one example:
https://doc.rust-lang.org/book/ch18-01-what-is-oo.html#inheritance-as-a-type-system-and-as-code-sharing

You can do this in a limited way in Rust code using default trait method implementations, which you saw in Listing 10-14 when we added a default implementation of the summarize method on the Summary trait.

(permalink)

If I want to see Listing 10-14 to reminds myself of its context, I would have to go looking for it. I know it's in Chapter 10, but which page? There are 3 (technically 4) where it could be.

Turns out it's in 10.2 Traits: Defining Shared Behavior.

Would it be too much work to add links to other chapters of the book when they are mentioned? Especially for listings, but not only.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in src/ch18-01-what-is-oo.md and inspect the reference to Listing 10-14, then compare it with the linked Chapter 10. Identify other references to previous listings or chapters in the latter half of the book and add links where appropriate. Done means readers can follow those references directly to their context.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
50/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.