Atlas is broken

[ben]

It doesn't look like we can rely on Atlas any longer, so we need a new toolchain. It should generate all the e-book versions, PDF, and HTML suitable for git-scm.com. Some ideas off the top of my head:

• Leanpub
• Pandoc
• Asciidoctor
• Use Travis to run the build

Any volunteers? I'd love to do this, but I'm swamped.

[jnavila]

Well, Ruby isn't my first language of taste, but I guess this would be the best way to go. Everything is already available in the infrastructure of the git-scm site.

So, we would rely on asciidoctor and add some customizations. In this direction, ebooks are rather simple to obtain with asciidoctor (but the book might need some rework in structure for e.g. internal links), and we can always feed the html output of a chapter after the processing to the actual build script to keep the website updated.

[mkarg]

What exactly is broken with Atlas? O'Reilly still has the Atlas promotion page online.

[ben]

It's more of a general pipeline problem than just Atlas. Atlas is a closed system, which means only @schacon or I can really see when it's broken or fix it, and we're both busy with other projects. The CI system is closed off as well, and doesn't appear to be working terribly well, especially with markup generated for the Git website. Having something that's more transparent and community-oriented would be better, even if the final artifacts may not be quite as pretty (and it's not guaranteed that they'll be uglier with an open system).

[mkarg]

I think it would be best to use GitHub's integrated CI "Travis" then, as it is at-most transparent and public. So the only thing we need to add is a transformation of Asciidoc to HTML and PDF, right?

[jnavila]

@mkarg I think the best way to go is to update the book deployment scripts on the git-scm site. They already achieve a good deal of processing and we can not get rid of them. It seems they are run via a crontab which is already a way of updating the content.

Running any transformation on Travis would require to set up a way to push the changes from Travis to git-scm. This facility doesn't exist as of now. Let's keep it simple and use the existing pipeline.

[mkarg]

Are the deployment scripts on the git-scm site public or how can I help then?

[jnavila]

Yes, they are available on https://github.com/git/git-scm.com/blob/master/lib/tasks/book2.rake

I believe this script is run on a periodical basis. As of now, it processes the html files generated by atlas. You can also take some ideas from https://github.com/git/git-scm.com/blob/master/lib/tasks/index.rake where the git man pages are extracted from the git repository.

One important point is to keep in mind that we will extract the books from all the translated repos. This can be done in a second step, but the pipeline should have this extensibility.

[mkarg]

Oops this apparently is Ruby... Unfortunately I have neither time nor interest to learn it. Hope you find a Ruby guy that is willing and free to follow that path.

[jnavila]

There is an alternative which involve using gitbooks.io . Apparently, they provide publishing of asciidoc formated books to html, ebook and pdf.

[jnavila]

For the record, I'm working on bringing at least the updates of progit on the html side of git-scm.com, through some changes in the deployment scripts.

[jnavila]

FYI git/git-scm.com#917

[jnavila]

Done. git/git-scm.com#917 was merged. We have at least the publishing workflow to the git-scm site

[jnavila]

Continued on #810