[antlr-interest] [v3] Lack of documentation

[Matt Benson]

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

:)  I can't stay out of it any longer.  That sounded
harsh and some folks may take Ter up on the offer to
bail, but c'est la vie... I read this as an indication
that he's secure enough in ANTLR's intrinsic value
that he doesn't fear to lose a couple of the
"freeloaders".  If you've ever worked with some
blockhead who has somehow managed to infiltrate our
ranks, you may have found yourself wishing you didn't
have to deal with such riffraff, so it doesn't really
surprise me if Ter makes the decision that there are
enough clueful devs out there that he won't miss the
ones who want to use a new version of a free tool
still in its infancy but expect the free doc to be
comprehensive.  One thing about open source is that it
emphasizes an amusing division among developers:  some
take it as an affront that they are expected to sully
themselves reading source code; others see it as a
privilege and thank Boole (that's a joke) that they
have access to the source code.  Personally, I often
read OSS source before even attempting to use a given
API, though that may be due to some failing on my part
that I can understand syntactically constrained source
code more readily than potentially ambiguous English. 
;)  And since I know I'm not the first to make this
observation, I shouldn't have to, but... duh, it's
entirely understandable that writing doc is tedious,
while writing code is fun.  And if you can't
sympathize with writing code being fun, you're in the
wrong business.  :|

-Matt

> Ter
> 
> 
> 



       
____________________________________________________________________________________Ready for the edge of your seat? 
Check out tonight's top picks on Yahoo! TV. 
http://tv.yahoo.com/