Kezzer Kezzer - 1 month ago 23
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

NSHelpManager
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/com.apple.help*
rm -rf ~/Library/Preferences/com.apple.help*
rm -rf ~/.Trash/*
killall helpd
defaults write com.apple.helpindexer IndexAnchors YES


updatehelpindex.sh (re-generates indexes)

#!/bin/sh
hiutil -C -f MyApp.help/Contents/Resources/English.lproj/MyApp.helpindex
MyApp.help/Contents/Resources/English.lproj/


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
NSHelpManager
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).

Ideas?

EDIT (folder structure):

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

+ Contents
Info.plist
+ Resources
+ shrd
(a bunch of image files)
+ English.lproj
MyProj.helpindex
index.html
+ 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.

Answer

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.