By using this site, you agree to our updated Privacy Policy and our Terms of Use. Manage your Cookies Settings.
435,519 Members | 2,258 Online
Bytes IT Community
+ Ask a Question
Need help? Post your question and get tips & solutions from a community of 435,519 IT Pros & Developers. It's quick & easy.

Python doc problem example: gzip module (reprise)

P: n/a
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 with
working with files using Python, it necessatates the reading of
Python's file objects documentation.

«The compresslevel argument is an integer from 1 to 9 controlling
the level of compression; 1 is fastest and produces the least
compression, and 9 is slowest and produces the most compression. The
default is 9.»

«Calling a GzipFile object's close() method does not close
fileobj, since you might wish to append more material after the
compressed data. This also allows you to pass a StringIO object opened
for writing as fileobj, and retrieve the resulting memory buffer using
the StringIO object's getvalue() method.»

huh? append more material? pass a StringIO? and memory buffer?

Here, expertise in programing with IO is assumed of the reader.
Meanwhile, the writing is not clear about how exactly what it is trying
to say about the close() method.
Suggestions
--------------------------
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 provides 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()

• Add at the beginning of the documentation a explicit statement,
that GzipFile() is modeled after Python's File Objects, and provide a
link to it.

• Rephrase the writing so as to not assume that the reader is
thoroughly familiar with Python's IO. For example, when speaking of the
modes 'r', 'rb', ... add a brief statement on what they mean. This way,
readers may not have to take a extra step to read the page on File
Objects.

• Remove arcane technical details about gzip compression to the
bottom as footnotes.

• General advice on the writing: The goal of writing on this module
is to document its behavior, and effectively indicate how to use it.
Keep this in mind when writing the documentation. Make it clear on what
you are trying to say for each itemized paragraph. Make it precise, but
without over doing it. Assume your readers are familiar with Python
language or gzip compression. For example, what are classes and objects
in Python, and what compressions are, compression levels, file name
suffix convention. However, do not assume that the readers are expert
of Python IO, or gzip specification or compression technology and
software in the industry. If exact technical details or warnings are
necessary, move them to footnotes.
---------------
For a collection of essays on Python's documentation problems, see
bottom of:
http://xahlee.org/perl-python/python.html

Xah
xa*@xahlee.org
http://xahlee.org/

Nov 5 '05 #1
Share this Question
Share on Google+
25 Replies


P: n/a
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. Thesentence
“...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 with
working with files using Python, it necessatates the reading of
Python's file objects documentation.

«The compresslevel argument is an integer from 1 to 9 controlling
the level of compression; 1 is fastest and produces the least
compression, and 9 is slowest and produces the most compression. The
default is 9.»

«Calling a GzipFile object's close() method does not close
fileobj, since you might wish to append more material after the
compressed data. This also allows you to pass a StringIO object opened
for writing as fileobj, and retrieve the resulting memory buffer using
the StringIO object's getvalue() method.»

huh? append more material? pass a StringIO? and memory buffer?

Here, expertise in programing with IO is assumed of the reader.
Meanwhile, the writing is not clear about how exactly what it is trying
to say about the close() method.
Suggestions
--------------------------
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 provides 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 belinked 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()

• Add at the beginning of the documentation a explicit statement,
that GzipFile() is modeled after Python's File Objects, and provide a
link to it.

• Rephrase the writing so as to not assume that the reader is
thoroughly familiar with Python's IO. For example, when speaking of the
modes 'r', 'rb', ... add a brief statement on what they mean. This way,
readers may not have to take a extra step to read the page on File
Objects.

• Remove arcane technical details about gzip compression to the
bottom as footnotes.

• General advice on the writing: The goal of writing on this module
is to document its behavior, and effectively indicate how to use it.
Keep this in mind when writing the documentation. Make it clear on what
you are trying to say for each itemized paragraph. Make it precise, but
without over doing it. Assume your readers are familiar with Python
language or gzip compression. For example, what are classes and objects
in Python, and what compressions are, compression levels, file name
suffix convention. However, do not assume that the readers are expert
of Python IO, or gzip specification or compression technology and
software in the industry. If exact technical details or warnings are
necessary, move them to footnotes.
---------------

Xah
xa*@xahlee.org
http://xahlee.org/


"""
You want to create the world before which you can kneel: this is your
ultimate hope and intoxication.

Also sprach Zarathustra.

"""

--Friedrich Nietzsche, Thus Spoke Zarathustra, 1885
Gerard

Nov 5 '05 #2

P: n/a
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.
Nov 5 '05 #3

