.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "LaTeXML::Common::Error 3pm"
.TH LaTeXML::Common::Error 3pm "2014-02-05" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
"LaTeXML::Common::Error" \- Error and Progress Reporting and Logging support.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`LaTeXML::Common::Error\*(C'\fR 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 \f(CW\*(C`Warn\*(C'\fR, \f(CW\*(C`Error\*(C'\fR and \f(CW\*(C`Fatal\*(C'\fR.
.SS "Error Reporting"
.IX Subsection "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.
.PP
The \f(CW$category\fR is a string naming a broad category of errors,
such as \*(L"undefined\*(R". The set is open-ended, but see the manual
for a list of recognized categories.  \f(CW$object\fR is the object
whose presence or lack caused the problem.
.PP
\&\f(CW$where\fR indicates where the problem occurred; passs in
the \f(CW$gullet\fR or \f(CW$stomach\fR 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.
.PP
The \f(CW$message\fR should be a somewhat concise, but readable,
explanation of the problem, but ought to not refer to the
document or any \*(L"incident specific\*(R" information, so as to
support indexing in build systems.  \f(CW@details\fR provides
additional lines of information that may be indident specific.
.ie n .IP """Fatal($category,$object,$where,$message,@details);""" 4
.el .IP "\f(CWFatal($category,$object,$where,$message,@details);\fR" 4
.IX Item "Fatal($category,$object,$where,$message,@details);"
Signals an fatal error, printing \f(CW$message\fR along with some context.
In verbose mode a stack trace is printed.
.ie n .IP """Error($category,$object,$where,$message,@details);""" 4
.el .IP "\f(CWError($category,$object,$where,$message,@details);\fR" 4
.IX Item "Error($category,$object,$where,$message,@details);"
Signals an error, printing \f(CW$message\fR along with some context.
If in strict mode, this is the same as \fIFatal()\fR.
Otherwise, it attempts to continue processing..
.ie n .IP """Warn($category,$object,$where,$message,@details);""" 4
.el .IP "\f(CWWarn($category,$object,$where,$message,@details);\fR" 4
.IX Item "Warn($category,$object,$where,$message,@details);"
Prints a warning message along with a short indicator of
the input context, unless verbosity is quiet.
.ie n .IP """Info($category,$object,$where,$message,@details);""" 4
.el .IP "\f(CWInfo($category,$object,$where,$message,@details);\fR" 4
.IX Item "Info($category,$object,$where,$message,@details);"
Prints an informational message along with a short indicator of
the input context, unless verbosity is quiet.
.ie n .IP """NoteProgress($message);""" 4
.el .IP "\f(CWNoteProgress($message);\fR" 4
.IX Item "NoteProgress($message);"
Prints \f(CW$message\fR unless the verbosity level below 0.
Typically just a short mark to indicate motion, but can be longer;
provide your own newlines, if needed.
.ie n .IP """NoteProgressDetailed($message);""" 4
.el .IP "\f(CWNoteProgressDetailed($message);\fR" 4
.IX Item "NoteProgressDetailed($message);"
Like \f(CW\*(C`NoteProgress\*(C'\fR, but for noiser progress, only prints when verbosity >= 1.
.SS "Internal Functions"
.IX Subsection "Internal Functions"
No user serviceable parts inside.  These symbols are not exported.
.ie n .IP """$string = LaTeXML::Common::Error::generateMessage($typ,$msg,$lng,@more);""" 4
.el .IP "\f(CW$string = LaTeXML::Common::Error::generateMessage($typ,$msg,$lng,@more);\fR" 4
.IX Item "$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.
\&\f(CW$typ\fR is a short string characterizing the type of message, such as \*(L"Error\*(R".  
\&\f(CW$msg\fR is the error message itself. If \f(CW$lng\fR is true, will generate a
more verbose message; this also uses the \s-1VERBOSITY\s0 set in the \f(CW$STATE\fR.
Longer messages will show a trace of the objects invoked on the stack,
\&\f(CW@more\fR are additional strings to include in the message.
.ie n .IP """$string = LaTeXML::Common::Error::stacktrace;""" 4
.el .IP "\f(CW$string = LaTeXML::Common::Error::stacktrace;\fR" 4
.IX Item "$string = LaTeXML::Common::Error::stacktrace;"
Return a formatted string showing a trace of the stackframes up until this
function was invoked.
.ie n .IP """@objects = LaTeXML::Common::Error::objectStack;""" 4
.el .IP "\f(CW@objects = LaTeXML::Common::Error::objectStack;\fR" 4
.IX Item "@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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Bruce Miller <bruce.miller@nist.gov>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Public domain software, produced as part of work done by the
United States Government & not subject to copyright in the \s-1US.\s0