Configuring MathFlow for Arbortext

The files custom/editinit/mathml_editinit.acl and custom/init/mathml_init.acl are where all the callbacks are set for the various events MathFlow handles, via the ACL function doc_add_callback.

The two primary callbacks are create and graphicpathhook:

If you are using your own functions as callbacks or hooks, it is possible they are in conflict with the ones defined in MathFlow

The following list includes all those MathFlow uses.

Callbacks:

Hooks:

When no explicit style information is specified, the MathFlow rendering engines apply internal algorithms to select fonts. The Java engine firsts attempts to locate characters in a set of preferred system fonts: Times New Roman for alphanumeric characters, Euclid Symbol for common symbol characters, and Code 2000 for rarer symbol characters. Note that Euclid Symbol is included with MathFlow but Code 2000 must be obtained separately. The choice of preferred system fonts is configurable. See Configuring preferred fonts.

When characters cannot be located in MathFlow preferred system fonts, the Java engine also contains built-in fonts containing around 500 symbol characters and will use these fonts instead. Characters that cannot be located either in preferred system fonts or internal fonts render as missing glyphs, generally represented by an empty box. In these cases, explicitly specifying a system font known to contain the character is generally the best solution.

The Win32 rendering engine employs a similar, but more complex model. Characters are first sought in a collection of preferred system fonts, primarily Times New Roman, Symbol and MT Extra. For certain classes of characters, Mathematica fonts, Euclid fonts, and/or Adobe's Mathematical Pi fonts may also be utilized. When characters cannot be located in preferred fonts, the rendering engine searches all available system fonts. At this point, there is no control over the order in which fonts are searched, which can lead to unpredictable results. As in the Java case, explicitly specifying a system font known to contain the character is generally the best solution.

MathML contains twelve pre-defined logical styles, such as "sans-serif" and "script." When one of these styles is selected, both the Java and Win32 engines reformulate these requests in terms of specific fonts. As above, the renderers first look for characters in preferred fonts, and then fall back to either internal fonts or other system fonts, depending on the rendering engine.

For user-defined custom styles, both engines will attempt to literally honor the request. If the specified font is not available, an attempt is made to render the character in some font containing the character. If no font can be found, the character is rendered with a missing glyph indicator.

To configure the list of fonts MathFlow Composer is allowed to use, create a font configuration file with file name "FontConfig.txt". Save the file to the <custom-path>/lib/dll/ folder.

If this file is not present when MathFlow Composer is initialized, MathFlow Composer will consider all TrueType, OpenType and PostScript fonts installed on the system as eligible for use within EPS files. This is not recommended, except for compatibility with older versions of MathFlow. See Font style management overview for more information.

The font configuration file should contain a list of font face names, one per line. The '#' character can be used to include comments. Any text on a line following a '#' character will be ignored.

The following example illustrates the format of the font configuration file:

# A sample FontConfig file
#
Times New Roman
Euclid Symbol
MT Extra
Mathematica7

Important: the font face name given in the font configuration file must exactly match the font face name as defined in the font. To determine the font face name under Windows, locate the font in the Fonts control panel and double click it to open the font preview panel. The font face name will be given on the first line. It does not include the parenthesized font technology label which is sometimes present. For example, the title bar of the font preview panel for the Mathematica7 Regular font reads "Mathematica7 (TrueType)" and the font face name is Mathematica7.

MathFlow Composer requires access to three special fonts to function properly: a main font, a symbol font, and an "extra" font. The main font must contain the ISO Latin 1 alphabetic characters and is the default font for Latin 1 variables and numbers when no explicit style is given in the MathML markup for an expression. Currently, MathFlow Composer requires Times New Roman to be available as a default choice of main font, and thus Times New Roman must always be listed in any font configuration file.

The symbol font should be a font with the Adobe symbol encoding, and glyphs for most characters in the encoding. There are two main choices, the standard Adobe Symbol font and the Euclid Symbol font installed with MathFlow Either can be used, but one must be listed in font configuration files. If both are listed, MathFlow Composer will designate the first one encountered in the listed fonts as the symbol font, and treat the other one as an optional entry.

