At some stage, between the release of macOS High Sierra 10.13 and the latest update to 10.13.4, Apple has replaced its Help system. I have checked through Apple’s release notes, including those concerning the SDK changes for developers, and have been unable to find any reference to such changes. However, users and developers should be aware that, when using Help in 10.13.4 and later, they are dealing with quite a different beast from that in the first release of macOS 10.13, Sierra, and before.

This only came to my attention because my Help book utility HelpHelp now crashes when opened in 10.13.4. On investigation, I discovered that the undocumented support files on which HelpHelp relies had changed format and content completely. This article presents a brief account of how Help works in High Sierra 10.13.4 and later.

If you want to refresh your mind as to how Help works in Sierra, this article may be helpful.

As far as I can tell, the top-level architecture of the Help system has changed relatively little: helpd is still there, processing Help books and turning them into the private databases stored in ~/Library/Caches/com.apple.helpd. But the way that this works, and how HelpViewer accesses those data, appears to have undergone radical overhaul.

/System/Library/CoreServices/HelpViewer.app is now at version 6.0, up from 5.3.5 in 10.12.6, and /System/Library/PrivateFrameworks/HelpData.framework/Versions/A/Resources/helpd is at version 1.2.3, from 1.1.10 in Sierra.

In Sierra, the key folder ~/Library/Caches/com.apple.helpd contains:

• Cache.db and two supporting database files,
• fsCachedData, a folder containing many files named using UUIDs,
• Generated, a folder containing many stub Help books each of which contains a help index,
• HelpCache.plist, detailed below,
• HelpindexCache.plist, a keyed archive apparently indexing into the contents of fsCachedData,
• SDMHelpData, a folder containing hierarchies of stub Help books.

Of those, it is HelpCache.plist which is the most useful, as it is a simple dictionary containing a list of apps without Help books, and full details of those Help books which are recognised by the Help system. It is those details which are accessed by HelpHelp to provide information to help debug Help book problems.

In High Sierra 10.13.4, the structure of ~/Library/Caches/com.apple.helpd remains the same, but its contents have changed:

• Cache.db and its two supporting database files remain,
• fsCachedData remains,
• Generated no longer contains stub Help books, but its help indexes are contained in folders such as com.apple.Dictionary.help*2.2.2, named by the Help book and app version,
• HelpCache.plist, which is now a keyed archive containing quite different data,
• HelpindexCache.plist, a keyed archive which has changed content but still appears to index into the contents of fsCachedData,
• SDMHelpData, which now contains hierarchies of folders rather than stub Help books.

Most significantly for HelpHelp, and anyone trying to debug Help book problems, there is now no convenient list detailing recognised Help books. HelpCache.plist may key into such information, but the important data are locked away in other files which are less willing to deliver them.

The property list at ~/Library/Preferences/com.apple.help.plist does contain a list of some registered Help books, and their registration order, as does ~/Library/Preferences/com.apple.helpd.plist in Sierra, but that list represents a small fraction of all the Help books known to macOS and indexed by helpd. It is also worth noting the subtle change in that file’s name, from com.apple.helpd.plist to com.apple.help.plist.

Another more pervasive change is the way in which these files refer to Help books. Previously this used their signatures, such as com.apple.Dictionary.help, which made it difficult for the Help system to cope with multiple versions of apps with different Help books. Now each Help book is known by a name which combines that signature with the app’s version number, such as com.apple.Dictionary.help*2.2.2.

Opening a Help book in the log

Without watching the performance of helpd and HelpViewer over a period of time in the log, it is difficult to draw any firm conclusions as to the practical effects of these changes in 10.13.4. However, simply opening a traditional local Help book shows some quite radical differences, suggesting that this is the largest overhaul of the Help system for some years.

In Sierra 10.12.6, the following is a very brief summary of highlights from the unified log when opening a Help book normally, with arbitrary time in seconds:

