[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