GtkMathView Questions & Answers

General questions

Does GtkMathView require GTK+?

No. You can compile GtkMathView without GTK+ and also without X.

Does GtkMathView do editing as well as rendering?

As the name says, GtkMathView only provides a view for a MathML document. Its API does not contain any method for changing the content of the MathML document being displayed. However, GtkMathView does support incremental rendering meaning that if the document changes GtkMathView finds out what is the smallest part of it that needs to be re-formatted when using the GMetaDOM frontend. When using other frontends that have no event notification mechanism, you can still notify GtkMathView explicitly about which parts should be re-formatted by means of the gtk_math_view_structure_changed and gtk_math_view_attribute_changed methods. In case you're using the C++ frontend, similar methods are also provided.

Which features of MathML are not supported by GtkMathView?
I think I've found a bug, where should I report it?

You can either post a report on the mailing list, or you can mail the author directly, or you can file a bug report on the bugzilla for GtkMathView (preferred).

When I render a document I get a funny question mark in a red diamond, what is it?

This usually happens in two cases:

If you want to specify a missing MathML element where one is expected, you can use an empty mrow element.

When I render a document I get a funny box with little numbers inside, what is it?

That means that you requested to render a Unicode character which GtkMathView is not capable of handling. Usually this happens if no font is found that has a glyph for that character.

What is a shaper?

A shaper is, within GtkMathView, a component that knows how to use a particular family of fonts, through a platform-dependent API, to render a set of Unicode characters. There cannot be a single shaper, as rendering math precisely is a delicate task that requires a deep knowledge of the fonts in a family, and of the very subtle ways the glyphs in these fonts can be combined together. Currently GtkMathView provides these shapers:

Can I control which shaper should handle a given Unicode character?

Currently you can assign a priority to each shaper so that when two shapers are capable of handling the same character, the shaper with higher priority "wins". At the moment it is not possible to specify this on a per-character basis, the smallest granularity is the shaper. In a future version it might be possible to disable the capability of rendering specific characters in specific shapers.

I'm trying to render a MathML document but all I get is a blank canvas. What's wrong?

Make sure that the MathML document is a well-formed XML document, that the root element is math and that all the MathML elements live in the MathML namespace http://www.w3.org/1998/Math/MathML.

I'm trying to render the MathML token <mi>x</mi> but GtkMathView displays a funny box with the numbers 1D44C. Isn't x U+0059?

The x is indeed U+0059 however the MathML specification states that an mi token element whose content is a single character has a default mathvariant="italic", which has the effect of mapping the characters in the element to the Unicode Mathematical Alphanumeric Symbols block. In particular, the x is mapped to U+1D44C. If no font is capable of rendering that particular Unicode character, you get the funny box.

Why does a parenthesis stretch more than is actually needed?

