Error Reporting

There are three classes of Errors that can be encountered when using SnuggleTeX:

  • Input LaTeX Errors: Any errors detected in the input LaTeX can be detected and recorded in a number of ways, as described below. You will want to act on these errors, usually by passing back to whomever supplied the input LaTeX to help them correct their input.
  • Runtime Errors: Any problems detected due to a mis-configuration or mis-deployment fall into this category. (E.g. if SnuggleTeX can’t locate an extension Class, can’t find one of its XSLT stylesheets or properties files or you attempt to use a feature requiring an XSLT 2.0 processor when one is not available.) They are raised as (unchecked) SnuggleRuntimeExceptions. Your application normally won’t want (or indeed be able) to deal with these — they normally indicate you need to fix your ClassPath or something similar.
  • Logic Errors: If SnuggleTeX detects something unexpected in its internal logic, then it will throw an (unchecked) SnuggleLogicException. You should not normally see one of these in the wild — please file a bug report if you do! SnuggleTeX has a test suite that aims to prevent these types of errors from happening.

Input LaTeX Errors

By default, a SnuggleSession keeps going whenever it detects bad or invalid LaTeX during parsing, in much the same way that LaTeX can often continue running. (Obviously, the results you get from after the point the error occurred may not be particularly useful.)

It is also possible to tell SnuggleTeX to “fail fast” and stop on the first error encountered with: 

snuggleSession.getConfiguration().setFailingFast(true)

In this case, snuggleSession.parseInput() returns false if parsing was terminated by an error and true if parsing was completed successfully for a given Input.

You can call:

snuggleSession.getErrors();

at any time to get a List of InputError Objects representing each LaTeX error detected by the SnuggleSession so far.

NOTE: Further errors can be recorded during the SnuggleTeX output processes so you should check errors after generating an output as well!

SnuggleTeX error messages are considerably different from what you might be used to in LaTeX. They are encapsulated as InputError Objects. Each has an error code; these are all enumerated in the ErrorCode enumeration class and listed on the SnuggleTeX Error Codes page here. SnuggleTeX is also reasonably good at resolving errors that manifest themselves once user-defined commands and environments have been evaluated.

The MessageFormatter class has some convenience methods for nicely formatting these error messages in various ways.

It is also possible to "inline" errors into the resulting XML outputs by calling the setErrorOutputOptions(...) on a DOMOutputOptions or WebPageOutputOptions Object.