[Tutor] Documentation concerns.

[Adrian Maier]

Magnus Lyck? (magnus@thinkware.se) a scris :
> 
> The Language Reference manual is perhaps the real problem
> child. I remember having problems with it initially. It's
> labeled as "for language lawyers" and is largely a spec,
> written partly in BNF, but at the same time, this *is* the
> reference guide for non-module things like operators and
> statements of various sorts. If you want something which
> is more reference than the tutorial, you have to look here,
> and end up with a very formal text.

Yes... there is a big gap between the introductory elements in the
"Tutorial" and the "Language Reference" (which is too advanced, and
looks more like technical specifications than a manual ). 


Just an example, page 53 "Class definitions" (in the Reference):
---
classdef    ::= "class" classname [inheritance] ":" suite
inheritance ::= "(" [expression_list] ")"
classname   ::= identifier

(two descriptive paragraphs follow.)
---
Compare this 20-lines subsection with the "Tutorial" which contains an
entire chapter about classes... The tutorial is more clear and useful 
on that topic.


I think that the BNF notation used to describe the syntax is
not very intuitive, because the difference between this notation
and the Python language is significant. 

It would be better if the basic statements would be described 
using *both* the existing notation and some kind of pseudocode, like:

if <expression> :
   <statement1>
   <statement2>
   ....

or some kind of schemas  ( i'm thinking of the graphical notation
i have seen in "Turbo Pascal Programmer's Guide" and other Pascal
books to describe the language syntax. My appologies for the ones 
who don't know what i'm talking about. )


Best wishes,

-- 
Adrian Maier
(am@fx.ro)