Monday, March 20, 2006

Cocoa Help System

Today I wasted almost the whole day figuring out how to get the Cocoa help system working. I read guides and tutorials and every time I did I got more and more angry at the articles going on about how simple it was to get working, "I just worked like magic". Well, I found other users didn't quite agree, and I am definitely one of them. One thing that can take some time getting used to with Cocoa is that naming convention is so important. If you don't give things the right name and are consistent, things easily get screwed up. So to help others to avoid trouble here are the pitfalls I ran into:
  1. The name of the menu item for help HAS to be the same as the name used in the AppleTitle metatags content attribute in your main html help file.
  2. CFBundleName key in the info.plist is not set automatically, so you need to do this. Set it to the same name as your executable.
  3. And finally what took me longest time to discover. When you add your folder with help files, you need to select the "Create Folder References for any added folders." radio button when adding the files to project (use add existing files... under resource folder). If you have done correctly the folder should show up as blue. If it shows up as yellow then you did wrong.
Anyway what really bugs me with this thing, is that there is no feedback on what went wrong when you miss one of the steps. I will add a step by step guide on how to to it later. In the meantime feel free to post questions. Oh and this link explains what the difference between copying added folders and using references is.