Volume Number: 16 (2000)
Issue Number: 6
Column Tag: Tools of the Trade

Apple Help

by William Allen

An Introduction to Apple's HTML-based Online Help System

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

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 <META> 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 <A HREF> hypertext links in your content which point to your scripts for execution.
• QuickTime-To Play QuickTime movies you embed <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.

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

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 prospects of starting from ground zero seem daunting, fear not because Apple provides some pre-made templates with generic content for you to use as a starting point. Look inside the SDKs Complete Books folder within the Samples folder. There's a simple help book as well as a more complex version for you to use. Make a copy of either one of these books somewhere convenient and then launch your favorite HTML authoring tool and create your help book. There are tons of software and about a bizillion books and web sites devoted to this topic so I won't present any of that here. HTML 3.2 is the backbone of your Help content but remember the restrictions mentioned earlier.

Sherlock

When launching any page with the Help Viewer you'll see a navigation/search interface at the top of the page's window. This interface consists of three navigation buttons and a search text field/button combination. Your user will always have access to this navigation/search interface no matter where they go in Apple Help. The search interface is how the user accesses the Sherlock search engine by typing a query and hitting the search button.

In order for the Sherlock search engine to process a query and find any hits in your pages, you have to first index your content with the Apple Help Indexing Tool provided with the SDK in the Authoring folder. The result of this process is a separate index file reflecting the contents of your book. When a user does a search, the search is performed on this index file rather than all the pages in your book. This strategy accounts for the speed in which a search can occur.

Before you use the tool to index your book you incorporate any combination of four <META> tag sets into your pages to control what the Indexing Tool indexes. Without these tags, the Apple Help Indexing Tool will indiscriminately index your help book willy nilly. This is the point where all your earlier planning pays off because your blueprint will guide you on what tags to use. What follows explains what these tags are, what they do, and where to place them in your pages.

Controlling the indexing

Placing the ROBOTS meta tag in your file's HTML header allows you to control how your content is indexed by the Apple Help Indexing Tool. There are four different values or attributes to this tag: INDEX, NOINDEX, SEGMENTS, and KEYWORDS. I'll explain each in order and why you may want to use the tag.

<META NAME="ROBOTS" CONTENT="INDEX">

• This tag/attribute combination tells the indexing tool to go ahead and index the entire page including all its segments and keywords which I'll explain about in a moment.

  <META NAME="ROBOTS" CONTENT="NOINDEX">
  

• This value has the opposite effect by telling the tool to not index this page at all. There's no point in indexing a table of contents page, for instance, so this type of page is a good candidate for this tag/attribute combination.

  <META NAME="ROBOTS" CONTENT="SEGMENTS">
  

• This tag/attribute combination tells the indexing tool to only index segments within you file which can also contain the next attribute KEYWORDS.

  <META NAME="ROBOTS" CONTENT="KEYWORDS">
  

• This tag/attribute combination causes only the words specified in the KEYWORDS tag to be indexed

Segments

This tag set is essentially a comment which allows you to divide your material into multiple sections within one HTML file. You place as many segments in the body of your content as you would a standard HTML comment tag. Each segment will return a separate "hit" from the search engine even though they originated from the same page. Segments work very well if you would like to organize a topic into a family with various members into one file rather that breaking them up into separate HTML files. Note that each AppleSegStart comment must end in an AppleSegEnd comment.

<!—AppleSegStart ="Setting Preferences"—>
		<A NAME="Setting Preferences"></A>
<!—AppleSegDescription ="This section describes how to set the Preferences for my application."—>
<<Content of Segment >>
<!—AppleSegEnd —>  

It's not always possible to anticipate how your user will search for help. Adding additional search synonyms, called keywords, enhance your indexing strategy by allowing your users to zero in on the concept they're looking for in a way that works for them. For instance, if you have a page devoted to explaining the options in your application's preferences you may want to include the KEYWORDS tag in your header as follows:

<META NAME="KEYWORDS" CONTENT="preferences, setting preferences, How do I set preferences?, prefs, options, selections">

This tag works very well especially if you do not have those particular words or phrases in the content of your page. Each of the words or phrases listed will return the same page as a valid "hit."

If you would like to add keywords to a segment then you use the following comment tag within the relevant AppleSegStart and AppleSegEnd tags explained earlier.

<!—AppleKeywords ="preferences, setting preferences, prefs, options, selections"—>

Finally, there is a DESCRIPTION tag which will return a brief description in the search results with each hit.

<META NAME="DESCRIPTION" CONTENT="This section describes how to change the Preferences">

