Adding Apple help to an OS-X application

So this is not Swift related, but it is something many of us will encounter eventually: How to add Apple Help support to an application

I spend a full day trying to get this to work, and I failed. The document from Apple has errors in it, and there is precious little to find elsewhere on the inet. Though I did find one interesting blog entry on this here: Apple help in 2015. Unfortunately the hints and tips provided there also failed to work for me.

I did in fact give up after that. I took the alternative approach: connect the help menu to the AppDelegate and handle the help by opening up a html file that is located in the resources. Like this:

    @IBAction func displayHelp(sender: AnyObject?) {

        

        let url = NSBundle.mainBundle().URLForResource("help", withExtension: "html")

        

        NSWorkspace.sharedWorkspace().openURL(url!)

    }

Of course that worked... but it irked me. Why would the "normal" approach not work?

What I wanted was the most simple implementation that I could think of, no multi language support, no icon, no special features, no index file etc. Just a simple title with a few topics. I figured that when I can get that to work, the rest is a matter of legwork.

And then I had some luck... well, at least it finally started to make some sense after I read up on the Core Foundation Keys. With a little experimenting I finally had my first success.

Here is how it works for me:

First create the content, I created one main file (MyAppHelp.html) and a couple of topic files (Topic1.html, Topic2.html etc). The MyAppHelp.html linked to the Topic files in the usual way (<a href...)

In the MyAppHelp.html file I did not include anything special, no meta tags. Specifically no "AppleTitle" tag and no "Robots" tag. Just plain html content with links to the topic pages.

Next I created the folder hierarchy for the help book on my desktop and placed the html files in the Resources folder.

We need one more file, a property list. I simply copied a Info.plist from another app's help bundle and modified its content as follows:

The key's InfoDictionary version, Bundle OS Type code, Bundle creator OS Type code and HPDBookType should be exactly as above.

The HPDBookAccessPath should be the name of the top level html file. I think that if you put it in a subdirectory (e.g. English/MyAppHelp.html) the name of the subdirectory should be included, but in my example here just the name is sufficient.

The HPDBookTitle is important, it is used in the Info.plist of your application to identify the help book.

The Info.plist just created should reside at the Contents level of the help book hierarchy. The complete help book looks as follows:

Now rename the help book to create a bundle: MyAppHelp becomes MyAppHelp.help. When we do this, the icon changes to the Apple helpbook icon, and we can no longer simply open the folder. Remember that with Right-Click -> Show Package Contents we can still see what is inside.

Note: Even though the icon changed, this does not mean that we can double-click the help book to open it. That won't work. But it will work from within the application...

Now switch to the project in xcode. In Xcode select "Add Files" and choose the help book just created. Make sure that the files and folder structure is copied:

Almost done...

Now edit the Info.plist of the project to include the following two key's:

Forget about the "Help Book File" key, we don't need that.

It should be noted that the Help Book Identifier must have the same value as the HPDBookTitle from the help book Info.plist file. The Help Book directory name key is the name of the help book file that we added to the project.

That is it, launch the application and select "Help -> MyApp Help" from the menu. Voila!

PS: A neat trick is to create an alias into the Resources folder of the help book and place that somewhere at the top level of the project. Use that alias to quickly access the html files for updating etc. Also, most HTML editors will be unable to open a bundle, but they can follow an alias. Unfortunately Xcode will not see the modifications you make to the help book, but git will. So if you use git, the changes to the help book will be put in the repository, even if Xcode does not show the "M" behind the help book.

Happy coding...

Did this help?, then please help out a small independent.
If you decide that you want to make a small donation, you can do so by clicking this
link: a cup of coffee ($2) or use the popup on the right hand side for different amounts.
Payments will be processed by PayPal, receiver will be sales at balancingrock dot nl
Bitcoins will be gladly accepted at: 1GacSREBxPy1yskLMc9de2nofNv2SNdwqH

We don't get the world we wish for... we get the world we pay for.