Re: [ANNOUNCE] GIT 1.5.3-rc4

From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Aug 4, 2007, 11:46 UTC
Message-ID: <Pine.LNX.4.64.0708041240500.14781@racer.site>
In-Reply-To: <20070804133923.eb84a308.tihirvon@gmail.com>

Hi,

On Sat, 4 Aug 2007, Timo Hirvonen wrote:

Show 15 quoted lines

> 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