killercup / trpl-ebook Goto Github PK

View Code? Open in Web Editor NEW

477.0 35.0 56.0 26.65 MB

UNMAINTAINED

Home Page: http://killercup.github.io/trpl-ebook/

Shell 0.37% CSS 15.11% HTML 6.04% TeX 14.73% Rust 63.76%

trpl-ebook's Introduction

'The Rust Programming Language' as EBook

This repository contains stuff to convert this book to HTML, EPUB and PDF.

Download Links

DIY

Install:

pandoc
Rust and cargo
XeLaTeX, up to date (sudo tlmgr update -all) and probably some additional packages (sudo tlmgr install $pkg) such as:
- framed
- hyphenat
- quotchap
- collection-fontsrecommended
- mathspec
- euenc
- xltxtra
- xecjk
- fancyhdr
the DejaVu Sans Mono font: http://dejavu-fonts.org/
the IPA font for Japanese Text: http://ipafont.ipa.go.jp/ipaexfont/download.html#en

Then run:

$ cargo run --release

Voilà!

Build different books

There are some CLI arguments that you can use to compile books other than the default (trpl). E.g., this repository also include the Rustonomicon.

You can build it like this:

$ cargo run --release -- --prefix=nomicon --source=nomicon --meta=nomicon_meta.yml

License

trpl-ebook's People

Stargazers

Watchers

Forkers

makemefriendanshu janusnic arden lgscofield akiress hainuo wangtiger878 xallss won21kr gankra just-d voidexception casimir jaxx ggomagundan mcarton robisys tomikes havk64 d3m3vilurr talklittle axlrose stormgbs adiultra adamrlukaitis tarun-verma owencook little-dude zoosky jcnoir codinghahn la10736 tfheen justryuz badpasta phyber dyhpoon palnabarun akappel abcdev kdxu zwindl maserg pjakma hoangpq pdoro oemaix beyondkmp johnsonhit v-indigo root83cn terence-deng stjordanis mouse07410 iq-scm agustinmorantes

trpl-ebook's Issues

table of contents for HTML format

...
nav {
float:left;
position: fixed;
top: 5px;
left: 10px;
bottom: 5px;
width: 285px;
overflow: auto;
}
</style>

Make Relative Links Absolute

Stuff like ../std/borrow/trait.Borrow.html is obviously broken.

i got one error on building pdf(a4)

the error is

! Undefined control sequence.
l.196 \tightlist

pandoc: Error producing PDF from TeX source

change some fonts in template.tex

can you help me ?

my rep is https://github.com/hainuo/trpl-ebook

Replace Ascii Art in "Basic terminology: Crates and Modules"

This doesn't render well in PDF or EPUB as it may be broken across multiple pages or line wrapped.

We could replace this with either a plain list like this:

Phrases

English

Greetings

Farewells

Japanese

Greetings

Farewells

or with a graphic (using graphviz, e.g.). The latter would look better but also requires us to deal with image format support of various devices (PDF for LaTeX, SVG for HTML and some eReaders, PNG for the rest).

Reference points to incorrect URL

In http://doc.rust-lang.org/book/conditional-compilation.html, the reference "[features] section" links to

http://doc.crates.io/manifest.html#the-[features]-section

But the PDF links to

http://doc.crates.io/manifest.html#the- {[}features{]}- section

Support latest trpl book

Hi, thanks a lot for your work on that.

Unfortunately it seems severely outdated as of now; would it be possible to support 2018 edition of the book?

Thanks again.

Links to local files are broken

doesn't work with pandoc 2.2.1

» cargo run --release
    Finished release [optimized] target(s) in 0.05s                                                                                                                      
     Running `target/release/compile-trpl`
Reading book..................................................................... done.
[✓] MD
--smart/-S has been removed.  Use +smart or -smart extension instead.
For example: pandoc -f markdown+smart -t markdown-smart.
--normalize has been removed.  Normalization is now automatic.
Try pandoc --help for more information.
thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Os { code: 32, kind: BrokenPipe, message: "Broken pipe" }', libcore/result.rs:945:5
note: Run with `RUST_BACKTRACE=1` for a backtrace.

Cannot convert correctly for references links

When I put the current docs of the official Rust source, I found there were some incorrect results on references link that is [ref] style in the original book, such as some [references]s rather than [references][references]s occurred in the article primitive types.

