Element Reference

<absolute>

Converts negative to positive numbers; positive numbers stay positive.

        <absolute value="line-width" result-to="lw"/>

Content

None.

Attributes

value: Required, except when <absolute> is the child of a <formula>. Any value or expression. The value to operate on.
result-to: Optional; not allowed when <absolute> is the child of a <formula>. The name of a variable or control value in which to store the result. If result-to is omitted where allowed and value is a variable or control value, the result is written to value. If value cannot be written to, the compiler issues a warning and the result is left on the stack.

<add>

Adds two numbers together.

        <add value1="line-width" value2="1p"/>

Content

None.

Attributes

value1, value2: Required, except when <add> is the child of a <formula>. Any value or expression. These are the values to add together.
result-to: Optional; not allowed when <add> is the child of a <formula>. If result-to is omitted where allowed, Xgridfit attempts to write the result to value1. If value1 cannot be written to, the compiler issues a warning and the result is left on the stack.

<alias>

Provides access to a value under some other name. The value can be a control-value, constant, variable, or any value that can be resolved to a number either at compile time or run time. The <alias> element can appear at the top level of a program (as a child of <xgridfit>), or along with other declarations at the beginning of <glyph>, <function>, <macro> or <pre-program> elements. An alias takes precedence over all other elements, so in the case of name collisions the alias is always used. Here is a simple example:

	<control-value name="lc-vert-stroke" value="0"/>
	<alias name="lc-vert-stem" target="lc-vert-stroke"/>

Now a <move> element with attribute distance="lc-vert-stem" will use the control-value named lc-vert-stroke. If another control-value is named lc-vert-stem it will be invisible. If you want the alias to be used in just one glyph program, declare it as a child of <glyph> rather than as a child of <xgridfit>.

Content

None.

Attributes

name: Required. A name: any sequence of letters, numbers, hyphens, periods; no spaces permitted. This is the name under which the program may now access the value.
target: Required. A name: any sequence of letters, numbers, hyphens, periods; no spaces permitted. The name of the value which is being renamed.

<align>

Moves one or more points along the freedom vector until aligned with a reference point. Points are "aligned" when their distance from each other, measured along the projection vector, is zero. When the projection vector is "x," aligned points end up stacked vertically; when it is "y" they end up in a horizontal line. When the projection vector is set to a line, the aligned points end up arrayed along an imaginary line orthogonal to the projection vector.

The <align> element must contain at least one object to align. It may contain any number of <point>s, <range>s and <set>s. An optional <reference> element contains the point to align with. If the reference point is omitted, the current setting of RP0 is used.

<align> can and frequently should be nested inside a <move> element, in which case points are aligned relative to the point that is the target of the <move>. In both of the following cases point "m" is aligned with point "r":

        <align>
          <reference>
            <point num="r"/>
          </reference>
          <point num="m"/>
        </align>

        <move>
          <point num="r"/>
          <align>
            <point num="m"/>
          </align>
        </move>

Content

One or more <point>, <range> and <set> elements.

Attribute

compile-if: Optional. Any value or expression that can be resolved to a number at compile time. If true (non-zero), the <align> element is compiled; otherwise the compiler passes it over.

<align-midway>

Must contain two <point> elements. Moves these along the freedom vector until they are aligned midway between their original positions. Measurement is along the projection vector.

        <align-midway>
          <point num="a"/>
          <point num="b"/>
        </align-midway>

Content

Two <point> elements, both required.

Attributes

None.

<call-function>

Calls a function (defined via the <function> element) by name. Parameters may be passed to the function by including several <with-param> elements; or, if the function is to be called repeatedly, several <param-set> elements, each containing the <with-param> elements for one call to the function.

If the function returns a value, it can be assigned to a variable via the result-to attribute. Note, however, that if a <call-function> element contains more than one <param-set>, only the value returned by the last iteration of the function is returned.

    <call-function name="cap-serif-width">
      <param-set>
        <with-param name="ref-pt" value="left-left"/>
        <with-param name="move-pt" value="top-serif-end"/>
      </param-set>
      <param-set>
        <with-param name="ref-pt" value="left-left"/>
        <with-param name="move-pt" value="bottom-serif-end"/>
      </param-set>
    </call-function>

Either several <with-param> elements (if the function is to be called just once) or several <param-set> elements.

Attribute

name: Required. The name of the function to call.
result-to: Optional. The name of a variable or control value in which to store the value returned by the function.

<call-glyph>

The <call-glyph> element causes code for the whole of a glyph program to be compiled and inserted, in the manner of a macro. Like <call-macro>, <call-glyph> can contain <with-param> elements, passing values to the glyph program. For a detailed account of its use, see the chapter on functions, macros and glyph programs.

Content

If the glyph being called has one or more <param> elements, one or more <with-param> elements. <param-set> elements are not permitted here.

Attribute

ps-name: Required. Must match the ps-name attribute of the <glyph> element being called.

<call-macro>

Causes a macro to be compiled and its code inserted at the present location.

    <call-macro name="lc-vert-stem-with-serif">
      <with-param name="anchor" value="left-left"/>
      <with-param name="distance-from-anchor" value="hn-width"/>
      <with-param name="stem-a" value="right-right"/>
      <with-param name="serif-a" value="right-serif-right"/>
      <with-param name="stem-b" value="right-left"/>
      <with-param name="serif-b" value="right-serif-left"/>
    </call-macro>

Content

Either one or more <with-param> elements, one for each parameter defined in the <macro> element, or several <param-set> elements if the macro is to be compiled and inserted at this place more than once. <with-param> may be omitted for each <param> element with a value attribute.

Attribute

name: Required. The name of the macro to call.

<call-param>

This element may be used within a <glyph> or <macro> element containing <param> elements. It will cause to be executed a snippet of code passed into a called <glyph> or <macro> via a <with-param> element. For details, see the "Callable Parameters" section of Functions, Macros and Glyph Programs.

Content

None.

Attribute

name: Required. The name of the <param> to call.

<ceiling>

Yields the smallest integer greater than or equal to value.

Content

None.

Attributes

value: Required, except when <ceiling> is the child of a <formula>. Any value or expression. The value to operate on.
result-to: Optional; not allowed when <ceiling> is the child of a <formula>. If result-to is omitted where allowed, Xgridfit attempts to write the result to value. If value cannot be written to, the compiler issues a warning and the result is left on the stack.

<command>

Causes any TrueType instruction (except the PUSHB and PUSHW instructions) to be inserted at this place in the output. name is the name of the command; modifier, is simply copied into brackets after the instruction that is generated. This element

        <command name="MIRP" modifier="10110"/>

is compiled to "MIRP[10110]". The modifier attribute lacks portability, since it is copied in literally. A better solution is to use <modifier> elements within the <command> element, thus:

        <command name="MIRP">
          <modifier type="rp0" value="yes"/>
          <modifier type="minimum-distance" value="no"/>
          <modifier type="round" value="no"/>
          <modifier type="color" value="black"/>
        </command>

Though verbose, this style allows Xgridfit to check the input code and has the potential to allow Xgridfit to vary the syntax of its output. (Since Xgridfit now produces scripts only for FontForge, the latter capability is not exploited.)

Content

One or more <modifier> elements, if required by the instruction and if the modifier attribute is not used.

Attributes

name: Required. The name of the TrueType instruction to be output. The compiler checks this against a list of instructions.
modifier: A modifier string to be inserted literatim in the TrueType instruction. For example, if command is "MIRP" and modifier is "rnd", then MIRP[rnd] is output.

<compile-if>

Code within <compile-if> is compiled only if the test attribute evaluates to true (non-zero). The compiler must be able to evaluate test at compile time: thus it may contain only constants, number literals, control value indexes and a few operators (+ - = != > < >= <= or and not).

Here is a simple example of <compile-if>:

        <compile-if test="bold-italic">
          <delta>
            <delta-set size="3" distance="-2">
              <point num="pt"/>
            </delta-set>
          </delta>
        </compile-if>

The delta is compiled and inserted in the output code only if bold-italic (a global constant) is non-zero.

The <compile-if> element may also contain an <else> element, which must come last. If test evaluates to false (zero), the code contained in <else> is compiled.

Content

Programming to be conditionally compiled.

Attribute

test: Required. Any value or expression that can be resolved to a number at compile time. If it evaluates as true (non-zero), the content of this element is compiled.

<constant>

A constant is a named number. The value can be an integer, either of the two kinds of fixed-point number (e.g. "2.3" for a distance on the grid or "1.0v" for a component of a vector), or the name of another constant, in which case it creates an alias for that constant. It can also be a simple expression (usually addition or subtraction) based on another constant:

        <constant name="bottom-left" value="3"/>
        <constant name="bottom" value="bottom-left"/>
        <constant name="bottom-right" value="bottom + 4"/>

Constants can be referenced just about anywhere that numbers are called for. To refer to a constant belonging to another glyph program, use the glyph's ps-name followed by a slash and the name of the constant, e.g.

        <point num="macron/bottom"/>

This is useful when instructing composite glyphs.

Constants can be declared at the beginning of a <glyph> program, or as a child of the <xgridfit> element.

Content

None.

Attributes

name: Required. A name: any sequence of letters, numbers, hyphens, periods; no spaces permitted. Other elements can refer to the constant by this name.
value: Required. A number or simple expression. It should be possible to resolve this attribute to a number at compile time.

<contour>

Specifies a contour to be shifted by a <shift> instruction.

Content

None.

Attributes

num: Required. A number or simple expression, the number of the contour. It should be possible to resolve this attribute to a number at compile time.
zone: Optional. Possible values are "glyph" and "twilight." Include the attribute zone="twilight" if this contour is in the twilight zone; otherwise the compiler will assume that it is in the glyph zone.

<control-value>

The font's Control Value Table is built from the <control-value> elements. Each <control-value> has an name (which must be unique) and a numerical value. The index of the <control-value> is generated by Xgridfit, and no attempt should be made to predict it: Xgridfit instructions should use only the names of <control-value>s, though the index may be derived and used at run time.

    <control-value name="curved-char-bottom" value="-25"/>
    <control-value name="lc-x-height" value="850"/>
    <control-value name="lc-descender-depth" value="-555"/>
    <control-value name="lc-ascender-height" value="1485"/>

