Re: Documentation suggestions

On 8 Dec 2005 08:00:25 -0800, BartlebyScrivener <[EMAIL PROTECTED]> wrote: > The bulleted points in BeginnersGuide/Overview are, again, things that > are important to programmers ("Automatic garbage collection frees you > from the hassles of memory management" means nothing to me, even now

Re: Documentation suggestions

On Sat, 10 Dec 2005 11:45:12 +0100, Fredrik Lundh <[EMAIL PROTECTED]> wrote: >> to make it better. Maybe it could be "'', from '' >> by ". Then the text for your file would be "'The zlib module', >> from '(the eff-bot guide to) The Standard Python Library' by Fredrik Lundh." > > that sh

Re: Documentation suggestions

I wrote: > if it turns out that this doesn't scale (has anyone put up that library > reference wiki yet? ;-) if anyone's interested, here's a seealso file for the python library reference: http://effbot.org/zone/seealso-python-library.xml this was generated from the global module index by t

Re: Documentation suggestions

A.M. Kuchling wrote: > BThe associated text currently isn't very helpful, but I'm not sure how > to make it better. Maybe it could be "'', from '' > by ". Then the text for your file would be "'The zlib module', > from '(the eff-bot guide to) The Standard Python Library' by Fredrik Lundh." that

Re: Documentation suggestions

Mike, This is probably a dumb thing to suggest, but I'm interested in knowing why it's dumb, if that makes sense? Could you use one of those free VMWare players? It makes a virtual operating system within an operating system as I understand it. http://www.vmware.com/products/player/ I just thin

Re: Documentation suggestions

Paul Rubin writes: > Mike Meyer <[EMAIL PROTECTED]> writes: >> I'm working on puttingn this up for Python. I'm planning on using AJAX >> to pass the input string to eval on the server. I.e. - you'll be >> limited to expressions, which is what it seems like the Ruby thing

Re: Documentation suggestions

Mike Meyer <[EMAIL PROTECTED]> writes: > I'm working on puttingn this up for Python. I'm planning on using AJAX > to pass the input string to eval on the server. I.e. - you'll be > limited to expressions, which is what it seems like the Ruby thing is > limited to. > > On the other hand, with itera

Re: Documentation suggestions

Trent Mick <[EMAIL PROTECTED]> writes: > [EMAIL PROTECTED] wrote] >> Trent> Nah, the Try Ruby thing is mostly faking it (I believe) rather >> Trent> than running an actually Ruby interactive session ("bastion'ed" >> Trent> or not). >> I don't think so. I tried typing some stuff at the

Re: Documentation suggestions

On Thu, 8 Dec 2005 18:17:59 +0100, Fredrik Lundh <[EMAIL PROTECTED]> wrote: > cool. can you post a sample page somewhere? It's not terribly interesting at the moment. The generated LaTeX looks like this: \seeurl{http://effbot.org/librarybook/zlib.htm}{The zlib module} And that gets f

Re: Documentation suggestions

[EMAIL PROTECTED] wrote] > > Trent> Nah, the Try Ruby thing is mostly faking it (I believe) rather > Trent> than running an actually Ruby interactive session ("bastion'ed" > Trent> or not). > > I don't think so. I tried typing some stuff at the prompt that it wasn't > asking for, lik

Re: Documentation suggestions

You guys are all wizards from mars. If it's easy to do I can tell you that it would very seductive to a prospective Pythoner, and you avoid the problem of making them download before they can try out a tutorial. Thanks for looking at it. rd -- http://mail.python.org/mailman/listinfo/python-list

Re: Documentation suggestions

On Thu, 08 Dec 2005 18:43:56 -0500 Mike Meyer <[EMAIL PROTECTED]> wrote: > "BartlebyScrivener" <[EMAIL PROTECTED]> writes: > > Too bad there > > isn't something like what Ruby does with the "Try Ruby > > In Your Browser" thing, which is a very effective > > marketing tool (although obviously I cho

Re: Documentation suggestions

Trent> Nah, the Try Ruby thing is mostly faking it (I believe) rather Trent> than running an actually Ruby interactive session ("bastion'ed" Trent> or not). I don't think so. I tried typing some stuff at the prompt that it wasn't asking for, like "x = [1,2,3]" followed by "x * 5" whe

