[Python-Dev] RE: [Doc-SIG] pydoc.py (show docs both inside and outside of Python)

[Tony J Ibbs (Tibs)]

I mentioned a "spurious"
>	The system cannot find the path specified.

on NT, and Ka-Ping Yee said:
> Thanks for the NT testing.  That's funny -- i put in a special case
> for Windows to avoid messages like the above a couple of days ago.
> How recently did you download pydoc.py?  Does your copy contain:
>
>     if hasattr(sys, 'winver'):
>         return lambda text: tempfilepager(text, 'more')

Hmm. I downloaded it when I read the email message announcing it, which
was yesterday some time. But it doesn't look like the lines you mention
are there - I'll try re-downloading...

...I've redownloaded the files from http://www.lfw.org/python/pydoc.py,
etc., and done a grep for hasattr within them. There's no check such as
the one you mention, so I guess it's "download impedance".

> So you can see what i'm up to, here's my current to-do list:
>
>     make boldness optional (only if using more/less?  only Unix?)

probably sensible. By the way, I don't get boldness on the NT box - any
chance (he says, not intending to help *at all* in doing it!) of it
happening there as well? (or would that depend on what curses support is
built into the Python?)

>     document a .py file given on the command line

also allow for a directory module (i.e., something with __init__.py in
it) given on the command line?

>     write a better htmlrepr (\n should look special, max
>     length limit, etc.)

yes, but these things can always get better - the fact it's working
allows for improoooovement down the line.

>     generate HTML index from precis and __path__ and package

a neat idea - definitely Good Stuff!

>     contents list

well, I always do these, so I'm for this one as well

>     have help(...) produce a directory of available things to
>     ask for help on

bouncy fun!

>     Windows and Mac testing

I'm running Windows 98 with Python 1.5.2 at home, and will willingly try
it out on that (after all, it's not a very big download) - although it
might sometimes take a day or two to get round to it (for instance, I
haven't yet done so!). But I suspect I shan't be a very demanding
user...

>     default to HTTP mode on GUI platforms?  (win, mac)
>
> The ones marked with + i consider done.  Feel free to comment on
> or suggest priorities for the others; in particular, what do you
> think of the last one?  The idea is that double-clicking on
> pydoc.py in Windows or MacOS could launch the server and then open
> the localhost URL using webbrowser.py to display the documentation
> index.  Should it do this by default?

I'll leave that to better designers than myself (although if one is to
*have* a double click action, that seems sensible to me).

(looks up webbrowser.py - ah, a 2.0 module). Personally, I'd also like
to have the option of having a "mini-browser" supported directly,
perhaps in Tkinter, so I don't need to start up a whole web browser. But
again I may be odd in that wish (I can't remember what IDLE does).

Oh - that also means "integrate into IDLE" presumably goes on at least a
WishList as well...

Other ideas:
* command line switch to *output* HTML to a file (i.e., documentation
generation) (presumably something like "-o <name>.html", where the
"html" indicates the output format - an alternative being "txt"
* if I ever finish the docutils effort (I should be getting back to it
soon) then use that to format the texts (this would mean I need not
worry about the "frontend" to docutils too much, since pydoc is already
doing so much). Or maybe the docutils tool should be importing pydoc...

Tibs (must do some (paid) work now!)

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"Bounce with the bunny. Strut with the duck.
 Spin with the chickens now - CLUCK CLUCK CLUCK!"
BARNYARD DANCE! by Sandra Boynton
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)