Sugar Maple Software

I recently wrote my first draft of documentation for my upcoming application. Integrating this documentation into Apple Help was much easier than I expected. The Apple Help Viewer simply displays HTML files. More impressively, cascading style sheets (CSS) are supported. I hope this will allow me to share the identical HTML files between my application and the support section of my web site and simply have different CSS files for each.

Cocoa Dev Central has a great tutorial that covers how to add HTML-based help to your Cocoa application. I also browsed Apple’s Providing User Assistance With Apple Help document. From reading this document, I picked up a an additional tip that I didn’t notice in the Cocoa Dev Central tutorial:

• Add an abstract to each page.

  The Providing User Assistance With Apple Help document states:

  An abstract is a brief description of a help topic that appears in the bottom frame of the Help Viewer window when the user selects that topic from a list of search results. Note: Beginning in Mac OS X version 10.2, Help Viewer displays the default text “No summary provided” for help topics without abstracts.

  This can be done with a meta tag:

  
  <meta name="description" content="How to invoke
     MyApplication via AppleScript.">
  

I also wanted to add a help button to my preference window that would launch the Help Viewer and display the page for the preference window. This was trivial:

- ( IBAction ) showPerferenceHelp : ( id ) sender
{
   AHGotoPage( CFSTR("MyApplication Help"),
      CFSTR("html/preferences.html"), NULL );
}

At first, I didn’t specify the all-important AppleTitle meta tag correctly. Once I fixed it, I still had a problem where Help Viewer wouldn’t display my application’s help when invoked from my application’s Help menu. I solved this by deleting the various Apple Help-related files from ~/Library/Preferences and ~/Library/Caches. Once I did that, everything worked great. So, if you can’t figure out why your help isn’t being displayed as expected, trash these files and try again.