xgridfit
Author: Peter S. Baker

Home Page Project Page Download CVS repository

<glyph-select> <infile> <outfile> <constant> <variable> <round-state> <default> <control-value> <alias> <function> <macro> <pre-program> <glyph>

# Structure of an Xgridfit Program

An Xgridfit program supplies the control-value table, pre-program, functions and glyph programs for the font. It also controls several parameters relating to TrueType instructions, stored in the font's maxp table. The contents of the file must be well-formed XML, validated against the Xgridfit RELAX NG schema (`xgridfit.rnc` or `xgridfit.rng`). Perhaps the easiest way to validate your program is to include the `-V` option on the Linux command line when you invoke Xgridfit:

        $ xgridfit -V myprog.xgf

Another worthwhile tool is nxml-mode, an Emacs mode that validates while you edit your program. To use nxml-mode, copy `xgridfit.rnc` to the nxml-mode schema directory and add this line to `schemas.xml` in the same directory:

        <documentElement localName="xgridfit" uri="xgridfit.rnc"/>

The first line in any Xgridfit program file must be the XML declaration:

        <?xml version="1.0" encoding="UTF-8"?>

Then comes the <xgridfit> element, the root element that contains all other information in the file. The <xgridfit> element must contain the Xgridfit namespace declaration:

        <xgridfit xmlns="http://xgridfit.sourceforge.net/Xgridfit2">

The child elements of <xgridfit> can come in any order, though it makes sense to group related elements (e.g. functions, control values) together.

Following are the possible children of the <xgridfit> element.

## <glyph-select>

Specifies a list of glyphs to compile, ignoring all others. The glyph names in the list may be delimited by "+" or space--but only one or the other. 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>

## <infile>

Specifies the name of the FontForge file or TrueType font to be opened by the script generated by Xgridfit.

## <outfile>

Specifies the name of the file or font to be saved by the script generated by Xgridfit.

## <datafile>

When running in merge-mode, Xgridfit needs to save information about the font. It can do so in the font.persistent object of an .sfd file it is saving or in a separate file. Use this element to specify the name of a separate file.

## <constant>

Unlike the <constant> elements defined in a <glyph> program, <constant>s here are visible in all <glyph> programs, in <function>, <macro>, and <pre-program> elements.

## <variable>

Like the global <constant>, the <variable> defined here is visible everywhere. It may be initialized by the <pre-program> so as to provide state information to all glyph programs, or it may be used anywhere for temporary storage.

## <round-state>

These elements, permitted only here, define custom round states, which can be invoked anywhere.

## <default>

These elements define graphics defaults and other defaults and settings.

## <control-value>

A <control-value> element defines a control value, a specialized variable used by various instructions to regulate distance on the grid. A typical TrueType font has many <control-value> elements.

## <alias>

An alternate name for a control-value, constant or variable.

## <function>

A <function> element contains the definition of a function--a chunk of code that can be invoked from anywhere and, like the functions (methods, procedures) of other programming languages, can accept parameters and return values.

## <macro>

A <macro> element contains the definition of a macro--a chunk of code that is compiled whenever the compiler encounters a <call-macro> element.

## <pre-program>

The <pre-program> contains programming that is run whenever the font is about to be rasterized at a new size. Typical tasks for the <pre-program> are to round and adjust control values and set default values in the graphics state. The <pre-program> element is required, though it may be empty.

## <glyph>

The file may contain any number of <glyph> elements. Each contains the programming for a single glyph.