On 3/17/2011 7:19 PM, Senthil Kumaran wrote:

On Wed, Mar 16, 2011 at 05:35:41PM -0400, Doug Hellmann wrote:

...

...

As I told Doug during Pycon, I think it would be a good idea to link his PyMOTW pages to our modules documentation in docs.python.org so people have more examples etc.

Various people have written various docs showing Python by example. I do not think any one should be singled out in the docs. On the other hand, the wiki could have a PythonByExample page (or pages) with links to various resources. If someone were ambitious, there could even be a page for each builtin class and each stdlib module, each with multiple links and examples. -- Terry Jan Reedy

I don't know about any other place where there's such an exhaustive documentation of the stdlib. Every module we have, have more examples in Doug's work than in the stdlib doc itself or elsewhere. I think this doc is the best one we have and not pointing to it is too bad ihmo. Le 17 mars 2011 18:48, "Steven D'Aprano" <steve@pearwood.info> a écrit :

Terry Reedy wrote:

...

On 3/17/2011 7:19 PM, Senthil Kumaran wrote:

...

On Wed, Mar 16, 2011 at 05:35:41PM -0400, Doug Hellmann wrote:

...

...

As I told Doug during Pycon, I think it would be a good idea to link his PyMOTW pages to our modules documentation in docs.python.org so people have more examples etc.

Various people have written various docs showing Python by example. I do not think any one should be singled out in the docs. On the other hand, the wiki could have a PythonByExample page (or pages) with links to various resources.

What he said.

With all respect to Doug, do we really want to bless his website more than any of the other Python blogs, tutorials, etc. out on the Internet?

I wouldn't mind having a prominent "External resources" page in the Python docs, if it is actively maintained and doesn't turn into a bunch of dead links in 12 months time. But I have grave doubts about linking to an external site all through the module documentation, no matter how useful it is. Who controls the external content?

-- Steven

_______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas

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

On Thu, Mar 17, 2011 at 8:47 PM, Steven D'Aprano <steve@pearwood.info>wrote:

Terry Reedy wrote:

...

On 3/17/2011 7:19 PM, Senthil Kumaran wrote:

...

On Wed, Mar 16, 2011 at 05:35:41PM -0400, Doug Hellmann wrote:

As I told Doug during Pycon, I think it would be a good idea to

...

...

link his PyMOTW pages to our modules documentation in docs.python.org so people have more examples etc.

Various people have written various docs showing Python by example. I do not think any one should be singled out in the docs. On the other hand, the wiki could have a PythonByExample page (or pages) with links to various resources.

What he said.

With all respect to Doug, do we really want to bless his website more than any of the other Python blogs, tutorials, etc. out on the Internet?

Bah humbug. If we could link stdlib docs to every good quality piece of coverage for that module then that would be great. It's not like someone else has been denied, or that we're giving Doug exclusive linking rights or something. It just happens he has written the most comprehensive and maintained set of docs, and so it would be bureaucratically rather easy to get a bunch more helpful links in the docs that will help people learn Python better. Frankly it doesn't matter if it's "blessed" as that doesn't incur any real benefit.

I wouldn't mind having a prominent "External resources" page in the Python docs, if it is actively maintained and doesn't turn into a bunch of dead links in 12 months time. But I have grave doubts about linking to an external site all through the module documentation, no matter how useful it is. Who controls the external content?

Adding any content, including links, incurs extra maintenance for that content. Links are a little harder than other pieces, and they should be added only with some consideration of the quality of the content. Again, conveniently, PyMOTW is a big list of quality documents, and AFAICT there is widespread approval of the content. Appropriate linking to some other documents might also be quite helpful; adding PyMOTW makes it more likely that will happen, but worrying about all the links we *aren't* adding doesn't move anything forward at all. Some tooling to manage the links would be nice, but doesn't seem like a particularly big barrier -- a standard link checker would find dead links (including existing external links) and there are tools to mirror content so that if it's considered valuable and it really does disappear, we can consider mirroring it (Wikipedia seems to do something roughly like this with web-addressable citations). Ian

On Fri, Mar 18, 2011 at 6:29 PM, Guido van Rossum <guido@python.org> wrote:

On Fri, Mar 18, 2011 at 1:48 PM, Ian Bicking <ianb@colorstudy.com> wrote:

...

On Thu, Mar 17, 2011 at 8:47 PM, Steven D'Aprano <steve@pearwood.info> wrote:

...

With all respect to Doug, do we really want to bless his website more than any of the other Python blogs, tutorials, etc. out on the Internet?

Bah humbug.  If we could link stdlib docs to every good quality piece of coverage for that module then that would be great.  It's not like someone else has been denied, or that we're giving Doug exclusive linking rights or something.  It just happens he has written the most comprehensive and maintained set of docs, and so it would be bureaucratically rather easy to get a bunch more helpful links in the docs that will help people learn Python better.  Frankly it doesn't matter if it's "blessed" as that doesn't incur any real benefit.

Good call!

+1000 Dougs docs are indispensable. The number of times I have had people at work and elsewhere come to me and ask "why aren't the PMOTW in, or linked to from the stdlib docs" is astounding. People consider them *better* resources than the stdlib docs right now. We shouldn't be afraid to link to real, valuable resources that enhance peoples' ability to learn the language and the standard library. I don't agree with the hand waving around broken links, the fact the Doug wrote a book, endorsements, etc. The fact is, he's written better docs on many things, and we're doing the community a disservice by not actively exposing them as supplements to the existing documentation. Why is it so hard to simply do the right thing here? jesse

On Sun, Mar 20, 2011 at 3:27 AM, Jesse Noller <jnoller@gmail.com> wrote:

I don't agree with the hand waving around broken links, the fact the Doug wrote a book, endorsements, etc. The fact is, he's written better docs on many things, and we're doing the community a disservice by not actively exposing them as supplements to the existing documentation.

Why is it so hard to simply do the right thing here?

