Logo 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="". 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-macro name="my=macro">
      <with-param name="my-macro-param"/>

<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.