Xgridfit
Author: Peter S. Baker

Home Page Project Page Download CVS repository

# Updating Xgridfit programs

With the introduction of Xgridfit 1.0, a number of elements and attributes were deprecated. Most continued to work, while a few had to be removed from programs. A utility, `xgfupdate`, was introduced, which automatically updated Xgridfit program files to use the newer, recommended syntax. A special schema, `xgridfit-transitional.rnc`, could be used to validate programs that retained deprecated but allowable features. More features were deprecated with the release of version 1.10, and `xgfupdate` was updated to substitute approved features for deprecated ones.

With the release of version 1.11, support for all deprecated features was removed from the Xgridfit compiler, and the transitional schema and the DTD based on it were both removed from the Xgridfit package. Therefore it is essential to run `xgfupdate` on older program files to bring them up to date.

By default, `xgfupdate` only does what is needed to update from version 2.0 to version 2.1: that is, it adds namespace declarations where needed (on <xgridfit> and in references in <xi:include> elements). Invoke it as follows:

        xgfupdate oldfile.xgf > newfile.xgf

If you have older program files that need to be updated for compatibility with Xgridfit 1.19, invoke `xgfupdate` as follows:

        xgfupdate -v 1 oldfile.xgf > newfile.xgf

Then run the program without the `-v 1` attribute, if necessary.

These commands will convert a batch of Xgridfit files:

        mkdir new
        for f in *.xgf; do xgfupdate $f > new/$f; done

If you have XMLStarlet installed on your system, `xgfupdate` will format the new file attractively; otherwise it will leave you with a valid file which is messy in some places.

The following sections outline the changes to the language since version 1.0.

## Namespace declaration needed (2.1)

The <xgridfit> element requires the namespace declaration `xmlns="http://xgridfit.sourceforge.net/Xgridfit2"`. This change also requires revision of most <xi:include> elements: for details, see the XInclude section of this documentation.

## Attributes `count` and `highest` replaced on <legacy-functions> (1.19)

There is now a single attribute, `max-function-defs`; this should be the same as the corresponding maxp entry in any font being converted for use with Xgridfit.

## When generating Python script, use `pyflags` attribute on <outfile> (1.19)

When you wanted a script generated by an earlier version of Xgridfit to generate a font (rather than save an .sfd file), you could include an `fmflags` attribute on the <outfile> element: this was an integer to pass to FontForge's Generate() command.

With version 1.19, you should still use `fmflags` when generating a script in FontForge's native scripting language. But if you are generating a Python script, you should instead use `pyflags`, a list of values documented here. Actually, it is perfectly all right to have both attributes on the <outfile> element.

## The `offset` attribute on <point> and <with-param> is not permitted (1.11)

The `offset` attribute has long been discouraged; use an expression instead, e.g.

        <point num="p + 1"/>

With version 1.11, the `offset` attribute is no longer permitted.

## Use <push> instead of <to-stack> (1.11)

In versions before 1.11, <push> could be used only to place on the stack values that could be resolved to numbers at compile time. It can now be used with values that must be resolved at run time, and thus <to-stack> is no longer necessary.

## Use -p (push-break) option instead of -b (delta-break) (1.11)

These options are meant to prevent Xgridfit from producing a command string so long that FontForge cannot process it. Xgridfit breaks up long PUSH instructions into shorter ones; these options determine how long those instructions can get before they must be broken. In versions before 1.11, the -b (delta-break) option applied only to deltas; in 1.11 and later both -b and -p (push-break) affect all lists of numbers to be pushed onto the stack. When -p is omitted but -b is present, -p is set to double the amount of -b (because deltas involve two numbers). When -p is present, -b, if present, is ignored. There is no plan to remove the -b option, but -p should be preferred.

## `value` attribute on <param> element behaves differently for functions (1.11)

In versions before 1.11, the `value` attribute on <param> was evaluated with <function> as context, making the function's other <param> and <variable> elements visible. This behavior made no sense, as `value` was evaluated before execution of the function began. Now the active context when evaluating `value` is the <call-function> element. This means that name collisions with the <constant> and other elements of a <glyph> program are possible. However, access to such elements may at times be useful.

## Use `name` attribute to name things (1.0)

Earlier versions of Xgridfit inconsistently used `name` and `id` attributes to name things. To refer to named elements, it used `function-id` in function calls, `macro-id` in macro calls, and `param-id` in passing parameters to functions and macros. In versions 1.0 and later you should use `name` everywhere, including these elements which formerly used other attributes:

        <function name="my-func">
        <macro name="my-macro">
        <control-value name="my-cv" value="235"/>
        <variable name="my-var"/>

        <call-function name="my-func">
          <with-param name="my-function-param"/>
        </call-function>

        <call-macro name="my=macro">
          <with-param name="my-macro-param"/>
        </call-macro>

## <default type="max-instructions"> is not permitted (1.0)

This <default> type is used only by pre-1.0 versions of Xgridfit running in TTX mode. Since this mode is no longer supported, the <default> type has no function.

## <asm> no longer permitted (1.0)

The <asm> element was used only in TTX mode, which is no longer supported. Therefore <asm> elements must be converted to <command> elements. To do this locate the sed script `convert-asm.sed` (Linux users will find it either in /usr/share/xml/xgridfit/utils/ or /usr/local/share/xml/xgridfit/utils/) and run it as follows:

        sed -f /usr/local/share/xml/xgridfit/utils/convert-asm.sed oldfile.xgf > newfile.xgf

The result will be an Xgridfit file that is valid for FontForge mode. This conversion is also done automatically by `xgfupdate`.

## Use `value` instead of `num` attribute with <constant> (1.0)

For consistency with <control-value> and <param>, the `num` attribute on the <constant> element has been changed to `value`.

## Container elements are not needed (1.0)

Older versions of Xgridfit required the use of certain elements whose only function was to contain other elements: <profile>, <control-values>, <functions>, <macros>, <declarations>, <variables>, <params>. These elements are no longer used. The elements they originally contained which are children of the <xgridfit> element can come in any order (in pre-1.0 versions Xgridfit was rather fussy about the order of these elements).

## <param-set> not always needed (1.0)

<call-function> and <call-macro> elements formerly could contain only <param-set> elements, which could contain <with-param> elements. But <param-set> is a device for grouping parameters when a function is to be called repeatedly via LOOPCALL, or when macro code is to be inserted repeatedly. It is unnecessary when a function or macro is to be called just once. Starting with version 1.0, <param-set> is needed only when a single <call-function> or <call-macro> contains more than one set of parameters; otherwise <with-param> elements can be the children of <call-function> or <call-macro>.

## Use `min-distance` instead of `min-amount` (1.0)

Before version 1.10, a `min-amount` attribute on <diagonal-stem> indicated that minimum distance should be used with a specified value. This was inconsistent with the usage of the <move> element. Beginning with version 1.0, and obligatorily with version 1.11, `min-amount` is not recognized; instead, specify a new minimum distance value with the `min-distance` attribute, which can take a number, or yes, or no.