The 'extra' font is used for pieces of brackets, braces, parentheses, and so on, assembled from pieces when required in large sizes. Because the notion of an "extra" font is particular to WIRIS products, there are again only two choices, MT Extra, and Euclid Extra. Either font is acceptable, but one must be listed in all font configuration files. As with the symbol font, if both fonts are listed, the first one encountered will be designated as the 'extra' font, and the other will be treated as an optional entry.

Apart from the required font entries, the font configuration file may list any number of additional fonts. When MathFlow Composer encounters a character without a style indicating an explicit font face, it will first try to locate the character in one of the required fonts. Failing that, it will proceed through the list of optional font entries in the order in which they occur, trying to locate a font containing the character. The first font containing the character will be used. If no font is located containing the character, MathFlow Composer will render a red question mark in place of the character.

When MathFlow Composer requires a character explicitly styled with a particular font face, it will consult the listed fonts, and if that font face is present, it will check if the font contains the character, and if it does, it will be used. Otherwise, the font face request will be ignored and the procedure used for unstyled characters will be employed, as described in the preceding paragraph.

MathFlow Composer contains a built-in database of characters useful for math typesetting and fonts that contain them. The fonts and font families are in the database and are known to work well in EPS:

indent> Euclid fonts

Mathematical Pi fonts

Mathematica fonts

Math fonts

Lucida New Math fonts

Lucida Bright Math fonts

Lucida Sans Unicode

WP Math fonts

cm (TeX) fonts

msam and msbm (AMS fonts)

Fences

</WRAP>

In addition, all PostScript Type 1 fonts and most OpenType versions of PostScript fonts can be used. For these fonts, however, you may need to provide MathFlow Composer with detailed information about the encoding and characters available in these fonts in a FontInfo.ini file. See The FontInfo.ini file for more information.

By contrast, TrueType fonts of the variety known as CID fonts will not work with the current version of MathFlow Composer. These include most large fonts for Asian languages. The most significant example of a CID font that cannot be used is the shareware Code2000 font.

In general, the easiest way to determine whether a TrueType font is compatible with MathFlow Composer is to simply conduct an experiment. List it in your font configuration file, create an equation with a custom style explicitly setting it as the font, and try it. If it works for any characters, the font is compatible. If MathFlow Composer doesn't seem to be able to find characters known to be present in the font, but it can find some characters, use a FontInfo.ini file to provide detailed information about the encoding and characters available. See The FontInfo.ini file for more information.

In some cases it may be necessary to add to the font knowledge of MathFlow MathFlow can use a configuration text file called FontInfo.ini. By placing this file into the same directory as the DLL, it will automatically try to use this file when the DLL is loaded. This section is dedicated to explaining how to use this feature. Using the techniques shown here, a user can assign a character set (encoding) to a font, create a new encoding, and define the PostScript font name to be used in EPS file generation.

MathFlow contains knowledge of the fonts and characters it works with, which results in improved formatting and translation into EPS. Most of this knowledge is in the form of tables built into the code. However, this information can be extended via the FontInfo.ini file external to the program, allowing it to be expanded and corrected without having to change the application itself.

Encodings

An encoding is a one-to-one correspondence between character meanings and integers. For example, ASCII is an encoding mapping characters onto numbers between 0 and 127 and "a" is assigned the number 97. Fonts are said to use or have a specific encoding. The font's encoding determines what character gets displayed when we pass a given number to the operating system. Note character style and shape plays no part in the encoding concept — A Times-Roman "a" has the same value as a Bookman-Italic "a" (assuming the fonts use the same encoding). A code-point is a particular value in an encoding. For example, "a" has the code-point 97 in the ASCII encoding.

The MTCode encoding

Central to our font information is the MTCode encoding. MTCode assigns a 16-bit constant to every different character our software works with. It is superset of Unicode, a standard encoding attempting to assign a unique number with each of the characters used in the world's languages. Unicode covers a lot of math, but not all the math characters we need. For this reason, MTCode uses Unicode's Private Use Area (PUA), a range of 6400 code points (0xE000 to 0xF8FF) for its additional math characters. We use MTCode values as the key to all of the per-character information — human-readable character descriptions, token types (variable, operator, etc.).

For more information on Unicode, see the Unicode Consortium. To find out about how we use the Unicode's Private Use Area, see the MTCode Encoding Tables.

