How to detect and correct errors
Author: Luc Maranget

## 4 How to detect and correct errors

- HEVEA does not know a macro
- HEVEA incorrectly interprets a macro
- HEVEA crashes

Most of the problems that occur during the translation of a given LATEX file (say `trouble.tex`) 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 trouble.hva) given as argument to HEVEA.

    # hevea trouble.hva trouble.tex

By doing so, the macros written specially for HEVEA are not seen by LATEX. Even better, `trouble.tex` is not changed at all.

A worth-mentiong alternative is inserting `\usepackage{trouble}` in the document preamble. Then, given HEVEA semantics for `\usepackage` (see Section B.5.2), HEVEA-specific commands should be placed in the file “trouble.hva” file, while LATEX-specific commands should be placed in the file “trouble.sty”.

Of course, adapting a document to HEVEA processing will be easier if the LATEX source is written in a generic style, using macros. Note that this style is recommended anyway, since it facilitates document maintenance.

### 4.1 HEVEA does not know a macro

> This section has been outdated by the implementation of `\raisebox` by C. Spiel. Nevertheless, the method illustrated here is still highly valuable. This method can be summarised as “if HEVEA does not know about a macro, you may solve the problem a simple one yourself” and “do not ignore warnings”.

Consider the following LATEX source excerpt:

    You can \raisebox{.6ex}{\em raise} text.

LATEX typesets this as follows:

Since HEVEA does not know about `\raisebox`, it incorrectly processes this input. More precisely, it first prints a warning message:

    trouble.tex:34: Unknown macro: \raisebox

Then, it goes on by translating the arguments of `\raisebox` as if they were normal text. As a consequence some `.6ex` is finally found in the html output:

> You can .6exraise text.

