module Blahcaml:`sig`

..`end`

The

`Blahcaml`

module defines functions for the conversion of TeX equations
into MathML. Important note: all the strings used in this module are assumed
to be encoded in UTF-8. Use Camomile if
you want to process the string's characters.`exception Blahtex_error of ``string`

Exception raised when the Blahtex core routines encounter an error parsing
the TeX equation.

`exception Unicode_error`

Exception raised when an error occurs during the conversion to/from UTF8
(if the string containing the TeX equation is not valid UTF8, for example).

`exception Invalid_root`

Exception raised when even though a fragment conforms to the MathML DTD,
the top-level element is not

`math`

.`val init_dtd : ``unit -> unit`

Performs a manual initialisation of the MathML2 DTD. The DTD must be
initialised before any of the safety-related functions are invoked
(these functions are

`Blahcaml.sanitize_mathml`

and `Blahcaml.safe_mathml_from_tex`

).
Note that this function is automatically called if the DTD has never
been initialised and you invoke one of the safety-related functions.
Therefore, even though there is no obligation to manually invoke this
function, because the initialisation can take several seconds to complete,
if you want predictability on the runtime performance of your application
you should invoke this function upon initialisation. Note also that this
function simply calls the low-level function `Mathml2dtd.init`

; therefore,
if you are already doing a low-level initialisation you will not need to
do it again by invoking this function.`val sanitize_mathml : ``?with_xmlns:bool -> string -> string`

Given a string containing potentially unsafe MathML, this function makes sure
the it conforms to the MathML2 DTD. If safe, the function returns the original
string. If, however, the string does not conform to the DTD, a PXP exception
is raised (please see the PXP
documentation for the meaning of these exceptions). If the optional boolean
parameter

`with_xmlns`

is true, this function will add the standard MathML
namespace to the top-level `math`

element. Note that if the DTD has never
been initialised, this function will automatically do so upon its first
invocation (see `Blahcaml.init_dtd`

for more information).`val unsafe_mathml_from_tex : ``?with_xmlns:bool -> string -> string`

Converts a string containing an equation in TeX format into another string
containing the same equation in MathML. No checking is done to make sure
the result conforms to the MathML2 DTD! If that assurance is required
please use the

`Blahcaml.safe_mathml_from_tex`

. If the optional boolean parameter
`with_xmlns`

is true, this function will add the standard MathML namespace
to the top-level `math`

element. Should the Blahtex core routines detect
an error in the TeX equation, an exception of either `Blahcaml.Blahtex_error`

or
`Blahcaml.Unicode_error`

will be raised.`val safe_mathml_from_tex : ``?with_xmlns:bool -> string -> string`

Converts a string containing an equation in TeX format into another string
containing the same equation in MathML. If the optional boolean parameter

`with_xmlns`

is true, this function will add the standard MathML namespace
to the top-level `math`

element. For added security, before being returned
the result value of this function is checked to make sure it indeed conforms
to the MathML2 DTD. If it does not, a PXP exception is raised (please consult
the PXP documentation for
the meaning of these exceptions). Also, should the Blahtex core routines
detect an error in the TeX equation, an exception of either `Blahcaml.Blahtex_error`

or `Blahcaml.Unicode_error`

will be raised. Note that if the DTD has never been
initialised, this function will automatically do so upon its first invocation
(see `Blahcaml.init_dtd`

for more information).
**Disclaimer:** There is presently no evidence supporting the assumption that
the output from the Blahtex library is untrustworthy security-wise. Therefore,
if you trust Blahtex with 100% certainty, then you may disregard this function
and use `Blahcaml.unsafe_mathml_from_tex`

instead. Nevertheless, given the complexity
of Blahtex's task and the size of its code, caution dictates invoking this
function *just in case*.