Retired Document
Important: The information in this document is relevant to Apple Help development for Mac OS X v10.3 and earlier. For Mac OS X v10.4, the information in this document is superseded by the information in Apple Help Programming Guide.
Introduction to Providing User Assistance With Apple Help
This document describes Apple Help, the HTML-based system for providing online user assistance in Mac OS X. Apple Help is the primary help system for the Mac OS 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. If you are creating an application, plug-in, or other software product with a user interface for Mac OS X v10.3 or earlier, you should read this document to learn how to create an Apple Help help book and display it in Help Viewer.
Apple Help offers significant advantages over static help documents, such as Read Me files or manuals in PDF, to teach your users how to use your products more effectively. The benefits of adopting Apple Help for user assistance include these:
Searchability. Apple Help takes advantage of Sherlock technology to offer users sophisticated search capabilities, including full-text searching and the ability to search on synonyms and common misspellings.
Full support for QuickTime media. 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.
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. 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 the Mac OS. 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 menu help), you need to call the Apple Help functions. The Apple Help API, although a Carbon API, is available to all Carbon, Cocoa, and Java developers.
The Apple Help Indexing Tool. This is a developer tool provided by Apple for indexing your help book. When you run the Apple Help Indexing Tool on your help book, the tool generates an index file that Help Viewer uses to make your help searchable.
System Requirements
Help Viewer and the Apple Help API are available in Mac OS X version 10.0 and later. They are also available in Mac OS 8.6 and later for Carbon applications. The Apple Help Indexing Tool is available in Mac OS X in /Developer/Applications/Utilities
when the Developer package is installed.
Organization of This Document
This document includes the following chapters and appendixes:
Apple Help Concepts describes the Help Viewer application and introduces the Apple Help API.
Authoring User Help shows how you can create a basic help book and describes how to use the Apple Help Indexing Tool to index your help book.
Registering Your Help Book 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
See Also
For a detailed description of the Apple Help application programming interface, see the Apple Help Reference. For information on Carbon help tags, seeProviding Help Tags in Carbon and the Carbon Help Manager Reference.
For information on help tags, or tooltips, in Cocoa applications, seeOnline Help.
For guidelines on how to use help effectively within your application, see Apple Human Interface Guidelines.
Copyright © 2003, 2007 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2007-10-31