Wincent Colaiuta <win@wincent.com> writes:

quoted text
> 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.

-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html