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
$102.10
Apple Inc.
+2.34
MSFT
$44.83
Microsoft Corpora
+0.75
GOOG
$522.10
Google Inc.
+1.26

MacTech Search:
Community Search:

Software Updates via MacUpdate

RapidWeaver 6.0 - Create template-based...
RapidWeaver is a next-generation Web design application to help you easily create professional-looking Web sites in minutes. No knowledge of complex code is required, RapidWeaver will take care of... Read more
NTFS 12.0.39 - Provides full read and wr...
Paragon NTFS breaks down the barriers between Windows and OS X. Paragon NTFS effectively solves the communication problems between the Mac system and NTFS, providing full read and write access to... Read more
RestoreMeNot 2.0.3 - Disable window rest...
RestoreMeNot provides a simple way to disable the window restoration for individual applications so that you can fine-tune this behavior to suit your needs. Please note that RestoreMeNot is designed... Read more
Macgo Blu-ray Player 2.10.9.1750 - Blu-r...
Macgo Mac Blu-ray Player can bring you the most unforgettable Blu-ray experience on your Mac. Overview Macgo Mac Blu-ray Player can satisfy just about every need you could possibly have in a Blu-ray... Read more
Apple iOS 8.1 - The latest version of Ap...
The latest version of iOS can be downloaded through iTunes. Apple iOS 8 comes with big updates to apps you use every day, like Messages and Photos. A whole new way to share content with your family.... Read more
TechTool Pro 7.0.5 - Hard drive and syst...
TechTool Pro is now 7, and this is the most advanced version of the acclaimed Macintosh troubleshooting utility created in its 20-year history. Micromat has redeveloped TechTool Pro 7 to be fully 64... Read more
PDFKey Pro 4.0.2 - Edit and print passwo...
PDFKey Pro can unlock PDF documents protected for printing and copying when you've forgotten your password. It can now also protect your PDF files with a password to prevent unauthorized access and/... Read more
Yasu 2.9.1 - System maintenance app; per...
Yasu was originally created with System Administrators who service large groups of workstations in mind, Yasu (Yet Another System Utility) was made to do a specific group of maintenance tasks... Read more
Hazel 3.3 - Create rules for organizing...
Hazel is your personal housekeeper, organizing and cleaning folders based on rules you define. Hazel can also manage your trash and uninstall your applications. Organize your files using a... Read more
Autopano Giga 3.7 - Stitch multiple imag...
Autopano Giga allows you to stitch 2, 20, or 2,000 images. Version 3.0 integrates impressive new features that will definitely make you adopt Autopano Pro or Autopano Giga: Choose between 9... Read more

Latest Forum Discussions

See All

