Re: [ANNOUNCE] GIT 1.5.3-rc4

From: Timo Hirvonen <tihirvon@gmail.com>
Date: Aug 4, 2007, 12:51 UTC
Message-ID: <20070804155129.a20cdb9b.tihirvon@gmail.com>
In-Reply-To: <Pine.LNX.4.64.0708041240500.14781@racer.site>

Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

Show 8 quoted lines

> Hi,
> 
> On Sat, 4 Aug 2007, Timo Hirvonen wrote:
> 
> > 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.

Well asciidoc doesn't even have a Makefile. You have to copy the files manually (maybe it's easier now, I don't know). Also getting it work correctly with xsl-stylesheets etc. was really frustrating experience. Now there's asciidoc, xmlto etc. in Arch Linux community repo but I wouldn't be surprised if it couldn't build the GIT documentation.

Show 7 quoted lines

> > 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,

I've never liked parser generators.

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

Very likely but perl is incompatible with my brain :)

> 	- the syntax is nowhere near asciidoc syntax.

I needed something really simple. asciidoc's syntax is full of surprises and it's much harder to parse.

Of course having a perl script which could convert asciidoc files directly to man and html would be really nice. We just need some brave perl hacker to write the script.

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

Agreed, rushing to change the documentation format wouldn't be wise.

-- 
http://onion.dynserv.net/~timo/