Python doc problem example: gzip module (reprise)

Discussion in 'Python' started by Xah Lee, Nov 5, 2005.

  1. Xah Lee

    Xah Lee Guest

    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

    ∑ http://xahlee.org/
     
    Xah Lee, Nov 5, 2005
    #1
    1. Advertising

  2. 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 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.
    > ---------------
    >
    > Xah
    >
    > ∑ 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
     
    Gerard Flanagan, Nov 5, 2005
    #2
    1. Advertising

  3. 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.
     
    Jeffrey Schwab, Nov 5, 2005
    #3
  4. Xah Lee

    Rick Wotnaz Guest

    "Gerard Flanagan" <> wrote in
    news::

    > 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
     
    Rick Wotnaz, Nov 5, 2005
    #4
  5. Xah Lee

    Peter Hansen Guest

    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
     
    Peter Hansen, Nov 5, 2005
    #5
  6. >>>>> "RW" == Rick Wotnaz <> 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
     
    Charlton Wilbur, Nov 5, 2005
    #6
  7. Xah Lee

    Mike Meyer Guest

    "Andrea Gavana" <> 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 ****** 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 <> http://www.mired.org/home/mwm/
    Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
     
    Mike Meyer, Nov 6, 2005
    #7
  8. Xah Lee

    Paul Rubin Guest

    Mike Meyer <> 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.
     
    Paul Rubin, Nov 6, 2005
    #8
  9. Xah Lee

    Mike Meyer Guest

    Paul Rubin <http://> writes:
    > Mike Meyer <> 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 <> http://www.mired.org/home/mwm/
    Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
     
    Mike Meyer, Nov 6, 2005
    #9
  10. Xah Lee

    Paul Rubin Guest

    Mike Meyer <> 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.
     
    Paul Rubin, Nov 6, 2005
    #10
  11. Xah Lee

    Mike Meyer Guest

    Paul Rubin <http://> 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 <> http://www.mired.org/home/mwm/
    Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
     
    Mike Meyer, Nov 6, 2005
    #11
  12. Xah Lee

    Paul Rubin Guest

    Mike Meyer <> 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.
     
    Paul Rubin, Nov 6, 2005
    #12
  13. Xah Lee

    Mike Meyer Guest

    Paul Rubin <http://> writes:
    > Mike Meyer <> 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 <> http://www.mired.org/home/mwm/
    Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
     
    Mike Meyer, Nov 6, 2005
    #13
  14. Instead of obsessing over the library *reference*,why not use other documentation?

    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>
     
    Fredrik Lundh, Nov 6, 2005
    #14
  15. On 05 Nov 2005 19:19:29 -0800, Paul Rubin <http://> wrote:

    >Mike Meyer <> 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
     
    Bengt Richter, Nov 6, 2005
    #15
  16. Re: Instead of obsessing over the library *reference*, why not use other documentation?

    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.
     
    Steven D'Aprano, Nov 6, 2005
    #16
  17. Re: Instead of obsessing over the library *reference*, why not useother documentation?

    > 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
     
    Diez B. Roggisch, Nov 6, 2005
    #17
  18. Xah Lee

    Guest

    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, 2005
    #18
  19. finding and accessing multiple documentation sources

    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/python-list/2005-May/280751.html
    http://mail.python.org/pipermail/python-list/2005-May/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>
     
    Fredrik Lundh, Nov 6, 2005
    #19
  20. 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 ****** 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
     
    Andrea Gavana, Nov 6, 2005
    #20
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Matt
    Replies:
    3
    Views:
    510
    Tor Iver Wilhelmsen
    Sep 17, 2004
  2. Dave
    Replies:
    2
    Views:
    327
    Ali Cehreli
    Aug 10, 2004
  3. Xah Lee
    Replies:
    10
    Views:
    714
  4. Byron Rios
    Replies:
    0
    Views:
    245
    Byron Rios
    Jun 22, 2008
  5. Xah Lee
    Replies:
    10
    Views:
    516
    Jeffrey Schwab
    Nov 9, 2005
Loading...

Share This Page