INTRODUCTION
============

  Mathtex is a parser/rendering framework for LaTeX math expressions.
  It can be used either as a library or standalone through a command
  line utility. The code is based off of that developed by the
  matplotlib project.

  To compile and install mathtex please follow the instructions in
  INSTALL.

USING MATHTEX
=============

  COMMAND LINE

  The simplest way to use mathtex is via the command line utility in
  util/mathtext. It provides access to most of the functionality of
  mathtex.

  Example

    $ ./mathtext test.png "\$x + \frac{y}{2}\$"

  this will produce a file called test.png in the current directory.
  There are several things worth noting: firstly the use of $...$ to
  denote math. Anything outside of $...$ will be treated as regular
  text. Secondly the need to escape $ when entering them on the command
  line.

  An easier way of passing the expression is by using stdin.

  Example

    $ ./mathtext test.png
    $x + \frac{y}{2}$

  If no expression is provided through the command line arguments then
  mathtext will attempt to read one from stdin.

  The file-format is auto detected based off of the provided filename.
  While the Image backend only supports PNG (.png) the Cairo backend
  supports SVG (.svg), PDF (.pdf) and PS (.ps). Should the Cairo
  backend have been compiled without support for a desired format, or
  not be available at all then an error will be raised.

  PYTHON

  Mathtex is also easy to use through Python.

  Example

    >>> from mathtex.mathtex_main import Mathtex
    >>> Mathtex("$x+y=z$", 'stix', 14, 100).save('test.pdf')

  This will render the expression x+y=z using the STIX fonts at 14pt
  with a resolution of 100dpi and then save it as test.pdf.

FONT SUPPORT
============

  Mathtex comes with built-in support for the Bakoma (Computer modern)
  and STIX fonts. The required .ttf files are bundled with mathtex.
  There is also experimental support for using unicode fonts.

  The use of unicode fonts is slightly more complicated than using
  either Bakoma or STIX. On the command line it is done as follows:

  $ ./mathtext test.png -f unicode -u "rm=times new roman,sf=arial"

  rm, sf, ..., map to the font used by the corresponding LaTeX command.
  rm = \rm, sf = \sf and so on. The font can be any TrueType (.ttf)
  font installed on the system.

  Using the mathtex API unicode font support is provided by the
  UnicodeFonts class from the mathtex.fonts module.

  In order to improve performance a font-cache is used. This is
  automatically generated the first time mathtex is run. By default
  it is stored in ~/.mathtex. It may take several seconds to generate.

  If new fonts are installed on the system the cache will need to be
  updated. The easiest way to do this is to delete ~/.mathtex.

UNIT/REGRESSION TESTS
=====================

  Mathtex ships with a regression testing utility. It is currently
  under heavy development and subject to change. Currently it works by
  hashing the raw RGBA data generated by the Image backend and
  comparing it to a hash-file that is distributed with mathtex.

  Although mostly functional there are some known issues

    1) Different FreeType versions generate different RGBA data for
       the same expression. This results in test failures even when
       the image is acceptable.
    2) Not all tests render correctly using the STIX fonts. This is a
       known bug and will be fixed in future releases :)

  Running python tests.py --help will provide information about some of
  the more advanced testing functionality.