I have looked up the src of the tool and found the issue was on the /src/helpers/adjust_reference_names.rs that could not dealt with all kinds of references links:

    let reference_link = Regex::new(r"(?x)
        \]\[                # This is a link to a reference
        (?P<id>.+?)         # The reference name
        \]
    ").unwrap();
...
        if reference_link.is_match(line) {
            let new_line = reference_link.replace_all(line, |matches: &Captures| {
                format!("][{prefix}--{id}]",
                    prefix = prefix,
                    id = matches.name("id").expect("no id in ref link")
                )
            });
            return initial + &new_line + "\n";
        }

The code just works on unique style of the references links.

Use booktabs

Use booktabs, because

[22:54:21] killercup: If you want to have anything in publication quality, you need to use booktabs. Standard TeX tables are fugly
[22:54:40] killercup: Also, I once read somewhere that pandoc can handle that (with a suitable tempalte)

Add mobi format

Please add mobi format for support kindle

Oddly formatted note dissapears in conversion

A little above http://doc.rust-lang.org/book/the-stack-and-the-heap.html#arguments-and-borrowing you see the text "[moving]" where all but the first "[" is sup, which seems to refer to a note a little below:

[moving]: We can make the memory live longer by transferring ownership, sometimes called ‘moving out of the box’. More complex examples will be covered later.

In the PDF (A4, page 64), the reference appears as "[ˆmoving]", and the note I quoted above has gone missing.

Error while building TRPL second edition:

I am trying to build the second edition of the book. I have copied over the source files from trpl/second-edition/src in the TRPL source code repository on Github.

nabarun@pal:~/codesl/trpl-ebook (git:master) $ ls trpl
appendix-00.md                              ch08-01-vectors.md                                  ch15-01-box.md
appendix-01-keywords.md                     ch08-02-strings.md                                  ch15-02-deref.md
appendix-02-operators.md                    ch08-03-hash-maps.md                                ch15-03-drop.md
appendix-03-derivable-traits.md             ch09-00-error-handling.md                           ch15-04-rc.md
appendix-04-macros.md                       ch09-01-unrecoverable-errors-with-panic.md          ch15-05-interior-mutability.md
appendix-05-translation.md                  ch09-02-recoverable-errors-with-result.md           ch15-06-reference-cycles.md
appendix-06-newest-features.md              ch09-03-to-panic-or-not-to-panic.md                 ch16-00-concurrency.md
ch01-00-introduction.md                     ch10-00-generics.md                                 ch16-01-threads.md
ch01-01-installation.md                     ch10-01-syntax.md                                   ch16-02-message-passing.md
ch01-02-hello-world.md                      ch10-02-traits.md                                   ch16-03-shared-state.md
ch02-00-guessing-game-tutorial.md           ch10-03-lifetime-syntax.md                          ch16-04-extensible-concurrency-sync-and-send.md
ch03-00-common-programming-concepts.md      ch11-00-testing.md                                  ch17-00-oop.md
ch03-01-variables-and-mutability.md         ch11-01-writing-tests.md                            ch17-01-what-is-oo.md
ch03-02-data-types.md                       ch11-02-running-tests.md                            ch17-02-trait-objects.md
ch03-03-how-functions-work.md               ch11-03-test-organization.md                        ch17-03-oo-design-patterns.md
ch03-04-comments.md                         ch12-00-an-io-project.md                            ch18-00-patterns.md
ch03-05-control-flow.md                     ch12-01-accepting-command-line-arguments.md         ch18-01-all-the-places-for-patterns.md
ch04-00-understanding-ownership.md          ch12-02-reading-a-file.md                           ch18-02-refutability.md
ch04-01-what-is-ownership.md                ch12-03-improving-error-handling-and-modularity.md  ch18-03-pattern-syntax.md
ch04-02-references-and-borrowing.md         ch12-04-testing-the-librarys-functionality.md       ch19-00-advanced-features.md
ch04-03-slices.md                           ch12-05-working-with-environment-variables.md       ch19-01-unsafe-rust.md
ch05-00-structs.md                          ch12-06-writing-to-stderr-instead-of-stdout.md      ch19-02-advanced-lifetimes.md
ch05-01-defining-structs.md                 ch13-00-functional-features.md                      ch19-03-advanced-traits.md
ch05-02-example-structs.md                  ch13-01-closures.md                                 ch19-04-advanced-types.md
ch05-03-method-syntax.md                    ch13-02-iterators.md                                ch19-05-advanced-functions-and-closures.md
ch06-00-enums.md                            ch13-03-improving-our-io-project.md                 ch20-00-final-project-a-web-server.md
ch06-01-defining-an-enum.md                 ch13-04-performance.md                              ch20-01-single-threaded.md
ch06-02-match.md                            ch14-00-more-about-cargo.md                         ch20-02-slow-requests.md
ch06-03-if-let.md                           ch14-01-release-profiles.md                         ch20-03-designing-the-interface.md
ch07-00-modules.md                          ch14-02-publishing-to-crates-io.md                  ch20-04-storing-threads.md
ch07-01-mod-and-the-filesystem.md           ch14-03-cargo-workspaces.md                         ch20-05-sending-requests-via-channels.md
ch07-02-controlling-visibility-with-pub.md  ch14-04-installing-binaries.md                      ch20-06-graceful-shutdown-and-cleanup.md
ch07-03-importing-names-with-use.md         ch14-05-extending-cargo.md                          img
ch08-00-common-collections.md               ch15-00-smart-pointers.md                           SUMMARY.md

