How do I add help to my application that works in Help Viewer?

Help books are just HTML files contained in their own folder. Yep, just like a website! You create an index page that will be the “landing zone” when one of your users selects the help menu item in your application. You can add as many or as few pages as you need to explain your application. If you need or want images, just create an images folder in your help book’s folder and in your pages use relative URL’s to reference them. So for a graphic, you would use href=“images/yourgraphic.jpg” rather than a full URL.

In order to convince the Help Viewer that your help book is legit, you must include the following meta tag in the section of your index page:

<meta name="AppleTitle" content="YourAppName Help">

There are other tags for setting the default font, default search font, chapter order and icon (to be used in the list of available help books). But the AppleTitle tag is the only one that must be present.

To provide your users the ability to search your help, you need to index your help pages. To do this, drop your help folder on the Help Indexer application in the Utilities folder of your Developer tools. An index file is created and put into your folder with your HTML files.

Once you’ve indexed your HTML pages and they work the way you want them to (I suggest viewing them in Safari first), you again use the Add Existing Files… context menu item to add the help folder to your project. When the copy dialog pops up, be sure to mark the “Add folder references” item, or your help won’t work. Why? Because one of the pieces of information you must provide XCode is the name of your help folder!

The other information you must provide to XCode is the name of the help book as you want it to appear in Help Viewer. To provide these 2 pieces of information you add 2 keys to the info.plist of your project in this form:

<key>CFBundleHelpBookName</key> <string>YourApp Help</string> <key>CFBundleHelpBookFolder</key> <string>YourApp Help</string>
Your folder name doesn’t have to match the name of the help book, but for convenience sake most developers name them the same.

That’s it. At this point, re-build your app and try out the help menu item. Thanks to Cocoa’s underlying framework, your user can initiate a help session with Help Viewer.