Because it's a new idea and a level of integration-without-incorporation that hasn't been considered before. The PSF reps on here (along with everyone else) wouldn't be doing a good job as stewards of the language if valid concerns were glossed over without being given due consideration. We may decide that given the specifics of the situation then including direct links from the 2.7 documentation to the current 2.x specific versions is an appropriate outcome. If Doug no longer wanted to maintain them separately in the future, then they could be incorporated at that point rather than having to do it up front (ideally under a contributor agreement, since relying on the existing CC license would mean that commercial entities like IDE vendors would need to drop it when redistributing the Python documentation set). The key point that I think distinguishes PyMoTW from most other documentation resources is that even though it is also being published as a book, the whole thing is available online under a Creative Commons Attribution-NonCommercial-ShareAlike license. Linking to a public resource like that is a *very* different prospect to linking to something that isn't independently redistributable. The source code for it all is also posted on github, so even if Doug were to abandon the project and drop off the face of the planet tomorrow, the repo could be cloned by a new maintainer. PyMOTW also covers each module individually, and links back to the relevant section of the official Python documentation*, something which other online resources may not do. For the reasons given above, I'm also +1 on including PyMoTW links in a "See Also" block at the bottom of each module's documentation. There are specifics at play here (as noted above) that distinguish this from linking to arbitrary resources on the web. One advantage to doing this systematically is that it can be done as part of the documentation generation process, rather than needing to be maintained individually in the source code of the documentation for each module. Cheers, Nick. * I thought http://docs.python.org/2.x had been added as an alias to allow stable external links to 2.x specific documentation, but neither that or 3.x appear to be currently working. -- Nick Coghlan   |   ncoghlan@gmail.com   |   Brisbane, Australia

On 3/19/2011 5:39 PM, Nick Coghlan wrote:

On Sun, Mar 20, 2011 at 3:27 AM, Jesse Noller

...

Why is it so hard to simply do the right thing here?

First one must decide what is the right thing. Do you agree that adding 2.x examples to 3.x doc is the wrong thing? The initial proposal did not mention the Python version that Doug's work applies to, and indeed http://www.doughellmann.com/PyMOTW/about.html (still) does not either. Ths only hint on that page is the example showing that 'import PyMOTW' works on 2.6. I had to go to Amazon to discover and report that the book is aimed at (and presumably tested with) 2.7. The initial proposal also did not specify the version of the docs to be augmented. Usually, these days, 'add x to the docs' means to add to the current 3.x development docs and maybe backport. I do not see '2.7' in the subject line above. I believe I was the first to raise these issues.

Because it's a new idea and a level of integration-without-incorporation that hasn't been considered before. The PSF reps on here (along with everyone else) wouldn't be doing a good job as stewards of the language if valid concerns were glossed over without being given due consideration.

+1 -- Terry Jan Reedy

Ian Bicking wrote:

On Thu, Mar 17, 2011 at 8:47 PM, Steven D'Aprano <steve@pearwood.info>wrote:

...

Terry Reedy wrote:

...

On 3/17/2011 7:19 PM, Senthil Kumaran wrote:

...

On Wed, Mar 16, 2011 at 05:35:41PM -0400, Doug Hellmann wrote:

As I told Doug during Pycon, I think it would be a good idea to

...

...

link his PyMOTW pages to our modules documentation in docs.python.org so people have more examples etc.

Various people have written various docs showing Python by example. I do not think any one should be singled out in the docs. On the other hand, the wiki could have a PythonByExample page (or pages) with links to various resources.

What he said.

With all respect to Doug, do we really want to bless his website more than any of the other Python blogs, tutorials, etc. out on the Internet?

Bah humbug. If we could link stdlib docs to every good quality piece of coverage for that module then that would be great. It's not like someone else has been denied, or that we're giving Doug exclusive linking rights or

In that case, I nominate Michael Foord's documentation of urllib2 for linking as well: http://www.voidspace.org.uk/python/articles/urllib2.shtml I am serious, by the way, I think Michael's urllib2 docs are excellent. But are we sure we want to go down this path? It's neither practical nor desirable to fill the Python docs with links to every good quality external source, so in a very real sense, yes, others will be denied. If not now, at some point we're going to say "I'm sorry, your web site is really excellent, but we're not going to link to you." But that's not my main objection. We keep the bar high for inclusion in the standard library, and it shouldn't offend anyone. I'm sure people will cope with the disappointment of having their excellent tutorial or blog rejected for inclusion. I think that the real risk comes from the implications of linking to an external page from the docs. If you think that there are no such implications, then you will probably think that there is no downside to such links. I hope to persuade you that there are, and that they need to be considered before making this decision. Giving a list of "useful external resources" is a very different from linking to Doug's site repeatedly throughout the module docs. The Python docs are not some blog, where external links are posted for fun or for giving credit, nor is it Wikipedia where the external links are used as authority. The Python docs are the authority. If they link to an external page, it confers some level of authority and officialness to that external page. Sometimes we do so explicitly, e.g. we link to Fredrik Lundh’s Elementtree pages: http://docs.python.org/library/xml.etree.elementtree.html othertimes it is implied, e.g. the Decimal docs say "See also" and then link to a pair of carefully selected (semi-)official sources. But the proposal goes even further: it would link to Doug's site from nearly every page in the modules documentation. By linking to an external site in such an intimate fashion, I believe we would be giving a significant level of official standing to an external site that we don't control. We would be saying not just that the site is a useful site, but that it's such a great site, and a *trusted* site, that we link to it all throughout the official documentation. That says a lot, and we shouldn't be so blasé about saying it.

something. It just happens he has written the most comprehensive and maintained set of docs, and so it would be bureaucratically rather easy to get a bunch more helpful links in the docs that will help people learn Python better. Frankly it doesn't matter if it's "blessed" as that doesn't incur any real benefit.

I think you mean "cost". But there is a real cost as well as benefit: the cost comes as risk. I think you have misunderstood my point about who controls the external content. Dead links are the least risk, and the only one that can be managed automatically. We would be linking to pages that aren't controlled by us. We have no real control over whether the pages remain updated, or what content goes into those pages, or whether they get filled with advertising, or whatever. These are real risks -- even if you trust Doug implicitly, what happens if he gets hit by a bus and somebody else takes over his website? Elementtree excepted, when we take on a module or package and distribute it as an official part of the standard library, we expect the author to hand over official control to the PSF (even if practical control remains in the author's hands). Perhaps we should consider something similar for documentation. -- Steven

