Add support for an offline reading experience (ePUB, PDF, etc.)

[krilnon]

The shipping book supports an offline reading experience with an ePUB version available on swift.org and on Apple Books. We should evaluate which formats we want to support going forward, and where in the publication pipeline we generate these artifacts.

Blocked by: https://github.com/apple/swift-docc/issues/354

rdar://71373710

[Gerzer]

I personally love that TSPL is available in the Apple Books store. It would be great if that availability can continue with this new publication pipeline!

[amartini51]

See also https://github.com/apple/swift-docc/issues/354, which likely requires much of the same underlying work in DocC.

[schwa]

A PDF of the TSPL book is almost required at this point. Losing the ability to download the TSPL seems like a major lose of usability and functionality.

[7ombie]

I had a couple of technical issues reading the book offline.

On the (11th-gen) Kindle Paperwhite (with an eInk display), the code examples (including inline code) use the same (variable width) font as the rest of the text.

In Apple Books, the syntax highlighting only works when the page is light. In Dark Mode, the code is all the same color. I'm not sure if this is a limitation of the software or an oversight with the formatting.

@schwa - The issue with PDFs is that you cannot resize them for tablets, ebook readers or people with poor eyesight. They only really work on desktops, where EPUB (and Apple Books) still makes more sense, at least generally.

[amartini51]

@7ombie Thanks for this feedback about the ePUB. However, that file was build using the legacy pre-DocC pipeline, which TSPL is no longer using. (That's why there's no longer an ePUB version of TSPL available.) When we investigate adding ePUB support to DocC, we can watch for these issues in case any of them re-occur.

[adamhill]

Any timeframe for EPUB / PDF output?

If this is going to take a while, can a static HTML site be generated by DocC that would be compatible with tablets / desktops?

How close is the current site that is generated able to be moved around as a ZIP archive and un-zipped on another computer for use?

Massive thanks to all the contributors for the work into DocC'ing the Swift Language spec!

[amartini51]

@adamhill You might have a better discussion in a GitHub issue specifically about DocC, such as https://github.com/apple/swift-docc/issues/354 (Is there a good way on GitHub to mark that issue as blocking this one?) The work to add support for PDF, ePUB, or static HTML would all happen in the DocC project — TSPL doesn't have any of its own build system.

The output from DocC requires running a server today — you can't just move the generated files around. It's more like a JavaScript web app that reads the documentation from a JSON file and renders content on the page. The --transform-for-static-hosting flag (on by default) passed to docc convert has something to do with not depending on server-side URL rewriting; it doesn't create plain non-JavaScript HTML output.

[adam-rocska]

Mind blown, that we no longer have Apple’s brilliant programming language’s Great Book in iBooks! Wth! I had notes, bookmarks, reading experience supporting my disability, had it offline, and the list goes on.

All of that is gone for good?

Given how long time ago the ditch was made, I guess I was patient enough with this rant.

Give us at least a lousy ebook or something. If I’d know how to do it, I swear I’d do it…

EDIT: No, the vue based clumsy webscript doesn’t replace it, the iPad’s reading mode can’t even parse the pages properly. Gosh I’m so disappointed and angry…

[amartini51]

@adam-rocska Thanks for writing this up. If you have time, and don't mind sharing it, what are the accessibility issues you run into with the ouput from DocC? It sounds like https://github.com/apple/swift-docc/issues/354 (feature request for DocC to support offline experience) doesn't capture all of the problem you're running into — but you can also add your use case and issues to that bug, if there are aspects it doesn't cover. It would be great if we can open bug(s) against DocC, in that other GitHub repo for accessibility problems.

As a workaround, you might try cloning this GitHub repository and rendering the markdown files locally. No, it's not ideal, but maybe it's better than all the issues you're having with the DocC output. There are a few places where TSPL uses DocC-specific markup (like term/definition lists and tables) but it should be 99% readable using a Swift Markdown, a plain GitHub-flavored-markdown renderer, or even cmark, since the majority of the formatting mostly just Commonmark.

[De-Byts]

Indeed it would be nice to have a PDF format both for having it on device and to make notes/bookmarks. I have created one for 5.9.2 with saving the website pages as pdf and concatenating the same in Preview. I myself made notes in my previous edition of Swift which unfortunately won't carry over. Swift 5.9.2 .pdf

[De-Byts]

. Swift 5.9.2 .pdf

One feature or annoyance is the hyperlinks go back to the site even when they don't need to(i.e., when the info could be a link to a point in the book itself).

[idevelop-app]

It would be really nice to have back the epub version, I use this reference mostly offline, thank you

[mjmsmith]

Swift 5.9.2 .pdf

How did you find this? Wondering if there a version for 5.10.

[nbalasundara]

I created it. Maybe I should do it for 5.10 as well! On May 11, 2024, at 1:30 PM, Mark Smith @.***> wrote:

Swift 5.9.2 .pdf

How did you find this? Wondering if there a version for 5.10.

—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you commented.Message ID: @.***>

[mjmsmith]

Thank you so much! Don't know if it would be tiresome for .x releases, but it would be great to have a refresh when 6.0 arrives.

[nbalasundara]

Will do!On May 12, 2024, at 9:52 PM, Mark Smith @.***> wrote: Thank you so much! Don't know if it would be tiresome for .x releases, but it would be great to have a refresh when 6.0 arrives.

—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you commented.Message ID: @.***>

[ekassos]

In case this helps anyone, here's the PDF version of the TSPL documentation I made for offline viewing based on 6.0.

TSPL Swift 6.0-beta.pdf

[nbalasundara]

Great, Thanks!!On Jun 23, 2024, at 6:18 PM, Evangelos Kassos @.***> wrote: In case this helps anyone, here's the PDF version of the TSPL documentation I made for offline viewing based on 6.0. TSPL Swift 6.0-beta.pdf

—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you commented.Message ID: @.***>

[mjmsmith]

In case this helps anyone, here's the PDF version of the TSPL documentation I made for offline viewing based on 6.0.

Thank you!

[liyanage]

I've been working on an up to date PDF/ePUB version of the current Swift 6 TSPL book that is based on the Markdown sources instead of a conversion of the rendered website, in order to provide a more full-featured PDF/ePUB reading experience. Here is the first version for anybody who is interested.

It features:

• A table of contents with working hyperlink entries
• A hierarchical PDF bookmark structure for the sections in the book
• Working cross-references between parts of the book (internal references are orange, links to the web are blue)
• Rendering/style that aims to stay consistent with the web version

The conversion is based on pandoc and its LaTeX/PDF/ePUB support. There are still some minor visual glitches, but overall I think it is already quite readable and useful.

Please follow up here if you see any issues, for now that's the best way to provide feedback.

I would like to thank @amartini51 for the extensive help and feedback in getting this conversion up and running.

• The-Swift-Programming-Language.pdf
• The-Swift-Programming-Language.epub.zip