Notes on GitHub Usage by OGC SWGs

a2x

asciidoctor

travis-ci

vagrant

git-scribe comments

from Simon Thum:
I am at present not convinced git-scribe adds value we couldn't easily add otherwise.
My colleague Michel Krämer has made some patches to git-scribe, notably docbook 4.5 and better styling support, which is what we are currently trying to improve. The current PDF output is just plain bad.

So what git-scribe does for us is call asciidoc, fop etc. and get us to a nice PDF. However there are a myriad ways to do this. This was just the fastest and most tested by people I trust.

The stuff git-scribe's readme proposes, such as helping manage contributions, seems not to be implemented. Luckily, github's management of pull requests is more than a substitute for that.

The more powerful gizmo in our workflow is vagrant, because it frees the document generation from hidden dependencies to individual developer/writer machines. It is completely independent of git-scribe, it's just that git-scribe handles PDF generation ATM.

git-scribe also handles other target formats, I don't know how it performs in comparison to a2x. I just tested a2x's pdf output (over dblatex and fop) and it is reasonable, with the dblatex chain doing a much better job for XML highlighting. We could obviously just use that; the XML listings are too sweet to ignore. Example attached.

I guess in 3DP we'll concentrate on content for now, and review the generation process when the needs arises.

I hope this clarifies our git-scribe usage a bit!

In case it fits the purpose of the conversation, I recommend looking more closely at vagrant. It has the potential to nail the document generation problem quite elegantly. (I know our usage of vagrant is not ideal, please don't take it as a good example!)

from Pepijn Van EeckHoudt
The description looks very promising, but the actual functionality at this point seems limited to generating a document skeleton and being a frontend for a number of asciidoc processing tools.

I'm not saying that's not useful, but the project is not in the state you're lead to believe it is in from the first paragraph of the README.

On a more positive note this kind of tool does appeal to me as a software developer. Bundling up all the tools you need to work on a spec in a redistributable package (be it a ruby gem, a python package, or something else) with a command line interface sounds fantastic. This could help in making the process more accessible to people that are less familiar with the workings and interdependencies of all the individual tools that are used in generating the final documents.

-- RajSingh - 26 Aug 2013