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

       Bruce Miller <bruce.miller@nist.gov>

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

perl v5.40.1                                       2025-05-28                        LaTeXML::Common::Error(3pm)

       "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.

   ErrorReporting
       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.

   ProgressReporting
       "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.

   InternalFunctions
       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.

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