RE: Python evolution: Unease

Discussion in 'Python' started by Roman Suzi, Jan 4, 2005.

  1. Roman Suzi

    Roman Suzi Guest

    On Tue, 4 Jan 2005, Batista, Facundo wrote:

    Maybe OP doesn't yet fully comprehend the ways of Python universe?

    As for his claims, I am quite surprised that Python lacks
    something in the docs.

    Concerning better hierarchy in the standard library, it is interesting
    that there are some movements in this direction: xml package,
    email package, etc. Probably Iwan thinks that letting more
    "hierachiesness" into std lib Python will be "cleaner".
    Yes, it will probably look "more organized" this way, but
    I do not like the idea:

    import time.time
    import time.calendar
    ...
    import web.url.openers
    import net.http
    ...
    import datatypes.string
    import textprocessing.re

    etc.


    > [Iwan van der Kleyn]
    >
    > #- need: a better standard ide, an integrated db interface with
    > #- a proper
    > #- set of db drivers (!!), a better debugger, a standard widget/windows
    > #- toolkit, something akin to a standard for web programming, better
    > #- documentation, a standard lib which is better organized, a
    > #- formalized
    > #- set of protocols and patterns for program construction. And an
    > #- interpreter which is fast enough to avoid using C or Pyrex in most
    > #- obvious cases.
    >
    > Let's take one by one:
    >
    > - IDE: Better than what? Than IDLE? Than Eclipse? Than SPE? Than Pythonwin?
    >
    > - Integrated DB interface with a proper set of db drivers (what means the
    > "!!"?): What do you mean with an integrated db interface? An standard API to
    > access different DB engines? Something like the Database API specification
    > (http://www.python.org/topics/database/DatabaseAPI-2.0.html)? There's a SIG
    > on DB at http://www.python.org/sigs/db-sig/ you may want to look at.
    > Regarding drivers, to what DB do you miss one?
    >
    > - Debugger: Again, better than what? I use the debugger in IDLE and it's
    > pretty ok.
    >
    > - Standard widget/windows toolkit: More standard than Tk?
    >
    > - Something akin to a standard for web programming: specifically?
    >
    > - Better documentation: Did you find *any* issue in the docs? And why you
    > didn't post a bug on that?
    >
    > - Better organization of the std lib: What do you propose (specifically)?
    > Please, in your proposal, take in consideration migration plans and how the
    > migration affect actual systems. And of course, why the new organization is
    > better than the old one. BTW, I also think that it should be better
    > organized, but don't know how.
    >
    > - a formalized set of protocols and patterns for program construction: a
    > what?
    >
    > - an interpreter which is fast enough to avoid using C or Pyrex in most
    > obvious cases: CPython is More Than Fast Enough. In which obvious cases it's
    > not enough for you?
    >
    > Don't misinterpret this response. I know it was a rambling. But *maybe* you
    > have something to contribute to Python development, even good ideas only and
    > no work.
    >
    > . Facundo


    Sincerely yours, Roman A.Suzi
    --
    - Petrozavodsk - Karelia - Russia - mailto: -
    Roman Suzi, Jan 4, 2005
    #1
    1. Advertising

  2. Roman Suzi

    Paul Rubin Guest

    Roman Suzi <> writes:
    > As for his claims, I am quite surprised that Python lacks
    > something in the docs.


    Python is lacking plenty in the docs. Care to figure out from the
    docs how tkinter works? That's not explained anywhere at all, except
    in some off-site resources and in some printed books. Even some
    language features like class methods and slots are explained only in
    PEP's and release notes, instead of in the language manual where you'd
    expect to find them since they're part of the language.
    Paul Rubin, Jan 4, 2005
    #2
    1. Advertising

  3. Paul> Care to figure out from the docs how tkinter works? That's not
    Paul> explained anywhere at all, except in some off-site resources and
    Paul> in some printed books. Even some language features like class
    Paul> methods and slots are explained only in PEP's and release notes,
    Paul> instead of in the language manual where you'd expect to find them
    Paul> since they're part of the language.

    Start writing (or reorganizing). Folks, this is open source. I'm sure by
    the traffic on the list most people here know how to write. In the case of
    Tkinter, you should probably get the okay of the authors of various external
    docs before incorporating them into the Python docs, but note that several
    Tkinter-related documents are referenced directly from the Tkinter module
    docs:

    Python Tkinter Resources
    The Python Tkinter Topic Guide provides a great deal of information
    on using Tk from Python and links to other sources of information on
    Tk.

    An Introduction to Tkinter
    Fredrik Lundh's on-line reference material.

    Tkinter reference: a GUI for Python
    On-line reference material.

    Tkinter for JPython
    The Jython interface to Tkinter.

    Python and Tkinter Programming
    The book by John Grayson (ISBN 1-884777-81-3).

    This being the Internet and all, it's not clear that referencing external
    documentation is somehow worse than incorporating it directly into the
    distribution.

    As for stuff that exists in PEPs and release notes, they should already all
    have the necessary copyright (either they were placed in the public domain
    or they are already part of the Python distribution) to allow you do just
    check out a CVS tree, make the necessary edits and either check the files
    back in or submit a patch to SourceForge.

    In the documentation arena, I think more thought should probably be given to
    producing online docs that can be directly annotated, thus further reducing
    the barrier to more complete documentation (and more updates). Take a look
    at latex2html, propose or implement changes, or just rewrite the damn thing
    in Python. I think latex2html is probably a recurring nightmare for Fred
    Drake.

    Skip
    Skip Montanaro, Jan 4, 2005
    #3
  4. Roman Suzi

    Paul Rubin Guest

    Skip Montanaro <> writes:
    > Start writing (or reorganizing). Folks, this is open source. I'm
    > sure by the traffic on the list most people here know how to write.


    Irrelevant, the issue isn't what docs can be written if someone
    wants to do it, it's what docs are actually already there. I mean
    every shortcoming anyone could raise about Python or anything else
    could have the same answer, "it's open source, go fix it". The
    question is what does the existing stuff do.

    > In the case of Tkinter, you should probably get the okay of the
    > authors of various external docs before incorporating them into the
    > Python docs,


    If such permission is available then the external docs should just
    be dropped into the distro.

    > but note that several Tkinter-related documents are referenced
    > directly from the Tkinter module docs:


    Irrelevant, the Python docs mean the ones that are included, not the
    ones that are merely referenced.

    > This being the Internet and all, it's not clear that referencing external
    > documentation is somehow worse than incorporating it directly into the
    > distribution.


    The same thing could be said for software. So why not eliminate the
    Python library and let everyone download each module separately?
    Because it's bogus is why. It really does matter whether something is
    included or just referenced. That's what "batteries included" is
    supposed to be about--you get ONE package and it's supposed to have
    everything you need without having to go forage for additional
    components. It matters because most users shouldn't need to care
    about the Python distro at all, since they got Python through its
    inclusion in some bigger distro. E.g., I'm now running the Python
    that was included in Fedora Core 3 GNU/Linux, a complete OS distro on
    a DVD-ROM, containing about 3 gigabytes not including sources. And
    when a user installs 3 gigabytes of software from a DVD, they can
    reasonably expect that they've installed a complete system and
    shouldn't need to download anything additional to use all the features
    of the programs on the DVD. Now the Fedora maintainers aren't Python
    gurus--people ask for Python so they did the obvious thing: downloaded
    it, ran its installer, put the output into their distro, and said "ok,
    Fedora has Python". That's all they should need to do to incorporate
    Python into Fedora. So it's up to the Python maintainers, not the
    Fedora maintainers or the user, to make sure that the Python distro
    has everything that users need, without further downloading.

    And that was just about Tkinter, for which good docs exist but just
    don't happen to be in the distro. How about something like
    SocketServer, for which no reasonable docs exist at all? There's no
    way to figure out how to use it without reading the source. Or the
    socket library, whose docs say to go buy a book by W. Richard Stevens.
    The book is very good, but having to go buy a proprietary book is the
    opposite of what self-contained free software documentation is
    supposed to mean.

    I'm not trying to bash Python, which is excellent in many ways, or I
    wouldn't be using it. I just see various other free software projects
    as trying to live up to higher standards and I think Python should
    aspire to the same thing.

    > As for stuff that exists in PEPs and release notes, they should
    > already all have the necessary copyright (either they were placed in
    > the public domain or they are already part of the Python
    > distribution) to allow you do just check out a CVS tree, make the
    > necessary edits and either check the files back in or submit a patch
    > to SourceForge.


    And about that full featured Python web browser and native-code Python
    compiler, all you have to do is go write it. Come on.

    Having to piece together info from a dozen obscure and inconsistent
    PEP's and stuff in the CVS tree and source comments is not what most
    people think of as "documentation". Documentation means I can look in
    the manual and the info is right there, properly referenced in the
    table of contents and in the proper section for that type of language
    feature, unified with the rest of the docs.

    > In the documentation arena, I think more thought should probably be
    > given to producing online docs that can be directly annotated, thus
    > further reducing the barrier to more complete documentation (and
    > more updates). Take a look at latex2html, propose or implement
    > changes, or just rewrite the damn thing in Python. I think
    > latex2html is probably a recurring nightmare for Fred Drake.


    I've personally been happy with Texinfo for other kinds of docs and
    would consider it easier to deal with than latex2html. It might even
    be feasible to edit it in a wiki, so anyone could improve it easily.
    Another idea is web-based doc comments like PHP and MySQL have, so the
    doc editors can incorporate the info from the comments in subsequent
    doc releases.
    Paul Rubin, Jan 5, 2005
    #4
  5. Paul> Skip Montanaro <> writes:
    >> Start writing (or reorganizing). Folks, this is open source. I'm
    >> sure by the traffic on the list most people here know how to write.


    Paul> Irrelevant, the issue isn't what docs can be written if someone
    Paul> wants to do it, it's what docs are actually already there.

    How do you think we got the docs we already have? Somebody wrote them. If
    there aren't enough docs or if they have mistakes, then somebody has to
    correct them. I'm just suggesting that more people put their money where
    they mouths are so-to-speak.

    >> This being the Internet and all, it's not clear that referencing
    >> external documentation is somehow worse than incorporating it
    >> directly into the distribution.


    Paul> The same thing could be said for software. So why not eliminate
    Paul> the Python library and let everyone download each module
    Paul> separately? Because it's bogus is why.
    Paul> It really does matter whether something is included or just
    Paul> referenced.

    Okay, then start doing the work necessary to incorporate that stuff into the
    core. Get Fredrik to say "okay" to including his Tkinter docs, then do what
    it takes to incorporate it. The fact that Fredrik can check those docs in
    himself but hasn't after several years suggests that he prefers the status
    quo for one or more reasons.

    I'm not saying references are perfect. I'm saying that given the time
    constraints of the existing developer crowd and the relative priority of
    various open tasks that folding in external documentation hasn't risen to
    the top of the queue yet. The best way to make that happen is for it to be
    your highest priority and then for you to make it happen. That's a
    longer-winded way to say what I meant with "this is open source".

    Paul> And that was just about Tkinter, for which good docs exist but
    Paul> just don't happen to be in the distro. How about something like
    Paul> SocketServer, for which no reasonable docs exist at all?

    I'm at a loss. Is there something about this quote taken directly from the
    section of the library reference manual entitled "Undocumented Modules" that
    is unclear?

    Here's a quick listing of modules that are currently undocumented, but
    that should be documented. Feel free to contribute documentation for
    them! (Send via email to .)

    The list there is itself incomplete.

    There is a reference manual section for SocketServer, btw:

    http://www.python.org/doc/current/lib/module-SocketServer.html

    If that needs examples or corrections or is incomplete, feel free to submit
    a patch to either SourceForge or by email to .

    Paul> I'm not trying to bash Python, which is excellent in many ways, or
    Paul> I wouldn't be using it. I just see various other free software
    Paul> projects as trying to live up to higher standards and I think
    Paul> Python should aspire to the same thing.

    I'm sorry, I don't know quite how to respond to that. Sure, I imagine there
    are other communities that do it better. I've seen PHP mentioned here
    recently, and have direct experience with CPAN (and actually like it pretty
    well).

    Look, I don't have much free time, and what free time I do have I mostly
    spend moonlighting on other software (much to my wife's chagrin). I imagine
    most of the other people who contribute to the Python distribution are
    similarly time-afflicted. Here are a couple ideas:

    1. Do you have more money than time? Donate a few bucks to the PSF:

    http://www.python.org/psf/

    Someone will probably do #2.

    2. Do you have more time than money? Write a proposal to the PSF to
    implement/improve/polish off some aspect of the distribution:

    http://www.python.org/psf/

    3. Got some free time and don't care about a few extra bucks? Check
    out how to contribute to Python:

    http://www.python.org/dev/

    >> As for stuff that exists in PEPs and release notes, they should
    >> already all have the necessary copyright (either they were placed in
    >> the public domain or they are already part of the Python
    >> distribution) to allow you do just check out a CVS tree, make the
    >> necessary edits and either check the files back in or submit a patch
    >> to SourceForge.


    Paul> And about that full featured Python web browser and native-code
    Paul> Python compiler, all you have to do is go write it. Come on.

    Where did I say to go write a browser or a native-code Python compiler? If
    that's your bag you can try resurrecting something Grail-like (browser) or
    contribute time top PyPy or Psyco. When I said "write", I literally meant
    write, as in English text.

    Paul> Having to piece together info from a dozen obscure and
    Paul> inconsistent PEP's and stuff in the CVS tree and source comments
    Paul> is not what most people think of as "documentation".
    Paul> Documentation means I can look in the manual and the info is right
    Paul> there, properly referenced in the table of contents and in the
    Paul> proper section for that type of language feature, unified with the
    Paul> rest of the docs.

    I was suggesting that maybe you might like to take the pieces and make them
    something coherent. If it was trivial it would have probably been done by
    now.

    >> In the documentation arena, I think more thought should probably be
    >> given to producing online docs that can be directly annotated, thus
    >> further reducing the barrier to more complete documentation (and more
    >> updates). Take a look at latex2html, propose or implement changes,
    >> or just rewrite the damn thing in Python. I think latex2html is
    >> probably a recurring nightmare for Fred Drake.


    Paul> I've personally been happy with Texinfo for other kinds of docs
    Paul> and would consider it easier to deal with than latex2html. It
    Paul> might even be feasible to edit it in a wiki, so anyone could
    Paul> improve it easily. Another idea is web-based doc comments like
    Paul> PHP and MySQL have, so the doc editors can incorporate the info
    Paul> from the comments in subsequent doc releases.

    I rather like reST (much of www.python.org is being reimplemented in reST),
    but that's just me. The key point I was trying to make is that an
    annotation capability would probably help. With such a feature you could
    add examples or links to the online Python Cookbook, whatever. Need some
    ideas? Look here:

    http://www.amk.ca/diary/archives/003336.html

    As Andrew indicated, it's a "half-hour hack", but it might give someone
    something to think about.

    Skip
    Skip Montanaro, Jan 5, 2005
    #5
  6. On Tue, 04 Jan 2005 17:12:04 -0800, Paul Rubin wrote:
    > Irrelevant, the issue isn't what docs can be written if someone wants to
    > do it, it's what docs are actually already there....


    > I just see various other free software projects as
    > trying to live up to higher standards and I think Python should aspire to
    > the same thing.


    So, nobody should have to write the docs because they should already be
    there, but "somebody" should have to write the docs?

    You need to think more clearly about the pronouns you are slinging around.
    Who is this "they" that should write the docs? (Yes, I know you didn't use
    that exact word but the concept is clearly there.) And what right do you
    have to demand this action from "they"? Are you willing to pay me to do it?
    Jeremy Bowers, Jan 5, 2005
    #6
  7. Roman Suzi

    Paul Rubin Guest

    Jeremy Bowers <> writes:
    > So, nobody should have to write the docs because they should already be
    > there, but "somebody" should have to write the docs?
    >
    > You need to think more clearly about the pronouns you are slinging around.
    > Who is this "they" that should write the docs?


    The Python advocates who claim that Python is well-documented and take
    exception to when someone say it isn't. Their idea of "it's
    well-documented" seems to be "if there's parts that you think are
    poorly documented, feel free to document it". What kind of nonsense
    is that? "Python code runs just as fast as C code. If you think it's
    slower, feel free to speed it up". "Python's standard library
    includes a database module. If it isn't there, feel free to add one".
    "Programming in Python cures cancer. If your cancer doesn't clear up
    when you code in Python, feel free to submit a patch".

    Software advocacy, which Python has an awful lot of, involves
    extolling the virtues of a program as it exists in the present. Not
    as it could potentially exist if someone hypothetically added a bunch
    of work that hasn't yet been done. Python is good software, but its
    advocates are making claims that Python itself doesnt live up to.

    And no, I don't feel a responsibility to do the missing work, since
    I'm not the one making those advocacy claims.
    Paul Rubin, Jan 5, 2005
    #7
  8. Roman Suzi

    Peter Hansen Guest

    Paul Rubin wrote:
    > Jeremy Bowers <> writes:
    >>So, nobody should have to write the docs because they should already be
    >>there, but "somebody" should have to write the docs?
    >>
    >>You need to think more clearly about the pronouns you are slinging around.
    >>Who is this "they" that should write the docs?

    >
    > The Python advocates who claim that Python is well-documented and take
    > exception to when someone say it isn't. Their idea of "it's
    > well-documented" seems to be "if there's parts that you think are
    > poorly documented, feel free to document it". What kind of nonsense
    > is that? "Python code runs just as fast as C code. If you think it's
    > slower, feel free to speed it up". "Python's standard library
    > includes a database module. If it isn't there, feel free to add one".
    > "Programming in Python cures cancer. If your cancer doesn't clear up
    > when you code in Python, feel free to submit a patch".


    I think you're throwing out strawman arguments here.

    The key distinction is that "well-documented" is clearly
    a judgment call, a personal opinion, while the others
    are all measurable absolutes. (The "as fast as C" one borders
    on being an opinion, since most people actually say things that
    mean something more like "as fast as I need it to, so C has no
    advantage".)

    Saying, in effect, as they are, "Python's docs are well enough
    documented for my purposes and, I believe, for those of many
    other people" certainly isn't nonsense, and saying "and if you
    don't agree you should consider improving them yourself
    instead of asking me or others who feel as I do" is certainly
    not nonsense.

    > And no, I don't feel a responsibility to do the missing work, since
    > I'm not the one making those advocacy claims.


    So those who claim Python is well-documented are the ones who
    should improve the documentation, but those claiming that
    the documentation is poor should feel no responsibility to
    make the improvements?

    Does this make any sense to you? To me, *this* is the nonsense.

    -Peter
    Peter Hansen, Jan 5, 2005
    #8
  9. Roman Suzi

    alex23 Guest

    Paul Rubin wrote:
    > The Python advocates who claim that Python is well-documented and

    take
    > exception to when someone say it isn't. Their idea of "it's
    > well-documented" seems to be "if there's parts that you think are
    > poorly documented, feel free to document it". What kind of nonsense
    > is that?


    It's called "having an opinion". "Good" documentation does its job, if
    noone else thought it was poorly documented then to them it wasn't.

    The only person who knows how the current documentation is
    unsatisfactory to you is *you*.

    The mistake being made here by the OS community is the assumption,
    based on their own personal experiences, that others will take the
    absence of something as a challenge to fill it themselves, serving the
    dual role of obtaining what they need for their own purposes AND
    providing it for the purposes of others. It's a mistaken assumption
    because for most people it's easier to gripe that someone else, oh
    let's say "advocates", should be doing it for you.

    > "Python code runs just as fast as C code. If you think it's
    > slower, feel free to speed it up".


    The objective, qualifiable speed of Python has *what* exactly to do
    with the subjective, interprative assessment of the Python
    documentation?

    > "Python's standard library includes a database module. If it isn't

    there,
    > feel free to add one".


    Which part of the open source movement do you just not get?

    > "Programming in Python cures cancer. If your cancer doesn't clear up
    > when you code in Python, feel free to submit a patch".


    Wow, you quickly ran out of points of blind Pythonic advocation, didn't
    you?

    > Software advocacy, which Python has an awful lot of, [...]


    Unjustifiable claims, which your postings have an awful lot of...see
    how easy it is to characterise someones position in the negative? See
    how pointless it is for useful dialogue?

    You've done nothing but kvetch about how others aren't providing you
    with what you need. Let's face it, people like you are never going to
    take the initiative and actually contribute something when you're
    already quite comfortable sponging off the efforts of others and hiding
    behind claims of advocacy whenever anyone questions your own
    motivations.
    In short: grow up and just write the damn documentation.

    - alex23 -
    alex23, Jan 5, 2005
    #9
  10. Roman Suzi

    Paul Rubin Guest

    Peter Hansen <> writes:
    > The key distinction is that "well-documented" is clearly
    > a judgment call, a personal opinion,


    No it's not. If a program has significant modules with complicated
    public API's and no documentation, it's poorly documented in an
    absolute sense. A well-documented program includes docs for all
    the public API's.

    > So those who claim Python is well-documented are the ones who
    > should improve the documentation, but those claiming that
    > the documentation is poor should feel no responsibility to
    > make the improvements?


    Yes, precisely so. Like if someone says "I've written this fantastic
    math package, it's fast and accurate and solves every problem
    perfectly, let's start a newsgroup about how to convince our PHB's to
    use it and why it's so much better than every other math package
    that's ever been written", and I try the package and it says that
    2+2=5 and I report that bug, I've made a constructive comment and have
    no further responsibility. I've also shown that the program doesn't
    live up to its claims and people wanting to do real work with it
    should watch out. If the developers want to keep making the grand
    claims, they should fix the bug. If they want to say "this package is
    technically cool but gets some answers wrong, maybe you don't want to
    do anything serious with it but it's fun to play with", that's
    different. But there's a constant current in clpy of "Python is great
    for everything, our PHB's should all embrace it, it supports protocols
    X, Y, and Z and is great for that kind of application" when those
    protocols turn out to be only half-implemented, or "it's
    well-documented" when the manual turns out to be only half-complete.
    And the responses I see sound almost like "2+2=5 is an accurate
    answer, and if you think it's not close enough, it's open source, so
    fix it".

    If you want to see a really well-done (at least in parts, and also
    poorly documented but not making claims to the contrary) Python
    program, take a look at Twisted Matrix. It reimplements any number of
    features that are already in Python. An early version of the docs
    explained the reason. It said something like "it may look like we're
    re-inventing the wheel, but we have no choice, since the existing
    wheel is square and made of glue".

    > Does this make any sense to you? To me, *this* is the nonsense.


    I don't see any nonsense. People who make claims about a program are
    the ones responsible for the truth of the claims. Saying anyone else
    is responsible is bizarre.
    Paul Rubin, Jan 5, 2005
    #10
  11. Roman Suzi

    Paul Rubin Guest

    "alex23" <> writes:
    > It's called "having an opinion". "Good" documentation does its job, if
    > noone else thought it was poorly documented then to them it wasn't.


    Obviously other people thought Tkinter is poorly documented in the
    Python distro, since the Python library manual says so itself and
    invites people to look at external references instead.

    > > Software advocacy, which Python has an awful lot of, [...]

    >
    > Unjustifiable claims, which your postings have an awful lot of...


    I've justified every claim I've made.

    > You've done nothing but kvetch about how others aren't providing you
    > with what you need. Let's face it, people like you are never going
    > to take the initiative and actually contribute something when you're
    > already quite comfortable sponging off the efforts of others and
    > hiding behind claims of advocacy whenever anyone questions your own
    > motivations.


    I'm not one of the Python developers, I'm just a user, I have my own
    projects that I spend my time on. I like the idea of using Python in
    some of those projects. Python advocacy revolves around encouraging
    people to use Python in their projects, without having to be Python
    developers themselves. Python advocates say "Python does what you
    need, so use it". That's supposed make Python sound attractive. If
    the real truth is "Python does something sort of related to what you
    need, so if besides your own project that you need to finish, you are
    willing to stop in the middle and take on some additional projects of
    improving Python, it can end up being useful for your task", that's a
    lot less attractive.

    I'm happy to use Python, as it is, for various kinds of noncritical
    and throwaway tasks. For critical projects I'm looking for tools that
    work (e.g. Linux, Apache, GCC), not "it's open source, go fix it".
    But just one or two days ago, various people on this group were urging
    me to do a critical project in Python instead of Java. I like Python
    enough to get into these romantic quarrels with it (which is what
    you're seeing now) and feel pretty cold toward Java. But while Java's
    libraries are poorly designed, their implementations tend to be quite
    complete, while Python's are well-designed but often incompletely
    implemented. And so with Java, I feel much less likely to look in the
    manual and note the existence of some feature and plan to use it, only
    to find out after it's too late, that the feature's implementation is
    missing some crucial functionality that would be a lot of work to add.
    (Then there's issues with the languages themselves, that are separate).

    > In short: grow up and just write the damn documentation.


    In short, I should grow up and quietly ignore a lot of Python advocacy
    as being groundless and just use Python for limited purposes. But
    what I want instead is for Python itself to grow up, and do things
    properly instead of half-assedly.
    Paul Rubin, Jan 5, 2005
    #11
  12. Roman Suzi

    Ville Vainio Guest

    >>>>> "Paul" == Paul Rubin <http://> writes:

    Paul> inclusion in some bigger distro. E.g., I'm now running the
    Paul> Python Python into Fedora. So it's up to the Python
    Paul> maintainers, not the Fedora maintainers or the user, to make
    Paul> sure that the Python distro has everything that users need,
    Paul> without further downloading.

    To me, this seems to be the job for the Fedora maintainers, not Python
    maintainers. If something essential is not in the distro the distro
    maintainers have screwed up.

    Paul> And that was just about Tkinter, for which good docs exist
    Paul> but just don't happen to be in the distro. How about

    I think most people these days do a google search when they are
    learning how to use a feature to get the whole story. It's often also
    faster than finding the information in the bundled documentation -
    even if the first google hit often happens to refer to the page with
    the very documentation thu user would have looked up.

    Paul> The book is very good, but having to go buy a proprietary
    Paul> book is the opposite of what self-contained free software
    Paul> documentation is supposed to mean.

    I'm not sure the free software documentation is going to evolve to be
    more self-contained; the exact opposite is more likely.

    --
    Ville Vainio http://tinyurl.com/2prnb
    Ville Vainio, Jan 5, 2005
    #12
  13. Roman Suzi

    Guest

    Paul Rubin:
    > I'm now running the Python
    > that was included in Fedora Core 3 GNU/Linux, a complete OS distro on
    > a DVD-ROM, containing about 3 gigabytes not including sources. And
    > when a user installs 3 gigabytes of software from a DVD, they can
    > reasonably expect that they've installed a complete system and
    > shouldn't need to download anything additional to use all the

    features
    > of the programs on the DVD. Now the Fedora maintainers aren't Python
    > gurus--people ask for Python so they did the obvious thing:

    downloaded
    > it, ran its installer, put the output into their distro, and said

    "ok,
    > Fedora has Python". That's all they should need to do to incorporate
    > Python into Fedora. So it's up to the Python maintainers, not the
    > Fedora maintainers or the user, to make sure that the Python distro
    > has everything that users need, without further downloading.


    Dunno about Fedora, I stopped using Red Hat just because they were
    *not* using
    the standard Python distribution, and the version they shipped was
    cripped in various
    ways. There is nothing the Python developers can do if the OS vendors
    choose to ship
    modified Python distributions, with missing modules or splitted in n
    separated packages
    to download separately.

    Michele Simionato
    , Jan 5, 2005
    #13
  14. Roman Suzi

    Paul Rubin Guest

    Ville Vainio <> writes:
    > To me, this seems to be the job for the Fedora maintainers, not Python
    > maintainers. If something essential is not in the distro the distro
    > maintainers have screwed up.


    I can't parse that. It says two contradictory things. Sentence 2
    says that if something essential is not in the (Python) distro then
    the (Python) distro maintainers have screwed up. Sentence 1 says
    it's the Fedora maintainer's job to deal with it. Huh?

    > Paul> The book is very good, but having to go buy a proprietary
    > Paul> book is the opposite of what self-contained free software
    > Paul> documentation is supposed to mean.
    >
    > I'm not sure the free software documentation is going to evolve to be
    > more self-contained; the exact opposite is more likely.


    With software, I don't think you're right. With documentation, I
    don't have a sense of whether you're right or not, but I hope you
    aren't right.
    Paul Rubin, Jan 5, 2005
    #14
  15. Roman Suzi

    Paul Rubin Guest

    writes:
    > Dunno about Fedora, I stopped using Red Hat just because they were
    > *not* using the standard Python distribution, and the version they
    > shipped was cripped in various ways.


    Eh? I used Red Hat for a long while and don't remember their crippling
    the Python distribution. I do remember their believing the Python
    advocates that Python was a stable language, and therefore building
    critical features around it, and being unwilling to upgrade between
    major Python releases during minor Red Hat release cycles. The result
    was that RH 7.x shipped with Python 1.5.x for quite a long time after
    Python 2.x had been released. However I don't remember anything being
    crippled about the 1.5.x installations.
    Paul Rubin, Jan 5, 2005
    #15
  16. Roman Suzi

    huy Guest


    > The Python advocates who claim that Python is well-documented and take
    > exception to when someone say it isn't. Their idea of "it's
    > well-documented" seems to be "if there's parts that you think are
    > poorly documented, feel free to document it". What kind of nonsense
    > is that?


    I'm not sure which planet you come from but open source is open source
    for a reason. IMO gratitude is the only thing which can be given back to
    the contributors of open source projects not "what you've given me for
    FREE is not good enough, go back and do a better job (and by the way I
    don't really know how you can do a better job) so I can make money off
    your free time". I don't even expect this much from software I pay for.

    Being a python user (not contributer) for the past few years I
    personally think the Python docs are GREAT. If it's not in the
    reference, it can be found in the source (again thank god for open
    source), if it's not in the source you have google, then google groups
    then ASPN python cookbook. If you're not smart enough to do this, well
    learn. It'll help you become a better programmer.

    Anyone who thinks Python docs suck haven't browsed javadocs lately, or MSDN.

    > Software advocacy, which Python has an awful lot of, involves
    > extolling the virtues of a program as it exists in the present. Not
    > as it could potentially exist if someone hypothetically added a bunch
    > of work that hasn't yet been done. Python is good software, but its
    > advocates are making claims that Python itself doesnt live up to.


    You should be more accurate. Quote "Python is good software, but its
    advocates are making claims that [you think it] doesnt live up to". I
    guess everyone is allowed to have their own opinion.

    > And no, I don't feel a responsibility to do the missing work, since
    > I'm not the one making those advocacy claims.


    Good on ya.

    Huy
    huy, Jan 5, 2005
    #16
  17. Roman Suzi

    Ville Vainio Guest

    >>>>> "Paul" == Paul Rubin <http://> writes:

    Paul> Ville Vainio <> writes:

    >> To me, this seems to be the job for the Fedora maintainers, not
    >> Python maintainers. If something essential is not in the distro
    >> the distro maintainers have screwed up.


    Paul> I can't parse that. It says two contradictory things.
    Paul> Sentence 2 says that if something essential is not in the
    Paul> (Python) distro then the (Python) distro maintainers have
    Paul> screwed up. Sentence 1 says it's the Fedora maintainer's
    Paul> job to deal with it. Huh?

    By "distro" I meant the Linux distribution, not the Python
    distribution. Distro is a customary term for a Linux distribution so I
    didn't qualify the word at the time.

    --
    Ville Vainio http://tinyurl.com/2prnb
    Ville Vainio, Jan 5, 2005
    #17
  18. Roman Suzi

    Paul Rubin Guest

    Ville Vainio <> writes:
    > Paul> I can't parse that. It says two contradictory things.
    > Paul> Sentence 2 says that if something essential is not in the
    > Paul> (Python) distro then the (Python) distro maintainers have
    > Paul> screwed up. Sentence 1 says it's the Fedora maintainer's
    > Paul> job to deal with it. Huh?
    >
    > By "distro" I meant the Linux distribution, not the Python
    > distribution. Distro is a customary term for a Linux distribution so I
    > didn't qualify the word at the time.


    Oh ok, but it's the Python distribution that's missing components that
    are essential to Python. Fedora and other Linux distros are
    collections of subsystems like Python. Linux distro maintainers get
    asked to include a subsystem, they check that the subsystem has a
    reasonable reputation (Python does), they install it in the distro and
    run some basic tests, and they ship it. They can't be expected to
    immerse themselves in its intricacies and hang out on the user forums
    to identify all the missing components that they should also hunt down
    and ship. So the Python needs to take care of that stuff.

    I realize that in the old days, people used to write big applications
    without makefiles, and later when they started using makefiles, they
    didn't use configure scripts. So to install a package, you had to do
    a bunch of hand configuration for your particular environment before
    you could compile it, and maybe you even had to say
    cc -O -Dthisflag=thatnumber xyz.c pqr.c frob.c -o frob
    on the command line instead of typing "make" to build the program.
    That kind of thing really doesn't fly any more. The standards for
    what constitutes a properly engineered release of something have
    gotten higher. You really need automatic configuration and build and
    installation. Likewise, if you're trying to market something as a
    complete drop-in system ("batteries included", to use the Python
    terminology), it should not be missing any essential pieces that
    the user has to hunt down separately.
    Paul Rubin, Jan 5, 2005
    #18
  19. Roman Suzi

    John Roth Guest

    "Paul Rubin" <http://> wrote in message
    news:...
    > "alex23" <> writes:


    >> It's called "having an opinion". "Good" documentation does its job, if
    >> noone else thought it was poorly documented then to them it wasn't.


    ....


    >
    >> In short: grow up and just write the damn documentation.


    I've been reading this thread and quietly congratulating myself
    on staying out of it, but this statement takes the cake.

    I would like to contribute some documentation to Python.
    I've got the time, I write quite a bit, etc. I've got fairly
    strong opinions about some things that need to be documented,
    (such as all the new style class descriptor stuff from 2.2)
    and I have relatively little difficulty matching the existing style.

    However, I don't
    know TEX, Latex, CVS or Sourceforge. (The latter two are
    on my "learn sometime soon so I can put PyFIT where it belongs"
    list.)

    I have no desire to install Perl to run the documentation toolchain.
    I also have no particular desire to write up a bunch of final
    format stuff and drop it on someone else to put into the latex
    format so it can be included.

    That means I'm not going to spend literally months learning
    all of this stuff so I can then spend the two or three days
    (each) it would take to write decent documentation for the
    places I think are lacking, and where I have the
    competence to write it up.

    I'm also not going to spend those same months writing
    a current source to XML translator, and then writing
    XSLT or more scripts to do the translations to final
    format, a strategy which would arguably be much more
    beneficial for the Python community as a whole.

    The bottom line is that I'm not going to be writing any
    extensive pieces of Python documentation. My time
    is better spent elsewhere.

    John Roth
    John Roth, Jan 5, 2005
    #19
  20. Roman Suzi

    Paul Rubin Guest

    Skip Montanaro <> writes:
    > Okay, then start doing the work necessary to incorporate that stuff into the
    > core. Get Fredrik to say "okay" to including his Tkinter docs, then do what
    > it takes to incorporate it. The fact that Fredrik can check those docs in
    > himself but hasn't after several years suggests that he prefers the status
    > quo for one or more reasons.


    I thought that we had been through this already, and permission from
    Frederik was not forthcoming. Either he has his own plans for those
    docs, or he has some obligation to someone else to not release them.

    The Tkinter reference at

    http://infohost.nmt.edu/tcc/help/pubs/lang.html

    is actually the best doc I've seen on tkinter so far, but it's only
    available in ps/pdf format and again, would need permission for
    inclusion in Python.

    > There is a reference manual section for SocketServer, btw:
    >
    > http://www.python.org/doc/current/lib/module-SocketServer.html
    >
    > If that needs examples or corrections or is incomplete, feel free to submit
    > a patch to either SourceForge or by email to .


    It's been a while since I really had to wrestle with SocketServer, but
    that its docs were quite inadequate and I had to study the source code
    for quite a while to grok how to use it.

    > Look, I don't have much free time, and what free time I do have I mostly
    > spend moonlighting on other software (much to my wife's chagrin). I imagine
    > most of the other people who contribute to the Python distribution are
    > similarly time-afflicted. Here are a couple ideas:


    Thanks, but I'm not in the business of promoting Python. I like to
    think I contribute in some minor ways by submitting bug reports and
    occasional small patches. I made a conscious decision to not spend
    time on big patches since Python is non-GPL, and I'd rather spend my
    limited volunteer time on GPL projects, working on non-GPL projects
    only if I'm getting paid for it. I offered to make an exception once
    to contribute some functionality that I felt was important for Python
    users, but it was declined.

    What I see going on in clpy all the time though, is people asking
    whether Python is good for some type of project, and always getting
    told "yes" no matter what the project is. If the "yes" means that in
    addition to doing your own project, you find out in the middle that
    you also have to add features to Python that other languages already
    support, that makes your project finish behind schedule and whoever
    told you Python was good for your project really did you a disservice.
    I'm reacting to that phenomenon in this thread, along with possible
    others.

    > 1. Do you have more money than time? Donate a few bucks to the PSF:


    Nah, I'd rather donate to the FSF if I have the bucks to spare. If I
    want to fund the development of proprietary Microsoft products, I'm
    better off sending the money directly to Bill G. Of course I'm happy
    if PSF gets corporate donations, but that's different than someone
    like me operating as a free software activist.

    > 2. Do you have more time than money? Write a proposal to the PSF to
    > implement/improve/polish off some aspect of the distribution:


    Huh? Do you mean like a funding proposal, where PSF would use some of
    those donations to hire me to develop something? I guess I'd consider
    that in principle, but I'm probably not PSF's favorite person right
    now, and unlikely to get hired. And anyway, I have other commitments
    right now and couldn't take on anything like that.

    > Where did I say to go write a browser or a native-code Python compiler? If
    > that's your bag you can try resurrecting something Grail-like (browser) or
    > contribute time top PyPy or Psyco. When I said "write", I literally meant
    > write, as in English text.


    I don't experience much difference between writing text and writing
    code. If I say the docs are missing something and you tell me to fix
    them, that's not much different than telling me to go write missing code.

    Re browsers and compilers: I think a Python browser depends on a good
    GUI toolkit and right now Python only has Tkinter. (There are
    toolkits like wxpython but Python doesn't "have" them; they exist
    separately).

    I think the PyPy group is doing real well with compilers, or at least
    knows what its doing. I want to wait til PyPy is actually deployed
    before I pay too much attention to Python compilation, since I think
    supporting good compilation should actually drive the Python 3000
    language design, and PyPy will make it much easier to experiment with
    new or changing language features.

    > Paul> Having to piece together info from a dozen obscure and
    > Paul> inconsistent PEP's and stuff in the CVS tree and source comments
    > Paul> is not what most people think of as "documentation".
    >
    > I was suggesting that maybe you might like to take the pieces and
    > make them something coherent. If it was trivial it would have
    > probably been done by now.


    I just avoid using those features. If they're not documented they
    probably don't work that well either.

    > I rather like reST (much of www.python.org is being reimplemented in reST),


    I don't know what that is.

    > Look here:
    >
    > http://www.amk.ca/diary/archives/003336.html
    >
    > As Andrew indicated, it's a "half-hour hack", but it might give someone
    > something to think about.


    That's pretty cute and python.org should link to it.
    Paul Rubin, Jan 5, 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. Iwan van der Kleyn

    Python evolution: Unease

    Iwan van der Kleyn, Jan 4, 2005, in forum: Python
    Replies:
    44
    Views:
    962
    Robert Kern
    Jan 7, 2005
  2. Carlos Ribeiro

    Re: Python evolution: Unease

    Carlos Ribeiro, Jan 4, 2005, in forum: Python
    Replies:
    9
    Views:
    376
    David Fraser
    Jan 7, 2005
  3. Replies:
    1
    Views:
    275
    Scott David Daniels
    Jan 4, 2005
  4. Roman Suzi

    Concepts RE: Python evolution: Unease

    Roman Suzi, Jan 5, 2005, in forum: Python
    Replies:
    6
    Views:
    270
    Jeremy Bowers
    Jan 6, 2005
  5. Daniel Bowett

    Re: Python evolution: Unease

    Daniel Bowett, Jan 5, 2005, in forum: Python
    Replies:
    1
    Views:
    307
Loading...

Share This Page