On Sat, 19 Mar 2011 12:48:48 +1100 Steven D'Aprano <steve@pearwood.info> wrote:

But that's not my main objection. We keep the bar high for inclusion in the standard library, and it shouldn't offend anyone.

Has treating the documentation like the library been considered? That is, instead of linking to Doug's examples, assuming Doug consented, incorporate them directly into the doc, and give Doug a commit bit so he can maintain them. That would also solve the versioning issues, at least to the level of "which version is the example for." Done right, the examples should be automatically testable. <mike -- Mike Meyer <mwm@mired.org> http://www.mired.org/consulting.html Independent Software developer/SCM consultant, email for more information. O< ascii ribbon campaign - stop html mail - www.asciiribbon.org

On 3/19/2011 10:54 AM, Doug Hellmann wrote:

Drawing a parallel from the way the library code is handled, it seems best to treat PyMOTW as a separately maintained resource and let users find it separately. Now, if there was an index equivalent to PyPI for documentation resources, *that* would complete the analogy. :-)

A Python Documentation Index (PyDI) is a nice idea. Authors could register, select keywords, and add links (and possibly upload). Users could search and rate as with packages. -- Terry Jan Reedy

On Fri, Mar 18, 2011 at 8:48 PM, Steven D'Aprano <steve@pearwood.info>wrote:

Ian Bicking wrote:

...

On Thu, Mar 17, 2011 at 8:47 PM, Steven D'Aprano <steve@pearwood.info

...

wrote:

Terry Reedy wrote:

...

On 3/17/2011 7:19 PM, Senthil Kumaran wrote:

...

On Wed, Mar 16, 2011 at 05:35:41PM -0400, Doug Hellmann wrote:

...

As I told Doug during Pycon, I think it would be a good idea to

...

link his PyMOTW pages to our modules documentation in > docs.python.org so people have more examples etc. > > Various people have written various docs showing Python by example.

I do not think any one should be singled out in the docs. On the other hand, the wiki could have a PythonByExample page (or pages) with links to various resources.

What he said.

With all respect to Doug, do we really want to bless his website more than any of the other Python blogs, tutorials, etc. out on the Internet?

Bah humbug. If we could link stdlib docs to every good quality piece of coverage for that module then that would be great. It's not like someone else has been denied, or that we're giving Doug exclusive linking rights or

In that case, I nominate Michael Foord's documentation of urllib2 for linking as well:

http://www.voidspace.org.uk/python/articles/urllib2.shtml

I am serious, by the way, I think Michael's urllib2 docs are excellent.

Certainly, it also seems very appropriate.

But are we sure we want to go down this path? It's neither practical nor desirable to fill the Python docs with links to every good quality external source, so in a very real sense, yes, others will be denied. If not now, at some point we're going to say "I'm sorry, your web site is really excellent, but we're not going to link to you."

But that's not my main objection. We keep the bar high for inclusion in the standard library, and it shouldn't offend anyone. I'm sure people will cope with the disappointment of having their excellent tutorial or blog rejected for inclusion.

I guess I'd summarize your point here that you feel that collective ownership and maintaining of additional docs will lead to better quality than external and single-author documentation. I think with docs in particular this is difficult because the bureaucratic nature of collective ownership makes it hard to actually do the work to improve documentation, as it's hard to maintain a sense of voice and I think it's hard to maintain the willpower to write documentation in particular in the face of collectivist stop-energy. And unlike the standard library itself, documentation does not suffer nearly as much from size -- the stdlib itself is conservatively maintained, but documentation could be much more freely maintained, and external links are one way of accomplishing that.

I think that the real risk comes from the implications of linking to an external page from the docs. If you think that there are no such implications, then you will probably think that there is no downside to such links. I hope to persuade you that there are, and that they need to be considered before making this decision.

Giving a list of "useful external resources" is a very different from linking to Doug's site repeatedly throughout the module docs. The Python docs are not some blog, where external links are posted for fun or for giving credit, nor is it Wikipedia where the external links are used as authority. The Python docs are the authority. If they link to an external page, it confers some level of authority and officialness to that external page. Sometimes we do so explicitly, e.g. we link to Fredrik Lundh’s Elementtree pages:

http://docs.python.org/library/xml.etree.elementtree.html

othertimes it is implied, e.g. the Decimal docs say "See also" and then link to a pair of carefully selected (semi-)official sources.

I don't think there is any significant authority incurred here, because the docs themselves are not authoritative. Generally speaking if many people use something in the standard library that is not documented, it turns into a kind of precedence anyway -- so if Doug or anyone else documents something non-public in the standard library, it means that interface is going to have to be supported or at least thoughtfully deprecated. That's true regardless of linking.

But the proposal goes even further: it would link to Doug's site from nearly every page in the modules documentation. By linking to an external site in such an intimate fashion, I believe we would be giving a significant level of official standing to an external site that we don't control. We would be saying not just that the site is a useful site, but that it's such a great site, and a *trusted* site, that we link to it all throughout the official documentation. That says a lot, and we shouldn't be so blasé about saying it.

I... don't really get this. I feel fine with this condition with respect to Doug's docs, but I don't see it as necessary anyway; there are good documents written by relatively unknown authors on specific topics. I don't seriously fear those docs will be changed underneath our feet. They probably *won't* be updated, and I have definitely noticed old Developer's Works articles that are distractingly out of date. OTOH, linking to good things *helps*, because when you Google for something it's hard to separate the old from the new. It adds us to the curation process.

something. It just happens he has written the most comprehensive and

...

maintained set of docs, and so it would be bureaucratically rather easy to get a bunch more helpful links in the docs that will help people learn Python better. Frankly it doesn't matter if it's "blessed" as that doesn't incur any real benefit.

I think you mean "cost".

I mean benefit to the person we're linking to. People are writing these things to help other people learn Python, they are acts of generosity, and any other benefits they might incur to the author are just a nice coincidence.

