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@python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe:
> http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.uk
>
>
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
