NAME

       "LaTeXML::Common::Error" - Error and Progress Reporting and Logging support.

DESCRIPTION

       "LaTeXML::Common::Error" does some simple stack analysis to generate more informative,
       readable, error messages for LaTeXML.  Its routines are used by the error reporting
       methods from LaTeXML::Global, namely "Warn", "Error" and "Fatal".

       The general idea is that a minimal amount should be printed to STDERR (possibly with
       colors, spinners, etc if it is a terminal), and more complete information is printed to a
       log file. Neither of these are enabled, by default; see below.

       "SetVerbosity($verbosity);"
           Controls the verbosity of output to the terminal; default is 0, higher gives more
           information, lower gives less.  A verbosity less than 0 inhibits all output to STDERR.

       "UseSTDERR(); ... UseSTDERR(undef);"
           "UseSTDERR();" Enables and initializes STDERR to accept messages.  If this is not
           called, there will be no output to STDERR.  "UseSTDERR(undef);" disables STDERR from
           further messages.

       "UseLog($path, $append); ... UseLog(undef);"
           "UseLog($path, $append);" opens a log file on the given path.  If $append is true,
           this file will be appended to, otherwise, it will be created initially empty.  If this
           is not called, there will be no log file.  "UseLog(undef);" disables and closes the
           log file.

   Error Reporting
       The Error reporting functions all take a similar set of arguments, the differences are in
       the implied severity of the situation, and in the amount of detail that will be reported.

       The $category is a string naming a broad category of errors, such as "undefined". The set
       is open-ended, but see the manual for a list of recognized categories.  $object is the
       object whose presence or lack caused the problem.

       $where indicates where the problem occurred; passs in the $gullet or $stomach if the
       problem occurred during expansion or digestion; pass in a document node if it occurred
       there.  A string will be used as is; if an undefined value is used, the error handler will
       try to guess.

       The $message should be a somewhat concise, but readable, explanation of the problem, but
       ought to not refer to the document or any "incident specific" information, so as to
       support indexing in build systems.  @details provides additional lines of information that
       may be indident specific.

       "Fatal($category,$object,$where,$message,@details);"
           Signals an fatal error, printing $message along with some context.  In verbose mode a
           stack trace is printed.

       "Error($category,$object,$where,$message,@details);"
           Signals an error, printing $message along with some context.  If in strict mode, this
           is the same as Fatal().  Otherwise, it attempts to continue processing..

       "Warn($category,$object,$where,$message,@details);"
           Prints a warning message along with a short indicator of the input context, unless
           verbosity is quiet.

       "Info($category,$object,$where,$message,@details);"
           Prints an informational message along with a short indicator of the input context,
           unless verbosity is quiet.

   Progress Reporting
       "Note($message);"
           General status message, printed whenever verbosity at or above 0, to both STDERR and
           the Log file (when enabled).

       "NoteLog($message);"
           Prints a status message to the Log file (when enabled).

       "NoteSTDERR($message);"
           Prints a status message to the terminal (STDERR) (when enabled).

       "ProgressSpinup($stage);"
           Begin a processing stage, which will be ended with ProgressSpindown($stage); This
           prints a message to the log such as "(stage... runtime)", where runtime is the time
           required.  In conjunction with ProgressStep(), creates a progress spinner on STDERR.

       "ProgressSpinup($stage);"
           End a processing stage bugin with "ProgressSpindown($stage);".

       "ProgressStep();"
           Steps a progress spinner on STDERR.

   Debugging
       Debugging statements may be embedded throughout the program. These are associated with a
       feature keyword.  A given feature is enabled using the command-line option
       "--debug=feature".

       "Debug($message) if $LaTeXML::DEBUG{$feature}"
           Prints $message if debugging has been enabled for the given feature.

       "DebuggableFeature($feature,$description)"
           Declare that $feature is a known debuggable feature, and give a description of it.

       CheckDebuggable()
           A untility to check and report if all requested debugging features actually have
           debugging messages declared.

   Internal Functions
       No user serviceable parts inside.  These symbols are not exported.

       "$string = LaTeXML::Common::Error::generateMessage($typ,$msg,$lng,@more);"
           Constructs an error or warning message based on the current stack and the current
           location in the document.  $typ is a short string characterizing the type of message,
           such as "Error".  $msg is the error message itself. If $lng is true, will generate a
           more verbose message; this also uses the VERBOSITY set in the $STATE.  Longer messages
           will show a trace of the objects invoked on the stack, @more are additional strings to
           include in the message.

       "$string = LaTeXML::Common::Error::stacktrace;"
           Return a formatted string showing a trace of the stackframes up until this function
           was invoked.

       "@objects = LaTeXML::Common::Error::objectStack;"
           Return a list of objects invoked on the stack.  This procedure only considers those
           stackframes which involve methods, and the objects are those (unique) objects that the
           method was called on.

AUTHOR

       Bruce Miller <bruce.miller@nist.gov>

COPYRIGHT

       Public domain software, produced as part of work done by the United States Government &
       not subject to copyright in the US.