September 96 - Using Apple Guide 2.1 With OpenDoc
Using Apple Guide 2.1 With OpenDoc
Peter Commons
You've helped create an Apple Guide guide for your standalone
application. Now your company is writing an OpenDoc part editor,
but it's not obvious how Apple Guide can be used in the context of
parts and compound documents. The answer is Apple Guide 2.1,
which extends the original version to allow easy use of Apple
Guide features, including Help menu management, coachmarks, and
context checks, in the world of OpenDoc. This article introduces
the new features of Apple Guide 2.1 and explains in detail how to
use them with OpenDoc.
The world of OpenDoc isn't like the world of the standalone "behemoth" application --
a fact that hasn't escaped the notice of developers who want to provide online help. An
application developer can easily provide complete online help since the application is a
single self-contained unit that will run in its own window. On the other hand, the
developer of an OpenDoc part editor never knows what other part editors will be
running along with it during an OpenDoc session. Users can have any number of part
editors running in any number of windows at the same time. All the editors might
belong to a package written by one company, or, more likely, it might be a
conglomeration written by a number of different companies. Under these
circumstances, providing help gets a little more complicated.
Since Apple Guide is such a powerful help system, wouldn't it be nice if it could be
applied to the new world of OpenDoc? Enter Apple Guide 2.1 (released right on the
heels of Cyberdog, Apple's new integrated suite of OpenDoc part editors for the
Internet). The raison d'être of Apple Guide 2.1 is to support Apple Guide for OpenDoc,
with particular emphasis on Cyberdog. This version includes a number of new
features, some of which are specific to OpenDoc and some of which aren't. Among these
new features are the following:
• a combined Full Access window (known as a Merged Access window) that
contains all the guide topic areas and index terms for OpenDoc part editors
currently running
• a similar ability to merge guides in conventional applications
• the ability to specify a list of applications for which a particular guide is
intended
• support for a whole new series of OpenDoc-related context checks
In this article, I'll describe how Apple Guide behavior has changed in the world of
OpenDoc, and I'll also tell you about some new features of Apple Guide 2.1 that you can
use in conventional applications. I'll go over the simple steps you must take to add a
guide to an OpenDoc part editor, and then I'll cover some of the things you could do,
depending on the kinds of help you want to provide for your part editor. You'll find
samples of the resources mentioned in the article on this issue's CD.
If you haven't worked with Apple Guide before, you might want to read "Giving Users
Help With Apple Guide" in develop Issue 18 before tackling the new concepts presented
here. Apple Guide Complete is the definitive reference, though the current (1995)
edition doesn't cover Apple Guide 2.1.
HOW APPLE GUIDE BUILDS THE HELP MENU
From the beginning, one of the strengths of Apple Guide has been that it enables guide
authors to create guides without requiring modification of the application being guided.
While most other new Toolbox managers were saying, "To support me, just add a
NewManagerIdle call in your main event loop," Apple Guide said simply, "I work just
fine without any modifications to your application at all!" One of the key elements
enabling Apple Guide to work without requiring changes to any code is Apple Guide's
automatic population of the Help menu.
The Help menu has also been called the Guide menu at certain times in its
history, but both names refer to the same menu (the one labeled with a
question mark).
The algorithm Apple Guide uses to determine how to populate the Help menu, although
simple on the surface, has a number of subtleties. With each new release, the
algorithm has been extended somewhat. To understand how the Help menu is populated
in Apple Guide 2.1, let's look at how the population algorithm has developed over time.
You Apple Guide experts might even discover some little-known features.
Table 1 presents a summary of how the different versions of Apple Guide populate the
Help menu; details follow.
How populating the Help menu has evolved
Original Apple Guide
• Guide files in application's folder.
• Based on (App Creator), (Gestalt), 'QLfy'.
• Based on type [About, Tutorial, Help, Shortcuts, Othr]. There can be only
one guide file of each type except Other.
Apple Guide 2.0
• Add guide files in Global Guide Files folder.
• No changes.
• Guide files in application's folder take precedence over those in Global
Guide Files folder.
Apple Guide 2.1
• For OpenDoc shell documents, change application's folder to mean
document's folder.
• Add an exclusion check based on resources of type 'prts' [for OpenDoc] and
'apsg' [for applications].
• Multiprocess guide files ['prts' for OpenDoc, 'mlti' for others], if
present, are accessed through the ProcessName Guide" item in the Help
type menu position. Guide files with the 'apsg' resource appear in the Help
menus of multiple applications.
Note: All candidates are determined when the Help menu is built. Exclusions are
applied at the time the menu is built, except for the 'prts' resource test, which is
applied when Apple Guide is launched.
"ORIGINAL" APPLE GUIDE
The general process of populating the Help menu hasn't changed since Apple Guide was
first introduced. At application launch time, Apple Guide does the following:
• creates a list of possible guide file candidates
• excludes any candidates that don't match required criteria
• puts the names of all remaining guide files in their requested positions in
the Help menu
For the original version of Apple Guide (any version before Apple Guide 2.0), the list
of candidates is created by searching for all guide files that are in the same folder as
the application being launched and that aren't Mixin guide files (see Apple Guide
Complete, page 2-14, for details about Mixin guide files). A guide file with an alias in
the application's folder would also be added to the list of candidates.
Apple Guide then sees if any candidates should be excluded by subjecting them to these
tests:
• If the guide file contains an command specifying a value
that doesn't match the signature of the current application, it's excluded (see
Apple Guide Complete, page 10-8).
• If the guide file specifies one or more checks and no
selector returns its required value, the guide file is excluded (see Apple Guide
Complete, page 10-10).
• If the guide file specifies exactly one check whose selector is
'QLfy', Apple Guide looks in the guide file's resource fork for a resource of
type 'QLfy' with a resource ID equal to the requiredValue parameter of the
resource that takes no parameters and returns a short in register D0
(standard C calling conventions). It calls the resource code and, if the result is
0, the guide file is excluded (see develop Issue 18, page 19).
Apple Guide then tries to place the name of each remaining candidate in the position it
requested with the helpType parameter of the command (see Apple Guide
Complete, page 10-14). Placement of the names of different types of guide files is
shown in Figure 1. If two or more final candidate guide files have the same type and
that type isn't Other, Apple Guide includes the name of the first guide file of that type
(by alphabetical order) and excludes the others. The names of all guide files of type
Other appear in the Help menu.
Figure 1. Placement of Help menu items by type in original Apple Guide
APPLE GUIDE 2.0
Apple Guide 2.0 (an update to System 7.5 but backward-compatible with System 7 and
7.1) added some logic to the Help menu population algorithm that hasn't been widely
documented. The crux was adding a new place to look for candidate guide files, called the
Global Guide Files folder. The Global Guide Files folder resides in the Extensions folder
and, as its name suggests, is a place where you can put guide files to make them
available to all applications.
When Apple Guide 2.0 is creating its list of candidate guide files for an application, it
looks both in the folder containing the application and in the Global Guide Files folder.
When looking to exclude candidates, Apple Guide 2.0 works almost exactly like the
original Apple Guide -- it excludes any guide files from its candidate list that don't
pass the , , and 'QLfy' tests.
The only difference is in how Apple Guide 2.0 selects an item for the Help menu if
there are multiple candidates. In the original Apple Guide, if two guide files passed all
the tests and were of the same type (aside from type Other), the one sorting first
alphabetically would be chosen for inclusion. In Apple Guide 2.0, if there are two or
more guide files of the same type, the first one alphabetically is still chosen for
inclusion, but any guide file in the application's folder is chosen over any guide file in
the Global Guide Files folder. So, for example, if there are Tutorial guide files in the
application's folder and also in the Global Guide Files folder, those in the Global Guide
Files folder will be ignored, and the one that's first alphabetically in the application's
folder will be chosen for inclusion. Names of guide files of type Other are added from
both the application folder and the Global Guide Files folder.
APPLE GUIDE 2.1
Apple Guide 2.1 adds two new mechanisms to the process of building the Help menu:
• the ability to define multiprocess guide files (with an 'mlti' or a 'prts'
resource) and to access these files as a group through a single menu item that
presents the user with a combined Full Access window (available in both
OpenDoc part editors and conventional applications)
• the ability to specify a list of application signatures that your guide
supports (with an 'apsg' resource), so that the name of your guide will appear
in the Help menu for each of those applications
We'll look at these new mechanisms in more detail in the next section.
In addition, Apple Guide 2.1 supports document-specific help. Recall that when
creating a list of candidate guide files, Apple Guide 2.0 looks in the same folder as the
application and in the Global Guide Files folder. Apple Guide 2.1 behaves exactly the
same way for conventional applications, but for OpenDoc documents launched via the
OpenDoc shell application, Apple Guide 2.1 treats the document's folder as the
"application's folder," so it looks in the same folder as the document for guide files,
rather than in the same folder as the OpenDoc shell application (besides searching the
Global Guide Files folder). As a result, the names of guide files in the same folder as
the OpenDoc shell application never appear in the Help menu; the names of guide files
in the same folder as an OpenDoc document can appear in the Help menu for that
document.
A CLOSER LOOK AT APPLE GUIDE 2.1
Apple Guide 2.1 introduces a new concept: the multiprocess guide file. A multiprocess
guide file is specified by including in the guide file an 'mlti' resource for conventional
applications or a 'prts' resource for OpenDoc part editors. Because these two are so
similar, I'll discuss them together. I'll also tell you more about the new 'apsg'
resource, which when added to a guide file means that the guide file's name will appear