06.413684 Help Entering AHRegisterHelpBookWithURL
Although the Help book opened has already been registered and accessed before, this is the start of the steps to open it.

06.444634 com.apple.cts Registered XPC Activity: com.apple.helpd.sdmmap_building
helpd is here working with the files in the SDMHelpData folder.

06.473299 HelpViewer HIServices _RegisterApplication( pid 9588 => 0x0,0x333333) type=ui-element
HelpViewer is launched.

06.476690 helpd HelpData Could not find access page in directory /System/Library/CoreServices/Finder.app
This is not in the Help book requested!

06.556356 HelpViewer SharedFileList com.apple.LSSharedFileList.RecentDocuments
06.608997 HelpViewer WebCore 0x7fe1ba61bb00 - PerformanceMonitor::measureCPUUsageInActivityState: Process is using 82.1% CPU in state: VisibleNonActive
As is usually the case, opening a Help book is a slow, CPU-intensive process. HelpViewer is clearly heavily loaded when it launches.

11.335952 HelpViewer <private>
After this comes a long series of entries concerning linguistic data, network connections and more. These take place in order to load data for all sorts of other Help books, but seldom for the one requested.

20.042895 HelpViewer WebCore 0x7fe1ba61bb00 - PerformanceMonitor::measurePostLoadMemoryUsage: Process was using 110952448 bytes of memory after the page load.
That’s 110 MB of memory to load one Help book of 8 MB, with no online content.

In High Sierra 10.13.4, this appears much quicker and less prone to errors and problems:

05.484540 LaunchServices LaunchApplication: appToLaunch={ … "CFBundleExecutablePath"="/System/Library/CoreServices/HelpViewer.app/Contents/MacOS/HelpViewer", … "CFBundleIdentifier"="com.apple.helpviewer", "CFBundleName"="Help Viewer", … } modifiers: { … } args=[ NULL ]
HelpViewer is launched earlier, and opens the requested Help book more quickly.

05.496825 com.apple.cts Registered XPC Activity: com.apple.helpd.sdmmap_building
helpd accesses files in the SDMHelpData folder after HelpViewer has started to launch.

05.520312 LaunchServices CHECKIN:0x0-0x41041 781 com.apple.helpviewer
HelpViewer is up and running very quickly, displaying the requested Help book. After this comes extensive internet access to obtain online help content, while the user is browsing the requested Help book.

16.030458 HelpViewer WebCore 0x7fe009617f30 - PerformanceMonitor::measurePostLoadMemoryUsage: Process was using 61480960 bytes of memory after the page load.
Memory usage is 61 MB, half that of Sierra’s HelpViewer.

21.031773 HelpViewer WebCore 0x7fe009617f30 - PerformanceMonitor::measurePostLoadCPUUsage: Process was using 12.9% CPU after the page load.
There has been a huge improvement in the CPU loading, down from 82% in Sierra.

21.765307 opendirectoryd PID: 781, Client: 'HelpViewer', exited with 0 session(s), 0 node(s) and 0 active request(s)
Closing the Help book is also quick and clean.

Access to and control of the Help system

According to current documentation, there have been no changes in code access to the Help system, which remains through the minimal NSHelpManager. There don’t appear to be any command tools which affect helpd or HelpViewer, nor any support for dealing with problems in the system or in Help books.

Summary

From a user’s view, the changes to Help in macOS 10.13.4 are very good news. This largely neglected part of macOS had become slow, CPU-intensive, and highly inefficient. This is very encouraging at a time when some of us were beginning to wonder whether these old features were going to die from their age alone.

The snag with the current implementation is that it is completely locked down, and provides no support for those trying to debug Help books or custom Help features.

Apple now needs to document the new Help system properly, in sufficient depth to aid developers who are making and trying to debug Help books. Apple’s Help Programming Guide – which provides minimal information about the Help system itself – has not had any substantial revision for nine years, since Mac OS X 10.5. Someone somewhere should be dying of shame over that.