Documentation suggestions

[rurpy at yahoo.com]

Fredrik Lundh wrote:
> Ian Bicking wrote:
>
> > > the standard library is not an add-on.  you're confused.
> >
> > I think the point is that there is the core language, and from a user's
> > perspective builtins and statements and syntax are all the same thing.
> > When you import a module, it's more-or-less obvious where you find
> > information about the module (the module index, of course).  But
> > "print", "sorted", and "list" are all equally "built in" in the mind of
> > a new user.
>
> so are many standard modules (don't tell me that any real user will
> learn all the builtins before she writes her first import statement...)

If this is a reference manual (as opposed by a tutorial)
then the order information is presented in is not guided
by a user's order of use.  It just needs to be presented
coherently (so you can find what they want quickly (with
the relevant material all together), and hopefuly in an
order that minimizes forward references (so it can be
read sequentially if desired).  This order had been
worked out by many previous language manuals and
I think is equally usable for Python.

> > A new and improved language reference document should deal with all of
> > these together, I think.
>
> wasn't the idea to get rid of the language reference altogether, and
> replace it with a better introduction ?

Can an introduction provide the information the language
reference provides (or maybe I am misunderstanding what
you mean by introduction.)