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.

 
AAPL
$101.76
Apple Inc.
+0.18
MSFT
$46.78
Microsoft Corpora
+0.26
GOOG
$588.24
Google Inc.
+3.47

MacTech Search:
Community Search:

Software Updates via MacUpdate

Xcode 6.0.1 - Integrated development env...
Apple Xcode is Apple Computer's integrated development environment (IDE) for OS X. The full Xcode package is free to ADC members and includes all the tools you need to create, debug, and optimize... Read more
Apple Safari 7.1 - Apple's Web brow...
Apple Safari in OS X Mavericks brings you all-new ways to find and enjoy the best of the web. It works with iCloud to give you a seamless browsing experience across all your devices. It looks out for... Read more
Delivery Status 6.1.2 - Check delivery s...
Delivery Status displays delivery status of packages for a variety of shipment services. Can't wait for your packages to arrive? Don't waste your time checking the site constantly, just open this all... Read more
Mavericks Cache Cleaner 8.0.9 - Clear ca...
Mavericks Cache Cleaner is an award-winning general purpose tool for OS X. MCC makes system maintenance simple with an easy point-and-click interface to many OS X functions. Novice and expert users... Read more
OneNote 15.2.2 - Free digital notebook f...
OneNote is your very own digital notebook. With OneNote, you can capture that flash of genius, that moment of inspiration, or that list of errands that's too important to forget. Whether you're at... Read more
Apple Configurator 1.6 - Configure and d...
Apple Configurator makes it easy for anyone to mass configure and deploy iPhone, iPad, and iPod touch in a school, business, or institution. Three simple workflows let you prepare new iOS devices... Read more
SpamSieve 2.9.16 - Robust spam filter fo...
SpamSieve is a robust spam filter for major email clients that uses powerful Bayesian spam filtering. SpamSieve understands what your spam looks like in order to block it all, but also learns what... Read more
OS X Server 3.2.1 - For OS X 10.9.5 Mave...
OS X Server is the next generation of Apple's award winning server software. Designed for OS X and iOS devices, OS X Server makes it easy to share files, schedule meetings, synchronize contacts, host... Read more
Apple Security Update 2014-004 - For OS...
Apple Security Update is recommended for all users and improves the security of Mac OS X. For information on the security content of this update, please visit this website: http://support.apple.com/... Read more
OS X Mavericks 10.9.5 - The latest versi...
Apple OS X Mavericks is the latest release of the world's most advanced desktop operating system. Now free! With more than 200 new features, OS X Mavericks brings Maps and iBooks to the Mac,... Read more

Latest Forum Discussions

See All

Sling Adds Chromecast Support Through Sl...
Sling Adds Chromecast Support Through Slingplaye​r Mobile Apps Posted by Jessica Fisher on September 18th, 2014 [ permalink ] | Read more »
How to Completely Delete Your iPhone’s C...
The iPhone 6 is out tomorrow, and plenty of people are excited about it. So much so that they’re planning to – or already have – traded in their old iPhone to go towards it. The thing about trading in hardware is it’s very important to make sure... | Read more »
Dragon Quest I Review
Dragon Quest I Review By Andrew Fisher on September 18th, 2014 Our Rating: :: THINE QUEST AWAITETHUniversal App - Designed for iPhone and iPad Its historical significance aside, Dragon Quest 1 is a fun, campy, difficult, thoroughly... | Read more »
It Came From Canada: Overkill 3
Overkill 3 is like every trope of big modern gaming rolled into one. It’s a sequel to an action-packed military shooter. It’s flashy and scripted and flaunts its sophisticated graphics. And it’s a mobile game with a heavy emphasis on in-app... | Read more »
New Modes and Leader Boards in Update fo...
New Modes and Leader Boards in Update for Rules! Posted by Jessica Fisher on September 18th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
TwistedRun Review
TwistedRun Review By Rob Thomas on September 18th, 2014 Our Rating: :: DON'T TWIST YOUR ANKLE!Universal App - Designed for iPhone and iPad TwistedRun is kind of like running up a giant curly fry into the sky. Or maybe that was just... | Read more »
Scope Review
Scope Review By Jennifer Allen on September 18th, 2014 Our Rating: :: LOCATION AWAREiPhone App - Designed for the iPhone, compatible with the iPad Want to easily find photos from around the world based on their location? Scope is a... | Read more »
HipstaFox Review
HipstaFox Review By Jordan Minor on September 18th, 2014 Our Rating: :: FANTASTIC MR. FOXUniversal App - Designed for iPhone and iPad HipstaFox is a great single that makes players long for the whole album.   | Read more »
Ninja Raft (Games)
Ninja Raft 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: ** Special Launch Price ** "Ninja Raft is definitely the game to play if you’re into Tower Defense games and want to play something... | Read more »
Paste+ | Clipboard Action Widget (Produ...
Paste+ | Clipboard Action Widget 1.0.0 Device: iOS iPhone Category: Productivity Price: $3.99, Version: 1.0.0 (iTunes) Description: Powerful clipboard widget for iOS 8. Reimagine what you can do with your clipboard! Paste+ is a... | Read more »

Price Scanner via MacPrices.net

Save up to $300 on the price of a new Mac wit...
Purchase a new Mac or iPad at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free,... Read more
13-inch 2.8GHz Retina MacBook Pro available f...
B&H Photo has the new 2014 13″ 2.8GHz Retina MacBook Pro on sale for $1699.99 including free shipping plus NY sales tax only. They’ll also include free copies of Parallels Desktop and LoJack for... Read more
16GB iPad Air on sale for $449, save $50
Walmart has the 16GB iPad Air WiFi on sale for $449 on their online store for a limited time. Choose free home shipping or free local store pickup. Their price represents a $50 savings over standard... Read more
13-inch 256GB MacBook Air on sale for $1099,...
B&H Photo has the 2014 13″ 1.4GHz 256GB MacBook Air on sale for $1099.99. Shipping is free, and B&H charges NY sales tax only. Their price is $100 off MSRP. Read more
Toshiba Introduces TransMemory ID High-Speed...
Toshiba’s Digital Products Division (DPD), a division of Toshiba America Information Systems, Inc., today introduced the TransMemory ID USB 3.0 Flash Drive, a simpler storage solution for people who... Read more
New iPads and OS X Yosemite Release Coming Oc...
The DailyDot’s Micah Singleton reports that Apple is planning to hold its next product announcement event on Oct. 21, at which it will unveil the iPad Air 2 and iPad mini 3 and release a final build... Read more
Logitech Bluetooth Multi-Device Cross-Platfor...
Logitech has an enviable track record of making some of the best computer keyboards and mice. At least in my estimation, the best freestanding keyboards I’ve ever used have been Logitech units,... Read more
Roundup of Apple refurbished iPad Airs and iP...
Apple is offering Certified Refurbished iPad Airs for up to $140 off MSRP. Apple’s one-year warranty is included with each model, and shipping is free. Stock tends to come and go with some of these... Read more
Sprint offers 16GB iPad mini for $199.99 with...
Sprint is offering 1st generation 16GB iPad minis for $199.99 with a 2-year service agreement. Standard MSRP for this iPad is $429. Their price is the lowest available for this model. Read more
2.5GHz Mac mini remains on sale for $549, sav...
B&H Photo has the 2.5GHz Mac mini on sale for $549.99 including free shipping. That’s $50 off MSRP, and B&H will also include a free copy of Parallels Desktop software. NY sales tax only. Read more

Jobs Board

Project Manager, *Apple* Financial Services...
**Job Summary** Apple Financial Services (AFS) offers consumers, businesses and educational institutions ways to finance Apple purchases. We work with national and Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.