Jason Earl wrote: > "msoulier" <[EMAIL PROTECTED]> writes: > > >> I have found the Python sidebar VERY helpful: > > > > Personally, I can't use local docs on my desktop as they may not be > > the same version of the docs for the Python distro running on the > > server that I'm deploying on. I usually go to python.org and use the > > wayback machine to look at the old docs for the release that I'm on. > > Why don't you instead install the info version of the Python > documentation on your server. Then you can do "info Python2.3-lib" > and have at it. If you are hacking in emacs then this is about as > slick a documentation system as you could ask for, but even if you use > some other editor info is a much better documentation tool than man.
You know, I'm pretty used to reading man pages. There's only a few simple keystrokes I need to remember, and the only time I ever touch "info" is when a very short man page tells me that the real docs are in info and I need to look there. At that point, I have to relearn how to use that info command. Info is complicated. It's got some concept of nodes being hierarcical, but also they seem to have some order to them (a la next and previous) as well. No idea what the connection between those is. Also it's got "cross- references" as well as menus -- dunno if they're different or not. Bah. Why not just use html and browse it with lynx/links/links2/elinks? I can't understand why we need two separate and distinct doc formats: man and info. My take: write your docs in some markup that can produce both man output and html. Done and done. Seems like two good candidates for that are epytext and reStructuredText ("reST"). > > But, if Python would match Perl for docs available on the > > command-line, then I'd have it all at my fingertips. I simply don't > > understand why this is not being done. When I'm coding in C, I use > > the manpages on the remote host so that I know the docs are correct > > for my target. Why can't I do that in Python? It's yet another thing > > that my Perl-using coworkers point out as a Python weakness. > > Python does match (and exceed) Perl for docs available on the command > line. Once you get used to using the excellent info-based Python > documentation using man is downright primitive. > > Jason I think that may be wishful thinking. When I use the pydoc command, I mostly get *very* short API docs with *no* example code or tutorial notes at all. Contrast that with perldoc which is categorized and complete docs for the entire language plus tutorials, faqs, ports info, ... I mean, have a look over at http://perldoc.perl.org/perl.html -- everything there is at your fingertips from the terminal! And it's written by folks like Larry, Dominus, Randal Schwartz, Tom Christiansen, et al. I've never come across a FLOSS software project with docs as good as Perl's. Now, the one big thing we have going for us is that since Python is a simpler language, so it needs few docs overall anyway. :) ---John http://www.simisen.com/jmg/cpd/ -- http://mail.python.org/mailman/listinfo/python-list