Re: WIP: asciidoc replacement

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 3, 2007, 10:57 UTC
Message-ID: <7vd4vwfou9.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <1D18C52E-BB96-49EC-97A9-F802D56CAFF5@wincent.com>

Wincent Colaiuta <win@wincent.com> writes:

Show 13 quoted lines

> Yes, but editing DocBook (XML) is relatively painful compared to  
> editing plain text. You either have to rely on a bloated XML- 
> validating editor or instead ask your doc authors to manually write  
> valid XML (and I totally agree with Terrence Parr that, "XML makes a  
> lousy human interface
> "; see <http://www.ibm.com/developerworks/xml/library/x-sbxml.html>  
> for his full take).
>
> I know that Linus has argued for AsciiDoc because the source *is* the  
> plain text documentation and is therefore easily readable, but for me  
> the real benefit lies in the fact that *because* the source is plain  
> text it is easily edited (ie. that the source is easily *writeable*),  
> and things like documentation patches are very neat with AsciiDoc.

To give credits to where they are due, most of the structure of the initial documentation was done during the first week of May 2005 by David Greaves while Linus was vacationing, and the first person who brought up AsciiDoc was Bert Hubert.

    http://article.gmane.org/gmane.comp.version-control.git/2323

One thing Linus had to say about the issue from early on, and I still agree with, is the last paragraph in:

    http://article.gmane.org/gmane.comp.version-control.git/2298

There was another thread in the recent past

    http://article.gmane.org/gmane.comp.version-control.git/55059

I've seen markdown used elsewhere, and I regularly read pod. These are both used by other people (I _care_ about good external support and user community), are readable as straight text (I personally care more about this than prettyprinted output), and can be alternative candidates if we consider switching.

How good are HTML and manpage output support from these (or other candidates) formats these days? Output to help page format Windows folks use (I am assuming Mac people are happy as long as man is available) would be a definite plus.

Another alternative could be to build on AsciiDoc to get manpage and html output without relying too heavily on docbook toolchain, and considering the fact that we still seem to be one of the most important customers listed on its home page, we might be able to get help from Stuart himself to improve the situation (I am assuming that mingwgit folks do not have problem with Python, but I may be mistaken).

In short, although I do appreciate Johannes's and Sam's attempt, I would really prefer to see us pick some externally maintained alternative, instead of inventing a homebrew system that we need to maintain ourselves. It is rumored that git has much higher developer count vs loc count ratio than many other open source projects, doing the documentation format is not part of our project, and I'd rather see them spend time working on git, not building and maintaining AsciiDoc lookalike.