Running Xgridfit

Using `xgridfit` and FontForge

Open your Xgridfit program file and make sure it contains an <infile> element containing the name of the FontForge source file (.sfd) or TrueType file (.ttf) to which instructions are to be added and an <outfile> element containing the name of the file (.sfd or .ttf) to be output. Now invoking Xgridfit is simply a matter of typing xgridfit on the command line, with the name of the program file (the extension should be .xgf or .xml) as a parameter, e.g.

    $ xgridfit Junicode-Bold.xgf

If all goes well, Xgridfit will produce a script named Junicode-Bold.py. If the file named in the <infile> element is present, you may simply run your script in FontForge:

    $ fontforge -script Junicode-Bold.py

Alternatively, if you're feeling confident, Xgridfit will pipe its output directly to FontForge without saving it in a file. Just include -f on the command line:

    $ xgridfit -f Junicode-Bold.xgf

The script produced by Xgridfit will open the .sfd or .ttf file, add cvt, fpgm and prep tables, add instructions to each glyph, and either save an .sfd file or generate a TrueType (.ttf) font.

The xgridfit script for Linux and Mac OS X takes several command-line options (the long forms in parentheses are the parameters to use if you bypass the xgridfit script, as explained below):

-a value (max-stack): The amount of memory reserved for the TrueType runtime stack. The default is 256, which is probably generous for most fonts; increase it if you sometimes write <delta> or <control-value-delta> elements containing a great many <delta-set> elements.
-A (auto-instruct): Auto-instruct all glyphs in the font before installing Xgridfit programming. This option has no effect except in merge-mode (option -m).
-b value (delta-break): Obsolete, but retained for backwards compatibility. This parameter formerly governed the number of <delta-set> elements that could be pushed onto the stack at one time. Beginning with version 1.11, it sets push-break to twice its value (since a <delta-set> has two values). If push-break is supplied, this parameter has no effect. It has no effect except when FontForge-language output is requested via the option -l ff.
-c yes|no (compile-globals): Determines whether Xgridfit should compile functions, control values, pre-program and maxp entries (default is "yes").
-C gray|black|white (color): Default color of rounded distances. This is the setting used by <move> and other instructions that move points; also the <round> and <no-round> elements and the round() operator. It can also be set with a <default> element, and it can be overridden by a color attribute on the elements affected by it. For an explanation of color, see the Apple TrueType Reference.
-d: Run in debug mode. Output is file.debug rather than file.pe or file.py.
-D (delete-all): Delete all instruction-related programming and data before installing Xgridfit programming. This option has no effect except in merge-mode (option -m). In Python mode (option -l py), instruction-related programming and data are always deleted.
-e: Echo the commands used to launch the XML validator and XSLT processor.
-E: Report the time (in seconds) used to run Xgridfit.
-f: Pipe generated script to FontForge. Do not save it in a file. This option overrides -O, and it is incompatible with -d, -S and -z.
-F file (datafile): In merge-mode, Xgridfit stores and reads information about the font's state. By default, this is stored in FontForge's font.persistent object, but this can be stored only in an .sfd file. Use this option to store font information in a file instead.
-g glyph (glyph-select): Compile only the specified glyphs and skip all others. If more than one ps-name is given, they must be separated by "+" signs. Spaces are not permitted. See also the <glyph-select> element.
-G yes|no (init-graphics): Include or omit at the beginning of each glyph program a function call that initializes variables used to track the graphics state. The default is "yes." This option can be overridden with the init-graphics attribute on any glyph element.
-h: Display a help message and exit.
-H (auto-hint): Auto-hint all glyphs in the font before auto-instructing. This option has no effect except when auto-instructing is requested (option -A).
-i file (infile): This is the name of a FontForge source file (.sfd) or TrueType font (.ttf) to be opened by the FontForge script generated by Xgridfit.
-l py|ff: As of version 1.19, Xgridfit can generate a script for FontForge in either of two flavors: Python or FontForge's native scripting language. Use this option to specify which one. In Python mode the default extension of the output script is .py; in FontForge native mode it is .pe. The default, beginning with version 2.0, is py. An alternative to using the command-line option (in version 2.1 and later) is to set an environment variable XGRIDFIT_OUTPUT_LANG to either "py" or "ff".
-m: Run in merge-mode. Xgridfit produces a Python script that merges Xgridfit programming with TrueType programming already present in the font.
-o file (outfile): The name of the file to be written by the FontForge script generated by Xgridfit. If you want FontForge to write a source file, the filename should end .sfd; if you want FontForge to generate a font, it should end .ttf. It is an error if the filename does not have one of these two extensions. It is strongly recommended that the infile and outfile names be different--that is, that you do not overwrite the file that your FontForge script reads.
-O file: Name of the FontForge script to be output by Xgridfit.
-p value (push-break): The maximum number of values that a single PUSHB or PUSHW instruction can push onto the stack. Longer lists of values are divided. This parameter affects the way Xgridfit processes <push>, <delta> and other elements that can work with long lists of values. Its purpose is to prevent strings in the script generated by Xgridfit from becoming long enough to exceed the maximum allowed by FontForge. The default is twenty; a higher number may well work for your font. If delta-break is set and push-break is not, the value of push-break is twice the value of delta-break (since a <delta-set> contains two values). This option has no effect except when FontForge-language output is selected with the option -l ff.
-P yes|no (combine-prep): Combine the Xgridfit pre-program with the prep table already present in the font (merge-mode only; default is yes).
-q (silent-mode yes|no): The xgridfit -q option does not take a value: when it is present, silent mode is used. The long form of the parameter requires a value, yes or no. When yes, messages like "Compiling glyph Adieresis" are suppressed. This can lead to significant increases in program speed. Warnings and error messages are still displayed. The default is no.
-s value (max-storage): The size of the Storage Area to be reserved for this font by the TrueType engine. The default is to reserve space for 64 32-bit numbers. Xgridfit reserves 24 of these for its own use (and so this value can never be less than 24), leaving 40 available for user-defined variables. Raise this number if you are likely to have more than 40 variables in use at any one time: lower it if you use fewer variables.
-S name (outfile-base): When this option is present, Xgridfit produces a separate file for every glyph it compiles. The file has the name specified here, plus the ps-name of the glyph, plus the extension .pe, .py or .debug. If the option is -S Test, you will get files Test_A.pe, Test_B.pe, etc., and also a file Myfont.pe containing control values and other global elements. Note that if the <outfile> element is present (or the -o option is used), the -S option also causes the resulting output to be saved in a separate file. Use the -z (outfile-script-name) option to specify a filename.
-t value (max-twilight-points): Maximum number of points in Twilight zone. The default is 25, but few fonts require so many.
-T file: Processors other than xsltproc do not have native support for XInclude. If you use one of these processors with XInclude, Xgridfit uses xmllint (part of the libxml package) to resolve XIncludes, writing an intermediate file which it passes to the XSLT processor. Normally it deletes this file at the end of the run. Use the -T option to specify a different name for the temporary file; this will not be deleted and may be useful for debugging.
-v: Show version number and exit.
-x: Skip compilation. Use this if you want to validate a file quickly.
-z file (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 saves 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 option has no effect when the outfile-base is not specified and the glyph programs in a script are not being saved separately.

Here are some sample command lines:

    Compiling all glyphs:
      xgridfit myfont.xgf

    Compiling only glyph uni0312:
      xgridfit -g uni0312 myfont.xgf

    Compiling several related glyphs:
      xgridfit -g a+macron+amacron myfont.xgf

    Producing a file to aid in debugging:
      xgridfit -d -g a+macron+amacron myfont.xgf

    Specifying input and output files:
      xgridfit -i myfont.sfd -o myfont.ttf myfont.xgf

    Validate before compilation:
      xgridfit -V myfont.xgf

    Validate only:
      xgridfit -V -x myfont.xgf

Bypassing the `xgridfit` script

The xgridfit executable is a script for the Bash shell, available on Linux systems and Mac OS X. If Bash is not available on your system, or if you prefer to use an XSLT processor that Xgridfit does not support (such as Microsoft's MSXML), you can run Xgridfit by invoking your favorite XSLT processor directly--in which case parameters have a longer form. Here Xgridfit is run directly with xsltproc:

    xsltproc -o Junicode-Bold.pe \
      --stringparam infile Junicode-Bold.sfd \
      --stringparam outfile Junicode-Bold.ttf \
      --param max-twilight-points 29 \
      --param max-storage 128 \
      /usr/local/share/xml/xgridfit/lib/xgridfit.xsl Junicode-Bold.xgf

Or for Python output:

    xsltproc -o Junicode-Bold.py \
      --stringparam infile Junicode-Bold.sfd \
      --stringparam outfile Junicode-Bold.ttf \
      --param max-twilight-points 29 \
      --param max-storage 128 \
      /usr/local/share/xml/xgridfit/lib/xgridfit-python.xsl Junicode-Bold.xgf

Here is Saxon 6:

    java -jar /usr/local/saxon/saxon.jar \
      -o Junicode-Bold.pe \
      Junicode-Bold.xgf \
      /usr/local/share/xml/xgridfit/lib/xgridfit.xsl

Or for merge-mode:

    java -jar /usr/local/saxon/saxon.jar \
      -o Junicode-Bold.pe \
      Junicode-Bold.xgf \
      /usr/local/share/xml/xgridfit/lib/xgridfit-merge.xsl

Xalan C++:

    xalan -in Junicode-Bold.xgf \
      -out Junicode-Bold.pe \
      -xsl /usr/local/share/xml/xgridfit/lib/xgridfit.xsl \
      -param infile "'Junicode-Bold.sfd'" \
      -param outfile "'Junicode-Bold.sfd'"

Xalan java in debug mode:

    java org.apache.xalan.xslt.Process -in Junicode-Bold.xgf \
      -out "Junicode-Bold.debug" \
      -xsl /usr/local/share/xml/xgridfit/lib/xgridfit-debug.xsl

If you like, you can skip generation of a FontForge script file and pass the output of an Xgridfit run directly to FontForge:

    xsltproc /usr/local/share/xml/xgridfit/lib/xgridfit.xsl \
      Junicode-Bold.xgf | fontforge -script -

Running Xgridfit

Using xgridfit and FontForge

Bypassing the xgridfit script

Using `xgridfit` and FontForge

Bypassing the `xgridfit` script