All DatabasesMacTech Vol 16-2000
Apple Help
Volume Number: 16
Issue Number: 6
Column Tag: Tools of the Trade
Apple Help
by William Allen
An Introduction to Apple's HTML-based Online Help
System
Overview
At some point in your project's development cycle you will come across the issue of
how to provide assistance to your users. Whether your project is a stand alone
application or an interface to your hardware product, an online help system adds a
level of polish in the eye's of your users. Online help is defined as being able to access
interactive and searchable help content from within your application via the Help
menu which the Mac OS provides to all applications displaying a menu or via a Help
(?) button.
There are have always been various solutions to providing online assistance. You can
roll-your-own or outsource this task to a third party solution such as Altura's
QuickHelp, or you can use the online help system that Apple includes as part of its Mac
OS operating system..
Apple's solution, called Apple Guide, was introduced with System 7. The good news
about Apple Guide was that it finally formalized the process of creating online help for
developers. The bad news was that the cost of admission in working with Apple Guide
was quite high. Despite the fact that it looked very cool and had some great
capabilities, creating an Apple Guide involved learning a set of proprietary script
commands embodied in the Apple published 600 page book and CD combination, Apple
Guide Complete: Designing and Developing Onscreen Assistance. With the rapidly
changing pace of software development, Apple Guide was too cumbersome to learn and
maintain. As a result, the payoff was rarely worth the effort and Apple Guide
floundered, never seeming to reach its full potential.
So, since Mac OS 8.6 Apple has quietly been upgrading its Mac OS online help system.
The Internet, of course, has changed everything. I'm guessing that Apple recognized
that there had to be a better way for developers to create and integrate their online
help solutions into their applications. Their answer lay in the integration of their
crown jewel technologies and the presentation capabilities of HTML into a more
accessable solution now called Apple Help.
You should consider looking into Apple Help because it offers considerable benefits to
you as a developer by being very simple to implement and manage, while tapping into
some of Apple's strongest technologies. A more significant reason to look into Apple
Help is because, according to Apple, this will be the operating system help engine used
for Mac OS X and beyond.
Under the Hood
The heart of Apple Help is an application called the Help Viewer, which operates with
support from the HTML Rendering Library extension (HTMLRenderingLib).
Figure 1. The Help Viewer application.
The Help Viewer is a lightweight browser based upon the HTML 3.2 specification. It
supports all HTML 3.2 features except forms and plug-ins, Java and a deliberate
restriction of only being able to handle one frame set on a page. To offset these
limitations the Help Viewer taps into some very cool Apple technologies to integrate
itself with both your application and the operating system to offer a high degree of
interactivity. These technologies are:
• Sherlock-Apple Help uses the Sherlock search engine to allow users to
find specific information within your content. You facilitate this feature with
an indexing process, part of which is strategically embedding HTML
tags throughout your HTML pages. You then run your indexed pages through an
indexing tool which reads these tags and generates an index file of your
content. These HTML tags allows you to control the indexing process.
• AppleScript-Apple Help becomes interactive with the ability to execute
AppleScript scripts. To execute AppleScript scripts you embed
hypertext links in your content which point to your scripts for execution.
• QuickTime-To Play QuickTime movies you embed tags in the
body of your content along with some parameters to indicate how the movie is
to be played.
HTML serves as the framework to these technologies so let's look at part of Apple Help
first.
Getting Started
The process of developing a basic HTML Apple Help involves four steps:
• Organizing and creating your content with HTML.
• Making your content searchable in an intelligent manner with four
tags sets.
• Creating a title page for your book so that your book is listed in the Help
Center.
• Creating a Help menu item in your application so users can jump to your
help book from within your application.
Organizing and Creating Your Content
Developing a blueprint based upon the goals of your presentation is essential to a
successful Apple Help project. A good way to start is to divide your content into static
and dynamic capabilities. A static presentation would be those elements that are
informative such a table of keyboard shortcuts and the like. Dynamic elements could
coach or assist your user through a process or steps such as launching a browser to
your web site or some other action like playing a QuickTime movie to explain a
concept.
To create your content in HTML, you have a wide variety of choices at your disposal.
You can use any authoring tool which outputs standard HTML 3.2. Your file names can
end with either the ".htm" or ".html" extension. You can link to other pages, create
tables, and display graphics as you would in building a conventional web site. You can
view and check links of your work in progress with any standard browser like
Netscape's Communicator or Microsoft's Explorer but you should view your work in
the Help Viewer to check the dynamic functions because off-the-shelf browsers
interpret the various tags, I'll introduce to you about shortly, differently than does the
Help Viewer. This point will become apparent as we move along.
Understanding how Apple Help is structured in the operating system will help you
organize and manage your material. If you visualize Apple Help as being a local web
site then the organization and management of your content will be a breeze. The folder
or directory structure of Apple Help is quite specific up to a point but offers lots of
latitude once you get past that point. Let's take a peek.
Look inside your System Folder for the Help folder. Inside the Help folder you'll see
some folders with one solitary file named Help Center. The Apple Help Viewer folder is
where the Apple Help Viewer application and its support files exists. This arrangement
of having the Help folder inside the System Folder provides a central and stable
location for the HTML material you create. Go ahead and double-click the Apple Center
file and you should get access to the Help Center just as if you selected the Help Center
menu item from the Finder's Help menu. If you make a side-by-side comparison to
what's listed in the Help Center topics window with the folder names in the Help folder
window then you'll see the connection between the folder names and the Help Center
listing as shown in Figure 2.
Figure 2. Help Center and the Help folder compared.
Since we're already looking in the Help folder, try this: Quit the Help Center page by
closing the window which quits the Help Viewer application. From the Finder remove
the Help Center file outside the Help folder to, say, the Desktop. Launch the Help
Center menu item from the Finder's Help menu and then look in your Help folder again.
Whoa, its a brand new Help Center file!
Based on this exercise, we can figure out that one of the Apple Help Viewer's functions
is to automatically create a table of contents of the various help folders existing in the
Help folder. To make this dynamic listing work you have to register your help content
with the Help Viewer. Later, I'll explain how you get the Help Viewer to list and link to
your help content in the Help Center page.
Before we go further in our explorations, lets imagine a classic organizational analogy
of books, chapters and pages to help us understand what were looking at. All the folders
inside the Help folder will be books. All the folders inside the books will be chapters.
Finally, all the files inside our chapters will be pages-HTML pages to be exact.
An HTML page, is typically made up of some combination of words, pictures, and
hyperlinks. Taking a clue from standard web publishing conventions, inside each
chapter folder you'd be wise to create one folder to put all your HTML pages into and
another folder to house your graphics and other media. Maintaining your help book
will be determined by how organized your assets are. So now its up to you and/or your
team to outline your content in this natural book, chapter, page analogy to suit your
goals and go to work.
I'm placing a lot of emphasis on planning your content ahead of time because the
process will help you identify what capabilities you wish to integrate into your
particular help book as well as the steps to achieve your goal of assisting your users.
Apple Help 1.2 SDK 1.0
Apple provides a software development kit (SDK) which will get you running in no
time. You can download the SDK from
<ftp://ftp.apple.com/developer/Development_Kits/Apple_Help_1.2_SDK_1.0.sit.hqx
>.
The SDK contains all the tools for making your job a lot easier. I'll point out the tools
you'll need as I go along but feel free to explore the rest of the SDK on your own.
The first task is to convert your content into HTML as mentioned earlier. If the
Referenced by (10):