After spending the better part of a day trying to figure why the help book wouldn’t open in Help Viewer, I finally discovered the reason. Hopefully anyone else trying to dig through Apple’s surprisingly verbose, yet conflicting and confusing documentation will stumble across this.

In general, there are quite a few hoops to jump through to get a help book up and running. And some additional ones to get it in a preference pane. But even if you follow Apple’s instructions, you’ll just get the annoyingly non-specific error “Help Viewer cannot open this content”.

The problem is, as usual for preference panes, that the bundle is not the app’s bundle, but rather a guest bundle to System Preferences.app. When Apple says that a help book is automatically registered, they mean the main bundle’s help book. For a preference pane, you have to manually register it.

In Snow Leopard, that’s just a couple lines of code using NSHelpManager, which you can drop somewhere like awakeFromNib:

NSBundle *myBundle = [NSBundle bundleForClass:[self class]];
[[NSHelpManager sharedHelpManager] registerBooksInBundle: myBundle];

In earlier versions of Mac OS X, you’ll have to use AHRegisterHelpBook() from Carbon’s Help framework (it’s quite annoying to have to link an otherwise 100% Cocoa app to Carbon just for this). It requires a few more lines of code, but the effect is the same:

FSRef fsref;
NSBundle *myBundle = [NSBundle bundleForClass:[self class]];
NSString *path = [myBundle bundlePath];
NSURL *url = [NSURL fileURLWithPath:path];
if (CFURLGetFSRef((CFURLRef)url, &fsref)) {
	OSStatus err = AHRegisterHelpBook(&fsref);
	if (err) // Do error stuff
}

Posted on Thursday, April 15th, 00:22. Filed under: Cocoa, Mac OS X, Xcode