[antlr-interest] You nailed the ANTLR docs problem there (Was: Why no links to ANTLR 3.0 on www.antlr.org??)

[Geir Ove Skjaervik]

-----Original Message-----
From: antlr-interest-bounces at antlr.org
[mailto:antlr-interest-bounces at antlr.org] On Behalf Of Gerald B.
Rosenberg
Sent: 4. juni 2005 10:48
To: Terence Parr; ANTLR Interest
Subject: Re: [antlr-interest] Why no links to ANTLR 3.0 on
www.antlr.org??


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