But there is a real cost as well as benefit: the cost comes as risk. I think you have misunderstood my point about who controls the external content. Dead links are the least risk, and the only one that can be managed automatically. We would be linking to pages that aren't controlled by us. We have no real control over whether the pages remain updated, or what content goes into those pages, or whether they get filled with advertising, or whatever. These are real risks -- even if you trust Doug implicitly, what happens if he gets hit by a bus and somebody else takes over his website?

Easy: we change the links! Even if we have to remove them entirely and lose the content, in the meantime it will have done good. If it seems like a concern, maybe we can talk about licensing -- e.g., a nice CC license (I don't see a problem with non-commercial), with a gentleman's agreement that we not clone the content unless the author explicitly lets go or becomes unresponsive. But such licensing is a detail we can consider later IMHO, it doesn't have any concrete effect now and we could look at it later if we start seeing a lot of external documentation and use of that documentation. There are some content management concerns, which would probably be good to think through. It would be nice if links were tagged with what Python versions they describe because it is a realistic concern that things won't be updated (and already there's many things that aren't updated for Python 3, or will be forked documents in which case you'd want both links in with different tags). It would be even nicer if we had a little microformat for pages to self-describe versions. It would be nice if there was a somewhat transparent link submission process, along with content guidelines; even if they are fuzzy guidelines like "a new link should add significant benefit over the content of the original documentation and any existing links" or "we strongly prefer documentation that has seen community acknowledgement and use". Mostly expectation management for submitters. External documents that themselves refer to other documents can be problematic, especially something like "a review of web frameworks" -- which might be nice to link to from wsgiref, but in a practical sense probably much too hard to maintain unless someone really wrote it to be timeless (which would be possible with the proper PyPI category links, wiki links, etc). I don't feel like just linking to wiki.python.org pages is a good idea, because all the problems with external links are also problems with wiki pages and generally wiki pages seem to end up worse -- more out of date, less well edited, more dead links, etc. In theory they could be maintained better, but it's failed enough in practice to put me off (barring some serious rethinking of the wiki itself; like maybe a more Stack Overflow approach might be successful where a freeform editable page is not). Also I don't think we'd see much traffic from the docs through to useful external resources if we have an interstitial wiki page. And if people don't click through then we'll have neutered the point of the original proposal. Ian

Would someone please just commit a doc fix to include the links? No one who is against it seems to care enough that they would revert them. -Jack

On Sun, Mar 20, 2011 at 11:30 AM, Jack Diederich <jackdied@gmail.com> wrote:

Would someone please just commit a doc fix to include the links?  No one who is against it seems to care enough that they would revert them.

While the philosophy of "rough consensus and running code" does hold in general, there's no need to quite *that* high-handed about it. The general objections to pervasive linking to an external resource are sound (perceived endorsement, risk of link rot, risk of outdated content). However, I (along with many others) am of the opinion that those concerns are of minimal significance in this case due to the open nature of the licensing on PyMOTW, and especially given the potential gain in allowing *new* Python users to more easily come to grips with Python modules, without needing to ask questions of the internet in general (and search engines in particular). The fact that the author and current maintainer of PyMOTW is an active member of the Python community in other ways certainly helps, but it isn't critical to the question of whether or not such links would improve the documentation. That said, with the BDFL and the current docs maintainer both in favour of the proposal, discussion should really be moving more towards "How?" rather than "Whether or not?". Cheers, Nick. -- Nick Coghlan   |   ncoghlan@gmail.com   |   Brisbane, Australia

On Sun, Mar 20, 2011 at 1:52 PM, Alexander Belopolsky <alexander.belopolsky@gmail.com> wrote:

How?  Instead of "pervasive linking"  add a link to a "See also" sections of the modules for which PyMOTW in the opinion of the editor (meaning committer who adds the link) is a valuable addition to the official documentation.  Note that this is the same approach as we currently take with respect to source code links.  We don't add them pervasively, but only in cases when the source code is deemed useful to the target audience.

There's a huge difference between linking to source code (which may or may not be edifying when it comes to respecting current Python idioms) by default, and linking to well written documentation. Having a mechanism to say "please don't automatically link to PyMOTW for this module, I really, really don't like it and think it will actively harm anyone attempting to understand how best to use this API" may make some sense, but can anyone cite a case where PyMOTW is actually *that* wrong? To those who see these links as a bad idea, who are you afraid it will hurt? We have an immediate target audience that we think it will help: new Python users that will read the docs and follow the links there.

From those opposing it I've heard objections along the lines of...

1. Why endorse Doug's take on the standard library over that provided by a multitude of other authors (such as Dive into Python, Python Essential Reference, etc)? PyMOTW is unique (as far as I am aware) as it is structured the same way as the Library Reference (i.e. with per-module documentation), reasonably comprehensive (although it does leave out some of the more obscure modules, such as binhex) and released under a permissive CC license that allows independent redistribution (albeit not by commercial entities). That's a hugely valuable resource that has been made available for free, and we'd be doing our users a service by linking to it more prominently than just providing a single link in an irregularly maintained and unpublicised list of additional resources [1] that isn't even available through the official documentation on docs.python.org. 2. What about link rot and obsolete material? PyMOTW has an active maintainer in Doug Hellman who posts the source as a github project (under the aforementioned permissive license). If these become a problem, either the links can then be dropped from new versions of the documentation, or else the project can be forked by a new maintainer. I would personally hope that if Doug tired of maintaining the project at some point in the future, he would be willing to turn it over to PSF stewardship under the same licensing terms as the rest of the documentation, but that possible scenario isn't an argument against adding the external links for the benefits of users *now*. While I've tried to resist making any argument based on the specifics of *who* Doug is rather than what he's written, people should be aware that we aren't talking about a random person who happened to post some good free information on the internet here: we're talking about the current Communications Officer for the PSF [2]. I can understand his reasons for wanting to maintain personal editorial control over PyMOTW, so linking rather than embedding is the next best option when it comes to serving users' interests. (Note that embedding under the existing CC license would not only be disrespectful of Doug's wishes, it would also cause a real redistribution licensing problem for the many commercial entities that pass the Python documentation along to their users, including Linux vendors, IDE vendors, etc) Cheers, Nick. [1] http://www.python.org/doc/ (bottom of the page) [2] http://www.python.org/psf/members/ -- Nick Coghlan   |   ncoghlan@gmail.com   |   Brisbane, Australia

On Sun, Mar 20, 2011 at 7:23 PM, Terry Reedy <tjreedy@udel.edu> wrote:

...

these become a problem, either the links can then be dropped from new versions of the documentation,

Since there will be no new 2.x versions I find this confusing.

Everything I have said in this thread is based on the (to me, obvious) presumption that the current PyMOTW would be linked only from the 2.7 documentation (and there *will* be plenty of maintenance releases that will pick up that change). Once a Python 3 version of PyMOTW is available (which shouldn't take *too* long, given the executable nature of the examples), then similar links could be added to the 3.x documentation. Another idea that occurred to me this evening to help mitigate any concerns regarding stale links to an external site in the bundled documentation (e.g. source builds, CHM files) is to pipe the PyMOTW references through a redirector on python.org. Those links could then remain stable even if the PyMOTW files are moved to a new domain at some point in the future. Cheers, Nick. -- Nick Coghlan   |   ncoghlan@gmail.com   |   Brisbane, Australia

On Sun, Mar 20, 2011 at 2:33 AM, Nick Coghlan <ncoghlan@gmail.com> wrote:

.. but can anyone cite a case where PyMOTW is actually *that* wrong?

Didn't I do it in my first reply to this thread? """ .. I visited a page on the module that I am well familiar with, the datetime module. On a cursory review, I don't think PyMOTW adds much to an already rather extensive docs.python.org documentation. One section, "Combining Dates and Times" struck me as not very clear. It starts with an example: print 'Now :', datetime.datetime.now() print 'Today :', datetime.datetime.today() .. $ python datetime_datetime.py Now : 2008-03-15 22:58:14.770074 Today : 2008-03-15 22:58:14.779804 .. Why would someone interested in combining dates and time would like to know two subtly different functions that return current time in a datetime object? The surrounding text does not explain the difference between datetime.now() and datetime.today(). Overall I am -1 on linking PyMOTW datetime page from datetime documentation. """ Note that my "-1" is limited to linking from the datetime module documentation. Having not read any other PyMOTW pages, I have no basis to form an opinion on whether links to those other pages will improve reader experience. The datetime module may be unique because it actually suffers from too much documentation rather than the lack of it. The official datetime documentation and its PyMOTW page are not complimentary. They cover the same material in different styles. Some users are better off reading just PyMOTW, others may prefer the official doc. I don't really see much incremental value from reading both. Note that it looks like PyMOTW author intended his pages to be self-contained rather than a compliment to the official doc. There is no link from PyMOTW datetime page to http://docs.python.org/library/datetime.html. PS: The PyMOTW datetime page is at http://blog.doughellmann.com/2008/03/pymotw-datetime.html. PPS: I don't think the PyMOTW datetime page is current for 2.7. This page seems to be 3 years old and 2.7 have seen a few additions to the datetime module.

On Mar 20, 2011, at 11:42 AM, Alexander Belopolsky wrote:

On Sun, Mar 20, 2011 at 2:33 AM, Nick Coghlan <ncoghlan@gmail.com> wrote:

...

.. but can anyone cite a case where PyMOTW is actually *that* wrong?

Didn't I do it in my first reply to this thread?

""" .. I visited a page on the module that I am well familiar with, the datetime module. On a cursory review, I don't think PyMOTW adds much to an already rather extensive docs.python.org documentation. One section, "Combining Dates and Times" struck me as not very clear. It starts with an example:

print 'Now :', datetime.datetime.now() print 'Today :', datetime.datetime.today() ..

$ python datetime_datetime.py Now : 2008-03-15 22:58:14.770074 Today : 2008-03-15 22:58:14.779804 ..

Why would someone interested in combining dates and time would like to know two subtly different functions that return current time in a datetime object? The surrounding text does not explain the difference between datetime.now() and datetime.today().

Overall I am -1 on linking PyMOTW datetime page from datetime documentation. """

Note that my "-1" is limited to linking from the datetime module documentation. Having not read any other PyMOTW pages, I have no basis to form an opinion on whether links to those other pages will improve reader experience.

The datetime module may be unique because it actually suffers from too much documentation rather than the lack of it. The official datetime documentation and its PyMOTW page are not complimentary. They cover the same material in different styles. Some users are better off reading just PyMOTW, others may prefer the official doc. I don't really see much incremental value from reading both.

Note that it looks like PyMOTW author intended his pages to be self-contained rather than a compliment to the official doc. There is no link from PyMOTW datetime page to http://docs.python.org/library/datetime.html.

PS: The PyMOTW datetime page is at http://blog.doughellmann.com/2008/03/pymotw-datetime.html.

PPS: I don't think the PyMOTW datetime page is current for 2.7. This page seems to be 3 years old and 2.7 have seen a few additions to the datetime module.

The canonical version of that page is http://www.doughellmann.com/PyMOTW/datetime/. You will find a link to the stdlib docs, as well as some other useful date-related docs and tools, in the "See also" section at the bottom of that page. If you are going to review the content page by page, please look at the versions of the articles under http://www.doughellmann.com/PyMOTW/ Doug

On Sun, Mar 20, 2011 at 12:07 PM, Alexander Belopolsky <alexander.belopolsky@gmail.com> wrote: ..

 Let me review that page more thoroughly.

I'll focus on criticism even though, overall I find the PyMOTD:datetime page a good introduction to the datetime module. I would recommend this page to beginners, but probably *before* the official docs, so a "see also" link is probably not the right way to link PyMOTD pages. Maybe a link to PyMOTD should be added to the main docs.python.org page. Now, what I don't like about PyMOTD:datetime. 1. Order of presentation: time, date, timedelta, datetime, tzinfo. For an introductory article, I would start with date, then do datetime and timedelta. The time objects are not that useful and aware time objects are rather exotic since time method of datetime strips tzinfo. The first example exposes the reader to the tzinfo attribute of time objects without any explanation. 2. In the first paragraph of the "Times" section: "the default of 0 is unlikely to be what you want" - this is somewhat confusing given that the following example is using the default value for microseconds and 01:02:03 time which is equally unlikely to be what someone wants in a typical application. It looks like the "unlikely" comment was about time() with no arguments and default of 0 for all components. It would be better to use a "likely" example, preferably in the PM range so that the reader is gently introduced to the 24-hour system. For example, 5pm as a typical office closing hour would be good, or say 5:45 pm as a realistic train departure time. Any of these would be better that a purely artificial time(1, 2, 3). 3. The min/max/resolution example. I don't think I ever used these attributes of the time class. Resolution is occasionally useful, but mostly for timedelta. Similarly, min and max of the other types reflect some non-obvious design choice, but for time, it is just the 24 hours in a day range. 4. The error passing float to microsecond argument example. Why are microseconds singled out? Similar error would result from passing float for hours, minutes or seconds. An example of how to generate and catch type error is not very helpful in an document about the datetime module. I would much rather see an example of how to convert fractional hours, minutes or seconds to datetime objects using timedelta constructor. (This is another case where dealing with time type is awkward because it does not support arithmetics. Another reason not to pick it as the first type to cover.) 5. The now() and today() example that I criticized in my earlier post is still present in the "canonical" version. The text preceding that example says: "there are several convenient class methods to make creating datetime instances from other common values." However, this does not match the examples which immediately follow. I would expect to see datetime.fromtimestamp() in that section, but for some reason it is covered in the "Dates" section instead. 6. In the revised "Time Zones" section, the author toned down his criticism of the approach taken by module developers. In the 2008 version, he called the tzinfo situation "ironic." Still, this section does not provide any useful examples. At the very least, it should give an example of passing tzinfo to datetime.now() to obtain current time in an aware datetime object. For 3.2 such example could use the new timezone type, but for 2.x it would be appropriate to provide an example using either pytz or a sample tzinfo implementation. The datetime module is a difficult area to cover. As I said before, it is likely that the situation with the other modules is different. If maintainers of other modules think that their documentation will benefit from a PyMOTW link, I have no objection to that. I still -1 on adding a PyMOTW:datetime link to the datetime module reference manual. I hope Doug will find my review of his datetime page helpful. I think PyMOTW will similarly benefit from other core developers' reviews as they consider linking PyMOTW to their documentation. However, blindly linking all pages simply because some people find Doug's work overall a better guide to stdlib than the official pages will only confuse readers. The reference manual and PyMOTW are two different works targeting different audiences. PyMOTW is more like a tutorial, trying to concisely introduce main features of each module without a claim to be comprehensive. In the reference manual on the other hand we try to be complete in feature coverage and economical in illustrative examples. It is reasonable to expect users to read PyMOTW articles in their entirety while reading entire sections of the reference manual would mean a very boring weekend. This observation makes it hard to find a good place for a PyMOTW? Should it go in the beginning or the end of the reference manual page? In either case, it is unlikely to be noticed by a typical user who goes directly to the class or method documentation through some kind of search.

On Sun, Mar 20, 2011 at 5:11 PM, Nick Coghlan <ncoghlan@gmail.com> wrote:

On Mon, Mar 21, 2011 at 4:18 AM, Alexander Belopolsky <alexander.belopolsky@gmail.com> wrote:

...

The reference manual and PyMOTW are two different works targeting different audiences.  PyMOTW is more like a tutorial, trying to concisely introduce main features of each module without a claim to be comprehensive.   In the reference manual on the other hand we try to be complete in feature coverage and economical in illustrative examples.

You just summarised *exactly* why a bunch of us want to include it in the official documentation (by reference, anyway): so people can read PyMOTW as an introduction, and use the official docs as a reference.

A See Also at the bottom of individual module pages, plus an "External Resources" link on the front page of the docs (as you suggested) would cover that nicely (especially with a pydotorg redirector in place to guarantee link stability).

Cheers, Nick.

What Nick said. You summarized why we want this done in the first place - the narrative/tutorial style works really, really well for a lot of people, non programmers and beginners. They're not API docs, and they're not meant to be. For the record? When I'm dealing with datetime, or logging, or other "bigger" modules - I tend to go to doug's site first to see if I can find a quick bit before I go through the official docs. jesse

On Sun, Mar 20, 2011 at 2:18 PM, Alexander Belopolsky < alexander.belopolsky@gmail.com> wrote:

On Sun, Mar 20, 2011 at 12:07 PM, Alexander Belopolsky <alexander.belopolsky@gmail.com> wrote: ..

...

Let me review that page more thoroughly.

I'll focus on criticism even though, overall I find the PyMOTD:datetime page a good introduction to the datetime module. I would recommend this page to beginners, but probably *before* the official docs, so a "see also" link is probably not the right way to link PyMOTD pages. Maybe a link to PyMOTD should be added to the main docs.python.org page.

Now, what I don't like about PyMOTD:datetime.

1. Order of presentation: time, date, timedelta, datetime, tzinfo. For an introductory article, I would start with date, then do datetime and timedelta. The time objects are not that useful and aware time objects are rather exotic since time method of datetime strips tzinfo. The first example exposes the reader to the tzinfo attribute of time objects without any explanation.

This is all just so ridiculous. If we're so sensitive to some (btw, arbitrary and subjective in this case) ordering, then why is the official stdlib documentation *not* in this order? Why does the datetime module documentation not cover the actual class for which it is named until after things like timedelta? Why does the document start out by covering constants, follow with available types, then shove in a few completely random miscellaneous statements, and dive into the timedelta object? Is this *really* the best way to introduce the datetime module to someone new to the language? How does the standard documentation hold up to the criteria you're using to critique the PyMOTW documentation? Why is there so much energy put forth to squash a good idea and almost none toward doing the actual work to improve what's already there? If the standard documentation was really that awesome, this discussion may never have come up. Let's think about the bar we've set in the standard library docs, and consider how PyMOTW contributes to raising that bar. The standard lib documentation is *not* all that awesome, *especially* for newcomers, in large part because large swaths of it are probably autogenerated direct from the source code. It therefore lacks almost any notion of human tone or personality, is completely unopinionated, dry, and in plenty of cases fails to document a given module completely. Where it does *document* completely, it doesn't necessarily provide examples illustrating the complete set of functionality provided by the module. Neither does PyMOTW, but the point is that they're complementary resources. PyMOTW provides a "feel" for a module. The stdlib docs are really designed to be a reference. If they *weren't* designed to strictly be a reference, then they need more work than I thought. Anyway, this critique is completely orthogonal to the issue at hand. What I think we're after here is: 1. Adding value over and above the standard library documentation 2. Targeting an audience (newbies or new-to-Python) that is just about completely ignored by the standard library documentation. Do the PyMOTW documents, on the whole, add value over and above the standard library documentation? I have yet to hear any compelling argument that they don't. Doug's existing 2.7-based work should be linked in the Python 2.7 documentation. This is not to say that this should happen to the exclusion of any other existing or future material by other authors. We already link to other external material, so it's not like there's no precedent for this. There's no precedent for the pervasiveness of the links being proposed, but that's because there's no precedent for a single work that so closely mirrors and deliberately targets full coverage of every module in the standard library. Does the proposal represent perfection? Absolutely not. Perfection would involve an overhaul of the existing documentation, which in plenty of places sucks no matter what your experience with Python or programming in general. But even if that were to occur, I think Doug's work would still add value. I move to stop playing Monday morning quarterback with Doug's work. There's no work that couldn't be better based on anyone's subjective idea of what "better" means. I've been in the position in the past of editing Doug's work. I'm currently reviewing Doug's book. I've been a long-time reader and user of both the standard library docs and PyMOTW. I'm working on a book for O'Reilly *right now* that will compete *directly* with Doug's book. I have the capability and, some might speculate, a motive to rip Doug's work apart. Doing so, in my opinion, has no merit, hinders efforts to improve the overall experience of those new to the language, and attempts to hide a perfectly worthy collection of work from those in need. Further, when these people come to stackoverflow and say that they have a question not answered by the standard docs, we're all going to point them to PyMOTW anyway. Doug's work is solid. Not perfect -- solid. It approaches topics in a reasonable way, provides a bit more humanistic tone and personality, covers the topics accurately, and does so for the entire standard library. If I weren't knee-deep in a book project of my own, I'd be happy to make this task my first commit ever to the Python documentation tree. If this thread continues until July, I just might be able to do that ;-) brian

2. In the first paragraph of the "Times" section: "the default of 0 is unlikely to be what you want" - this is somewhat confusing given that the following example is using the default value for microseconds and 01:02:03 time which is equally unlikely to be what someone wants in a typical application. It looks like the "unlikely" comment was about time() with no arguments and default of 0 for all components. It would be better to use a "likely" example, preferably in the PM range so that the reader is gently introduced to the 24-hour system. For example, 5pm as a typical office closing hour would be good, or say 5:45 pm as a realistic train departure time. Any of these would be better that a purely artificial time(1, 2, 3).

3. The min/max/resolution example. I don't think I ever used these attributes of the time class. Resolution is occasionally useful, but mostly for timedelta. Similarly, min and max of the other types reflect some non-obvious design choice, but for time, it is just the 24 hours in a day range.

4. The error passing float to microsecond argument example. Why are microseconds singled out? Similar error would result from passing float for hours, minutes or seconds. An example of how to generate and catch type error is not very helpful in an document about the datetime module. I would much rather see an example of how to convert fractional hours, minutes or seconds to datetime objects using timedelta constructor. (This is another case where dealing with time type is awkward because it does not support arithmetics. Another reason not to pick it as the first type to cover.)

5. The now() and today() example that I criticized in my earlier post is still present in the "canonical" version. The text preceding that example says: "there are several convenient class methods to make creating datetime instances from other common values." However, this does not match the examples which immediately follow. I would expect to see datetime.fromtimestamp() in that section, but for some reason it is covered in the "Dates" section instead.

6. In the revised "Time Zones" section, the author toned down his criticism of the approach taken by module developers. In the 2008 version, he called the tzinfo situation "ironic." Still, this section does not provide any useful examples. At the very least, it should give an example of passing tzinfo to datetime.now() to obtain current time in an aware datetime object. For 3.2 such example could use the new timezone type, but for 2.x it would be appropriate to provide an example using either pytz or a sample tzinfo implementation.

The datetime module is a difficult area to cover. As I said before, it is likely that the situation with the other modules is different. If maintainers of other modules think that their documentation will benefit from a PyMOTW link, I have no objection to that. I still -1 on adding a PyMOTW:datetime link to the datetime module reference manual.

I hope Doug will find my review of his datetime page helpful. I think PyMOTW will similarly benefit from other core developers' reviews as they consider linking PyMOTW to their documentation. However, blindly linking all pages simply because some people find Doug's work overall a better guide to stdlib than the official pages will only confuse readers. The reference manual and PyMOTW are two different works targeting different audiences. PyMOTW is more like a tutorial, trying to concisely introduce main features of each module without a claim to be comprehensive. In the reference manual on the other hand we try to be complete in feature coverage and economical in illustrative examples.

It is reasonable to expect users to read PyMOTW articles in their entirety while reading entire sections of the reference manual would mean a very boring weekend. This observation makes it hard to find a good place for a PyMOTW? Should it go in the beginning or the end of the reference manual page? In either case, it is unlikely to be noticed by a typical user who goes directly to the class or method documentation through some kind of search. _______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas

-- Brian K. Jones My Blog http://www.protocolostomy.com Follow me http://twitter.com/bkjones

On Sun, Mar 20, 2011 at 9:18 PM, Brian Jones <bkjones@gmail.com> wrote: ..

This is all just so ridiculous. If we're so sensitive to some (btw, arbitrary and subjective in this case) ordering, then why is the official stdlib documentation *not* in this order?

One possible explanation is that it was not written by me. :-) Seriously, official datetime documentation can be improved. Order of presentation is one area of improvement. Note that the order in "Available Types" is different from the order of per-type sections. I would certainly make sense to use the same somehow logical order for both. However, for a reference documentation that is not designed to be read sequentially, the order of presentation is not as important as in a module overview or a tutorial.

Why does the datetime module documentation not cover the actual class for which it is named until after things like timedelta?

I don't know. In the summary section the timedelta is listed after datetime. On the other hand, covering timedelta first, is likely to reduce the number of back-references because timedelta arithmetics is self-contained while datetime arithmetic properties cannot be described without introducing timedelta.

Why does the document start out by covering constants, follow with available types, then shove in a few completely random miscellaneous statements, and dive into the timedelta object?

Constants followed by types is a fairly standard order in stdlib documentation. I think we mostly follow the order in which things are defined in code which in turn usually organized so that things are defined before they are referenced. What "random miscellaneous statements" do you refer to? Documentation patches are always welcome.

Is this *really* the best way to introduce the datetime module to someone new to the language?

No. Reference manual is *not* the best way to introduce anything to someone new to the language. We do try to make the reference manual novice friendly as long as it does not conflict with completeness or accuracy.

How does the standard documentation hold up to the criteria you're using to critique the PyMOTW documentation?

I would not use the same criteria for the two works. They serve different purposes.

Why is there so much energy put forth to squash a good idea and almost none toward doing the actual work to improve what's already there?

Why do you think adding a link to official module documentation pointing to a document that has not been reviewed by module maintainers is a good idea? ..

Do the PyMOTW documents, on the whole, add value over and above the standard library documentation? I have yet to hear any compelling argument that they don't.

I don't know about "on the whole." I have specific issues with the datetime article. Other modules' maintainers may or may not have issues with the specific PyMOTW articles. Why does this need to be all or nothing? Note that we don't cross-reference official tutorial sections from Language Reference. PyMOTW looks like the missing Library Tutorial. I don't object to featuring it as such on the main documentation page.

On Fri, Mar 18, 2011 at 5:06 PM, Terry Reedy <tjreedy@udel.edu> wrote:

I actually think that would be fine on wiki pages where any python writer can add links to their stuff. I already suggested that there could be one for module. There could also be some for statements and builtins.

It might be nice if at the bottom of the official docs there a link to a wiki version of the docs and in the wiki version there were external links to things like MOTW. Of course, the wiki would eventually have links to resources that were OK but not great, but I don't think that would be a problem as long as each page of the wiki has a link to its equivalent in the official docs. The idea would be if I wanted to know about module X, first I look in the official docs. If I find that my question wasn't answered, or I just want more, I could switch over to the wiki to see if anything different is over there and then check out the list of external links. I'm not sure if it would be maintainable or not, but would it be that bad to try as an experiment? If after six months it doesn't seem to have worked, take the link out of the official docs and shut the wiki down. No harm in trying something out, right? -- Carl Johnson

On Mar 17, 2011, at 7:51 PM, Terry Reedy wrote:

On 3/17/2011 7:19 PM, Senthil Kumaran wrote:

...

On Wed, Mar 16, 2011 at 05:35:41PM -0400, Doug Hellmann wrote:

...

...

As I told Doug during Pycon, I think it would be a good idea to link his PyMOTW pages to our modules documentation in docs.python.org so people have more examples etc.

Various people have written various docs showing Python by example. I do not think any one should be singled out in the docs.

I can certainly appreciate that position.

On the other hand, the wiki could have a PythonByExample page (or pages) with links to various resources.

If someone were ambitious, there could even be a page for each builtin class and each stdlib module, each with multiple links and examples.

-- Terry Jan Reedy

_______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas

On Sun, Mar 20, 2011 at 8:19 AM, Alexander Belopolsky <alexander.belopolsky@gmail.com> wrote:

I am sure there are instances when a PyMOTW is a valuable addition to the "official" module documentation, but I think a decision to link it should be made on a case by case basis by someone who would review both the official and PyMOTW pages and decide that a link to PyMOTW adds to the quality of documentation for a given module.

I think this is another case where "perfect is the enemy of good", though. Perfect: a broader "Python Documentation Index" that collects and curates links to documentation of various Python topics, including the standard library modules Perfect: a case-by-case comparison of the stdlib docs and the PyMOTW docs for each module by a module expert, deciding whether or not to link to the PyMOTW version in a "See Also" link Good: just link them all as part of the module documentation generation process. Some people may understand the stdlib docs better, some may understand PyMOTW better, but providing ready access to both is unlikely to actively *confuse* anyone that wasn't already lost. Cheers, Nick. -- Nick Coghlan   |   ncoghlan@gmail.com   |   Brisbane, Australia

On Sun, Mar 20, 2011 at 8:47 AM, Raymond Hettinger <raymond.hettinger@gmail.com> wrote:

P.S.  I really like Doug's collected articles and find them to be a pleasure to read; however, the articles have a introductory survey quality to them and do not purport to be up-to-date or to be complete (many methods, flags, arguments, classes, are omitted), so I'm not sure how well they would serve as primary documentation.

It's precisely their survey quality that makes them a potentially useful supplement to the existing documentation. Jacob Kaplan-Moss gave an excellent talk at PyCon regarding the multiple levels at which documentation needs to work. Most of the module documentation in the Library Reference dives right in to API level reference details, which can be impenetrable for users trying to get a feel for an unfamiliar module. Not all of our documentation is like that (plenty of people will have heard me talking up the new logging tutorials Vinay added for 3.2), but quite a lot of it is. Systematically linking to PyMOTW would be about providing new users with a resource that may help them come to grips with a module when using it for the first time, helping to fill the gaps where our own documentation fails to cover this aspect. All respect to Doug, while his opinion as the PyMOTW author is certainly relevant, this question is about whether or not such links would make the Library Reference documentation better for newcomers, so the final decision certainly isn't his (if the final call belongs to anyone other than Guido, it would be Georg). Cheers, Nick. -- Nick Coghlan   |   ncoghlan@gmail.com   |   Brisbane, Australia