Font encodings

Every font is the expression of some character set. In fact, many fonts share the same character set. We use the term "font encoding" to represent a character set that might be shared by one or more fonts. Many applications (e.g. word processors) don't have to know a font's encoding — the user hits a key, a code is sent to the application, the code is sent back to the operating system to select a character from a font for display. Our software needs to know more.

A font encoding can be thought of as a table with two columns, the position within the font (a numerical index) and an MTCode code point value (the number from our own master character list, MTCode, uniquely identifying the character). We give each font encoding a name (e.g. WindowsANSI, MacStd, Symbol). Many encodings are named after the single font whose encoding it is. Many fonts share the same encoding. For example, standard ISO Latin-1 fonts on Windows all have the WindowsANSI encoding.

Our software represents every encoding other than MTCode as a mapping onto MTCode. That is, for every code-point in a given encoding it indicates a unique MTCode code-point. Using this mapping, we can get at all the per-character information for any code-point in the encoding and, therefore, for any character in fonts with that encoding. For this reason, knowing a font's encoding is very important.

Unfortunately, the computer's operating system tells us very little about the encodings of fonts, least of all for those containing math symbols. So, we have to keep our own knowledge of which encoding each font has. Of course, as people can create their own fonts, the set of font encodings is open-ended.

Extension scenarios

Font information may be extended in the following ways:

Determining what MathFlow knows

Since the font information extension mechanism we are talking about also applies to MathType, it can be very useful to do the setup with MathType first to verify the proper syntax has been used in the configuration file. When the file is finished, you can then copy the file and place it in the same directory as the DLL.

If you have a font installed on your computer our software does not seem to know anything about, the first thing to do is to verify this is the case. The easiest way to do this is via MathType's Insert Symbol dialog. Follow these steps:

If the encoding name is "Unknown", it means our database of fonts and characters has no information for that font.

Defining the encoding for a font falls into two cases:

Once you have decided to assign an encoding to a font, the next step is to determine if its character set matches that of a font for which our software already has an encoding. This is easy if you designed your own font as a perfect substitute for another font that our software already knows about. For example, if you created your own version of the Symbol font, its encoding would be the same as the Symbol font's — "Symbol". If you aren't in this lucky situation, you'll have to work a bit harder. There are a couple of ways to do this:

If you have access to the Internet, you can view our font encoding tables and try to find an exact match in terms of characters and their positions in the font. It would help if you display the font in question in MathType 7 Insert Symbol dialog, as described in the previous section.

Display the font in question in Window's Character Map utility. Use MathFlow's Insert Symbol dialog to view other math fonts on your system, looking for an exact match in terms of characters and their positions in the font. If you find a match, write down the encoding name for the font.

If you found an encoding that matches your new font, you have to tell MathFlow about it by adding to the Fonts section of FontInfo.ini. See The FontInfo.ini file and Font Sections for details. If you assign an encoding to a font, you should consider letting our tech support department know so we can add it to the built-in font knowledge of the next version of our software. Just send an email to support@wiris.com and mention the font name and the encoding name (please be precise). If you can, send us a copy of the font and any other information associated with it. If it is a commercially available font, let us know who makes it.