These four simple tag/attribute combinations provide all the necessary capabilities you need to control the indexing process.

Having gone through the above steps, your help book is just about ready for indexing. It should have the final directory structure with the above HTML indexing tags in place. The last step is to merely drag and drop your book on top of the Apple Help Indexing Tool located in the Authoring Tools folder of the SDK. That's it! The result is an index file which you include with your help book. Remember, if there is no accompanying index file of your help book, then your users cannot search your book.

You are free to create as many index files that makes sense for your book. For instance, if your book is simple then one master index file might be all that you need. However, you could also create a series of smaller index files for each chapter. If your application were progressively modular in nature, for instance, then you could have a separate help chapter with its own index file with each module. Maintenance becomes localized rather global. Each strategy has its valid depending on your own situation.

If the tool reports an error or warning it probably has to do with your directory structure or tag formation. Select the error/warning to see the cause of the problem in your file.

Creating a Title Page

Now we need to register your newly minted book with Apple Help so it will both appear in the Help Center and link to your book's title page. You use the AppleTitle meta tag in the HTML header of your title page to accomplish this task.

<META NAME="AppleTitle" CONTENT="My New Help Book">

The HTML title page should be at the root level of your book. Finally, place the whole help book folder in the Help folder in the System Folder along with all the other help books which may exist there. Delete the Help Center file as we did earlier. Now launch the Help Center menu item in the Finder's Help menu. The Help Viewer will generate a new Help Center file as we've seen earlier. You should now see your new help book listed in the Help Center. Congratulations! Walk through your help book by clicking on links and do some searches to see how it all works.

Of course, the first pass through will reveal any broken links, etc. in your book. Just go back into your HTML authoring environment and fix those until you've squashed them all. If the searching does not work as you'd like then merely add, delete, or modify the appropriate tags and regenerate a new index file or files until it works as you'd like. The development cycle is minimal if you stay organized.

There are some other visual attributes you can influence with minimal effort such as the icon displayed for the link to your book in the Help Center. If you do not provide an icon then the application provides a generic one. I hope you'll want to roll up your sleeves and check out the SDK's reference section to add some final polish to your help book.

The final visual polish is to have your HTML help files display the "Question Mark" icon in the Finder associated with the Help Viewer. Your book will work just fine without this icon but to add it is trivial. To give you this Finder icon, change the file's have a creator code to "hbwr" and creator type of "TEXT". Some HTML authoring tools such as BBEdit allow you to save your work with a different creator code other than its native one. The advantage to this is you progressively create files with the icon you want as you work. If your authoring tool does not have this feature then you could create an AppleScript applet to automate this resource modification.

Now it's time to move our attention to the final steps which is to link your application to your help book by creating a Guide file component which points the Help Viewer to your particular Help book.

Create a text file with Guide Script commands

Make a copy of your final compiled application in the Finder. Open up a text editor like SimpleText and type in the following Guide Script commands.

<Help Menu>"MyApp Help",help,"?"
<App Creator>'abcd'
<Startup Window> presentation, "Empty Sequence"
<Version>"1.0 ©My Software Company, Inc. 2000","1.0"
<Balloon Menu Text>"Displays information and instructions for using MyApp."
<Define Sequence>"Empty Sequence"
<Define Panel>"Empty Panel"
Empty Text
<End Panel>
<End Sequence>

Save this text file as "MyApp Guide Source" in the same folder as your application. The first command's parameter is a list of the menu items listed in your application's Help menu. The second parameter is your application's four letter creator code. The <Balloon Menu Text> command is the text displayed over this menu item when the user has Show Balloons menu item turned on.

Create a resource for the Guide file

Launch ResEdit and create an new empty resource file named "MyApp Guide.rsrc" in the same folder as your application and text file "MyApp Guide Source" you just created.

Create a new resource item 'html' with an id 1000. This resource item tells the Apple Guide that this Guide file contains menu items which should be redirected to HTML help content. Save the file.

Next, create a new resource item in the same resource file of type 'TEXT' and click OK.

Open the TEXT resource and type the relative path into the TEXT resource, which in this example is: MyApp%20Book/myTitlePage.htm. This is the URL which gets passed to the Help Viewer when the user selects the "MyApp Help" menu item from the Help menu. Note the hexadecimal notation for a space character (%20) in the URL path which is relative to the Help folder. Close this window. Change the name of this TEXT resource item to something like "MyApp Help".

Close all your windows, save the resource file and quit ResEdit.

Linking your application with your help book

