SnuggleTeX 1.1.0 to 1.2.0 migration guide

snuggletex-core module

There have been a small number of necessary API changes made in this module, though they are fairly small and most users will not be affected by this.

  • The DefinitionMap class has been refitted into the newer and more useful SnugglePackage, which also allows you to register your own custom ErrorCodes and provide a standard Java ResourceBundle for formatting error messages. You add a SnugglePackage to your SnuggleEngine with the new addPackage() method, which replaces registerDefinitions().
  • The ErrorCode enumeration has been replaced by an interface, and two implementations. The first implementation CoreErrorCode defines all of the error codes for the snuggletex-core module. The second defines all of the error messages for the snuggletex-upconversion module. This all fits into the new SnugglePackage model and makes error code registration much more modular.
  • There is a new ErrorGroup interface for grouping ErrorCodes into logic groups. This is used mainly for documentation purposes. If you have been creating your own ErrorCodes, then you will need to fit this in.
  • The DOMOutputOptions class has been tidied up by adding in a subclass called XMLStringOutputOptions that now houses properties relating to XML String outputs, with a few new features such as the ability to output named entities for mathematical symbols instead of numeric character references.
  • The SerializationMethod inner enumeration class is now a top level enumeration class.
  • The getDefaultDOMOptions and setDefaultDOMOptions methods in SnuggleEngine have been renamed as getDefaultDOMOutputOptions and setDefaultDOMOutputOptions for consistency. The old method named will still work for the time being but are deprecated for removal in 1.3.0.
  • SnuggleSession now includes methods for generating XML String outputs that take a XMLStringOutputOptions. Older methods that took a DOMOutputOptions and a number of additional parameters have been marked as deprecated and will be removed in 1.3.0. Please update your code to use this (nicer) new approach.
  • The addingMathAnnotations property of DOMOutputOptions has been renamed as addingMathSourceAnnotations, which is more expliclt. Accessors for the old version of this property have been kept but marked as deprecated and will be removed for the 1.3.0 release. Please update your code accordingly.
  • The SNUGGLETEX_MATHML_ANNOTATION_ENCODING constant in SnuggleConstants has been renamed as SNUGGLETEX_MATHML_SOURCE_ANNOTATION_ENCODING. The old constant has been kept around but marked as deprecated and will be removed in the 1.3.0 release.
  • The MathMLUtilities utility class has been improved with serialization methods the allow you to pass a SerializationOptions instance specifying exactly how you want the results to be serialized. Some of the existing overloaded methods doing much the same thing have been deprecated as a result, and will be removed in 1.3.0. Use the new methods when possible!
  • Moved W3C-related constants into a W3CConstants interface. Their old locations in the internal Globals class have been marked as deprecated and will be removed for the 1.3.0 release.
  • The Token class representing a parsed LaTeX token may now have more than one Interpretation associated with it. This has allowed some of the existing classes in the Interpretation hierarchy to be simplified as they no longer have to rely on multiple inheritance. This change should only affect people who have been writing their own CommandHandlers and EnvironmentHandlers that hook into existing concepts.
  • The BuiltinCommandOrEnvironment base class has changed to accommodate allowing Tokens to have multiple Interpretations. This will affect you if you have been defining your own BuiltinCommands or BuiltinEnvironments that make use of this feature. Interpretation information is now stored in an EnumMap.
  • The StylesheetManager class has been refactored and improved and some of the functionality previously provided by the internal XMLUtilities class has been moved here. Most users will not be using either of these.
  • Added the TransformerFactoryChooser interface and 2 implementations (one using JAXP, one hard-coded to use Saxon) that you may want to use or think about using should you ever use a StylesheetManager.

snuggletex-jeuclid module

The 1.2.0 full distribution ships with a newer version of JEuclid that fixes problems previously noticed. Aside from a couple of API improvements, code compiled against the 1.1.0 version of this module should work fine in 1.2.0.

snuggletex-upconversion module

This work is still experimental so the API should be considered somewhat unstable until further notice.

  • The old UpConversionParameters constants are replaced by the UpConversionOptions and UpConversionOptionDefinitions idea, which allows both Java and LaTeX-based control over the process, and facilities the new "assumptions" ideas in 1.2.0.
  • Some changes to the API of MahMLUpConverter have been changed to accommodate the above.
  • You now have to register the up-conversion SnugglePackage with your SnuggleEngine if you want to use any of the commands added in 1.2.0. See the example classes for a guide. (As there were no up-conversion LaTeX commands in 1.1.0, this will not be an issue!)