Rendering diffs list / errata?

[mcast]

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

[killercup]

Hi @mcast,

I see what you mean. There is no errate planned currently; mostly, because errors are split 50-50 between typos in the source and errors in the conversion and both are not that easy to track.

If you want to see a diff between the first version I uploaded on May 15th and the latest version available (the dates only indicate the date of the source not the date of the conversion), you could theoretically diff the two Markdown files. Sadly, Github doesn't allow you to do that easily as the file names differ.

I'll see if I can create a nice diff later today.

[mcast]

On Mon, Jun 01, 2015 at 05:17:12AM -0700, Pascal Hertleif wrote:

I see what you mean. There is no errate planned currently; mostly,
because errors are split 50-50 between typos in the source and
errors in the conversion and both are not that easy to track.

I guessed cd rust-lang/rust && git diff 1.0.0-alpha.2 1.0.0 src/doc/trpl/ would tell me about the source changes, I just don't
have the two places exactly.

It would be nice to do this in Github, to get the benefit of Markdown
diffs in "paper view",
https://help.github.com/articles/rendering-differences-in-prose-documents

but (so long as Github can't render diffs between arbitrary revisions)
the only way I know of to construct a page showing book content diffs
is some weird fork of rust.git constructed

• to contain only src/doc/trpl/ (git filter-branch--subdirectory-filter)
• commit logs suffixed to link back sanely, like rust-lang/rust@5a341ecf
• merge commits fabricated where you rendered the book versions

Random example of a useful part of a merge commit
rust-lang/rust@5a341ec#diff-1c24e61e34a56ad10bec93a29c45ad1f

Overall it sounds like a lot of work, and I don't know of a suitable
tool beyond git-filter-branch to do it.

As for the rendering changes, these bugs were what confused me; the
content changes are hopefully just a matter of staying up-to-date.

If you want to see a diff between the first version I uploaded on
May 15th and the latest version available (the dates only indicate
the date of the source not the date of the conversion),

Lacking context, I guessed the dates to be book source + renderer at
that time, and the resulting .pdfs etc. are then frozen.

you could theoretically diff the two Markdown files. Sadly, Github
doesn't allow you to do that easily as the file names differ.

For the rendering changes, the set of commits on trpl-ebook might be
more informative?

"Fix rendering of 2^30 in section 4.1; it displayed as plain 230" is
much more informative than seeing the dozen instances of that fixed,
interspersed with other changes. And hopefully less effort!

Oh, well maybe section name rather than number. Presumably the
numbering can change with the content.

I'll see if I can create a nice diff later today.

Thanks! I realise there may not be much demand for this in general,
but possibly the timing of the changes near the 1.0.0 release makes a
difference?

Matthew

The Wellcome Trust Sanger Institute is operated by Genome Research
Limited, a charity registered in England with number 1021457 and a
company registered in England with number 2742969, whose registered
office is 215 Euston Road, London, NW1 2BE.

[killercup]

Damn, gists don't have rendered markdown diffs. Or this would've looked far better: https://gist.github.com/killercup/df7e9be34bf8a51b0c3e/revisions

Sadly, the plain text diff now also contains every instance where the name of a reference was changed (to be unique in the whole file, for example). But give me a minute, I'll make a branch in this repo which should render prose diffs.

I guessed cd rust-lang/rust && git diff 1.0.0-alpha.2 1.0.0 src/doc/trpl/ would tell me about the source changes, I just don't
have the two places exactly.

No problem, this is the result of git diff HEAD..1.0.0 src/doc/trpl/: https://gist.github.com/killercup/e3a1f4642f8b1e81da4c

---

Funnily enough, I only added the dates to the names so people could hotlink to the PDF files in specific versions. Maybe I should've just skipped that and linked to the revisions on GitHubs CDN.

[killercup]

Okay, I pushed the branch diff but GitHub just doesn't render the diffs now because they are too large: 7817893#diff-e01779a7aecee141f0521bbe49b8e44c

Well, this is all the time I'm spending on this today. If you have any other ideas, please tell me :)

[mcast]

On Mon, Jun 01, 2015 at 11:46:02AM -0700, Pascal Hertleif wrote:

Damn, gists don't have rendered markdown diffs. Or this would've
looked far better:
https://gist.github.com/killercup/df7e9be34bf8a51b0c3e/revisions

Yes, the wordwrap change alone makes it just... not useful. 8-(

I guessed cd rust-lang/rust && git diff 1.0.0-alpha.2 1.0.0 src/doc/trpl/ would tell me about the source changes, I just
don't have the two places exactly.

No problem, this is the result of git diff HEAD..1.0.0 src/doc/trpl/:
https://gist.github.com/killercup/e3a1f4642f8b1e81da4c

So 2015-05-15 was the 1.0.0 release? No, now I clone & gitk --all I
can see the story is much more complicated than I expected.

Possibly, what I'm asking for can't be done retrospectively across the
already published versions, with a sane amount of effort.

Funnily enough, I only added the dates to the names so people could
hotlink to the PDF files in specific versions. Maybe I should've
just skipped that and linked to the revisions on GitHubs CDN.

That would have been easier, but then the same problem plus "why are
there three, and which is the newest?".

Matthew

The Wellcome Trust Sanger Institute is operated by Genome Research
Limited, a charity registered in England with number 1021457 and a
company registered in England with number 2742969, whose registered
office is 215 Euston Road, London, NW1 2BE.

[mcast]

On Mon, Jun 01, 2015 at 11:53:35AM -0700, Pascal Hertleif wrote:

Okay, I pushed the branch diff but GitHub just doesn't render the
diffs now because they are too large [..link..]

Well, this is all the time I'm spending on this today. If you have
any other ideas, please tell me :)

Thanks for trying.

I'll have another poke around the old builds this evening, now I
understand (for example) that 88c2bac is the last good-old-ruby
build, and the book files are rebuilt several times (without changing
the date-based name).

Matthew

The Wellcome Trust Sanger Institute is operated by Genome Research
Limited, a charity registered in England with number 1021457 and a
company registered in England with number 2742969, whose registered
office is 215 Euston Road, London, NW1 2BE.

[mcast]

I wrote:

I'll have another poke around the old builds this evening, now I understand (for example) that 88c2bac is the last good-old-ruby build, and the book files are rebuilt several times (without changing the date-based name).

So the PDFs I'm looking at / wanted to compare match gh-pages@9e6b8c05d, so I need to diff those .md's.

I propose to write a Markdown chapter splitter which takes a split depth (e.g. 2) and input foo.md to foo.md.split/{}, producing

• the YAML prologue as prologue.yaml
• 1-Introduction.md; except when there's no content before sec 1.1
• 1.1-Contributing.md
• 1.2-A_brief_introduction_to_Rust.md
  ...

There is a risk of Github's diff viewer not working when section numbers change, but this could be fixed by rename commits before the diff commit.

Automating a viewable diff generator would be more work.

"I propose to write" kind of means... I should write it in Rust I guess. Hmm.

Matthew >= JAPH