There’s deep irony in the fact that macOS Help is one of its most poorly documented systems. The last time that anyone seems to have even amended its old documentation was seven years ago, since when it has undergone major change and improvement. Now, though, it’s one of the few systems in Big Sur which has started to play up. In the last few days, it has decided not to open some Help books, to open others using Safari, and to show others in French. Let’s explore what’s going wrong.

Apps can implement their Help in any way that they wish, and need not provide any at all. Those which use the system built into AppKit, though, rely on four components:

• a Help book constructed in XHTML with CSS according to rules laid down by Apple, put into a Help bundle and placed in the app’s internal Resources folder in /Contents/Resources/;
• the helpd service provided by macOS from /System/Library/PrivateFrameworks/HelpData.framework/Versions/A/Resources/helpd, which collates indexes and other information about Help books;
• the HelpViewer app, at /System/Library/CoreServices/HelpViewer.app, which renders and displays Help books;
• the ~/Library/Caches/com.apple.helpd folder which contains indexes, databases and property lists maintained by helpd.

This top-level architecture has changed relatively little through versions of macOS from around 10.6, and last underwent major revision in High Sierra 10.13.4, since when it appears to have hardly changed at all. The precise contents of the com.apple.helpd folder have changed, though, and for this article I will refer to those in macOS 11.0.1. For reference, the High Sierra update brought helpd from version 1.1.10 (in 10.12.6) to 1.2.3, which is still the current version in Big Sur. HelpViewer went from 5.3.5 in Sierra to 6.0 in High Sierra and is still 6.0.

The current structure of the com.apple.helpd folder is:

• Cache.db and its two supporting database files,
• CSHelpindexCache.plist, a keyed archive which contains structured information about recognised Help books,
• fsCachedData, which contains many files named using UUIDs,
• Generated contains help indexes within folders such as com.apple.Dictionary.help*2.2.2, named by the Help book and app version,
• HelpCache.plist, which is a keyed archive containing further structured information about recognised Help books,
• three NSFileProtection… folders containing Spotlight index data.

Installing a new or updated Help book

The macOS Help system has traditionally relied on the user (or an installer) adding an app bundle to one of its two watched folders, /Applications and /Applications/Utilities, to trigger the process of adding any new or updated Help book to those available. The helpd service is activated by File System Events when such an event occurs, and responds by checking the app bundle for a Help book to register it.

There is also a direct route, by calling NSHelpManager.registerBooks() with the bundle for helpd to examine. This is primarily intended for use by developers when an app needs to register additional Help books, perhaps for components installed elsewhere.

One important issue which was addressed in the improved Help system in High Sierra is the identification of Help books. Previously, that for the Dictionary app was known as com.apple.Dictionary.help, which made it difficult to accommodate more than one version of an app and its Help book at a time. The current system incorporates a version number, such as com.apple.Dictionary.help*2.2.2.

Accessing a Help book

When originally developed, the great majority of Help books relied on static content built into them. All that had to happen for most was the launch of HelpViewer, and for it to open the supplied Help book.

Since then, Help books have increasingly relied on online content, which needs to be refreshed before each access. Thus HelpViewer and helpd have to work together to deliver the latest content, with helpd doing the refreshing and updating to the databases in the com.apple.helpd folder, which HelpViewer uses with the WebCore rendering engine in WebKit to display pages and interact with the user.

The new naming system and use of WebCore are important improvements; both helpd and HelpViewer also deliver greatly improved performance over that seen in Sierra, for example.

What’s going wrong in Big Sur?

Although I’m progressively migrating the Help books in my own apps to a mixture of rich text and PDF files, several still rely on conventional AppKit Help books. Each new update I edit the Help book, and until Big Sur the macOS Help system has coped remarkably well with these new versions and their changed Help books.

I first noticed a problem when building the current version of LockRattler. Despite correctly updating the Help book in Xcode, when I tested it I kept seeing the Help book for the previous version. In the end, I got this to work, notarized the app, and took it across to my M1 mini for final testing. Although the app was installed in its main Applications folder, when I tried to open its Help book, HelpViewer reported that it couldn’t be accessed, as if it was looking online for its content. I couldn’t view that Help book for about half an hour after the new version of the app was installed.

The same M1 mini later decided that it wouldn’t open the Help book for T2M2 properly. Clicking on any of the links on this mangled page opens that section of the Help book using Safari. A few hours later, this has spontaneously corrected itself, and the same Help book now works correctly. That copy of T2M2 was installed on the mini several days ago.

Going back to my iMac Pro, I recently installed the updated Apple Configurator 2 from the App Store. In common with several of Apple’s other apps, this has now decided that I want Help in French, although I have never made that language a system-wide or local setting for any app.

At first sight, you might think that Help’s language preferences were determined by those of the app. Those can be changed using the Apps tab in the Language & Region pane, but have always been set to the default, which isn’t French. Changing that setting to make another language as that set for the app changes all the text used in the app, but doesn’t affect its Help book. So I can use Configurator in Italian, but its Help book remains set to French.

Browse CSHelpindexCache.plist and you’ll come across entries like
https://help.apple.com/assets/5F60E367680CE2D7421BC3F0/5F60E36E680CE2D7421BC3F8/fr_FR/search.cshelpindex
which explain how the Help system has decided to deliver that Help book in French. But helpd doesn’t offer any way to force that to be updated or changed, and those files don’t appear to be refreshed when you start up in Safe mode. Once this type of error has occurred, it looks like you’re stuck with it until at least the next version of that app.

Can anyone help?