Introduction to Apple Help Programming Guide

This document describes Apple Help, the HTML-based system for providing user assistance in OS X. Apple Help is the primary help system for 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).

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 media for which plug-ins are installed. 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.

• 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 an OS X application.

• Spotlight For Help. Starting with 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 hiutil 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 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 Cocoa and Java developers.

Who Should Read This Document?

If you are creating an application, plug-in, or other software product for 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.

Organization of This Document

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 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.