git meets asciidoc
Linus' still on his vacation while other ppl continue on improving git.
As git has got to a point where the core itself is stable and mature eough, it's time for making some (great) documentation. One of the most obvious advantages of open source is that, everyone can participate and contribue in various aspects of the project, be it coding, designing, art stuff, or documentation. And good documentation is as important as, if not more than, the code itself.
So here comes a wonderful text processing tool: asciidoc.
Quick installation:
download, unpack, and then
$ ln -s /path/to/unpacked/dir/asciidoc.py /somewhere/bin/asciidoc
AsciiDoc is good at converting plain text to a number of different formats like xhtml, html, docbook/xml, or docbook/sgml.
Basic usage:
$ asciidoc -b <backend> -d <doctype> <filename> One of the nice features i like most is that asciidoc's docbook/xml backend works pretty well with xmlto/xsltproc[1] (well, it's designed to be so..).
ie.
$ asciidoc -b docbook -d manpage file.txt $ xmlto man file.xml
or
$ asciidoc -b docbook -d article file.txt $ xmlto -x xhtml.xsl xhtml-nochunks file.xml
Very neat, now it's easier to write docbook articles and/or books. =) You can find more examples and docs at asciidoc's web site.
See results in action: asciidoc generated[2] git manpages (html format).
P.S, other news about git: Petr made up a 'core' git tree of his own: git-pb, in which he would constantly apply newest patches from the git mailing list.
[1] xmlto is just a shell script wrapper to xsltproc. Sometimes xmlto does not work so well; the asciidoc author directly uses xsltproc worldwide.
ie.
$ asciidoc -b docbook -d article file.txt $ xsltproc --nonet chunked.xsl file.xml or $ xsltproc --nonet xhtml.xsl file.xml >nochunked.html
so main syntax to use xsltproc is like: $ xsltproc --nonet <xsl> <file> [>output]
[2] command: $ asciidoc -b css-embedded -d manpage <file>
