How to Use Add Lists

Introduction

This document describes the format of an add list, which is a plain text file you can provide to the AAT Font Tool in order to add new glyphs to a font. The glyphs you add are composites made up of glyphs which already exist in the font; which glyphs those are and where they are placed relative to each other is up to you. Once the AAT Font Tool is finished adding the glyphs, it will also add the tables needed to access those glyphs (assuming they aren't just immediately keyboard accessible), but note that the resulting font can also be used in a non-AAT system, and the glyphs will still be there. You might want to use TrueEdit to edit the new font, since you can thereby add entries to existing 'cmap' tables (or add new 'cmap' tables) in order to be able to type your new glyphs.

Creating an Add List

To create an add list you can use any word processor which allows you to save as plain text, or use a text editor such as MPW or Metrowerks. Each new glyph you wish to add to the font is represented by several lines in the text file, where each line comprises several tab-delimited fields and is terminated with a carriage return. There are several examples of complete add lists in the examples section of this document; you can also open the "Roman Adds" file to see a complete list of accented glyphs which may be added to any font.

The first line

The first line of an add list entry contains information about the whole new glyph you're adding. The first field on this line is the PostScript® name of the new glyph. If you want the AAT Font Tool to include the new glyph in the morph tables it builds, you should choose a name from the list of names the AAT Font Tool recognizes; however, you may certainly add glyphs which aren't on that list, if you wish. See the various "Glyph Names" documents (included with the AAT Font Tool) for exact names you can use.

The next field on the first line is the count of the number of component glyphs making up this new glyph.

After the count, one or several optional flags may appear on the first line, separated by spaces. These flags are defined as follows:

Use Cluster Advance ("-C")

The "-C" flag tells the AAT Font Tool to use the cumulated width for all of the component pieces in determining the advance width of this new glyph. This is not the default case, which is why you have to specify it. The default is to just use the advance width of the first component. This is the usual case for the "baseform plus accent" combination, where you want the width of the new glyph to be the same as the width of the baseform.

Zero Sidebearings ("-Z")

The "-Z" flag tells the AAT Font Tool to zero the sidebearings of the new glyph; you will not usually specify this for Roman fonts.

Force Advance Width ("-W glyph")

The "-W" flag tells the AAT Font Tool to copy the advance width of another glyph for this new glyph being added. The glyph specified after the "-W" can be either a numerical glyph index, or else a valid name.

The component line(s)

After the first line there follow immediately one or more lines, one per component glyph making up this new glyph. We'll call these the "component lines." The first component line is sometimes referred to as the "baseform line" since it is usually (though not always) the main component, the piece which "anchors" the whole new glyph.

The first field on a component line is either a glyph index or else a PostScript name. In order to use the name, you should make sure the font has a real 'post' table, which is to say a 'post' table in a format other than 3. If the font has a format 3 'post' table, you can tell the AAT Font Tool to build a real 'post' table by providing a name list, which is just a plain text file naming all the glyphs in the font, one name per line.

The next two fields are the delta-X and delta-Y values. The baseform line will usually have zeroes for these values, though it need not do so. These are signed values, and are expressed in font units. Note, however, that certain flags (see below) can change the interpretation of one or both of these delta values. In the absence of any flags, these deltas are relative to the natural origin of the component. Thus, if you specified several components with zero deltas and no flags, the new composite glyph would have the glyphs overlaid on top of each other, aligning them on their origins.

After the delta-X and delta-Y values, several different flags may appear. These flags are defined as follows:

Link to Prior Component ("-L")

If this flag is present, the delta-X for this component is not interpreted as a distance. Rather, it is the index of a previous component at whose natural advance this new component is to be placed. Thus, if you wanted to make a single new glyph of the word "Hello" you would specify 5 components, where the first (the "H") didn't have any flags, where the "e" has the "-L" flag and a delta-X of zero (meaning the "zeroth" -- or baseform -- component), the first "l" has the "-L" flag and a delta-X of one, the second "l" has the "-L" flag and a delta-X of two, and so on. In this way you can create linked aggregates of glyphs. The first example in the examples section below shows this use.

Relative Positioning in Zones ("-Z")

Sometimes you want to specify relative positioning where you don't explicitly know the deltas. Or perhaps you're creating an add list to be used with many different fonts, some wide like Avant Garde, some narrow like Onyx. In order to satisfy this need, add lists can use the concepts of "zones" with the "-Z" flag. Don't confuse this component flag with the "-Z" flag that appears on the first line as described above; they are completely separate. If the zone flag is present on a component line, then the delta-X and delta-Y values are not interpreted as actual distances. Rather, they refer to zones where the component will be positioned. Consider the following diagram:

There are five horizontal zones, and five vertical zones. The heavy line drawn around the center nine zones is where the referent component is conceptually placed. The referent is some previous component -- usually component zero (i.e. the baseform), but see the discussion of the "-R" flag below. The new component is then placed relative to the referent component based on the zones specified, as follows:

Zone 1

As a delta-X zone, zone 1 means that the right edge of this new component's bounding box will be aligned with the left edge of the referent's bounding box. As a delta-Y zone, zone 1 means the top edge of this new component's bounding box will be aligned with the bottom edge of the referent's bounding box.

Zone 2

As a delta-X zone, zone 2 means that the left edge of this new component's bounding box will be aligned with the left edge of the referent's bounding box. As a delta-Y zone, zone 2 means the bottom edge of this new component's bounding box will be aligned with the bottom edge of the referent's bounding box.

Zone 3

As a delta-X zone, zone 3 means that the center of this new component's bounding box will be aligned with the center of the referent's bounding box. As a delta-Y zone, zone 3 means the center of this new component's bounding box will be aligned with the center of the referent's bounding box.

Zone 4

As a delta-X zone, zone 4 means that the right edge of this new component's bounding box will be aligned with the right edge of the referent's bounding box. As a delta-Y zone, zone 4 means the top edge of this new component's bounding box will be aligned with the top edge of the referent's bounding box.

Zone 5

As a delta-X zone, zone 5 means that the left edge of this new component's bounding box will be aligned with the right edge of the referent's bounding box. As a delta-Y zone, zone 5 means the bottom edge of this new component's bounding box will be aligned with the top edge of the referent's bounding box.

Add Small Gap ("-G")

All the positioning happens with respect to the tight bounding boxes of the components, and not with respect to their advances or sidebearings. This gives tighter control. For zones 1 and 5, you may additionally specify the "-G" or "gap" flag, which means that after the alignment described above takes place, a small gap (about 5% of the em square) is added. This is useful, for instance, if you don't want your accents to touch the baseforms. The second example below shows how the "-Z" and "-G" flags are used.

Specify Relative Component ("-Rn")

Sometimes it's useful to position a component not relative to the baseform, but rather relative to a different previous component. You may specify this by using the "-Rn" flag, where n is the number of a prior component. Remember that component zero is the baseform; this case is so common that you don't ever need to include an "-R0" flag, because it's the default in the zone case. The third example below shows how this can be useful.

Scale Component ("-S scalefactor")

The default behavior for all components is to be used at 100% of their regular size. You may change that by using the "-S" flag and specifying a scale factor, expressed as a decimal number where 1.0 means 100% (i.e. the regular size).

Some examples

This section gives some examples of how add lists work. You should try copying them into a plain text file and actually running them with a real font to see the results. You might want to have a copy of TrueEdit around to do this -- its glyph palette, or its ability to open the 'glyf' table are both useful in visually proofing the results.

Roman numerals

For the first example, let's say you wanted to add some Roman numerals to a font. By adding them as separate glyphs you can maintain separate semantics for them. Here is how an add list would look to add 1 through 5:

oneroman 1
I 0 0
tworoman 2 -C
I 0 0
I 0 0 -L
threeroman 3 -C
I 0 0
I 0 0 -L
I 1 0 -L
fourroman 2 -C
I 0 0
V 0 0 -L
fiveroman 1
V 0 0

The new "one" and "five" glyphs are made up of only one component, with zero delta-X and delta-Y values. The "two," "three," and "four" glyphs are made up of two or three pieces. The "-C" flag on the first line for these indicates that the new glyph is to have the cumulative advance of all its components. The "-L" flag indicates this is a linked glyph. The value in the delta-X slot in these cases is not actually a delta-X, but rather a reference to which component this one is to link. Remember that the first component is number zero, not number one.

Accented glyphs

The next example involves adding a new accented glyph, upper-case and lower-case, to a font. Let's say you need to add an "F" with a "caron" (or "hachek") above it. You might use an add list like:

Fcaron 2
F 0 0
caron 3 5 -Z -G
fcaron 2
f 0 0
caron 34 5 -Z -G

The absence of the "-C" flag on the first line tells the AAT Font Tool to use just the advance width of the baseform letter as the advance width of the new composite glyph. The baseform has no delta-X or delta-Y applied. The presence of the "-Z" flag indicates that those components' delta-X and delta-Y values are not actual distances, but rather zone identifiers. The Y-Zone is 5 for both glyphs, meaning the components should be positioned atop the baseform. The X-Zone of 3 for the upper-case letter means to center the caron. The X-Zone of 34 for the lower-case letter means to position the caron halfway between the 3 (centered) and 4 (right edges aligned) positions.

More extreme examples

Now let's try a more whimsical example. Suppose we wish to create a new glyph which is an "F" with two carons atop it, side-by-side. Here's the add list that does the trick:

Fdblcaron 3
F 0 0
caron 2 5 -Z -G
caron 5 3 -Z -R1

The interesting this to note in this list is the third line, which has the "-R1" flag. This flag means that the positioning of this component is to be relative to the bounding box of the first caron, and not of the baseform.