<!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>