Apple help

Enough of my time has been wasted by this.  I have been trying to get  
BitPim to use the native help system on Mac.  In the end I failed due  
to gaping holes in Apple's documentation.  If someone else can figure  
out the answers to these questions I'll go ahead and change things,  
otherwise you'll just have to stick with wxWidgets help system.

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

You can turn the BitPim help into help that conforms with the above by  
doing the following:

  - Make a directory somewhere
  - Extract resources/bitpim.htb using unzip into that directory
  - 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).

According to the doc that is all that is necessary to make a  
non-localized help book.  To use it you can do the following:

   import Carbon.AH
   Carbon.AH.AHGotoPage(None, "file:///path/to/welcome.htm", None)

That will correctly bring up the help.  However the search function  
won't work, and it thinks the book title is (null).  (So what exactly  
was the point of the meta tag above then?  Why does it ignore the index  
it created?)

Presumably some pieces are missing.  Maybe you have to use the  
Carbon.AH.AHRegisterHelpBook function (I couldn't find any parameter  
that would not give an error).  There is probably a property list file  
that should be somewhere although the online documentation doesn't say  
where (in that directory, in a parent directory, somewhere else?).  It  
also doesn't say how to create a property list from the command line  
even if I knew where to put it, nor what it actually needs to contain.

Note that I am trying to create a standalone non-localized help book  
that is not part of any other bundle or even of BitPim, and do so  
entirely from the command line.

And I have to admit that the more I use MacOS, the less and less  
impressed I am.  It feels very comparable to Linux GUI environments  
with applications randomly incomplete, appalling documentation, lots of  
unpolished corners and some sort of promise that you should excuse all  
this because of how much better it will be in the future.

Roger



-------------------------------------------------------
This SF.Net email is sponsored by: IntelliVIEW -- Interactive Reporting
Tool for open source databases. Create drag-&-drop reports. Save time
by over 75%! Publish reports on the web. Export to DOC, XLS, RTF, etc.
Download a FREE copy at http://www.intelliview.com/go/osdn_nl