doc: provide epub download of The Book

akavel commented 9 years ago

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 commented 9 years ago

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 commented 9 years ago

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

killercup commented 9 years ago

@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 commented 9 years ago

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

akavel commented 9 years ago

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

Gankra commented 9 years ago

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

killercup commented 9 years ago

@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 commented 9 years ago

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.

steveklabnik commented 8 years ago

Further update: I am still interested in getting this done, but takes some infrastructure work. @brson and @edunham and I should chat about it, maybe.

asolove commented 8 years ago

Working on a general way to do this in https://github.com/azerupi/mdBook/issues/88.

In the meantime, a rust book-specific version is probably as simple as:

pandoc -S -o book.epub {list of markdown files in the order they should be included}`.

brson commented 8 years ago

It's not too difficult to make one of our doc builders produce the epub files and for us to publish it. The big wart here though is that we produce doc packages for every platform we publish, so every builder needs pandoc in order to keep them at parity.

One thing we might do in the interim is to make epub artifacts opt-in, set up pandoc on our linux builder only (the one that we use to publish the docs to the website). Then we would be publishing the epubs, but e.g. the mac doc packages wouldn't contain it.

Incidentally, splittiing non-api docs out of the repo would (with a lot of other work) fix this problem since we could build all the docs on linux.

okulev commented 8 years ago

@killercup doesn't generate epubs anymore :-( So I made a script that generates proper Table Of Contents:

#!/bin/sh

if [ ! -d "$1" ]; then
    echo Usage: $(basename "$0") BOOKDIR \> trpl.md
    echo Then: pandoc -S -o trpl.epub trpl.md
    exit 1
fi

cat "$1/README.md"
echo

grep '^ *\*' "$1/SUMMARY.md" |
sed 's/^\*/main/g' |
sed 's/^ \+\*/sub/g' |
sed 's/\[.*\](\(.*\))/\1/g' |
while read level filename; do
    cat "$1/$filename" |
    if [ "$level" = "main" ]; then
        sed 's/^\(#\+ \)/#\1/g' |
        sed 's/^% /# /g'
    else
        sed 's/^\(#\+ \)/##\1/g' |
        sed 's/^% /## /g'
    fi |
    sed 's/^\(```rust\),.*$/\1/g'
    echo
done

pravic commented 8 years ago

@killercup doesn't generate epubs anymore :-(

@okulev, but you can find it in PRs as I did.

edunham commented 8 years ago

Help wanted: Write a .travis.yml to do this build on Travis and upload it to GitHub's releases storage. (ping me for help if this is confusing)

bkoehm commented 7 years ago

Script from @okulev worked nicely for me, so +1 for that. I wanted a PDF instead of an EPUB so I added this step:

ebook-convert trpl.epub trpl.pdf \
  --margin-top 36 --margin-bottom 36 \
  --margin-left 36 --margin-right 36

ebook-convert is from Calibre.

I tried ebook-convert directly on the md instead of epub and it produced a PDF, but the resulting PDF is better if you use pandoc to convert it to epub first.

pandoc may be able to convert directly to PDF without ebook-convert, but I got errors from pandoc about unrecognized unicode characters. ("Unicode char" ... "not set up for use with LaTeX".) That's probably fixable for someone that knows more about pandoc and LaTeX than I do.

EDIT: I got pandoc PDF conversion working. No need for ebook-convert. The trick was adding the --latex-engine=xelatex option. i.e., pandoc --latex-engine=xelatex -V geometry:margin=0.5in -V fontsize=12pt -o /tmp/trpl.pdf /tmp/trpl.md. And the quality of this output is superior compared to my previously described attempts.

pravic commented 7 years ago

Any download links to the recent book versions?

codingHahn commented 7 years ago

@killercup 's repo works, but the files need to be updated. @killercup how would I do this?

pravic commented 7 years ago

Since there is no progress: https://github.com/lise-henry/books - not perfect, but from June 2017. https://github.com/killercup/trpl-ebook/pull/47 PR for killercup's books from May 2017, but unmerged.

That's all I found, rest are just talks and wishes.

jasonwilliams commented 6 years ago

@steveklabnik @brson any update on this? There’s still no easy way to read the rust book offline on an iPad. I wonder if we can use service workers to cache all the pages on the site, the single page html doesn’t work as it chokes my tablet

steveklabnik commented 6 years ago

No changes; print to PDF is still the best option.

jasonwilliams commented 6 years ago

On iOS the default option is to add the PDF to ibooks where it doesn’t come out right, you can’t use the built in features such as bookmark, take notes, page numbers, index. Is there not an easy way to auto generate an epub file on each update?

If it’s a case of time anyway I can help? A PDF link would also be nice on the rust book page.

