[antlr-interest] A postmortem of my use of antler

[Benjamin Shropshire]

I don't want to be a troll so plese understand I'm trying to be helpful 
with these comments, not antagonistic.

The concept of ANTLR is a really good idea.

The execution is fairly good (It could be better in a few places but 
it's not worth complaining about.

The documentation is abysmal.

In my experience, ANTLR doesn't so much have a learning curve as a 
learning step function. The documentation seems to assume a degree of 
understanding of what antlr is that, IMHO, is unreasonable to assume of 
a new user. In attempting to learn antler I was playing with it, reading 
what docs I could find, looking for and reading example code and looking 
at the output code. In all that, it took me over 2 weeks to even notice 
that the expected mode of operation is to lex, AST, work with AST. I saw 
mentions of AST and assumed that this was antlr's turm for the type of 
output that yacc and bison typically are sued to generate. This is just 
one example of a cases where the antlr docs seemed to assume a 
understanding of things that I didn't have. And I'm not talking general 
ignorance. I'm referring to ignorance of the specifics of antlr. The 
best I can do to describe my frustration is this: "the antlr doc's are 
not good enough to let a new user figure out what questions to ask." I'm 
not so dumb that I can't figure antlr out (theres nothing complicated 
with any part of it that I've used) I just wasn't asking the right 
questions and had no way to find that out.

Now I will confess that I have yet to read the manual cover to cover, 
but I think I've hit all of the intro material in it and in the web 
pages. If that material doesn't give the user something to hold onto, I 
fear that many users a just going to give up on antlr after only a few 
minutes to an hour. In retrospect that is what I /should/ have done. My 
bosses opinion is that antlr is not giving us much enough value over 
writing the parser by hand. I'm a bit embarrassed to say, I think he's 
correct and I could have/should have made that call a lot sooner.

Now for some rhetorical questions:

--What is ANTLR? Is it an academic research project? A source of work 
for grad students? A FOSS utility intended for the general community? A toy?
--Who is the intended user base? It's own developers? Language/grammar 
theory people? Professional programming gurus? The programming world at 
large?

I don't need answers to those, I'd be interested but it's academic at 
this point. If ANTLR is supposed to be what I think it's supposed to be, 
I think that ANTLR would benefit by the consideration of those questions.

My suggestion is that someone go over the docs with an eye to how well 
they present material to a brand new users. Does it quickly present the 
user with the information needed to (correctly) grasp the big picture? 
What IS the big picture? Does it give the user the information they need 
to find the information thy /really/ need? This would be no trivial task 
and I understand that. What wold do the most good would be to have about 
1 or 2 dozen new users (a compilers class?) be thrown at antlr with 
nothing but the current docs to work from. let them play with it for 
about a day or two and then start asking them what they found 
interesting/useful/confusing. Then start answering there questions and 
/recording/ what they asked, what they wanted to known (when these are 
different that is valuable info). Also take notes on what kind of 
assumptions, correct and incorrect they made. This info would be of huge 
value to the ANTLR project.

OK I understand that that project has about zero chance of happening, 
but one can dream...

I hope this is of some use.

Benjamin Shropshire

p.s. I might get to use ANTLR on another project (only, oddly enough, 
because the default rendering of AST looks like lisp)
p.p.s. Another guy on that last project (with a much different 
personality than me) also took a look at antlr and more or less agreed 
with me on the deficiencies of the antlr docs.