Refresh with latest book (as of June 2th)

[royalstream]

Ok, here's my take at it. It includes the latest MD files from the Rust repo plus two PRs I did in the last few days (merge pending) (that already got merged).

I think it handles most (if not all) the pending issues preventing us from releasing a new PDF except for the ASCII diagram which is not a regression (ASCII diagram included)

I added some changes to your rust code to take care of the checkmarks and replace them with \checkmark for the TEX and the PDFs.

This is how the final documents look: https://www.dropbox.com/sh/wlj05c3j2lw69d5/AADX8lE_kuflpiup6TewzNj1a?dl=0

[killercup]

Wow, thank you so much! Looks like this supersedes #34 and #35.

I'll have a look at the PDF tomorrow and will report any remaining issues :)

[killercup]

Also, thanks for upstreaming some of the changes!

[royalstream]

You're welcome.

[royalstream]

I added a couple "custom" changes to the markdown:

• I changed the "draft" warning for the Nomicon to be simply bold (instead of a headline)
• I made the ASCII diagram fit and I think it's now more symmetric. I wonder if they would accept a PR for such an apparently unnecessary change.

(by "custom" I mean they're not part of a PR to the main rust repo)

[royalstream]

FYI: both PRs to the main repo got merged.

[killercup]

Very nice! I wanted to read through your changes and the resulting PDF yesterday, but that was just when GitHub was down…

I'll just paste the issues I found in #34 here as a todo list and tick them when I verified that you addressed them -- but that may take me some time.

• [x] The second chapter headline of the nomicon is actually just Gankro's big notice that the nomicon is a WIP. It's only a headline to make it bigger. You can reduce this to a simple paragraph in bold.
• [x] I remembered correctly! On page 14 of the A4 PDF of TRPL, there are no tick marks -- compare it to the book in HTML. A workaround for that might be to simply replace '✓' with a LaTeX glyph for that (here are some suggestions from stackoverflow). (The Japanese characters on page 148 are rendered beautifully by the way!)
• [x] The ASCII diagram on page 139 (TRPL A4 PDF) is still broken, but it's been broken since forever (see #11).
• [x] The table on page 188 (TRPL A4 PDF) is broken. Is the Markdown correct? I.e., does pandoc understand it?
• [x] There are code blocks page 225f, 275f, 278f, 281f, 293-298, and 304-307 (TRPL A4 PDF) that are not highlighted (probably just need to be rust or sh instead of ```). Feel free to make a PR for those changes on https://github.com/rust-lang/rust as well!
• [x] There are broken references on pages 233, 236, 239, 246, 253, 261, 265 (TRPL A4 PDF) which are rendered as "?? on page ??". At some of them seem to come from the fact that pandoc creates IDs for headlines in another way than rustdoc, so when the book contains references of not just pages but sections (link links to error-handling.html#composing-optiont-values) it may be that in our version those sections are actually called differently. I think I've had this problem before and just changed the links to whatever IDs pandoc creates.

[royalstream]

No rush. Thanks! I also made some changes to your Rust code, I'm sure you want to review those too (even though they were minimal).

[killercup]

Oh, no, I totally forgot about this! I'll have a look at this in the afternoon (at UTC+2). Feel free to ping me here or on IRC if I don't respond to a PR for several days!

[killercup]

Okay, so I looked through it and it looks really well.

Except for, err… where are the cross references? For example: In the PDF for PR #34, on page 233 of the TRPL (A4), you can see this:

Composing Option<T> values

In an example from before (??, page ??), we saw how […]

In your PDF (via Dropbox), the same paragraph is on page 235, but reads as:

In an example from before, we saw how […]

This line is also in the PR diff here (took my browser a while to load that page!) so the link is still there.

[royalstream]

Mmm. I wonder what could be causing the PDF conversion to lose them, any ideas? Any XeLaTeX packages that come to mind? (that I could be missing)

[killercup]

Maybe an updated pandoc?

Steven Burns notifications@github.com schrieb am Di., 31. Mai 2016 um 19:07:

Mmm. I wonder what could be causing the PDF conversion to lose them, any ideas? Any XeLaTeX packages that come to mind?

— You are receiving this because you commented.

Reply to this email directly, view it on GitHub https://github.com/killercup/trpl-ebook/pull/36#issuecomment-222754302, or mute the thread https://github.com/notifications/unsubscribe/AABOX0cy_q8q3AyFg2jLtLjPwyId28_gks5qHGrmgaJpZM4IimSS .

[royalstream]

What happens if you generate the PDF from your machine (but using the sources from this PR)? I'm no TeX expert (pretty far from it). That's the reason I ask :)

[killercup]

I'll try it later when I'm at home.

On a scale from "notepad user" to "TeX magician" I'm at the "this looks so complicated, I bet TeX macros are Turing complete" stage ;)

Steven Burns notifications@github.com schrieb am Di., 31. Mai 2016 um 19:09:

What happens if you generate the PDF from your machine (but using the sources from this PR)? I'm no TeX expert (pretty far from it). That's the reason I ask :)

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/killercup/trpl-ebook/pull/36#issuecomment-222754835, or mute the thread https://github.com/notifications/unsubscribe/AABOXyFk5bUt9R8PrQ4ILlReh1yp96nLks5qHGtYgaJpZM4IimSS .

[killercup]

Damn, it doesnt work on my machine as well. I suspect it was this pandoc 1.15.2 change:

Use \hypertarget and \hyperlink for links. This works correctly to link to Div or Span elements.

that destroys this hack:

\renewcommand*{\hyperref}[2][\ar]{%
  \def\ar{#2}%
  #2 (\autoref{#1}, page~\pageref{#1})}

in template.tex.

[killercup]

Okay, replacing \hyperref with \hyperlink in the snippet above does something, but not what we want. Links get transformed into text like

In an code-option-ex-string-find (??, page ??)example from before

In general, it looks like the right approach, though \hyperlink seems to take other parameters than \hyperref. I don't have the time to try this right now, maybe you can fiddle with this a bit, @royalstream?

https://en.wikibooks.org/wiki/LaTeX/Hyperlinks seems to have some information on the \hyperlink macro.

[talklittle]

Hi all, I investigated a little bit and the pandoc change indeed seems to be the cause of the autoref issue, because it removes the \label.

After doing this change (and no idea what I'm doing with LaTeX), it's closer but still broken:

\renewcommand*{\hypertarget}[2][\ar]{%
  \def\ar{#2}%
  \label{#1}}

\renewcommand*{\hyperlink}[2][\ar]{%
  \def\ar{#2}%
  #2 (\autoref{#1}, page~\pageref{#1})}

In an code-option-ex-string-find (section 1, page 234)example from before

As you can see, it's the correct page number but wrong section number. I think it might be because the section labels have a sec-- prefix instead of sec:, so \autoref doesn't like it. Haven't verified this.

[killercup]

Thanks for investigating, @talklittle! I think we add the sec-- prefix ourselves, so we can totally change this if it makes handling the LaTeX part easier.

[talklittle]

I changed sec-- to sec: in markdown.rs and normalize.rs and it doesn't help. All hyperlinks still say "section 1". So much for that theory.

[royalstream]

They talk about it here, but they provide no solution (other than going directly from MD to PDF)

[royalstream]

Ok, I took @talklittle's code and tweaked it a little bit and it looks much better. The section number is right and the code-option-ex-string-find rubbish is gone:

In an example from before (section 5, page 234), we saw how to use find ...

I'm going to do some additional commits but I definitely need another set of eyes to look at it because I only partially understand what I think I'm doing. Here's the code:

\renewcommand*{\hypertarget}[3][\ar]{%
  \def\ar{#2}%
  \label{#1}%
  #3}

\renewcommand*{\hyperlink}[2]{%
 #2 (\autoref{#1}, page~\pageref{#1})}

[talklittle]

@royalstream Awesome! The PDF looks good on my end too, as well as the single-page HTML and EPUB, which both have a regular link and no "section 5, page 234". This is expected.

[royalstream]

Ok, I updated my Dropbox with the latest docs and also created the respective PR on the gh-pages branch.

[killercup]

Awesome! Let me take a quick look at this and we are good to go!

[killercup]

Thanks so much! Looks perfect! You even updated the sources again :)