<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<META name="GENERATOR" content="hevea 1.10">
<META name="Author" content="Luc Maranget">
<LINK rel="stylesheet" type="text/css" href="manual.css">
<TITLE>How to detect and correct errors</TITLE>
</HEAD>
<BODY >
<A HREF="manual005.html"><IMG SRC="previous_motif.gif" ALT="Previous"></A>
<A HREF="manual002.html"><IMG SRC="contents_motif.gif" ALT="Up"></A>
<A HREF="manual007.html"><IMG SRC="next_motif.gif" ALT="Next"></A>
<HR>
<H2 CLASS="section"><A NAME="htoc13">4</A>  How to detect and correct errors</H2><UL>
<LI><A HREF="manual006.html#toc9">H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A does not know a macro</A>
</LI><LI><A HREF="manual006.html#toc10">H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A incorrectly interprets a macro</A>
</LI><LI><A HREF="manual006.html#toc11">H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A crashes</A>
</LI></UL>
<P><A NAME="trouble"></A></P><P>Most of the problems that occur during the translation of a given
L<sup>A</sup>T<sub>E</sub>X file (say <CODE>trouble.tex</CODE>) can be detected and solved at
the macro-level. That is, most problems induce a macro-related warning
and can be solved by writing a few
macros. The best place for these macros is an user style file (say
<TT>trouble.hva</TT>) given as
argument to H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A.
</P><PRE CLASS="verbatim"># hevea trouble.hva trouble.tex
</PRE><P>By doing so, the macros written specially for H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A are not
seen by L<sup>A</sup>T<sub>E</sub>X. Even better, <CODE>trouble.tex</CODE> is not changed
at all.</P><P>Of course, this will be easier if the L<sup>A</sup>T<sub>E</sub>X source is written in a
generic style, using macros.
Note that this style is recommended anyway, since it facilitates the changing
and tuning of documents.</P><H3 CLASS="subsection"><A NAME="toc9"></A><A NAME="htoc14">4.1</A>  H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A does not know a macro</H3><P><A NAME="dontknow"></A>
Consider the following L<sup>A</sup>T<sub>E</sub>X source excerpt:
</P><PRE CLASS="verbatim">You can \raisebox{.6ex}{\em raise} text.
</PRE><P>L<sup>A</sup>T<sub>E</sub>X typesets this as follows:
</P><BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>
<IMG SRC="manual001.gif">
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE><P>Since H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A does not know about <CODE>\raisebox</CODE>,
it incorrectly processes this input. More precisely,
it first prints a warning message:
</P><PRE CLASS="verbatim">trouble.tex:34: Unknown macro: \raisebox
</PRE><P>Then, it goes on by translating the arguments of <CODE>\raisebox</CODE> as if
they were normal text. As a
consequence some <CODE>.6ex</CODE> is finally found in the HTML output:
</P><BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>
You can .6ex<EM>raise</EM> text.
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE><P>To correct this, you should provide a macro that has more or less the effect of
<CODE>\raisebox</CODE>. It is impossible to write a generic
<CODE>\raisebox</CODE> macro for H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A, because of HTML limitations.
However, in this case, the effect
of <CODE>\raisebox</CODE> is to raise the box <EM>a little</EM>.
Thus, the first, numerical, argument to <CODE>\raisebox</CODE> can be
ignored in a private <CODE>\raisebox</CODE> macro defined in <TT>trouble.hva</TT>:
</P><PRE CLASS="verbatim">\newcommand{\raisebox}[2]{$^{\mbox{#2}}$}
</PRE><P>Now, translating the document yields:
</P><BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>
You can <EM><SUP>raise</SUP></EM> text a little.
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE><P>Of course, this will work only when all <CODE>\raisebox</CODE> commands in
the document raise text a little. Consider, the following
example, where text
is both raised a lowered a little:
</P><PRE CLASS="verbatim">You can \raisebox{.6ex}{\em raise}
or \raisebox{-.6ex}{\em lower} text.
</PRE><P>Which L<sup>A</sup>T<sub>E</sub>X renders as follows:
</P><BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>
<IMG SRC="manual002.gif">
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE><P>
Whereas, with the above definition of <CODE>\raisebox</CODE>, H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A produces:
</P><BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>
You can <EM><SUP>raise</SUP></EM>
or <EM><SUP>lower</SUP></EM> text.
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE><P>A solution is to add a new macro definition in the <CODE>trouble.hva</CODE> file:
</P><PRE CLASS="verbatim">\newcommand{\lowerbox}[2]{$_{\mbox{#2}}$}
</PRE><P>Then, <CODE>trouble.tex</CODE> itself has to be modified a little.
</P><PRE CLASS="verbatim">You can \raisebox{.6ex}{\em raise}
or \lowerbox{-.6ex}{\em lower} text.
</PRE><P>H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A now produces a satisfying output:
</P><BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>
You can <EM><SUP>raise</SUP></EM>
or <EM><SUB>lower</SUB></EM> text.
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE><P>Note that, for the document to remain L<sup>A</sup>T<sub>E</sub>X-processable,
it should also contain the following definition for
<CODE>\lowerbox</CODE>:
</P><PRE CLASS="verbatim">\newcommand{\lowerbox}[2]{\raisebox{#1}{#2}}
</PRE><P>This definition can safely be placed anywhere in <TT>trouble.tex</TT>,
since by H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A semantics for <CODE>\newcommand</CODE> (see
section <A HREF="manual030.html#usermacro">B.8.1</A>)
the new definition will not overwrite the old one.</P><H3 CLASS="subsection"><A NAME="toc10"></A><A NAME="htoc15">4.2</A>  H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A incorrectly interprets a macro</H3><P><A NAME="blob"></A></P><P>Sometimes H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A knows about a macro, but the produced HTML
does not look good when seen through a browser.
This kind of errors is detected while visually checking the
output.
However, H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A does its best to issue warnings when such situations
are likely to occur.</P><P>Consider, for instance, this definition of <CODE>\blob</CODE> as a small
black square.
</P><PRE CLASS="verbatim">\newcommand{\blob}{\rule[.2ex]{1ex}{1ex}}
\blob\ Blob \blob
</PRE><P>Which L<sup>A</sup>T<sub>E</sub>X typesets as follows:
</P><BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>
<IMG SRC="manual003.gif"><HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE><P>
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A always translates <CODE>\rule</CODE> as <CODE><HR></CODE>, ignoring size
arguments.
Hence, it produces the following, wrong, output:
</P><BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>
<HR SIZE=2> Blob <HR SIZE=2>
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE><P>We may not be particularily commited to a square blob.
In that case, other small symbols would perfectly do the job
of <CODE>\blob</CODE>, such as a bullet (<CODE>\bullet</CODE>).
Thus, you may choose to give <CODE>\blob</CODE> a definition in
<CODE>trouble.hva</CODE>:
</P><PRE CLASS="verbatim">\newcommand{\blob}{\bullet}
</PRE><P>This new definition yields the following, more satisfying output:
</P><BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>• Blob •
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE><P><A NAME="square:blob"></A>
<A NAME="@default6"></A>In case we do want a square blob, there are two alternatives.
We can have L<sup>A</sup>T<sub>E</sub>X typeset some subparts of
the document and then to include them as images, section <A HREF="manual008.html#imagen">6</A>
explains how to proceed.
We can also find a square blob somewhere in the variety of Unicode
(or do I mean ISO 10646?) characters,
and define <CODE>\blob</CODE> as a numerical
character reference. Here, the character <TT>U+02588</TT>
seems ok.
</P><PRE CLASS="verbatim">\newcommand{\blob}{\@print@u{X2588}}
</PRE><BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>█ Blob █
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE><P>
However, beware that not all browsers display all of Unicode…</P><H3 CLASS="subsection"><A NAME="toc11"></A><A NAME="htoc16">4.3</A>  H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A crashes</H3><P>H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A failure may have many causes, including a bug.
However, it may also stem from a wrong L<sup>A</sup>T<sub>E</sub>X input.
Thus, this section is to be read before reporting a bug…</P><H4 CLASS="subsubsection">4.3.1  Simple cases: L<sup>A</sup>T<sub>E</sub>X also crashes</H4><P>
In the following source, environments are not properly balanced:
</P><PRE CLASS="verbatim">\begin{flushright}
\begin{quote}
This is right-flushed quoted text.
\end{flushright}
\end{quote}
</PRE><P>Such a source will make both L<sup>A</sup>T<sub>E</sub>X and H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A choke.
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A issues the following error message that shows the L<sup>A</sup>T<sub>E</sub>X
environment that is not closed properly:
</P><PRE CLASS="verbatim">./trouble.tex:6: Environment nesting error: html: 'DIV' closes 'BLOCKQUOTE'
./trouble.tex:4: Latex environment 'quote' is pending
Adios
</PRE><P>Thus, when H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A crashes, it is a good idea to check that the
input is correct by running L<sup>A</sup>T<sub>E</sub>X on it.</P><H4 CLASS="subsubsection">4.3.2  Complicated cases</H4><P>Unfortunately, H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A may crash on input that does not affect
L<sup>A</sup>T<sub>E</sub>X.
Such errors usually relate to environment or group nesting.</P><P>Consider for instance the following “optimized” version of a
<CODE>quoteright</CODE> environment:
</P><PRE CLASS="verbatim">\newenvironment{quoteright}{\quote\flushright}{\endquote}
\begin{quoteright}
This a right-flushed quotation
\end{quoteright}
</PRE><P>The <CODE>\quote</CODE> and <CODE>\flushright</CODE> constructs
are intended to replace
<CODE>\begin{quote}</CODE> and <CODE>\begin{flushright}</CODE>,
while <CODE>\endquote</CODE> stands for <CODE>\end{quote}</CODE>.
Note that the closing <CODE>\endflushright</CODE>
is omitted, since it does nothing.
L<sup>A</sup>T<sub>E</sub>X accepts such an input and produces a right-flushed quotation.</P><P>However, H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A usually translates L<sup>A</sup>T<sub>E</sub>X environments to HTML
block-level elements and it <EM>requires</EM>
those elements to be nested properly.
Here, <CODE>\quote</CODE> translates to <CODE><BLOCKQUOTE></CODE>,
<CODE>\flushright</CODE> translates to <CODE><DIV ALIGN=right></CODE> and
<CODE>\endquote</CODE> translates to <CODE></BLOCKQUOTE></CODE>.
At that point, H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A refuses to generate obviously
non-correct HTML and it crashes:
</P><PRE CLASS="verbatim">Giving up command: \@close
Giving up command: \endquote
Giving up command: \endquoteright
Giving up command: \end
./trouble.tex:7: Environment nesting error: html: 'BLOCKQUOTE' closes 'DIV'
./trouble.tex:5: Latex environment 'quoteright' is pending
Adios
</PRE><P>Also notice that the error message above includes a backtrace showing
the call-chain of commands.</P><P>In this case, the solution is easy: environments must be opened and
closed consistently. L<sup>A</sup>T<sub>E</sub>X style being recommended, one should write:
</P><PRE CLASS="verbatim">\newenvironment{quoteright}
{\begin{quote}\begin{flushright}}
{\end{flushright}\end{quote}}
</PRE><P>And we get:
</P><BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>
<BLOCKQUOTE CLASS="quote"><DIV CLASS="flushright">
This is a right-flushed quotation
</DIV></BLOCKQUOTE>
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE><P>Unclosed L<sup>A</sup>T<sub>E</sub>X groups (<CODE>{</CODE>…) are another source
of nuisance to H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A.
Consider the following <TT>horreur.tex</TT> file:
</P><PRE CLASS="verbatim">\documentclass{article}
\begin{document}
In this sentence, a group is opened now {\em and never closed.
\end{document}
</PRE><P>L<sup>A</sup>T<sub>E</sub>X accepts this file, although it produces a warning:
</P><PRE CLASS="verbatim"># latex horreur.tex
This is TeX, Version 3.14159 (Web2C 7.2)
...
(\end occurred inside a group at level 1)
Output written on horreur.dvi (1 page, 280 bytes).
</PRE><P>By contrast, running H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A on <TT>horreur.tex</TT> yields a fatal error:
</P><PRE CLASS="verbatim"># hevea horreur.tex
Giving up command: \@raise@enddocument
Giving up command: \enddocument
Giving up command: \end
./horreur.tex:4: Environment nesting error: Latex env error: 'document' closes ''
./horreur.tex:3: Latex environment '' is pending
Adios
</PRE><P>Thus, users should close opening braces where it belongs.
Note that H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A error message “<TT>Latex environment
’</TT><I>env</I><TT>’ is pending</TT>” helps a lot in locating
the brace that hurts.</P><H4 CLASS="subsubsection">4.3.3  Desperate cases</H4><P>If H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A crashes on L<sup>A</sup>T<sub>E</sub>X source (not on T<sub>E</sub>X source),
then you may have discovered a bug, or this manual is not as complete
as it should.
In any case, please report to <A HREF="mailto:Luc.Maranget@inria.fr">Luc.Maranget@inria.fr</A>.</P><P>To be useful, your bug report should include L<sup>A</sup>T<sub>E</sub>X code
that triggers the bug (the shorter, the better) and mention
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A version number.</P><HR>
<A HREF="manual005.html"><IMG SRC="previous_motif.gif" ALT="Previous"></A>
<A HREF="manual002.html"><IMG SRC="contents_motif.gif" ALT="Up"></A>
<A HREF="manual007.html"><IMG SRC="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
