Kezzer Kezzer - 2 months ago 36
Objective-C Question

Apple Help Authoring

I'm following this guide to public some Apple help. The application I work on has had help built in for years, but it stopped working all of a sudden, and no changes were made to the application plist or any of the help files. We're presuming Apple changed something, so I made sure it met the specifications Apple were requiring. When I say "not working" I mean that our links using

will open the help viewer but bring back a page not found.

Things to check off the list:

  1. There is an anchor with the correct name at the top of the page

  2. The folder structure is a replica of what is in that article linked earlier

  3. We are re-indexing the help pages

  4. We do clear out all of the caches

Here's the code we use to open the help page:

NSString *locBookName = [[NSBundle mainBundle] objectForInfoDictionaryKey: @"CFBundleHelpBookName"];
[[NSHelpManager sharedHelpManager] openHelpAnchor:@"mypage" inBook:locBookName];

In this instance we'd have a page with a
<a name="mypage"></a>
at the top so it should link correctly. Our scripts are as follows:

hvfix (clears all caches):

rm -rf ~/Library/Caches/*
rm -rf ~/Library/Preferences/*
rm -rf ~/.Trash/*
killall helpd
defaults write IndexAnchors YES (re-generates indexes)

hiutil -C -f

We do a build, drop the folder into the Applications folder in order to register the application + the help. We even try a restart or logoff/logon and still we get nothing. I know it's a very fiddly process but nothing we try seems to work. All we want to be able to do is use the
to open a help anchor. Undoubtedly this works in 10.6+ as so many other apps do it (some reports suggest it won't work in 10.7/8, but they must be untrue).


EDIT (folder structure):

This is within the folder that's in a sub-directory of the overall Cocoa project called 'help'.

+ Contents
+ Resources
+ shrd
(a bunch of image files)
+ English.lproj
+ css
+ pgs
+ gfx

And in the folders are precisely what's as expected, 'css' has a bunch of CSS files in it, 'pgs' has the HTML pages and 'gfx' has image files.


OK, this one's been quite a roller-coaster of confusion but it has something to do with with your folder structure setup in Xcode. Here's some things worth knowing:

  • People opt to put it in English.lproj. Don't do this, for a few reasons. First it won't display the sub-directories/files in Xcode if you dragged the help folder into your file listing, and secondly stuff in that folder is supposed to be flat, not structured.
  • Create a "help" folder in the root and put your files in that. You can then put them in a sub-directory called "English.lproj" if you want localisation.
  • Don't create a ".help" folder which contains all of your help files. This seems to break indexing. We don't know why.
  • Instead, have /help/Contents/stuff and drag and drop that folder into your project directory listing (mine's in "Resources" group). Make sure it's a blue folder and that you can see the entire directory (all of your HTML etc.)
  • Run the help indexer against it to generate the .helpindex file
  • Make sure your plist entries reflect the name of that folder and the meta tag name specified in your index.html file

If you follow the above rules things should work fine. It seems in ML that creating a .help folder breaks things from here on out, so basically, don't follow the Apple guide.