`rustup doc --book` to directly link to subsections and paragraphs of the book

[Wilker-uwu]

Problem you are trying to solve

i came up recently with this case in Rustlings, where i wanted the hints in the exercises to point out sections of the book to be cross-referenced when completely offline, but all the hints in those exercises links to online resources instead.

main problem is, someone pointed out there's way too many variables to keep track of to be worth maintained in Rustlings alone, ranging from browser installation checks, to the file URLs which Rustup already handles. so the current options in Rustlings' side as of now may become either make the user setup a Hosts file redirect into the offline book, or omit links altogether and just hint the user to the chapter section and the existence of the rustup doc commands, as opposed to having both the links and the commands on all relevant hints.

so my thought with this was, if it was maintained on Rustup's side instead, that'll probably be worth it better since it's gonna become easily accessible outside anyway.

Solution you'd like

the access would be made for commands like

$ rustup doc --book chapter-part[-section[-subsection]]

for instance,

$ rustup doc --book 03-05-02-02
#not sure if this would require changing how all the HTML page links and headers are written

would ammount to file:///…/book/ch03-05-control-flow.html#returning-values-from-loops
but maybe an easier approach could be to instead index all headers in the book together and make them accessible by name directly like so:

#this does the same except it's easier to see where you're going to from the start.
$ rustup doc --book returning-values-from-loops 

i think this would enable for easier access to notes and not just the use for the initial learning of the language. what do you think?

Notes

No response

[jasperyou]

This is a good idea，so Amazing。

[YegorStolyarov]

This is a good idea，so Amazing。

I tried to create easier way to link subtopics without indexing book contents, just by adding url tail as param
If PR will be merged, it should work:
rustup doc --book ch03-05-control-flow.html#returning-values-from-loops

[rbtcollins]

I think supporting fragments in the rustup doc command line interface makes sense; invoking rustup is already an explicit user action (whether directly or via an IDE), so I'm not worried about injection attacks.

I do like the proposed UX for semantic indexing into books, but thats not something rustup can solve for on its own: the generated books from the rust repository itself have to have a defined interface that they can commit to not changing - or at least changing slowly. I think perhaps putting that into the metadata for the doc package in the channel metadata, or putting it in a file in the doc distribution itself might work.

The point being that rustup installs many different versions of rust - going waaay back - and will install all new future versions; so where something is layout-specific we try quite hard to make sure that the authors of the thing can provide data to drive rustup, rather than rustup doing a release each time a cross-project fix is needed.

[rami3l]

I tried to create easier way to link subtopics without indexing book contents, just by adding url tail as param If PR will be merged, it should work: rustup doc --book ch03-05-control-flow.html#returning-values-from-loops

With #4070, it's possible to do something like rustup doc --rustc platform-support::armv6k-nintendo-3ds::building-the-target.

As such, I'm closing this issue now.

PS: Due to a restriction with our upstream Seeker14491/opener and/or the underlying macOS open command, anchors (such as #building-the-target in this case) are unfortunately ignored when using this syntax.

[Wilker-uwu]

thank you so much ^~^