Giters

rust-lang / book

The Rust Programming Language

Home Page:https://doc.rust-lang.org/book/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Render the book to PDF and make it available for download

simonsan opened this issue · comments

commented

Hey there,
@max-heller was a great help to comprehensive-rust and rust-patterns as they helped us set up rendering to PDF. So what's your opinion on having the book available as a nice looking PDF?

mdbook-pandoc has some pre-rendered examples in also of Rust-by-example and the book: https://github.com/max-heller/mdbook-pandoc?tab=readme-ov-file#rendered-books

(At this point, I think it makes sense to write up a condensed tutorial how to add PDF support to an existing mdbook...)

Some Resources

commented

Well, I don't know-- there already is the very nice eBook version available for purchase from No Starch Press, as well as using the "print" button and printing to PDF.

This book is also integrated into the rustc release process and packaged with Rust releases, so I'm not sure what kind of additional artifact production maintenance you're proposing to add.

In other words, my questions are:

  • How would the PDF you're proposing be different from what's already available?
  • What would adding this PDF generation entail, exactly?
commented

Well, I don't know-- there already is the very nice eBook version available for purchase from No Starch Press, as well as using the "print" button and printing to PDF.

The PDF, that would be generated would be basically a cleaner version of the mdbook print output, converted with pandoc to pdf. It has a TOC and the code blocks are coloured:

You can see the output here: https://github.com/max-heller/mdbook-pandoc/releases/latest/download/rendered-rust-book.pdf

In other words, my questions are:

* How would the PDF you're proposing be different from what's already available?

I don't see a free pdf version available, only the 40+$ version? I searched the repository for *.pdf but didn't find anything, did I miss it?

Otherwise, the availability is pretty limited to the online version and the print symbol, which doesn't take care of good layout. The pdf version and maybe the epub version in the future, are (IMHO) much cleaner and higher quality, e.g. for reading it on a tablet.

Also, you get all the features of a pdf and epub (readers), basically. Bookmarks, comments, etc.

* What would adding this PDF generation entail, exactly?
  • Some addition to the book.toml to configure pandoc
  • some apt install for the ci, to have the needed dependencies
  • and probably an addition of 3 lines to index.hbs in the theme, to add a download button (if needed) or linking it directly in the book.
  • maybe a section in a blog post about this in a future release of a new rust version, maybe when epub is integrated
  • linking it on the official website
commented

I don't see a free pdf version available, only the 40+$ version? I searched the repository for *.pdf but didn't find anything, did I miss it?

No, by "what's already available" I meant just the $ NoStarch version and print-to-PDF options. You've clarified that the difference in what you're proposing would be a table of contents and cleaner layout, thank you for the detail.

  • some apt install for the ci, to have the needed dependencies
  • linking it on the official website

So here's where it gets complicated: as I mentioned, the book is included in rust-lang/rust's CI process, is shipped as part of Rust, and ends up on doc.rust-lang.org/book as part of Rust's release process. If this PDF process breaks, it breaks rust-lang/rust. I am not going to make the decision to add these things without buy-in from people who maintain those parts of rust-lang/rust. So if you're interested in continuing to explore this possibility, please open an issue over there (and link over here) to start a discussion with those folks. Thanks!

commented

For the record, trying to build the book with mdbook-pandoc works without failures, just a couple warnings. For anyone interested, here is a build from latest:
book.pdf

commented

For the record, trying to build the book with mdbook-pandoc works without failures, just a couple warnings. For anyone interested, here is a build from latest:
book.pdf

That's a good one-time data point, but how stable is this over time?

commented

That's a good one-time data point, but how stable is this over time?

mdbook-pandoc's CI builds The Book and uploads it as an artifact for each commit to main. Obviously this is no guarantee of future success, and the version of the book that gets built isn't synced with the latest upstream commits. The biggest risks I see are network issues when embedding e.g. images—Comprehensive Rust has experienced some such spurious errors.

commented

The biggest risks I see are network issues when embedding e.g. images—Comprehensive Rust has experienced some such spurious errors.

I'm not sure, but it seems like the images for the book are in-repo: https://github.com/rust-lang/book/tree/main/src/img

So this error category may not fully apply?