[antlr-interest] [v3] Lack of documentation

[Terence Parr]

On Jul 1, 2007, at 3:32 AM, Harald Wellmann wrote:

> Getting started with ANTLR v3 is a frustrating experience for its  
> lack of
> coherent documentation and non-trivial example code.

Well, it was just released, bro! ;)  v2 had nothing for a while  
either ;)  I've worked 7 days a week for 4 years to bring you the  
software.  Can you hold your horses for a bit until I can get you  
some more doc?

> I've been using ANTLR since the good old times when it used to be  
> called
> PCCTS, and I always used to be fond of it, but I am disappointed  
> with v3.
>
> Marketing-style hype about the latest cool features does not really  
> help
> when you get no little or no information on how to use them.

I'm kind of surprised by your reaction.  There are lots and lots of  
people building projects.  We provide examples, a helpful list, a  
start on doc, a FAQ, etc...  With your experience going back 15  
years, I'm surprised you can't get started, particularly with  
ANTLRWorks!

> Even v2 documentatation was a bit scarce, it always cost you some  
> trial and
> error to get things right, but this was bliss compared to the  
> scattered and
> incomplete bits of documentation you get for v3.

Feel free to help out...can't always get something for nuthin' ;)

> Yes, I know there's a book now. And no, I don't think it's in the  
> spirit of
>  a successful open source project to hide all relevant information  
> in a
> book that is only available commercially.

You would begrudge me $24 for providing such a useful tool?  I've  
devoted my life to building parsing tools (nearly 20 years now).  The  
book was a way for me to write *good* doc as opposed to the v2 doc.

> There's nothing wrong about books, but you can publish a book and  
> still
> make the information publicly available, see e.g. the Subversion Book.

Yep, I'm working on the doc as often as I can.  I also have to keep  
working on the software, fix bugs, do my other job *and* do the same  
for StringTemplate.

> By the way, even this mailing list is inaccessible to most people in a
> corporate IT environment, as the Mailman Frontend is running on a
> non-standard port 8080 which tends to get blocked by firewalls.

People seem to get around that.  Shall I sign you up?  You can always  
do the email subscription I think instead.

Free software is free software and whatever doc you can find  
(including the source).  Why you expect a shrink-wrapped piece of  
commercial software with professional docs for free is beyond me.

Thanks for your interest,
Ter