doc: provide epub download of The Book

[akavel]

Could you possibly add an .epub version of The Book for download on the website?

The epub format seems at least mentioned in some Makefiles, so I hope this should be not very hard -- unless it's defunct and unsupported, and would have to be done from scratch? If not, then still there are some tools like pandoc, that I think support making epubs from Markdown already, so at least should be doable without reinventing the tools...

I'd be very grateful, thanks.

[killercup]

I've thought about this, as well. @steveklabnik, too.

Technically, this might a bit tricky, partially because of #20826.

What you need to do is create one markdown document with a correct outline (i.e. cleverly interpreting and changing headline levels) and in order of the table of contents (i.e. parsing the TOC file which is a markdown list containing links). But then it would be trivial to feed that to pandoc and generate all sorts of formats!

[akavel]

As to #20826, I've just sent a pull request that might (or might not) close the issue.

[killercup]

@akavel I don't think that'll solve this problem by itself, since all the chapter headings are actually level two in the global table of contents.

E.g., "2.8. Compound Data Types" should be a level 2 heading in an ebook, therefore the content of that chapter should start headings at level 3. (In an epub/book, heading level 1 might be a "part", level 2 might be a "chapter" and level 3+ might be subsections.)

Your changes might simplify the script needed to compile the book contents though.

[killercup]

@akavel @steveklabnik I created an epub version of the book!

• Explanation on reddit with download link
• Gist with the script to generate the file

[akavel]

Woohoo, awesome, thanks a lot! And the code samples seem to wordwrap quite nicely on my nook too, big thanks! :)

[Gankra]

@killercup would it be possible to integrate this back into our toolchain for us to officially provide it?

[killercup]

@gankro please do! Consider the code to be in the public domain; just take it, it's yours.

I don't think it'd take much time to rewrite this in Rust, it's just a bunch of calls to pandoc. It would be a nice feature for rustbook.

[killercup]

Just an update: Last week I redid most of that script I posted above. This now also deals with normalizing code blocks and fixing links. You can find it here and the results (html, epub, pdf) here.