Paul> Skip Montanaro <[EMAIL PROTECTED]> 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 [EMAIL PROTECTED]) 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 [EMAIL PROTECTED] 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 -- http://mail.python.org/mailman/listinfo/python-list