Please consider a donation to the Higher Intellect project. See or the Donate to Higher Intellect page for more info.

Apple Guide

From Higher Intellect Vintage Wiki
Jump to navigation Jump to search

Apple Computer's onscreen assistance technology, Apple Guide, is the most effective online help system available. With Apple Guide, users proceed through complicated tasks one step at a time, making even long instructions easy to follow. Coach marks are drawn on the screen to emphasize what needs to be done. And if a user does make an error, Apple Guide can detect it, and either provide additional instruction or do the step automatically. Using Apple Guide is like having a personal instructor in the chair next to you, showing you how to perform the task and telling you when you make a mistake.

What is Apple Guide?

Apple Guide is a revolutionary new help system that assists users in accomplishing new or complex tasks. It goes far beyond what traditional help systems are able to accomplish. Apple Guide interactively walks a user through accomplishing a task step-by-step. The user learns the task while they are performing it.

System 7.5 includes several Guides which utilize the Apple Guide technology. The primary Guide is the Macintosh Guide, which guides you through tasks related to working with your Macintosh. Application developers can develop Guides which walk users through tasks specific to their applications.

Businesses and other organizations can also create Guides which are customized for tasks specific to their organization. For example, a corporation could write a custom Guide which walks their employees through the task of finding out the current inventory levels. A higher educational institution might write a custom Guide which walks students through the task of completing a lab assignment. These Guides can be developed on top of existing applications and IS solutions.

Why is Apple Guide Better?

Apple Guide provides user assistance far beyond what traditional help systems provide. Apple Guide is task-oriented, not feature-oriented. This allows users to identify the task they are trying to solve as well as learn much more effectively.

In addition, Apple Guide provides instructions in a window which floats on top of the application. This allows the user to accomplish each step before proceeding. Thus, the user performs the task while they are learning rather than bouncing back and forth between the application and the help system or trying to memorize a list of instructions.

Since Apple Guide content resides in a floating window above all applications, help can be provided for applications without any modification to those applications.

Build that assistance right into your custom solutions. With Apple Guide.

Apple Guide onscreen assistance technology from Apple Computer goes way beyond any on-line help system you've seen before. When users are unfamiliar with, or unsure about, any process in your solutions, they can rely on Apple Guide technology to walk them through the steps to get the job done right. With Apple Guide assistance, you can be confident your users will fill out electronic forms correctly, transfer files to the right locales, access information properly-and get the most out of your solutions. It's a lot like having a local expert, trainer, or member of your support staff looking over your users' shoulders, prompting them through the steps it takes to complete their tasks successfully.

Onscreen assistance that makes sure users get the job done.

Apple Guide systems assist your users by directing them and encouraging them-but your users actually perform the tasks themselves. The Guide systems show them where to look for the buttons and menus they need, as well as indicate which choices to make, and even provide helpful tips and reminders. Apple Guide systems help them begin-and ensure they finish-their computer work.

Encourage learning by doing.

Experience is the best teacher and Apple Guide onscreen assistance gives users the chance to do tasks themselves. Apple Guide systems work at any pace, so everyone can follow their lead. The next time, users can perform the function on their own, or simply have their Apple Guide system assist them again.

Apple Guide onscreen assistance helps get the most out of people.

Creating well-designed, functional solutions is what you do best. But if you're an in-house developer, systems integrator, or consultant, that's only one of your responsibilities. You also have to help your users learn your solutions then support them down the road. Apple Guide systems help you do these support jobs. For example, you can build Guide systems to direct people in getting started, then to continually help when questions arise. The features you add to your custom solutions will be put to good use right away and your users will maintain a high level of productivity.

Workers remain at work, not in training sessions.

Productivity goes down when employees do not know how to use their software effectively. An Apple Guide assistance system-whether it's the Macintosh Guide, an Application Guide, or a Custom Guide-instructs users while they do their jobs with "just-in-time" training. And Apple Guide systems train workers only on the parts of the application that are relevant to them.

Your support staff can make better use of its time.

When you've got Apple Guide systems to answer your users' questions, you-and all of the information technology resources at your organization-are free to do other things. Leave troubleshooting and problem-solving to Apple Guide onscreen assistance, and your team can concentrate on the things that require your unique expertise and creativity.

Apple Guide systems open new business opportunities.

When you build Apple Guide assistance systems, you also build new opportunities, new customers, and new ways to please your clients. Because this technology was recently introduced, it provides an ideal way to expand your current offerings. You can add value to your custom solutions by creating Apple Guide systems for all your solutions-existing or new. Whether you work with FileMaker Pro, 4D Forms, Microsoft Excel, HyperCard, or any Mac OS application, if your solutions run on the Macintosh, you can enhance them all with Apple Guide technology.

Help your organization keep up with the cost of keeping up. Most organizations spend significant resources educating their members on the latest improvements in their computer software. With Apple Guide technology, you'll be able to reduce the need for expensive classroom instruction, printed manuals, and extensive documentation outlining proper procedures.

Opportunities to differentiate your solutions. Solutions enhanced with Apple Guide systems clearly stand apart. When you add Apple Guide onscreen assistance to your offerings, you gain a powerful edge on the competition.

Apple Guide technology can show you the way to a promising future. Apple Guide assistance is a next-generation technology, one that Apple has pledged to support and upgrade into the future. More and more, you'll find Apple Guide technology behind off-the-shelf applications and proprietary solutions for the Mac OS. Hundreds of developers have already shipped Guides with their applications, and the number is growing every week. Your solutions should include Apple Guide technology, too.

Apple Guide 2.1/2.1.1 Release Notes

Installing OpenDoc files

