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

Bookends 13.2.6 - Reference management a...
Bookends is a full-featured bibliography/reference and information-management system for students and professionals. Bookends uses the cloud to sync reference libraries on all the Macs you use.... Read more
BusyContacts 1.4.0 - Fast, efficient con...
BusyContacts is a contact manager for OS X that makes creating, finding, and managing contacts faster and more efficient. It brings to contact management the same power, flexibility, and sharing... Read more
Chromium 77.0.3865.75 - Fast and stable...
Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all Internet users to experience the web. Version 77.0.3865.75: A list of changes is available... Read more
DiskCatalogMaker 7.5.5 - Catalog your di...
DiskCatalogMaker is a simple disk management tool which catalogs disks. Simple, light-weight, and fast Finder-like intuitive look and feel Super-fast search algorithm Can compress catalog data for... Read more
Alfred 4.0.4 - Quick launcher for apps a...
Alfred is an award-winning productivity application for OS X. Alfred saves you time when you search for files online or on your Mac. Be more productive with hotkeys, keywords, and file actions at... Read more
A Better Finder Rename 10.45 - File, pho...
A Better Finder Rename is the most complete renaming solution available on the market today. That's why, since 1996, tens of thousands of hobbyists, professionals and businesses depend on A Better... Read more
iFinance 4.5.11 - Comprehensively manage...
iFinance allows you to keep track of your income and spending -- from your lunchbreak coffee to your new car -- in the most convenient and fastest way. Clearly arranged transaction lists of all your... Read more
OmniGraffle Pro 7.11.3 - 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
BBEdit 12.6.7 - Powerful text and HTML e...
BBEdit is the leading professional HTML and text editor for the Mac. Specifically crafted in response to the needs of Web authors and software developers, this award-winning product provides a... Read more
OmniGraffle 7.11.3 - 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

Five Nights at Freddy's AR: Special...
Five Nights at Freddy's AR: Special Delivery is a terrifying new nightmare from developer Illumix. Last week, FNAF fans were sent into a frenzy by a short teaser for what we now know to be Special Delivery. Those in the comments were quick to... | Read more »
Rush Rally 3's new live events are...
Last week, Rush Rally 3 got updated with live events, and it’s one of the best things to happen to racing games on mobile. Prior to this update, the game already had multiplayer, but live events are more convenient in the sense that it’s somewhat... | Read more »
Why your free-to-play racer sucks
It’s been this way for a while now, but playing Hot Wheels Infinite Loop really highlights a big issue with free-to-play mobile racing games: They suck. It doesn’t matter if you’re trying going for realism, cart racing, or arcade nonsense, they’re... | Read more »
Steam Link Spotlight - The Banner Saga 3
Steam Link Spotlight is a new feature where we take a look at PC games that play exceptionally well using the Steam Link app. Our last entry talked about Terry Cavanaugh’s incredible Dicey Dungeons. Read about how it’s a great mobile experience... | Read more »
PSA: GRIS has some issues
You may or may not have seen that Devolver Digital just released GRIS on the App Store, but we wanted to do a quick public service announcement to say that you might not want to hop on buying it just yet. The puzzle platformer has come to small... | Read more »
Explore the world around you in new matc...
Got a hankering for a fresh-feeling Match-3 puzzle game that offers a unique twist? You might find exactly what you’re looking for with What a Wonderful World, a new spin on the classic mobile genre which merges entertaining puzzles with global... | Read more »
Combo Quest (Games)
Combo Quest 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: Combo Quest is an epic, time tap role-playing adventure. In this unique masterpiece, you are a knight on a heroic quest to retrieve... | Read more »
Hero Emblems (Games)
Hero Emblems 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: ** 25% OFF for a limited time to celebrate the release ** ** Note for iPhone 6 user: If it doesn't run fullscreen on your device... | Read more »
Puzzle Blitz (Games)
Puzzle Blitz 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Puzzle Blitz is a frantic puzzle solving race against the clock! Solve as many puzzles as you can, before time runs out! You have... | Read more »
Sky Patrol (Games)
Sky Patrol 1.0.1 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0.1 (iTunes) Description: 'Strategic Twist On The Classic Shooter Genre' - Indie Game Mag... | Read more »

