TweetFollow Us on Twitter

A Look at AG Author

Volume Number: 13 (1997)
Issue Number: 6
Column Tag: Viewpoint

AG Author

by John R. Powers, III, guideWorks

A new authoring tool for Apple Guide

Introduction

AG Author is an authoring tool for Apple Guide content. A previous MacTech article (Powers, 1996) reviewed other Apple Guide authoring tools and this article reviews the newest entry.

First Impressions

AG Author is available directly from the developer and publisher, Lakewood Software. You can download a compile-disabled version from their web site (Internet resources are at the end of this article) and request a registration number from Lakewood to upgrade to a fully functional application. This registration number is also used for enabling software updates.

Installation

Installation consists simply of unstuffing the downloaded file and placing it on a hard disk. The provided Espy fonts must be dragged to the Fonts folder. These fonts must be installed before authoring for Apple Guide. Apple Guide users do not require these fonts.

The downloaded software does not include two essential components. They are Guide Maker Lite and the Claris XTND system. Guide Maker Lite compiles the output of AG Author into an Apple Guide document. Guide Maker Lite in turn requires the Claris XTND system if any elements other than plain text documents are used, or there is any character stlying in the Apple Guide source file. Since you must have Guide Maker Lite to compile AG Author output into an Apple Guide document, you must have Guide Maker Lite before you can create a guide file with AG Author. Use the links at Lakewood Software's or guideWorks's sites to get Guide Maker Lite and Claris XTND. AG Author could have simplified things for first-time Apple Guide authors had they provided Guide Maker Lite and the Claris XTND system as part of the distribution package.

The download also does not include Apple Guide, but all systems shipped since 7.5 have the necessary software. Users with System 7.0 or 7.1 require Apple Guide 2.0 or newer. Subscribers to Apple's "MacOS SDK," already have a license to ship Apple Guide with their products. The SDK contains the latest version of Apple Guide and all the pieces necessary for installing Apple Guide on System 7.0 and newer. If your user has System 7.5 or newer, you do not need to ship Apple Guide with your product.

AG Author requires a minimum of a 68020 processor, MacOS 7.0, 8 MB of RAM, and 5 MB of disk space. The AG Author documentation recommends a PowerPC processor. The download includes PowerPC and 68K versions.

Documentation

The included Read Me includes important notices, technical support and contact information, quick start instructions for experienced Apple Guide developers, and version history.

The product also includes a 64-page on-screen "User Guide." The document contains step-by-step and reference information about every aspect of AG Author. It is a good reference document, but assumes you already know a great deal about Apple Guide. If you are new to Apple Guide authoring, you will also need one of the three Apple Guide books. (A list of books and articles are at the end of this article.) Ironically, AG Author does not ship with an Apple Guide because the development tool used to create AG Author does not support it. This is unfortunate because an Apple Guide for AG Author would be enormously helpful.

Authoring steps

The User Guide describes a seven-step process for using AG Author to develop Apple Guide content. The steps are as follows:

  1. Plan the guide file project,
  2. Specify the project globals,
  3. Build the topic and index lists,
  4. Build the definition library,
  5. Write the panel and sequence scripts,
  6. Compile the guide file, and
  7. Test the guide file.

