search

killercup / trpl-ebook

UNMAINTAINED
http://killercup.github.io/trpl-ebook/
477 stars 56 forks source link

Rendering diffs list / errata? #15

Open mcast opened 9 years ago

mcast commented 9 years ago

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

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

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

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

Random example of a useful part of a merge commit https://github.com/rust-lang/rust/commit/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 commented 9 years ago

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

Okay, I pushed the branch diff but GitHub just doesn't render the diffs now because they are too large: https://github.com/killercup/trpl-ebook/commit/7817893f82d27c3cdff58b76d031c61fe49a11f2#diff-e01779a7aecee141f0521bbe49b8e44c

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

mcast commented 9 years ago

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

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

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

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