Price Scanner via MacPrices.net

Sunday Sale! 2019 27″ 5K 6-Core iMacs for $20...
B&H Photo has the new 2019 27″ 5K 6-Core iMacs on stock today and on sale for up to $250 off Apple’s MSRP. Overnight shipping is free to many locations in the US. These are the same iMacs sold by... Read more
Weekend Sale! 2019 13″ MacBook Airs for $200...
Amazon has new 2019 13″ MacBook Airs on sale for $200 off Apple’s MSRP, with prices starting at $899, each including free shipping. Be sure to select Amazon as the seller during checkout, rather than... Read more
2019 15″ MacBook Pros now on sale for $350-$4...
B&H Photo has Apple’s 2019 15″ 6-Core and 8-Core MacBook Pros on sale today for $350-$400 off MSRP, starting at $2049, with free overnight shipping available to many addresses in the US: – 2019... Read more
Buy one Apple Watch Series 5 at Verizon, get...
Buy one Apple Watch Series 5 at Verizon, and get a second Watch for 50% off. Plus save $10 on your first month of service. The fine print: “Buy Apple Watch, get another up to 50% off on us. Plus $10... Read more
Sprint offers 64GB iPhone 11 for free to new...
Sprint will include the 64GB iPhone 11 for free for new customers with an eligible trade-in in of the iPhone 7 or newer through September 19, 2019. The fine print: “iPhone 11 64GB $0/mo. iPhone 11... Read more
Verizon offers new iPhone 11 models for up to...
Verizon is offering Apple’s new iPhone 11 models for $500 off MSRP to new customers with an eligible trade-in (see list below). Discount is applied via monthly bill credits over 24 months. Verizon is... Read more
AT&T offers free $300 reward card + free...
AT&T Wireless will include a second free 64GB iPhone 11 with the purchase of one eligible iPhone at full price. They will also include a free $300 rewards card. The fine print: “Buy an elig.... Read more
US Cellular offers 64GB iPhone 11 for free to...
US Cellular is offering the base 64GB iPhone 11 for free for new customers. Qualified trade-in of iPhone 7 or higher required (or a number of Android phones). Discounts are applied via monthly bill... Read more
New 7th generation 10.2″ 128GB iPads availabl...
Amazon is accepting preorders for Apple’s new 7th generation 10.2″ 128GB iPads for $399.99 each, or $30 off Apple’s MSRP for this model. Shipping is free: – 10.2″ 128GB WiFi iPad Space Gray: $399.99... Read more
Sprint has the new 7th Generation iPad on sal...
Sprint has the new 2019 7th Generation 32GB WiFi + Cellular iPad available starting at only $99.99 from 9/12/19 to 10/3/19. Their price is a $360 savings over Apple’s standard MSRP. See the deal live... Read more

Jobs Board

Geek Squad *Apple* Master Consultation Agen...
**732131BR** **Job Title:** Geek Squad Apple Master Consultation Agent **Job Category:** Services/Installation/Repair **Location Number:** 000399-Wausau-Store **Job Read more
*Apple* Mobility Pro - Best Buy (United Stat...
**723452BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Location Number:** 001194-Greeley-Store **Job Description:** At Best Buy, our Read more
Best Buy *Apple* Computing Master - Best Bu...
**732027BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Store Associates **Location Number:** 002507-Alexandria-Store **Job Description:** The Read more
Best Buy *Apple* Computing Master - Best Bu...
**727669BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Sales **Location Number:** 000890-Buckhead-Store **Job Description:** **What does a Read more
Geek Squad *Apple* Master Consultation Agen...
**731944BR** **Job Title:** Geek Squad Apple Master Consultation Agent **Job Category:** Services/Installation/Repair **Location Number:** 001130-Nashville Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.