Each time that I dip into Apple Help, the more complex it appears. Having struggled with some bizarre problems in my own Help Book, I have gained further insights into how Help works, which can explain problems experienced by users and developers, and help propose some solutions.

The real Apple Help

The HelpViewer app, tucked away in /System/Library/CoreServices, is only the tip of Help’s iceberg – a minimal front end which is called by apps which use Apple Help to handle their Help Books. The heart of Help is the undocumented helpd service, which is buried in Apple’s private framework HelpData.framework.

helpd doesn’t run constantly in the background, but is launched on demand by Grand Central Dispatch, using a mechanism similar to that of Time Machine backups. Events which will normally cause it to be launched are the addition of an app to its watched folders /Applications and /Applications/Utilities.

One of helpd‘s main tasks is to maintain the Help Cache stored in ~/Library/Caches/com.apple.helpd. Although most of the contents of that folder form the cache itself which is not readily accessible, HelpCache.plist is most revealing. It contains a long list of apps in the watched folders which have no declared Help Book, so either handle their own help, or have none. For apps which have a declared Help Book, helpd copies in data from the Help Book’s Info.plist to maintain HelpCache.plist and its caches.

Part of this work involves fetching online components to support Help Books, and helpd regularly checks in with help.apple.com, which is Apple’s server supplying most of its online help pages, as well as those for third-party Help Books which use online features.

When you open an item in the Help menu of an app, the app first decides whether to handle that request itself, or to pass it on to Apple Help. Apps such as Adobe’s and the current release of Microsoft Office (and very many others) handle their own help, which is often delivered by cross-platform tools. Similarly, an app which displays a PDF help file does not use Apple Help to do that.

How to get the wrong Help Book

The great majority of Apple’s apps, and many developed by others (now including my own Consolation 2.0), pass the request for Help to macOS. This launches the HelpViewer.app front end, which then looks up in the Help Cache the location of the Help Book which it is to open. This is an important feature: because helpd maintains the Help Cache on the basis of apps which are installed in its watched folders /Applications and /Applications/Utilities. Apps which are opened from other locations are likely to open the Help Book in the version to be found in one of those watched folders.

To give a practical example, yesterday I was finishing off writing the Help Book for Consolation 2.0. When I installed the new and much larger .help bundle in Consolation’s Xcode project file, and rebuilt the app to include it, each time that I opened Help, HelpViewer opened the previous version of the Help Book, which was located in the older copy of Consolation 2 in my /Applications folder.

For users, this means that having multiple versions of apps outside the /Applications folder will result in confusion: when you try opening the Help Book, HelpViewer will open the version which is stored in the app registered with helpd, in /Applications.

For developers, this makes the development and testing of Help Books very difficult (an issue which has long been recognised, it appears). In order to access a new Help Book, you will need to install your test app in /Applications, or Apple Help will carry on using the old version – which is what was driving me nuts until I realised what was occurring.

What if no help appears?

helpd seems to be very reliable at doing its job of maintaining the Help Cache, but occasionally that cache gets into a mess. This can manifest itself as the wrong Help Book being opened, the HelpViewer window remaining blank, or the Help system crashing altogether.

Instinctively, you might then go to the obvious Help preference files stored in ~/Library/Preferences, such as com.apple.help.plist, com.apple.helpd.plist, or com.apple.helpviewer.plist.

Chances are that moving any of them from that folder will achieve very little. com.apple.helpd.plist might appear very important, but is currently vestigial with no content, and com.apple.helpviewer.plist just contains basic settings for HelpViewer.

com.apple.help.plist might be a better prospect, but at the moment seems to contain limited information to top up what is stored in much greater detail in the Help Cache. So if you cannot find any better solution, you are most likely to be successful if you force the Help Cache to be rebuilt. One way of doing that is to move its entire contents to another folder outside ~/Library.

HelpViewer also keeps its own cache, in ~/Library/Caches/com.apple.helpviewer, which you might need to empty as well.

I don’t yet know whether those caches are cleaned when you start up in Safe mode, but that could be another way of fixing these problems.

Note that the helpd service is not accessible at the command line. You cannot, to the best of my knowledge, force helpd to rebuild its caches through a command, and it will only run when scheduled to do so through Grand Central Dispatch.

Finally, when you come to use Sierra’s logs to trace helpd problems, you will discover that com.apple.helpd is not a ‘subsystem’ as far as they are concerned. You’ll find it most useful to filter log messages using
senderImagePath CONTAINS[c] helpd
or
processImagePath CONTAINS[c] helpd

eventMessage CONTAINS[c] helpd
will pick up despatching of helpd activity, but also a lot of calls to access remote help servers which are probably of no interest.