[Python-Dev] Python Doc problems
There are a lot reports on the lousy state of python docs. I'm not much in the python community so i don't know what the developers are doing anything about it. anyway, i've rewrote the Python's RE module documentation, at: http://xahlee.org/perl-python/python_re-write/lib/module-re.html and have recently made the term of user clear. may i ask what the python developers is doing about the python's docs? Are you guys aware, that there are rampant criticisms of python docs and many diverse tries by various individuals to rewrite the doc by starting another wiki or site? Xah [EMAIL PROTECTED] ∑ http://xahlee.org/ ☄ ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] Collecting 2.4.4 fixes
I've put some candidate fixes and listed some tasks at http://wiki.python.org/moin/Python24Fixes. --amk ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] AST structure and maintenance branches
On 9/23/06, Anthony Baxter [EMAIL PROTECTED] wrote: I'd like to propose that the AST format returned by passing PyCF_ONLY_AST to compile() get the same guarantee in maintenance branches as the bytecode format - that is, unless it's absolutely necessary, we'll keep it the same. Otherwise anyone trying to write tools to manipulate the AST is in for a massive world of hurt. Anyone have any problems with this, or can it be added to PEP 6? It's possible we should poll developers of other Python implementations and find out if anyone has objections to supporting this AST format. But in principle, it sounds like a good idea to me. Jeremy ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] AST structure and maintenance branches
On Friday 29 September 2006 00:30, Jeremy Hylton wrote: On 9/23/06, Anthony Baxter [EMAIL PROTECTED] wrote: I'd like to propose that the AST format returned by passing PyCF_ONLY_AST to compile() get the same guarantee in maintenance branches as the bytecode format - that is, unless it's absolutely necessary, we'll keep it the same. Otherwise anyone trying to write tools to manipulate the AST is in for a massive world of hurt. Anyone have any problems with this, or can it be added to PEP 6? It's possible we should poll developers of other Python implementations and find out if anyone has objections to supporting this AST format. But in principle, it sounds like a good idea to me. I think it's extremely likely that the AST format will change over time - with major releases. I'd just like to guarantee that we won't mess with it other than that. Anthony -- Anthony Baxter [EMAIL PROTECTED] It's never too late to have a happy childhood. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] AST structure and maintenance branches
On 9/28/06, Anthony Baxter [EMAIL PROTECTED] wrote: On Friday 29 September 2006 00:30, Jeremy Hylton wrote: On 9/23/06, Anthony Baxter [EMAIL PROTECTED] wrote: I'd like to propose that the AST format returned by passing PyCF_ONLY_AST to compile() get the same guarantee in maintenance branches as the bytecode format - that is, unless it's absolutely necessary, we'll keep it the same. Otherwise anyone trying to write tools to manipulate the AST is in for a massive world of hurt. Anyone have any problems with this, or can it be added to PEP 6? It's possible we should poll developers of other Python implementations and find out if anyone has objections to supporting this AST format. But in principle, it sounds like a good idea to me. I think it's extremely likely that the AST format will change over time - with major releases. I'd just like to guarantee that we won't mess with it other than that. Good point. I'm fine with the change, then. Jeremy ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Python Doc problems
xah lee [EMAIL PROTECTED] wrote: There are a lot reports on the lousy state of python docs. I'm not much in the python community so i don't know what the developers are doing anything about it. I don't know about everyone else, but when I recieve comments like the docs are lousy, fix them, it is more than a bit difficult to know where to start, and/or what would be better. Case-by-case examples of the phrasing of the docs here is confusing are helpful, as are actual documentation patches (even plain text is fine). While I have heard comments along the lines of the docs could be better, I've never heard the claim that the Python docs are lousy. anyway, i've rewrote the Python's RE module documentation, at: http://xahlee.org/perl-python/python_re-write/lib/module-re.html and have recently made the term of user clear. Aside from a few sections in the original docs, and also some sections in your docs, about the only part of the original docs that I find unclear is that some sections do not have function names sorted lexically. This is confusing compared to other module documentation available in the stdlib. I would also like to make one comment about your updated docs (I didn't read them all, I'm on vacation); In the section about 'Regex Functions' you used r'[EMAIL PROTECTED]' as a regular expression for an email address in information about the search() function. This particular RE will only give results for the simplest of email addresses. I understand that you wanted to provide an example, but providing a generally broken example will be detrimental to newer Python RE users, especially those who were looking for a regular expression for email addresses. I would say slim it down to domain names, but even the correct RE for domain names (with or without internationalization) is ugly. I don't currently have an idea of what kind of example would be simple and illustrative, but maybe someone else has an idea. may i ask what the python developers is doing about the python's docs? Are you guys aware, that there are rampant criticisms of python docs and many diverse tries by various individuals to rewrite the doc by starting another wiki or site? If there are rampant criticisms of the Python docs, then those that are complaining should take specific examples of their complaints to the sourceforge bug tracker and submit documentation patches for the relevant sections. And personally, I've not noticed that criticisms of the Python docs are rampant, but maybe there is some I hate Python docs newsgroup or mailing list that I'm not subscribed to. While I personally think that having a wiki attached to the documentation is a decent idea, I fear that we would run into a situation like php, where the documentation is so atrocious that users need to comment on basically every function in every package to understand what the heck is going on. - Josiah ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] difficulty of implementing phase 2 of PEP 302 in Python source
On 9/27/06, Phillip J. Eby [EMAIL PROTECTED] wrote: At 05:26 PM 9/27/2006 -0700, Brett Cannon wrote:Ah, OK.So for importing 'email', the zipimporter would call the .pycimporter and it would ask the zipimporter, can you get me email.pyc? and if it said no it would move on to asking the .py importer for email.py, etc.Yes, exactly.That's fine.Just thinking about how the current situation sucks for NFSbut how caching just isn't done.But obvoiusly this could change. Well, with this design, you can have a CachingFilesystemImporter as yourstorage mechanism to speed things up. Of course, to fully support .pyc timestamp checking and writeback, you'd need some sort of stat or getmtime feature on the parent importer, as well as perhaps an optional save_data method.These would be extensions to PEP 302, but welcome ones. Could pass the string representing the location of where the string came from.That would allow for the required stat calls for .pyc files as needed without having to implement methods just for this one use case.Huh?In order to know if a .pyc is up to date, you need the st_mtime ofthe .py file.That can't be done in the parent importer without giving it format knowledge, which goes against the point of the exercise.Sorry, thought .pyc files based whether they needed to be recompiled basedon the stat info on the .py and .pyc file, not on data stored from within the .pyc .It's not just that (although I believe it's also the case that there is atimestamp inside .pyc), it's that to do the check in the parent importer,the parent importer would have to know that there is such a thing as .py-and-.pyc.The whole point of this design is that the parent importerdoesn't have to know *anything* about filename extensions OR how thosefiles are formatted internally.In this scheme, adding more child importers is sufficient to add all the special handling needed for.py/.pyc-style schemes.Of course, for maximum flexibility, you might want get_stream() andget_file() methods optionally available, since a .so loader really needs a file, and .pyc might want to read in two stages.But the child importerscan be defensively coded so as to be able to live with only aparent.get_data(), if necessary, and do the enhanced behaviors only ifstat() or get_stream() or write_data() etc. attributes are available on the parent.Yeah, how to get the proper information to the data importers is going to be the trick. If we get some standards for these additional attributes, we can documentthem as standard PEP 302 extensions.The format importer mechanism might want to have something like'sys.import_formats' as a list of importer classes (or factories).Parent (storage) importer classes would then create instances to use.If you add a new format importer to sys.import_formats, you would of courseneed to clear sys.path_importer_cache, so that the individual importers are rebuilt on the next import, and thus they will create new child importerchains.Yeah, that pretty much ought to do it.I will think about it, but I am still trying to get the original question of how bad the C code is compared to rewriting import in Python from people. =) -Brett ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] difficulty of implementing phase 2 of PEP 302 in Python source
At 11:25 AM 9/28/2006 -0700, Brett Cannon wrote: I will think about it, but I am still trying to get the original question of how bad the C code is compared to rewriting import in Python from people. =) I would say that the C code is *delicate*, not necessarily bad. In most ways, it's rather straightforward, it's actually the requirements that are complex. :) A Python implementation, however, would be a good idea to have around for PyPy, Py3K, and other versions of Python, and as a refactoring basis for writing any new C code. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] weakref enhancements
i'd like to suggest adding weak attributes and weak methods to the std weakrefmodule. weakattrs are weakly-referenced attributes. when the value they reference is no longer strongly-referenced by something else, the weakattrs nullify themselves. weakmethod is a method decorator, like classmethod et al, that returns weaklybound methods. weakmethod's im_self is a weakref.proxy to `self`, which meansthe mere method will not keep the entire instance alive. instead, you'll get a ReferenceError.i think these two features are quite useful, and being part of the stdlib, would provide programmers with easy-to-use solutions to object-aliveness issues.more info, examples, and suggested implementation: * http://sebulba.wikispaces.com/recipe+weakattr* http://sebulba.wikispaces.com/recipe+weakmethod -tomer ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] difficulty of implementing phase 2 of PEP 302 in Python source
Phillip J. Eby schrieb: At 11:25 AM 9/28/2006 -0700, Brett Cannon wrote: I will think about it, but I am still trying to get the original question of how bad the C code is compared to rewriting import in Python from people. =) I would say that the C code is *delicate*, not necessarily bad. In most ways, it's rather straightforward, it's actually the requirements that are complex. :) A Python implementation, however, would be a good idea to have around for PyPy, Py3K, and other versions of Python, and as a refactoring basis for writing any new C code. FYI, Gordon McMillan had a Python 'model' of the import mechanism in his, (not sure if it was really named) iu.py. It was part of his installer utility, maybe the code still lives in the PyInstaller project. IIRC, parts of pep 302 were inspired by his code. Thomas ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] weakref enhancements
Also, I question the utility of maintaining a weakref to a method or attribute instead of holding one for the object or class. Strike that paragraph -- the proposed weakattrs have references away from the object, not to the object. Raymond ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] difficulty of implementing phase 2 of PEP 302 in Python source
Phillip J. Eby schrieb: I would say that the C code is *delicate*, not necessarily bad. In most ways, it's rather straightforward, it's actually the requirements that are complex. :) From what I recall, that's right. The C code's main disadvantage is that it isn't very well commented (as far as I recall) and there's no documentation of precisely what it's trying to achieve (insofar as there isn't a precise spec for how importing works in the Python docs, covering all the subtleties of things like package imports, package __path__ entries, reloading, etc etc...) A Python implementation, however, would be a good idea to have around for PyPy, Py3K, and other versions of Python, and as a refactoring basis for writing any new C code. It would also provide the basis of a much better spec - both because a clear spec would need to be established before you could write it, and because Python code is inherently readable... On 9/28/06, Thomas Heller [EMAIL PROTECTED] wrote: FYI, Gordon McMillan had a Python 'model' of the import mechanism in his, (not sure if it was really named) iu.py. It was part of his installer utility, maybe the code still lives in the PyInstaller project. IIRC, parts of pep 302 were inspired by his code. That's right. Lots of the path importer and metapath stuff came from iu.py. I have an oldish copy (Installer 5b5_2, from 2003) if you can't get it anywhere else... Paul. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] weakref enhancements
I'm sceptical that these would find use in practice. [..] Also, I question the utility of maintaining a weakref to a method or attribute instead of holding one for the object or class. As long as the enclosing object or class lives, so too will their methods and attributes. So what is the point of a tighter weakref granualarity?i didn't just came up with them out of boredom, i have had specific use cases for these, mainly in rpyc3000... but since the rpyc300 code base is still far from completion, i don't want to give examples at this early stage.however, these two are theoretically useful, so i refactored them out of my code into recipes.-tomerOn 9/28/06, Raymond Hettinger [EMAIL PROTECTED] wrote: Also, I question the utility of maintaining a weakref to a method or attribute instead of holding one for the object or class.Strike that paragraph -- the proposed weakattrs have references away from the object, not to the object.Raymond ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] weakref enhancements
On 9/28/06, tomer filiba [EMAIL PROTECTED] wrote: I'm sceptical that these would find use in practice. [..] Also, I question the utility of maintaining a weakref to a method or attribute instead of holding one for the object or class. As long as the enclosing object or class lives, so too will their methods and attributes. So what is the point of a tighter weakref granualarity? i didn't just came up with them out of boredom, i have had specific use cases for these, mainly in rpyc3000... but since the rpyc300 code base is still far from completion, i don't want to give examples at this early stage. however, these two are theoretically useful, so i refactored them out of my code into recipes. I've had use cases for weakrefs to boundmethods (and there IS a Cookbook recipe for them), as follows: sometimes I'm maintaining a container of callables, which may be of various kinds including functions, boundmethods, etc; but I'd like the mere presence of a callable in the container not to keep the callable alive (especially when the callable in turn keeps alive an object with possibly massive state). In practice I use wrapping and tricks, but it would be nice to have cleaner standard library support for this. (Often the container needs to be some form of a Queue.Queue, since queues of callables are a form I use very often to dispatch work requests to worker-threads in a threadpool). Alex ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] weakref enhancements
[Alex Martelli] I've had use cases for weakrefs to boundmethods (and there IS a Cookbook recipe for them), Weakmethods make some sense (though they raise the question of why bound methods are being kept when the underlying object is no longer in use -- possibly as unintended side-effect of aggressive optimization). I'm more concerned about weakattr which hides the weak referencing from client code when it is usually the client that needs to know about the refcounts: n = SomeClass(x) obj.a = n del n # hmm, what happens now? If obj.a is a weakattr, then n get vaporized; otherwise, it lives. It is clearer and less error-prone to keep the responsibility with the caller: n = SomeClass(x) obj.a = weakref.proxy(n) del n # now, it is clear what happens The wiki-space example shows objects that directly assign a copy of self to an attribute of self. Even in that simplified, self-referential example, it is clear that correct functioning (when __del__ gets called) depends knowing whether or not assignments are creating references. Accordingly, the code would be better-off if the weak-referencing assignment was made explicit rather than hiding the weak-referencing wrapper in a descriptor. Raymond ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] weakref enhancements
On 9/28/06, Raymond Hettinger [EMAIL PROTECTED] wrote: [Alex Martelli] I've had use cases for weakrefs to boundmethods (and there IS a Cookbook recipe for them), Weakmethods make some sense (though they raise the question of why bound methods are being kept when the underlying object is no longer in use -- possibly as unintended side-effect of aggressive optimization). There are *definitely* use cases for keeping bound methods around. Contrived example: one_of = set([1,2,3,4]).__contains__ filter(one_of, [2,4,6,8,10]) -bob ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] weakref enhancements
There are *definitely* use cases for keeping bound methods around. Contrived example: one_of = set([1,2,3,4]).__contains__ filter(one_of, [2,4,6,8,10]) ISTM, the example shows the (undisputed) utility of regular bound methods. How does it show the need for methods bound weakly to the underlying object, where the underlying can be deleted while the bound method persists, alive but unusable? Raymond ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] weakref enhancements
On 9/28/06, Raymond Hettinger [EMAIL PROTECTED] wrote: There are *definitely* use cases for keeping bound methods around. Contrived example: one_of = set([1,2,3,4]).__contains__ filter(one_of, [2,4,6,8,10]) ISTM, the example shows the (undisputed) utility of regular bound methods. How does it show the need for methods bound weakly to the underlying object, where the underlying can be deleted while the bound method persists, alive but unusable? It doesn't. I seem to have misinterpreted your Weakmethods have some use (...) sentence. Sorry for the noise. -bob ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] weakref enhancements
Raymond Hettinger wrote: Also, I question the utility of maintaining a weakref to a method or attribute instead of holding one for the object or class. As long as the enclosing object or class lives, so too will their methods and attributes. So what is the point of a tighter weakref granualarity? I think you're misunderstanding what the OP means. A weak attribute isn't a weak reference to an attribute, it's an attribute that holds a weak reference and is automatically dereferenced when you access it. A frequent potential use case is parent-child relationships. To avoid creating cycles you'd like to make the link from child to parent weak, but doing that with raw weakrefs is somewhat tedious and doesn't feel worth the bother. If I could just declare the attribute to be weak and then use it like a normal attribute from then on, I would probably use this technique more often. So, before being entertained for addition to the standard library, this idea should probably first be posted as an ASPN recipe, That's a reasonable idea. -- Greg ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Python Doc problems
Josiah Carlson writes: fine). While I have heard comments along the lines of the docs could be better, I've never heard the claim that the Python docs are lousy. FYI, I have heard this, recently, from Tom Lord (aka developer of Arch, rx, guile, etc). Since he also took a swipe at Emacsen, I pressed him on what he meant. He immediately backtracked on (all) Python docs and lousy, but did say that in his opinion scripting languages that provide docstrings have lost a fair amount of coherence in their documentation, and that Python's are consistent with the general trend. (He's started using Python relatively recently and does not claim a historical perspective.) What is lost according to him is information about how the elements of a module work together. The docstrings tend to be narrowly focused on the particular function or variable, and too often discuss implementation details. On the other hand, manuals tend to become either tutorials or compedia of the docstrings. If there are rampant criticisms of the Python docs, then those that are complaining should take specific examples of their complaints to the sourceforge bug tracker and submit documentation patches for the relevant sections. What they *should* do, but don't, is not necessarily a reflection on the accuracy of what they say. FWIW ... I find the documentation for the language, the standard library, and the Python applications I use quite adequate for my own use. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] Python Doc problems
xah lee writes: anyway, i've rewrote the Python's RE module documentation, at: http://xahlee.org/perl-python/python_re-write/lib/module-re.html -1 The current docs could be improved (but not by me, at least not today), but I don't consider the general direction of Xah's edits desirable. Eg, the current table of contents is just as accurate and more precise than Xah's top node, which makes navigation faster for someone who knows what he forgot.wink In general his changes improve the narrative flow, but for me that's a very low priority in a reference manual, while the cost in loss of navigability of his changes is pretty high for me. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Python Doc problems
[EMAIL PROTECTED] wrote: xah lee writes: anyway, i've rewrote the Python's RE module documentation, at: http://xahlee.org/perl-python/python_re-write/lib/module-re.html -1 The current docs could be improved (but not by me, at least not today), but I don't consider the general direction of Xah's edits desirable. Eg, the current table of contents is just as accurate and more precise than Xah's top node, which makes navigation faster for someone who knows what he forgot.wink In general his changes improve the narrative flow, but for me that's a very low priority in a reference manual, while the cost in loss of navigability of his changes is pretty high for me. 'Fraid that doesn't get him any nearer his hundred bucks, then. Xah: the money it still on offer should you choose to rewrite until the criteria are satisfied. regards Steve -- Steve Holden +44 150 684 7255 +1 800 494 3119 Holden Web LLC/Ltd http://www.holdenweb.com Skype: holdenweb http://holdenweb.blogspot.com Recent Ramblings http://del.icio.us/steve.holden ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Python Doc problems
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On Sep 28, 2006, at 8:49 PM, [EMAIL PROTECTED] wrote: What is lost according to him is information about how the elements of a module work together. The docstrings tend to be narrowly focused on the particular function or variable, and too often discuss implementation details. On the other hand, manuals tend to become either tutorials or compedia of the docstrings. There's no doubt that writing good documentation is an art form. There's also the pull between wanting to write reference docs for those who know what they've forgotten (I love that phrase!) and writing the introductory or how it hangs together documentation. It's not easy at all, and some of Python's documentation does better at this than others. In the vast array of FOSS and for-pay docs I've read in my career, Python actually ain't too bad. :) - -Barry -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.5 (Darwin) iQCVAwUBRRx+AXEjvBPtnXfVAQJgNgP8D9f2ZUqIDTUmQU8BRx4iqjbXQANrdHt1 usZCwguIS4pa0pmUp73E514y+tDs1UzU1E2I2itIifqtKXZuPOSZYG/DWcg4h8vh KPCygqSDNiW5dr77UP4QBXk3DOoj68E/WpLWOquoLB/eOYWOa08lh+XEJ9ShHF1F WfHMygrtpqk= =vEEN -END PGP SIGNATURE- ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Python Doc problems
Barry Warsaw wrote: There's also the pull between wanting to write reference docs for those who know what they've forgotten (I love that phrase!) and writing the introductory or how it hangs together documentation. The trick to this, I think, is not to try to make the same piece of documentation serve both purposes. An example of a good way to do it is the original Inside Macintosh series. Each chapter started with a narrative-style About this module kind of section, that introduced the relevant concepts and explained how they fitted together, without going into low-level details. Then there was a Reference section that systematically went through and gave all the details of the API. While Inside Mac could often be criticised for omitting rather important info in either section now and then, I think they had the basic structure of the docs right. -- Greg ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
