Apple Guide FAQ

What is a mixin?
How do I decide whether to use mixins?
How do I set up and compile a mixin?
How do I control when a mixin mixes into the parent guide?
How do I use elements from the parent guide in a mixin?
Why does GuideMaker refuse to compile my mixin?
Why won't a mixin mix into the parent guide?
Why does the guide look strange when a mixin is active?

What is a mixin?

A mixin (also called a Guide Addition) is an add-on Apple Guide file that can modify its parent guide at run time. A mixin can add sequences or suppress the display of existing sequences in the guide; it can change the index and topics list; and it can override sequences in the guide, replacing them with new content. You can limit a mixin so that it "mixes in" only on machines with a certain configuration, and otherwise leaves the parent guide unchanged.

The mixin is placed in the same folder as the parent guide, but it does not appear in the Guide menu, and the user never selects it directly. Instead, Apple Guide automatically applies the mixin's changes to the parent guide whenever the parent guide is opened.

A mixin can be used:

as a change file for a new version, so that you don't need to distribute the entire guide to users who upgrade.
to present information that's only relevant for a particular configuration. For example, a mixin might add instructions for features that are only available on a color monitor.
to provide alternative instructions for different configurations. For example, you can provide separate mixins for AV and non-AV machines.

You can use a qualifier resource - a code segment that returns a boolean - to specify the conditions under which a mixin should mix into the parent guide. When the parent guide is opened, if a qualifier resource is present, Apple Guide checks the qualifier result; if the conditions aren't met, the mixin is ignored and doesn't affect the parent guide.

How do I decide whether to use mixins?