~ubuntu-branches/ubuntu/edgy/hevea-doc/edgy : contents of manual007.html at revision 3

~ubuntu-branches/ubuntu/edgy/hevea-doc/edgy : (revision 3)
<!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=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<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="manual006.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="manual003.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="manual008.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc13">4</A>&nbsp;&nbsp;How to detect and correct errors</H2><UL>
<LI><A HREF="manual007.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><A HREF="manual007.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><A HREF="manual007.html#toc11">H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A crashes</A>
</UL>
<A NAME="trouble"></A>
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.
<PRE CLASS="verbatim">
# hevea trouble.hva trouble.tex
</PRE>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.<BR>
<BR>
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 eases the changing
and tuning of documents.<BR>
<BR>
<A NAME="toc9"></A>
<H3 CLASS="subsection"><A NAME="htoc14">4.1</A>&nbsp;&nbsp;H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A does not know a macro</H3><A NAME="dontknow"></A>
Consider the following L<sup>A</sup>T<sub>E</sub>X source excerpt:
<PRE CLASS="verbatim">
You can \raisebox{.6ex}{\em raise} text.
</PRE>
L<sup>A</sup>T<sub>E</sub>X typesets this as follows:
<BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>
<IMG SRC="manual001.gif">
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE>
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:
<PRE CLASS="verbatim">
trouble.tex:34: Unknown macro: \raisebox
</PRE>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:
<BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>
You can .6ex<EM>raise</EM> text.
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE>
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>:
<PRE CLASS="verbatim">
\newcommand{\raisebox}[2]{$^{\mbox{#2}}$}
</PRE>
Now, translating the document yields:
<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>
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:
<PRE CLASS="verbatim">
You can \raisebox{.6ex}{\em raise}
or \raisebox{-.6ex}{\em lower} text.
</PRE>Which L<sup>A</sup>T<sub>E</sub>X renders as follows:
<BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>
<IMG SRC="manual002.gif">
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE>
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:
<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>
A solution is to add a new macro definition in the <CODE>trouble.hva</CODE> file:
<PRE CLASS="verbatim">
\newcommand{\lowerbox}[2]{$_{\mbox{#2}}$}
</PRE>Then, <CODE>trouble.tex</CODE> itself has to be modified a little.
<PRE CLASS="verbatim">
You can \raisebox{.6ex}{\em raise}
or \lowerbox{-.6ex}{\em lower} text.
</PRE>H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A now produces a satisfying output:
<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>
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>:
<PRE CLASS="verbatim">
\newcommand{\lowerbox}[2]{\raisebox{#1}{#2}}
</PRE>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&nbsp;<A HREF="manual024.html#usermacro">B.8.1</A>)
the new definition will not overwrite the old one.<BR>
<BR>
<A NAME="toc10"></A>
<H3 CLASS="subsection"><A NAME="htoc15">4.2</A>&nbsp;&nbsp;H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A incorrectly interprets a macro</H3><A NAME="blob"></A>
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.<BR>
<BR>
Consider, for instance, this definition of <CODE>\blob</CODE> as a small
black square.
<PRE CLASS="verbatim">
\newcommand{\blob}{\rule[.2ex]{1ex}{1ex}}
\blob\ Blob \blob
</PRE>Which L<sup>A</sup>T<sub>E</sub>X typesets as follows:
<BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>
<IMG SRC="manual003.gif"><HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE>
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A always translates <CODE>\rule</CODE> as <CODE>&lt;HR&gt;</CODE>, ignoring size
arguments.
Hence, it produces the following, wrong, output:
<BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>

<HR SIZE=2> Blob <HR SIZE=2>
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE>
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>:
<PRE CLASS="verbatim">
\newcommand{\blob}{\bullet}
</PRE>This new definition yields the following, more satisfying output:
<BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>&#8226; Blob &#8226;
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE>
<A NAME="square:blob"></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&nbsp;<A HREF="manual009.html#imagen">6</A>
explain how to proceed.
We can also find a square blob somewhere in the variety of Unicode I
mean ISO&nbsp;10646) characters,
and define <CODE>\blob</CODE> as a (numerical or symbolic)
character reference. Here, the character <TT>U02588</TT>
seems ok.
<PRE CLASS="verbatim">
\newcommand{\blob}{\@print{&amp;#X2588;}
</PRE><BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>&#X2588; Blob &#X2588;
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE>
However, beware that not all browsers display all of Unicode...<BR>
<BR>
<A NAME="toc11"></A>
<H3 CLASS="subsection"><A NAME="htoc16">4.3</A>&nbsp;&nbsp;H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A crashes</H3>
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...<BR>
<BR>

<H4 CLASS="subsubsection">4.3.1&nbsp;&nbsp;Simple cases: L<sup>A</sup>T<sub>E</sub>X also crashes</H4>
In the following source, environments are not properly balanced:
<PRE CLASS="verbatim">
\begin{flushright}
\begin{quote}
This is right-flushed quoted text.
\end{flushright}
\end{quote}
</PRE>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:
<PRE CLASS="verbatim">
trouble.tex:7: hml: DIV closes BLOCKQUOTE
trouble.tex:5: Latex environment ``quote'' is pending
Adios
</PRE>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.<BR>
<BR>

<H4 CLASS="subsubsection">4.3.2&nbsp;&nbsp;Complicated cases</H4>
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.<BR>
<BR>
Consider for instance the following &#8220;optimized&#8221; version of a
<CODE>quoteright</CODE> environment:
<PRE CLASS="verbatim">
\newenvironment{quoteright}{\quote\flushright}{\endquote}

\begin{quoteright}
This a right-flushed quotation
\end{quoteright}
</PRE>
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.<BR>
<BR>
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>&lt;BLOCKQUOTE&gt;</CODE>,
<CODE>\flushright</CODE> translates to <CODE>&lt;DIV ALIGN=right&gt;</CODE> and
<CODE>\endquote</CODE> translates to <CODE>&lt;/BLOCKQUOTE&gt;</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:
<PRE CLASS="verbatim">
trouble.tex:9: hml: BLOCKQUOTE closes DIV
trouble.tex:7: Latex environment ``quoteright'' is pending
Adios
</PRE>
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:
<PRE CLASS="verbatim">
\newenvironment{quoteright}
  {\begin{quote}\begin{flushright}}
  {\end{flushright}\end{quote}}
</PRE>And we get:
<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>
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:
<PRE CLASS="verbatim">
\documentclass{article}

\begin{document}
In this sentence, a group is opened now {\em and never closed.
\end{document}
</PRE>L<sup>A</sup>T<sub>E</sub>X accepts this file, although it produces a warning:
<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>
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:
<PRE CLASS="verbatim">
# hevea horreur.tex 
horreur.tex:5: Latex env error: ``document'' closes ``''
horreur.tex:4: Latex environment ``'' is pending
Adios
</PRE>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 &#8220;<TT>Latex environment
&#8220;</TT><I>env</I><TT>&#8221; is pending</TT>&#8221; helps a lot in locating
the brace that hurts.<BR>
<BR>

<H4 CLASS="subsubsection">4.3.3&nbsp;&nbsp;Desperate cases</H4>
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>.<BR>
<BR>
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.<BR>
<BR>
<HR>
<A HREF="manual006.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="manual003.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="manual008.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>