Note: This document supersedes the information in the older document Providing User Assistance With Apple Help, which has been moved to the Legacy Documents area of the ADC Reference Library (Reference Library > Legacy Documents > User Experience). This document describes development of Apple Help for Mac OS X v10.4 and later. For information on providing Apple Help for earlier versions of the operating system, see Providing User Assistance With Apple Help.
This document describes Apple Help, the HTML-based system for providing user assistance in Mac OS X. Apple Help is the primary help system for Mac OS X and is designed to deliver online topic-based user help, such as is often provided in user manuals and lists of frequently asked questions (FAQ). Carbon, Cocoa, and Java applications can use Apple Help in Mac OS X.
Note: In addition to Apple Help, Mac OS X includes another help technology, help tags. Help tags, also known as tooltips, are short contextual help messages that appear onscreen when the user hovers the pointer over an element in an application’s user interface. Help tags are documented in Providing Help Tags in Carbon. You can use Interface Builder to add help tags to Carbon or Cocoa applications. In Cocoa Interface Builder, help tags are referred to as tooltips. In Carbon, they’re referred to as Help and Extended Help (displayed by holding down the Option key).
Apple Help offers significant advantages over static help documents, such as Read Me files or manuals in PDF. The benefits of adopting Apple Help for user assistance include these:
Searchability. Apple Help offers users sophisticated search capabilities, including full-text searching and the ability to search on synonyms and common misspellings.
Full support for QuickTime and any other media for which plug-ins are installed. Using QuickTime or other authoring tools, you can create animated sequences that showcase hidden or complex features of your software product and play these sequences as part of your help content.
AppleScript automation. Using AppleScript, you can automate tasks and run them from your help content to guide users through a complex operation step by step.
Ease of updating. Apple Help makes it simple to revise and expand your help content, page by page or all at once. Using Apple Help, you can even maintain up-to-date help pages and search indexes on your own server and have them downloaded via the Internet to update your help content.
Ease of adoption. Many developers have recognized the advantages of browser-based help and implemented HTML solutions to provide user assistance. Apple Help makes it easy for you to adapt previously created HTML pages into the form used by Apple Help.
User experience. The Help Viewer application is optimized for delivering onscreen help. By using Apple Help, you’ll ensure the user experience for your application is consistent with users’ expectations of a Mac OS X application.
Spotlight For Help. Starting with Mac OS X v10.5, Apple Help integrates Spotlight For Help, which lets users search the contents of your menus and application help directly from your application’s Help menu. If you don’t use Apple Help, then Spotlight For Help returns results only from Mac Help rather than from your application’s help.
When you use Apple Help, you can supply HTML-based user assistance and integrate it into your application with relatively little effort. Apple Help manages and displays help books; a help book is the collection of HTML files that constitute the user help for your software product, plus a help index file generated by the Help Indexer utility. When you supply a help book and register it with Apple Help, users can access your help from your user interface and view it in Help Viewer without any additional work on your part.
The Apple Help system includes these components:
The Help Viewer application. This is the default application for viewing user assistance in Mac OS X. Help Viewer displays your HTML-based help book.
The Apple Help application programming interface (API). This is a set of functions provided by Apple Help that allow you to access and load help in Help Viewer. You do not need to use these functions if you are providing only a basic help interface; however, if you wish to implement advanced help features (such as contextual help), you need to call the Apple Help functions. The Apple Help API is available to all Carbon, Cocoa, and Java developers.
The Help Indexer utility. This is a developer tool provided by Apple for indexing your help book. When you run the Help Indexer utility on your help book, the tool generates an index file that Help Viewer uses to make your help searchable.
If you are creating an application, plug-in, or other software product for Mac OS X with a user interface, you should read this document to learn how to create an Apple Help help book and display it in Help Viewer.
This document includes the following chapters and appendixes:
“Apple Help Concepts” describes the Help Viewer application and Spotlight For Help, and introduces the Apple Help API.
“Authoring Apple Help” shows how you can create a basic help book and describes how to use the Help Indexer utility to index your help book.
“Help Book Registration” describes how to register your help book with Help Viewer.
“Opening Your Help Book in Help Viewer” shows how to use the Apple Help functions to access and display help book content from your application..
“Apple Help Meta Tag Properties” lists the meta tags specific to Apple Help. You can use these tags to control how your help content is displayed.
“Apple Help URLs” lists Apple Help URLs that you can use to link to help pages and other resources.
“Apple Help Segments” lists the commands you can use to divide HTML help pages into multiple segments.
Help Viewer and the Apple Help API are available in Mac OS X v10.0 and later. The Help Indexer tool is available in Mac OS X v10.4 and later in /Developer/Applications/Utilities when the Developer package is installed.
For more information about help technologies, you can refer to these other documents in the ADC Reference Library (http://developer.apple.com/referencelibrary/index.html):
For a detailed description of the Apple Help application programming interface, see the Apple Help Reference.
For information on Carbon help tags, see Providing Help Tags in Carbon and the Carbon Help Manager Reference.
For information on help tags, or tooltips, in Cocoa applications, see Online Help and Providing Help Tags in Carbon.
For guidelines on how to use help effectively within your application, see “User Assistance” in the Using Mac OS X Technologies chapter of Apple Human Interface Guidelines.
Last updated: 2009-05-29