[antlr-interest] [v3] Lack of documentation

[Terence Parr]

On Jul 1, 2007, at 9:22 AM, David Piepgrass wrote:
>> Getting started with ANTLR v3 is a frustrating experience for its  
>> lack of
>> coherent documentation and non-trivial example code.
>>
>> 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 know how you feel. I even bought the book and was pretty
> disappointed with it.

it's all about managing expectations. ;)

> For starters I had no idea that there would be
> absolutely no information about non-Java targets, it's hard to use as

there was a serious space issue. I went like 100 pages over their  
original limit.  The targets and API would change often enough that I  
figured that should be in the wiki.  The javadoc is up for some  
targets already too.

> a reference because much of it is treated as a tutorial, there is no
> tutorial or reference for the runtime library, there's no specific
> discussion of differences between v2 and v3,

on the wiki

> no complete grammar file
> in chapter 3

you mean other than the complete grammar syntax I put in there?

> ... I could go on. (mind you, there is a lot of useful
> information despite these problems.)

It's all about how much I could cram in there.

> Still, I think it's a general problem in the computer field that the
> authors of the most useful projects, i.e. open-source projects, have
> trouble getting paid anything for their work. The government, and most
> social institutions, have provided no means of making money except
> selling copies of something. This is very unfortunate, because
> e-copies cost nothing to make and logically should be free, but I
> don't think you can blame Ter for it. It's a limitation of our

Money makes me spend a lot more time on it than I would for free  
doc.  Why should a book be free just because my marginal cost to  
produce is $0?  The value is in the content not the medium.

> society's institutions. He could give away the PDF, but I think the
> truth is, it would hurt book sales. Don't be mad at Ter just because
> there are more generous people out there who give away all their hard
> work for little or nothing in return.

Are you really saying that devoting 20 years of my life to make the  
best tools possible is not generous?  You kidding me?  others are  
more generous?  You've got to be kidding me.  People swoop in and  
built a few patches or whatever and then move on.  Rare few start  
building something of value and keep honing it. How many people do  
you know that have been dedicated to free software for as long as I  
have?  I am working on the doc and you can help add more doc.

I get $3 measly dollars when you buy the book at amazon.  I want all  
you whiners about the doc to either decide you can't use the tool  
because it's not well documented enough or suck it up and start  
helping out.  Most of the whiners are freeloaders....complaining, but  
never having contributed themselves to open source or ANTLR before.   
Bunch of ungrateful freeloaders...how dare you make these demands!

Ter