Repository navigation
Atlas is broken #625
Description
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.
Reacted by 戴均民 and Yue Lin Ho
Activity
jnavila commentedon Jun 29, 2016
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 commentedon Aug 7, 2016
What exactly is broken with Atlas? O'Reilly still has the Atlas promotion page online.
ben commentedon Aug 7, 2016
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 commentedon Aug 7, 2016
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 commentedon Aug 8, 2016
@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 commentedon Aug 8, 2016
Are the deployment scripts on the git-scm site public or how can I help then?
jnavila commentedon Aug 9, 2016
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 commentedon Aug 9, 2016
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 commentedon Oct 4, 2016
There is an alternative which involve using gitbooks.io . Apparently, they provide publishing of asciidoc formated books to html, ebook and pdf.
jnavila commentedon Dec 27, 2016
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 commentedon Jan 6, 2017
FYI git/git-scm.com#917
jnavila commentedon Jan 18, 2017
Done. git/git-scm.com#917 was merged. We have at least the publishing workflow to the git-scm site
jnavila commentedon Oct 13, 2017
Continued on #810