Help !?!, How to integrate a helpfile in my application

In every (non trivial) application we need help. When developping a Cocoa application using XCode we get the foundation for help for free. (In Interface builder their is a menubar foreseen for your window, in that menubar you see the menuitem Help).

By default , the help menuitem is connected to the showHelp: method of the firstResponder (or in the chain up of responders).
Now you can do 2 things, first is to override the default implementation of the showHelp: in your firstResponder :

- (void) showHelp: (id) sender { NSString* help = [[NSBundle mainBundle] pathForResource:@"Some Help" ofType:@"html"]; NSURL* url = [NSURL fileURLWithPath:help]; [[NSWorkspace sharedWorkspace] openURL: url]; }

The above method (I found this code on the Internet) will open a html file (Some Help.html) in a seperate browser.
Of course you need first to add the file to your project, otherwise it will not be published in the application bundle.

(To do this in XCode : open the folder 'Resources' , the press CTRL-, a context menu will appear and you select 'Existing files' ) :



This rather cumbersome, and your help is not nicely integrated in Apple's HelpViewer.

So a second solution is to use the HelpViewer functionality. And now a whole quest started....
I first started to read the Apple documentation on the subject, but it seems that the documentation is written by experts and for experts (preferably working at Apple).
I followed the instructions line by line and the only thing I got was the HelpViewer coming up with a blank page.

After hours of frustration (I almost threw my MacBook thru the window) and searching on the Internet I finally found a way to integrate my help files with HelpViewer.
So here are the steps to follow to get it done :

1. Create your help files and put them in folder (for example 'MyApplication Help' ). this folder will usually be a subfolder in your project. In the first page of your help (your homepage of the help) you need to add a meta tag in the head section :

<META NAME="AppleTitle" CONTENT="MyApplication Help">

ps: MyApplication Help is the name of your help book

2. Run the HelpIndexer, this utility can be found in Developer>Applications>Utilities. In the HelpIndexer you first select the folder in which you dropped your help files and then you press 'create index'.

3. Then you go to XCode (I assume your project is open) and then via Finder you drag-and-drop the help folder in the resources folder of your project.

4. In the Info.plist file you need to add to key-value pairs as follow :
key : CFBundleHelpBookFolder
string: MyApplication Help

key: CFBundleHelpBookName
string:MyApplication Help

5. Now you need to rebuild your XCode project, before you do a build first do clean all targets, otherwise your Info.plist will not be processed.

When you run now your application and press help, you'll see your help file appearing in the HelpViewer.
Also note that when you click the home button in HelpViewer you'll see your help appearing in the list of help book's.