I’m writing the help book for my application. As required, I have the CFBundleHelpBookName and CFBundleHelpBookFolder keys in my app’s info.plist, and I’m using the new Snow Leopard .help bundle format for the help book. The various keys in Rehearsals.help/Contents/Info.plist are all populated as per the Apple Help Programming Guide. As expected, when a user chooses “Rehearsals Help” from the Help menu, the index page of my help book (in the appropriate localisation, currently only English) is opened in Help Viewer.
However there are actually (currently) two HTML files in the bundle, index.html and support.html. It’s my understanding that if I place a named anchor in one file, like this:
<a name="support"></a>
Then I can link to it from the other file, like this:
<a href="help:anchor=support bookID=info.thaesofereode.Rehearsals.help">Support</a>
However that doesn’t work. Neither does:
<a href="help:anchor=support">Support</a>
Help viewer displays a sheet saying “Help Viewer cannot open this content.”, and if I turn on debug logging in Help Viewer and helpd, I see this:
10/03/2010 15:46:02 HelpViewer[2049] decidePolicyForNavigationAction: help:anchor=support%20bookID=info.thaesofereode.Rehearsals.help
10/03/2010 15:46:02 HelpViewer[2049] decidePolicyForNavigationAction: apple-help-content:help:anchor=support%2520bookID=info.thaesofereode.Rehearsals.help
10/03/2010 15:46:02 HelpViewer[2049] willSendRequest: <NSMutableURLRequest apple-help-content:help:anchor=support%2520bookID=info.thaesofereode.Rehearsals.help>
10/03/2010 15:46:02 HelpViewer[2049] Start loading apple-help-content:help:anchor=support%2520bookID=info.thaesofereode.Rehearsals.help
10/03/2010 15:46:02 HelpViewer[2049] Starting search for query "support" with return port com.apple.helpd-26755
10/03/2010 15:46:02 helpd[2050] PID #2050 - received message #0: HPDStartMessageID
10/03/2010 15:46:02 helpd[2050] Process 2049 requested callback at com.apple.helpd-26755 and sent query: HPDQuery 289928762.026442: "support" in ("info.thaesofereode.Rehearsals.help") of types ("com.apple.HelpArticleResult") with limit 0
10/03/2010 15:46:02 helpd[2050] Run loops which have yet to start: (
"com.apple.kbPlugin",
"com.apple.helpbookPlugin"
)
10/03/2010 15:46:02 helpd[2050] Search for this query has been delayed 1 time: support
10/03/2010 15:46:02 helpd[2050] Delayed search for query: "support"
10/03/2010 15:46:02 helpd[2050] Starting help articles search for query: "support"
10/03/2010 15:46:02 helpd[2050] Query 289928762.026442 returned results: (
)
10/03/2010 15:46:02 helpd[2050] Response sent to port: com.apple.helpd-26755
10/03/2010 15:46:02 helpd[2050] Query finished: HPDQuery 289928762.026442: "support" in ("info.thaesofereode.Rehearsals.help") of types ("com.apple.HelpArticleResult") with limit 0
10/03/2010 15:46:02 helpd[2050] Response sent to port: com.apple.helpd-26755
10/03/2010 15:46:02 HelpViewer[2049] <HVAnchorURLHandler: 0x1002bde50> finished query: HPDQuery 289928762.026442: "support" in ("info.thaesofereode.Rehearsals.help") of types ("com.apple.HelpArticleResult") with limit 0
10/03/2010 15:46:02 HelpViewer[2049] <HVAnchorURLHandler: 0x1002bde50> has results: {
}
10/03/2010 15:46:02 HelpViewer[2049] Found no results for support
How do I use help: URLs correctly in Snow Leopard help bundles? (Needless to say I know the workaround to use relative file URLs, and that works, but I want to get help anchors working for context help and linking within the app.)
It turns out those anchors and URLs are correct, and helpd does index content automatically, but it maintains an aggressive cache. If the help book is updated without bumping the version number, it doesn’t scan for new anchors.