[EMAIL PROTECTED] <[EMAIL PROTECTED]> wrote: > IMO, Perl has docs nailed. I learned Perl before coming > to Python, and I can tell you that their docs kick butt. > I believe the reason why is (besides Larry's excellent > and entertaining writing) because of perldoc. Here's how > it works: they write special doc directives into their .pl > files that the interpreter ignores, but that the perldoc > command processes into a manpage for you. This is a *bit* > like what pydoc does, only pydoc just regurgitates docstrings, > while perldoc formats special directives into headings, code > listings, bulleted lists, etc.
As another perl refugee I agree with you 100% here. "perldoc perltoc" then "perldoc xxxx" will find you anything in perl. Its frustrating that pydoc is only half (or less) of the docs. However having bedded into python for a few years, I now just reach for my web browser for the global module index instead of pydoc. Its not as good as perldoc as it doesn't cover all the modules I've got installed, but its very good documentation. Some modules have good pydoc-umentation but not all of them. Code examples tend to be missing. I think a major problem with our way of thinking about perldoc/pydoc/man pages is that it is a) unix centric, and b) possibly a bit old fashioned! a) and b) apply to perl certainly, but I don't think they apply to python in the same way. I'd love to have a unified documentation system where *all* the documentation for *all* installed modules was available to pydoc *and* the web browser and *all* this documentation was in .py files. (Putting the code together with the documentation is essential in my opinion and experience - if you seperate the two then the documention will lag the code.) PS I've used reST and perldoc. reST is easier to use for the easy things, but gets complicated for the hard things. -- Nick Craig-Wood <[EMAIL PROTECTED]> -- http://www.craig-wood.com/nick -- http://mail.python.org/mailman/listinfo/python-list
