[antlr-interest] [v3] Lack of documentation

[Randall R Schulz]

On Sunday 01 July 2007 03:32, Harald Wellmann wrote:
> Getting started with ANTLR v3 is a frustrating experience for its
> lack of coherent documentation and non-trivial example code.

I can both agree and disagree with this sentiment.

ANTLR is a powerful tool and not a simple one. Naturally, the two go 
together, for the most part.

On the other hand, when one is faced with a task that includes language 
processing, often it's but a small aspect of the overall problem. From 
this perspective, one wants to just write the parser and then put it on 
a shelf, never to be touched again. For what it's worth, for me this 
has actually been the case. I've done several parsers using JavaCC and 
one completed and another in progress using ANTLR.

I'm both frustrated by and incredibly impressed by ANTLR and ANTLRWorks. 
These are very sophisticated, very mature tools, and it is not really 
reasonable to expect it to be easy to use them, at least not right away 
or on your first go-around.


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

Two things come to mind:

1) Your problem may not be complicated enough to tip the balance of 
learning vs. power for ANTLR v3 by comparison to its predecessors.

2) You are premature in your criticism. Get to know the tools better 
before judging them.


> 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 seriously doubt that concerns that would traditionally be associated 
with a marketing department or director or campaign are what motivated 
the new capabilities of ANTLR v3. I don't really have the full history, 
but I can see no motivation for the principals to have proceeded in 
such a manner.


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

Perhaps you were just more motivated at the time or had more of your own 
time available to learn. I've found, generally speaking, that the 
earlier one is in their career in software, the easier it is to learn 
new things. This is really just part of the human condition—an aspect 
of our cognitive makeup and the finiteness of our brains and minds, if 
you will.


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

Well, I myself tend to respond with peevishness to being told to "read 
the source" (one of my recent postings supports this admission), but at 
root, nothing is hidden in an open-source project.

That said, I don't subscribe to the notion that open-source admits a 
lesser standard of software engineering, including documentation 
quality and comprehensiveness.

I will say, I don't think ANTLR's documentation is exemplary, but 
between what is available on-line, in the book and this forum (two of 
which are entirely open-ended, after all), one can be assured of 
accomplishing pretty much anything that is possible or essentially 
afforded by these tools.

It may well be the case that were ANTLR handled as a commercial tool 
with the standards of documentation one would expect from such a tool 
(and we're talking something with a multi-hundred-dollar per-user 
license or even a royalty structure in the "bad old days") a user could 
just sit down, with a well-defined task in hand, use the plethora of 
documentation (tutorial, reference, sample code, etc.) and bang out a 
parser on a pretty tight schedule. And that may not be possible for all 
or even most users at the moment, this is not a legitimate indictment 
of the quality of this software.


> 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.
>
> By the way, even this mailing list is inaccessible to most people in
> a corporate IT environment, as the Mailman Frontend is running on a
> non-standard port 8080 which tends to get blocked by firewalls.

I assume you're only talking about subscribing. Surely you could just 
leave the confines of your corporate network to initiate the 
subscription request, right? I've worked under such 
corporate "security" regimes, and they're onerous to workaday 
personnel, to say the least. But in this case, they're not 
insurmountable. (At my last corporate gig, they outlawed connections on 
all but a very few ports, cutting me off from my beloved dictionary 
service.)


> Regards,
>
> Harald


I hope you'll stick with ANTLR. It's really amazing. The whole concept 
of a tree grammar is gold. I don't think I'd ever have conceived of it 
myself, but once you're introduced to the concept, so many things 
become so much more straightforward. It's exemplary of the kind of 
advancement that facilitates lots of other work. Afterwards, one 
wonders why it didn't happen 20 or 30 years ago. But that's 
hindsight...


Randall Schulz