This is the same process used by other Apple Guide authoring tools (Powers, 1996) with the addition of step 4, building the definition library. As a point of reference, other authoring tools either require the writing of Guide Script (Guide Maker) or insulate the user from writing Guide Script (Danny Goodman's Apple Guide Starter Kit and Guide Composer). AG Author writes and displays the Guide Script automatically.

Using AG Author

Step 1. Plan the guide file project

This step is the first step in any documentation project, no matter what authoring tool you are using. It includes defining the target user and the scope of the help content, and performing a task analysis. This all-important step does not require AG Author.

Step 2. Specify the project globals

Project globals information applies to the entire guide file. Examples are the type of access window, the howdy text, default formats, the help menu item, and prompts. Use the Project Globals dialog box to enter this information. A WYSIWYG interface makes it easy to see what how the information will appear in the guide.

Figure 1. Project Globals dialog box.

Step 3. Build the topic and index lists

The AG Author List Manager defines the contents of the Apple Guide access window. Topic areas, index terms, headers, and topic names are entered into a window that looks a lot like the Apple Guide access window with a few extras. Each list starts with one "Undefined" item. If you have done step 1, the plan, thoroughly, it is a simple task to add the topic areas to the access window. AG Author provides a lot of flexibility in how to enter information. For example, you can enter all the topic areas and then go back and enter topics for each, or you can do one topic area at a time, entering all its topics. Enter, modify, move, and delete items by selecting it and clicking on the appropriate button. This is similar to Apple Guide Starter Kit and Guide Composer.

To enter a topic, select the topic area and use the New button to create each header and topic. A triangular marker shows the insertion point for the next topic area or topic. If you build your list from the bottom up, then entries come out in order. Otherwise, you must move the marker down before entering each new list item. When you switch between the topic areas, the marker is reset to the top of the list. If you get an item out of order, you can move the item to its proper location using Option-drag.

Figure 2. List Manager.

Index terms are added using the List Manager Index view. The process is very similar to creating topic areas and topics in the List Manager Topics view. Often, you may want to enter an index term and use a header or topic from the Topics view. However, AG Author only lets you copy and paste entire topic lists from the List Manager Topics View, not individual topics. You must either build the index from scratch, re-entering all the headers and topics for each index term, or copy a complete topic list and delete the unwanted topics. Also, there is no automatic generation of index terms to "seed" the list. It would be nice to start with the words used to describe the topics, for example, for a head-start with the index list. Guide Composer is the only authoring tool that offers automatic seeding of the index list.

Step 4. Build the definition library

AG Author Definition Factory builds the definition library. The definition library contains sequences (topics), panels, formats, graphics, coachmarks, and other items used in an Apple Guide file. You create an element once and refer to it from many places. It is a useful way to create and manage the many elements of a guide file. None of the other authoring tools offer anything similar.

The New Sequence dialog box has entries for sequence name, the title to appear on each panel of the sequence, the prompt set, and the navigation button set. Unfortunately the New Sequence dialog box is a nonmoveable modal dialog box that positions itself in the middle of the monitor, covering other documents. The dialog box displays a default prompt set and navigation button set. You can also elect to have an ID number pre-defined for the sequence. This is a handy option if your application uses the AGOpenWithSequence Toolbox call to open the sequence for you. For example, you can use a Help button in your application to call up the sequence directly. The application passes the pre-defined ID number in the AGOpenWithSequence call to identify which sequence to open. See Powers, 1994 for more information on how to use this context-sensitive feature of Apple Guide.

Figure 3. New Sequence dialog box.

When you create a new sequence, AG Author displays the Script Editor window containing the Guide Script for the sequence. The script includes a completed sequence name and display name. You can enter Guide Script directly or use popups to insert panels, control structures, and navigation statements. If you do enter Guide Script directly, AG Author does not add it to the definition library. For example, if you enter a "Panel" or "Define Panel" command in the Guide Script, AG Author does not add the panel to the definition library. The best approach is to use the popups and let AG Author generate the Guide Script for you. The Apple Guide Starter Kit and Guide Composer create Guide Script too, but they do not display it for the author. This is not necessarily a shortcoming as we will see below.

The Insert Panel popup brings up a list of defined panels. If you have not defined the panel, you can Option-click the button and create a new panel.

Figure 4. Script Editor for a sequence.

The New Panel dialog box lets you select from a list of templates. The templates contain formatting and prompt information for the standard types of Apple Guide panels. The panel types include introductions, actions, definitions, tips, and many others. This is a very nice feature of AG Author. It provides a quick and consistent way to present the standard forms of help content.

Figure 5. New Panel dialog box.

When you create the new panel, AG Author displays the Script Editor window. In this context, the window shows the script for a panel rather than a sequence and includes popups for panel Insert, Button, and On Panel items. AG Author also highlights the area where you need to enter your own content.

Figure 6. Script Editor for an introductory panel.

To create a "Do This" panel for example, the author clicks New in the definition factory panel list and selects the Action template. The script editor appears with the appropriate tag and body formats already entered. To add a "Do It For Me" button in the panel, the Button popup is used. If you have not defined any buttons yet, you need to go back to the definition factory and define a "3D" button that executes an AppleScript. If you are not very familiar with this Apple Guide button capability, then the button definition dialog box will appear overwhelming at first. This is one of the places where AG Author needs Apple Guide, a better interface, and/or better documentation.

Figure 7. Button Definition dialog box.

When you click New in the definition factory panel list, the New Panel dialog box appears with the panel name already entered and changed from "Step 1" to "Step 2". This feature of AG Author simplifies the creation of a series of step panels.

To create a coachmark, the author Option-clicks the Coachmark item in the script editor Insert popup for the panel. The Coachmark Definition window has all the fields necessary for defining the coachmark including a file selection dialog box to select the target application signature.

Figure 8. Coachmark Definition dialog box.

It is easy to create additional coachmarks by duplicating the first coachmark and changing a few parameters.

Step 5. Write the panel and sequence scripts

After defining all the panels for the sequence, the script editor is used to add the panels to the sequence. To do this, the author opens the sequence and selects the panel title from a list. This adds a panel reference in the Guide Script for the sequence.

Figure 9. Script Editor for a sequence with panels.

One script editor window displays the script for either panels or sequences, but not both at the same time, a shortcoming of AG Author. Fortunately, the script editor contains pop-ups for the ten most recent sequences and panels. Context checks make the guide file "intelligently" responsive to the user's actions. Context checks skip unnecessary panels and check to see that a step is completed before going on. For example, if a window is already open, the context check skips the panel telling the user to open the panel. The definition factory has a dialog box for defining context checks, but it requires detailed knowledge of Apple Guide to use. Again, this is a good place for some interactive assistance from AG Author, a better designed interface, and/or better documentation.

Figure 10. Context Check Definition dialog box.

After creating a context check, select the sequence and add the control structure. Use the popups to select the control structure ("Skip If" and "Make Sure"). However, a knowledge of Guide Script is necessary to know where to insert the control structure.

Figure 11. Script Editor for a sequence with panels and context checks.

Step 6. Compile the guide file

The "Compile" step involves two major operations. First, the project is exported into Guide Script files. Next, an Apple Guide "guide" file is created from the Guide Script. AG Author does the export and Guide Maker Lite creates the guide file. The step starts with choosing Compile Project from the AG Author File menu. A dialog box appears to show the progress through each step in the process.

Figure 12. Compile progress dialog box.

My first attempt at compiling a project failed; AG Author did not complete all the compilation steps. It exported all the Guide Script files, brought Guide Maker Lite to the front, but stopped prematurely. I re-read the User's Guide to make sure I installed the software correctly. I also reviewed the instructions for setting up the compile preferences and starting the compile. Finally, I called the AG Author customer support number and asked for their help. They walked me through the compile process and duplicated it at their end. They asked some good questions about my configuration, leading me to suspect my copy of Guide Maker Lite. Replacing Guide Maker Lite solved the problem.

My first compilation reported an error. Guide Maker Lite did not recognize the name of a panel. I had changed the panel name in the definition factory panels list, expecting AG Author to change the panel name in the Guide Script for me, but it didn't. To correct the problem, I used AG Author's Find & Replace to find the old panel name and replace it with the new one.

You must keep the Guide Script in synchronization with the definition factory. Otherwise, compilation errors will occur. If you make a change to an object's definition, then you must also make the corresponding change in the Guide Script. If you make a change in the Guide Script, then you must also make the corresponding change in the definition. AG Author does not do this automatically. You can use Find & Replace to do part of the job, but not all of it. AG Author has elected to "expose" Guide Script to the user in a passive way. Once the Guide Script is presented to the user, it's entirely up to the user to maintain it. This introduces the risk of the user breaking the Guide Script and introducing compiler errors which may be difficult to track down. This is a trap that new user should avoid until they become more comfortable with Guide Script. You can use the Lock Scripts option to give some degree of protection against this.

Figure 13. Compiled guide file.

AG Author creates Guide Script text files for the compilation by Guide Maker Lite, and exports the project as multiple text files, resource files, and pict files. The user does not have to touch these files. The text files contain the Guide Script for the project. A build file contains references to the text and resource files for Guide Maker Lite. AG Author generates well-organized and well-commented Guide Script.

Conclusions

AG Author delivers all the features of Apple Guide wrapped up in a friendly and useful user interface. It requires knowledge of Guide Script, but it does not require the user to be an advanced scripter to create useful guides. Some kind of step-by-step assistance in using AG Author would make the product much easier to use. There are several areas, outlined in the article, where documentation change and/or change in basic architecture would benefit the product.

AG Author is the next step in the evolution of Apple Guide authoring tools. This is a good product, but it has some weaknesses. While it adds a lot more authoring capability, it does not go far enough in providing the ease-of-use to support that capability. The product has numerous features that are buried in the documentation and user interface. The new or occasional user will realize the full potential of the product only after a great deal of hands on experience. To the positive, it does help those authors that need more capability without requiring them to go entirely to Guide Script. It holds its own nicely with the competition, but is not the hands-down winner. Here are some suggestions for different types of authors:

  • If you want the easiest way to try out Apple Guide, buy Danny Goodman's book (Goodman and Hewes, 1995). Read it and write a guide using the software provided with Danny's book.
  • If you want to use most of the features of Apple Guide and avoid Guide Script, use StepUp Software's Guide Composer.
  • If you want to use all the capability of Apple Guide and are willing to learn some Guide Script, use AG Author. AG Author is also the only product that lets you style text without a word processor.

Overall, AG Author provides a new level of capability and ease for authoring Apple Guide files.

Availability

AG Author retails for $99.00 U.S. Educational and site licenses are available. AG Author is available only from Lakewood Software's web site. A compile-disabled version is available for download from Lakewood Software's web site for free. You can evaluate the compile-disabled version at no charge and, when you want change it into a fully enabled version, obtain a registration number from Lakewood Software. Complete information is available at the Lakewood Software web site at http://www.lakewoodsoftware.com.

Books

The following are books about Apple Guide authoring.

  1. Apple Computer, Inc. "Apple Guide Complete: Designing and Developing Onscreen Assistance". Addison-Wesley (ISBN 0-201-48334-3) $39.95 (U.S.)
  2. Feiler, Jesse. "Real World Apple Guide". M&T Books, ISBN 1-55851-429-5, $39.95 (U.S.)
  3. Goodman, Danny and Hewes, Jeremy Joan. "Danny Goodman's Apple Guide Starter Kit". Addison-Wesley Publishing (ISBN 0-201-48349-1) $34.95 (U.S.)

Articles

The following are articles about Apple Guide authoring.

  1. Powers, John. "Giving Users Help With Apple Guide". develop (June 1994, issue 18). This article introduces Apple Guide and describes how to add Apple Guide support to an application.
  2. Powers, John. "New Apple Guide Authoring Aids". MacTech Magazine (January 1996, Volume 12, No. 1). This article reviews three books about Apple Guide authoring: Apple Guide Complete, Danny Goodman's Apple Guide Starter Kit, and Real World Apple Guide.
  3. Powers, John. "Apple Guide Authoring Tools". MacTech Magazine (June 1996, Volume 12, No. 6). This article reviews 3 Apple Guide authoring tools: Guide Maker, Danny Goodman's Apple Guide Starter Kit software, and Guide Composer.

Internet Resources

The following are Apple Guide resources on the Internet.
  1. http://www.guideworks.com -- everything you need to know about Apple Guide including demos of authoring tools, frequently asked questions, tips, and links to other sites.
  2. http://www.lakewoodsoftware.com -- the home site for AG Author. Provides information about the product, a demo that you can download, and ordering information.
  3. http://www.macos.com/Apple_Guide/ -- Apple's site for Apple Guide.
  4. http://www.dannyg.com/ -- Danny Goodman's site.
  5. http://rampages.onramp.net/~stepup/ -- StepUp Software's site.

Thanks

The author thanks Marc Paquette, Document Bard at Metrowerks, Inc., for his help in preparing this article.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

FotoMagico 5.6.12 - Powerful slideshow c...
FotoMagico lets you create professional slideshows from your photos and music with just a few, simple mouse clicks. It sports a very clean and intuitive yet powerful user interface. High image... Read more
OmniGraffle Pro 7.12.1 - Create diagrams...
OmniGraffle Pro helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use... Read more
beaTunes 5.2.1 - Organize your music col...
beaTunes is a full-featured music player and organizational tool for music collections. How well organized is your music library? Are your artists always spelled the same way? Any R.E.M. vs REM?... Read more
HandBrake 1.3.0 - Versatile video encode...
HandBrake is a tool for converting video from nearly any format to a selection of modern, widely supported codecs. Features Supported Sources VIDEO_TS folder, DVD image or real DVD (unencrypted... Read more
Macs Fan Control 1.5.1.6 - Monitor and c...
Macs Fan Control allows you to monitor and control almost any aspect of your computer's fans, with support for controlling fan speed, temperature sensors pane, menu-bar icon, and autostart with... Read more
TunnelBear 3.9.3 - Subscription-based pr...
TunnelBear is a subscription-based virtual private network (VPN) service and companion app, enabling you to browse the internet privately and securely. Features Browse privately - Secure your data... Read more
calibre 4.3.0 - Complete e-book library...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital librarian... Read more
Lyn 1.13 - Lightweight image browser and...
Lyn is a fast, lightweight image browser and viewer designed for photographers, graphic artists, and Web designers. Featuring an extremely versatile and aesthetically pleasing interface, it delivers... Read more
Visual Studio Code 1.40.0 - Cross-platfo...
Visual Studio Code provides developers with a new choice of developer tool that combines the simplicity and streamlined experience of a code editor with the best of what developers need for their... Read more
OmniGraffle 7.12.1 - Create diagrams, fl...
OmniGraffle helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use Graffle to... Read more

Latest Forum Discussions

See All

The House of Da Vinci 2 gets a new gamep...
The House of Da Vinci launched all the way back in 2017. Now, developer Blue Brain Games is gearing up to deliver a second dose of The Room-inspired puzzling. Some fresh details have now emerged, alongside the game's first official trailer. [Read... | Read more »
Shoot 'em up action awaits in Battl...
BattleBrew Productions has just introduced another entry into its award winning, barrelpunk inspired, BattleSky Brigade series. Whilst its previous title BattleSky Brigade TapTap provided fans with idle town building gameplay, this time the... | Read more »
Arcade classic R-Type Dimensions EX blas...
If you're a long time fan of shmups and have been looking for something to play lately, Tozai Games may have just released an ideal game for you on iOS. R-Type Dimensions EX brings the first R-Type and its sequel to iOS devices. [Read more] | Read more »
Intense VR first-person shooter Colonicl...
Our latest VR obsession is Colonicle, an intense VR FPS, recently released on Oculus and Google Play, courtesy of From Fake Eyes and Goboogie Games. It's a pulse-pounding multiplayer shooter which should appeal to genre fanatics and newcomers alike... | Read more »
PUBG Mobile's incoming update bring...
PUGB Mobile's newest Royale Pass season they're calling Fury of the Wasteland arrives tomorrow and with it comes a fair chunk of new content to the game. We'll be seeing a new map, weapon and even a companion system. [Read more] | Read more »
PSA: Download Bastion for free, but wait...
There hasn’t been much news from Supergiant Games on mobile lately regarding new games, but there’s something going on with their first game. Bastion released on the App Store in 2012, and back then it was published by Warner Bros. This Warner... | Read more »
Apple Arcade: Ranked - 51+ [Updated 11.5...
This is Part 2 of our Apple Arcade Ranking list. To see part 1, go here. 51. Patterned [Read more] | Read more »
NABOKI is a blissful puzzler from acclai...
Acclaimed developer Rainbow Train's latest game, NABOKI, is set to launch for iOS, Android, and Steam on November 13th. It's a blissful puzzler all about taking levels apart in interesting, inventive ways. [Read more] | Read more »
A Case of Distrust is a narrative-driven...
A Case of Distrust a narrative-focused mystery game that's set in the roaring 20s. In it, you play as a detective with one of the most private eye sounding names ever – Phyllis Cadence Malone. You'll follow her journey in San Francisco as she... | Read more »
Brown Dust’s October update offers playe...
October is turning out to be a productive month for the Neowiz team, and a fantastic month to be a Brown Dust player. First, there was a crossover event with the popular manga That Time I Got Reincarnated as a Slime. Then, there was the addition of... | Read more »

Price Scanner via MacPrices.net

Score a 37% discount on Apple Smart Keyboards...
Amazon has Apple Smart Keyboards for current-generation 10″ iPad Airs and previous-generation 10″ iPad Pros on sale today for $99.99 shipped. That’s a 37% discount over Apple’s regular MSRP of $159... Read more
Apple has refurbished 2019 13″ 1.4GHz MacBook...
Apple has a full line of Certified Refurbished 2019 13″ 1.4GHz 4-Core Touch Bar MacBook Pros available starting at $1099 and up to $230 off MSRP. Apple’s one-year warranty is included, shipping is... Read more
2019 13″ 1.4GHz 4-Core MacBook Pros on sale f...
Amazon has new 2019 13″ 1.4GHz 4-Core Touch Bar MacBook Pros on sale for $150-$200 off Apple’s MSRP. These are the same MacBook Pros sold by Apple in its retail and online stores: – 2019 13″ 1.4GHz/... Read more
11″ 64GB Gray WiFi iPad Pro on sale for $674,...
Amazon has the 11″ 64GB Gray WiFi iPad Pro on sale today for $674 shipped. Their price is $125 off MSRP for this iPad, and it’s the lowest price available for the 64GB model from any Apple reseller. Read more
2019 15″ MacBook Pros available for up to $42...
Apple has a full line of 2019 15″ 6-Core and 8-Core Touch Bar MacBook Pros, Certified Refurbished, available for up to $420 off the cost of new models. Each model features a new outer case, shipping... Read more
2019 15″ MacBook Pros on sale this week for $...
Apple resellers B&H Photo and Amazon are offering the new 2019 15″ MacBook Pros for up to $300 off Apple’s MSRP including free shipping. These are the same MacBook Pros sold by Apple in its... Read more
Sunday Sale: AirPods with Wireless Charging C...
B&H Photo has Apple AirPods with Wireless Charging Case on sale for $159.99 through 11:59pm ET on November 11th. Their price is $40 off Apple’s MSRP, and it’s the lowest price available for these... Read more
Details of Sams Club November 9th one day App...
Through midnight Saturday night (November 9th), Sams Club online has several Apple products on sale as part of their One Day sales event. Choose free shipping or free local store pickup (if available... Read more
Sprint is offering the 64GB Apple iPhone 11 f...
Sprint has the new 64GB iPhone 11 available for $15 per month for new lines. That’s about 50% off their standard monthly lease of $29.17. Over is valid until November 24, 2019. The fine print: “Lease... Read more
New Sprint November iPhone deal: Lease one iP...
Switch to Sprint and purchase an Apple iPhone 11, 11 Pro, or 11 Pro Max, and get a second 64GB iPhone 11 for free. Requires 2 new lines or 1 upgrade-eligible line and 1 new line. Offer is valid from... Read more

Jobs Board

*Apple* Mobility Pro - Best Buy (United Stat...
**746087BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Store NUmber or Department:** 000319-Harlem & Irving-Store **Job Description:** Read more
Best Buy *Apple* Computing Master - Best Bu...
**743392BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Store Associates **Store NUmber or Department:** 001171-Southglenn-Store **Job Read more
Best Buy *Apple* Computing Master - Best Bu...
**746015BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Sales **Store NUmber or Department:** 000372-Federal Way-Store **Job Description:** Read more
*Apple* Mobility Pro - Best Buy (United Stat...
**744658BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Store NUmber or Department:** 000586-South Hills-Store **Job Description:** At Read more
Best Buy *Apple* Computing Master - Best Bu...
**741552BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Sales **Store NUmber or Department:** 000277-Metcalf-Store **Job Description:** **What Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.