Re: Documentation suggestions

Mike> The question is how do you keep the system that the Python code is Mike> actually running on safe? Ruby may have a real bastion mode, but Mike> Python doesn't. User Mode Linux? chroot? Skip -- http://mail.python.org/mailman/listinfo/python-list

Re: Documentation suggestions

[Mike Meyer wrote] > "BartlebyScrivener" <[EMAIL PROTECTED]> writes: > > Too bad there > > isn't something like what Ruby does with the "Try Ruby In Your Browser" > > thing, which is a very effective marketing tool (although obviously I > > chose Python). > > > > http://tryruby.hobix.com/ > > I've

Re: Documentation suggestions

In article <[EMAIL PROTECTED]>, Mike Meyer <[EMAIL PROTECTED]> wrote: >"BartlebyScrivener" <[EMAIL PROTECTED]> writes: >> >> Too bad there >> isn't something like what Ruby does with the "Try Ruby In Your Browser" >> thing, which is a very effective marketing tool (although obviously I >> chose Py

Re: Documentation suggestions

"BartlebyScrivener" <[EMAIL PROTECTED]> writes: > Too bad there > isn't something like what Ruby does with the "Try Ruby In Your Browser" > thing, which is a very effective marketing tool (although obviously I > chose Python). > > http://tryruby.hobix.com/ I've seen things like this for other lang

Re: Documentation suggestions

amk> I wonder if the Internet chapter should be split into "HTTP/Web amk> Tools" (webbrowser, cgi, cgitb, httplib, urllib) and "Non-Web amk> Protocols" (ftplib, gopherlib, smtp, all the rest). Note that cgitb works just fine in a non-web environment. I would actually prefer it be ren

Re: Documentation suggestions

A.M. Kuchling wrote: > > of the seealso environment. I'll talk to Fred about it and begin > > assembling a patch. > > Patch #1376361: http://www.python.org/sf/1376361 . I still need to talk > to Fred about this. cool. can you post a sample page somewhere? -- http://mail.python.org/mailma

Re: Documentation suggestions

On Wed, 07 Dec 2005 10:36:52 -0600, A.M. Kuchling <[EMAIL PROTECTED]> wrote: > of the seealso environment. I'll talk to Fred about it and begin > assembling a patch. Patch #1376361: http://www.python.org/sf/1376361 . I still need to talk to Fred about this. --amk -- http://mail.python

Re: Documentation suggestions

A.M. Kuchling wrote: > On Wed, 07 Dec 2005 12:10:18 -0500, > Kent Johnson <[EMAIL PROTECTED]> wrote: > >>OK I'll bite. That Beginners Guide page has bugged me for a long time. >>It's a wiki page but it is marked as immutable so I can't change it. >>Here are some immediate suggestions: >

Re: Documentation suggestions

Andrew, The site changes for the new-to-Python person are a big improvement in terms of the sequence of exposures, but from a marketing perspective, the first thing they read about Python is still aimed at a programmer. The bulleted points in BeginnersGuide/Overview are, again, things that are imp

Re: Documentation suggestions

On Wed, 07 Dec 2005 12:58:36 -0800, Michael Spencer <[EMAIL PROTECTED]> wrote: > I experimented with some more re-organization, but I don't see away > to attach the resulting file in the SF comments, so I'll post it > here instead. I've attached your file to the patch. Some comments: >

Re: Documentation suggestions

On Wed, 07 Dec 2005 12:10:18 -0500, Kent Johnson <[EMAIL PROTECTED]> wrote: > OK I'll bite. That Beginners Guide page has bugged me for a long time. > It's a wiki page but it is marked as immutable so I can't change it. > Here are some immediate suggestions: Good suggestions; thanks! I

Re: Documentation suggestions

On 7 Dec 2005 05:51:45 -0800, Iain King <[EMAIL PROTECTED]> wrote: > Argh, you made me look at the html again - at least now I know *why* it > is so disgusting. I understand there's a new version coming out soon, > hopefully in html 4 strict or xhtml. I'm sure at that point it'll be > ea

Re: Documentation suggestions

[EMAIL PROTECTED] wrote: > [EMAIL PROTECTED] wrote: > > I suspect I'd have a harder time living without the sys module than with > > many of the builtins. Then there's os, re, math, ... Some modules, like > > thread and sys, have to be linked into the interpreter. Are they "core" or > > "add on"

