[antlr-interest] [v3] Lack of documentation

Alexandre Porcelli porcelli at uol.com.br
Sun Jul 1 10:37:54 PDT 2007

It is very difficult read these messages and just forgets it and move
directly to trash!

Most of people are learning and exchanging knowledge through this
list; It is amazing that a person ask for more than that (for free!)
and use this list for it!

We have a great book available and a great people exchanging info here
- what else is necessary? More docs? The Terr's book is wonderful ,
during the read we know that he wrote that with passion to disseminate
knowledge, and had careful to make the book accessible for everyone!

Now a days I use v3 in my day by day… and reading these messages I'm
feeling a bit embarrassed and even need to ask for apologies to not
contribute more to this great software...

On 7/1/07, Terence Parr <parrt at cs.usfca.edu> wrote:
> 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

More information about the antlr-interest mailing list