Re: [ANNOUNCE] GIT 1.5.3-rc4

[Johannes Schindelin <Johannes.Schindelin@gmx.de>]

Hi,

On Sat, 4 Aug 2007, Timo Hirvonen wrote:

> Junio C Hamano <gitster@pobox.com> wrote:
> 
> > It might be more worthwhile to research what other "Text-ish
> > lightweight mark-up" systems are availble, and if there is one
> > that is more efficient and can go to at least html and man,
> > one-time convert our documentation source to that format using
> > your Perl magic.  The minimum requirements are:
> > 
> >  * The source is readable without too much mark-up distraction;
> > 
> >  * Can go to roff -man;
> > 
> >  * Can go to html.
> 
> I used asciidoc too but it was really PITA to install and use

I disagree.  Whenever I had the need, installing asciidoc was pretty 
swift.  No problems at all.

> so I wrote a small tool (ttman) in C which converts .txt files directly 
> to man pages.

I was impressed!  Right until I saw that

	- it rolls its own parser/lexer without using bison/flex, which 
	  makes it much longer than necessary,

	- it looks like a perl script doing the same job would have been 
	  even smaller yet, and

	- the syntax is nowhere near asciidoc syntax.

The last point is really something to keep in mind.  We have not only a 
large amount of documentation in that format, which would have to be 
converted -- accurately! -- to the new format.  We also have quite a 
number of documentation contributors which would have to be "migrated" 
towards the new format.

I think that Steven's goal is a laudable one.  We have the 'man' and 
'html' branch mainly for the reason that some cannot/wantnot install 
asciidoc.

But I think that we do not have to have a _complete_ replacement.  I, for 
one, would be happy to see a small script which converts all the man pages 
more or less accurately, with the main goal to be _fast_ and having as 
few dependencies as possible (I think Perl is okay here).

For official releases, I'd still want to rely on asciidoc.

Ciao,
Dscho