To correct this, you should provide a macro that has more or less the effect of `\raisebox`. It is impossible to write a generic `\raisebox` macro for HEVEA, because of html limitations.1 However, in this case, the effect of `\raisebox` is to raise the box a little. Thus, the first, numerical, argument to `\raisebox` can be ignored in a private `\raisebox` macro defined in trouble.hva:

    \newcommand{\raisebox}[2]{$^{\mbox{#2}}$}

Now, translating the document yields:

> You can raise text a little.

Of course, this will work only when all `\raisebox` commands in the document raise text a little. Consider, the following example, where text is both raised a lowered a little:

    You can \raisebox{.6ex}{\em raise}
    or \raisebox{-.6ex}{\em lower} text.

Which LATEX renders as follows:

Whereas, with the above definition of `\raisebox`, HEVEA produces:

> You can raise or lower text.

A solution is to add a new macro definition in the `trouble.hva` file:

    \newcommand{\lowerbox}[2]{$_{\mbox{#2}}$}

Then, `trouble.tex` itself has to be modified a little.

    You can \raisebox{.6ex}{\em raise}
    or \lowerbox{-.6ex}{\em lower} text.

HEVEA now produces a satisfying output:

> You can raise or lower text.

Note that, for the document to remain LATEX-processable, it should also contain the following definition for `\lowerbox`:

    \newcommand{\lowerbox}[2]{\raisebox{#1}{#2}}

This definition can safely be placed anywhere in trouble.tex, since by HEVEA semantics for `\newcommand` (see section B.8.1) the new definition will not overwrite the old one.

### 4.2 HEVEA incorrectly interprets a macro

Note : HEVEA now renders the `\rule` command very similarly to LATEX. Hence the forthcomming section is in some sense obsolete. Nevertheless, the technique described is useful and the section is still worth reading.

Sometimes HEVEA 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, HEVEA does its best to issue warnings when such situations are likely to occur.

Consider, for instance, this definition of `\blob` as a small black square.

    \newcommand{\blob}{\rule[.2ex]{1ex}{1ex}}
    \blob\ Blob \blob

Which LATEX typesets as follows:

HEVEA always translates `\rule` as `<hr>`, ignoring size arguments. Hence, it produces the following, wrong, output:

> Blob

We may not be particularily commited to a square blob. In that case, other small symbols would perfectly do the job of `\blob`, such as a bullet (`\bullet`). Thus, you may choose to give `\blob` a definition in `trouble.hva`:

    \newcommand{\blob}{\bullet}

This new definition yields the following, more satisfying output:

> • Blob •

In case we do want a square blob, there are two alternatives. We can have LATEX typeset some subparts of the document and then to include them as images, section 6 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 `\blob` as a numerical character reference. Here, the character U+02588 seems ok.

    \newcommand{\blob}{\@print@u{X2588}}

> █ Blob █

However, beware that not all browsers display all of Unicode…

Finally, users that experience poor rendering of the `\rule` command can also upgrade HEVEA, so as to benefit from the new implementation of this command:

Blob

### 4.3 HEVEA crashes

HEVEA failure may have many causes, including a bug. However, it may also stem from a wrong LATEX input. Thus, this section is to be read before reporting a bug…

#### 4.3.1 Simple cases: LATEX also crashes

In the following source, environments are not properly balanced:

    \begin{flushright}
    \begin{quote}
    This is right-flushed quoted text.
    \end{flushright}
    \end{quote}

Such a source will make both LATEX and HEVEA choke. HEVEA issues the following error message that shows the LATEX environment that is not closed properly:

    ./trouble.tex:6: Environment nesting error: html: 'DIV' closes 'BLOCKQUOTE'
    ./trouble.tex:4: Latex environment 'quote' is pending
    Adios

Thus, when HEVEA crashes, it is a good idea to check that the input is correct by running LATEX on it.

#### 4.3.2 Complicated cases

Unfortunately, HEVEA may crash on input that does not affect LATEX. Such errors usually relate to environment or group nesting.

Consider for instance the following “optimized” version of a `quoteright` environment:

    \newenvironment{quoteright}{\quote\flushright}{\endquote}

    \begin{quoteright}
    This a right-flushed quotation
    \end{quoteright}

The `\quote` and `\flushright` constructs are intended to replace `\begin{quote}` and `\begin{flushright}`, while `\endquote` stands for `\end{quote}`. Note that the closing `\endflushright` is omitted, since it does nothing. LATEX accepts such an input and produces a right-flushed quotation.

However, HEVEA usually translates LATEX environments to html block-level elements and it requires those elements to be nested properly. Here, `\quote` translates to `<blockquote>`, `\flushright` translates to `<div class="flushright">` and `\endquote` translates to `</blockquote>`. At that point, HEVEA refuses to generate obviously non-correct html and it crashes:

    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

Also notice that the error message above includes a backtrace showing the call-chain of commands.

In this case, the solution is easy: environments must be opened and closed consistently. LATEX style being recommended, one should write:

    \newenvironment{quoteright}
      {\begin{quote}\begin{flushright}}
      {\end{flushright}\end{quote}}

And we get:

> > This is a right-flushed quotation

Unclosed LATEX groups (`{`…) are another source of nuisance to HEVEA. Consider the following horreur.tex file:

    \documentclass{article}

    \begin{document}
    In this sentence, a group is opened now {\em and never closed.
    \end{document}

LATEX accepts this file, although it produces a warning:

    # 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).

By contrast, running HEVEA on horreur.tex yields a fatal error:

    # 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

Thus, users should close opening braces where it belongs. Note that HEVEA error message “Latex environment ’env’ is pending” helps a lot in locating the brace that hurts.

#### 4.3.3 Desperate cases

If HEVEA crashes on LATEX source (not on TEX source), then you may have discovered a bug, or this manual is not as complete as it should. In any case, please report to Luc.Maranget@inria.fr.

To be useful, your bug report should include LATEX code that triggers the bug (the shorter, the better) and mention HEVEA version number.

1
  Clearly the author of those lines was wrong, as demonstrated here.