P: n/a
"Gerard Flanagan" <gr********@yahoo.co.uk> wrote in
news:11**********************@g44g2000cwa.googlegr oups.com:
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
Nov 5 '05 #4

P: n/a
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
Nov 5 '05 #5

P: n/a
>>>>> "RW" == Rick Wotnaz <de*****@wtf.com> 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
Nov 5 '05 #6

P: n/a
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
Nov 5 '05 #7

P: n/a
"Andrea Gavana" <an***********@tin.it> 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 <mw*@mired.org> http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
Nov 6 '05 #8

P: n/a
Mike Meyer <mw*@mired.org> 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.
Nov 6 '05 #9

P: n/a
Paul Rubin <http://ph****@NOSPAM.invalid> writes:
Mike Meyer <mw*@mired.org> 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 <mw*@mired.org> http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
Nov 6 '05 #10

P: n/a
Mike Meyer <mw*@mired.org> 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/lan...n/tkinter.html

to be a pretty good tutorial, though incomplete as a reference.
Nov 6 '05 #11

P: n/a
Paul Rubin <http://ph****@NOSPAM.invalid> 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/lan...n/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 <mw*@mired.org> http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
Nov 6 '05 #12

P: n/a
Mike Meyer <mw*@mired.org> 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/lan...n/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.
Nov 6 '05 #13

P: n/a
Paul Rubin <http://ph****@NOSPAM.invalid> writes:
Mike Meyer <mw*@mired.org> 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 <mw*@mired.org> http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
Nov 6 '05 #14

P: n/a
Charlton Wilbur wrote:
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.


There is no shortage of code examples for Python modules either,
thanks to people who've worked hard to prepare cookbooks and example
collections. If people began using those instead of complaining about
the library reference or their own inability to use the help()
command, everybody would save a lot of time.

(this would also make it easier for less ignorant "newbies" to find
the examples: when Xah first complained about gzip, googling for
"python gzip example" brought up a full page of examples. If you do
the same search today, you'll still find examples, but 5 of the top 10
hits are references to Xah's problems with the library reference. A
few more rounds, and people will have to start adding -xah to their
Python searches to get quality results.)

</F>

Nov 6 '05 #15

P: n/a
On 05 Nov 2005 19:19:29 -0800, Paul Rubin <http://ph****@NOSPAM.invalid> wrote:
Mike Meyer <mw*@mired.org> 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/lan...n/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
Nov 6 '05 #16

P: n/a
On Sun, 06 Nov 2005 09:31:54 +0100, Fredrik Lundh wrote:
(this would also make it easier for less ignorant "newbies" to find
the examples: when Xah first complained about gzip, googling for
"python gzip example" brought up a full page of examples. If you do
the same search today, you'll still find examples, but 5 of the top 10
hits are references to Xah's problems with the library reference. A
few more rounds, and people will have to start adding -xah to their
Python searches to get quality results.)


People are linking to Xah??? Or he is google-bombing?
--
Steven.

Nov 6 '05 #17

P: n/a
> People are linking to Xah??? Or he is google-bombing?

I guess /F meant the results on google that show this very NG/ML.

Diez
Nov 6 '05 #18

P: n/a
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 ;-) )

Nov 6 '05 #19

P: n/a
jm*********@gmail.com wrote:
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.
while I don't care much about the "since I don't understand the
reference manual, I demand that some experts should rewrite it
for me, for free" line of reasoning, I still think it would be a good
idea to make it easier to navigate the existing material. I wrote
about this back in may:

http://mail.python.org/pipermail/pyt...ay/280751.html
http://mail.python.org/pipermail/pyt...ay/280755.html
http://effbot.org/zone/idea-seealso.htm

but, iirc, only got "wikis rulez" and "enough with that comp.sci crap"
responses.
In time, one goes from newbie to casual-user, to regular-user and
createds his own setof useful references ...


exactly.

</F>

Nov 6 '05 #20

P: n/a
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.

Nov 6 '05 #21

P: n/a
Rick Wotnaz <de*****@wtf.com> 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) ks***@mib.org <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.
Nov 7 '05 #22

P: n/a
(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

Nov 7 '05 #23

P: n/a
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
xa*@xahlee.org
http://xahlee.org/

Nov 8 '05 #24

P: n/a
"Xah Lee" <xa*@xahlee.org> 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 <mw*@mired.org> http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
Nov 8 '05 #25

P: n/a
Mike Meyer wrote:
"Xah Lee" <xa*@xahlee.org> 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?
Nov 9 '05 #26

This discussion thread is closed

Replies have been disabled for this discussion.