Re: Documentation files in html format?

[Willy Tarreau <w@1wt.eu>]

On Sat, Aug 11, 2007 at 10:19:25AM -0400, J. Bruce Fields wrote:
> On Fri, Aug 10, 2007 at 10:51:17PM +0200, Willy Tarreau wrote:
> > The problem I have with asciidoc is that it's a nightmare to get it
> > to work. It's what GIT uses, and after spending a whole day trying
> > to *build* that thing, I finally resigned and asked Junio if he could
> > publish the pre-formatted manpages himself, which he agreed to.
> 
> I wasn't actually suggesting we use the asciidoc tools--that's a
> separate question.  We could ignore them, or wait till they solve
> whatever problems they may have.
> 
> I was just suggesting that if we took your suggestion of standardizing
> on plain text plus some conventions for formatting lists and headers and
> such, one easy way to do that might just be to adopt the asciidoc format
> (or some subset thereof).  Is there any part of the asciidoc *syntax*
> that you object to?

Not particularly. It's just slightly less readable as plain text but
OTOH produces nice documents when you have a working toolchain. But
that's a language which needs to be learned, as every such language.
Plain text on the contrary, requires no learning. The conventions are
more like suggestions to newcomers. Everyone is free to proceed as he
wants, judging by the result while writing the text.

Willy