Python doc problem example: gzip module (reprise)

Discussion in 'Perl Misc' 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. 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
    >
    > ∑ 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 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.

    --
    With kind regards Veli-Pekka Tätilä ()
    Accessibility, game music, synthesizers and programming:
    http://www.student.oulu.fi/~vtatila/
     
    Veli-Pekka Tätilä, 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. Re: OT: Python doc problem example: gzip module (reprise)

    Keith Thompson wrote:
    > "Veli-Pekka Tätilä" <> writes:
    > [snip]
    >> PS: I won't cross-post as I'm not subscribed to the Python group.

    > Not cross-posting is good.
    > Posting *only* to comp.lang.perl.misc, where Python documentation is
    > off-topic, is not the best idea I've seen today.

    Well, true and sorry for any inconvenience. But the quality and
    accessibility of the docs is one factor in choosing which language to use
    and where. I think the inaccessibility of Python docs strongly favors Perl
    in this Regard. And I did talk abou the perl docs, too, both in my message
    and the Google news post to which I linked.

    Isn't this kind of OT complaint even more OT in some sense, and shouldn't
    you also complain to the person who started this thread? I guess most people
    have already killfiled him, though.

    --
    With kind regards Veli-Pekka Tätilä ()
    Accessibility, game music, synthesizers and programming:
    http://www.student.oulu.fi/~vtatila/
     
    Veli-Pekka Tätilä, Nov 7, 2005
    #7
  8. Re: OT: Python doc problem, Netiquette

    Keith Thompson wrote:
    > Yes, you did mention the Perl docs, so my claim that your post was
    > off-topic may have been overstated (or just plain wrong).

    Well, I still think you do have a point. My post was a bit on the OT:ish
    side but not more than the root of this thread, I think. It's funny how
    lasting an effect even a written, valid and nicely put niggle about a
    message such as that it is OT can have. If someone said it to me in real
    life, I would take the point and quickly forget that particular instance.
    But now I even bothered to reply, and started pondering afterwords if it was
    a good idea at all, as my original was not too well argumented.

    In my experience some people in techy groups, and I'm not refering to say
    this one in particular, have a tendency to analyse every word down to the
    letter, even in cases where it might not make that much sense. That is where
    you know by context that a person said the thing, say, more strongly than
    what he really must think. In spoken language such an exaggeration wouldn't
    be a big deal at all, though it is not exactly a good way of argumentation,
    either.

    > If Xah Lee happens to make a valid point and you want to discuss it,
    > start a new thread, preferably without mentioning his name.

    Oh ok. But how should I refer to him, then? I think people following his
    posts will know my thread is based on the original, anyway.

    While we are discussing OT:ness and related things, I'd like to ask a
    netiquettte question here:
    Often I want to reply to several people in a thread but the individual
    replies would be a bit on the brief side. I would rather concatenate them in
    one long message, quoting and snipping everyone appropriately and adding my
    comments. In such a case, where should I put the message in the thread?

    --
    With kind regards Veli-Pekka Tätilä ()
    Accessibility, game music, synthesizers and programming:
    http://www.student.oulu.fi/~vtatila/
     
    Veli-Pekka Tätilä, Nov 8, 2005
    #8
  9. Xah Lee

    Xah Lee Guest

    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

    ∑ http://xahlee.org/
     
    Xah Lee, Nov 8, 2005
    #9
  10. Xah Lee

    Xah Lee Guest

    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

    ∑ http://xahlee.org/
     
    Xah Lee, Nov 8, 2005
    #10
  11. Mike Meyer wrote:
    > "Xah Lee" <> 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?
     
    Jeffrey Schwab, Nov 9, 2005
    #11
    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:
    509
    Tor Iver Wilhelmsen
    Sep 17, 2004
  2. Dave
    Replies:
    2
    Views:
    327
    Ali Cehreli
    Aug 10, 2004
  3. Xah Lee
    Replies:
    10
    Views:
    713
  4. Xah Lee
    Replies:
    25
    Views:
    881
    Jeffrey Schwab
    Nov 9, 2005
  5. Byron Rios
    Replies:
    0
    Views:
    245
    Byron Rios
    Jun 22, 2008
Loading...

Share This Page