[antlr-interest] [v3] Lack of documentation

Micheal J open.zone at virgin.net
Tue Jul 3 04:18:13 PDT 2007


Harald,

> 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.
> 
> Even v2 documentatation was a bit scarce, it always cost you 
> some trial and error to get things right, but this was bliss 
> compared to the scattered and incomplete bits of 
> documentation you get for v3.
> 
> Yes, I know there's a book now. And no, I don't think it's in 
> the spirit of  a successful open source project to hide all 
> relevant information in a book that is only available commercially.

The ANTLR wiki has lots of tutorials and other information for learning to
use ANTLR v3. There is also some information on learning v3 for those used
to v2.

The model of freely available open source software supported by basic free
documentation plus comprehensive documentation as a paid-for book is quite
common actually. Many of the various JBoss projects are good examples.

I'm all for it since it goes some way to ensuring the project's continued
existence.

> There's nothing wrong about books, but you can publish a book 
> and still make the information publicly available, see e.g. 
> the Subversion Book.

Or not. It's the book writer's choice.

The project has had a wiki for over a year now to encourage contributions to
the documentation. The source has been available for long enough for any
interested party to grok it and write about it in the wiki.


Micheal

-----------------------
The best way to contact me is via the list/forum. My time is very limited.



More information about the antlr-interest mailing list