In order for Apple Guide to interact with OpenDoc it is necessary to place a file called 'AppleGuidePlugIn' in the 'System Folder:Editors:OpenDoc:OpenDoc Shell Plug-Ins:' folder. This plugin is the link for Apple Guide to communicate with OpenDoc processes. The Apple Guide plugin is a 'FAT' version for PowerPC and 68K Macs using OpenDoc 1.0.1 or greater; unless you are running OpenDoc 1.0 in which case you need to following files:

OpenDoc on 68K Macs Using OpenDoc 1.0

If you are running OpenDoc on a 68k Mac, you will need to use the 'AppleGuidePlugIn.68K' file in your plug-ins folder.

OpenDoc on PowerPC Macs Using OpenDoc 1.0
If you are running OpenDoc on a PowerPC Mac, you will need to use the 'AppleGuidePlugIn.PPC' file in your plug-ins folder.

Guide files for editors reside in the ':System Folder:Extensions:Global Guide Files:' folder along with the main guide file for OpenDoc itself, called 'OpenDoc Guide'.

Revision History

· 2.1.1 11/xx/96
- Now properly checking multiple-type guide files for qualifer routines ('QLfy').

· 2.1 7/xx/96
- Apple Guide now supports help access from OpenDoc processes, which involves numerous parts and not a single application process as in the previous help environment. For information on providing guide files for OpenDoc parts, please see the document titled "Multiple Guide Files".
- Now supports the ability to access multiple guide files combining the topic areas, index, and look content across all open guide files. The full description of how Apple Guide support multiple guide files can be found in the document called 'Multiple Guide Files'.
- There is now 68k CFM glue code present for 68k apps that want to link with the 'AppleGuideGlueLib.68K' shared library code.
- Applications no longer have to build and handle the Help menu if they want their guide files to reside in a folder other than the application's folder. By including a Guide Directory resource (type = 'gdir'; id = -16384) in their application, they can specify a directory for AG to search for guide files other than the application's directory. See 'Guide Directory Resource' topic below.
- Whether an application has guide files or not, Apple Guide was searching through the app's directory 5 different times for guide files. This is now a single search and is now faster. Any guide file information found is cached for performance.

Known Problems

Please note that this is an intermediary revision and has been released to get OpenDoc/CyberDog functionality in a usable state. The following items are known problems that will be addressed very shortly. Please don't bother reporting in Radar what is listed here as we already know about them.

- The <App Logo> and <App Text> area is still containing the wrong data sometimes.

Multi Guide Files and GuideScript

With the new support for multi process guide files comes an unfortunate side effect that guide authors should know about.

The following commands should not be used in multi-process guide files:
<App Logo>
<App Text>
<Index Instruction>
<Look For Instruction>
<Look For Results Instruction>
<Look For Search Btn Instruction>
<Startup Window>
<Topic Instruction>
<Topic Areas Instruction>
<Balloon Menu Text>

Note that in multi-process guide files the following exception applies:
<Help Menu> - The specified text will appear as the heading used in the merged access window for that guide file, and not the text used in the Help pull-down menu.

In order to have application-specific items for the above commands, create a main guide file for your application with these command and place it in the Global Guide folder. This will insure that your application logo, text, etc., will appear when the user clicks help on your app. Editor guide files and other multi-process guide files will use the main guide file values for these commands.

Guides saved in their application folder should contain the above commands. If other files from the Global Guide folder are merged into the guide, Apple Guide will still use the original Guide's values, and not merge in the main guide file from the Global Guide folder.

If these commands were to appear in each of the individual guide files, the guide developer might be mislead into thinking that different multi-process guides could have different Howdy texts appearing depending on which parts were currently open. Apple Guide will use the application's main guide to display the above commands.

Guide Directory Resource

Apple Guide 2.1 has the ability to search an alternate directory for application guide files as opposed to the familiar searching of the same directory the application is in.

In most cases, it works without code changes to your application. The existance of a 'gdir' resource of resource id '-16384' in your application is enough to indicate to Apple Guide 2.1 where to look for your guide files. If you are currently using the Apple Guide API to populate the Help Menu with your guide files, you will probably want to do a Gestalt check on 'ag_v' and if the result is >= 0x00000210 then you are running Apple Guide 2.1 or later and as long as you have the 'gdir' rsrc you won't need to modify the menu on your own anymore.

The format of the 'gdir' resource; id = -16384 is as follows:

				type 'gdir'
					literal longint		kApplicationFolderType	= 0,
										kSystemFolderType		= 'macs',
										kControlPanelFolderType	= 'ctrl',
										kExtensionFolderType	= 'extn',
										kFontsFolderType		= 'font',
										kPreferencesFolderType	= 'pref';
				resource 'gdir' (-16384)
					"My Guides Are Here"

The value of the first is one of the constants used in FindFolder() calls as defined in Folders.h. If that value is NIL then no FindFolder() directory change is completed leaving the search to be based on the application's current directory (e.g. where the app is located).

The value of the second field is the name of the folder to search relative to the result of the above mentioned FindFolder search if one was performed. So for example, if you put 'extn' in the first long value Apple Guide would first go to the ':Extensions:' folder and then look for the directory specified in this second parameter. If no string is specified in this second parameter, then Apple Guide simply begins searching for guide files in the directory specified by the FindFolder result.

Possible Combinations

Using the 'gdir' resource you can get Apple Guide to do the following.

1. Look in a sub-folder relative to the application's directory. How? Specify a folder name in the second field, and 0L in the FindFolder constant value.

2. Look in a FindFolder() directory for guide files. How? Specify a constant in the first field for FindFolder() to use and no string in the second folder name field.

3. Look in a directory inside one of the predefined FindFolder() result directories. How? Specify a constant in the first field for FindFolder and specify a folder name in the second field.

See Also