Add remaining redirects from the old section/subsection URLs

[amartini51]

Because of the way Swift-DocC works, the URL we publish to must change from https://docs.swift.org/swift-book to https://docs.swift.org/documentation/swift-book. We need to set up server-side redirects on Swift.org so that links to chapters continue to work. These should be relatively straightforward.

In addition, TSPL specifies a stable ID for each heading's anchor. This is used for on-page navigation within the book, and frequently used outside of the book to provide a link directly to a specific heading. Because the DocC dialect of markdown doesn't allow us to specify an anchor's ID, all of these stable IDs will be destabilized and instead derived from the text of the section heading. (See also https://github.com/apple/swift-docc/issues/345)

For the second issue, we don't believe the web server can inspect the URL's fragment and offer different redirect options. It may be possible to use a bit of JavaScript on a "trampoline" page, located at the old URL, to redirect to the new URL.

rdar://96321914

[amartini51]

Fixed for chapters by https://github.com/apple/swift-book/pull/100, which also contains a proof of concept for section redirects.

[flbn]

is this still open? repo links to https://docs.swift.org/swift-book/, which redirects to https://docs.swift.org/swift-book/documentation/the-swift-programming-language/ as opposed to the https://docs.swift.org/documentation/swift-book link mentioned above (which results in a 404)

[amartini51]

@flbn The url https://docs.swift.org/documentation/swift-book is the URL I originally expected to use. DocC has limitations on URLs, so we ended up publishing at https://docs.swift.org/swift-book/documentation/the-swift-programming-language/ instead.

If you see links to https://docs.swift.org/swift-book/ in a Swift project, please either open an issue or a PR to update the link. I'm not sure which place you mean by "repo".

This issue is still open, tracking the second issue in its description — redirection of links to sections.

[flbn]

:0 sounds good, here's a quick PR: https://github.com/apple/swift-book/pull/113

[amartini51]

With the changes from #109 about 1/4 of the redirects still need to be manually filled in. Here's the process I've used to create those entries:

1. Check out commit 94646f9aa6ecd5a02a1670299d2a26663dfe7d02 in a separate directory, which was the last RST version of the book.
2. Identify a missing redirect in bin/redirects/redirect.swift by searching for docc: "" (an empty string).
3. Do a case-insensitive search for that line's sphinx parameter in the RST source, replacing - with _ in the search term.
4. If there's a search match, it will be right before the heading. Use the filename and the text of the heading to construct a DocC link, and write it in the docc parameter.
5. If there are no matches, use git log -S or git log -G to find the commit where the Spinx writer-specified ID was changed, and repeat the search using the new name. Or, if the section was deleted, try to pick a fallback heading that contains the same content.