[Python-ideas] Linking Doug's stdlib documentation to our main modules doc.

[Doug Hellmann]

On Mar 18, 2011, at 4:06 AM, Terry Reedy wrote:

> On 3/18/2011 1:50 AM, Tarek Ziadé wrote:
>> I don't know about any other place where there's such an exhaustive
>> documentation of the stdlib.
> 
> It may well be the broadest collection on the net. Indeed, it is so broad that he is having it published as a commercial book (Amazon is taking preorders). But that does not make each exposition the best there is for each and every module. I have elsewhere seen some pretty in-depth articles on particular modules. In any case, as I believe Doug acknowleded, it would be inappropriate to promote one particular book in the manuals.
> 
> What this discussion has so far ignored is that there is no such thing as 'the stdlib'. There are multiple Python versions and releases, and we have this thing called Python 3, which is a bit but significantly different from Python 2. Though the web pages do not say much that I found, the examples are for (mostly unspecified) Python 2. The book promo blurb specifically says 2.7, so I presume he tested and updated as necessary. (Probably not too much was needed since 2.x code is mostly forward compatible up to 2.7).

It isn't mentioned on every page, but the about page for the project does talk about the version of code and modules supported (2.7). I will make that information more explicit on each page when I start porting the examples to Python 3.

> I have no idea if he added new material for new features added late in Py2. For instance, an up-to-date discussion of difflib should include an example showing the need for the SequenceMatcher autojunk parameter added in 2.7.1 to fix the bug independently discovered and reported by multiple people.

Thanks, Terry, I'll make a note of that. I did try to refresh the content over the last year, but I'm sure I missed some subtle pieces or changes that went in after I finished the refresh. I think the difflib article is one of the first I wrote, so that would make it as somewhere between 3 and 4 years old. A lot has changed in that time!

> In any case, Python 3.x manuals should have examples that run with 3.x and not reference Python 2 code.

I understood Tarek's proposal to refer to the 2.7 docs only.

> 
>> Every module we have, have  more examples in Doug's work than in the
>> stdlib doc itself or elsewhere.
> 
> There are a lot of modules to check;-).
> 
>> I think this doc is the best one we have and not pointing to it is too
>> bad ihmo.
> 
> Do it on the wiki, as I suggested. But do specify that it is Python 2 code.

I think there is sufficient well-reasoned opposition to the idea that we should drop it. I appreciate Tarek's encouragement, but I also see the other perspective and don't want any ill-will. Google being what it is, people don't seem to have a hard time finding the examples where they are, so I am content to leave well enough alone.

Thanks,
Doug