[antlr-interest] Why no links to ANTLR 3.0 on www.antlr.org??

[Gerald B. Rosenberg]

At 12:14 PM 6/3/2005, Terence Parr wrote:

>>I am over the beginner level know (I think and hope), but getting
>>there
>>was very time-consuming: And, isn't a tool like this about saving
>>time?
>
>Why was it time consuming to get through the beginning level?  I'll
>need this info when I write the book.  Is it because language tools
>are just different from normal programming or does the tool suck?
>Does the intro doc suck?

I will try to take a constructive stab at this.  Given that the problem 
space and tool are respectively very complex and capable of very complex 
operation, the documentation is just too eager.  It presents something 
basic and then jets off mixing a bunch of fairly complex potential uses 
together which makes following and understanding any one very difficult.

For example, under http://www.antlr.org/doc/trees.html#_bb4, there is brief 
introduction to marking lexer tokens as roots.  Ok.  Then some stuff about 
building trees.  Nothing there about parser tokens as roots.  I think that 
is what I need for my problem -- I need to understand better how ANTLR 
wants to mark and construct parser trees.  So, is marking a new parser 
token as a root even possible?  Well, keep looking down.  Token 
translation.  Ok.  Token factories.  Ok, I guess.  Heterogeneous ASTs.  Ok, 
real advanced.  Fairly certain that is not applicable to my initial needs.

Finally! An first example ("An Expression Tree Example").  Maybe that will 
walk me through enough to understand how ANTLR wants  me to solve my problem.

Problem statement: a simple value accumulator implemented using a simple 
tree.  Ok, not really close to my case I think, but sounds like it has a 
similar level of complexity so I should be able to learn bunches from it.

OH, NO: Third paragraph, the "formal statement of the explanation of the 
solution to follow":

"The AST operator nodes must combine the results of computing the value of 
their two subtrees.  They must perform a depth-first walk of the tree below 
them.  For fun and to make the operations more obvious, the operator nodes 
define left() and right() instead, making them appear even more different 
than the normal child-sibling tree representation.  Consequently, these 
expression trees can be treated as both homogeneous child-sibling trees and 
heterogeneous expression trees."


??? Fun and obvious???  Make them appear more different???  A straight 
first example?  No.  More accurately an advanced transvestite example.

There are so many issues working in this example, I challenge anyone not 
already an expert to readily tell what design features pertain to what -- 
what is there for fun and what select parts are essential for the 
particular purposes relevant to a relative new-comer's basic issues of 
understanding.  The question is, would someone not capable of authoring 
this example in the first place, now understand matters well enough to go 
back and author the simple, straight-forward version?

Now, don't get me wrong: I am not advocating plodding 
documentation.  Enthusiasm is a great tool for maintaining interest in the 
narrative, particularly on paper.  There just needs to be something of a 
middle ground (at least for us middle of the road programmers).

HTHs,
Gerald


----
Gerald B. Rosenberg
Certiv Analytics

www.certiv.net