In many cases a stretched parenthesis is rendered by putting together several glyphs, each glyph providing a piece of the whole parenthesis. For instance, an open round parenthesis ( is usually provided in three pieces, the upper hook U+239B , the lower hook U+239D , and an extension U+239C . The parenthesis is stretched by combining an appropriate number of pieces, where the hooks are always present and the extension is repeated as needed. When symbols are stretched this way, their size does not vary continuously as the pieces are fixed-size glyphs. So, it may be the case that a parenthesis turns out to be over stretched with respect to the context where it is required to stretch. You can try using the minsize and maxsize attributes of the mo element to control the amount by which the symbol is stretched, or you can disable stretchying alltogether by setting stretchy="false".

What is the Operator Dictionary?

In MathML, mo elements have a large number of attributes affecting their rendering. The operator dictionary defines the default values of these attributes depending on the element's form, on the observation that in most cases the user will not need to change these values. The form of an mo element is either prefix, infix, or postfix depending on its position with respect to its parent element, and on its sibling (the exact definition can be found in the MathML specification).

How do I tell GtkMathView to load my own configuration file?

GtkMathView loads configuration files in this order:

Entries in the configuration file can be set multiple times, the last value set is the one found. Note that it is not necessary for a configuration file to be "complete". Simply, its entries will override the ones loaded from previous configuration files.

How do I specify an application-specific Operator Dictionary?

You can add the path of the operator dictionary you want to use as a path key in the dictionary section.

Compiling and linking issues

GtkMathView takes ages to compile, is it normal?

GtkMathView makes large use of C++ templates and GCC is known to be kind of slow to compile them. However, chances are that you don't need to compile every feature provided by GtkMathView, here are a few suggestions in decreasing order of effectiveness:

Compilation fails with the message undefined reference to `T1_GetNoFonts'.
This is due to a wrong version of the t1lib library (1.x instead of 5.y). You can
  1. upgrade t1lib, or
  2. disable t1lib at configuration time with the --with-t1lib=no option, or
  3. patch gtkmathview's source code to use the the old T1_Get_no_fonts instead of T1_GetNoFonts.

Gtk Backend

Where does GtkMathView sit in the GTK+ heirachy?

GtkMathView derives from GtkWidget directly.

Is the GtkMathView widget able to get GTK+ events?

Yes, you have to set the right flags and, for keyboard events, enable focus like this:

        gtk_widget_add_events(GTK_WIDGET(math_view), GDK_KEY_PRESS_MASK);
	GTK_WIDGET_SET_FLAGS(GTK_WIDGET(math_view), GTK_CAN_FOCUS);

Can I control which fonts GtkMathView uses with the Pango shaper?

You can specify the Pango Text Attributes to be used for mapping the various variants in the MathML specification. You can do so by specifying a variants section within the pango-default-shaper section:

      <section name="variants">
       <section name="normal">
         <key name="family">courier</key>
         <key name="style">normal</key>
         <key name="weight">bold</key>
       </section>
     </section>
This specifies that tokens rendered using the normal variant should look for a font family courier, using normal (i.e. up-right roman) style, and bold weight.

Can GtkMathView render a formula on a bitmap?

Yes, look at the viewer/test_rendering.cc example in the source tarball.

What is a document decoration?

A decoration is any additional drawing that occurs in the GtkMathView canvas and that is controlled by code provided by the user. Whenever GtkMathView renders the document on the canvas, it emits two signals: decorate_under is emitted just before the document is rendered, and is thus suitable for drawing decorations that lay underneath the document, whereas decorate_over is emitted just after the document is rendered, and is thus suitable for drawing decorations that lay on top of the document.

BoxML

What is BoxML?

BoxML is a low-level markup language where layout is controlled by different kinds of boxes. Horizontal H and vertical V boxes have fixed layout. Horizontal/Vertical HV boxes implement consistent linebreaking (render the content either as a horizontal box as a vertical box depending on the amount of space available). Horizontal or Vertical HOV boxes implement inconsistent linebreaking (the content is broken only when needed, but not necessarily at every break point).

BoxML is meant to be an experimental feature of GtkMathView: first of all it shows how GtkMathView's architecture supports the mutual embedding of different markup languages. Second, the layout algorithms developed for BoxML should provide feedback on how to implement automatic linebreaking of long formulas in MathML.

TeX Fonts

I have installed GtkMathView and mathmlviewer does seem to work correctly, however it does not use TeX fonts. What's wrong?

By default Computer Modern fonts are not enabled because not every system has them. Here are the instructions for enabling Computer Modern fonts with the GTK+ backend under the Debian system:

  1. Download the True Type version of Computer Modern fonts and copy them in the ~/.fonts directory
  2. either modify the system-wide GtkMathView configuration file or create a new one so that the gtk-backend/pango-computer-modern-shaper is enabled
  3. in the fonts/computer-modern section uncomment the fonts that you have installed and that you want to use. If you want to use TFMs, make sure that the set of uncommented fonts is included in the TFM support level specified at configuration time (TFM level 1 includes the minimal set, TFM level 2, which is the default, includes the normal set, and TFM level 3 includes the full set).
  4. now you're ready to render MathML documents using Computer Modern fonts
What is post-shaping?

Post shaping enables support for kerning and ligatures for fonts that support them. These features take place after a shaper has found the glyphs for rendering a particular Unicode character and this is why the mechanism is called post-shaping. Post-shaping is controlled by the post-shaping entry in the configuration file for those shapers that support it.

What are TFMs?

TeX Font Metrics are binary files containing detailed information about TeX Fonts (in fact, more detailed information than is usually available from fonts). Their purpose is to provide a formatting engine with all the necessary information for rendering and combining glyphs with the highest possible precision, and to define a set of parameters that should be considered when using these glyphs. In order to avoid further dependencies on externa libraries, GtkMathView can be configured so as to embed TFM data in the generated binaries. These data takes some space, of course, so a user may configure the amount of TFM data to be embedded by means of the --enable-tfm option at configuration time. The user can specify 4 values ranging from 0 (no TFM data) to 3 (full TFM data). A setting of 1 will include only the minimal TFM data for using the main Computer Modern fonts. A setting of 1 will include TFM data for all Computer Modern fonts at 10 points. A setting of 3 will include TFM data for all Computer Modern fonts at all sizes. TFM data is required for post-shaping to work correctly.