Closed akavel closed 11 months 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!
As to #20826, I've just sent a pull request that might (or might not) close the issue.
@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.
@akavel @steveklabnik I created an epub version of the book!
Woohoo, awesome, thanks a lot! And the code samples seem to wordwrap quite nicely on my nook too, big thanks! :)
@killercup would it be possible to integrate this back into our toolchain for us to officially provide it?
@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.
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.
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}`.
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.
@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
@killercup doesn't generate epubs anymore :-(
@okulev, but you can find it in PRs as I did.
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)
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.
Any download links to the recent book versions?
@killercup 's repo works, but the files need to be updated. @killercup how would I do this?
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.
@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
No changes; print to PDF is still the best option.
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.
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.
@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
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.
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.
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
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. ☹️
@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?
What's the status here? I'd love to get this book on my Kobo reader :)
Ohhh please....
This is me not reading the rust documentation on my flight from San Diego to DC...
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.
@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.
Is there anyone try Calibre? looks promising.
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:
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() });
F="TheRustcBook190626" && pandoc $F.html --to=epub --output=$F.epub && ls -l $F.epub
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!
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.
@jasonwilliams That would be great! Let us know if there's any progress! (Y)
@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
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.
Hello everyone, I have generated the
epub
andpandoc
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!
@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:
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.image
and code block are also not supported by some epub reader2019-10-13
version, so I create 2019-10-17
version2019-10-17
version, I have solved code box bug. And I think it's true for page 22, pages 74-80, etc.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.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:
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.
I recently used mdbook-epub to build an epub version of several mdbooks, and this worked reasonably well.
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.
Letting you know that .epub version of the Book would be nice to have here.
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:
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?
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:
<pre>
tags, and pandoc optimizations),<details>
),The file below, published at 2022-01-13, is convert via Epubor. Download if you need.
This browser extension can convert HTML to EPUB easily. https://github.com/dteviot/WebToEpub
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.