As we get ready to publish the DocC version of “The Swift Programming Language”, we’re taking a review pass over the entire book this week, to check for markup issues, DocC bugs, or problems with the RST-to-markdown conversion. If you’d like to be part of that review process, please highlight any issues you find in this forum thread.
Suggested steps for reviewing:
- Pick a chapter from GitHub issue 74 that hasn’t been reviewed yet.
- Open the current and new version of TSPL, using the links below, and navigate to the chapter you will review.
- Visually compare both versions, checking for problems or differences.
- If you find an issue, please open a GitHub issue and post a link to it on this thread.
- After you finish a chapter, comment on this thread and we’ll update issue 74.
Published version: https://docs.swift.org/swift-book/GuidedTour/GuidedTour.html
New version: https://krilnon.github.io/swift-book/documentation/the-swift-programming-language/guidedtour
Specific things to watch for, which we've run into so far:
- Broken links
- Titles and labels that got changed by accident
- Content that's missing or displayed wrong
- Incorrect output for nested markup, like code listing in a list item
- Comment markers like
@Commentor-->appearing in output
We already have bugs tracking the following known issues:
- DocC doesn't support placeholders (blue bubbles)
- DocC doesn't support downloading the tour as a playground
- DocC doesn't support downloading the whole book as an ePUB
- Formal grammar doesn't contain links to the definition of each syntactic category
- Formal grammar doesn't have blank lines between groups of definitions
- The overview heading that DocC adds looks awkward
- The previous/next chapter navigation is missing
- Code listings in the book are no longed tested/testable