Hi all!
I'm just starting to learn Swift today and downloaded the Swift toolchain from the officially supported method (winget install --id Swift.Toolchain -e)
All of the official docs point to the online book (Documentation) for learning the language, but it seems like the book is covering a different major version of the language (6.0) than what is currently availible to download (5.10).
Is there a way to access the 5.10 book, or is the Windows package distribution just not up to date yet?
Sadly, this has been a perennial problem around this time of year, when the beta releases of the next version come out:
I fear it's gotten worse as I think the iBooks releases are no longer; last I recall, the only solution is to find someone with an archived version of the last version of TSPL.
You could try downloading the source for the book for the version you desire from https://github.com/apple/swift-book/tags, and
run docc preview TSPL.docc in this repository's root directory.
It would be nice if there were a version picker on https://docs.swift.org/swift-book/documentation/the-swift-programming-language/!
Thanks for the pointer. I will pull and build the docs locally as a temporary workaround.
After making this post I saw that Swift 6.0 is not going to be released until September, so definitely seems like a bug for the 5.10 documentation to no longer exist on the site.
We have an issue tracking simultaneous publishing of beta+release versions of the book here: Improve docs experience for those not running the latest beta · Issue #26 · apple/swift-book · GitHub
More generally, there's a tradeoff between making custom things work just for the Swift book versus adopting what the people working on DocC and the Swift website create. Versioning sits in that space.
Also, you can search for text in a local copy (since the hidden symbol search feature has limited utility).
could we roll back the version of the book on the website to 5.10, until such time as 6.0 is actually released? ideally we could show both, but until that happens we should really be defaulting to 5.10 and not an unreleased version of Swift.
As others have said, it's a known issue that doesn't have a quick fix available. If the GitHub issue that Kyle linked doesn't describe your use case already, please add a few paragraphs to describe how this impacts your development. That kind of information can be very helpful when managers are prioritizing which DocC work gets engineering time.
You can also look at the revision history to see what's different between the Swift 5.10 and 6 versions of the book. In this specific case, the material about Swift 6 is contained in new sections that you can skip if you're targeting Swift 5.10. In other releases, you'll see new information added that also applies to previous Swift versions — for example, when the in-progress branches are merged that discuss what "safety" means and provide conceptual information about data races, that content applies to Swift 5 and 6.
If you want to to see exactly what was added, you can also compare tags, which shows you all the other minor corrections and typo fixes that are omitted from the revision history:
If a rollback to 5.10 isn't possible, is there any way to add disclaimers to the book more precisely indicating which information is about beta/unreleased features?
As it stands TSPL serves as the language reference and the learning resource that everyone is officially pointed to, and every page seems to have a big disclaimer that the page is talking about beta content that is subject to change before it's released to the public.
As someone trying to learn the language, it's not a great experience for the current language reference to not be hosted anywhere online. The GitHub issue linked is proposing a new feature/enhancement on DocC, while this forum thread is about a current issue with the documentation that shouldn't theoretically be blocked on a new feature before it can be fixed by rollback or editing the book contents.
i went ahead and added a copy of TSPL at version 5.10 on Swiftinit, and you can also compare it to the top-of-tree main version. please let me know if you encounter any issues!
Thank you!