5 ms·

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 Markdow

by schacon 12y ago

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.

coherentpony 12y ago
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.
BookMaker 12y ago
Is there an open source alternative to the Atlas Platform that has similar features? Thanks!
- mhartl 12y ago
  Take a look at Softcover (http://www.softcover.io/ http://www.softcover.io/), which is a 100% open-source ebook production toolchain used to produce the Ruby on Rails Tutorial book (among others).
- schacon 12y ago
  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 https://github.com/progit/progit2#how-to-generate-the-book
- cenazoic 12y ago
  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 https://news.ycombinator.com/item?id=7822057
yfefyf 12y ago
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.
- antrix 12y ago
  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 http://antrix.net/py4java
  - sysk 12y ago
    Have you tried Gitbook? (https://www.gitbook.io/ https://www.gitbook.io/ https://news.ycombinator.com/item?id=7524956 https://news.ycombinator.com/item?id=7524956)
    - steveklabnik 12y ago
      20% per transaction is just too much.
    - antrix 12y ago
      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.
- kevin_thibedeau 12y ago
  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.
fakeyfake 12y ago
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.
- schacon 12y ago
  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.
clumsysmurf 12y ago
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.
- schacon 12y ago
  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.
- schacon 12y ago
  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 https://github.com/progit/progit2/issues/111

by schacon 12y ago

coherentpony 12y ago

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.

BookMaker 12y ago

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

mhartl 12y ago
Take a look at Softcover (http://www.softcover.io/ http://www.softcover.io/), which is a 100% open-source ebook production toolchain used to produce the Ruby on Rails Tutorial book (among others).
schacon 12y ago
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 https://github.com/progit/progit2#how-to-generate-the-book
cenazoic 12y ago
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 https://news.ycombinator.com/item?id=7822057

yfefyf 12y ago

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.

antrix 12y ago
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 http://antrix.net/py4java
- sysk 12y ago
  Have you tried Gitbook? (https://www.gitbook.io/ https://www.gitbook.io/ https://news.ycombinator.com/item?id=7524956 https://news.ycombinator.com/item?id=7524956)
  - steveklabnik 12y ago
    20% per transaction is just too much.
  - antrix 12y ago
    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.
kevin_thibedeau 12y ago
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.

fakeyfake 12y ago

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.

schacon 12y ago
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.

clumsysmurf 12y ago

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.

schacon 12y ago
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.
schacon 12y ago
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 https://github.com/progit/progit2/issues/111