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.

perl v5.38.2                                       2024-02-27                        LaTeXML::Common::Error(3pm)