TSPL review pass

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:

  1. Pick a chapter from GitHub issue 74 that hasn’t been reviewed yet.
  2. Open the current and new version of TSPL, using the links below, and navigate to the chapter you will review.
  3. Visually compare both versions, checking for problems or differences.
  4. If you find an issue, please open a GitHub issue and post a link to it on this thread.
  5. 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 @Comment or --> 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

The page-by-page comparison between the legacy and DocC versions of TSPL has finished. Thank you to all the folks who took time out of their day. We found and fixed about 50 issues total, including issues in the RST-to-markdown export process, configuration issues, and tooling issues.