[Pythonmac-SIG] Implementing help

[Roger Binns]

For the BitPim project I currently use the wxWidgets way of doing help,  
authored using HelpBlocks.  Behind the scenes it amounts to various  
HTML files dumped into a zip file and given a .htb extension.   
HelpBlocks also makes a Windows format help file (CHM) and I use the  
native Windows help api to load and display that help on Windows.  I  
want to produce a tool that can take any wxWidgets format help file and  
transform it into a directory that can be used by the Apple help APIs  
(AHRegisterHelpBook and AHGotoPage).  These are the steps I took in  
compliance with Apple's doc:

http://developer.apple.com/documentation/Carbon/Conceptual/ 
ProvidingUserAssitAppleHelp/index.html

 - Make a directory somewhere
 - Extract resources/bitpim.htb using unzip into that directory (you
   can find this file if you peek inside the standard download of
   BitPim for Mac)
 - Edit welcome.htm to add a tag in the head section:
          <META ="AppleTitle" CONTENT="BitPim help">
 - Drag and drop the folder onto the help indexing tool. It is in
   /Developer/Applications/Utilities.  (For some reason Apple go
   out of their way to ensure you can't run this tool from the
   command line).
If I call AHGotoPage (which is the only API I want to call), the page  
displays correctly but the search widget does nothing and claims to be  
in a book (null).  I couldn't figure out what to do to get  
AHRegisterHelpBook to accept the directory since Apple's doc helpfully  
leaves that information out.  I assume some sort of directory structure  
is needed as well as a property list somewhere (the doc is vague).

Note that I am not trying to put something within my application  
bundle.  I just want a standalone directory with non-localised help  
content that I can use from an application if I happen to know where  
the directory ended up.  And I want to be able to do this  
transformation from pure Python code (ie no dragging and dropping or  
using an interactive property list editor).  As an alternative I would  
settle for an extra option to py2app where I can give the path of the  
.htb file and have it do the right thing.

BTW I have found the Mac support in Python quite a bit harder to work  
with than the corresponding stuff for Windows (win32all).  In  
particular most of the documentation is empty and there are no  
examples.  Most of the APIs like to return MacOS.Error: (-50, 'error in  
user parameter list').  Things are more complicated by the  
corresponding C API documentation going on about types like FSRef and  
CFStringRef so I couldn't be sure if I was supposed to call some  
constructor in Carbon.CF or if it was fine just passing in Python  
strings.  I am still not sure if AhRegisterHelpBook isn't working  
because I have the wrong types or because the underlying API doesn't  
like whatever directory structure and contents I am supposed to have  
but Apple didn't document.

Roger
_______________________________________________
Pythonmac-SIG maillist  -  Pythonmac-SIG@python.org
http://mail.python.org/mailman/listinfo/pythonmac-sig