[antlr-interest] [v3] Lack of documentation

[Jim Idle]

> -----Original Message-----
> From: scott at javadude.com [mailto:scott at javadude.com]
> Sent: Monday, July 02, 2007 3:58 PM
> To: Jim Idle
> Cc: ANTLR Interest
> Subject: Re: [antlr-interest] [v3] Lack of documentation
> 
> >> I'M SAYING THE ANTLR v3 LICENSE IS BS IF PEOPLE MUST PAY FOR THE
> BASIC
> >> DOCS.
> >>
> >
> > I think that the point is that you are NOT forced to buy the book,
in
> > the same way you are not forced to buy lots of books on PHP, Java or
> the
> > dragon book (especially the latest edition) and so on.
> 
> Completely different. The Java Language Manual is free. It has all the
> details of the language in it.

It is exactly the same - the wiki documentation is free and so is the
source code. The fact that there aren't an army of documentation bods to
fill in the wiki at the moment is because Sun aren't paying them. That
doesn't mean that somehow there is a conspiracy to prevent any free docs
until Ter has made his first million :-)

> The ANTLR v3 ref manual is only available in the book. You must buy it
> to
> know the deets.
> 
> For example:
> * How do I use scopes? Only in the book

Err... and in the example grammar project "DynamicScope" in the Java, C
and C# targets, where it says:

    scope 
    {
      /** name is visible to any rule called by method directly or
indirectly.
       *  There is also a stack of these names, one slot for each nested
       *  invocation of method.  If you have a method nested within
another
       *  method then you have name strings on the stack.  Referencing
       *  $method.name access the topmost always. 
       */

/** Demonstrate that 'name' is a dynamically-scoped attribute defined
 *  within rule method.  With lexical-scoping (variables go away at
 *  the end of the '}'), you'd have to pass the current method name
 *  down through all rules as a parameter.  Ick.  This is much much
better.
 */

And so on.

> * How do I use predicates? Only in the book (unless you look at v2
> docs)

A quick search of the archives of this list will show you, as will
typing antlr3 predicates into google. I can't really agree that this is
hidden. I can agree that it is a bit of a muddle right now, but then you
could help out here, as well as many others. The wiki is a good place
for this stuff.

> 
> But he's already written the content; he's just hiding it in the book.

No, that isn't true as google easily shows. If anything, Ter is trying
to make ANTLR3 more professional and accessible. If you think that the
book and the online docs are in the wrong order then fair enough, but it
is too much of a stretch to say that he is hiding it and somehow
ransoming you for a $3 profit. It WILL all turn up, but it IS early days
yet.

Anyway, that's enough from me on this subject.

Jim