Jeanne's World    Apple Guide Place        Apple Guide FAQs

How do I set up and compile a mixin?

You write a mixin in much the same way as an ordinary guide file. To add new content, you define and use sequences, panels, context checks, and so forth. Then you add special mixin-related GuideScript commands to indicate how you want this content to alter the parent guide.

The <mixin> command

The <mixin> command is required for all mixins. It must be the first command in the first source file of your mixin. The command looks like this:

<mixin> symFile, startResourceID

You can specify a symFile, a startResourceID, or both. (Versions of GuideMaker before 1.2.5 allow one or the other, but not both parameters.)

The SYM file is a resource file that GuideMaker generated when you compiled the parent guide. This file contains information about the objects in the parent guide, and must be included if you want the mixin to modify the parent guide. You can create a mixin without using the SYM file, but it will only be able to add topic areas and index terms; it will not be able to replace existing content or make changes to the parent guide's topic list or index.

The startResourceID determines which resource IDs GuideMaker will allocate to the mixin. Legal values for guide resources are in the range 2000-20,000. If you don't include this parameter, GuideMaker starts using resources for the mixin wherever the parent guide left off; if you do specify a resource ID, make sure to leave sufficient headroom for the resources in the parent guide. Most guides of moderate size use less than 2000 resource ID slots, so you might use a startResourceID of 4000 for the mixin.

If you are developing multiple mixins which will all mix into the same parent guide at the same time, use a different startResourceID for each one to make sure their resource IDs don't conflict.

The <mixin match> command

The <mixin match> command lets you control which parent guides a mixin can mix into. The parameter is a four-character code. If you use a <mixin match> in the parent guide, only mixins with the same code can mix into that guide, and vice versa, so you can use this command to ensure a mixin only mixes into its parent guide. It's also useful for version control: change the mixin match parameter with each version to make sure old mixins don't interfere with new parent guides or vice versa.

If you don't include a <mixin match>, the mixin will mix into any guide that's in the same folder, as long as that guide doesn't include a <mixin match> itself.

The <replace sequence> command

You use the <replace sequence> command to replace an entire sequence in the parent guide with one in the mixin.

The sequence in the mixin is used wherever the original sequence was, with one exception: if the parent guide used the <insert sequence> command in a sequence, and you replace the inserted sequence, the original material will still appear rather than the new material from the mixin. The reason for this is that <insert sequence> includes the contents of the inserted sequence at compile time, instead of creating a jump to the inserted sequence; in other words, <insert sequence> is a shortcut for copying and pasting the contents of the inserted sequence.

Insertion and deletion commands

If you include topic areas in the mixin, they'll be appended to the end of the parent guide's topic list when the mixin is active. If you include index terms, they will appear in the parent guide's index, in alphabetical order. Including topic areas and index terms is the simplest way to let the user access the new information in the mixin.

You can also change the index and topics list by deleting topic areas, inserting new topic areas and sequences wherever you want them, deleting index terms, and inserting new sequences for an existing index term.

These commands are not required for a mixin; you can append new topic areas and index terms simply by including them in your mixin source. They are needed only if you want to modify, as well as add to, the parent guide.

You can find more information about mixin-specific commands in Apple Guide Complete, pages 191-210.

How do I control when a mixin mixes into the parent guide?

Jeanne A. E. DeVoto jaed@jaedworks.com
Copyright © 1997 Jeanne A. E. DeVoto