However, when I try to build the book, I encounter the following error:

nabarun@pal:~/codesl/trpl-ebook (git:crate-update) $ cargo run --release                                                                                                 
    Finished release [optimized] target(s) in 0.0 secs
     Running `target/release/compile-trpl`
Reading book.thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Error { repr: Os { code: 2, message: "No such file or directory" } }', libcore/resul
t.rs:916:5
note: Run with `RUST_BACKTRACE=1` for a backtrace.

I also tried with:

nabarun@pal:~/codesl/trpl-ebook (git:crate-update) $ ./target/release/compile-trpl --source=/home/nabarun/codesl/trpl-ebook/trpl
Reading book.thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Error { repr: Os { code: 2, message: "No such file or directory" } }', libcore/resul
t.rs:916:5
note: Run with `RUST_BACKTRACE=1` for a backtrace.

and I get the same error.

Did anybody else try to do the same?

At least some superscript text is rendered as normal

On page 60 (A4) for example it reads: "That number comes from 230, the number of bytes in a gigabyte." where is should read "That number comes from 2^30, the number of bytes in a gigabyte."

Error while installing

I am new to rust and I wanted to generate the epub format ebook for my kindle.

I downloaded the project to rebuild the book the second edition draft. When I do cargo run --release, I encounter the following error:

nabarun@pal:~/codesl/trpl-ebook (git:master) $ cargo run --release
   Compiling rustc-serialize v0.3.19
   Compiling memchr v0.1.11
   Compiling kernel32-sys v0.2.2
error[E0642]: patterns aren't allowed in methods without bodies
   --> /home/nabarun/.cargo/registry/src/github.com-1ecc6299db9ec823/rustc-serialize-0.3.19/src/serialize.rs:147:45
    |
147 |                                             &f_name: &str,
    |                                             ^^^^^^^

   Compiling aho-corasick v0.5.3
   Compiling thread-id v2.0.0
   Compiling thread_local v0.2.7
   Compiling regex v0.1.77
error: aborting due to previous error

error: Could not compile `rustc-serialize`.
warning: build failed, waiting for other jobs to finish...
error: build failed

I tried to search and debug the error but couldn't do so owing to my lack of knowledge of rust at the moment. Did anyone else encounter this error?

Kobo Aura One does not display monospace fonts

When reading the book on a Kobo Aura One, monospace fonts are displayed like regular fonts, therefore the code looks unaligned. The checkmarks that should display on the tables in the first chapters do not show up.

I managed to fix the first problem by editing the ePub file using calibre, changing the font from “monospace” to “DejaVu Sans Mono” and embedding the font using the font management tool. Also, I removed the size restriction on the CSS file that stated that the “pre” element needed to have fonts that were 0.6 em. Perhaps these fixes can be integrated into the book sources somewhat.

How to update books?

This is a great tool - but the books versions it contains are 6 years outdated.

It would be good if there were some guidance on how to update the book content and, e.g., produce an eBook of the current (2022-12-xx) version of TRPL, rather than that of 2016.

It could be as simple as just replacing all the .md files with the new ones pulled from GitHub - but it would be best if the maintainer of this tool described the process explicitly.

And thanks again for this useful tool!

Some Markdown links are not rendered

E.g., in "Getting Started" the Link to "Install from Source".

There are two possible causes for this: First, the ref IDs contain spaces, and second the link text is broken into two lines.

PDF: Chapter start pages have page numbers in footer

Should be empty or in header like everywhere else.

Automatically build periodically (each release?)

