4 |
How to detect and correct errors |
|
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.
Of course, this will be easier if the LATEX source is written in a
generic style, using macros.
Note that this style is recommended anyway, since it eases the changing
and tuning of documents.
4.1 |
HEVEA does not know a macro |
|
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.
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 |
|
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
There is not small square in the symbol font used by HEVEA.
However there are other small symbols that 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 ·
Now, if you insist on having a square ``blob'', you can.
It suffices to have LATEX typeset some subparts of
the document and then to include them as images, section 6
explain how to proceed.
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:7: hml: DIV closes BLOCKQUOTE
trouble.tex:5: 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.
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 ALIGN=right>
and
\endquote
translates to </BLOCKQUOTE>
.
At that point, HEVEA refuses to generate obviously
non-correct HTML and it crashes:
trouble.tex:9: hml: BLOCKQUOTE closes DIV
trouble.tex:7: Latex environment ``quoteright'' is pending
Adios
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
horreur.tex:5: Latex env error: ``document'' closes ``''
horreur.tex:4: 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.
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.