Python doc problem example: gzip module (reprise)
fileToCompress = open('finalcallejon.mb')
fileToStr = fileToCompress.read()
import gzip
fileZipped = gzip.GzipFile('finalcallejon.mb.gz', 'wb', 9)
fileZipped.write(fileToStr)
fileZipped.close()
this may help you in
http://mail.python.org/pipermail/python-list/2005-November/349718.html
have a nice day Emoticon1.gif--
http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
Mike Meyer wrote: Xah Lee [EMAIL PROTECTED] writes: Newsgroups: comp.lang.perl.misc PS: I won't cross-post as I'm not subscribed to the Python group. Very wisely done. Then from Xah Lee, we get; I have cross posted it for you. Proving once again that he's stupider than spam. Please help google find him that way by adding this link to your pages: a href=http://xahlee.org/;stupider than spam/a thank you, mike Ah, but is he stupider spam, spam, spam, spam, bacon, eggs, and spam? -- http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
Newsgroups: comp.lang.perl.misc From: Veli-Pekka Tätilä Date: Sat, 5 Nov 2005 17:25:35 +0200 Subject: Re: Python doc problem example: gzip module (reprise) Xah Lee wrote: Today i need to use Python to compress/decompress gzip files. snip However, scanning the doc after 20 seconds there's no single example showing how it is used. jargons of Class, Constructor, Object etc are thrown together with presumption of reader's expertise of IO programing in Python snip I se the problem now. Perl usually doesn't have that kind of trouble as there are plenty of example snippets and the synopsis part even before the description. But if you want to bash the Python docs, I'd like to mention that they are pretty inaccessible and unmanagable with speech. Here's my post about it in comp.langh.python: URL: http://tinyurl.com/dfrb7 (or search Google Groups with vtatila python) Though I've carefully explain the problems and provided a number of solutions, no-one has replied yet. I reckon that, ether people don't know what I'm talking about accessibility being such a nieche topic still, or else my explanation is all too elaborate or just heavy to read through. Well, I've tried. Yet another reason to stay with Perl. Whose docs are, by the way, very accessible in general. PS: I won't cross-post as I'm not subscribed to the Python group. --- Thank you Veli-Pekka Tätilä for your thoughtful reply. I have cross posted it for you. Xah [EMAIL PROTECTED] ∑ http://xahlee.org/ -- http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
Xah Lee [EMAIL PROTECTED] writes: Newsgroups: comp.lang.perl.misc PS: I won't cross-post as I'm not subscribed to the Python group. Very wisely done. Then from Xah Lee, we get; I have cross posted it for you. Proving once again that he's stupider than spam. Please help google find him that way by adding this link to your pages: a href=http://xahlee.org/;stupider than spam/a thank you, mike -- Mike Meyer [EMAIL PROTECTED] http://www.mired.org/home/mwm/ Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
(gulp! red-in-the-face) yes Steve, I meant gist, sorry if I offended anyone, specially Fredrik since I was referring to the 'substance' of his post...certainly not as if it were a 'joke' . Jean-Marc -- http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
On 05 Nov 2005 19:19:29 -0800, Paul Rubin http://[EMAIL PROTECTED] wrote: Mike Meyer [EMAIL PROTECTED] writes: It's only -because- of those licenses that there's any reason not to bundle. Actually, there are other reasons, just as there are reasons besides licensing for not simply including third party libraries into the standard library. I'm not talking about 3rd party libraries, I'm talking about 3rd party documentation for modules that are already in the Python standard library. For example, if someone wrote a good Tkinter manual that were licensed in a way that the PSF could drop it into the Python distro, then PSF should certainly consider including it. The same goes for good docs about urllib2, or various other modules that currently have lousy docs. I found http://infohost.nmt.edu/tcc/help/lang/python/tkinter.html to be a pretty good tutorial, though incomplete as a reference. Thanks for the URL, but that's just a short list of links, most of which I've already seen. Sorry, I meant: http://infohost.nmt.edu/tcc/help/pubs/tkinter/ (html) http://www.nmt.edu/tcc/help/pubs/tkinter.pdf (pdf of same) You've probably seen this manual already. If not, I'll second the recommendation for the pdf. It's not complete, but it's quite useful and pretty easy to use. Hm, seems to be updated since I downloaded a copy, guess I'll grab the newest ;-) Hm2, it doubled in size! The creation dates are *** FILE tkinter.pdf *** /CreationDate (D:20030416170500) *** FILE tkinter2.pdf *** /CreationDate (D:20050803114234) So I guess it could double in 2 years 4 months. I'll have to look into it. Regards, Bengt Richter -- http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
Sorry but I take exception on this subject. I still think Fredrik's Intro to Tkinter is still more usable ... Grayson's book uses PMW extensively, and a lot is about specific widgets of that library. This actually brings us back to the jest of F. previous post, that documentation is question of multiple source reference, and yes that you have to work the field (Google search, newgroups, cookbooks, source-code, et al) a little bit to get some information. In time, one goes from newbie to casual-user, to regular-user and createds his own setof useful references ... Simple ready-to-eat recipes are just that - fast-food for the mind! (Ok some of it is delicious, even nourishing ;-) ) -- http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
On Sun, 06 Nov 2005 04:28:35 -0800, jmdeschamps wrote: This actually brings us back to the jest of F. previous post, I didn't think it was very funny... Unless you meant the *gist* of Fredrik's post. -- Steven. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
Rick Wotnaz [EMAIL PROTECTED] writes: [snip] I've managed to avoid reading Xah Lee's diatribes for the most part. Since you included the *WHOLE THING* in your post, I had an opportunity to see what he had to say, and for once I agree with some of it. That's fine, but if you're going to post a followup, could you please limit it to comp.lang.python? There's no hope of getting Xah Lee to stop posting his rants to irrelevant newsgroups (that's what killfiles are for), but I doubt that many readers of comp.lang.perl.misc really want to read about Python documentation -- if they do, they can always read comp.lang.python. -- Keith Thompson (The_Other_Keith) [EMAIL PROTECTED] http://www.ghoti.net/~kst San Diego Supercomputer Center * http://users.sdsc.edu/~kst We must do something. This is something. Therefore, we must do this. -- http://mail.python.org/mailman/listinfo/python-list
Python doc problem example: gzip module (reprise)
Python Doc Problem Example: gzip Xah Lee, 20050831 Today i need to use Python to compress/decompress gzip files. Since i've read the official Python tutorial 8 months ago, have spent 30 minutes with Python 3 times a week since, have 14 years of computing experience, 8 years in mathematical computing and 4 years in unix admin and perl, i have quickly found the official doc: http://python.org/doc/2.4.1/lib/module-gzip.html I'd imagine it being a function something like: fileContent = GzipFile(filePath, comprress/decompress) However, scanning the doc after 20 seconds there's no single example showing how it is used. Instead, the doc starts with some arcane info about compatibility with some other compression module and other software. Then it talks in a very haphazard way with confused writing about the main function GzipFile. No perspectives whatsoever about using it to solve a problem nor a concrete description of how to use it. Instead, jargons of Class, Constructor, Object etc are thrown together with presumption of reader's expertise of IO programing in Python and gzip compression arcana. After no understanding, and being not a Python expert, i wanted to read about file objects but there's no link. After locating the file object's doc page: http://python.org/doc/2.4.1/lib/bltin-file-objects.html, but itself is written and organized in a very unhelpful way. Here's the detail of the problems of its documentation. It starts with: «The data compression provided by the zlib module is compatible with that used by the GNU compression program gzip. Accordingly, the gzip module provides the GzipFile class to read and write gzip-format files, automatically compressing or decompressing the data so it looks like an ordinary file object. Note that additional file formats which can be decompressed by the gzip and gunzip programs, such as those produced by compress and pack, are not supported by this module.» This intro paragraph is about 3 things: (1) the purpose of this gzip module. (2) its relation with zlib module. (3) A gratuitous arcana about gzip program's support of “compress and pack” software being not supported by Python's gzip module. Necessarily mentioned because how the writing in this paragraph is phrased. The writing itself is a jumble. Of the people using the gzip module, vast majority really just need to decompress a gzip file. They don't need to know (2) and (3) in a preamble. The worst aspect here is the jumbled writing. «class GzipFile( [filename[, mode[, compresslevel[, fileobj) Constructor for the GzipFile class, which simulates most of the methods of a file object, with the exception of the readinto() and truncate() methods. At least one of fileobj and filename must be given a non-trivial value. The new class instance is based on fileobj, which can be a regular file, a StringIO object, or any other object which simulates a file. It defaults to None, in which case filename is opened to provide a file object.» This paragraph assumes that readers are thoroughly familiar with Python's File Objects and its methods. The writing is haphazard and extremely confusive. Instead of explicitness and clarity, it tries to convey its meanings by side effects. • The words “simulate” are usd twice inanely. The sentence “...Gzipfile class, which simulates...” is better said by “Gzipfile is modeled after Python's File Objects class.” • The intention to state that it has all Python's File Object methods except two of them, is ambiguous phrased. It is as if to say all methods exists, except that two of them works differently. • The used of the word “non-trivial value” is inane. What does a non-trivial value mean here? Does “non-trivial value” have specific meaning in Python? Or, is it meant with generic English interpretation? If the latter, then what does it mean to say: “At least one of fileobj and filename must be given a non-trivial value”? Does it simply mean one of these parameters must be given? • The rest of the paragraph is just incomprehensible. «When fileobj is not None, the filename argument is only used to be included in the gzip file header, which may includes the original filename of the uncompressed file. It defaults to the filename of fileobj, if discernible; otherwise, it defaults to the empty string, and in this case the original filename is not included in the header.» “discernible”? This writing is very confused, and it assumes the reader is familiar with the technical specification of Gzip. «The mode argument can be any of 'r', 'rb', 'a', 'ab', 'w', or 'wb', depending on whether the file will be read or written. The default is the mode of fileobj if discernible; otherwise, the default is 'rb'. If not given, the 'b' flag will be added to the mode to ensure the file is opened in binary mode for cross-platform portability.» “discernible”? Again, familiarity with the working of Python's file object is implicitly assumed. For people who do not have expertise
Re: Python doc problem example: gzip module (reprise)
Xah Lee wrote: Python Doc Problem Example: gzip Xah Lee, 20050831 Today i need to use Python to compress/decompress gzip files. Since i've read the official Python tutorial 8 months ago, have spent 30 minutes with Python 3 times a week since, have 14 years of computing experience, 8 years in mathematical computing and 4 years in unix admin and perl, i have quickly found the official doc: http://python.org/doc/2.4.1/lib/module-gzip.html I'd imagine it being a function something like: fileContent = GzipFile(filePath, comprress/decompress) However, scanning the doc after 20 seconds there's no single example showing how it is used. Instead, the doc starts with some arcane info about compatibility with some other compression module and other software. Then it talks in a very haphazard way with confused writing about the main function GzipFile. No perspectives whatsoever about using it to solve a problem nor a concrete description of how to use it. Instead, jargons of Class, Constructor, Object etc are thrown together with presumption of reader's expertise of IO programing in Python and gzip compression arcana. After no understanding, and being not a Python expert, i wanted to read about file objects but there's no link. After locating the file object's doc page: http://python.org/doc/2.4.1/lib/bltin-file-objects.html, but itself is written and organized in a very unhelpful way. Here's the detail of the problems of its documentation. It starts with: «The data compression provided by the zlib module is compatible with that used by the GNU compression program gzip. Accordingly, the gzip module provides the GzipFile class to read and write gzip-format files, automatically compressing or decompressing the data so it looks like an ordinary file object. Note that additional file formats which can be decompressed by the gzip and gunzip programs, such as those produced by compress and pack, are not supported by this module.» This intro paragraph is about 3 things: (1) the purpose of this gzip module. (2) its relation with zlib module. (3) A gratuitous arcana about gzip program's support of “compress and pack” software being not supported by Python's gzip module. Necessarily mentioned because how the writing in this paragraph is phrased. The writing itself is a jumble. Of the people using the gzip module, vast majority really just need to decompress a gzip file. They don't need to know (2) and (3) in a preamble. The worst aspect here is the jumbled writing. «class GzipFile( [filename[, mode[, compresslevel[, fileobj) Constructor for the GzipFile class, which simulates most of the methods of a file object, with the exception of the readinto() and truncate() methods. At least one of fileobj and filename must be given a non-trivial value. The new class instance is based on fileobj, which can be a regular file, a StringIO object, or any other object which simulates a file. It defaults to None, in which case filename is opened to provide a file object.» This paragraph assumes that readers are thoroughly familiar with Python's File Objects and its methods. The writing is haphazard and extremely confusive. Instead of explicitness and clarity, it tries to convey its meanings by side effects. • The words “simulate” are usd twice inanely. The sentence “...Gzipfile class, which simulates...” is better said by “Gzipfile is modeled after Python's File Objects class.” • The intention to state that it has all Python's File Object methods except two of them, is ambiguous phrased. It is as if to say all methods exists, except that two of them works differently. • The used of the word “non-trivial value” is inane. What does a non-trivial value mean here? Does “non-trivial value” have specific meaning in Python? Or, is it meant with generic English interpretation? If the latter, then what does it mean to say: “At least one of fileobj and filename must be given a non-trivial value”? Does it simply mean one of these parameters must be given? • The rest of the paragraph is just incomprehensible. «When fileobj is not None, the filename argument is only used to be included in the gzip file header, which may includes the original filename of the uncompressed file. It defaults to the filename of fileobj, if discernible; otherwise, it defaults to the empty string, and in this case the original filename is not included in the header.» “discernible”? This writing is very confused, and it assumes the reader is familiar with the technical specification of Gzip. «The mode argument can be any of 'r', 'rb', 'a', 'ab', 'w', or 'wb', depending on whether the file will be read or written. The default is the mode of fileobj if discernible; otherwise, the default is 'rb'. If not given, the 'b' flag will be added to the mode to ensure the file is opened in binary mode for cross-platform portability.» “discernible”? Again, familiarity with
Re: Python doc problem example: gzip module (reprise)
Xah Lee wrote: i've read the official Python tutorial 8 months ago, have spent 30 minutes with Python 3 times a week since, have 14 years of computing experience, 8 years in mathematical computing and 4 years in unix admin and perl I can wiggle my ears. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
Gerard Flanagan [EMAIL PROTECTED] wrote in news:[EMAIL PROTECTED]: Xah Lee wrote: Python Doc Problem Example: gzip [...] A quality documentation should be clear, succinct, precise. And, the least it assumes reader's expertise to obtain these qualities, the better it is. Vast majority of programers using this module really just want to compress or decompress a file. They do not need to know any more details about the technicalities of this module nor about the Gzip compression specification. Here's what Python documentation writers should do to improve it: ⢠Rewrite the intro paragraph. Example: âThis module prov ides a simple interface to compress and decompress files using the GNU compression format gzip. For detailed working with gzip format, use the zlib module.â. The âzlib moduleâ phrase should be linked to its documentation. ⢠Near the top of the documentation, add a example of usage. A example is worth a thousand words: # decompressing a file import gzip fileObj = gzip.GzipFile(/Users/joe/war_and_peace.txt.gz, 'rb'); fileContent = fileObj.read() fileObj.close() # compressing a file import gzip fileObj = gzip.GzipFile(/Users/mary/hamlet.txt.gz, 'wb'); fileObj.write(fileContent) fileObj.close() You want to create the world before which you can kneel: this is your ultimate hope and intoxication. Also sprach Zarathustra. I've managed to avoid reading Xah Lee's diatribes for the most part. Since you included the *WHOLE THING* in your post, I had an opportunity to see what he had to say, and for once I agree with some of it. Some of us learn by example; sometimes an example is all we need to use a particular feature (especially one that we don't often have need for). The criticism that the documentation would be improved by adding some model code is valid for *all* documentation, I think, not just Python's. Typically, when someone proposes changes to documentation to an open source project, someone else will come along and remind everyone that it's all volunteer effort, so why shouldn't the one doing the propopsing be the one to make the change? In the case of documentation, that approach would mean that those who have the least idea of how a module works should be the ones to describe it for everyone else, which seems a little backward to me. The examples should come from those who know what they're doing and they should explain what the example is doing -- just the sort of things a casual user wants to learn quickly. Someone is sure to jump in now and point to sample code, which nearly all reasonably major packages include. That's good stuff. With (for example) wxPython, it's the only useful documentation, or rather, it's the only thing that makes the wxWidgets documentation useful. Links to code samples in the documentation would be fine in lieu of snippets of example calls. But there's not enough of either in most documentation. I would love to see examples for essentially every function and method. And not just something that echoes the signature, but some context to show how it might be useful. That would be in the intoxication class of ultimate hopes. In most cases, though, it would be *extremely* helpful for a casual user of that part of the package. -- rzed -- http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
Jeffrey Schwab wrote: Xah Lee wrote: i've read the official Python tutorial 8 months ago, have spent 30 minutes with Python 3 times a week since, have 14 years of computing experience, 8 years in mathematical computing and 4 years in unix admin and perl I can wiggle my ears. Which is almost as good as having spent, um, let's see... a grand total of 52 hours attempting to code in Python! Which is to say roughly one week with a little overtime. I've had a large number of co-op students and junior programmers come on board in a Python/agile group. I've said here before that most of them were able to code reasonably in Python after only about one week, at least enough to contribute and participate. Several took a few weeks to completely abandon their bad habits from other languages (e.g. coding C-style iterate-over-chars-in-a-string loops in Python). Of course, most of them had a basic competence and ability to learn, so maybe for them 52 hours was much more effective than it is for others. Still, 52 hours is nothing... and doing it as 30 minutes, 3 times a week, for 8 months vastly decreases the value of those 52 hours, even if it makes it sound much more impressive. I'm not surprised now at what we keeping seeing here... -Peter -- http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
RW == Rick Wotnaz [EMAIL PROTECTED] writes: RW Someone is sure to jump in now and point to sample code, which RW nearly all reasonably major packages include. That's good RW stuff. With (for example) wxPython, it's the only useful RW documentation, or rather, it's the only thing that makes the RW wxWidgets documentation useful. Links to code samples in the RW documentation would be fine in lieu of snippets of example RW calls. But there's not enough of either in most documentation. This is one of the places where Apple's Cocoa documentation shines: there are frequently snippets of code accompanying more complicated methods, which is nice, but there are a couple dozen small sample programs that demonstrate how to use particular aspects of the framework, available with full source code. RW I would love to see examples for essentially every function RW and method. And not just something that echoes the signature, RW but some context to show how it might be useful. That would be RW in the intoxication class of ultimate hopes. In most cases, RW though, it would be *extremely* helpful for a casual user of RW that part of the package. Well, at some level you have to consider - who is the target audience of the documentation? There's usually a tradeoff involved in that documentation aimed at novice users is usually not useful to advanced users; there's also a ridiculous amount of work involved in making *all* documentation available to all users, and there's usually a better payoff involved in writing documentation that shows novice users how to be intermediate users. To take another example: in Cocoa, there's a well-defined and well-documented approach to memory management, and conventions used consistently throughout the whole Cocoa framework. These conventions could be documented over again for each and every class, but it's a much better use of resources to document them once and to assume in the documentation for each class that the reader is familiar with the conventions. Charlton -- cwilbur at chromatico dot net cwilbur at mac dot com -- http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
Hello NG, I've managed to avoid reading Xah Lee's diatribes for the most part. Since you included the *WHOLE THING* in your post, I had an opportunity to see what he had to say, and for once I agree with some of it. snip I would love to see examples for essentially every function and method. And not just something that echoes the signature, but some context to show how it might be useful. That would be in the intoxication class of ultimate hopes. In most cases, though, it would be *extremely* helpful for a casual user of that part of the package. I tend to agree with you, Rick. I usually don't like Xah's posting behavior, but this time he has done, in my opinion, a constructive criticism (and he didn't even say *fuck* once in the whole post!!!). I am quite a newbie in Python, I usually deal with wxPython that is sometimes not very pythonic, or not enough pythonic. As a newbie (in whatever language you wish), I would like to open the docs about a particular library, class or method and find a small sample application of it. I think many newbies learn by examples. I don't mean to say anything negative about the docs or the docs' authors, but I would imagine that having a simple example of use for all the methods in a class/library would be a nice and valuable improvement for the docs. OTOH, usually by using some simple google-fu, it is easy to find a sample application for a particular method. This is due mainly to the popularity of Python, and its popularity is due to its beauty as a language. Compared to other I learnt in the past, like C++, Fortran and Matlab, I have about 99% less jitters now that I use Python ;-) . Andrea. Imagination Is The Only Weapon In The War Against Reality. http://xoomer.virgilio.it/infinity77 -- http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
Andrea Gavana [EMAIL PROTECTED] writes: I tend to agree with you, Rick. I usually don't like Xah's posting behavior, but this time he has done, in my opinion, a constructive criticism (and he didn't even say *fuck* once in the whole post!!!). I am quite a newbie in Python, I usually deal with wxPython that is sometimes not very pythonic, or not enough pythonic. As a newbie (in whatever language you wish), I would like to open the docs about a particular library, class or method and find a small sample application of it. I think many newbies learn by examples. I don't mean to say anything negative about the docs or the docs' authors, but I would imagine that having a simple example of use for all the methods in a class/library would be a nice and valuable improvement for the docs. The thing is, the library documentation that Xah Lee is complaining about is a *reference document*. It says so right in the title: Python Library Reference. As such, it makes lousy tutorial documentation. Xah correctly points this out, which is akin to pointing out that the sky is not green. Now, if he wanted to call the PSF to task for not providing sufficient tutorial documentation, he might have a point. On the other hand, the PSF has limited resources, and: OTOH, usually by using some simple google-fu, it is easy to find a sample application for a particular method. The Python Cookbook should show up a lot in this search. If other people are providing tutorial documentation, then it's not at clear that the PSF should be duplicating that effort. If they had infinite resources, it's clear they should be providng the documentation Xah Lee wants. It doesn't, so letting third parties provide tutorial documentation is probably the best use of the limited resources that they have available. And, since we're talking about Mr. Lee, let's add the obligatory request that you help google find him by description by adding this link to your page: a href=http://xahlee.org/;stupider than spam/a mike -- Mike Meyer [EMAIL PROTECTED] http://www.mired.org/home/mwm/ Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
Mike Meyer [EMAIL PROTECTED] writes: The thing is, the library documentation that Xah Lee is complaining about is a *reference document*. It says so right in the title: Python Library Reference. As such, it makes lousy tutorial documentation. I'm not sure which particular library Xah Lee was complaining about but lots of the lib docs are awful even as references. The Python Cookbook should show up a lot in this search. If other people are providing tutorial documentation, then it's not at clear that the PSF should be duplicating that effort. It seems to me that since the PSF is so persnickety about code licenses (and that is a good thing), it should be persnickety about documentation licenses too. Lots of FSF documentation projects were undertaken because while there were good docs in existence for whatever it was, there were none that the FSF could include in its distros. It's similarly not so great if Python users have to rely on proprietary docs. Of course the PSF has to prioritize its tasks and some things will necessarily stay far down on the list for quite a while, but they should at least BE on the list. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
Paul Rubin http://[EMAIL PROTECTED] writes: Mike Meyer [EMAIL PROTECTED] writes: The thing is, the library documentation that Xah Lee is complaining about is a *reference document*. It says so right in the title: Python Library Reference. As such, it makes lousy tutorial documentation. I'm not sure which particular library Xah Lee was complaining about but lots of the lib docs are awful even as references. That's true, but Xah Lee's proposed fixes do nothing to address this problem. The Python Cookbook should show up a lot in this search. If other people are providing tutorial documentation, then it's not at clear that the PSF should be duplicating that effort. It seems to me that since the PSF is so persnickety about code licenses (and that is a good thing), it should be persnickety about documentation licenses too. Lots of FSF documentation projects were undertaken because while there were good docs in existence for whatever it was, there were none that the FSF could include in its distros. It's similarly not so great if Python users have to rely on proprietary docs. Of course the PSF has to prioritize its tasks and some things will necessarily stay far down on the list for quite a while, but they should at least BE on the list. To my knowledge the PSF isn't doing anything about including the documentation with their distribution, so they shouldn't care about the licenses. Wanting to bundle a good tutorial for everything in the library might be on the list, but the licenses on third-party tutorials shouldn't matter until you are considering bundling them. In that light, the only major omission I can think of is Tkinter, as the only good docs - tutorial, reference, or otherwise - is the Grayson's book. mike -- Mike Meyer [EMAIL PROTECTED] http://www.mired.org/home/mwm/ Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
Mike Meyer [EMAIL PROTECTED] writes: To my knowledge the PSF isn't doing anything about including the documentation with their distribution, so they shouldn't care about the licenses. Wanting to bundle a good tutorial for everything in the library might be on the list, but the licenses on third-party tutorials shouldn't matter until you are considering bundling them. It's only -because- of those licenses that there's any reason not to bundle. Are there any good Python docs outside of the distro, that are licensed suitably for bundling? If yes, I'd say there's a good case for bundling them. In that light, the only major omission I can think of is Tkinter, as the only good docs - tutorial, reference, or otherwise - is the Grayson's book. I found http://infohost.nmt.edu/tcc/help/lang/python/tkinter.html to be a pretty good tutorial, though incomplete as a reference. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
Paul Rubin http://[EMAIL PROTECTED] writes: To my knowledge the PSF isn't doing anything about including the documentation with their distribution, so they shouldn't care about the licenses. Wanting to bundle a good tutorial for everything in the library might be on the list, but the licenses on third-party tutorials shouldn't matter until you are considering bundling them. It's only -because- of those licenses that there's any reason not to bundle. Actually, there are other reasons, just as there are reasons besides licensing for not simply including third party libraries into the standard library. Most important is the issue of maintenance: is someone going to commit to keeping an added document up to date with the distribution? Bundling out of date documentation is a bad thing. Bundling documentation that is going to be left out of the next release because nobody updated it isn't much better. The author of the documentation is the logical person to do this, but if they wanted the documentation bundled with Python, they probably would have submitted it as a PR (I know that's what I do for OSS projects). In that light, the only major omission I can think of is Tkinter, as the only good docs - tutorial, reference, or otherwise - is the Grayson's book. I found http://infohost.nmt.edu/tcc/help/lang/python/tkinter.html to be a pretty good tutorial, though incomplete as a reference. Thanks for the URL, but that's just a short list of links, most of which I've already seen. mike -- Mike Meyer [EMAIL PROTECTED] http://www.mired.org/home/mwm/ Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
Mike Meyer [EMAIL PROTECTED] writes: It's only -because- of those licenses that there's any reason not to bundle. Actually, there are other reasons, just as there are reasons besides licensing for not simply including third party libraries into the standard library. I'm not talking about 3rd party libraries, I'm talking about 3rd party documentation for modules that are already in the Python standard library. For example, if someone wrote a good Tkinter manual that were licensed in a way that the PSF could drop it into the Python distro, then PSF should certainly consider including it. The same goes for good docs about urllib2, or various other modules that currently have lousy docs. I found http://infohost.nmt.edu/tcc/help/lang/python/tkinter.html to be a pretty good tutorial, though incomplete as a reference. Thanks for the URL, but that's just a short list of links, most of which I've already seen. Sorry, I meant: http://infohost.nmt.edu/tcc/help/pubs/tkinter/ (html) http://www.nmt.edu/tcc/help/pubs/tkinter.pdf (pdf of same) You've probably seen this manual already. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python doc problem example: gzip module (reprise)
Paul Rubin http://[EMAIL PROTECTED] writes: Mike Meyer [EMAIL PROTECTED] writes: It's only -because- of those licenses that there's any reason not to bundle. Actually, there are other reasons, just as there are reasons besides licensing for not simply including third party libraries into the standard library. I'm not talking about 3rd party libraries, I'm talking about 3rd party documentation for modules that are already in the Python standard library. So am I. My point is that many of the considerations as to why you don't simply include a module in the library also apply when it comes to including documentation in the distribution. I gave some examples, including why they were important for *documentation*, but you carefully elided those. For example, if someone wrote a good Tkinter manual that were licensed in a way that the PSF could drop it into the Python distro, then PSF should certainly consider including it. The same goes for good docs about urllib2, or various other modules that currently have lousy docs. The key word is consider. They have to deal with all the issues I pointed out before, of which licensing is just the beginning. Sorry, I meant: http://infohost.nmt.edu/tcc/help/pubs/tkinter/ (html) http://www.nmt.edu/tcc/help/pubs/tkinter.pdf (pdf of same) You've probably seen this manual already. Yes, I have. I still say the only good documentation is Grayson's book. mike -- Mike Meyer [EMAIL PROTECTED] http://www.mired.org/home/mwm/ Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information. -- http://mail.python.org/mailman/listinfo/python-list