Content

None.

Attributes

name: Required. A name: any sequence of letters, numbers, hyphens, periods; no spaces permitted.
value: Required. A number in font units (the units of the grid on which the font was designed, normally 100 units per em or 2048 units per em).
index: Optional, and consulted only in merge-mode. Specifies how to determine a control-value's index. "Auto" (the default) means that if a control-value with this one's value is found in the font, it should be re-used; otherwise this control value should be appended to the end of the control-value table. "Append" means that the control-value should always be appended to the end of the control-value table. A number specifies the index at which the control-value should be placed. If the value of this control-value is different from the value of that of the control-value at that index in the existing font, the control-value is updated.

<control-value-delta>

The <control-value-delta> element works like the <delta> element, but operates on the Control Value Table rather than on a point. It should normally be invoked in the <pre-program>. Each <delta-set> inside a control-value-delta element must have cv, size and distance attributes, but it may not contain a point.

The setting of the vectors has no effect on the <control-value-delta>. Rather, the <delta-set> specifies an amount to add to or subtract from the value stored there.

    <control-value-delta>
      <delta-set cv="pq-char-width" size="6" distance="-8"/>
      <delta-set cv="pq-char-width" size="9" distance="-8"/>
    </control-value-delta>

Content

One or more <delta-set> elements.

Attributes

None.

<control-value-index>

Assigns the index of a control value to a variable. Use this if you need to get such an index for any reason, since the <set-equal> instruction yields the value, not the index, of a control value.

Content

None.

Attributes

value: Required. The name of the control value whose index you want to retrieve. No other kind of value is recognized here.
result-to: Required. The name of a <variable> in which to store the index of the control value.. Only a variable is permitted here--not, for example, the name of another control value.

<default>

This element, which may appear as a child of <xgridfit>, declares a default value. If the type is "minimum-distance," "control-value-cut-in," "single-width," "single-width-cut-in," "delta-base," "delta-shift" or "round-state," Xgridfit also inserts code in the prep program to set a font-wide default in the TrueType engine. Another way of setting these defaults is simply to include elements that set these values in the <pre-program>, and the effect is the same. If you want the TrueType engine to reject all attempts to set defaults (that is, if you want to use only the defaults that are standard for TrueType), include this:

        <default type="use-truetype-defaults" value="yes"/>

In addition to TrueType defaults, stored in the font file, this element controls several defaults that govern how Xgridfit operates.

Content

None.

Attributes

type: Required. Must be one of the following: "minimum-distance", "control-value-cut-in", "single-width", "single-width-cut-in", "delta-base", "delta-shift", "delta-break", "max-twilight-points", "max-storage", "legacy-storage", "max-stack", "use-truetype-defaults", "round-state", "function-base", "init-graphics", "color", "delete-all", "combine-prep", "auto-instr", "auto-hint", "cv-num-in-compile". For details about the meanings of these types, see The Graphics State and Xgridfit Defaults and Merge-mode.
value: Required. For permissible values, see The Graphics State and Xgridfit Defaults.

<delta>

A delta instruction moves points at particular sizes. The <delta> element may contain any number of <delta-set> elements, each one specifying a point to move, a size at which to move it, and a distance to move it.

The direction of the move is determined by the current setting of the freedom vector. The available specifications are fuzzy as to the details. You will experience no surprises when the vectors are set to x or y; you may experiment with the vectors set at other angles.

When the first element of a <delta> is a <point>, that point is the default, which every <delta-set> element will move unless it contains its own <point>. These two <delta> elements are equivalent:

      <delta>
        <delta-set size="3" distance="8">
          <point num="p1"/>
        </delta-set>
        <delta-set size="4" distance="8">
          <point num="p1"/>
        </delta-set>
      </delta>

      <delta>
        <point num="p1"/>
        <delta-set size="3" distance="8"/>
        <delta-set size="4" distance="8"/>
      </delta>

Note that a <move> element may contain <delta> elements. When a <delta-set> element inside one of these <delta> elements lacks a <point>, it operates on the point moved by the parent <move>.

Content

An optional <point> element, followed by one or more <delta-set> elements.

Attributes

compile-if: Optional. Any value or expression that can be resolved to a number at compile time. If true (non-zero), the <delta> element is compiled; otherwise the compiler passes it over.

<delta-set>

The <delta-set> element encapsulates the essential information about a single delta move or adjustment: the resolution at which to apply the delta, the magnitude of the adjustment, and the point or control value that will be affected.

The resolution is determined by the size attribute, which can be a number from 0 to 47. It is added to the value set by the <set-delta-base> or <with-delta-base> instruction to obtain the resolution (in pixels per em or "ppem") at which the move should take place. The default delta base is 9; if you don't change it, a size of "0" means 9 ppem, "9" means 18 ppem, and so forth up to "47," which means 56 ppem.

The distance attribute is the distance to shift the point along the freedom vector, or the amount to add to or subtract from the control value. Legal values are from -8 to 8 (excluding 0). When moving points, negative numbers shift against the direction of the freedom vector (generally down or left) and positive numbers shift in the direction of the freedom vector.

The default unit by which pixels are moved and control values adjusted is 1/8 pixel. The unit is controlled by means of the <set-delta-shift> or the <with-delta-shift> instruction.

A <delta-set> that is the child of a <delta> will normally contain a single <point>. However, the <point> may be omitted in either of two circumstances: First, when the <delta> is the child of a <move> element, the <point>, when not specified, is implicitly the <point> that is the child of the parent <move>. Second, when the first child element of the <delta> is <point>, that point will be moved by any <delta-set> that lacks a child <point>. A <delta-set> that is the child of a <control-value-delta> element may not contain a <point>, but it must have a cv attribute.

All attribute values in a <delta-set> and a child <point> must be capable of being resolved to numerical values at compile time. Variables and function parameters are not permitted.

Content

When the <delta-set> is the child of a <delta> element, it may contain a <point>; this is the point to move. It must contain a <point> when it the parent <delta> is not the child of a <move> and the first child of the <delta> is not a <point>. When the <delta-set> is the child of <control-value-delta> it has no content.

Attributes

cv: Required when the <delta-set> is the child of <control-value-delta>. The name of the control value to adjust.
size: Required. An integer from 0 to 47. The resolution at which to move the point or adjust the control value, as explained above.
distance: Required. An integer from -8 to 8, excluding 0. The distance to move the point or the amount to adjust the control value, as explained above.

<diagonal-stem>

Given two lines (making up a diagonal stem), makes the second line parallel to the first, subject to the operation of the Control Value cut-in. If one <align> element is present, the points it contains are aligned with the second line; if there are two, the first set of points is aligned with the first line and the second set with the second line. You may, and often should, set a new minimum distance value with the min-distance attribute. At the end of this instruction the minimum distance is reset to its former value.

Usually it doesn't make a lot of sense to round the distance when calling this instruction; and yet the default value of round is yes for compatibility with other, similar instructions. You'll probably want to set the round attribute to no; but if you have several <diagonal-stem> instructions together, enclose them in a <with-round-state round="no"> element to turn off rounding beforehand and on again afterwards. In this case, do not include the round attribute with the <diagonal-stem> elements.

By default this instruction does not set the Freedom Vector, since the best setting of that vector varies with circumstances. If you want the Freedom Vector to be the same as the Projection Vector, set freedom-vector="yes".

This instruction is not suitable for use inside a function (though you may do so if the <line> elements contain points rather than ref attributes). Also, I'm not sure whether it will work if the various points are in different zones. It may, but I don't guarantee it.

    <with-minimum-distance value="diag-min-dist">
      <with-round-state round="no">
        <diagonal-stem distance="cap-thick-diag" save-vectors="yes">
          <line ref="left-diag-left-line"/>
          <line ref="left-diag-right-line"/>
        </diagonal-stem>
        <diagonal-stem distance="cap-thin-diag" save-vectors="yes">
          <line ref="right-diag-right-line"/>
          <line ref="right-diag-left-line"/>
        </diagonal-stem>
      </with-round-state>
    </with-minimum-distance>

Content

Two <line> elements, the second to be made parallel to the first. Optionally, one or two <align> elements, the first containing points to be aligned with the first line and the second with the second line.

Attributes

distance: Required. The name of a control value which determines the distance to place the second line from the first.
round: Optional. The value may be "yes" or "no", the name of a standard or custom round state, or any number or expression to use as an input for SROUND. If the value is anything but "no", rounding is used.
cut-in: Optional. The value may be "yes" or "no"; the default is "yes". Determines whether to use the control value cut-in.
min-distance: Optional. The value may be "yes" or "no" or any value or expression to be used to set the minimum distance for this operation.
color: Optional. Permitted values are "black", "white" and "gray". The default is "black." The kind of distance between the points of the two <line> elements.
freedom-vector: Optional. The value may be "yes" or "no"; the default is "no". Determines whether to set the freedom vector to the same angle as the projection vector.
save-vectors: Optional. The value may be "yes" or "no"; the default is "no". If "yes", both the projection vector and the freedom vector are guaranteed to be the same after this intruction as they were before.

Attributes

result-to: Optional. The name of a variable or control value in which to store the result. If there is no result-to attribute, the compiler issues a warning and the result is left on the stack.

<function>

The <function> element is used to define functions. Functions are called by name using the <call-function> element. Normally Xgridfit takes care of indexing functions and making sure the right number is used to call them.

A function may also have a num attribute: this is used to define the function in the fpgm table and ensures that any legacy programming can continue to call older functions by number. Xgridfit assigns a number automatically to any function that lacks a num attribute.

A function that returns a value must have the attribute return="yes"; within such a function an instruction may assign a value to the special variable "return". The return value must be a single number; lines, vectors, and other structures consisting of two or more numbers cannot be returned.

