[antlr-interest] [v3] Lack of documentation
Randall R Schulz
rschulz at sonic.net
Sun Jul 1 18:06:33 PDT 2007
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
> 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
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
More information about the antlr-interest