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

Mark Mandel mark.mandel at gmail.com
Mon Mar 10 14:23:26 PDT 2008


Honestly,

With the amount of help that is available through this mailing list,
it pretty much cancels out any deficiencies that may or may not exist
in the documentation.

The documentation for ANTLR took me from woah, to go without a huge
hassle, and I had never worked on a Lexer or a Parser before, but I
did have to look outside ANTLR's documentation to do it, and I don't
think that is unreasonable.

I actually bought the book * after * I had used ANTLR for quite a
while, and all I can say is that it is an incredible resource.

Now, I have to assume as well, you're offering to help write all this
missing documentation? It is a Wiki after all, so I expect that after
this post you'll be quite active?

Mark

On Tue, Mar 11, 2008 at 7:29 AM, Benjamin Shropshire
<shro8822 at vandals.uidaho.edu> wrote:
> 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.
>
>



-- 
E: mark.mandel at gmail.com
W: www.compoundtheory.com


More information about the antlr-interest mailing list