Hacker News Reader

Comment by schacon | Hacker News Reader

I'm planning to write all of this up soon, but there are a few really interesting things about the second edition.

For one, everything was changed from Markdown to Asciidoc and the entire book can now be generated in multiple formats in the asciidoctor toolchain. Also, we're using O'Reilly's Atlas platform to generate amazingly high-quality PDF, ePub and Mobi versions automatically with every push to master. In every language. This is a massive improvement over the previous version.

The other really interesting thing is the production process. We used GitHub and prose diffs for the entire production of the book. I think we used about 100 Pull Requests to get to where we are now. This is a massive improvement over how I collaborated with editors for the first version, the first few chapters of which were actually done by sending Word documents back and forth.

View on HN

It's interesting you talked about the writing process and not the content. After reading your comment I realised that I was overlooking a huge aspect of providing this resource. As a consumer of Pro Git, all I ever see is the end result. Thank you for reminding me there are serious man hours behind this, and thank you for your time and effort and the time and effort of all the people that contributed.

Thanks for all your hard work.

But why did you choose Asciido and asccidoctor? I think Markdown together with Pandoc is capable of generatring all kinds of formats too.

I wrote a short book recently [1] and went through a similar process. Started writing using Markdown & Pandoc but soon realized that Markdown isn't a very good fit for longer technical documents. As an example, support for asides aka admonition blocks is nonexistent. I switched to Asciidoc + Asciidoctor and the process was much more productive.

[1] Python for the busy Java Developer. http://antrix.net/py4java

Have you tried Gitbook? (https://www.gitbook.io/ https://news.ycombinator.com/item?id=7524956)

If I understand correctly, the gitbook toolchain isn't freely available. Nor does gitbook address any of the limitations of Markdown that prompted me to switch to Asciidoc.

20% per transaction is just too much.

Pandoc is a powerful tool but it has some serious limitations. Nothing more sophisticated than it's own flavor of Markdown is supported. "Simple" things like internal references to anything other than headings are impossible. I had to abandon it after realizing how restricted its ReST parser is compared to the official Docutils.

Hi Scott, this is very exciting. Thank you.

I'd just like to point out that Google Play Books (play.google.com/books) gave me an error after I uploaded progit-en.31.epub:

"This file cannot be processed."

Then again, I've had lots of problems with Play Books and ePubs from APress.

OK, Play appears to be pretty strict about xrefs for some reason. I'll look into it. You can track the issue here:

https://github.com/progit/progit2/issues/111

This is interesting, I've never used Google Play Books. Is there an actual error message that you could put into our issues? The file is actually generated with O'Reillys Atlas platform, not Apress, so they would be interested in why that doesn't work I'm sure.

Is there an open source alternative to the Atlas Platform that has similar features? Thanks!

Take a look at Softcover (http://www.softcover.io/), which is a 100% open-source ebook production toolchain used to produce the Ruby on Rails Tutorial book (among others).

There is a simple build process using asciidoctor-pdf and asciidoctor-epub that can also create all 3 formats locally. The Atlas ones are just a little more professional looking, but the asciidoctor chain is still really great.

https://github.com/progit/progit2#how-to-generate-the-book

See also this previous HN thread about Pollen (written on top of Racket) by Matthew Butterick of Butterick's Practical Typography fame.

https://news.ycombinator.com/item?id=7822057

Hi, not 100% sure but I think there might be a typo on the front page "Everything you need to know about GITT". I'm new so might be missing something.

Yup, that's the cover that Apress made and we (lol) screenshot from Amazon. I was thinking of Photoshopping it out, but decided to just wait until they fixed it and do another screenshot.

Reply on news.ycombinator.com