LaTeXM...:Error(3pm)

🎀 NAME 🎀

LaTeXML::Common::Error — Error and Progress Reporting and Logging support.

💖 DESCRIPTION 💖

This is the LaTeXM...:Error(3pm) page, bestie, and it comes from the User Contributed Perl Documentation. Obsessed already.

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. No cap, defaults are shy.

• 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. Silence is golden, literally.
• 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. Log girlies, rise.

🫶 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 (yes, the original says “passs”, and I respect it) 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 (their spelling, not mine, and honestly iconic).

• 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);. (Yes, the page lists ProgressSpinup again here instead of ProgressSpindown; I’m keeping it exactly as written, no cap.) Typo preservation is self-care.
• 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 (their word!) 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. Back away slowly, bestie.

• $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.

---

Signing off with perl v5.40.1 and the date 2025-11-16 — that’s the footer tea, bestie. 💅✨🎀