amk> The library reference has so many modules that the table of amk> contents is very large. Again, not really a problem that we can amk> fix; splitting it up into separate manuals doesn't seem like it amk> would help.
I've been meaning to tackle this with a wiki macro. It would remember the most frequently requested modules (say, the 10-20 most requested) and display them in a separate alphabetical section ahead of the normal massive module index. That would then become the module index I bookmark. I just haven't had the time to implement it. amk> I suspect the Achilles' heel of the docs is the Language Reference. amk> Put aside the fact that it's not up to date with new-style classes amk> and other stuff; that would be fixable with some effort. On a day-to-day basis I don't use the Language Reference at all. Once every couple months perhaps. I think most people who have absorbed the basic syntax and semantics of the language will be in the same boat. It's the Library Reference that requires the most effort I think. amk> To some degree, the guide is trying to be very formal; it's written amk> like a specification for an implementor, not a document that people amk> would read through. But there's no other way for people to learn amk> about all the special object methods like __add__; the tutorial amk> can't cover them all, and the LibRef doesn't describe them. So the amk> newbie is stuck. I think if the newbie has outgrown the Tutorial, they should be able to approach various bits of the Language Reference. Perhaps some bits of its subject matter should be tutorialized and added to the Tutorial amk> I don't know exactly what Bray meant, but suspect that a more amk> readable reference guide would have helped him understand what was amk> going on. I think it would be difficult to produce a more readable reference manual that doesn't introduce some vagueness that will be more difficult for implementers. The Global Index has this to say about various docs: Which Manual Target Audience ------------ --------------- Library Reference keep this under your pillow Language Reference for language lawyers Extending and Embedding tutorial for C/C++ programmers Python/C API reference for C/C++ programmers I think those comments are about right. amk> One problem with such a friendly document: it might make the Ref amk> Guide even more irrelevant, if we always updated the friendly amk> document (which is easy) and left the RefGuide to drift even amk> further out of date (because it's hard to update). Somehow I think Guido would eventually put his (16-ton) foot down. ;-) amk> Dumping the RefGuide means there isn't a more formal-style amk> description of Python's semantics. I don't know if this matters. amk> In theory, the implementors of Jython or IronPython could be using amk> the RefGuide to know what they need to implement, but in practice I amk> suspect implementors use the test suite and existing library as amk> checks. Maybe we don't really need a tediously precise description amk> of Python. I think you need something precise, if for no other reason than to distinguish the language definition from the canonical CPython implementation (or in the future to arbitrate disagreements betwee CPython, PyPy, IronPython or some other newcomer). Maybe we have the cart before the horse w.r.t. documenting changes to the language. When a new feature goes into the language proper it is generally discussed on python-dev and written up in a PEP then approved by Guido. We've generally accepted the PEP as informal documentation, but PEP's aren't really part of the formal documentation set. Perhaps all we need to do is be more stringent in requiring Language Reference updates before PEP acceptance. Skip -- http://mail.python.org/mailman/listinfo/python-list