Up-Conversion Usage

Getting Started

  • In order to use the up-conversion features, you will have to download the full distribution of SnuggleTeX.
  • You must have snuggletex-core.jar and snuggletex-upconversion.jar in your runtime ClassPath, as well as saxon9.jar and saxon9-dom.jar. (The JARs in the distributon ZIP file contain version numbers in their names; it should be obvious what we mean here!)

Example

Have a look at the source code for BasicUpConversionExample.java  to see how to invoke the up-conversion process.

The key to invoking the up-conversion process is by attaching an UpConvertingPostProcessor into the SnuggleTeX DOM-building process using the addDOMPostProcessor() method of your DOMOutputOptions, XMLStringOutputOptions.

Additionally, if you want to use any of the special LaTeX up-conversion commands added in SnuggleTeX 1.2.0, such as \assumeSymbol and \setUpConversionOption, then you must also register the appropriate SnugglePackage with your SnuggleEngine as follows: 

SnuggleEngine engine = new SnuggleEngine();
engine.addPackage(UpConversionPackageDefinitions.getPackage());

Extracting Information from Resulting MathML

The up-conversion process replaces each raw MathML <math/> element with an annotated element housing all of the resulting output forms together. In the case of the above example, the resulting MathML is: 

<math xmlns="http://www.w3.org/1998/Math/MathML" display="block">
   <semantics>
      <mfrac>
         ...
      </mfrac>
      <annotation-xml encoding="MathML-Content">
         <apply>
            <divide/>
            ...
         </apply>
      </annotation-xml>
      <annotation encoding="Maxima">((2 * x) - (y^2)) / sin((x * y * (x - 2)))</annotation>
   </semantics>
</math>

The SnuggleTeX utility class MathMLUtilities  includes some useful helper methods for extracting individual parts of the MathML. Here are some examples:

  • extractAnnotationXML(element, "MathML-Content") will extract the content of the named <annotation-xml/> element, in this case giving you an Element of the form: 
    <apply>
   <divide/>
   ...
</apply>
  • You can use isolateAnnotationXML(element, "MathML-Content") to do the same thing, but wrapping the result in a <math/> having the same attributes as the original one, giving: 
    <math xmlns="http://www.w3.org/1998/Math/MathML" display="block">
  <apply>
     <divide/>
     ...
  </apply>
</math>
  • Use extractAnnotationString(element, "Maxima") to get the Maxima input annotation. This would give you: 
    ((2 * x) - (y^2)) / sin((x * y * (x - 2)))
  • The unwrapParallelMathMLDOM() method returns a simple Object with all of the annotations extracted that can be easily interrogated.
  • MathMLUtilities  has some convenience methods for serialising MathML Elements and Documents as XML Strings, that can be useful for debugging or documentation purposes.