It would be awesome to have this automatically run every so often, and it should be pretty easy to set this up with a CI tools (and since it's open source, it should be free, no?).

Unicode rendering omission

Hi again,

Possibly related to #6, I'm looking at

let x = 'x';
let two_hearts = '💕';

in the pdf derived from trpl-2015-05-24.md (monster page!) in 9e6b8c0 and the \u1f495 renders as zero width nothing. (Mind you, my font in Emacs only renders it as wide nothing).

In the official copy it is at http://doc.rust-lang.org/book/primitive-types.html#char

This doesn't trouble me too much as it is, though a missing-glyph box might at least avoid some confusion about the meaning of the Rust demonstration.

Thanks,

Rendering diffs list / errata?

Hi,

Thanks for the TRPL ebook - PDF was the one convenient format for me when I came looking (after the 1.0.0 release announcement).
Would it be possible to list rendering errata with the later versions, please? Or at least connect the generated readables to the commitid of trpl-ebook and rust-lang/rust so I can get the diffs?

Looking in http://killercup.github.io/trpl-ebook/trpl-2015-05-15-a4.pdf , I found some rendering bugs which you've now fixed

p.60 sec 4.1.2 The Stack :: 2³⁰ renders as plain 230 .
p.84 sec 4.4 :: "looks different than the output:" ... there was no difference! Very confusing to this Rustling::new.

and so I'm wondering what else I missed or might have misunderstood, in what I've read so far.

Hoping to reduce confusion a little,

Matthew

Add Mobi Version

After the next round of updates, I want to manually convert the EPUB version to MOBI (using Calibre) and add that to the gh-pages repo, so people can just download that file to their Kindles.

(This may also be done automatically using ebook-convert but it didn't work on my machine and I haven't investigated further.)

CSS in HTML Version Broken When Using Pandoc 1.15

Pandoc seems to eat whitespaces before embedding the CSS files.

Reported as jgm/pandoc#2301, will update here when this is fixed.

thread '<main>' panicked at 'called `Result::unwrap()`

I execute cargo run and...

[...]
Reading book........................................................................ done.
[✓] MD
thread '<main>' panicked at 'called `Result::unwrap()` on an `Err` value: Error { repr: Os(2) }', /home/rustbuild/src/rust-buildbot/slave/stable-dist-rustc-linux/build/src/libcore/result.rs:729
An unknown error occurred

I need help.

Printing the PDFs [question]

I would like to know if it's OK to send the PDFs to a printing company. Call me old-fashioned but I read better that way.

Assuming the answer is yes, please let me know if a new commit is right around the corner so I can wait for it before paying for the printing.

Fails to render TRPL

MacOS 13.2, Rust-1.66.1.

$ cargo run --release -- --prefix=trpl --source=trpl --meta=trpl_meta.yml
.  .  .
warning: `compile-trpl` (bin "compile-trpl") generated 58 warnings
    Finished release [optimized] target(s) in 0.17s
     Running `target/release/compile-trpl --prefix=trpl --source=trpl --meta=trpl_meta.yml`
Reading book.thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Os { code: 2, kind: NotFound, message: "No such file or directory" }', src/main.rs:50:68
stack backtrace:
   0:        0x1095ee6d2 - std::backtrace_rs::backtrace::libunwind::trace::hf6d6e64f9b264809
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/../../backtrace/src/backtrace/libunwind.rs:93:5
   1:        0x1095ee6d2 - std::backtrace_rs::backtrace::trace_unsynchronized::h83629c2e54dbbc12
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/../../backtrace/src/backtrace/mod.rs:66:5
   2:        0x1095ee6d2 - std::sys_common::backtrace::_print_fmt::h40995e5769fa5524
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/sys_common/backtrace.rs:65:5
   3:        0x1095ee6d2 - <std::sys_common::backtrace::_print::DisplayBacktrace as core::fmt::Display>::fmt::h8d94e552d95b28cc
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/sys_common/backtrace.rs:44:22
   4:        0x10960590a - core::fmt::write::h421d4212716e9716
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/core/src/fmt/mod.rs:1209:17
   5:        0x1095ec20c - std::io::Write::write_fmt::hdc28b71c2d62dad8
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/io/mod.rs:1682:15
   6:        0x1095ee49a - std::sys_common::backtrace::_print::habfe2bb38db219c3
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/sys_common/backtrace.rs:47:5
   7:        0x1095ee49a - std::sys_common::backtrace::print::he11eab6b959c3b5b
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/sys_common/backtrace.rs:34:9
   8:        0x1095efb66 - std::panicking::default_hook::{{closure}}::ha68ba8cbe26bbbe3
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/panicking.rs:267:22
   9:        0x1095ef8b7 - std::panicking::default_hook::h5cf85224a4df5bc6
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/panicking.rs:286:9
  10:        0x1095f02ad - std::panicking::rust_panic_with_hook::hed342721bf9addfa
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/panicking.rs:688:13
  11:        0x1095f0063 - std::panicking::begin_panic_handler::{{closure}}::h3d9af89e51f2fba9
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/panicking.rs:579:13
  12:        0x1095eeb68 - std::sys_common::backtrace::__rust_end_short_backtrace::hfb9719355016e93f
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/sys_common/backtrace.rs:137:18
  13:        0x1095efd2d - rust_begin_unwind
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/panicking.rs:575:5
  14:        0x1096122f3 - core::panicking::panic_fmt::h1965fc2159be50bb
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/core/src/panicking.rs:65:14
  15:        0x109612545 - core::result::unwrap_failed::hd7c24c16a0c71445
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/core/src/result.rs:1791:5
  16:        0x10955e98b - compile_trpl::main::h3dcd51463120ec07
  17:        0x10954faa6 - std::sys_common::backtrace::__rust_begin_short_backtrace::hc01da124e1c7d003
  18:        0x10955a70c - std::rt::lang_start::{{closure}}::haf7bdb1b58616cde
  19:        0x1095e8644 - core::ops::function::impls::<impl core::ops::function::FnOnce<A> for &F>::call_once::h876a81bfbfbf7dbd
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/core/src/ops/function.rs:286:13
  20:        0x1095e8644 - std::panicking::try::do_call::hb6eb6d47c9dfec1f
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/panicking.rs:483:40
  21:        0x1095e8644 - std::panicking::try::h414888b29889cbcb
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/panicking.rs:447:19
  22:        0x1095e8644 - std::panic::catch_unwind::h7afb8146105b2697
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/panic.rs:137:14
  23:        0x1095e8644 - std::rt::lang_start_internal::{{closure}}::ha2ee572c3866be4c
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/rt.rs:148:48
  24:        0x1095e8644 - std::panicking::try::do_call::h82662207cd7c76a9
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/panicking.rs:483:40
  25:        0x1095e8644 - std::panicking::try::hed70fec8d8e154f7
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/panicking.rs:447:19
  26:        0x1095e8644 - std::panic::catch_unwind::h3a1314c401e90464
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/panic.rs:137:14
  27:        0x1095e8644 - std::rt::lang_start_internal::haf0419567751b65f
                               at /rustc/90743e7298aca107ddaa0c202a4d3604e29bfeb6/library/std/src/rt.rs:148:20
  28:        0x10955eb5c - _main
  29:     0x7ff813f5e310 - <unknown>

it would be nice to change unwrap() to something that would at least tell what file it tried to find and couldn't.

Emojis render as unknown glyphs in PDF

I'd probably try to just remove them…

Use Pandoc AST

We do some filtering and stuff. Maybe we can use https://github.com/oli-obk/pandoc-ast instead of doing it with regexes.

Explain trpl vs nomicon

Hi,

It could be useful to add a bit of an explanation on what's the difference between trpl and nomicon versions. If I was to know that one's about "unsafe" low-level programming and the other's about the basics, for now I'd opt for the latter.

Cheers,
d33tah

unknown references

pages 14, 28, 208 and 233 have unknown references (??, page ??) - otherwise looking good so far!

– https://twitter.com/ChristianSonne/status/598624881144700928

Please put TRPL on top of NOMICON

Hello,

First of all, thank you for your fantastic work. It's incredibly valuable to have the 'The Rust Programming Language' e-book in one file.

My suggestion is to put the NOMICON links at the bottom of your page, and the TRPL links at the top of your page. Frankly, 'The Rustonomicon' e-book is not as useful, and even if it is, your page is called 'trpl-ebook', so one would expect to see TRPL first. Every time I visit your page, I mis-click because of that.

Possible solution to unicode fallbacks: http://michaelfranzl.com/2014/12/10/xelatex-unicode-font-fallback-unsupported-characters/

EPUB Validation Errors

https://cdn.rawgit.com/killercup/59020258835a976e4795/raw/2629836f22bcfd7e6417a18b0e8d640a71b41293/epub_validator.html