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
$98.15
Apple Inc.
-0.23
MSFT
$43.58
Microsoft Corpora
-0.31
GOOG
$587.42
Google Inc.
+1.81

MacTech Search:
Community Search:

Software Updates via MacUpdate

Knock 1.1.7 - Unlock your Mac by knockin...
Knock is a faster, safer way to sign in. You keep your iPhone with you all the time. Now you can use it as a password. You never have to open the app -- just knock on your phone twice, even when it's... Read more
Mellel 3.3.6 - Powerful word processor w...
Mellel is the leading word processor for OS X and has been widely considered the industry standard since its inception. Mellel focuses on writers and scholars for technical writing and multilingual... Read more
LibreOffice 4.3.0.4 - Free Open Source o...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
Freeway Pro 7.0 - Drag-and-drop Web desi...
Freeway Pro lets you build websites with speed and precision... without writing a line of code! With it's user-oriented drag-and-drop interface, Freeway Pro helps you piece together the website of... Read more
Drive Genius 3.2.4 - Powerful system uti...
Drive Genius is an OS X utility designed to provide unsurpassed storage management. Featuring an easy-to-use interface, Drive Genius is packed with powerful tools such as a drive optimizer, a... Read more
Vitamin-R 2.15 - Personal productivity t...
Vitamin-R creates the optimal conditions for your brain to work at its best by structuring your work into short bursts of distraction-free, highly focused activity alternating with opportunities for... Read more
Toast Titanium 12.0 - The ultimate media...
Toast Titanium goes way beyond the very basic burning in the Mac OS and iLife software, and sets the standard for burning CDs, DVDs, and now Blu-ray discs on the Mac. Create superior sounding audio... Read more
OS X Yosemite Wallpaper 1.0 - Desktop im...
OS X Yosemite Wallpaper is the gorgeous new background image for Apple's upcoming OS X 10.10 Yosemite. This wallpaper is available for all screen resolutions with a source file that measures 5,418... Read more
Acorn 4.4 - Bitmap image editor. (Demo)
Acorn is a new image editor built with one goal in mind - simplicity. Fast, easy, and fluid, Acorn provides the options you'll need without any overhead. Acorn feels right, and won't drain your bank... Read more
Bartender 1.2.20 - Organize your menu ba...
Bartender lets you organize your menu bar apps. Features: Lets you tidy your menu bar apps how you want. See your menu bar apps when you want. Hide the apps you need to run, but do not need to... Read more

Latest Forum Discussions

See All

Murl the Squirrel (Games)
Murl the Squirrel 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: Meet Murl. He is teased by a group of flying squirrels because he can't fly. Determined to show them he's can fly, he meets... | Read more »
Celleste (Games)
Celleste 0.1 Device: iOS Universal Category: Games Price: $2.99, Version: 0.1 (iTunes) Description: Lots of cute action with amazing 3D graphics and a new type of gameplay! Take control over the forces of the universe to help a group... | Read more »
Super Heavy Sword (Games)
Super Heavy Sword 0.0.1 Device: iOS Universal Category: Games Price: $.99, Version: 0.0.1 (iTunes) Description: Get Ready to Get HEAVY! Monster Robot Studios presents SUPER Heavy Sword! The sequel to the smash hit HEAVY sword which... | Read more »
Angels In The Sky (Games)
Angels In The Sky 1.00 Device: iOS Universal Category: Games Price: $6.99, Version: 1.00 (iTunes) Description: - This game is only for the iPhone 5s. please do not use the iPad, iPhone 5 or earlier devices.- Just touch or holding... | Read more »
80 Days (Games)
80 Days 1.0.2 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.2 (iTunes) Description: 1872, with a steampunk twist. Phileas Fogg has wagered he can circumnavigate the world in just eighty days. Choose your own route... | Read more »
Micromon (Games)
Micromon 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: 130+ Animated Monsters to Catch & Battle! No waiting, play at your own pace! Embark on an epic monster capture RPG like none... | Read more »
Empire Manager (Games)
Empire Manager 1.0 Device: iOS iPhone Category: Games Price: $3.99, Version: 1.0 (iTunes) Description: Become ruler of an empire. Manage your economy, develop technology, hire an army and conquer the world in this addictive turn-... | Read more »
Empire Manager HD (Games)
Empire Manager HD 1.0 Device: iOS Universal Category: Games Price: $7.99, Version: 1.0 (iTunes) Description: Become ruler of an empire. Manage your economy, develop technology, hire an army and conquer the world in this addictive... | Read more »
Star Admiral Review
Star Admiral Review By Rob Thomas on July 30th, 2014 Our Rating: :: ADMIRABLE ADMIRALSUniversal App - Designed for iPhone and iPad While this new digital CCG may feel a bit familiar, Star Admiral offers a sci-fi twist and galaxy’s... | Read more »
Zap! Pow! Become a Badass Wizard in Phan...
Zap! Pow! | Read more »

Price Scanner via MacPrices.net

iPad Cannibalization Threat “Overblown”
Seeking Alpha’s Kevin Greenhalgh observes that while many commentators think Apple’s forthcoming 5.5-inch panel iPhone 6 will cannibalize iPad sales, in his estimation, these concerns are being... Read more
Primate Labs Releases July 2014 MacBook Pro P...
Primate Labs’ John Poole has posted Geekbench 3 results for most of the new MacBook Pro models that Apple released on Tuesday. Poole observes that overall performance improvements for the new MacBook... Read more
Apple Re-Releases Bugfixed MacBook Air EFI Fi...
Apple has posted a bugfixed version EFI Firmware Update 2.9 a for MacBook Air (Mid 2011) models. The update addresses an issue where systems may take longer to wake from sleep than expected, and... Read more
Save $50 on the 2.5GHz Mac mini, plus free sh...
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
Save up to $140 on an iPad Air with Apple ref...
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
$250 price drop on leftover 15-inch Retina Ma...
B&H Photo has dropped prices on 2013 15″ Retina MacBook Pros by $250 off original MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.3GHz Retina MacBook Pro: $2249, $250 off... Read more
More iPad Upgrade Musings – The ‘Book Mystiqu...
Much discussed recently, what with Apple reporting iPad sales shrinkage over two consecutive quarters, is that it had apparently been widely assumed that tablet users would follow a two-year hardware... Read more
13-inch 2.5GHz MacBook Pro on sale for $999,...
Best Buy has the 13″ 2.5GHz MacBook Pro available for $999.99 on their online store. Choose free shipping or free instant local store pickup (if available). Their price is $100 off MSRP. Price is... Read more
Save up to $300 on an iMac with Apple refurbi...
The Apple Store has Apple Certified Refurbished iMacs available for up to $300 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free. These are the best prices on... Read more
WaterField Unveils 15″ Outback Solo & 13″...
Hard on the heels of Apple’s refreshed MacBook Pro Retina laptops announcement, WaterField Designs has unveiled a 15-inch version of the waxed-canvas and leather Outback Solo and a 13-inch version of... Read more

Jobs Board

Sr. Product Leader, *Apple* Store Apps - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full Read more
Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full 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
Sr. Product Leader, *Apple* Store Apps - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.