Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Render the book to PDF and make it available for download #3863

Open
simonsan opened this issue Mar 17, 2024 · 7 comments
Open

Render the book to PDF and make it available for download #3863

simonsan opened this issue Mar 17, 2024 · 7 comments
Labels
blocked upstream Blocked on a change that needs to happen in a different repo first Online only

Comments

@simonsan
Copy link

simonsan commented Mar 17, 2024

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

@carols10cents
Copy link
Member

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?

@simonsan
Copy link
Author

simonsan commented Mar 18, 2024

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

@carols10cents
Copy link
Member

carols10cents commented Mar 20, 2024

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!

@carols10cents carols10cents added blocked upstream Blocked on a change that needs to happen in a different repo first Online only labels Mar 20, 2024
@Viicos
Copy link

Viicos commented Apr 15, 2024

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

@carols10cents
Copy link
Member

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?

@max-heller
Copy link

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.

@simonsan
Copy link
Author

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
blocked upstream Blocked on a change that needs to happen in a different repo first Online only
Projects
None yet
Development

No branches or pull requests

4 participants