Skip to content

Add anchors to split chapters on landing page #51

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Add anchors to split chapters on landing page #51

wants to merge 1 commit into from

Conversation

albel727
Copy link

@albel727 albel727 commented May 2, 2017

This is intended to fix #50, at least temporarily.

I've dug out the last non-split version of the reference and, with a help of a small Ruby script, generated a landing page, which superficially resembles the old reference, but instead of the actual contents, links to the chapters of the new reference.

This approach relies on the Markdown->HTML converter generating anchoring ids for section headers in the particular backward-compatible way, as well as on unchanging section headers in the new reference, i.e.

  1. If the markdown generator changes in the future so that its header_text->anchor_id generation no longer matches the old behaviour, then the page becomes useless. This can be worked around by using a pre-generated static html page instead of Markdown.
  2. If sections are renamed in the new reference, the fragment parts of redirection links on the landing page would no longer match. But at least, the links would still lead to the correct chapter pages.

@steveklabnik
Copy link
Member

This approach relies on the Markdown->HTML converter generating anchoring ids for section headers in the particular backward-compatible way, as well as on unchanging section headers in the new reference, i.e.

I forget if rustdoc does this, actually. But...

This can be worked around by using a pre-generated static html page instead of Markdown.

I wonder if this approach just isn't better, because then it will always work, and it's not like there's heavy development going on here.

If sections are renamed in the new reference, the fragment parts of redirection links on the landing page would no longer match. But at least, the links would still lead to the correct chapter pages.

This will probably happen, but at least that's not too bad, and we can always fix it.

Anyway, let's go the HTML route. Can you run rustdoc on this file, and change the PR to have the HTML instead? Thanks for this.

@albel727 albel727 closed this May 3, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Provide a migration page from the old single page to new split reference pages format
2 participants