[antlr-interest] ANTLR documentation restructuring
Terence Parr
parrt at jguru.com
Sun Oct 20 12:39:45 PDT 2002
On Wednesday, October 9, 2002, at 10:49 PM, Daniel Gackle wrote:
> If I may offer a suggestion, I've spent a lot of time poring over the
> documentation, and it would be worlds easier if care were taken to
> define
> each notion before using it. The way it is structured now is sort of
> like
> this: X is explained using Y and Z, Y is explained using X and A and B
> and
> C, Z is explained in terms of A and Y and D, C and D are not explained
> anywhere and, well, you get the picture. It's the sort of
> documentation
> that makes perfect sense if you already know what everything means,
> but is
> hard to break into if you don't, which kind of defeats the purpose of
> documentation. I don't doubt that this is partly because of the high
> level
> of expertise of the authors. It is often difficult to temporarily
> forget
> what you know in order to walk someone step by step into that
> knowledge.
Howdy. Yeah, the doc is pretty much just a "core dump" w/o regards to
flow. more of a reference manual if you're already "in the know". :(
> Of course, you can't explain everything back to the beginning of the
> world,
> but it is certainly possible to say, "an introduction to X is out of
> the
> scope of this document, here are some good sources to learn about X".
I'm hoping that when I start up on the book again in January 2003 (yep
in a few months...gotta start teaching a grad language course) that it
will provide the background so that the reference manual will make more
sense.
> I have really come to appreciate ANTLR as an excellent tool, and have
> also
> gotten good information from the docs, so I hope my remarks don't sound
> cranky. I do believe that ANTLR would profit immensely from an
> orderly,
> clear exposition. In my dreams I imagine something like an O'Reilly
> book...
> a solid O'Reilly book on ANTLR would really make the power of this tool
> accessible to the wide audience it deserves.
Yep, perhaps my rework of the doc will be sufficiently good to make it
a real book. My language book will be a "magnus opus" and take me
probably 2 more years after I start again. The ref book could be done
quickly. I'm converting to TML (Terence's Markup Language) as we
speak. From that I can gen HTML, PDF, etc... in nice format so I'll
look at how far off from a book the doc is. I'm guessing pretty far :(
Ter
--
Co-founder, http://www.jguru.com
Creator, ANTLR Parser Generator: http://www.antlr.org
Lecturer in Comp. Sci., University of San Francisco
Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/
More information about the antlr-interest
mailing list