A <function> may contain any number of <param> elements and any number of <variable> elements, followed by programming.

    <function name="lc-standard-serif">
      <!-- Regulates vertical distances within a serif -->
      <param name="base"/>
      <param name="bottom-left"/>
      <param name="bottom-right"/>
      <param name="top-left"/>
      <param name="top-right"/>
      <with-vectors axis="y">
        <mdap>
          <point num="base"/>
        </mdap>
        <mirp distance="lc-serif-height" set-rp0="yes">
          <point num="top-left"/>
        </mirp>
        <align>
          <point num="top-right"/>
        </align>
        <mirp distance="lc-serif-height" set-rp0="yes">
          <point num="bottom-left"/>
        </mirp>
        <align>
          <point num="bottom-right"/>
        </align>
      </with-vectors>
    </function>

You may define function variants, that is, alternative versions of a function to be used at certain sizes or resolutions. To do so, simply include one or more <variant> elements as the last children of the <function> element.

Content

First optional <param> elements; next optional <variable> and <alias> elements (in any order); then elements containing programming to be executed by default; finally optional <variant> elements defining versions of the function to be used if the test attribute of the <variant> element evaluates as true (non-zero) when the <pre-program> is run.

Attributes

name: Required. A name: any sequence of letters, numbers, hyphens, periods; no spaces permitted. The name of this function.
xml:id: Optional. A valid XML ID, i.e. any sequence of letters, numbers, hyphens, periods; no spaces permitted; and unique within the program. This ID may be used if a function is imported into a file using XInclude.
num: Optional. A non-negative integer (zero or greater). See above for its use. If your program contains functions with num attributes, it should not contain a <legacy-functions> element.
return: Optional. Permitted values are "yes" and "no"; "no" is the default. If "yes", the function may return a value by assigning a value to the special "return" variable.

<get-coordinate>

Gets the coordinate of a point, measured along the current projection vector. If the projection vector is set to x, for example, the result will be the horizontal distance of the point from the grid origin (0,0). The result-to attribute may be the name of a variable, a control value, or a graphics state variable.

        <get-coordinate result-to="v">
          <point num="p"/>
        </get-coordinate>

Most of the time it will be more convenient to use one of the "coord" operators in an expression.

Content

The <point> to get the coordinate of.

Attributes

grid-fitted: Optional. Permitted values are "yes" and "no"; the default is "yes". Whether to use the point's current (grid-fitted) position or its original position (before grid-fitting).
result-to: Optional. The name of a variable or control value in which to store the result. If there is no result-to attribute, the compiler issues a warning and the result is left on the stack.

<getinfo>

The <getinfo> element provides access to the TrueType GETINFO instruction, which queries the TrueType engine about the state of the current glyph, about the engine version, or about whether ClearType is enabled. In general it is more convenient to use Xgridfit's built-in graphics variables to obtain such information, but the <getinfo> element may be useful to combine selectors in ways that Xgridfit does not anticipate; and future versions of the TrueType may introduce selectors that Xgridfit does not know about.

<getinfo> takes two attributes: selector indicates which query or queries to submit to GETINFO. Its value can be any number or expression; and note that the relevant graphics variables can be used here, and the value of these variables in this context is the selector rather than the result of a GETINFO query, as is the case elsewhere. Selectors for GETINFO can be combined by ANDing them; this can be simulated in Xgridfit by adding selectors together (since TrueType programming does not have arithmetical AND). This query

	<getinfo result-to="v" selector="is-glyph-rotated + is-glyph-stretched"/>

will return a non-zero (true) value if either condition is true.

The second attribute, result-to, works like the same attribute elsewhere: that is, it is a variable in which to store the result of the query, and if it is omitted the compiler issues a warning and the value is left on the top of the stack.

Content

None.

Attributes

selector: One or more of the following, added together: is-glyph-rotated, is-glyph-stretched, is-glyph-grayscale, is-cleartype-enabled, is-compatible-width-enabled, is-symmetrical-smoothing-enabled, is-BGR-order. Or, by itself, is-glyph-transformed.
result-to: Optional. The name of a variable in which to store the result. If there is no result-to attribute, the compiler issues a warning and the result is left on the stack.

<glyph>

The <glyph> element contains instructions relating to an individual glyph. Example:

        <glyph ps-name="sample-glyph">
          <constant name="last" value="50"/>
            . . .
          <variable id="v"/>
          <with-vectors axis="y">
            <!-- programming here -->
          </with-vectors>
          <with-vectors axis="x">
            <!-- more programming here -->
          </with-vectors>
          <interpolate-untouched-points/>
        </glyph>

To make a glyph program callable in the manner of a macro (see <call-glyph>), include one or more <param> elements for key values. These should have value attributes, since the glyph program will have to be compiled and run even when it is not called.

Content

<param> elements (if any) must come first, followed by <constant>, <range>, <set>, <line>, <alias> and <variable> elements in any order. Finally programming for the glyph.

Attributes

ps-name: Required. The PostScript name of the glyph. It must match the PostScript name of the glyph in the font.
xml:id: Optional. A valid XML ID, i.e. any sequence of letters, numbers, hyphens, periods; no spaces permitted; and unique within the program. This ID may be used if a <glyph> is imported into a file using XInclude.
init-graphics: Optional. Permitted values are "yes" and "no". This attribute determines whether variables used by Xgridfit to track the graphics state are initialized at the beginning of the glyph program. Such initialization is not needed when instructions are imported from another font. The default value is normally "yes," but the default may be set with the init-graphics <default> or with the -G option for the xgridfit executable.

<glyph-select>

Specifies a whitespace-delimited list of glyphs to compile, ignoring all others. It is all right to keep this element in the file when you don't need it: just empty it out. These are valid:

	<glyph-select>a macron amacron</glyph-select>
	<glyph-select></glyph-select>

This element corresponds to the glyph-select parameter and the -g command line option, either of which will, if present, override the element.

Content

A whitespace-delimited list of ps-names of glyph elements.

Attributes

None.

<if>

Contains instructions that are executed only if the expression in the test attribute is true. If the test is false, and an <else> element is the last child of this <if>, the instructions in the <else> element are executed. <if> elements may be nested.

The test attribute contains an expression, e.g.

        <if test="minimum-distance = 1p">

For more on expressions, see the Expressions section of this documentation. In the TrueType language, where all data is numeric, a non-zero value is considered true and zero false. So the test attribute can be used to tell whether a value is zero. This

        test="round(lc-vert-stem) != 0"

is equivalent to this:

        test="round(lc-vert-stem)"

The <if> element may contain an <else> clause, which must come last.

        <if test="boolean-expression">
          <!-- programming -->
          <else>
            <!-- alternative programming -->
          </else>
        </if>

Content

Programming, followed optionally by an <else> element.

Attributes

test: Required. Any value or expression. The condition to test for.

<infile>

Contains the name of a file to which TrueType instructions are to be added. This may be either a FontForge source file (.sfd) or a TrueType font (.ttf).

          <infile>MyFont.sfd</infile>
          <outfile>MyFont.ttf</outfile>

Content

The name of a file with extension .sfd or .ttf.

Attributes

None.

<interpolate>

To "interpolate" a point is to move it so that its position relative to two reference points is what it was in the original outline. If the distance between the two reference points is not what it was in the original outline, the point is positioned so that its relationship to the reference points is proportionally correct.

The <interpolate> element must contain at least one point to interpolate. It may contain any number of <point>s, <range>s and <set>s. Like most other elements that move points, it may contain a <reference> element; but this element must contain two <point>s, not just one.

This instruction may be nested inside a <move> element containing a reference point, in which case no reference points are needed in the <interpolate> element: the points it contains are automatically interpolated between the <move> element's reference point and its moved point. These two <interpolate> elements do the same thing:

        <interpolate>
          <reference>
            <point num="top"/>
            <point num="bottom"/>
          </reference>
          <point num="bar-top-left"/>
        </interpolate>

        <move>
          <reference>
            <point num="bottom"/>
          </reference>
          <point num="top"/>
          <interpolate>
            <point num="bar-top-left"/>
          </interpolate>
        </move>

If you want to round points after interpolating them, simply include the attribute round="yes" on the <interpolate> element. The points will be moved along the freedom vector to the nearest rounded position. Note that this has no effect on <range> or <set> elements. If you want to use a round state other than the current one, use the appropriate value for round:

	<interpolate round="to-half-grid">
	  <reference>
	    <point num="a"/>
	    <point num="b"/>
	  </reference>
	  <point num="c"/>
        </interpolate>

Content

An optional <reference> element (containing two <point> elements), followed by one or more <point>, <range> and <set> elements.

Attributes

compile-if: Optional. Any value or expression that can be resolved to a number at compile time. This <interpolate> element is compiled only if the compile-if attribute evaluates as true (non-zero). If this attribute is not present, the <interpolate> is compiled.
round: Optional. The value may be "yes" or "no", the name of a standard or custom round state, or any number or expression to use as an input for SROUND. If the value is anything but "no", any points referred to by <point> elements (but not <range> or <set> elements) are moved to the nearest rounded position. Points are not rounded when this attribute is not present.

<interpolate-untouched-points>

Interpolates all points that have not been moved or "touched" by instructions so that they are positioned correctly relative to points that have been moved. Most of the time you will want to place this instruction at the end of the program for each glyph.

Content

None.

Attribute

axis: Optional. Permitted values are "x" and "y". Determines the axis along which interpolation is performed. If this attribute is omitted, interpolation is performed along both x and y axes.

<legacy-functions>

Stores functions from a font that has been converted for use with Xgridfit. Normally this should not be created or edited by hand: see Conversion for further details.

Content

Programming imported from an existing font: normally just <command> and <push> elements.

Attributes

max-function-defs: Required. A positive integer (one or higher). One more than the highest index of a functon defined in the <legacy-functions> element. Normally this will be set correctly by ttx2xgf, but the user should check it before proceeding.

<line>

A <line> is defined by its two end-points. These points need not be adjacent.

When a <line> has a name attribute, another <line> may refer to it by name. You may name the <line> the first time you use it or declare it in a <line> element among the declarations at the beginning of a <glyph>. For example, if you declare the line thus:

        <line name="line-2b">
          <point num="b"/>
          <point num="a"/>
        </line>

then you can use an abbreviated form whenever you need it:

        <set-freedom-vector>
          <line ref="line-2b"/>
        </set-freedom-vector>

