[Pythonmac-SIG] On-line help; webbrowser problems

[Russell E Owen]

I'm trying to write an on-line help system for a cross-platform (unix 
and MacOS X at least, Windows would also be helpful) Python app. The 
sort of help needed tends to be verbose; tool tips aren't going to be 
useful.

My first thought was to write the help in HTML and use the webbrowser 
module to access it.

Unfortunately, I'm having trouble with webbrowser on MacOS X 10.2. I 
suspect it's intrinsic to limitations in the way the OS tries to do 
things. For example:
   webbrowser.open("file://...html#anchor")  # in Python
% open -a icab file://...html#anchor  # on the command line
open location "file://...html#anchor"  -- AppleScript in the Script Editor
all do the same two wrong things:
- The file is opened in whatever application created it, rather than 
in the default web browser. I can live with this, but it's not good. 
(A pain for users, and a pain for me as I usually have the creator as 
Pepper, my text editor).
- Even if it does open in a web brwoser, the anchor is ignored!!! 
This is nasty, as I don't want a hundred different tiny html files, 
one per help item.

So...any advice would be welcome.

- Any suggestions of a way to open an html file pointing to a given 
anchor within Python? Ideally I'd like the default Internet Config 
browser to be used, but at this point just about anything will do.

I fear I'm looking at learning how to send GetURL apple events from 
within python to a user-chosen browser. The docs suggest I'll need to 
create some sort of apple event dictionary for every possible 
browser, which sounds ghastly.

An alternative is to use a web server (I'm assuming http:// URLs are 
handled correctly). But that sounds horrible. Who'd serve the data? 
And to avoid synch problems, I'd have to keep a help set for every 
version of the software, and my URLs would have to include the 
version #.

- Any suggestions for a better way to do help?

I started out by putting the help text directly in the code. But then 
the help gets displayed in a dialog box of some kind. Modal dialogs 
are pretty gross but easy to do. Non-modal means a lot of clutter, 
unless I use one window and just replace the text when new help is 
requested. But that brings up the issue of navigation (it'll be 
frustrating to have none), which suggests a web browser...sigh.

- Should I report the problem with "open -a" and "open location" as a 
bug? (Anyone know how to report bugs to Apple?).

-- Russell

P.S. in case you've not stumbled across this gem: different browsers 
handle file:// URLs in different ways. Carbon apps (such as iCab) 
tend to favor file://localhost/HardDiskName/path whereas Cocoa apps 
(such as OmniWeb) leave out the hard disk name, making for a 
unix-like path.