
Guide Maker
How do I . . .
How do I speed up Guide Maker
compiles?
The slowest part of compiling a guide file is the time it takes for Guide
Maker to write each of the objects out to disk. Big guide files are made
up of thousands of resource-like objects. Because the resource manager gets
overwhelmed by the number of objects created, they're all handled by some
special database routines that write them into the data fork of the guide
file. These database disk reading and writing routines consume most of the
compile time. To speed up compiles, you can:
- switch to a faster computer - for example, compiling on a Quadra 800
takes about half the time of compiling on my Duo 280c. Using Guide Maker
1.2.5, which is native, on a PowerMac will give you an even greater speed
gain.
- compile your guide file on a RAM disk - faster reads/writes really speed
up compiles.
- use Guide Maker Lite - this stripped-down, compile-only version of Guide
Maker eliminates the MacApp overhead and graphics that slow down its big
brother. On a computer with a PowerPC 604 processor, Guide Maker Lite compiles
up to 10 times as fast as Guide Maker running on a 68040. Click this link
to download Guide
Maker Lite (353K).
- break a big guide file into smaller chunks - this technique lets you
quickly compile and test subsections of a large guide file without having
to suffer through very long compiles. It also has the advantage of allowing
multiple authors to work on sections of the guide independently.
We handle links between the separate chunks by defining stub/placeholder
objects in a special Setup file and a Build file for each of the subsections.
Each of the subsection Build files includes the needed Guide Script files
as well as the Setup file for that section. The Build file for the entire
guide file omits these special files, because they are not needed when compiling
all of the files together. For example, a typical set of folders/files might
look like:
Section 1 folder
- Section 1 Build
- Section 1 Panels
- Section 1 Sequences
- Section 1 Resources
- Section 1 Setup (includes all the stub objects and AccWin commands
necessary to compile section 1 independently, but won't be included in a
build of entire guide)
Section 2 folder
- Section 2 Build
- Section 2 Panels
- Section 2 Sequences
- Section 2 Resources
- Section 2 Setup
Shared folder
- Shared Panels
- Shared Sequences
- Shared Resources
Full Build folder
- All Build (points to Guide Script command and resource files from
each of the sections as well as the Shared folder)
- All Setup(includes all the AccWin commands necessary to compile the
entire guide file)
It takes a little time to setup the build files and setup files for each
of the subsections, but on large guide file projects, you'll quickly recover
the time through more efficient compiling.
How do I quickly check for syntax errors?
Guide Maker makes many passes through your Guide Script commands, building
up the hierarchy of objects in your guide file. This isn't quite accurate,
but it goes something like this:
- 1st pass - import all resources and merge all Guide Script commands
into one large file
- 2nd pass - check syntax of individual Guide Script commands (catches
bad parameters)
- 3rd pass - build basic objects (external to panels) and globals
- 4th pass - build panels (finds panel level problems - missing movies,
no end panel, etc.)
- 5th pass - repanel (handles cases where a single panel gets re-used)
- 6th pass - build sequences (detects sequence logic problems and bad
references to panels or sequences)
Guide Maker proceeds as far as it can, but stops when it can't be certain
that the objects required to continue have been built successfully. For
example, when checking command syntax, Guide Maker typically completes the
entire pass, but it sometimes stops if a huge numbers have been detected.
By the time it starts building sequences, individual errors can stop a compile,
because sequences often depend on other sequences being there.
A great feature available in Guide Maker 1.2.5 is Check Syntax Only. This
command works through the compile process and reports many of the small
syntax errors and typos without taking the time write out the objects to
disk. If you've made lots of changes to a file, checking the syntax before
starting a real compile can be a great time- and frustration-saving strategy.
How do I avoid Guide Maker / XTND
translator crashes?
As many have noted, Guide Maker crashes when using XTND translators to import
text from many word processing formats. Our experience has been:
- the "Microsoft Word 4-5" and "MacWrite II" XTND
translators are safe and reliable.
- other XTND translators seem to work for single file compiles, but crash
when you use multiple source files with a build file to link them.
- using any of the MacLinkPlus XTND translators slows down the compile
process to a crawl.
If you want to include styled text on your panels:
- use either Microsoft Word 5 (be sure to disable Fast Saves) or MacWrite
II to create the panels. You'll be able to compile these files without problems.
- or, if you prefer to use a different word processor, use the XTND translator
to save a copy of the source files in the MacWrite II format, then compile
the MacWrite II versions. This adds an additional step to the compile process,
but it will eliminate the XTND translator crash problems.
© 1997, guideWorks, LLC -- Last updated: 970325 GPB