In the SDK's Authoring Tools folder find the Guide Maker 2.0 tool. This tool compiles the text file and resource file we created into an Apple Guide file. This file ties your application's Help menu item and your help book all together.

Launch the Guide Maker. From the File menu select Import Source and select the "MyApp Help Source" text file you created earlier. Save the new Guide Maker file with the name "MyApp Guide.gm" in the same folder as your other resources and application. Select Compile from the File menu. Save this file as "MyApp Help" in your application's folder. When the file is compiled it looks for a resource file with the same name as the guide file but ending in ".rsrc". If it is found, then its resources are copied into the new Guide file. Quit the Guide Maker application.

If the Guide Maker complains or reports an error, go back a review the previous steps carefully to make sure all your resources are correct and named properly.

If all went well then you'll see a Guide file in the same folder as your application. At this point, you can launch your application and check out the Help menu items. You should see the "MyApp Help" as the first menu item in the Help menu. When you select this menu item, the Help Viewer will launch and you will be taken to your Help book. Congratulations!

Once again, explore the SDK for further variations like adding multiple menu items in the Help menu. For integrating a Help (?) button within your application, the SDK contains PowerPlant files for you to use in your application's source code.

Adding Interactivity

I've outlined the basic architecture of planning, implementing and attaching a help book to your application. Once you've established this framework, adding interactive features using QuickTime and AppleScripts is achieved with two tags as follows:

QuickTime

The essential tag to placing a QuickTime movie into your content is an <EMBED> tag.

<EMBED src="mymovie.mov">

The SRC tag is a relative path to the movie. Additionally you add WIDTH and HEIGHT attributes to tell the Help browser the size of your movie. The introduction of QuickTime 4.1 added AppleScript capabilities to the QuickTime Player application. This opens up some fascinating possibilities which are outside the scope of this article but are certainly worth exploring.

AppleScript

One of the most exciting features of the Apple Help System is its ability to run AppleScript scripts. Your scripts are triggered with hypertext links which you embed in your pages as follows:

<A HREF='help:runscript="MyApp%20GuideBook:MyApp%Scripts:MyScript.src"'>Click me</A>

The link begins with an opening Anchor Tag: <A

This is followed by a hypertext reference tag HREF= with a command value: help:runscript= followed simply by a relative path to the script file with a dot three letter extension of .src. The Anchor tag is completed with the closing bracket: >. Then follows the text which is displayed to the user : Click me. Finally, the link is completed with the closing Anchor Tag: </A>.

Since this link is a command to run a script, you can optionally pass your AppleScript script data using the optional STRING parameter. You place this parameter after the script's path but before the single quote as follows: <A HREF='help:runscript="MyApp%20GuideBook:MyApp%Scripts:MyScript.src" STRING="myData"'>Click me</A>. One script, then, can be multi-functional by merely passing a different parameter. If the script launched a browser, for instance, you could pass different URLs as a parameter.

On the other end, your AppleScript scripts use the following special handler to receive the information sent by the script link as follows:

  on «event helphdhp» (myData)
			—script goes here
  end «event helphdhp»

The event handler used by the Help Viewer application is written in the raw code format which uses the chevron characters and alphanumeric codes. This example shows the optional passed variable myData within the parenthesis.

Besides these few requirements, implementing AppleScripts to control any aspect of the Mac OS or any other scriptable application, including you own, is up to you.

Conclusion

The Sapple Help SDK provides a wealth of samples and templates for you to begin adding a professional level of Help capabilities to your project. Overall, its strength lay in seamlessly blending the best of two worlds: HTML and the MacOS. Apple has certainly done a fine job of addressing the needs of developers and users alike with its new HTML-based Help System.

References

• Mac OS Help Documentation
  http://developer.apple.com/macos/help.html
• AppleScript General Information
  http://www.apple.com/applescript/
• AppleScripts for QuickTime 4.1
  http://www.apple.com/applescript/qtas.html
• AppleScript Guidebook Script Module
  http://www.apple.com/applescript/help_mods.html
• Apple Mailing Lists

Subscribe to either a full text version or a digest version by sending a blank email to the respective addresses below.

Apple-Help-Authoring-subscribe@public.lists.apple.com

Apple-Help-Authoring-digest-subscribe@public.lists.apple.com

William Allen is the Senior Graphic Designer for Transdigital Communications Corporation, an in-flight entertainment corporation in Brea, California. In this role he produces interface designs for interactive systems for the travel and leisure industry. He has been working on a Mac since 1984. He can be reached at wallen@mac.com.