A little while ago, I explored the new Help system included in the macOS High Sierra 10.13.4 update. This article is an attempt to explain more clearly how it now works, and where the main areas of change are, using diagrams.

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. I don’t know how often that is called, but I believe that it is used by Xcode when testing built applications within its development environment. I also use it in my tool, HelpHelp.

This is an important step: if an app is installed in another folder, even ~/Applications, then any Help book may not get registered properly.

Another important issue, which appears to have been addressed in this new Help system, 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 version of an app and its Help book at a time. The new 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 ~/Library/Caches/com.apple.helpd, which HelpViewer uses with the WebCore rendering engine 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.

This should ensure that the use of both traditional and largely online Help books is much better at last.