Tilt to Live: Gauntlet’s Revenge is Almo...
Tilt to Live: Gauntlet’s Revenge is Almost Here Posted by Jessica Fisher on October 21st, 2014 [ permalink ] One Man Left has announced the official release date of Tilt to Live: Gauntlet’s Re | Read more »
Sago Mini Monsters Celebrates Halloween...
Sago Mini Monsters Celebrates Halloween with Fun Costumes and Special Treats. Posted by Jessica Fisher on October 21st, 2014 [ permal | Read more »
Inferno 2 Review
Inferno 2 Review By Andrew Fisher on October 21st, 2014 Our Rating: :: TWIN STICK GOODNESSUniversal App - Designed for iPhone and iPad With tight controls and awesome, stark visuals, Inferno 2 is loads of fun.   | Read more »
Clips Review
Clips Review By Jennifer Allen on October 21st, 2014 Our Rating: :: CONVENIENT PASTINGUniversal App - Designed for iPhone and iPad Making copying and pasting more powerful than usual, Clips is a great way to move stuff around.   | Read more »
MonSense Review
MonSense Review By Jennifer Allen on October 21st, 2014 Our Rating: :: ORGANIZED FINANCESiPhone App - Designed for the iPhone, compatible with the iPad Organize your finances with the quick and easy to use, MonSense.   | Read more »
This Week at 148Apps: October 13-17, 201...
Expert App Reviewers   So little time and so very many apps. What’s a poor iPhone/iPad lover to do? Fortunately, 148Apps is here to give you the rundown on the latest and greatest releases. And we even have a tremendous back catalog of reviews; just... | Read more »
Angry Birds Transformers Review
Angry Birds Transformers Review By Jennifer Allen on October 20th, 2014 Our Rating: :: TRANSFORMED BIRDSUniversal App - Designed for iPhone and iPad Transformed in a way you wouldn’t expect, Angry Birds Transformers is a quite... | Read more »
GAMEVIL Announces the Upcoming Launch of...
GAMEVIL Announces the Upcoming Launch of Mark of the Dragon Posted by Jessica Fisher on October 20th, 2014 [ permalink ] Mark of the Dragon, by GAMEVIL, put | Read more »
Interview With the Angry Birds Transform...
Angry Birds Transformers recently transformed and rolled out worldwide. This run-and-gun title is a hit with young Transformers fans, but the ample references to classic Transformers fandom has also earned it a place in the hearts of long-time... | Read more »
Hail to the King: Deathbat Review
Hail to the King: Deathbat Review By Rob Thomas on October 20th, 2014 Our Rating: :: SO FAR AWAYUniversal App - Designed for iPhone and iPad Hail to the King: Deathbat may feel like “Coming Home” for Avenged Sevenfold’s faithful,... | Read more »

Price Scanner via MacPrices.net

Select MacBook Airs $100 off MSRP, free shipp...
B&H Photo has 2014 a couple of MacBook Airs on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only. They also include free copies of Parallels Desktop and LoJack for... Read more
13-inch 2.5GHz MacBook Pro on sale for $100 o...
B&H Photo has the 13″ 2.5GHz MacBook Pro on sale for $999.99 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more
Strong iPhone, Mac And App Store Sales Drive...
Apple on Monday announced financial results for its fiscal 2014 fourth quarter ended September 27, 2014. The Company posted quarterly revenue of $42.1 billion and quarterly net profit of $8.5 billion... Read more
Apple Posts How-To For OS X Recovery
OS X 10.7 Lion and later include OS X Recovery. This feature includes all of the tools you need to reinstall OS X, repair your disk, and even restore from a Time Machine backup. OS X Recovery... Read more
Mac OS X Versions (Builds) Supported By Vario...
Apple Support has posted a handy resource explaining which Mac OS X versions (builds) originally shipped with or are available for your computer via retail discs, downloads, or Software Update. Apple... Read more
Deals on 2011 13-inch MacBook Airs, from $649
Daily Steals has the Mid-2011 13″ 1.7GHz i5 MacBook Air (4GB/128GB) available for $699 with a 90 day warranty. The Mid-2011 13″ 1.7GHz i5 MacBook Air (4GB/128GB SSD) is available for $649 at Other... Read more
2013 15-inch 2.0GHz Retina MacBook Pro availa...
B&H Photo has leftover previous-generation 15″ 2.0GHz Retina MacBook Pros now available for $1599 including free shipping plus NY sales tax only. Their price is $400 off original MSRP. B&H... Read more
Updated iPad Prices
We’ve updated our iPad Air Price Tracker and our iPad mini Price Tracker with the latest information on prices and availability from Apple and other resellers, including the new iPad Air 2 and the... Read more
Apple Pay Available to Millions of Visa Cardh...
Visa Inc. brings secure, convenient payments to iPad Air 2 and iPad mini 3as well as iPhone 6 and 6 Plus. Starting October 20th, eligible Visa cardholders in the U.S. will be able to use Apple Pay,... Read more
Textkraft Pocket – the missing TextEdit for i...
infovole GmbH has announced the release and immediate availability of Textkraft Pocket 1.0, a professional text editor and note taking app for Apple’s iPhone. In March 2014 rumors were all about... Read more

Jobs Board

Senior Event Manager, *Apple* Retail Market...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global event strategy. Delivering an overarching brand story; in-store, Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Project Manager / Business Analyst, WW *Appl...
…a senior project manager / business analyst to work within our Worldwide Apple Fulfillment Operations and the Business Process Re-engineering team. This role will work Read more
*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Position Opening at *Apple* - Apple (United...
…customers purchase our products, you're the one who helps them get more out of their new Apple technology. Your day in the Apple Store is filled with a range of Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.