If both points that define a <line> are in the same zone, you may use the optional zone attribute on the <line> to indicate this. Most instructions that take a <line> as an argument allow one point to be in one zone and the other point in the other: in such cases place the zone attributes on the <point>s. The exception is the <move-point-to-intersection> instruction, which requires that each of the two lines it takes as arguments be entirely in a zone. For this instruction, place the zone attributes on the <line>s, never on the <point>s.

Content

Two <point> elements, one at each end of the line. These are required if no ref attribute is present.

Attributes

name: Optional, but necessary if this <line> is referred to elsewhere. A name: any sequence of letters, numbers, hyphens, periods; no spaces permitted. Names this <line>.
ref: Required if no <point> elements are present. A reference to a named <line>.
zone: Optional. Permitted values are "twilight" and "glyph". Include the attribute zone="twilight" if both end-points of the line are in the twilight zone.

<macro>

A macro is a stretch of code that is compiled and inserted into the program stream wherever a <call-macro> element is encountered. Macros resemble functions in syntax: they begin with <param> definitions followed by program code, which can access all global variables and values (e.g. control values, graphics variables, constants and variables declared as children of <xgridfit>). Macros can be called from a <function>, <pre-program> or <glyph>, and variables and values local to these structures can be accessed by passing them as parameters.

Macro parameters are fundamentally different from function parameters. A function parameter is passed to the function on the stack at run time; the macro parameter, on the other hand, is swapped at compile time for the value parameter, which is then evaluated as any value is evaluated at run time. When passing variables or control values, there is no rule governing whether they are passed to the macro by value or by reference; rather, they are evaluated according to the rule that governs evaluation of variables for the particular instruction where they occur.

Content

Optional <param> elements, followed by optional <alias> elements, and then by programming.

Attributes

name: Required. A name: any sequence of letters, numbers, hyphens, periods; no spaces permitted. Names this <macro>.
xml:id: Optional. A valid XML ID, i.e. any sequence of letters, numbers, hyphens, periods; no spaces permitted; and unique within the program. This ID may be used if a <macro> is imported into a file using XInclude.

<maximum>

Yields the greater of the two values value1 and value2.

        <maximum value1="lc-vert-stem" value2="1p" result-to="lc-vert-stem"/>

Content

None.

Attributes

value1: Required except when <maximum> is the child of a <formula> element. Any value or expression.
value2: Required except when <maximum> is the child of a <formula> element. Any value or expression.
result-to: Optional; not allowed when <maximum> is the child of a <formula>. The name of a variable in which to store the result. If result-to is omitted where allowed, the compiler issues a warning and the result is left on the stack.

<mdap>

Corresponds to the TrueType MDAP instruction. Normally <move> is a better choice for moving points, but this element is provided to facilitate low-level programming.

This element rounds a point to the grid if the round attribute is not no; otherwise it "touches" the point (marks it as moved).

        <mdap>
          <point num="p"/>
        </mdap>

Content

A single <point>.

Attributes

round: Optional. The value may be "yes" or "no", the name of a standard or custom round state, or any number or expression to use as an input for SROUND. The default value is "yes." This attribute determines whether and how to round the point.

<mdrp>

Corresponds to the TrueType MDRP instruction. Normally <move> is a better choice for moving points, but this element is provided to facilitate low-level programming.

This element will also take care of setting RP0 beforehand if a reference point is supplied. If no reference point is supplied, the current value of RP0 is used.

        <mdrp>
          <reference>
            <point num="r"/>
          </reference>
          <point num="p"/>
        </mdrp>

Content

An optional <reference> element (containing one point), followed by a single <point>.

Attributes

round: Optional. The value may be "yes" or "no", the name of a standard or custom round state, or any number or expression to use as an input for SROUND. The default value is "yes." This attribute determines whether and how to round the distance between the reference point and the moved point.
min-distance: Optional. Permitted values are "yes" and "no". The default is "yes." Whether or not to maintain a minimum distance between the reference point and the moved point.
set-rp0: Optional. Permitted values are "yes" and "no". The default is "no." Whether or not to set the RP0 pointer to the moved point after the instruction is executed.
color: Optional. Permitted values are "black", "white" and "gray". The default is "gray." The kind of distance between the reference point and the moved point. This is used by some TrueType engines to compensate for engine characteristics.

<measure-distance>

Measures the distance between two points and returns an F26dot6 number. The measurement is performed along the projection vector, and the result may be positive or negative depending on the relationship of the distance to the direction of the vector. Another way of putting it is that the order of the two points in this instruction is significant; reverse them and you reverse the sign of the result.

        <measure-distance result-to="v">
          <point num="p1"/>
          <point num="p2"/>
        </measure-distance>

Usually it will be more convenient to use the -- or --- operator in an expression.

Content

Two <point> elements.

Attributes

grid-fitted: Optional. Permitted values are "yes" and "no"; the default is "yes". Whether to use the point's current (grid-fitted) position or its original position (before grid-fitting).
result-to: Optional. The name of a variable or control value in which to store the result. If there is no result-to attribute, the compiler issues a warning and the result is left on the stack.

<message>

The <message> element produces no TrueType code, but rather causes a message to be output at compile-time via the <xsl:message> element. This may help with debugging.

Content

Text of a message to be output.

Attributes

None.

<miap>

Corresponds to the MIAP instruction. Normally <move> is a better choice for moving points, but this element is provided to facilitate low-level programming.

Positions a point a specified distance from the grid origin.

Content

A single point.

Attributes

distance: Required. The name of a control value.
round: Optional. The value may be "yes" or "no", the name of a standard or custom round state, or any number or expression to use as an input for SROUND. The default value is "yes." This attribute determines whether and how to round the distance between the reference point and the moved point.
cut-in: Optional. The value may be "yes" or "no". The default is "yes." Whether to use the control value cut-in. If rounding is used, this will always be yes, even if you set it to no.

<minimum>

Yields the lesser of the two values value1 and value2.

        <minimum value1="lc-vert-stem" value2="1p" result-to="lc-vert-stem"/>

Content

None.

Attributes

value1: Required except when <minimum> is the child of a <formula> element. Any value or expression.
value2: Required except when <minimum> is the child of a <formula> element. Any value or expression.
result-to: Optional; not allowed when <minimum> is the child of a <formula>. The name of a variable in which to store the result. If result-to is omitted where allowed, the compiler issues a warning and the result is left on the stack.

<mirp>

Corresponds to the MIRP instruction, but attempts, insofar as it is practical, to separate rounding and the cvt cut-in. You can specify round="no" and cut-in="yes" or both no or both yes, but not round="yes" and cut-in="no". That produces an error-message.

This will take care of setting RP0 beforehand if a reference point is included.

        <mirp distance="lc-x-height">
          <reference>
            <point num="p1"/>
          </reference>
          <point num="p2"/>
        </mirp>

Content

An optional <reference> element (containing one point), followed by a single <point>.

Attributes

distance: Required. The name of a control value. Distance (from a <control-value> element) relative to the reference point (or to RP0 if that was set by a previous instruction).
round: Optional. The value may be "yes" or "no", the name of a standard or custom round state, or any number or expression to use as an input for SROUND. The default value is "yes." This attribute determines whether and how to round the distance between the reference point and the moved point.
cut-in: Optional. The value may be "yes" or "no". The default is "yes." Whether to use the control value cut-in. If rounding is used, this will always be yes, even if you set it to no.
min-distance: Optional. Permitted values are "yes" and "no". The default is "yes." Whether or not to maintain a minimum distance between the reference point and the moved point.
set-rp0: Optional. Permitted values are "yes" and "no". The default is "no." Whether or not to set the RP0 pointer to the moved point after the instruction is executed.
color: Optional. Permitted values are "black", "white" and "gray". The default is "gray." The kind of distance between the reference point and the moved point. This is used by some TrueType engines to compensate for engine characteristics.

<modifier>

When used as the content of a <command> element, controls one or two bits of the output instruction.

Content

None.

Attributes

type: Required. Must be one of the following: "set-rp0", "round", "minimum-distance", "color", "grid-fitted", "to-line", "axis", "ref-ptr". This determines which bits are affected.
value: Required. The possible values vary with the type. For details and defaults, see the "Low-Level Elements" section.

<move>

Moves a point and, optionally, aligns other points with it or moves other points in relation to it. For details, see the section on moving points.

Content

An optional <reference> element containing one <point>; then a required <point>. This may be followed by any number of the following elements, in this order:

<delta>
<align>, <interpolate>, <shift> (in any order),
<move>
<delta>

The first group of <delta> element is executed before the embedded <align>, <interpolate>, <shift> and <move> elements; the second group is executed afterwards. A <move> may contain <interpolate> only if <reference> is present.

Attributes

