The AppleScript Studio Workshop

Once you make some progress in your application you might want to add some offline help files that can be displayed by choosing “Your_Application_Name Help” from the Help menu. Below are some instructions on how you can do this, along with an XCode project you can download to work with.

1. Create your files using your favorite HTML application. You can have images and CSS files as well. Put all these files into a folder and give it a name. For my example, I will call the folder “Help Folder Example Help” since my application will be called “Help Folder Example”

2. Each file must have an additional META tag added inside the HEAD tag near the top of your HTML files with the title of your application and “Help”:

3. After you have finished making all your help files, open the application “Help Indexer” found in your Developer/Utilities folder. Navigate and choose the folder containing all your HTML, CSS, and images. This will create an “index” for your help files which can be used to search your files in the help browser.

4. Back in XCode, right-click on your “Resources” folder on the left and choose Add – “Existing Files…” choosing your folder with the help files and the newly created index. When you are given some more options, this seems to work for me:

This should result in the files being added to your project, looking something like this:

You then need to add two keys to your “Info.plist” plist file, one indicating the name of your application’s help book, and the other the name of your help folder. In my example, here is what I needed to add:

CFBundleHelpBookName
Help Book Example Help
CFBundleHelpBookFolder
Help Book Example Help

5. Finally, you probably want to change the “Title” of the help menu item in “Interface Builder” to something like “Help Book Example Help” (in my case) so that it doesn’t say “NewApplication Help” when it is run. You can find the help menu item in the “1” menu under “2”

Now try compiling and running your application and the help book’s index.html home page should appear. My biggest complaint with the Help Book browser in OS X is that even simple files seem to load relatively slow; slower than running files directly in Safari for example. I am often reluctant to read help files since the help book takes one or two seconds longer to load than I am willing to wait for an answer. In the same time I can google a question online rather than risk the possibility that the help files are sorely lacking in documentation.

You can download the sample XCode project demonstrating the above here: Help Book Example

In order to write this posting and learn the techniques described here, I depended on these useful websites: a MacScripter posting on the topic and this excellent tutorial in French (I just looked at the pictures and guessed what I could from the accompanying text but the author recommends using Google to translate the site).