HelpHelp: a tool to search Help Books and debug problems

It’s difficult to diagnose and fix problems in Apple Help, as there are no tools, not even command line tools, to help. It’s also no longer possible to use Help Viewer (or HelpViewer) to search a Help Book of your choosing, without opening the app which owns that Help Book.

I am pleased to announce the first development version of my new free utility HelpHelp, which starts to address these issues. Because this is the first release (0.1), it has neither documentation beyond this article, nor a Help Book of its own, for the moment.

The latest release is available from Downloads above.

It is a standard document-based app which only runs under macOS 10.12.x Sierra. Again, I am afraid that it is unlikely to be compatible with El Capitan for the foreseeable future. It is signed, so should run normally from the outset.

When it starts, you will need to open a new window using the New command in the File menu.


Initially, it loads all the available Help Books into the Help file popup menu at the top. Currently these are not sorted into alphabetical order, which is my next task in its development. They also exclude those apps which provide their own non-Apple help systems; I have no plans to try to add those, as they can only be opened by the apps which operate them.

Select a Help Book in that popup menu, and you should then see the following information displayed about it:

  • Help Book ID – is the signature by which that Help Book is known to Apple Help;
  • Help Book path – is the full path to that Help Book;
  • Access path – is the full path to the index file used in the Help Book.

Once that information has been displayed, you can then search for a text string within that designated Help Book by entering the text into the Search text box, and clicking on the Search button next to it.

There will then be a pause, Help Viewer will open, and the search results will be displayed there, listed for the selected Help Book first.


What use is this?

For regular Mac users, it lets you target the Help Books of other apps when performing a search. If you are using Safari, and want to refer to Logic Pro Help, you do not have to start Logic Pro up, or wade through all the Other search results looking for those from Logic Pro. Just as you used to be able to, in Help Viewer, you can now target your searches independently of which app(s) are open.

For those developing Help Books or apps containing Help Books, it enables you to see exactly which Help Book will open when you access Help in your app. It cannot do anything about changing that (at the moment), but will explain why you may see the ‘wrong’ Help Book, and when the ‘right’ Help Book is being used.

For anyone trying to diagnose Apple Help problems, it is a tool which gives you insight into what is happening, and should thus inform you of what is going wrong.

How does it work?

The information used to construct the Help file popup menu is drawn from the cached list of Help Books which is maintained by the helpd helper service, which supports Help Viewer. It thus shows you exactly what Help Viewer is seeing.

A further article explaining this in detail, and how it is implemented, will appear shortly.

For those who like such things, if you open its Help menu (which currently doesn’t open a Help Book), you will be offered HelpHelp Help.