distance: Optional. The name of a <control-value> element. If a distance is specified, the target point is positioned that distance either from the reference point or from the grid origin. If a distance is not specified, the distance from the original outline is used. In either case, the distance is measured along the projection vector.
pixel-distance: Optional. A distance in pixels. If a pixel-distance is specified, the target point is positioned that distance either from the reference point or from the grid origin. The distance and pixel-distance attributes are not compatible, and the schema does not permit both to be present.
round: Optional. The value may be "yes" or "no", the name of a standard or custom round state, or any number or expression to use as an input for SROUND. The default is "yes." Whether and how to round the distance or pixel-distance. "Yes" means round the distance according to the current round state (to-grid, if you haven't changed it). If you specify "no", no rounding is done. To use one of the standard round states, use to-grid, to-half-grid, to-double-grid, down-to-grid or up-to-grid. To use a custom round state defined in the top level of the program (as a child of <xgridfit>), use its name. Finally, any number (constant, variable) is passed to SROUND for the TrueType engine to interpret. Setting the round state with this attribute has no effect except in this instruction: the round state returns to its former value after the instruction is executed. If several <move> instructions use the same round state, it is more efficient to enclose them in a <with-round-state> element than to include a round attribute with each one. That is also true if the round value is to be no: in that case use <with-round-state round="no"> and omit the round attribute for the <move> instructions.
cut-in: Whether to use the Control Value cut-in; or a cut-in value to use. Legal values are "yes", "no" or any value or expression; the default value is "yes". If the value of this attribute is no, the value of the round attribute must also be "no". (This is a peculiarity of the TrueType instruction set and has nothing to do with Xgridfit.) This attribute has an effect only when the distance attribute is present.
min-distance: Optional. The value may be "yes" or "no" or any value or expression to be used to set the minimum distance for this operation. This attribute has an effect only when there is a reference point.
color: Optional. Permitted values are "black", "white" and "gray". The default is "gray." The kind of distance between the reference point and the moved point. This is used by some TrueType engines to compensate for engine characteristics. This applies only when there is a reference point.

<move-point-to-intersection>

Moves a point to the intersection of two lines. Each of the lines must be wholly in a single zone, so if specifying the zone use the zone attribute of the <line> elements rather than the zone attributes of the <point> elements that make up the lines.

        <move-point-to-intersection>
          <point num="p"/>
          <line>
            <point num="l1p1"/>
            <point num="l1p2"/>
          </line>
          <line>
            <point num="l2p1"/>
            <point num="l2p2"/>
          </line>
        </move-point-to-intersection>

Content

A single <point> and two <line> elements.

Attributes

None.

<multiply>

Multiplies value1 by value2. If there is no result-to attribute, Xgridfit attempts to write the result to value1.

        <multiply value1="lc-vert-stem" value2="3.3" result-to="v"/>

Content

None.

Attributes

value1: Required except when <multiply> is the child of a <formula> element. Any value or expression.
value2: Required except when <multiply> is the child of a <formula> element. Any value or expression.
result-to: Optional; not allowed when <multiply> is the child of a <formula>. The name of a variable in which to store the result. If result-to is omitted where allowed, the compiler issues a warning and the result is left on the stack.

<negate>

Converts positive to negative numbers; negative numbers stay negative. If the result-to attribute is not present, Xgridfit attempts to write the result back to value. Failing that, it issues a warning and leaves the result on the stack.

        <negate value="v"/>

Content

None.

Attributes

value: Required, except when <negate> is the child of a <formula>. Any value or expression. The value to operate on.
result-to: Optional; not allowed when <negate> is the child of a <formula>. The name of a variable or control value in which to store the result. If result-to is omitted where allowed, and value is a variable or control value, the result is written to value. If value cannot be written to, the compiler issues a warning and the result is left on the stack.

<no-compile>

This element, which must always be a child of <xgridfit>, contains <glyph> elements (usually imported via XInclude) which are visible for reference purposes but not compiled. If a file MyFont-Basic.xgf contains a glyph program with an opening tag that looks like this:

	<glyph ps-name="a" xml:id="a">

then that glyph program can be made visible within another file thus:

	<no-compile>
	  <xi:include href="MyFont-Basic.xgf#a"/>
	</no-compile>

Now the following <point> will compile correctly:

	<point num="a/top + another-num"

The glyph included in this way can also be compiled via <call-glyph>:

	<call-glyph ps-name="a">
	  <with-param name="left-sidebearing" value="111"/>
	</call-glyph>

The <no-compile> element can be overridden with the <glyph-select> element (glyph-select parameter or -g option). This behavior may ease the testing of programs for composite glyphs.

Content

One or more <glyph> elements; more typically, <xi:include> elements importing <glyph> elements from other files.

Attributes

None.

<no-round>

Like round, but without the rounding. That is, it may apply a correction for the "color" of the distance, but it will not round the distance. If the result-to attribute is not present, Xgridfit attempts to write the result back to value. Failing that, it issues a warning and leaves the result on the stack.

        <no-round value="v1" color="black" result-to="v2"/>

Content

None.

Attributes

value: Required, except when <no-round> is the child of a <formula>. Any value or expression. A distance on the current grid; the value to operate on.
color: Optional. Permitted values are "black", "white" and "gray". The default is "gray." The kind of distance that the value represents. This is used by some TrueType engines to compensate for engine characteristics.
result-to: Optional; not allowed when <no-round> is the child of a <formula>. The name of a variable or control value in which to store the result. If result-to is omitted where allowed, and value is a variable or control value, the result is written to value. If value cannot be written to, the compiler issues a warning and the result is left on the stack.

<no-warning>

Inside a <no-warning></no-warning> block, warning messages are suppressed. Use this if you find a particular warning message annoying and you want to assure the compiler that you know what you're doing.

Content

Programming of any kind.

Attributes

None.

<outfile>

Contains the name of a file to write. If the filename ends .sfd it is assumed that a FontForge source file is desired, and the generated FontForge script ends with a "Save" command. If the filename ends .ttf it is assumed that a TrueType font is desired, and the generated FontForge script ends with a "Generate" command. It is an error if the filename has any other suffix.

The fmflags attribute indicates flags to pass to FontForge when generating a TrueType font. It has no effect when the <outfile> is a FontForge source file. For a list of these flags, see the documentation for the Generate command. Probably the most likely to be used is "2048" (generate old-style kern table).

          <infile>MyFont.sfd</infile>
          <outfile fmflags="2048">MyFont.ttf</outfile>

Content

The name of a file, with extension of either .sfd or .ttf.

Attributes

fmflags: Optional. An integer. Flags to be passed to the FontForge "Generate" command. This has no effect when Python output is selected; instead, use pyflags.
pyflags: A list of flags for FontForge to use when it generates a font. This is a space-separated list of tokens, e.g. pyflags="old-kern ofm". Possible tokens are: afm, pfm, tfm, ofm, composites-in-afm, glyph-map-file, short-post, apple, opentype, old-kern, dummy-dsig, TeX-table, round, no-hints, omit-instructions, PfEd-comments, PfEd-colors, PfEd-lookups, PfEd-guidelines, PfEd-background, symbol. For the meanings of these, see the section of the FontForge manual on generating fonts in Python scripts.

<outfile-base>

This element, which must be a child of <xgridfit>, corresponds to the outfile-base parameter and the -S option for the xgridfit shell script. If present, it causes a separate file to be output for every glyph that Xgridfit compiles. The name of the file is the string supplied in this element, plus the ps-name of the glyph, plus the extension .pe, .py or .debug. For example, this element

	<outfile-base>Test</outfile-base>

causes Xgridfit to output files with names like Test_A.pe and Test_B.py (or Test_A.py and Test_B.pe when Python output is requested). Elements such as control values, functions and the pre-program are output as usual in the default output script or in a file specified with the -O option. Note that this element also causes the output of <outfile> to be saved in a separate script whose default name depends on <outfile-base>. See <outfile-script-name> to specify a different name for this separate file.

This feature depends on the presence of an extension element that not every XSLT processor supports. Xsltproc, which Xgridfit uses by default, does support it.

Content

A fragment of a file name, from which other file names are built.

Attributes

None.

<outfile-script-name>

When the <outfile-base> element is present or the -S option is used, and the <outfile> element is present or the -o option is used, Xgridfit outputs the FontForge command that saves a font file or generates a font in a separate script file. By default the filename for this script is based on the outfile-base: for example, if the -S parameter is MyFont, then the filename will be MyFont_outfile.pe or MyFont_outfile.py. Use the <outfile-script-name> element (or the -z option) to specify a filename other than the default. This element must be a child of <xgridfit>.

num: Required. Any value or expression. The number of a point. To refer to a point in a glyph other than the one whose glyph program is currently running (as you may have occasion to do when instructing composite glyphs), use the syntax "g/p", where g is the ps-name of the other glyph, and p is the point being referred to (it must be the name of a <constant> declared in the other glyph).
zone: Optional. Permitted values are "twilight" and "glyph". The zone that contains this point. Instructions will take note of this attribute, when present, and adjust the zone pointers appropriately. The glyph zone is always the default zone. When a point is in the glyph zone it is generally redundant to include an attribute zone="glyph", and doing so may also cause unnecessary (though harmless) code to be generated. N.B. For instructions that deal with lists of points, include the zone attribute only in the first.

<pre-program>

The prep table (or CVT program) is made from the <pre-program> element. It contains instructions that are executed before a font is rasterized, or whenever it is about to be rasterized in a new size. A typical thing to do in the <pre-program> is to adjust control values, e.g. rounding or applying deltas to them. Another is to set defaults: an instruction that assigns a value to a graphic variable sets a default when it is executed in the <pre-program>. For example, if executed in the <pre-program> this instruction:

        <set-minimum-distance value="0.9">

ensures that the minimum-distance graphics variable is always 0.9 pixels at the beginning of any glyph program.

The <pre-program> element must be present in a complete Xgridfit program, even if it is empty.

Content

One or more optional <variable> and <alias> elements, followed by optional programming.

Attribute

xml:id: Optional. A valid XML ID, i.e. any sequence of letters, numbers, hyphens, periods; no spaces permitted; and unique within the program. This ID may be used if the <pre-program> is imported into a file using XInclude.

<ps-private>

Provides access to the font's private PostScript dictionary. This dictionary is not included in a TrueType font, but it does provide crucial information to the FontForge auto-hinter; and the FontForge auto-instructor, in turn, depends on the presence of PostScript-style hints. For details, see Merge-mode.

Content

One or more <entry> elements, each supplying the name and value of an entry in the PostScript private dictionary. For example:

	<ps-private>
          <entry name="BlueValues" value="-33 -2 856 873 1358 1385"/>
          <entry name="OtherBlues" value="-578 -553"/>
          <entry name="BlueFuzz" value="0"/>
        </ps-private>

<push>

The <push> element does the work of the various PUSHB and PUSHW instructions, and it can generate the code to move any value (e.g. a variable or control-value) onto the stack. It may be used in combination with <command> to insert low-level TrueType commands into your Xgridfit programming in a portable way. Its content is a whitespace-delmited list of numbers, identifiers and expressions. These are valid Xgridfit <push> instructions:

        <push>2 5 89 67</push>

        <push>
          left
          right
          lc-vertical-stem
          -1
        </push>

        <push> 0.58p 2.0 to-grid </push>

        <push>1 (top + 3) 512</push>

It is essential that all expressions containing whitespace be enclosed in parentheses.

Content

A space-delimited list of values and expressions.

Attributes

None.

<range>

A <range> is a collection of contiguous points defined by its end-points. It can be used in any instruction that operates on more than one point: <shift>, <align>, <interpolate>, <shift-absolute>, <toggle-points>. The order of points in the <range> is not significant. Example:

        <align>
          <reference>
            <point num="bottom"/>
          </reference>
          <range>
            <point num="bottom - 2"/>
            <point num="bottom + 2"/>
          </range>
        </align>

If "bottom" is point 17, the <range> begins with 15 and ends with 19. But any reference point in the parent element of the <range> is excluded from the <range>, so this <range> actually represents points 15, 16, 18 and 19. The same is true of implicit reference points supplied by a <move> element that is the parent of the parent of the <range>:

        <move>
          <point num="bottom"/>
          <align>
            <range>
              <point num="bottom - 2"/>
              <point num="bottom + 2"/>
            </range>
          </align>
        </move>

Here the points in the <range> are aligned with "bottom" after it has been moved by the <move> instruction; but "bottom" itself is not part of the <range>. The code above is functionally identical to this:

        <move>
          <point num="bottom"/>
          <align>
            <point num="bottom - 2"/>
            <point num="bottom - 1"/>
            <point num="bottom + 1"/>
            <point num="bottom + 2"/>
          </align>
        </move>

The latter generates more efficient code than the example with the <range>, but the <range> is more flexible, since its endpoints, its size, and the points to be excluded need not be known until run-time. This makes the <range> ideal for use in functions.

All the points in a <range> must be in the same zone, determined by the optional zone attribute on the <range> element. Any zone attributes on the <point>s within the <range> are ignored.

Content

Two <point> elements. These are required if no ref attribute is present.

Attributes

name: Optional, but necessary if this <range> is referred to elsewhere. A name: any sequence of letters, numbers, hyphens, periods; no spaces permitted. Names this <range>.
ref: Required if no <point> elements are present. A reference to a named <range>.
zone: Optional. Permitted values are "twilight" and "glyph".

<restore-default>

To reset any of the graphics variables tracked by Xgridfit to its default value (that is, the value set by your Xgridfit program via a <default> element or by setting it in the <pre-program>--failing that, the TrueType default), use the <restore-default> element. Use the value all to reset all graphics variables, including the freedom and projection vectors and the auto-flip state, which Xgridfit does not track. The all option sets these last to their TrueType defaults: the x axis for the vectors and "on" for auto-flip.

	<restore-default name="minimum-distance"/>

Content

None.

Attribute

name: The name of the graphics variable to restore to its default value. Possible values are "minimum-distance", "control-value-cut-in", "single-width", "single-width-cut-in", "delta-base", "delta-shift", "round-state", "all".

<reference>

In any instruction that can position a point or other structure with reference to one or more points, the <reference> element holds the reference point(s). This element generally contains precisely one point, but when it is the child of an <interpolate> element it must contain two points. In the following example, point p2 is moved relative to point p1:

        <move>
          <reference>
            <point num="p1"/>
          </reference>
          <point num="p2"/>
        </move>

Content

A single <point>. When the <reference> element is the child of <interpolate>, two points.

Attributes

None.

<round>

Rounds a number representing a distance according to the current round state, applies whatever correction is appropriate for the "color" of the distance, and returns the result.

<round value="lc-vert-stem" color="black" result-to="new-cvt"/>

Content

None

Attributes

value: Required, except when the child of <formula>. Any value or expression, understood as a distance on the current grid. This is the number to round.
color: Optional. Permitted values are "black", "white" and "gray". The default is "gray." The kind of distance that the value represents. This is used by some TrueType engines to compensate for engine characteristics.
result-to: Optional; not allowed when <round> is the child of a <formula>. The name of a variable or control value in which to store the result. If result-to is omitted where allowed, and value is a variable or control value, the result is written to value. If value cannot be written to, the compiler issues a warning and the result is left on the stack.

<round-state>

Declares a custom round state whose name can be passed to <set-round-state>, <with-round-state>, or any element that takes a round attribute. For an explanation of the period, phase and threshold attributes, see "Rounding." Note that only a limited number of values is permitted for each of these attributes. This element is permitted only at the top level of a program, as a child of <xgridfit>.

        <round-state name="my-round" period="two-pixel"
                     phase="three-quarters"
                     threshold="three-quarters"/>

Content

None.

Attributes

name: Required. A name: any sequence of letters, numbers, hyphens, periods; no spaces permitted. This is the name under which the program may refer to this round state.
period: Required. One of the following: "half-pixel", "one-pixel", "two-pixel".
phase: Required. One of the following: "zero", "one-quarter", "one-half", "three-quarters".
threshold: Required. One of the following: "period-minus-one", "minus-three-eighths", "minus-one-quarter", "minus-one-eighth", "zero", "one-eighth", "one-quarter", "three-eighths", "one-half", "five-eighths", "three-quarters", "seven-eighths", "one", "nine-eighths", "five-quarters", "eleven-eighths".

<set>

A <set> is an arbitrary collection of points, defined by the <point> elements contained in the <set> element. The <set> can be used by any element that accepts a collection of points: <align>, <interpolate>, <shift>, <shift-absolute>, <toggle-points>.

A <set> can be used only in a <glyph> program, or it can be referenced in a <macro> called by a <glyph> program. The name of a <set> can be passed to a macro as a parameter, and a <set> can be the content of a <with-param> element.

Xgridfit must be able to resolve the num attributes of all <point>s in a <set> at compile time. It is an error to attempt to reference a variable in a <set>.

When a <set> is used in an element that has reference points, either explicitly via the <reference> element or implicitly via an enclosing <move> element, any reference points repeated in the set are excluded. This works only when the <reference> points can be resolved at compile time.

A <set> may be preferable to a <range> when all point numbers are known at compile time and the range is short, including perhaps three or four points. The code generated by Xgridfit on encountering a <set> is less flexible, but vastly more efficient than that generated on encountering a <range>.

A <set> may be defined thus among the declarations at the beginning of a <glyph>:

	<set name="bar-bottom-left-corner">
	  <point num="bar-bottom-left"/>
	  <point num="bar-bottom-left + 1"/>
	  <point num="bar-bottom-left + 2"/>
	</set>
	<set name="bar-bottom-right-corner">
	  <point num="bar-bottom-right"/>
	  <point num="bar-bottom-right - 1"/>
	  <point num="bar-bottom-right - 2"/>
	</set>

It can then be referenced whenever needed:

	<move distance="cap-horz-stem">
	  <reference>
	    <point num="bar-top-left"/>
	  </reference>
	  <point num="bar-bottom-left"/>
	  <shift>
	    <set ref="bar-bottom-left-corner"/>
	    <set ref="bar-bottom-right-corner"/>
	  </shift>
	</move>

Content

One or more <point> elements. These are required if no ref element is present.

Attributes

name: Optional, but necessary if this <set> is referred to elsewhere. A name: any sequence of letters, numbers, hyphens, periods; no spaces permitted. Names this <set>.
ref: Required if no <point> elements are present. A reference to a named <set>.
zone: Optional. Permitted values are "twilight" and "glyph".

<set-auto-flip>

When "on" (the default setting), the TrueType engine automatically adjusts the signs of control values when executing MIRP and MIAP instructions. This works very well, so there is rarely a reason to set this to "off."

Content

None.

Attribute

value: Required. Permitted values are "on" and "off".

<set-control-value>
<with-control-value>

You can assign a value to a control value anywhere: in the <pre-program>, a <function>, or a <glyph> program. The value you assign can be either in font units (the units of the grid on which you designed the font) or in pixel units (the grid on which the glyph is now being rasterized). To specify which, include the attribute unit="font" or unit="pixel" ("font" is the default). You must specify the name of the control value with the name attribute and the value (an integer in font units or an "F26Dot6" number in pixel units) with the value attribute.

You can use <set-control-value> to make a control value simulate a local variable.

Use <with-control-value>, which takes attributes exactly like those of <set-control-value>, to assign a control value to be used only within the <with-control-value> element. After this element, the value will be the same as it was before.

	<set-control-value name="myval" unit="font" value="850"/>
	<set-control-value name="otherval" unit="pixel"
                    value="control-value(otherval) * 2"/>
        <with-projection-vector axis="y">
	  <set-control-value name="myval" unit="pixel"
	            value="point(a) --- point(b)"/>
	</with-projection-vector>

Content

None for <set-control-value>; <with-control-value> contains programming of any kind.

Attributes

name: Required. The name of the control value to set.
value: Required. Any value or expression. The value to write to the control value.
unit: Optional. Permitted values are "font" and "pixel"; the default is "font". Whether the value is in font units or pixel units.

<set-control-value-cut-in>
<with-control-value-cut-in>

The value is a distance on the grid. If the difference between a distance from a <control-value> element and the original distance is greater than this, the original distance is used. The effect is generally to use the <control-value> distance at low resolutions and the original distance at high resolutions. This can be used to promote evenness at small sizes, where a 1-pixel difference between the width of (say) p and b can look bad. The default value is 17/16: that is, 1.0625p or 68.

        <set-control-value-cut-in value="1.1"/>

Content

<set-control-value-cut-in> has no content; <with-control-value-cut-in> contains programming.

Attribute

value: Required. Any value or expression. This is the new control value cut-in.

<set-coordinate>

Moves a point to a coordinate determined by the freedom and projection vectors. On the rare occasions when you need a command like this one, it is probably better to use <move> with the pixel-distance attribute.

Content

A <point> to move.

Attribute

coordinate: Required. Any value or expression. This is the new coordinate of the point.

<set-delta-base>
<with-delta-base>

Sets the number that is added to the "size" attribute of a <delta-set> element to get the resolution at which an adjustment should take place. The default value is 9, and that rarely needs to be changed.

        <with-delta-base value="56">
          <delta>
            <delta-set size="12" distance="-8">
              <point num="p"/>
            </delta-set>
          </delta>
        </with-delta-base>

Content

<set-delta-base> has no content; <with-delta-base> contains programming.

Attribute

value: Required. Any value or expression. This is the new delta base.

<set-delta-shift>
<with-delta-shift>

The unit by which a delta instruction shifts a point. If the unit is "2," the smallest shift is half a pixel; if "4," it is a quarter of a pixel; if "8" (the default) it is one eighth, and so on.

        <set-delta-shift value="32"/>

Content

<set-delta-shift> has no content; <with-delta-shift> contains programming.

Attribute

units-per-pixel: Required. These values are permitted: "2", "4", "8", "16", "32", "64".

<set-dropout-control>

Sets up dropout control. The threshold is a number between 0 and 255 in pixels per em. The flags attribute is a number that tells how to set up dropout control relative to the threshold. Here are the flags as explained in the Apple TrueType Reference:

1. Set dropout control to TRUE if other conditions do not block and ppem is less than or equal to the threshold value.
2. Set dropout control to TRUE if other conditions do not block and the glyph is rotated.
4. Set dropout control to TRUE if other conditions do not block and the glyph is stretched.
8. Set dropout control to FALSE unless ppem is less than or equal to the threshold value.
16. Set dropout control to FALSE unless the glyph is rotated.
32. Set dropout control to FALSE unless the glyph is stretched.

Note that, for the sake of simplicity, the numbers used here are different from those implied in the Apple TrueType Reference. Xgridfit adjusts them before passing them to the TrueType engine.

To turn off dropout control, set both threshold and flags to zero.

Content

None.

Attributes

threshold: Required.
flags: Required.

<set-dropout-type>

Sets dropout type. The Microsoft TrueType Reference describes the action of the possible values as follows:

if n=0 rules 1 and 2, and 3 are invoked (dropout control scan conversion including stubs)
if n=1 rules 1, 2 and 4 are invoked (dropout control scan conversion excluding stubs)
if n=2 rules 1 and 2 only are invoked (fast scan conversion; dropout control turned off)
if n=3 same as n = 2
if n = 4 rules 1, 2, and 5 are invoked (smart dropout control scan conversion including stubs)
if n = 5 rules 1, 2, and 6 are invoked (smart dropout control scan conversion excluding stubs)
if n = 6 same as n = 2
if n = 7 same as n = 2

The scan conversion rules are shown here:

Rule 1: If a pixel’s center falls within the glyph outline, that pixel is turned on.
Rule 2: If a contour falls exactly on a pixel’s center, that pixel is turned on.
Rule 3: If a scan line between two adjacent pixel centers (either vertical or horizontal) is intersected by both an on-Transition contour and an off-Transition contour and neither of the pixels was already turned on by rules 1 and 2, turn on the left-most pixel (horizontal scan line) or the bottom-most pixel (vertical scan line). This is “Simple” dropout control.
Rule 4: Apply Rule 3 only if the two contours continue to intersect other scan lines in both directions. That is, do not turn on pixels for ‘stubs.’ The scanline segments that form a square with the intersected scan line segment are examined to verify that they are intersected by two contours. It is possible that these could be different contours than the ones intersecting the dropout scan line segment. This is very unlikely but may have to be controlled with grid-fitting in some exotic glyphs.
Rule 5: If a scan line between two adjacent pixel centers (either vertical or horizontal) is intersected by both an on-Transition contour and an off-Transition contour and neither of the pixels was already turned on by rules 1 and 2, turn on the pixel which is closer to the midpoint between the on-Transition contour and off-Transition contour. This is “Smart” dropout control.
Rule 6: Apply Rule 5 only if the two contours continue to intersect other scan lines in both directions. That is, do not turn on pixels for ‘stubs.’

Content

None.

Attribute

value: Required. Possible values are from "0" to "7," with meanings as described above.

<set-dual-projection-vector>

Like <set-projection-vector>, but the dual projection vector can be set only from a line, and it uses the original positions in the outline of the points that constitute the line rather than their current positions (assuming they have moved).

The dual projection vector is not used by every instruction: just by <interpolate>, <get-coordinate>, <measure-distance>, <mirp>, <mdrp>, and <move> (only when a "relative-to" point is present). This vector lasts only until a new projection vector is set; then it gets canceled.

One or both points in the line may be in the twilight zone. See the explanation for <set-vectors>.

        <with-projection-vector>
          <set-dual-projection-vector to-line="orthogonal">
            <line ref="line-a"/>
          </set-dual-projection-vector>
          <!-- programming here; then the end of the with-projection-vector
               block returns the dual projection vector to its former value. -->
        </with-projection-vector>

Content

One <line>.

Attributes

to-line: Optional. Possible values are "orthogonal" and "parallel"; the default is "parallel". Determines whether the dual projection vector will be orthogonal or parallel to the <line> from which it is set.

<set-equal>

Set target (variable, control value, or any of the graphics state variables that Xgridfit can write to) equal to source, which can be an expression or any number type that Xgridfit can handle.

        <!-- This is the equivalent of a := b; in C. -->
        <set-equal target="a" source="b"/>

Content

None.

Attributes

source: Required. Any value or expression.
target: Required. The name of a variable, control value or graphics variable to write to.

<set-freedom-vector>
<with-freedom-vector>

Just like <set-vectors>, but sets only the freedom vector.

<set-minimum-distance>
<with-minimum-distance>

The minimum-distance property is used by several instructions when the "min-distance" attribute is "yes." The default minimum distance is one pixel (1.0, 1p, 64), but can be set to another value here.

        <with-minimum-distance value="0.85">
          <!-- The distance between p1 and p2 must be at least 0.85 pixel. -->
          <move round="no">
            <reference>
              <point num="p1"/>
            </reference>
            <point num="p2"/>
          </move>
        </with-minimum-distance>

Content

<set-minimum-distance> has no content; <with-minimum-distance> contains programming.

Attributes

value: Required. Any value or expression. This is the new minimum distance.

<set-projection-vector>
<with-projection-vector>

Just like <set-vectors>, but sets only the projection vector.

<set-round-state>
<with-round-state>

Sets the round state. If the round attribute matches the name of a <round-state>, that round state is used. If not, one of TrueType's prefabricated round states may be used:

to-grid
to-half-grid
to-double-grid
up-to-grid
down-to-grid

If the round attribute is not one of these, and not the name of one of the custom round-states, Xgridfit tries to resolve it as a number, constant, variable or function parameter and use that as an argument to SROUND. You had better know what you're doing if you intend to use a raw number in this way; it is safer, more intelligible and just as effective to supply a custom <round-state> element.

The distinction between the element beginning with "set" and the one beginning with "with" is the same as it is for the vector-setting elements: briefly, the round state set by the "set" element affects the instructions that follow it; the round state set by the "with" instruction affects only the instructions that it contains.

Xgridfit generates instructions that keep track of the round state (since the TrueType engine provides no way to read it), but it may lose track if Xgridfit instructions are not used exclusively.

        <with-round-state round="to-half-grid">
          <move>
            <point num="v-point"/>
          </move>
        </with-round-state>

Content

<set-round-state> has no content; <with-round-state> contains programming.

Attributes

round: Required. The name or a standard or custom round state; any value or expression. This is the new round state.

<set-single-width>
<with-single-width>

The size of the single width, in FUnits, i.e. the units of the grid the font was designed on (usually 2048 or 1000 units per em). Presumably this width is converted to the current grid, and it is that converted value that the single-width cut-in is compared to.

Content

<set-single-width> has no content; <with-single-width> contains programming.

Attributes

value: Required. Any value or expression, interpreted as font units. This is the new single width.

<set-single-width-cut-in>
<with-single-width-cut-in>

When the <mirp> or <mdrp> instruction is used, or when <move> is used relative to a point, a single width (determined by <set-single-width> or <with-single-width>) may be used rather than a control value or the original distance if this condition is met: the absolute (either positive or negative) difference between the original outline and the single width is less than the single-width cut-in. The relevant distances are in pixels.

The single width feature appears to be used rarely.

Content

<set-single-width-cut-in> has no content; <with-single-width-cut-in> contains programming.

Attributes

value: Required. Any value or expression. This is the new single-width cut-in.

<set-vectors>
<with-vectors>

Sets both the projection vector and the freedom vector to the same value. They can be set to "x" or "y" via the axis attribute; to a line by including a line element as the content of the <set-vectors> element or the first child of the <with-vectors> element; or by passing "raw" values via the x-component and y-component attributes.

Xgridfit looks first for an axis attribute, next for a <line>, and finally for x-component and y-component attributes (neither is used unless both are present). If it finds none of these and the present element is <with-vectors>, Xgridfit simply stores the present vectors on the stack and restores them at the end of the block. If the present element is <set-vectors>, Xgridfit prints a warning and attempts to find "raw" vector values on the stack.

The "raw" values passed in via x-component and y-component are constrained in ways that make them difficult to calculate, at least in a TrueType program, but the x-component/y-component method is useful to restore values that have been saved via <store-projection-vector> or <store-freedom-vector>. For example, to copy one vector to another, you can do this:

        <variable name="x-comp"/>
        <variable name="y-comp"/>
        <store-freedom-vector x-component="x-comp" y-component="y-comp"/>
        <set-projection-vector x-component="x-comp" y-component="y-comp"/>

But because of the way these instructions can leave values on the stack and take them from the stack again, this is easier and more efficient:

	<no-warning>
          <store-freedom-vector/>
          <set-projection-vector/>
	</no-warning>

When setting vectors to a line, one or both points in the line can be in the twilight zone. You can include a zone attribute in the <line> element or one in either or both <point> elements. Include a zone attribute in the <line> element if both points are in the twilight zone. This is the same as including an attribute zone="twilight" in both points. If only one point is in the twilight zone, include the zone attribute for that point.

Here are several examples:

        <with-vectors axis="x">
          <!-- programming that moves points horizontally. -->
        </with-vectors>

        <with-vectors to-line="orthogonal">
          <line ref="diagonal-line"/>
          <!-- programming that moves points along a line orthogonal to
               diagonal-line. -->
        </with-vectors>

        <set-vectors to-line="parallel">
          <line ref="diagonal-line"/>
        </set-vectors>
        <!-- Subsequent programming will move points along a line parallel
             to diagonal-line. -->

Content

<set-vectors> has no content if an axis attribute or the x-coordinate and y-coordinate attributes are present; otherwise it may contain a <line> element. <with-vectors> works the same way, but also contains programming.

Attributes

axis: Optional, and incompatible with other attributes. Possible values are "x" and "y".
to-line: Optional, and permitted only when a <line> is present. Possible values are "orthogonal" and "parallel"; the default is "parallel". Determines whether the vectors will be orthogonal or parallel to the <line> from which they are set.
x-component, y-component: Optional, but if one of these attributes is present, the other must be as well. Not permitted with other attributes or when a <line> is present.

<shift>

Shifts one or more points, ranges, sets, contours and zones by the distance between the current position of the reference point and its original position. Note that this does not guarantee that the shifted elements will maintain their original distance from the reference point (use <move> or <mdrp> for that).

The <shift> element may contain points, ranges, sets, contours and zones in any combination and order. The following is perfectly correct:

        <shift>
          <reference>
            <point num="ref-pt"/>
          </reference>
          <point num="move-pt-1"/>
          <range ref="move-rg-1"/>
          <contour num="0"/>
          <point num="move-pt-2"/>
          <range ref="move-rg-2"/>
        </shift>

But note that all the points are shifted first, then all the ranges or sets, then all the contours, and finally any zones. The order of child elements in the <shift> element is not significant.

If you want to move points to the nearest rounded position after the shift, include a round attribute. This works exactly like the round attribute on the <interpolate> element.

Content

Any number of <point>, <range>, <set>, <contour> and <zone> elements, in any order.

Attributes

compile-if: Optional. If present, the <shift> element is compiled only if this attribute evaluates as true (non-zero) at compile time.
round: Optional. Possible values are "yes", "no", one of the standard or custom round states, or any value or expression yielding a number to pass to SROUND. The default value is "no", since by default no rounding is done on the <point>s contained in a <shift> element.
reference-ptr: Optional. Possible values are "1" and "2". This determines which reference pointer (RP1 or RP2) to use. Normally Xgridfit decides which pointer is appropriate in the context; otherwise RP1 is used.

<shift-absolute>

Moves one or more points along the freedom vector by a fixed amount (expressed in pixels); it does not use the projection vector. The <shift-absolute> element must contain at least one point to shift: that is, a <range>, <set> or <point> element. It may contain any number of <point>s, <range>s and <set>s.

Content

Any combination of <range>, <set> and <point> elements in any order.

Attributes

pixel-distance: Required. Any value or expression, understood as a distance on the grid.

<srp>

Does the work of SRP0, SRP1, SRP2. But it should rarely be necessary to set the reference pointers explicitly.

Content

One <point> element; the reference pointer is set to point to this.

Attribute

whichpointer: Required. The reference pointer to set. Possible values are "0", "1" and "2".

<store-projection-vector>
<store-freedom-vector>

These instructions store a vector as two numbers, an x-component and a y-component. The x-component and y-component attributes, if given, must be identifiers for variables:

	<store-projection-vector x-component="vx" y-component="vy"/>

If these attributes are not given, a warning is printed and the values are left on the stack, where they will be picked up correctly by a following set instruction. For example, this code sets the projection vector to be the same as the freedom vector:

        <store-freedom-vector/>
        <set-projection-vector/>

Note that a with block will not pick up the components of a vector from the stack.

Content

None.

Attributes

x-component, y-component: Optional, but if one attribute is present the other must be as well. The names of variables in which to store the components of the vector. If these attributes are not present, the compiler displays a warning and the values are left on the stack.

<subtract>

Subtracts minuend - subtrahend. If result-to is not specified, Xgridfit attempts to write the result to minuend.

Content

None.

Attributes

minuend: Required, except when <subtract> is the child of a <formula>. Any value or expression. The value to subtract from.
subtrahend: Required, except when <subtract> is the child of a <formula>. Any value or expression. The value to subtract from the minuend.
result-to: Optional; not allowed when <subtract> is the child of a <formula>. The name of a variable of control value in which to store the result of this operation. If result-to is omitted where allowed, and minuend is a variable or control value, the result is written to minuend. If minuend cannot be written to, the compiler issues a warning and the result is left on the stack.

<szp>

Does the work of SZP0, SZP1, SZP2. But these should rarely be needed (use the zone attributes of the point element instead).

Content

None.

Attributes

zone: Required. Possible values are "twilight" and "glyph". The zone to set the zone pointer to.
whichpointer: Required. Possible values are "0", "1" and "2". Identifies the pointer to set.

<variable>

Variables are spaces in the TrueType Storage Area. They are declared in <variable> elements; Xgridfit takes care of indexing the Storage Area.

        <variable name="var-name"/>

Most variables are local to a glyph program, function or pre-program. Variable declarations may come among the declarations at the beginning of a <glyph> program; after <param> elements in a <function>, and at the beginning of the <pre-program>. A global variable may be declared anywhere in the top level of the program, as a child of <xgridfit> (it is good form to group variable declarations together); a value may be assigned to a global variable in the <pre-program> and read by code in any <glyph> or <function> or elsewhere in the <pre-program>.

Variables must be written to before they can be read from. (Some versions of Freetype initialize them to zero, but the Microsoft rasterizer yields an error if a variable is read before it is written.) Local variables may be initialized with a value attribute in the declaration.

A variable is named via its name attribute. This must be unique in the file in the case of a global variable, but in the case of local variables unique only in the <glyph> program or <function>. Several names are reserved and should be avoided when naming variables and constants, since they belong to pre-defined variables and constants:

Current size (all read-only):
- pixels-per-em
- point-size
Values of the round-state variable (constants):
- to-grid
- to-half-grid
- to-double-grid
- down-to-grid
- up-to-grid
- no
- custom
Graphics variables:
Writing to these changes the graphics state. The "default" variables can be written to only in the <pre-program>. Trying to write to them elsewhere produces a compile error. Actually, it is never necessary to write to a "default" variable since writing to one of the other variables in the <pre-program> automatically writes to the "default" variable as well. So treat the "default" variables as read-only variables.
- round-state (can be written to only via <set-round-state> and <with-round-state>)
- custom-round-state (can be written to only via <set-round-state> and <with-round-state>)
- minimum-distance
- minimum-distance-default
- control-value-cut-in
- control-value-cut-in-default
- single-width
- single-width-default
- single-width-cut-in
- single-width-cut-in-default
- delta-base delta-base-default
- delta-shift delta-shift-default

Content

None.

Attributes

name: Required. A name: any sequence of letters, numbers, hyphens, periods; no spaces permitted. The name of this variable.
value: Optional. Any value or expression. A value with which to initialize the variable.

<variant>

A <variant> is an alternative version of a function to be used at certain sizes or resolutions. Include one or more <variant> elements as the last children of any <function> element. For further explanation, see the section on functions.

Content

Programming. <param> and <variable> elements are not permitted; the <variant> must use those of the parent <function>.

Attribute

test: Required. Any value or expression. The variant is used if this attribute evaluates as true (non-zero) when the <pre-program> is run.

<with-control-value>

See <set-control-value>

<with-control-value-cut-in>

See <set-control-value-cut-in>

<with-delta-base>

See <set-delta-base>

<with-delta-shift>

See <set-delta-shift>

<with-freedom-vector>

See <set-freedom-vector>

<with-minimum-distance>

See <set-minimum-distance>

<with-param>

Defines a value to be passed to a function, macro or glyph program. The value may be any of the value-types that Xgridfit handles. Note that all values are resolved to numbers before a call to a function takes place: Xgridfit does not pass parameters to functions by reference. A result of this is that if a variable or control value is passed to a function, these things cannot be written to.

In general there will be a <with-param> element for every <param> element that appears in the function or macro being called. However, a <with-param> element may be omitted if the matching <param> contains a default value.

The order of <with-param> elements in a <param-set>, <call-function>, <call-macro> or <call-glyph> element is not significant.

If the <with-param> element is part of a call to a macro, the value passed can be a <set>, <range> or <line>. The name of such a structure can be passed via the value attribute, or the structure itself can be passed as the child of <with-param>. When <with-param> contains a <set>, <range> or <line>, the value attribute is optional.

Programming can also be passed via a <with-param> element, and in this case too the value attribute is optional.

Content

Usually none, but if the call is to a <macro> or <glyph>, the element can contain a <range>, <set> or <line>, or a fragment of programming.

Attributes

name: Required. A name: any sequence of letters, numbers, hyphens, periods; no spaces permitted. This must match the name of <param> in the <function>, <macro> or <glyph> being called.
value: Required except when content is present. Any value or expression. The value to pass as a parameter.

<with-projection-vector>

See <set-projection-vector>

<with-round-state>

See <set-round-state>

<with-single-width>

See <set-single-width>

<with-single-width-cut-in>

See <set-single-width-cut-in>

<with-vectors>

See <set-vectors>

<xgridfit>

The root element of an Xgridfit program file.

Namespace declaration

This element must contain the namespace declaration xmlns="http://xgridfit.sourceforge.net/Xgridfit2".

Content

One at most of these: <glyph-select>, <infile>, <outfile>, <outfile-base>, <outfile-script-name>, <no-compile>, <legacy-functions>, <pre-program>. Any number of these: <constant>, <alias>, <variable>, <round-state>, <default>, <control-value>, <function>, <macro>, <glyph>, <xi.include>.

Attribute

xml:id: Optional. A valid XML ID, i.e. any sequence of letters, numbers, hyphens, periods; no spaces permitted; and unique within the program. This ID may be used if the <xgridfit> element is imported into a file using XInclude.

<zone>

A zone to be shifted by a <shift> instruction.

Content

None.

Attribute

zone: Required. Must be "twilight" or "glyph".

Element Reference

<absolute>

Content

Attributes

<add>

Content

Attributes

<alias>

Content

Attributes

<align>

Content

Attribute

<align-midway>

Content

Attributes

<call-function>

Contents

Attribute

<call-glyph>

Content

Attribute

<call-macro>

Content

Attribute

<call-param>

Content

Attribute

<ceiling>

Content

Attributes

<command>

Content

Attributes

<compile-if>

Content

Attribute

<constant>

Content

Attributes

<contour>

Content

Attributes

<control-value>

Content

Attributes

<control-value-delta>

Content

Attributes

<control-value-index>

Content

Attributes

<default>

Content

Attributes

<delta>

Content

Attributes

<delta-set>

Content

Attributes

<diagonal-stem>

Content

Attributes

<disable-instructions>

Content

Attributes

<divide>

Content

Attributes

<else>

Content

Attributes

<enable-instructions>

Content

Attributes

<entry>

Content

Attributes

<flip-off><flip-on>

<flip-off>
<flip-on>