[Python-Dev] introducing the experimental pyref wiki

[Fredrik Lundh]

A.M. Kuchling wrote:

> 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.

or as likely, mailing list archives.

> 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.
>
> (Or are the two goals -- completeness and readability --
> incompossible, unable to be met at the same time by one document?)

well, I'm biased, but I'm convinced that the pyref material (which consists
of the entire language reference plus portions of the library reference) can
be both complete and readable.  I don't think it can be complete, readable,
and quite as concise as before, though ;-)

(see the "a bit more inviting" part on the front-page for the guidelines I've
been using this far).

</F>