hoakley Macs, Technology

Help Help: 2 What has happened to Help?

Apple Help and Help Books have changed a lot since Apple last properly revised their documentation in 2007-9, back in the days of Mac OS X 10.5 Leopard. Yes, it really is that long ago: check the online docs, which have only had one minor change since 29 May 2009.

The screenshots in that documentation still proudly proclaim What’s New in Leopard? for example. Gone from the Help Viewer window is much of its toolbar functionality: the Back and Forward buttons remain, but there is no longer any Home button to return to the title page of the current Help Book, andd the Action menu has vanished too. The magnifying glass tool in the Search field no longer does much either. You also cannot view other installed Help Books and select one in the popup Library Menu.

helphelp21

Now all the toolbar offers are the same Back and Forward buttons, a button to hide or show the sidebar, and one to share the current page.

helphelp22

Search does offer a list of suggestions as you type into it, and that’s about it.

Back in 2012, version 5.1.2 of the HelpViewer app weighed in at 4.5 MB. Today, version 5.3.2 in Sierra is significantly slimmer at 3.1 MB. It would be tempting to conclude that Help is on its way out, all going online, and that investing time and effort in producing good Help Books is a waste.

Despite Apple’s lack of documentation (sadly now a general failure for almost all its products), and the reliance of Help Books on AppleScript to script the launch of apps, for instance, there is no evidence that Apple is abandoning Help Books or HelpViewer in macOS. Indeed, Apple continues to invest in its own Help Books: over that period of five years, MacHelp.help has grown from 21.6 MB to 50.9 MB, and Apple continues to provide Help Books for all its major and most of its minor apps – even the much-maligned Console 1.0 in Sierra.

The underlying architecture works much the same, but has been streamlined to improve its responsiveness. A few years ago, Apple Help had almost lost its purpose because opening and using Help Books had become so painfully slow. In Sierra they are much more usable again, and for developers are well worth investing the effort and time in producing good Help Books.

HelpViewer.app, hidden away in /System/Library/CoreServices, is the minimal front end for Apple Help, but there is more besides. helpd is an on-demand service which appears to watch your Applications and Utilities folders for newly-added apps containing Help bundles, registering them with macOS.

Three separate Property List files, kept in ~/Library/Preferences, support the Help system:

  • com.apple.help.plist keeps a recent shortlist of registered Help Books, but is far from a complete list of those registered.
  • com.apple.helpd.plist is currently a blank property list, presumably used in the event that the helpd service needs to store settings.
  • com.apple.helpviewer.plist contains preference settings for the HelpViewer app.

There are two other folders which can be important to the Help system, but out of bounds to both user and developer:

  • /Library/Documentation/Help is used by macOS to store some Help Books; although /Library/Documentation is accessible, few apps seem to use it now and it is worth avoiding if possible.
  • ~/Library/Documentation/Help has fallen from favour so much that even ~/Library/Documentation doesn’t normally exist in Sierra.

As an app, HelpViewer is a pain to developers and the curious. It appears to run in only one mode, with a single window, no menu (apart from the standard Help menu, which is actually handled by the frontmost app), and almost no options, hidden or otherwise. Its only documented hidden option, which is of use to developers, is to set a preference to add the URL to printed help pages. You can set this by entering the following in Terminal:
defaults write com.apple.helpviewer PrintURLInFooter YES

This does not display the URL of the current help page, but if you print it to a PDF file, it inserts it as a footer to each printed page. It is a painful way to debug misbehaving help files.

Help Books, bundles with the extension .help, folders containing help files, and individual help files such as PDF documents, are now conventionally stored in the Resources folder of an app. This is good because it makes the app more self-contained and simpler to move around, and keeps help material inside the app bundle and therefore covered by code signing. But it also makes the developer’s task harder: you can’t just drop a PDF into the app, or tweak some of the help pages to fix typos.

This blocks one provision which you will find described in Apple’s antiquated documentation: automatic updating of help content over the internet. This rather pleasant dream entailed checking a remote server that the pages in your Help Book are fully up to date, and replacing those that aren’t. As that would break signing of the Help Book, the practical options now, in Sierra, are to use remotely-hosted pages for content, or to use local ones.

Apps can load additional help files, but Apple discourages this except where it is necessary, for example when plugins are installed. There is no real esacpe from building a proper Help Book, storing it in the Resources folder, and rebuilding your app whenever the Help Book or app change.

There is considerable variation in the form of help provided by different developers. A few just load a PDF containing the user documentation, which is better than nothing, but far from ideal for the user. Some excellent apps, with extensive help, still deliver that from a folder.

It is generally preferable to create a proper Help Book, which is externally just a folder with the extension .help. But to work properly, this should be structured internally to contain a single top-level folder named Contents, within which is a folder named Resources, containing the help content.

helphelp23

This is an unsigned Help Book generated for a single language by Help Crafter, which conforms to Apple’s guidelines.

helphelp24

Apple’s own Help Books are similar, but being individually signed they have additional files and folders and many localisations.

A minimal Help Book is required to contain a title page, at least one page of content, and a .helpindex, which can be generated by Apple’s Help Indexer, one of the supplementary apps to Xcode.

The Help bundle Info.plist file in the Contents folder is particularly important, and detailed in Apple’s documentation. A typical file should look something like:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleDevelopmentRegion</key>
<string>en-GB</string>
<key>CFBundleIdentifier</key>
<string>co.eclecticlight.consolation2.help</string>
<key>CFBundleInfoDictionaryVersion</key>
<string>6.0</string>
<key>CFBundlePackageType</key>
<string>BNDL</string>
<key>CFBundleShortVersionString</key>
<string>1</string>
<key>CFBundleSignature</key>
<string>hbwr</string>
<key>CFBundleVersion</key>
<string>1</string>
<key>HPDBookAccessPath</key>
<string>index.html</string>
<key>HPDBookIconPath</key>
<string>images/Images</string>
<key>HPDBookIndexPath</key>
<string>help.helpindex</string>
<key>HPDBookTitle</key>
<string>Consolation 2 Help</string>
<key>HPDBookType</key>
<string>3</string>
<key>HPDBookUsesExternalViewer</key>
<false/>
</dict>
</plist>

The title and other pages are written in XHTML, using the XHTML 1.0 Strict DTD, which is supported by most authoring tools. CSS and JavaScript are widely used in those, and Apple Help expects use of metadata tags to set keywords, abstracts, and for several other purposes including anchors and segments. There are also ROBOTS meta tags which control indexing. These are all detailed in the documentation.

This may sound quite uniform and restrictive, but inspecting the Help Books for several different apps reveals substantial differences in implementation, which largely reflect the tools used to maintain them. Many, perhaps most, of Apple’s Help Books now rely largely on external content, which is fetched from help.apple.com. This ensures that it is kept fully up to date, although when your Mac is not connected to the internet it is less than helpful.

All the Help Books that I have examined bear the hallmarks of being generated by a HAT (Help Authoring Tool), but they also have little structurally in common. This suggests that different developers use different tools, most of them, I suspect, created in-house, and relying on CSS and JavaScript. A quite widespread tool for the latter is the open-source jquery. Some, notably Apple’s, have extensive JSON data files, but a few accomplish everything using just XHTML and CSS.

Whether you’re a user or developer, Apple Help and Help Books are here to stay. They’re not cut down, but are now lighter and more usable, with good support for the inclusion of internet content. Unless a developer has their own in-house tools for creating and maintaining Help Books, they can be a real pain, which explains why many smaller, cheaper apps go without. To my mind, that short-changes the user.