steveklabnik commented 6 years ago

Is there not an easy way to auto generate an epub file on each update?

Not currently.

If it’s a case of time anyway I can help?

Sure! The first thing we'd need is support in mdbook; then we'd have to change the infrastructure to actually use that new code.

jasonwilliams commented 6 years ago

@steveklabnik I’m not sure if this is the right repo to raise it, but could we take advantage of service workers to cache the book so it can be read offline? I would be happy to work on this if it’s possible. Edit: I can raise in the rust book repo

pravic commented 6 years ago

May be offline version is abandoned in favor of the printed version?

Upd: it's claimed to be identical with the second edition. I wouldn't mind to buy it, personally, but not in pdf form - it is terrible for ebook readers.

steveklabnik commented 6 years ago

May be offline version is abandoned in favor of the printed version?

It's not, it's abandoned because nobody has wanted to put in the work to get it working. The second edition online is literally the same as the printed book / ebook as far as the text goes; No Starch has their own typesetting and such that makes their PDF worth buying, but that doesn't preclude us from generating one ourselves as well.

hawkins commented 5 years ago

FWIW, a PR was opened against the book to add support for building an ePub just last week: https://github.com/rust-lang/book/pull/1654

It includes a link to download the built ePub as well, for any readers looking for a more recent version but without the overhead of compiling it yourself

gluons commented 5 years ago

I'm also waiting for EPUB. I just start learning Rust. I'm frequently reading on mobile in train. Reading on web isn't comfortable for me. ☹️

jasonwilliams commented 5 years ago

@gluons yep i had the same issue, I ended up buying the e-book of Amazon because i needed an offline version for train reading.

is it possible to take @jmoy's PR and apply it to https://github.com/rust-lang-nursery/mdBook/issues/88 instead?

monokrome commented 5 years ago

What's the status here? I'd love to get this book on my Kobo reader :)

justacec commented 5 years ago

Ohhh please....

This is me not reading the rust documentation on my flight from San Diego to DC...

dolph commented 5 years ago

Resolving this issue would be entirely worth the effort. For Rust to be successful, people need to be able to learn about it, and this issue is fundamentally about accommodating alternative learning environments.

steveklabnik commented 5 years ago

@justacec you can rustup doc --book to read the book in HTML form locally.

@dolph nobody disagrees that this is worth doing. Nobody has stepped up to actually do it.

jiacai2050 commented 5 years ago

Is there anyone try Calibre? looks promising.

vitali2y commented 5 years ago

Next quick "life hack" for many formats (e. g. epub, docbook, or fb2) works for up-to-date and any doc from Learn Rust page:

click "Print this book" icon on top right corner,
"Cancel" print popup,
press F12,
copy-n-paste-n-enter next into "Console" tab:

document.getElementById('sidebar').remove();
document.getElementById('menu-bar').remove();
Array.from(document.querySelectorAll("div.buttons")).forEach(el => el.remove());
Array.from(document.querySelectorAll("img.ferris")).forEach(el => el.remove());
document.getElementById('page-wrapper').classList.remove('page-wrapper');
Array.from(document.getElementsByTagName('script')).forEach(el => el.remove());
document.getElementById('sections').remove();

Hint: next extra line is required for WebAssembly Book (because paths to images are broken in print mode):

Array.from(document.getElementsByTagName('img')).forEach(function(el) { if (el.src.indexOf('https://rustwasm.github.io/docs/images/') > -1) el.src = 'https://rustwasm.github.io/docs/book/images/game-of-life/' + el.src.split(/[/ ]+/).pop() });

right mouse click, "Save as..." HTML (e. g. TheRustcBook190626.html) file (use "Webpage, Complete" file type for saving!),
from CLI execute:

F="TheRustcBook190626" && pandoc $F.html --to=epub --output=$F.epub && ls -l $F.epub

enjoy TheRustcBook190626.epub on your e-reader!

DevQps commented 5 years ago

For people that are curious about what it would look like:

