QMath is a batch processor that produces an OMDoc file from a plain Unicode
text document. In this aspect, its usage resembles TeX.

The "Q" was intended to mean "quick", since QMath begun in 1998 as an
abbreviated notation for MathML. The first version (0.1) just expanded the
abbreviations to full MathML element names, and added the extra markup such
as "<mrow>" and the like.

There have been many changes (and two complete rewrites) since then. You
can find a more detailed history at http://www.matracas.org/qmath/history.html

QMath is very simple in its design: it just parses a text (UTF-8) file
according to a user-definable table of symbols, and builds an XML document
from that.

The symbol definitions are grouped in files called "contexts". The idea is
that when you "declare" a context, its file is loaded and from then on
these symbol definitions take precedence over any previous one, thus
setting the context for parsing of subsequent expressions.

The text is split into "paragraphs", which are pieces of text separated by
at least one void line.

Each paragraph can have a metadata section at the beginning. There are a
variety of classes of paragraphs, wich are identified by a name followed by
a colon (":"), optionally followed by an identifier which becomes the "id"
attribute of the generated OMDoc element.

Inside the text, a mathematical expression is enclosed in dollar ("$") signs.
Each such a section becomes an OMOBJ in the output document.


A minimal document looks like this:

---------------------------------------------------

QMATH 0.3.9
:"Diary"
:Winston Smith
:1984-04-04
:en

Context: "Mathematics/Arithmetic"

:"Down with Big Brother"
Freedom is the freedom to say $2+2=4$. If that is granted, all else follows.

---------------------------------------------------

The first line ("QMATH 0.3.9") is required for the parser to recognize the
file.

The lines beginning with ":" are metadata items: first the document title,
then the author name (one line for each author), and finally the primary
language for the document. This last item is required, as it sets the basic
symbol set accordingly. For example, the "Context" item of an English
document is written "Contexto" if the document is in Spanish. (Similarly,
the arithmetic context would be "Matemticas/Aritmtica")

The document is split into paragraphs, which are separated by void lines.
Then, mathematical expressions are written enclosed by "$" (dollar) signs.

The "QMath" command works as a pure filter: reads the document from standard
input, and writes the resulting OMDoc in standard output. So, the typical
usage is "QMath <document.qmath >document.omdoc".

It needs to know where to find the "contexts/" directory. For that, the
"./configure" script sets the default QMATH_HOME value to the compilation
path, so that you can test it immediately after compiling, without having
to install anything.
If you want to install it in some other place, you can use the "--prefix"
option of "./configure".
Another way to specify the home directory of QMath is to set the
"QMATH_HOME" environment variable.

To get it running and test it, the following sequence is all you need:

./configure
make
bin/QMath <examples/example.qmath >examples/example.omdoc

This will put the result OMDoc file in the "examples/" directory.
