[Python-Dev] introducing the experimental pyref wiki

[Michael Foord]

A.M. Kuchling wrote:
> On Sat, Apr 29, 2006 at 08:54:00PM +0200, Fredrik Lundh wrote:
>   
>>     http://pyref.infogami.com/
>>     
>
> I find this work very exciting.  Time hasn't been kind to the
> reference guide -- as language features were added to 2.x, not
> everything has been applied to the RefGuide, and users will probably
> have been forced to read a mixture of the RefGuide and various PEPs.
>
> The Reference Guide tries to provide a formal specification of the
> language.  A while ago I wondered if we needed a "User's Guide" that
> explains all the keywords, lists special methods, and that sort of
> thing, in a style that isn't as formal and as complete as the
> Reference Guide.  Now maybe we don't -- maybe the RefGuide can be
> tidied bit by bit into something more readable.  
>   
At my company we recently got badly bitten because the language syntax 
as defined in the 'language reference' varies wildly from the grammar in 
SVN.

We had to implement it twice !

When we tried to check syntax usage (as distinct from the BNF type 
specification in the grammar) we found that things like keyword 
arguments (etc) are not documented anywhere, except possibly in the 
tutorial.

Currently the language reference seems to neither reflect the language 
definition in the grammar, nor be a good reference for users (except 
parts that are excellent).

A users guide which straddles the middle would be very useful, and with 
some shepherding can probably be mainly done by community input.

I also find that when trying to implement objects with 'the magic 
methods', I have to search in several places in the documentation.

For example, to implement a mapping type I will probably need to refer 
to the following pages :

    http://docs.python.org/ref/sequence-types.html
    http://docs.python.org/lib/typesmapping.html
    http://docs.python.org/ref/customization.html

Michael Foord 

> (Or are the two goals -- completeness and readability --
> incompossible, unable to be met at the same time by one document?)
>
> --amk
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.uk
>
>