Re: Documentation suggestions

On Thu, 8 Dec 2005 01:32:08 +0100, "Fredrik Lundh" <[EMAIL PROTECTED]> wrote: >[EMAIL PROTECTED] wrote: > >> > wasn't the idea to get rid of the language reference altogether, and >> > replace it with a better introduction ? >> >> Can an introduction provide the information the language >> referen

Re: Documentation suggestions

[EMAIL PROTECTED] wrote: > > wasn't the idea to get rid of the language reference altogether, and > > replace it with a better introduction ? > > Can an introduction provide the information the language > reference provides (or maybe I am misunderstanding what > you mean by introduction.) from th

Re: Documentation suggestions

Aahz wrote: > In article <[EMAIL PROTECTED]>, > A.M. Kuchling <[EMAIL PROTECTED]> wrote: > >>So now we're *really* stuck. The RefGuide doesn't describe the rules; >>the PEP no longer describes them either; and probably only Guido can >>write the new text for the RefGuide. (Or are the semantics t

Re: Documentation suggestions

Fredrik Lundh wrote: > Ian Bicking wrote: > > > > the standard library is not an add-on. you're confused. > > > > I think the point is that there is the core language, and from a user's > > perspective builtins and statements and syntax are all the same thing. > > When you import a module, it's m

Re: Documentation suggestions

[EMAIL PROTECTED] wrote: > Ian> I think the point is that there is the core language, and from a > Ian> user's perspective builtins and statements and syntax are all the > Ian> same thing. When you import a module, it's more-or-less obvious > Ian> where you find information about the

Re: Documentation suggestions

Ian> I think the point is that there is the core language, and from a Ian> user's perspective builtins and statements and syntax are all the Ian> same thing. When you import a module, it's more-or-less obvious Ian> where you find information about the module (the module index, of

Re: Documentation suggestions

Ian Bicking wrote: > > the standard library is not an add-on. you're confused. > > I think the point is that there is the core language, and from a user's > perspective builtins and statements and syntax are all the same thing. > When you import a module, it's more-or-less obvious where you find

Re: Documentation suggestions

>> http://staging.musi-cal.com/modindex/ rurpy> Is this only for the online docs? Yes. I don't see that it would be helpful for static docs. Presumably they will get reorganized. I want something for the many times I return to the global module index looking for help with a particul

Re: Documentation suggestions

Fredrik Lundh wrote: > [EMAIL PROTECTED] wrote: > > > The builtins section should be moved to the language > > reference manual. The material it documents is part > > of the language definition, not part of an add-on library. > > the standard library is not an add-on. you're confused. I think th

Re: Documentation suggestions

[EMAIL PROTECTED] wrote: > Fredrik Lundh wrote: > > [EMAIL PROTECTED] wrote: > > > > > The builtins section should be moved to the language > > > reference manual. The material it documents is part > > > of the language definition, not part of an add-on library. > > > > the standard library is no

Re: Documentation suggestions

Fredrik Lundh wrote: > [EMAIL PROTECTED] wrote: > > > The builtins section should be moved to the language > > reference manual. The material it documents is part > > of the language definition, not part of an add-on library. > > the standard library is not an add-on. you're confused. > > Your

Re: Documentation suggestions

[EMAIL PROTECTED] wrote: > >> The library reference has so many modules that the table of contents > >> is very large. Again, not really a problem that we can fix; > >> splitting it up into separate manuals doesn't seem like it would > >> help. > > Iain> I like the Global Module I

Re: Documentation suggestions

[EMAIL PROTECTED] wrote: > The builtins section should be moved to the language > reference manual. The material it documents is part > of the language definition, not part of an add-on library. the standard library is not an add-on. you're confused. -- http://mail.python.org/mailman/list

Re: Documentation suggestions

Adam Olsen wrote: > On 12/7/05, [EMAIL PROTECTED] <[EMAIL PROTECTED]> wrote: > > > > Adam> I don't expect everything to make the transition. Are discussions > > Adam> of "atoms" and fragments of BNF really better than calling them > > Adam> expressions and linking to CPython's Grammar

Re: Documentation suggestions

"Michael Spencer" <[EMAIL PROTECTED]> wrote: > A.M. Kuchling wrote: > > On Tue, 06 Dec 2005 10:29:33 -0800, > > Michael Spencer <[EMAIL PROTECTED]> wrote: > >> not that helpful. "Miscellaneous Services", in particular, gives no clue > >> to > >> treasures it contains. I would prefer, for exampl

Re: Documentation suggestions

In article <[EMAIL PROTECTED]>, A.M. Kuchling <[EMAIL PROTECTED]> wrote: > >So now we're *really* stuck. The RefGuide doesn't describe the rules; >the PEP no longer describes them either; and probably only Guido can >write the new text for the RefGuide. (Or are the semantics the same >and only so

Re: Documentation suggestions

A.M. Kuchling wrote: > On Tue, 06 Dec 2005 10:29:33 -0800, > Michael Spencer <[EMAIL PROTECTED]> wrote: >> not that helpful. "Miscellaneous Services", in particular, gives no clue to >> treasures it contains. I would prefer, for example, to see the data >> structure modules: collections,

Re: Documentation suggestions

On Wed, 7 Dec 2005 07:45:13 -0600, [EMAIL PROTECTED] <[EMAIL PROTECTED]> wrote: > Just because that audience is small doesn't mean they are unimportant. > There are currently four actively maintained/developed implementations of > Python. A common language reference manual is important fo

Re: Documentation suggestions

Steven Bethard <[EMAIL PROTECTED]> writes: > [EMAIL PROTECTED] wrote: > > Iain> I like the Global Module Index in general - it allows quick access > > Iain> to exactly what I want. I would like a minor change to it though > > Iain> - stop words starting with a given letter rolling over

Re: Documentation suggestions

Might be better as: "Many popular tutorials use Python to teach computer programming, because Python is free, easy to learn, immediately useful, and fun!" -- http://mail.python.org/mailman/listinfo/python-list

Re: Documentation suggestions

Kent> OK I'll bite. That Beginners Guide page has bugged me for a long Kent> time. It's a wiki page but it is marked as immutable so I can't Kent> change it. That's because for some reason it is one of the top two or three most frequently defaced pages on the wiki. We got tired of h

Re: Documentation suggestions

Yep, Guido's tutorial belongs on the Python for Programmers page where people know who he is and are able to understand him. > Alan Gauld's tutorial is very popular on the > tutor list, so is A Byte of Python (which is not listed on the > NonProgrammers page). I would list them first. Or maybe tak

Re: Documentation suggestions

Steve Holden wrote: > BartlebyScrivener wrote: >> Now you are on a page with promising-looking links that all start with >> "BeginnersGuide," but the first three are not warm welcomes, they are >> housekeeping matters about where you can take courses or how to >> download Python for people who don'

Re: Documentation suggestions

>> http://staging.musi-cal.com/modindex/ Steven> What I don't know is how it would look after thousands of people Steven> using it. I know that I probably only have 10 modules or so Steven> that I consistently need to check the docs for. Your hack above Steven> would conveni

Re: Documentation suggestions

On Wed, 7 Dec 2005 09:36:24 +0100, Fredrik Lundh <[EMAIL PROTECTED]> wrote: > or just add a marker (in some for me unknown way), and postprocess > the HTML files. I'm not sure the links does necessarily belong in e.g. > PDF renderings of the documentation, but that's of course up to the >

Re: Documentation suggestions

In article <[EMAIL PROTECTED]>, <[EMAIL PROTECTED]> wrote: > >OTOH, I find myself returning to the same module docs over and over >again to look up function arguments, regular expression syntax, that >sort of thing. Having to page down past dozens and dozens of modules I >don't care about to clic

Re: Documentation suggestions

A.M. Kuchling wrote: > There's another struggle within the LibRef: is it a reference or a > tutorial? Does it list methods in alphabetical order so you can look > them up, or does it list them in a pedagogically useful order? I > think it has to be a reference; if each section were to be a tutor

Re: Documentation suggestions

[EMAIL PROTECTED] wrote: > Iain> I like the Global Module Index in general - it allows quick access > Iain> to exactly what I want. I would like a minor change to it though > Iain> - stop words starting with a given letter rolling over to another > Iain> column (for example, os.pat

Re: Documentation suggestions

On Tue, 06 Dec 2005 10:29:33 -0800, Michael Spencer <[EMAIL PROTECTED]> wrote: > not that helpful. "Miscellaneous Services", in particular, gives no clue to > treasures it contains. I would prefer, for example, to see the data > structure modules: collections, heapq, array etc... given

Re: Documentation suggestions

On 12/7/05, [EMAIL PROTECTED] <[EMAIL PROTECTED]> wrote: > > Adam> Having a large and detailed language specification, although an > Adam> admirable ideal, is a waste of time when the target audience is > Adam> perhaps a few dozen people. > > Just because that audience is small doesn't

Re: Documentation suggestions

[EMAIL PROTECTED] wrote: > Iain> Well, the point of the GMI is to lookup whatever module you are > Iain> currently having to use for the first time (at least it is for > Iain> me). Giving easy access to the modules I've already had to look > Iain> up (because they are common) doesn't

Re: Documentation suggestions

Adam> Having a large and detailed language specification, although an Adam> admirable ideal, is a waste of time when the target audience is Adam> perhaps a few dozen people. Just because that audience is small doesn't mean they are unimportant. There are currently four actively mainta

Re: Documentation suggestions

Iain> Well, the point of the GMI is to lookup whatever module you are Iain> currently having to use for the first time (at least it is for Iain> me). Giving easy access to the modules I've already had to look Iain> up (because they are common) doesn't really help - I've already

Re: Documentation suggestions

On 12/7/05, [EMAIL PROTECTED] <[EMAIL PROTECTED]> wrote: > > Adam> I don't expect everything to make the transition. Are discussions > Adam> of "atoms" and fragments of BNF really better than calling them > Adam> expressions and linking to CPython's Grammar file? > > Actually, yes. Th

Re: Documentation suggestions

[EMAIL PROTECTED] wrote: > >> The library reference has so many modules that the table of contents > >> is very large. Again, not really a problem that we can fix; > >> splitting it up into separate manuals doesn't seem like it would > >> help. > > Iain> I like the Global Module I

Re: Documentation suggestions

>> The library reference has so many modules that the table of contents >> is very large. Again, not really a problem that we can fix; >> splitting it up into separate manuals doesn't seem like it would >> help. Iain> I like the Global Module Index in general - it allows quic

Re: Documentation suggestions

> The library reference has so many modules that the table of contents > is very large. Again, not really a problem that we can fix; splitting > it up into separate manuals doesn't seem like it would help. I like the Global Module Index in general - it allows quick access to exactly what I want.

Re: Documentation suggestions

Adam> I don't expect everything to make the transition. Are discussions Adam> of "atoms" and fragments of BNF really better than calling them Adam> expressions and linking to CPython's Grammar file? Actually, yes. The actual Grammar file isn't designed for explanation (mostly it's m

Re: Documentation suggestions

BartlebyScrivener wrote: > You are correct about the tutorial. Just try to look at the home page > through the eyes of a curious Windows user who wants to learn > programming and is trying to decide whether to take up Perl, Ruby, > Python, or Visual Basic, let's say. > > On the home page, the firs

Re: Documentation suggestions

A.M. Kuchling wrote: > > I've proposed adding support for semi-automatic linking to external > > documents, based on a simple tagging model, a couple of times, e.g. > > > > http://mail.python.org/pipermail/python-list/2005-May/280751.html > > Very interesting. There could be a manually-mainta

Re: Documentation suggestions

Ian Bicking wrote: > > I've proposed adding support for semi-automatic linking to external > > documents, based on a simple tagging model, a couple of times, e.g. > > > > http://mail.python.org/pipermail/python-list/2005-May/280751.html > > http://mail.python.org/pipermail/python-list/2005

Re: Documentation suggestions

A.M. Kuchling wrote: > Here are some thoughts on reorganizing Python's documentation, with > one big suggestion. Throwing in my own 2¢.. I think the language reference should be disseminated into the rest of the documentation. Some of the stuff (operator precedence anybody?) could be done directl

Re: Documentation suggestions

Steve Holden <[EMAIL PROTECTED]> writes: > I proposed a documentation sprint for PyCon a couple of years ago, but > nobody thought it was important enough to work on. It would be a good > idea next year, too. IMO this should definitely be done. That nobody thought docs were important enough to wo

Re: Documentation suggestions

Aahz wrote: > Here's a question that kind of gets to the heart of a lot of the > problem: where does ``print`` get documented? If we can come up with a > good process for answering that question, we can probably fix a lot of > other problems. (Note emphasis on the word "process".) Sometimes a po

Re: Documentation suggestions

You are correct about the tutorial. Just try to look at the home page through the eyes of a curious Windows user who wants to learn programming and is trying to decide whether to take up Perl, Ruby, Python, or Visual Basic, let's say. On the home page, the first link that catches the eye for this

Re: Documentation suggestions

On Tue, 6 Dec 2005 11:31:21 -0500 "A.M. Kuchling" <[EMAIL PROTECTED]> wrote: > Here are some thoughts on reorganizing Python's > documentation, with one big suggestion. > There's another struggle within the LibRef: is it a > reference or a tutorial? REFERENCE! :-) > Does it list methods in >

Re: Documentation suggestions

[EMAIL PROTECTED] wrote: > Ian> I think it would be very useful if there was reference (not just > Ian> tutorial) documentation for all the syntax, special semantics like > Ian> magic methods, and all the functions and objects in builtins. > > It's pretty common to have a User's Guide as w

Re: Documentation suggestions

Ian> I think it would be very useful if there was reference (not just Ian> tutorial) documentation for all the syntax, special semantics like Ian> magic methods, and all the functions and objects in builtins. It's pretty common to have a User's Guide as well as a Reference Manual fo

Re: Documentation suggestions

Michael Spencer wrote: > A.M. Kuchling wrote: > >> Here are some thoughts on reorganizing Python's documentation, with >> one big suggestion. >> > > Thanks for raising this topic, and for your on-going efforts in this field. > > I use the compiled html help file provided by PythonWin, which incl

Re: Documentation suggestions

Carl Friedrich Bolz wrote: > [EMAIL PROTECTED] wrote: > >> Ian> A test suite seems far more useful to implementors than any >> guide, >> >> Of course, test cases can be modified or ignored. I'd agree with you >> if we >> had a test suite that was more strongly cast in stone. > > > hum. a

Re: Documentation suggestions

Aahz wrote: > Here's a question that kind of gets to the heart of a lot of the > problem: where does ``print`` get documented? If we can come up with a > good process for answering that question, we can probably fix a lot of > other problems. (Note emphasis on the word "process".) Good point; th

Re: Documentation suggestions

>> Of course, test cases can be modified or ignored. I'd agree with you >> if we had a test suite that was more strongly cast in stone. Carl> hum. a test suite like that would have to be constructed very Carl> carefully. The current CPython testsuite tests quite some things

Re: Documentation suggestions

A.M. Kuchling wrote: > On Tue, 6 Dec 2005 11:28:12 -0600, > [EMAIL PROTECTED] <[EMAIL PROTECTED]> wrote: > >>Somehow I think Guido would eventually put his (16-ton) foot down. ;-) > > > Maybe, but he hasn't put his foot down on new-style classes yet, which > were added in 2.2. It would b

Re: Documentation suggestions

In article <[EMAIL PROTECTED]>, A.M. Kuchling <[EMAIL PROTECTED]> wrote: > >There's another struggle within the LibRef: is it a reference or a >tutorial? Does it list methods in alphabetical order so you can look >them up, or does it list them in a pedagogically useful order? I >think it has to b

Re: Documentation suggestions

[EMAIL PROTECTED] wrote: > Ian> A test suite seems far more useful to implementors than any guide, > > Of course, test cases can be modified or ignored. I'd agree with you if we > had a test suite that was more strongly cast in stone. hum. a test suite like that would have to be constructed

Re: Documentation suggestions

On 6 Dec 2005 10:10:09 -0800, Ian Bicking <[EMAIL PROTECTED]> wrote: > stable personal pages that should be linked in . But I do think that > we should encourage some specific process for new or revised > tutorial/howto contributions, like encouraging people put such material > in the wik

Re: Documentation suggestions

On Tue, 6 Dec 2005 18:33:05 +0100, > I've proposed adding support for semi-automatic linking to external > documents, based on a simple tagging model, a couple of times, e.g. > > http://mail.python.org/pipermail/python-list/2005-May/280751.html Very interesting. There could be a manually-ma

Re: Documentation suggestions

>>> A series of examples seems more concrete than a formal description,<< rd> Amen. This is why people buy the books: The good ones have lots of rd> examples. The wizards glance at them in passing and think, "Duh." rd> And the rest of us (including the intermediate folks, I'll bet

Re: Documentation suggestions

A.M. Kuchling wrote: > Here are some thoughts on reorganizing Python's documentation, with > one big suggestion. > Thanks for raising this topic, and for your on-going efforts in this field. I use the compiled html help file provided by PythonWin, which includes all the core documentation. I u

Re: Documentation suggestions

Fredrik Lundh wrote: > > > There's another struggle within the LibRef: is it a reference or a > > > tutorial? Does it list methods in alphabetical order so you can look > > > them up, or does it list them in a pedagogically useful order? I > > > think it has to be a reference; if each section wer

Re: Documentation suggestions

Fredrik Lundh wrote: > I've proposed adding support for semi-automatic linking to external > documents, based on a simple tagging model, a couple of times, e.g. > > http://mail.python.org/pipermail/python-list/2005-May/280751.html > http://mail.python.org/pipermail/python-list/2005-May/2807

Re: Documentation suggestions

>> A series of examples seems more concrete than a formal description,<< Amen. This is why people buy the books: The good ones have lots of examples. The wizards glance at them in passing and think, "Duh." And the rest of us (including the intermediate folks, I'll bet) are grateful for the chance

Re: Documentation suggestions

On Tue, 6 Dec 2005 11:28:12 -0600, [EMAIL PROTECTED] <[EMAIL PROTECTED]> wrote: > Somehow I think Guido would eventually put his (16-ton) foot down. ;-) Maybe, but he hasn't put his foot down on new-style classes yet, which were added in 2.2. It would be all to the good if the BDFL (or t

Re: Documentation suggestions

Ian Bicking wrote: > > There's another struggle within the LibRef: is it a reference or a > > tutorial? Does it list methods in alphabetical order so you can look > > them up, or does it list them in a pedagogically useful order? I > > think it has to be a reference; if each section were to be a

Re: Documentation suggestions

A.M. Kuchling wrote: > There's another struggle within the LibRef: is it a reference or a > tutorial? Does it list methods in alphabetical order so you can look > them up, or does it list them in a pedagogically useful order? I > think it has to be a reference; if each section were to be a tutor

Re: Documentation suggestions

Ian> A test suite seems far more useful to implementors than any guide, Of course, test cases can be modified or ignored. I'd agree with you if we had a test suite that was more strongly cast in stone. Skip -- http://mail.python.org/mailman/listinfo/python-list

Re: Documentation suggestions

Ben> Make the docs like PHP's docs. Easier said than done. There is still - I think - a project in the works to redo the python.org website, but I have no idea if it means to retain ht2html+latex2html as the page builders or move to something else. Neither ht2html nor latex2html support in

Re: Documentation suggestions

Ian Bicking wrote: >>There are endless minor bugs in the library reference, but that seems >>unavoidable. It documents many different and shifting modules, and >>what to document is itself a contentious issue, so I don't think the >>stream of small problems will ever cease. > > > Since the topic

Re: Documentation suggestions

amk> The library reference has so many modules that the table of amk> contents is very large. Again, not really a problem that we can amk> fix; splitting it up into separate manuals doesn't seem like it amk> would help. I've been meaning to tackle this with a wiki macro. It woul

Re: Documentation suggestions

A.M. Kuchling wrote: > Here are some thoughts on reorganizing Python's documentation, with > one big suggestion. Thanks for bringing this up... > There are endless minor bugs in the library reference, but that seems > unavoidable. It documents many different and shifting modules, and > what to d

Re: Documentation suggestions

A.M. Kuchling wrote: > The tutorial seems to be in pretty good shape because Raymond > Hettinger has been keeping it up to date. It doesn't cover > everything, but it's a solid introduction, and if people don't find it > works for them, they have lots of alternative books. No suggestions > here.

Documentation suggestions

Here are some thoughts on reorganizing Python's documentation, with one big suggestion. The tutorial seems to be in pretty good shape because Raymond Hettinger has been keeping it up to date. It doesn't cover everything, but it's a solid introduction, and if people don't find it works for them, t