As stated earlier, our software produces Encapsulated PostScript (EPS) files. These must refer to fonts using the PostScript names of fonts, not their operating system name (the font names listed in MathType 7 and other applications' dialogs and menus. So, for example, "Times New Roman" must be referred to as "Times-Roman" in an EPS file. Unfortunately, this is another piece of information that the operating system doesn't give up easily.

Our software can generally communicate with the operating system to get the PostScript name for any PostScript font. Names obtained this way are the correct ones for use in an EPS file. For TrueType fonts used both for the screen and printing, our software can often, but not always, obtain the PostScript name from the TrueType font. In order to handle exception cases, however, you can set the PostScript name for a font by adding to the Fonts section of FontInfo.ini. See The FontInfo.ini file and Font sections for details.

Creating a new font encoding is easy, but a bit tedious. Font encodings are defined using a text file that is placed in the same directory as the MathFlow DLL. For an example of what this file should look like, see Font encoding example.

The filename should follow these rules:

FontEncoding, 1.0, Byte, Symbol

Your encoding file's first line must start with exactly "FontEncoding, 1.0", which identifies this file as a font encoding file whose version number is 1.0. The rest of the line consists of either Byte or Word. This means that the MTCode value will be either two or four hexadecimal characters. For example, if you use Byte, then a MTCode value is expressed as "AE" (without the quotes). If you use Word, then that same number must be expressed as "00AE". The last part of this line is the name of your encoding. So for example, instead of "Symbol" you should use the name of your encoding (which is also what the name of the file should be, followed by .enc). The name of an encoding should be alphanumeric characters without any spaces or punctuation and starting with a letter (e.g. DatapageMath3).

Any blank lines are ignored. Any line that starts with # is a comment. For example:

# Purpose: Symbol font encoding

The rest of the file must contain lines that define the characters in the encoding. For example,

28,226E,NOT LESS-THAN

The three fields are (from left to right):

Although we have attempted to put every character into the MTCode encoding that is in common use by mathematicians and scientists, this is a goal that we can approach but never reach. In the process of creating a new encoding, if you come across characters that are not in MTCode (i.e. not in the Unicode specification or in the MTCode Encoding Tables), you have two choices:

We will assign a new MTCode value to the character and tell you how to proceed from there.

This file will be in Windows initialization file format and consist of:

For each font for which additional information (i.e. PostScript name and/or encoding) is to be specified, the FontInfo.ini file must include a [Font<num>] section (<num> is simply an integer to make the section names unique; e.g. Font1, Font2). Each such section may contain one or more key/value pairs, of which, only the OSName key is required to identify the font whose attributes are being overridden. Any omitted keys will cause the corresponding value to be determined in the default manner described in the earlier sections of this document.

Name = <operating system font name>

Identifies the font being described by the other keys in the section. The <operating system font name> value is the name of the font as it appears in MathFlow style dialog. This key is required.

Encoding = <encoding name>

Identifies the encoding of the font. The <encoding name> value must be the name of a built-in encoding or one defined in the [Encoding] section (see below for details).

PSName<num> = <style> , <PostScript name>

Where <num> is simply an integer, to make the key names unique (e.g. PSName1, PSName2). The <style> value must be P for plain, B for bold, I for italic, or BI for bold-italic. The <PostScript name> is the name to be used in the EPS file.

The Encoding section

Contains lines of the form:

indent> <encoding name> = <encoding definition file></WRAP>

where <encoding name> defines an encoding (or overrides a built-in encoding) using the data in the file referred to by <encoding definition file>. This file, whose extension is .enc, must exist and the encoding name in this line must match that stored in the file.

The MTCode section

It is unlikely that you will need to use this section. However the information about this section is provided for completeness. This section contains lines of the form:

indent> <MTCode value in hex> = <token type>,<default style>,<description></WRAP>

where <token type> is NONE, NUM, VAR, FUNC, OPER, BINOP, RELOP, OPEN, CLOSE, FENCE, PUNCT, INNER, CTRL, or SPACE.

where <default style> is NONE, TEXT, FUNCTION, VARIABLE, LCGREEK, UCGREEK, SYMBOL, VECTOR, NUMBER, USER1, USER2, MTEXTRA, or TEXT_FE. (This is only used by MathFlow

where <description> is a human-readable description for a given character.

////////////////////////////////////////////////
INFIX
////////////////////////////////////////////////
default, 17, 17
minus, 33, 33
plus, 33, 33
sum, 33, 33, moveablelimits=false
////////////////////////////////////////////////
PREFIX
////////////////////////////////////////////////
default, 17, 17
plus, 3em, 5
sum, 33, 33, moveablelimits=false
////////////////////////////////////////////////
POSTFIX
////////////////////////////////////////////////
plus, 5u, 3em
sum, 33, 33, moveablelimits=true

This mfopdict.txt file changes the default spacing of all INFIX and PREFIX operators to 0.17em on both sides, but uses MathFlow default values for postfix operators. The INFIX minus operator has different spacing (0.33em on both sides), and the same is true for the INFIX plus and sum operators. The INFIX sum operator also has the moveablelimits property set to false. In the prefix table, the PREFIX plus gets a larger left space (3em) and a smaller right space (0.05em). Lastly, the sum operator will have moveablelimits when used as a POSTFIX operator.