As an extra tip!: If you want the page to be broader (so you don't have to zoom in on some E-readers) you can also add:

document.getElementsByTagName("main")[0].style.maxWidth = "";

You would then get something like this:

I am not sure how hard it would be to create a small program that could also generate a PDF or EPUB file and add a button to download it on each webpage. I might try to look into that if I can find some time!

jasonwilliams commented 5 years ago

As a slight update to this thread, I'm going to see if i can get https://github.com/rust-lang-nursery/mdBook/issues/546 moving again, as the people previously working on it have left.

DevQps commented 5 years ago

@jasonwilliams That would be great! Let us know if there's any progress! (Y)

jasonwilliams commented 5 years ago

@DevQps There is progress, and you can help! See https://github.com/rust-lang-nursery/mdBook/pull/1000 Test it out and give feedback, there are instructions in the PR

kaizhang16 commented 5 years ago

Hello everyone, I have generated the epub and pdf version by pandoc inspired by https://github.com/rust-lang/rust/issues/20866#issuecomment-170563129. And here is the links:

Hope it helps.

antoneliasson commented 4 years ago

Hello everyone, I have generated the epub and pdf version by pandoc inspired by #20866 (comment). And here is the links:
* https://github.com/kaizhang91/book/blob/feature-epub-and-pdf/assets/The-Rust-Programming-Language-2019-10-13.epub

* https://github.com/kaizhang91/book/blob/feature-epub-and-pdf/assets/The-Rust-Programming-Language-2019-10-13.pdf
Hope it helps.

Thanks for generating the offline ebooks! Your epub lacks the "ferrises" in the code boxes and some words are hyphenated in strange ways, but otherwise it looks great and is perfectly usable! I've so far enjoyed about the first quarter of it.

The PDF on the other hand has a few major problems. Some code boxes are completely missing content (e.g. page 22, pages 74-80). In at least one place a big chunk of text is missing. Some of it has not compiled properly and is shown as a compressed super long line of TeX code (page 29).

An epub rendering is what I wanted the most though, so thanks again for that!

kaizhang16 commented 4 years ago

@antoneliasson Thank you for your detailed bug report! I'm very happy to hear about that the offline book is helpful. However, let me clarify some points:

the epub version:
- It does not lack "ferrises". It's true that they aren't shown on duokan or iReader, but they are shown on calibre. So the bug is related to the capacity of epub reader for rendering some css syntax.
- Actually, image and code block are also not supported by some epub reader
the pdf version:
- As you kindly explained, there are some serious bugs in 2019-10-13 version, so I create 2019-10-17 version
- In 2019-10-17 version, I have solved code box bug. And I think it's true for page 22, pages 74-80, etc.
- In 2019-10-17 version, there are still some super long lines. This bug is related to https://github.com/gpoore/minted/issues/194. Maybe I have no time to fix it recently.
- I will change above link to 2019-10-17 version instead of 2019-10-13 version.

In fact, I have read through the 2019-10-17 pdf version instead of the 2019-10-13 epub version. :smiley: Maybe some serious bugs you most care about have already been fixed. Give it a try if you're interested in the pdf version someday. :wink:

jasonwilliams commented 4 years ago

Help Needed!

https://github.com/rust-lang/mdBook/pull/1000 seems to be working pretty well from what i can see so far, I just need some feedback now. The PR allows the rust book to be read offline, new changes will still take affect.

You can just navigate to https://jason-williams.co.uk/book/ and try it out, then leave any feedback in the issue above.

Sjord commented 3 years ago

I recently used mdbook-epub to build an epub version of several mdbooks, and this worked reasonably well.

shirshak55 commented 2 years ago

For pdf: https://github.com/shirshak55/Rust-Book-In-PDF/releases

I update the pdf every day via ci so it should be somewhat better :) Also, sorry I myself never use mobi so don't have any incentives to do it.

vitali2y commented 2 years ago

Letting you know that .epub version of the Book would be nice to have here.

peterbartha commented 2 years ago

Latest DIY steps for converting (any) Rust learning material to EPUB (or other ebook formats). Steps and required files: https://gist.github.com/peterbartha/54708ae739478a45b52612311d49717c

Samples:

vitali2y commented 2 years ago

Latest DIY steps for converting (any) Rust learning material to EPUB (or other ebook formats). Steps and required files: https://gist.github.com/peterbartha/54708ae739478a45b52612311d49717c

What are principal improvements in comparison with ~3 years old receipt?

peterbartha commented 2 years ago

Latest DIY steps for converting (any) Rust learning material to EPUB (or other ebook formats). Steps and required files: https://gist.github.com/peterbartha/54708ae739478a45b52612311d49717c

What are principal improvements in comparison with ~3 years old receipt?

The following:

More readable source code (previously problems with nested <pre> tags, and pandoc optimizations),
Clickable "Table of Contents" section added,
Code legend (Ferris) is present (instead of removing from the samples),
Handle unsupported HTML tags (i.e. <details>),
(Optional) Consistent stylesheet for the ebook.

johnroyer commented 2 years ago

The file below, published at 2022-01-13, is convert via Epubor. Download if you need.

https://s3.ap-northeast-1.amazonaws.com/assets.blog.zeroplex.tw/2022/2022-01-13-The-Rust-Programming-Language.epub

zhoukuncheng commented 2 years ago

This browser extension can convert HTML to EPUB easily. https://github.com/dteviot/WebToEpub

rust-lang / rust

doc: provide epub download of The Book #20866