\usepackage{a4}
\usepackage{fullpage}
\usepackage{makeidx}
\usepackage{texnames}
\usepackage{url}
\usepackage{hevea}
\usepackage{isolatin1}
\usepackage{ifthen}
\usepackage{array}
\usepackage{graphics}
%HEVEA\usepackage{color}
\input{macros.tex}
\title{\hevea{} User Documentation\\
{\normalsize Version~\heveaversion}}
\author{Luc Maranget\thanks{Inria Rocquencourt -- BP 105, 78153 Le
Chesnay Cedex. {\tt \mailto{Luc.Maranget@inria.fr}}}}
\urldef{\ftpbase}{\url}{ftp://ftp.inria.fr/INRIA/Projects/para/hevea/unstable}
\urldef{\ftpbase}{\url}{ftp://ftp.inria.fr/INRIA/Projects/para/hevea}
\urldef{\httpbase}{\url}{http://pauillac.inria.fr/~maranget/hevea}
\def\locversion{\ifdevrelease\releasedate\else\heveaversion\fi}
This manual also exists in
\ahref{\ftpbase/hevea-\locversion-manual.ps.gz}{compressed Postscript},
\ahref{\ftpbase/hevea-\locversion-manual.pdf}{PDF}, and as
a \ahref{\ftpbase/hevea-\locversion-manual.tar.gz}{bundle of HTML files}.
\begin{abstract}
\hevea{} is a \LaTeX{} to
The input language is a fairly complete subset of \LaTeXe{} (old
\LaTeX{} style is also accepted) and the
output language is {\html} that is (hopefully) correct with respect to
now standard \verb+FACE+ attribute of the \verb+FONT+ tag.
This allows the translation to {\html} of quite a lot of the symbols used in
\hevea{} understands \LaTeX{} macro definitions. Simple user style
files are understood with little or no modifications.
Furthermore, \hevea{} customization is done by writing \LaTeX{} code.
\hevea{} is written in Objective Caml, as many lexers. It is
Using \hevea{} it is possible to translate  large documents such
as manuals, books, etc. very quickly. All documents are
translated as one single {\html} file. Then, the output file can be cut into
smaller files, using the companion program \hacha.
\hevea{} can also be instructed to output plain text or info files.
Information on \hevea{} is available at \ahrefurl{\heveaurl}.
\end{abstract}
\clearpage
reference manual and some practical information. The latter part
includes a small \ahrefloc{@index}{index}.
\clearpage
\label{usermanual}
Assume that you have a file, ``\texttt{a.tex}'', written in \LaTeX, using the
is achieved by issuing the command:
# hevea a.tex
\hevea{} does not crash, just ignore them for the moment
``\texttt{a.html}'', which you can visualize through  a {\html} browser.
If \texttt{a.tex} contains math symbols you need to instruct your
If you wish to experiment \hevea{} on small \LaTeX{} source fragments,
then launch \hevea{} without arguments. \hevea{} will read its
standard input and print the translation on its standard output.
# hevea
$x \in {\cal E}$
You can find some more elaborate \footahref{\heveaurl/examples/index.html}{examples} in the on-line
\LaTeX{} style files are files that are not intended to produce output, but
define document layout parameters, commands, environments, etc.
\subsection{Standard base styles}
The base style of a \LaTeX{} document is the argument to the
\verb+\documentclass+ command (\verb+\documentstyle+ in old style).
Normally, the base style of a document defines the structure and
appearance of the whole document.
\noindent\hevea{} really knows about two \LaTeX{} base styles,
Base style \filename{style} is implemented by an \hevea{} specific
style file \filename{style}\verb+.hva+.
More precisely, \hevea{} interprets
\verb+\documentclass{+\filename{style}\verb+}+ by attempting to load
the file \filename{style}\verb+.hva+ (see section~\ref{comline} on where
\hevea{} searches for files).
Thus, at the moment, \hevea{} distribution includes the files,
\texttt{article.hva}, \texttt{book.hva}, etc.
\subsection{Other base styles}\label{otherbase}
Documents whose base style is not recognized by \hevea{} can be
Let us assume that \texttt{mydoc.tex} uses an exotic
base style such as \filename{acmconf}. Then, typing
\verb+hevea mydoc.tex+ will yield an error, since
\hevea{} cannot find the \texttt{acmconf.hva} file:
# hevea.opt mydoc.tex
mydoc.tex:1: Warning: Cannot find file: acmconf.hva
This situation is avoided by invoking \hevea{} with the known
base style file  \texttt{article.hva} as an extra argument:
# hevea article.hva mydoc.tex
The extra argument instructs
\hevea{} to load its \texttt{article.hva}
\verb+\documentclass+ (or \verb+\documentstyle+).
Observe that the fix above works because the \filename{acmconf} and
\filename{article} base styles look the same to the document (i.e., they define
the same macros).
More generally, most  base styles that are neither
\textit{article} nor \textit{book} are in fact variations
However, such styles usually provides extra macros.
If users documents use these macros, then users should also instruct
\hevea{} about them (see section~\ref{dontknow}).
Finally, it is important to notice that
renaming a base style file \filename{style}\verb+.cls+ into
\filename{style}\verb+.hva+ will not work in general.
As a matter of fact, base style files are \TeX{} and not \LaTeX{} source and
\hevea{} will almost surely fail on \TeX-ish input.
the commands  \verb+\input+ or \verb+\usepackage+ or \verb+\input+.
\subsubsection{Files loaded with \texttt{\char92 input}}
Just like \LaTeX{}, \hevea{} reacts to the construct
\textit{file}. (if I got it right, \hevea{} even follows \TeX{} crazy
As it is often the case, assume that the document \texttt{mydoc.tex} has a
\verb+\input{mymacros.tex}+ instruction in its preamble, where
\texttt{mymacros.tex} gathers custom definitions.
Hopefully, only a few macros give rise to trouble: macros that performs fine
typesetting or {\TeX}ish macros.
Such macros need to be rewritten, using basic \LaTeX{}
constructs (section~\ref{trouble} gives examples of macro-rewriting).
\texttt{mymacros.hva} for instance.
# hevea mymacros.hva mydoc.tex
The file \texttt{mymacros.hva} is processed before
\texttt{mydoc.tex} (and thus before \texttt{mymacros.tex}).
As a consequence of \hevea{} behavior with respect to
definition and redefinition (see section~\ref{usermacro}),
the macro definitions in \texttt{mymacros.tex}
override the ones in  \texttt{mymacros.tex}, provided
Another situation is when  \hevea{} fails to process a whole 
style file. Usually, this means that \hevea{} crashes on that style
The basic idea is then
to write a \texttt{mymacros.hva} style file that contains alternative
definitions for all the commands defined in \texttt{mymacros.sty}.
Then, \hevea{} should be instructed
to load \texttt{mymacros.hva} and not to load \texttt{mymacros.tex}.
This is done by invoking \texttt{hevea} as follows:
# hevea mymacros.hva -e mymacros.tex mydoc.tex
Of course, \texttt{mymacros.hva} must now contain replacements for
all the useful macros of \texttt{mymacro.tex}.
\subsubsection{Files loaded with \texttt{\char92 usepackage}}
As far as I know, \LaTeX{} reacts to the construct
\verb+\usepackage{+\textit{name}\verb+}+ by loading the file
\hevea{} reacts in a similar, but different, manner, by
loading the file \textit{name}\texttt{.hva}.
\hevea{} distributions already includes quite a few ``\texttt{.hva}''
implementations of famous packages (see section~\ref{implemented:package}).
When a given package (say  \texttt{zorglob}) is not implemented, the
situation may not be as bad as it may seem first.
Hopefully, you are only using a few commands from package
Then, it suffices to put your definitions in file~\texttt{zorglub.hva}
and \hevea{} will react to \verb+\usepackage{zorglub}+ by loading
\texttt{zorglub.hva}.
See section~\ref{usepackage} for the full story on \verb+\usepackage+.
\subsection{Spacing, Paragraphs}
Spacing in the \html{} document reflects the original source spacing.
More precisely, any sequence of spaces is outputed as one
space, whereas a single newline is replicated in the output.
introduce a paragraph break.
\index{tabulation}Whether the tabulation character is a space or not 
Paragraphs are rendered by a blank line and there is no paragraph
\hevea{} is a bit simplistic in breaking paragraphs and extra paragraph
This can usually be corrected by modifying the source, without
after a comment or macro definition can be deleted.
\index{ @`` '' (space)!after macro}
Space after macros with no argument is skipped (as in \LaTeX{}) ---
however this is not true in math mode, as explained in
section~\ref{spacemath} below.
In the output above, the space after \verb+\open+ does not
\hevea{} tries to emulate \LaTeX{} behavior in all situations, but
Thus, users are invited to make explicit what they want.
This is good practice anyway, because \LaTeX{} is mysterious
here. Consider the following example, where the \verb+\tryspace+
macro is first applied and then expansed by hand:
\newcommand{\tryspace}[1]{#1 XXX}
Some space: \tryspace{\bfsymbol}\\
No space: \bfsymbol XXX
Spacing is a bit chaotic here,
the space after \textbf{symbol} remains when \verb+#1+ is substituted for it
by \LaTeX{} (or \hevea).
\newcommand{\tryspace}[1]{#1 XXX}
Some space & \tryspace{\bfsymbol}\\
No space   & \bfsymbol XXX
\par ~\vspace{-1ex}
Note that, if a space before ``XXX'' is wanted, then
\newcommand{\tryspace}[1]{#1{} XXX}
\subsection{Math mode}
\hevea{} math mode is not very far from normal text mode, except that
all letters are shown in italics and that space after macros
is echoed.
However, typesetting math formulas in \html{} rises two difficulties.
First, formulas contain symbols, such as Greek letters; second,
\subsubsection{Spacing in math mode}\label{spacemath}
\index{ @`` '' (space)!after macro!in math}
By contrast with \LaTeX{}, spaces from the input are significant in
math mode, this
feature allows users to instruct \hevea{}
on how to put space in their formulas.
For instance, \verb+\alpha\rightarrow\beta+ is typeset without spaces between
symbols, whereas \verb+\alpha \rightarrow \beta+ produces these spaces.
\begin{array}{l@{ : }l}
\verb+\alpha\rightarrow\beta+ & \alpha\rightarrow\beta\\
\verb+\alpha \rightarrow \beta+ & \alpha \rightarrow \beta\\
\end{array}
Note that \LaTeX{} ignores spaces in math mode, so that users can
freely adjust \hevea{} output without changing anything to \LaTeX{}
\caption{\label{xfd} Symbol font in X}
the now standard \verb+FACE+ attribute to the \verb+FONT+
element instruct the browser to switch to a symbol font.
\hevea{} assumes this choice for the symbol font to be
A browser  correctly displays \hevea{} symbols when
figure~\ref{xfd} resembles the \html{} page located
at \localurl{symbol.html} in \hevea{} on-line documentation
For authors that do not want to generate symbols that cannot be shown
by any browser, \hevea{} offers a degraded mode that outputs text
in place of symbols.
\hevea{} operates in this mode when given the \verb+-nosymb+ flag.
Replacement text is in English, unless
\hevea{} is also given the \verb+-francais+ flag. In that case
replacement text is in French.
For instance. the ``$\in$'' symbol is replace by ``in'' (or by ``appartient
à'' if French mode is selected).
This is far from being satisfactory, but degraded mode may be
appropriate for documents than contain few symbols.
that departs from normal text typesetting. For instance, fractions
numerators and denominators must be placed one above the other.
\hevea{} handles such constraints in display mode only.
The main two operating modes of \hevea{} are \emph{text} mode and
when in this mode, text items are echoed one following the other and
paragraph breaks are just blank lines, both in input and output.
The so called \emph{displayed-paragraph environments} of \LaTeX{} (such as
elements (such as \texttt{DIV} or \texttt{BLOCKQUOTE}).
Rendering is correct becauses both \LaTeX{} displayed environments and
a new line, any text that sould appear inside a paragraph must be
\hevea{} chooses to translate in-text formulas that way.
\hevea{} display mode allows more control on text placement, since
a \html{} \verb+TABLE+ element and that tables allow to control the
Displays come in two flavor, horizontal displays and vertical
An horizontal display is a one-row table, while a vertical display is
sub-elements being centered vertically in horizontal display mode and
horizontally in vertical display mode.
Display mode is first opened by opening a \verb+displaymath+ environment
Then, sub-displays are opened by \LaTeX{} constructs which require
For instance, a displayed  fraction (\verb+\frac+) opens a vertical display.
typesetting math formulas.
An in-text formula such as
\verb+$\int_1^2 xdx = \frac{3}{2}$+ appears as:
%HEVEA$\int_1^2 xdx =\frac{3}{2}$,
while the same formula has a better aspect in display mode:
%HEVEA$$\int_1^2xdx = \frac{3}{2}$$
As a consequence, \hevea{} is more powerful in display mode and
formulas should be displayed as soon as they get a bit complicated.
This rule is also true in \LaTeX{} but it is more strict in \hevea{},
since \html{} capabilities to typeset formulas inside text are quite
In particular, it is not possible to get in-text ``real'' fractions or
Users should remember that \hevea{} is not \TeX{} or \LaTeX{} and that
\hevea{} author neither is D.~E.~Knuth nor L.~Lamport.
For instance, two fractions with different denominator and numerator
\frac{1}{\sum_{i=0}^{N}U_i} = \frac{\sum_{i=0}^{N}U_i}{1}
\image{cloche}
The reason is that vertical displays in an horizontal display are
that always get centered in the vertical direction.
Such a crude model cannot  faithfully emulate any \TeX{} box placement.
Users can get an idea on how \hevea{} combines elements in display mode
by giving the \verb+-v+ option comand line option twice, which
instructs \hevea{} to add a
By contrast with formulas, which \hevea{} attempts to render with
text-level elements only when they appear inside paragraphs, \LaTeX{} arrays
always translate to the
breaks before and after in-text arrays.
As a consequence, in-text arrays yield an acceptable output, only while
alone in a paragraph.
This is a small array:
This is a small array:
\verb+array+ and \verb+tabular+ environments implicitly open display
mode, thus allowing a satisfactory typesetting of formulas in
arrays. More precisely, array elements whose column format
specification is \verb+l+, \verb+c+ or \verb+r+ are typeset in display
mode (see section~\ref{arraydef}).
When \hevea{} thinks it cannot translate a symbol or construct
properly, it issues a warning. This draws user attention onto a
In the following (silly) example, \hevea{} gets nervous  because of
the complicated length given as argument to \verb+\hspace+:
\begin{tabular}{c@{\hspace{\mylength}}c}
Running \hevea{} on this input produces a warning:
# hevea manual.tex
manual.tex:507: Warning: \hspace with arg ``\mylength''
\begin{tabular}{c@{\hspace{\mylength}}c}
Note that all warnings can be suppressed with the \verb+-s+ (silent)
When a warning reveals a real problem, it can often be cured by
writing a specific macro. The next two sections introduce \hevea{}
macros, then section~\ref{trouble} describes how to proceed with
Just like \LaTeX{}, \hevea{} can be seen as a macro language, macros
characters (such as letters, integers\ldots) are outputed or some
internal operation (such as changing font attributes, or arranging
This scheme favors easy extension of program capabilities
by users. However, predicting program behavior and correcting errors
may occur after several levels of macro expansion.
As a consequence, users can tailor \hevea{} to their needs, but it
Nevertheless, happy \LaTeX{} users should enjoy customizing
\hevea{}, since this is done by writing \LaTeX{} code.
\subsection{Style choices}\label{stylechoice}
fine control over text placement, whereas
More symbols and font attributes are available in \LaTeX{} than in
{\html}. Conversely, {\html} has font attributes, such as color, which
standard \LaTeX{} has not.
Therefore, there are many situations where \hevea{} just cannot
render the visual effect of \LaTeX{} constructions. Here some choices
have to be made. For instance, the calligraphic letters (\verb+\mathcal+)
are rendered in red (\verb+<FONT COLOR=red>+), and the small caps
(\verb+\scshape+) are rendered in bold font (\verb+<B>+).
If you are not satisfied with \hevea{} rendering of text style
declarations, then you
can choose your own, by redefining the \verb+\cal+ and \verb+\sc+
macros, using \verb+\renewcommand+, the macro redefinition operator of
\LaTeX{}. The key point is that you need not worry about \hevea{}
declarations (i.e. \verb+\it+, \verb+\sc+, etc.) and everything should
\renewcommand{\cal}{\em}
(See sections~\ref{trouble} and~\ref{both} on how to make such
changes while leaving your file processable by \LaTeX{}, and
With such redefinitions, we get:
\renewcommand{\cal}{\em}
This is \textsc{small caps} and this is $\cal CALLIGRAPHIC LETTERS$
Note that many of \LaTeX{} commands and environments are defined in the 
\texttt{hevea.hva} file that \hevea{} loads before processing any
invoke \hevea{} internal commands.
Other \LaTeX{} constructs, such as
\LaTeX{} key constructs or \hevea{} internal commands (see section~\ref{internal}),
that require special processing are defined
in \hevea{} source code.
However, the vast majority of these definitions can be overridden by a
redefining core constructs such as \verb+\newcommand+ for instance.
Most of the problems that occur during the translation of a given
\LaTeX{} file (say \verb+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
\texttt{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, \verb+trouble.tex+ is not changed
at all.
generic style, using macros.
Note that this style is recommended anyway, since it eases the changing
\subsection{\hevea{} does not know a macro}\label{dontknow}
You can \raisebox{.6ex}{\em raise} text.
\LaTeX{} typesets this as follows:
\begin{showlatex}
You can \raisebox{.6ex}{\em raise} text.
\end{showlatex}
Since \hevea{} does not know about \verb+\raisebox+,
it first prints a warning message:
trouble.tex:34: Unknown macro: \raisebox
Then, it goes on by translating the arguments of \verb+\raisebox+ as if
You can .6ex{\em raise} text.
To correct this, you should provide a macro that has more or less the effect of
\verb+\raisebox+ macro for \hevea, because of \html{} limitations.
However, in this case, the effect
Thus, the first, numerical, argument to \verb+\raisebox+  can be
ignored in a private \verb+\raisebox+ macro defined in \texttt{trouble.hva}:
You can \raisebox{.6ex}{\em raise} text a little.
Of course, this will work only when all \verb+\raisebox+ commands in
is both raised a lowered a little:
You can \raisebox{.6ex}{\em raise}
Which \LaTeX{} renders as follows:
\begin{showlatex}
You can \raisebox{.6ex}{\em raise} or \raisebox{-.6ex}{\em lower} text.
\end{showlatex}
Whereas, with the above definition of \verb+\raisebox+, \hevea{} produces:
You can \raisebox{.6ex}{\em raise}
A solution is to add a new macro definition in the \verb+trouble.hva+ file:
Then, \verb+trouble.tex+ itself has to be modified a little.
You can \raisebox{.6ex}{\em raise}
\hevea{} now produces a satisfying output:
You can \raisebox{.6ex}{\em raise}
Note that, for the document to remain \LaTeX{}-processable,
This definition can safely be placed anywhere in \texttt{trouble.tex},
since by \hevea{} semantics for \verb+\newcommand+ (see
section~\ref{usermacro})
\subsection{\hevea{} incorrectly interprets a macro}\label{blob}
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
However, \hevea{} does its best to issue warnings when such situations
Consider, for instance, this definition of \verb+\blob+ as a small
black square.
Which \LaTeX{} typesets as follows:
\hevea{} always translates \verb+\rule+ as \verb+<HR>+, ignoring size
\begin{latexonly}\vspace*{.5ex}
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 \verb+\blob+, such as a bullet (\verb+\bullet+).
Thus, you may choose to give \verb+\blob+ a definition in
\verb+trouble.hva+:
\begin{latexonly}\vspace*{.5ex}
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~\ref{imagen}
\subsection{\hevea{} crashes}
\hevea{} failure may have many causes, including a bug.
However, it may also stem from a wrong \LaTeX{} input.
\subsubsection{Simple cases: \LaTeX{} also crashes}
In  the following source, environments are not properly balanced:
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:
Thus, when \hevea{} crashes, it is a good idea to check that the
\subsubsection{Complicated cases}
Unfortunately, \hevea{} may crash on input that does not affect
Such errors usually relate to environment or group nesting.
This a right-flushed quotation
are intended to replace
Note that the closing \verb+\endflushright+
\LaTeX{} accepts such an input and produces a  right-flushed quotation.
However,  \hevea{} usually translates \LaTeX{} environments  to \html{}
At that point, \hevea{} refuses to generate obviously
non-correct {\html} and it crashes:
In this case, the solution is easy: environments must be opened and
of nuisance to \hevea{}.
\documentclass{article}
\LaTeX{} accepts this file, although it produces a warning:
By contrast, running \hevea{} on \texttt{horreur.tex} yields a fatal error:
# hevea horreur.tex 
Thus, users should close opening braces where it belongs.
Note that \hevea{} error message ``\texttt{Latex environment
``}\textit{env}\texttt{'' is pending}'' helps a lot in locating
the brace that hurts.
\subsubsection{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
In any case, please report to \mailto{Luc.Maranget@inria.fr}.
that triggers the bug (the shorter, the better) and mention
\hevea{} version number.
\latexsection{Making \hevea{} and \LaTeX{} both happy}
\pdfsection{Making HeVeA and LaTeX both happy}
A satisfactory translation from \LaTeX{} to \html{} often requires
giving instructions to \hevea{}.
Typically, these instructions are macro definitions and
Conversely, some source that \LaTeX{} needs should not be processed
by \hevea{}.
Basically, there are three ways to make input vary according to the
processor, file loading, the \texttt{hevea} package
\hevea{} and \LaTeX{} treat files differently. Here is a summary of the main
  \item \LaTeX{} and \hevea{} both load files given as arguments to
  \hevea{} does not load \filename{filename}.
  \item \hevea{} loads all files given as command line arguments.
  \item Both \LaTeX{} and \hevea{} load style files given as optional
  \verb+\documentstyle+ and as arguments to \verb+\usepackage+,
  but the files are searched by following different methods and
As a consequence, for having a file \filename{latexonly} loaded by
in the source and to invoke \hevea{} as follows:
\verb+# hevea+ \texttt{-e} \filename{latexonly}\ldots
\label{heveaonly}Having \filename{heveaonly} loaded by \hevea{} only is more
simple: it  suffices to invoke \hevea{} as follows:
\verb+# hevea+ \filename{heveaonly}\ldots
Finally, if one has an \hevea{} equivalent \textit{style}\texttt{.hva}
\verb+\usepackage{+\textit{style}\verb+}+
while \hevea{} loads \textit{style}\texttt{.hva}.
As \hevea{} will not fail in case \textit{style}\texttt{.hva} does not
exist, this is another method for having a style file loaded by
Writing an \hevea{}-specific file \textit{file}\texttt{.hva}
is the method of choice for supplying command definitions
to \hevea{} only. Users can then be sure that these definitions are
not seen by \LaTeX{} and will not get echoed to the \textit{image}
The file \textit{file}\texttt{.hva} can be loaded by either
\textit{file}\texttt{.hva}, or by
\verb+\usepackage{+\textit{file}\verb+}+ from inside the document.
Which method is better depends
on whether it is choosed to override or to replace the document
In the command-line case,
definitions from \textit{file}\texttt{.hva} are processed before the
In the \verb+\usepackage+ case, \hevea{} loads \textit{file}\texttt{.hva}
at the place where \LaTeX{} loads \textit{file}\texttt{.sty}, hence
the definitions from \textit{file}\texttt{.hva} replace
\subsection{The \protect\texttt{hevea} package}\label{heveastyle}
The \texttt{hevea.sty} style file is intended to be loaded by \LaTeX{}
and not by \hevea{}.
It provides \LaTeX{} with means to ignore or process some parts of the
Note that \hevea{} copes with the constructs defined in
the \texttt{hevea.sty} file by default.
It is important to notice that the \texttt{hevea.sty} style file from
the distribution is a \emph{package} in \LaTeXe{} terms and that it
is not compatible with old \LaTeX{}. Moreover, the \texttt{hevea}
package loads the \texttt{comment} package which must be present.
\hevea{} and \LaTeX{} perform the following actions on source inside
the  \verb+latexonly+, \verb+verblatex+, \verb+htmlonly+, \verb+rawhtml+,
\envdefindex{rawhtml}
environment & \multicolumn{1}{c}{\hevea} &  \multicolumn{1}{c}{\LaTeX}
\verb+rawhtml+  & echo verbatim (see section~\ref{rawhtml}) & ignore\\
constructs and macro characters are processed (see section~\ref{imagen})  &
\noindent As an example, this is how some text can be typeset in purple by
\hevea{} and left alone by \LaTeX{}:
It is impossible to avoid the spurious space in \hevea{} output
This extra spaces comes from the newline character that follows
\LaTeX{} to recognize it. Anyway, better control over spaces
can be achieved
by using the \texttt{hevea} boolean register
or comments, see sections~\ref{heveabool}
Also note that environments define a scope and that style changes
(and non-global definitions) are local to them. For instance, in the
example above, ``\ldots'' appears in black in \html{} output.
However, as an exception, the environments \texttt{image}
It takes a little practice of \hevea{} to understand why this is
\subsubsection{Why are there two environments for ignoring input?}\label{why}
Some scanning and analysis of source is performed
by \hevea{} inside the \texttt{latexonly} environment, in order to
allow  \texttt{latexonly} to dynamically occur inside other environments.
More specifically, \verb+\end{+\textit{env}\verb+}+ macros
are recognized and their \textit{env} argument is tested against
the name of the environment whose opening macro \verb+\+\textit{env}
In that case, macro expansion of \verb+\end+\textit{env} is performed and
and may get expanded if it matches a pending
This enables playing tricks such as:
\begin{showlatex}
\end{showlatex}
\noindent While there is no \hevea{} output.
Since \hevea{} somehow analyses input that is enclosed in the
it may choke.
Fortunately, it remains possible to have input processed by \LaTeX{}
only, regardless of what it is, by enclosing it in the
Inside this environment, \hevea{} performs no other action
than looking for \verb+\end{verblatex}+. As a consequence,
may only appear in the main flow of text or inside the same macro body,
Additionally, formal parameters \verb+#+\textit{i} are replaced by
actual arguments inside the \texttt{toimage} environment
\subsubsection{The \texttt{hevea} boolean register}\label{heveabool}
Boolean registers are provided by the \texttt{ifthen} package
\boolindex{hevea}Both the \texttt{hevea.sty} style file
and \hevea{} define the boolean register \texttt{hevea}.
and \textit{true} for \hevea{}.
Thus, provided, both the \texttt{hevea.sty} style file and the
\texttt{ifthen} packages are loaded, the ``purple rain'' example can
be rephrased as follows:
{\ifthenelse{\boolean{hevea}}{\purple}{}purple rain, purple rain}\ldots
{\ifthenelse{\boolean{hevea}}{\purple}{}purple rain, purple rain}\ldots
Another choice is using the \TeX{}-style conditional macro
\verb+\ifhevea+ (see Section~\ref{texcond}):
{\ifhevea\purple\fi purple rain, purple rain}\ldots
We get: {\ifhevea\purple\fi purple rain, purple rain}\ldots
\index{comment!hevea@\texttt{\%HEVEA}}
\hevea{} processes all lines that start with \verb+%HEVEA+, while
Thus, this is a last variation on  the ``purple rain'' example:
(Note how comments are placed at the end of some lines to avoid spurious spaces
Comments thus provide an alternative to loading the
\texttt{hevea} package. For user convenience, comment equivalents to
Note that \LaTeX{}, by ignoring comments, naturally performs the action
\latexsection{With a little help from \LaTeX}
\pdfsection{With a little help from LaTeX}\label{imagen}
\hevea{} just cannot process its input, but it remains acceptable to
have \LaTeX{} process it, to produce a \texttt{.gif} image from
\LaTeX{} output and to include a link to this image into \hevea{}
\hevea{} provides a limited support for doing this.
While outputting \filename{mydoc}\texttt{.html}, \hevea{} echoes some
Additionally, \verb+\usepackage+ commands, top-level and global
are automatically echoed to the image file. This enables using
Output to the image file builds up a current page, which is flushed
This command has the following effect:  it outputs a strict page break
output a \verb+<IMG SRC="+\textit{pagename}\verb+.gif">+ tag in \hevea{}
and \hevea{} output file name.
Then the \verb+imagen+ script has to be run by:
file through \LaTeX,
\texttt{dvips}, \texttt{ghostscript} and a few others tools, which must all be
section~\ref{imagenusage}. Note that \texttt{imagen} is a simple shell
Here is the active part of a \texttt{blob.tex} file:
This time, we would like \verb+\blob+ to produce a small black square, which
Thus we can write:
 # hevea blob.tex
\begin{latexonly}\vspace*{.5ex}
Observe that the trick can be used to replace missing symbols by small
is generally bad, fine placement is ignored and font style changes are
Cost can be lowered using \verb+\savebox+, but the other problems remain.
In this section, a technique to transform included Postscript images
Note that this technique is used by \hevea{} implementation of the
\texttt{graphics} package (see section~\ref{graphics}),
which provides a more standard manner to include Postcript images in
Included images are easy to manage: it suffices to let \LaTeX{} do the
Let \texttt{round.ps} be a Postscript file, which is included as an
image in the source file \texttt{round.tex} (which must load the
\filename{epsf} package):
Then, \hevea{} can have this image translated into a inlined (and
(Note that the \texttt{round.tex} file
still can be processed by \LaTeX, since comment equivalents
of the \texttt{toimage} environment are used and that
Then, processing \texttt{round.tex} through \hevea{} and
\includegraphics{round}%
It is important to notice that things go smoothly because the
\verb+\usepackage{epsf}+ command  gets echoed to the
\filename{image} file.  In more complicated cases, \LaTeX{} may fail
on the \filename{image} file because it does not load the right
packages or define the right macros.
However, the above solution implies modifying the original \LaTeX{}
command, so that \hevea{} echoes  \verb+\epsfbox+ and its argument to
Such a definition must be seen by \hevea{} only. So, it is best put
in a separate file whose name is given as an extra argument on
\hevea{} command line (see section~\ref{heveaonly}).
protected inside an \verb+%HEVEA+ comment is a bad idea, %
because it might then get echoed to the \textit{image} file
Observe that the above definition of \verb+\epsfbox+ is a definition
because \hevea{} does not know about \verb+\epsfbox+ by default.
Also observe that this not a recursive definition, since
a pity to translate it back into a bitmap.
and then to include a link to that GIF file in \html{} output, see
section~\ref{imgsrc} for a description of this more adequate technique.
Some programs extend \LaTeX{} capabilities using a filter principle.
In such a scheme, the document contains source fragments for the program.
A first run of the program on \LaTeX{} source changes these fragments
into constructs that \LaTeX{} (or a subsequent stage in the paper
document production chain, such as \texttt{dvips}) can handle.
Here again, the rule of the game is keeping \hevea{} away from the
normal process: first applying the filter, then making \hevea{} send
the filter output to the \filename{image} file, and then having
then the result is available to subsequent \LaTeX{} source as a \TeX{}
box \verb+\box\graph+.
draws a ``Smile!'' logo as a centered
paragraph:
 ~\box\graph~
Both the image description (\verb+.PS+\ldots\ \verb+.PE+) and usage (\verb+\box\graph+)
 ~\box\graph~
The \texttt{gpic} filter is applied first, then come \texttt{hevea}
 # hevea tmp.tex -o smile.html
~\box\graph~
Observe how the \verb+-o+ argument to \hevea{} is used and that
\texttt{imagen} argument is \hevea{} output basename (see
section~\ref{basenames} for the full definition of \hevea{} output basename).
In the \texttt{gpic} example, modifying user source cannot be totally avoided.
 \newenvironment{centergpic}{}{\begin{center}~\box\graph~\end{center}}
\hevea{} will process this source correctly, provided it is given its
own definition for the \verb+centergpic+ environment beforehand:
   {\box\graph\end{toimage}\begin{center}\imageflush\end{center}}
Assuming that the definition above is in a \ahref{\heveaurl/examples/smile.hva}{smile.hva} file,
\ahref{\heveaurl/examples/smile.tex}{smile.tex} \mbox{now is}:
 # hevea smile.hva tmp.tex -o smile.html
The warnings above are normal: they are issued when \hevea{} runs
across the \LaTeX{}-intended definition of the \verb+centergpic+
environment and refuses to override its own definition for that
\latexsection{Cutting your document into pieces with \hacha{}}
\pdfsection{Cutting your document into pieces with HaChA}
\label{hacha}
\hevea{} outputs a single \texttt{.html} file. This file can be
cut into pieces at various sectional units by {\hacha}
First generate your {\html} document by applying \hevea{}:
\texttt{\# hevea }\filename{mydoc}\texttt{.tex}
\texttt{\# hacha }\filename{mydoc}\texttt{.html}
This root file holds document title, abstract and a simple table of
Every item in the table of contents contains a link to or into a file
that holds a ``cutting'' sectional unit.
\filename{article} style and {\em chapter} in the \filename{book}
as an entry in the table of contents.
Cross-references are properly handled, that is, the local links generated by
\hevea{} are changed into remote links.
The name of the root  file can be changed using the
\texttt{\# hacha -o root.html }\filename{mydoc}\texttt{.html}
Some of \hevea{} output get replicated in all the files generated by
\hacha{}.
Users can supply a header and a footer, which  will appear at the
begining and end of every page generated by \hacha{}. It suffices to
\quad\verb+\htmlhead{+\textit{header}\verb+}+\\
\hacha{} also makes every page it generates a clone of its input as
regards attributes to the \verb+<BODY ...>+ opening tag and
block. See section~\ref{metadef} for examples of this replication
\hacha{} behavior can be altered from the document source, by using
a counter and a few macros.
A document that explicitly includes cutting macros still can be typeset by
\texttt{hevea.sty} style file from the \hevea{} distribution.
An alternative to loading the \texttt{hevea} package is to put
{\hacha} recognizes all sectional units, ordered as follows, from
part}, {\em chapter},
\emph{paragraph} and \emph{subparagraph}.
a current cutting depth, a root file and an output file.
Cutting units start a new output file, whereas units comprised between the
cutting unit and the cutting units plus the cutting depth add new
entries in the table of contents.
At document start, the root file and the output file are {\hacha}
The cutting unit and the cutting depth are set to default values that
\subsubsection{Cutting macros}
preamble. They command the cutting scheme of the whole document:
\item[{\tt\char92 cuttingunit}]
This is a macro that holds the document cutting unit. You can change
the default (which is {\em section} in the \filename{article} style
and {\em chapter} in the \filename{book} style)  by doing:
\verb+\renewcommand{\cuttingunit}{+{\it secname}\verb+}+.
\item[{\tt\char92 tocnumber}] Instruct \hevea{} to put section numbers
\item[{\tt\char92 notocnumber}] Instruct \hevea{} \emph{not} to put
This is a counter that holds the document cutting depth.
You can change the default value of 1 by doing
A cutting depth of zero means no other entries than the cutting units
in the table of contents.
\verb+\begin{document}+. They all generate \html{} comments in \hevea{}
These comments then act as instructions to {\hacha}.
\item[{\tt\char92 cuthere\{}{\it secname}{\tt\}\{}{\it itemtitle}{\tt\}}]
   \item If {\it secname} is the current cutting  unit or
   \item If {\it secname} is above the cutting  unit, then the
   \item If {\it secname} is below the cutting  unit and less than the
   cutting depth away from it, then an entry is added in the table of
   \item Otherwise, no action is performed.
\item[{\tt\char92 cutdef[}{\it depth}{\tt]\{}{\it secname}{\tt \}}]
   Open a new table of contents, with cutting depth~{\em depth} and
   cutting unit {\em secname}. If the optional {\em depth} is absent,
   the cutting depth does not change.
   Result is unspecified if whatever {\em secname} expands to is
   the current cutting  unit, is not a valid sectional unit name or if
\item[{\tt\char92 cutend}]
   previous \verb+\cutdef+. The cutting unit and cutting depth are
   Note that \verb+\cutdef+ and \verb+\cutend+ must be properly balanced.
with the sectional unit name as first argument and the (optional, if
Note that started versions of the sectioning commands also perform
Consider, for instance, a \filename{book} document with a long chapter
that you want to cut at the section level, showing subsections:
\chapter{A long chapter}
\chapter{The next chapter}
Then, you should insert a \verb+\cutdef+ at chapter start and a
\verb+\cutend+ at chapter end:
\chapter{A long chapter}
\chapter{The next chapter}
that would otherwise contain the long chapter now contains the chapter
title and a table of sections.
No other change is needed, since the macro \verb+section+ already
performs the appropriate \verb+\cuthere{section}{...}+ commands,
which were ignored by default.
(Also note that cutting macros are placed inside \verb+%HEVEA+ comments,
The \verb+\cuthere+ macro can be used to put some document parts into
This may prove appropriate for long cover pages or abstracts that would
\documentclass{article}
\begin{abstract} A big abstract \end{abstract}
Then, you make the abstract go to its own file as it was a cutting
\documentclass{article}
\usepackage{hevea}
\cuthere{\cuttingunit}{Abstract}
\begin{abstract} A big abstract \end{abstract}
(Note that, this time, cutting macros appear unprotected in the
source. However, \LaTeX{} still can process the document, since the
\texttt{hevea} package is loaded).
In this section we show how to alter some details of \hacha{}
behavior.
When invoked as \texttt{hacha \textit{doc}.html},
\hacha{} produces a \texttt{index.html} table of links file that
sets the name of  the current output file name as \textit{name}.
Consider a document cut at the section level, which contains the
Then, section ``Important section'' can be referenced from
an \hevea{} unaware \html{} page by~:
\ifhevea
If you are reading the \html{} version of this manual, you may check
that wou are now reading file ``\texttt{cutname.html}''.
This particular file name has been specified from the source
When \hacha{} creates a web page from a given sectional unit,
the title of this page normally is the name of the sectional unit.
``Cutting your document into pieces with \hacha''.
\verb+\htmlprefix{\hevea{} Manual: }+ in the document,
``\hevea{} Manual: Cutting your document into pieces with \hacha''
and the title of all other pages would show the same prefix.
The command \verb+\toplinks{+\textit{prev}\verb+}{+\textit{up}\verb+}{+\textit{next}\verb+}+ instructs \hacha{}  to put links to a
\item The arguments
notice that these argument are processed (see section~\ref{urlareprocessed}).
This feature can prove useful to
relate documents that are generated independantly by
\hevea{} and \hacha{}.
Part of a document goes to a separate file whem enclosed in a
the argument \textit{title} is used as the title of the introduced
\paragraph{A small quiz}
\item What is black?
\item What is white?
\item What is Dylan?
\paragraph{Quiz answers}\label{answers}
\item Black is black.
\ifhevea The example yields:
\paragraph{A small quiz}
\item What is black?
\item What is white?
\item What is Dylan?
\paragraph{Quiz answers}\label{answers}
\item Black is black.
\comindex{aname}\comindex{ahrefloc}
references with the \verb+\aname+ and \verb+\ahrefloc+ commands
will be more practical most of the time.
\hevea{} output language being \html{}, it is normal for users to insert
\hevea{} provides high-level commands for doing this.
Users are advised to use these macros in the first place,
because it is easy to write incorrect \html{} and that writting
\html{} directly may interfeer in nasty ways with \hevea{} internals.
A few commands for hyperlink  management and included images
commands have approriate equivalents defined by the \texttt{hevea}
package (see section~\ref{heveastyle}).
Hence, a document that relies on these high-level commands
still can be typeset by \LaTeX{}, provided it loads the \texttt{hevea}
package.
\comindex{ahref}\comindex{ahrefurl}\comindex{footahref}\comindex{ahrefloc}
\comindex{aname}
\multicolumn{1}{c}{Macro} & \multicolumn{1}{c}{\hevea} &
\verb+\ahref{+\textit{url}\verb+}{+\textit{text}\verb+}+ &
echo \textit{text}\\ \hline
\verb+\footahref{+\textit{url}\verb+}{+\textit{text}\verb+}+ &
\verb+\ahrefurl{+\textit{url}\verb+}+ &
\verb+\ahrefloc{+\textit{label}\verb+}{+\textit{text}\verb+}+ &
echo \textit{text}\\ \hline
\verb+\aname{+\textit{label}\verb+}{+\textit{text}\verb+}+ &
make \textit{text} an hyperlink target with label \textit{label} &
echo \textit{text}\\ \hline
& insert \textit{url} as an image, \textit{attr} are attributes in the
\multicolumn{2}{p{.6\linewidth}}{produce a home-dir url both for output and links, output aspect is: ``\home{\textit{text}}''}
\label{urlareprocessed}It is important to notice that all arguments
my home page, (\verb+http://pauillac.inria.fr/~maranget/index.html+),
\ahref{http://pauillac.inria.fr/\home{maranget}/index.html}{his home page}
\verb+\ahref{\verb" ... /~maranget/..."}{his home page}+ does not
Fortunately, the \texttt{url} package provides a very convenient
\verb+\url+ command that acts like \verb+\verb+ and can appear in
(unfortunately, this is not the full story, see section~\ref{urlpackage}).
Hence, provided the \texttt{url} package is loaded,
\ahref{\url{http://pauillac.inria.fr/~maranget/index.html}}{his home page}
\urldef{\lucpage}{\url}{http://pauillac.inria.fr/~maranget/index.html}
\ahref{\lucpage}{his home page}
It may seem complicated, but this is a safe way to have a
document processed both by \LaTeX{} and \hevea{}.
because users may sometime want urls to be processed and some other
Moreover, \hevea{} (optionnaly) depends on only one third party package:
\texttt{url}, which as correct as it can be and well-written.
In case the \verb+\url+ command is undefined
\verb+\ahref+, \verb+\ahrefurl+ and \verb+\footahref+, thereby
some compatibility with older versions of \hevea.
Note that this usage of \verb+\url+ is deprecated.
\subsubsection{\html{} style colors}\label{color:high}
\hevea{} should be done using the \texttt{color} package (see
section~\ref{color:package}).
However,one can also specify text color using special type style declarations.
The \texttt{hevea.sty} style file
define no equivalent for these declarations, which therefore are for
\hevea{} consumption only.
Those declarations follow \html{} conventions for colors.
%HEVEA\black
\verb+\black+,
%HEVEA\fuchsia
\verb+\fuchsia+,
%HEVEA\aqua
\verb+\aqua+
\comindex{htmlcolor}Additionally, the current text color can be
changed by the declaration \verb+\htmlcolor{+{\it number}\verb+}+,
where {\it number} is a six digit hexadecimal number specifying a
color in the RGB space.  For instance, the following declarations
change font color to dark gray:%HEVEA{\htmlcolor{404040}%
becomes handy when one has images both in Postscript and GIF format.
As explained in section~\ref{substimage}, Postscript images can
command from the \texttt{epsf} package.
For instance, if \texttt{screenshot.ps} is an encapsulated  Postscript
file, then a \texttt{doc.tex} document can include it by:
We may very well also have a GIF version of the screenshot image
Then, for \hevea{} to include a link to the GIF image in its
to define the \verb+\epsfbox+ command in the \texttt{macro.hva} file
Then \hevea{} has to be run as:
# hevea macros.hva doc.tex
Since it has its own definition of \verb+\epsfbox+, \hevea{} will
If another naming scheme for image files is prefered, there are
For instance, assume that Postscript files are of the kind
Then, images can be included using
\newcommand{\includeimage}[1]{\ifhevea\imgsrc{#1.gif}\else\epsfbox{#1.ps}\fi}
Note that this method uses the \texttt{hevea} boolean register (see
section~\ref{heveabool}).
If one does not wish to load the \texttt{hevea.sty} file,
one can adopt the slightly more verbose definition:
When the Postscript file has been produced by
mechanism (see section~\ref{imagen}),
which will translate the image back from
Postscript to bitmap format and will thus degrade it.
\subsection{The \texttt{rawhtml} environment}\label{rawhtml}
\envindex{rawhtml}
Any text enclosed between \verb+\begin{rawhtml}+ and
\verb+\end{rawhtml}+ is echoed verbatim into the \html{} output file.
For avoiding to break \html~element nesting, the \texttt{rawhtml}
environment should be used only at toplevel (i.e. not within another
environment), and it should contain only \html~text that makes sense
(e.g. \verb+\begin{rawhtml}<TABLE><ALIGN=right>\end{rawhtml}+\ldots{}
\verb+\begin{rawhtml}</TABLE>\end{rawhtml}+ is
dangerous. In that case,
use the internal macros \verb+\@open+ and \verb+\@close+ of
When \hevea{} is given the command line option ``\texttt{-O}'',
checking and optimization of text-level elements in the whole document
takes place.
As a consequence, incorrect \html{} introduced by using the \texttt{rawhtml}
environment may be detected at a later stage.
\texttt{hevea.sty} style file (see section~\ref{heveastyle}).
\subsection{Internal macros}\label{internal}
In this section a few of \hevea{} internal macros are
Internal macros occur at the final expansion stage of \hevea{} and
their behavior may change from one version of \hevea{} to another and
because using them incorrectly easily
crashes \hevea.
\item Internal macros
are almost mandatory for writing supplementary base style files.
\item Casual usage is a convenient (but dangerous) way to finely control
\item Knowing a little about internal macros helps in understanding how
\hevea{} works.
The general principle of \hevea{} is that \LaTeX{} environments
More specifically, such block level elements are opened by the
internal macro \verb+\@open+ and closed by the internal macro
As a special case, \LaTeX{} groups \verb+{+\ldots{} \verb+}+
get translated into \html{} \emph{groups}, which are shadow block-level
\index{"@print@\texttt{\char92"@print}|defocc}
\index{"@getprint@\texttt{\char92"@getprint}|defocc}
\index{"@hr@\texttt{\char92"@hr}|defocc}
\index{"@open@\texttt{\char92"@open}|defocc}
\index{"@close@\texttt{\char92"@close}|defocc}
\index{"@style@\texttt{\char92"@style}|defocc}
\index{"@nostyle@\texttt{\char92"@nostyle}|defocc}
\index{"@fontsize@\texttt{\char92"@fontsize}|defocc}
\index{"@fontcolor@\texttt{\char92"@fontcolor}|defocc}
It is important to notice that primitive arguments \emph{are}
some characters cannot be given directly (e.g. \verb+#+ and
\item[{\tt\char92 @print\char123}{\it text}{\tt\char125}]
Echo \textit{text} verbatim.
\item[{\tt\char92 @getprint\char123}{\it text}{\tt\char125}]
Process \textit{text} using a special output mode that strips off
\html~tags. This macro is the one to use for processed attributes of
\item[{\tt\char92 @hr[}{\it attr}{\tt]\char123}{\it
width}{\tt\char125\char123}{\it height}{\tt\char125}]
directly (e.g. \verb+SIZE=3 HOSHADE+), while \textit{width} and
\textit{height} are length arguments given in the \LaTeX{} style
\item[{\tt\char92 @open\char123}{\it BLOCK}{\tt\char125\char123}{\it
attributes}{\tt\char125}]
Open \html{} block-level element \textit{BLOCK} with attributes
uppercase.
As a special case \textit{BLOCK} may be the empty string, then a \html{}
\item[{\tt\char92 @close\char123}{\it BLOCK}{\tt\char125}]
Note that \verb+\@open+ and \verb+\@close+ must be properly balanced.
Text-level elements are managed differently. They are not seen
as blocks that must be closed explicitely and they are replaced by the
internal text-level declarations \verb+\@style+, \verb+\@fontsize+ and
delimit the effect of such declarations.
\item[{\tt\char92 @style\char123}{\it SHAPE}{\tt\char125}]
Declare the text shape \textit{SHAPE} (which must be uppercase)
as active. Text shapes are known as font style elements (\verb+I+, \verb+TT+,
etc.) or phrase elements (\verb+EM+, etc.) in the
\html{} terminology, they are part of the more general class of
necessary and closed automatically, when the
The next text-level constructs exhibit similar behavior with respect
\item[{\tt\char92 @fontsize\char123}{\it int}{\tt\char125}]
Declare the text-level element \verb+FONT+ with attribute
\verb+SIZE=+\textit{int} as active. Note that \textit{int} must
be a small integer in the range \texttt{1},\texttt{2}, \ldots{} , \texttt{7}.
\item[{\tt\char92 @fontcolor\char123}{\it color}{\tt\char125}]
Declare the text-level element \verb+FONT+ with attribute
\verb+COLOR=+\textit{color} as active.
Note that \textit{color} must be a color attribute value in the \html{}
style. That is either one of the sixteen conventional colors
\verb+black+, \verb+silver+ etc, or a RGB hexadecimal color specification
Note that the argument \textit{color} is processed, as a consequence
numerical color arguments should be given as \verb+"\#+\textit{XXXXXX}\verb+"+.
\item[{\tt\char92 @nostyle}]
Close active text-level declarations and ignore further text-level
declarations (such as \verb+\@style+, etc).
\index{"@open@\texttt{\char92"@open}}
\index{"@close@\texttt{\char92"@close}}
As a first example of using internal macros, consider the following
excerpt from the \texttt{hevea.hva} file that
color declaration (see section~\ref{color:high}):
\hevea{} does not feature all text-level elements by default.
However one can easily use them with the internal macro
For instance this is how you can make all emphasized text blink:
\index{"@print@\texttt{\char92"@print}}
\index{"@getprint@\texttt{\char92"@getprint}}
\index{"@nostyle@\texttt{\char92"@nostyle}}
command (see section~\ref{hyperlink}), without its optional argument:
Note that \verb+\@open{IMG}{SRC="#1"}+ is not correct,
because the element \verb+IMG+ consists in a single tag, without a
\index{"@nostyle@\texttt{\char92"@nostyle}}
which \hevea{} uses internaly to output \texttt{A} elements.
argument contains the opening tag attributes; while the second element is
By contrast with the \verb+\imgsrc+ exemple above,
tags are emitted inside groups where styles are canceled by using the
\verb+\@nostyle+ declaration.
Such a complication is needed, so as to avoid breaking proper nesting
\index{"@open@\texttt{\char92"@open}}
\index{"@close@\texttt{\char92"@close}}
The \texttt{bgcolor} environment from the \texttt{color} package
locally changes background color (see section~\ref{bgcolor}).
command. In my opinion, such a style of opening block-level elements
\index{"@getcolor@\texttt{\char92"@getcolor}}
The one cell background color is forced with a \verb+BGCOLOR+
Note that the mandatory argument to \verb+\begin{bgcolor}+ is the
background color expressed as a high-level color, which therefore
\verb+\@getcolor+ internal macro from the \texttt{color} package.
as an optional argument. These attributes are the ones of the
\latexsection{Customizing \hevea}
\hevea{} can be controlled by writing \LaTeX{} code. In this section,
we examine how users can change \hevea{} default behavior or add
functionalities. In all this section we assume that a document
\texttt{macros.hva}. That is, \hevea{} is invoked as:
# hevea macros.hva mydoc.tex
\texttt{macros.hva}, using internal commands. This requires a good
working knowledge of both \LaTeX{} and \html.
Usually, one can avoid internal commands, but then, all command
redefinitions interact, sometimes in very nasty ways.
\subsection{Simple changes}
Users can easily change the rendering of some constructs. For
instance, assume that \emph{all} quotations in a text should be
emphasized. Then, it suffices to put the following redeclaration in
\texttt{macros.hva}:
The same effect can be achieved without using any of the internal
\verb+\em+ can be changed elsewhere.
\subsection{Changing defaults for type-styles}\label{customize-style}
\hevea{} default rendering of type style changes is described in
for the font shapes:
\itshape italic shape \slshape slanted shape
\scshape small caps shape \upshape upright shape
By default, \verb+\itshape+ is italics, \verb+\slshape+ is maroon
italics, \verb+\scshape+ is navy blue color and \verb+\upshape+ is no
style at all.
All shapes are mutually exclusive, this means that each shape
declaration cancels the effect of other active shape declarations.
For instance, in the example, small caps shapes is navy blue and not
\itshape italic shape \slshape slanted shape
\scshape small caps shape \upshape upright shape
If one wishes to change the rendering of some of the shapes (say small
caps), then one should redefine the old-style \verb+\sc+ declaration.
For instance, to render small caps as bold fonts, one should
\texttt{macros.hva}.
And now, the shape example above gets rendered as follows:
{\itshape italic shape \slshape slanted shape
\scshape small caps shape \upshape upright shape}
Redefining the old-style \verb+\sc+ is compatible with the cancelation
mechanism, redefining \verb+\scshape+ is not.
Thus, redefining directly \LaTeXe{} \verb+\scshape+ with
\verb+\renewcommand{\scshape}{\@style{B}}+ would yield:
\begin{htmlout}\renewcommand{\scshape}{\@style{B}}
{\itshape italic shape \slshape slanted shape
\scshape small caps shape \upshape upright shape}
Hence, redefining old-style declarations using internal commands
should yield satisfactory output.
However, since cancelation is done at the \html{}
level, a declaration belonging to one component may sometimes cancel the
effect of another that belongs to another component.
Anyway, you might have not noticed it if I had not told you.
\subsection{Changing the interface of a command}\label{customize-let}
Assume for instance that the base style of \texttt{mydoc.tex} is
For running \hevea{}, the \textit{jsc} style can be replaced by
style, but for a few commands whose calling interface is changed.
takes an extra optional argument (which \hevea{} should ignore
However, \hevea{} can process the document as it stands.
One  solution to insert the following lines into \texttt{macros.hva}:
\input{article.hva}% Force document class ``article''
The effect is to replace \verb+\title+ by a new command which
calls \hevea{} \verb+\title+ with the appropriate argument.
\subsection{Checking the optional argument within a command}\label{fullepsfbox}
\hevea{} fully implements \LaTeXe{} \verb+\newcommand+.
That is, users can define commands with an optional argument.
Such a feature permits to write a \verb+\epsfbox+ command that
has the same interface as the \LaTeX{} command and
echoes itself as it is invoked to the \textit{image} file.
To do this, the \hevea{} \verb+\epsfbox+ command has to check
whether it is invoked with an optional argument or not.
This can be achieved as follows~:
{\begin{toimage}\epsfbox{#2}\end{toimage}}%No optional argument
{\begin{toimage}\epsfbox[#1]{#2}\end{toimage}}}%With optional argument
\subsection{Changing the Format of Images}
command, which calls the \verb+\imgsrc+ command~:
{\@imageflush\stepcounter{image}\imgsrc[#1]{\jobname\theimage\heveaimageext}}
That is, you may supply a \html-style attribute to the included image,
as an optional argument to the \verb+\imageflush+ command.
\hevea{} provides direct support for the alternative PNG image file
It suffices to invoke \texttt{hevea} as:
\texttt{\#~hevea~png.hva}~\textit{mydoc.tex}
Beware that transparent colors are not shown correctly by my browser
for PNG images, while they work as advertised for GIF images.
This does not harm as long as the final \html{} document has a white
background color (see Section~\ref{metadef}).
It is possible to translate \LaTeX{} file into other formats than
\html. There are two such formats: plain text and info files.
\html, plain text and info manuals from one (\LaTeX) input file.
To translate into text, invoke \hevea{} as follow:
# hevea -text [-w <width>] myfile.tex
Then, \hevea{} produces \texttt{myfiles.txt} a plain text translation
Additionally, the optional argument \texttt{-w <number>} sets the
72~characters wide.
Nearly every environments have been translated, included lists and tables.
The support is nearly the same as in \html, excepted in some cases
described hereafter.
Most style changes are ignored, because it is hardly
bold fonts, underlinings, nor size change or colors\ldots{}
that puts the text inside quotes, to distinguish it more easily.
Tables with borders are rendered in the same spirit as in \LaTeX{}.
Thus for instance, it is possible to get vertical lines between some
Table rendering can be poor in case of line overflow.
The only way to correct this (apart from changing the tables
For now, maths are not supported at all in text mode. You can get very weird
results with in-text mathematical formulas.
Of course, simple expressions such as subscripts remains readable.
can be read by using \emph{emacs} info mode or the
Please note that \hevea{} translates plain \LaTeX{} to info, and not
You can translate your \LaTeX{} files into info file(s) as follows:
# hevea -info [-w <width>] myfile.tex
Then, \hevea{} produces the file \texttt{myfile.info}, an info
automatically,
the nodes in the others files, which are named \texttt{myfile.info-1},
The optional argument \verb+-w+ has the same meaning as for text output.
The text will be organized in nodes that follow
the pattern of \LaTeX{} sectioning
commands. Menus are created to navigate through the sections easily
A table of content is produced automatically.
References, indexes and footnotes are supported, as they are in
i.e., in \hevea{} case, to sectional units.
As a consequence all cross references lead to sectional unit headers.
\renewcommand{\thesection}{\thepart.\arabic{section}}
\part{Reference manual}
\pdfpart{-17}{Reference manual}\label{referencemanual}
This part follows the pattern of the \LaTeX{} reference
manual~\cite[Appendix~C]{latex}.
\LaTeX{} comments that start with ``\verb+%+'' %
Usually, \hevea{} ignore such comments. However, \hevea{} processes
text that follows ``\verb+%HEVEA+'' %
and some other comments have a specific meaning to it (see
Command names follow strict \LaTeX{} syntax. That is, apart from
\verb+~+, \verb+_+ and \verb+^+, they either are
``\verb+\+'' followed by a single non-letter character or
(and this is the case of many of \hevea{} internal commands), or
terminated by ``\verb+*+'' (starred variants are implemented as plain
arguments. That is, mandatory arguments are enclosed in curly braces
\verb+{+\ldots{} \verb+}+ and braces inside arguments must be properly
balanced.
Optional arguments are enclosed in square brackets \verb+[+\ldots{}
However, \hevea{} does its best to read arguments even when they are
not enclosed in curly braces.
Such arguments are a single, different from ``\verb+\+'', ``\verb+{+''
and ``\verb+ +'', character or
Thus, constructs such as ``\verb+\'ecole+'',
``\verb+$a_1$+'' or ``\verb+$a_\Gamma$+'' are
recognized and processed as ``\'ecole'' ``$a_1$'' and ``$a_\Gamma$''.
Also note that, by contrast with \LaTeX{}, comments are parsed during
argument scanning, as an important consequence brace nesting is also
checked inside comments.
\hevea{} has been improved as regards emulation of complicated
argument passing. That is,
commands and their arguments can now appear in
\hevea{} correctly processes the following source:
\verb+\textbf+ and \hevea{} succeeds in fetching the argument
The above example arguably is no ``legal'' \LaTeX{},
but \hevea{} handles it.
numerous ``clever'' \LaTeX{} tricks that exploits \TeX{} internal
behavior, which \hevea{} does not handle.
the rest of the text alone. While \hevea{} typesets everything using
bold font. Here is \ifhevea\hevea\else\LaTeX\fi{} output:
Note that, in most similar situations, \hevea{} will likely crash.
curly braces and not to think too much the \TeX{} way.
\verb+\end+\textit{env} in place of \verb+\begin{+\textit{env}\verb+}+ and
Fragile commands are not relevant to \hevea{} and \verb+\protect+ is
defined as a null command.
\subsection{Declarations}
Scope rules are the same as in \LaTeX.
I am a bit lost here. However spaces in the output should correspond
to users expectations. Note that, to \hevea{} being
invisible commands is a static property attached to command name.
\subsection{The \texttt{\char92\char92} Command}
The \verb+\\+ and \verb+\\*+ commands are the same, they perform a
line break, except inside arrays where they end the current row.
Optional arguments to \verb+\\+ and \verb+\\*+ are ignored.
The \emph{preamble} starts as soon as \hevea{} starts to operate and
ends with the \verb+\begin{document}+ construct.
arguments to \hevea{}, see section~\ref{comline}).
As a consequence, command and environment  definitions that
\comindex{htmlhead}
In particular one can define a \emph{header} and a \emph{footer}, by using the
\verb+\htmlhead+ and \verb+\htmlfoot+ commands in the preamble.
Those commands register their argument as the header and the footer of
the final \html{} document. The header appears first while the footer
This is mostly useful when \hevea{} output is later cut into pieces by
\hacha{}, since both header and footer are replicated
at the start and end of any file generated by \hacha.
\index{color!of background|see{\texttt{\char92"@bodyargs}}}
\index{"@bodyargs@\texttt{\char92"@bodyargs}}
\index{"@meta@\texttt{\char92"@meta}}\label{metadef}
The \verb+\htmlhead+ command cannot be used for changing anything outside of
One can
change \hevea{} default (empty) atribute for
For instance, you get black text on a white background, when the
following declaration occurs before \verb+\begin{document}+:
\renewcommand{\@bodyargs}{TEXT=black BGCOLOR=white}
\comindex{let}\envindex{rawhtml}
\label{exlet}Similarly, some elements can be inserted into the output file
(Such elements typically are \verb+META+, \verb+LINK+, etc.).
As such text is pure \html{}, it should be included in a
\verb+rawhtml+ environment. For instance, you can specify
\begin{rawhtml}
<META name="Author" content="Luc Maranget">
\end{rawhtml}}
\section{Sentences and Paragraphs}
\subsection{Spacing}
\index{ @`` '' (space)}
\index{spacing|see{`` ''}}
Generally speaking, spaces (and single newline characters) in the
source are echoed in the output.  Browser then manage with spaces and
line-breaks.  Following \LaTeX{} behavior, spaces after commands are
not echoed.  Spaces after invisible commands with arguments are not
echoed either.
However this is no longer true in math mode, see
section~\ref{spacemathref} on spaces in math mode.
\subsection{Paragraphs}
New paragraphs are introduced by one blank line or more.
Paragraphs are not indented. Thus the macros \verb+\indent+ and
\verb+\noindent+ perform no action.
optional arguments) are supported.
Footnotes appear at document end in the \filename{article} style and
at every chapter end in the \filename{book} style.
If the document is then cut into smaller files by \hacha{} (see
section~\ref{hacha}) footnotes may go to a separate file.
\subsection{Accents and special symbols}
the iso-latin1 and symbol character sets, then \hevea{}
outputs such an equivalent.
\html{} pages that show these character sets can be found
in the directory \texttt{\heveaurl/doc/}
at \ahref{iso.html}{\texttt{iso.html}} and
\ahref{symbol.html}{\texttt{symbol.html}}.
Otherwise, \hevea{} usually issues a warning to draw user attention.
Users can then choose their own equivalent for the symbol.
Commands for making accents used in non-English languages, such as
\verb+\'+, work when then produce letters from the iso-latin1 character set.
Otherwise, the argument to the command is not modified (no warning here).
\LaTeX{} can process such documents by loading the package
\verb+\subparagraph+ are defined in base style files.
They accept an optional argument and have starred versions.
\verb+\subsubsection+ show section numbers in sectional unit headings,
provided their \textit{level} is greater than or equal to the current
are the same as in \LaTeX{}.
Furthermore, given a sectional unit {\it secname}, the
counter {\it secname} exists and the appearance of sectional units
numbers can be changed by redefining \verb+\the+{\it secname}.
chapters into alphabetic (uppercase) style:
\renewcommand{\thechapter}{\Alph{chapter}}
When jumping to anchors, browsers put the targeted line on top
Note that \verb+\label+ should not be be placed last in
\hevea{} now generates a table of contents, using a procedure similar
One inserts this table of contents in the main document by issuing
By default, the table of contents shows sectionning units down to the
One can also add extra entries in the table of contents by using
the command \verb+\addcontentslines+, in a way similar
an anchor is defined in the section title and refered to in the
\subsection*{\aname{no:number}{Use \hacha{}}}
\addcontentsline{toc}{subsection}{\ahrefloc{no:number}{Use \hacha{}}}
\subsection*{\aname{no:number}{Use \hacha{}}}
\addcontentsline{toc}{subsection}{\ahrefloc{no:number}{Use \hacha{}}}
However, \hevea{} has a more sophisticated way of producing
A later run of {\hacha} on \hevea{} output file splits it
By contrast with \LaTeX{}, starred sectioning commands generate
Table of contents entries hold the optional argument to sectioning
argument. Section~\ref{hacha} explains how to
control {\hacha}.
\section{Classes, Packages and Page Styles}
Both \LaTeXe{} \verb+\documentclass+ and old \LaTeX{}
\verb+\documentstyle+ are accepted.
Their argument \filename{style} is interpreted by attempting to load a
\filename{style}\texttt{.hva} file (see~\ref{comline} to see where \hevea{}
searches for files).
Presently, only the style files \texttt{article.hva}, \texttt{seminar.hva},
\texttt{book.hva} and \texttt{report.hva} exist, the latter two
If one of the reckognized styles has already been loaded at the time when
\verb+\documentclass+ or
\verb+\documentstyle+ is executed, then no attempt to load a style
file is made. This allows to override the document style file by
giving one of the four recognized style files of \hevea{} as command
line arguments (see section~\ref{otherbase}).
Conversely, if \hevea{} attempt to load \filename{style}\texttt{.hva}
fails, then a fatal error is flagged, since it can be sure
that the document cannot be processed.
\subsection{Packages and Page Styles}\label{usepackage}
\hevea{} reacts to
\verb+\usepackage[+\textit{options}\verb+]{+\textit{pkg}\verb+}+ in
\verb+\usepackage+ command with its arguments gets echoed to the
\item \hevea{} attempt to load file \textit{pkg}\texttt{.hva},
(see section~\ref{search:path} on where \hevea{} searches for files).
Note that \hevea{} will not fail if it cannot load
\textit{pkg}\texttt{.hva} and that no warning is issued in that case.
The \hevea{} distribution contains implementations of some packages,
such as \texttt{verbatim}, \texttt{colors}, \texttt{graphics}, etc.
In some situations it may not hurt at all if \hevea{} does not
implement a package, for instance \hevea{} does not provide an
implementation for the packages \texttt{isolatin1} or
Users needing an implementation of a package that is widely used and
available are encouraged to contact the
\ahref{\url{mailto:Luc.Maranget@inria.fr}}{author}.
Experienced users may find it fun to attempt to write package
\subsection{The Title Page and Abstract}
All title related commands exist, with the following peculiarities:
to appear in \html{} document header.
  \item When not present the date is left empty. The \verb+\today+
command generates will work properly only if \texttt{hevea} is invoked
with the \verb+-exec xxdate.exe+ option.
Otherwise \verb+\today+ generates nothing and a warning is issued.
The \verb+abstract+ environment is present is all base styles,
\section{Displayed Paragraphs}
Displayed-paragraph environments translate to block-level
\hevea{} implements the \verb+center+, \verb+flushleft+ and
\hevea{} also implements the corespondant \TeX{} style declaration
\verb+\centering+ \verb+\raggedright+ and \verb+\raggedleft+,
but these declarations may not work as expected, when they do not
appear directly inside a displayed-paragraph environment or inside an array
The \verb+quote+ and \verb+quotation+ environments are the same thing: they
As a consequence, no control is allowed on the appearances of these
environments.  More precisely optional arguments to \verb+\item+ do not
However, customized lists can be produced by using the
Arguments to \verb+\begin{list}+ are handled as follows:
The first argument {\it default\_label} is the label generated by an
The second argument, {\it decls} is a sequence of declarations.
In practice, the following declarations are relevant:
\item[\texttt{\char92 usecounter\{}\textit{counter}\texttt{\}}]
\item[\texttt{\char92 renewcommand\{\char92
Thus, users can change label formatting by redefining
The default definition of \verb+\makelabel+ simply echoes \textit{label}.
As an example, a list with an user-defined counter can be defined as
\begin{list}{\thecoucou}{%
  {\thecoucou}
Inside \verb+verbatim*+, spaces are replaced by underscores (``\verb*+ +'').
\section{Mathematical Formulas}
\subsection{Math Mode Environment}
The three ways to use math mode (\verb+$+\ldots\verb+$+,
\verb+\begin{math}+\ldots\verb+\end{math}+) are supported.
The three ways to use display math mode (\verb+$$+\ldots\verb+$$+,
\verb+\begin{displaymath}+\ldots\ \verb+\end{displaymath}+) are also
Furthermore, \verb+\ensuremath+ behaves as expected.
The \verb+equation+, \verb+eqnarray+, \verb+eqnarray*+ environments
Additionally, numbering can be suppressed in one row of an
\verb+eqnarray+, using the \verb+\nonumber+ command.
Math mode is not as powerful in \hevea{} as in \LaTeX{}.  The
limitations of math mode can often be surpassed by using math display
mode.  As a matter of fact, math mode is for in-text formulas. From
the \html{} point of view, this means that math mode does not close
the current flow of text and that formulas in math mode must be
formulas can be rendered using block-level elements.  This means that
\hevea{} have much more possibilities in display context than inside
normal flow of text.  In particular, stacking text elements one above
For instance compare how \hevea{} renders
\verb+$\frac{1}{\sum_{i=1}^{\infty}$+
as: $\frac{1}{\sum_{i=1}^{\infty} i^i}$, and 
\verb+$$\frac{1}{\sum_{i=1}^{\infty}$$+ as:
$$\frac{1}{\sum_{i=1}^{\infty} i^i}$$
\hevea{} admits, subscript (\verb+_+), superscripts (\verb+^+) and
fractions (\verb+\frac{+{\it numer}\verb+}{+{\it denom}\verb+}+).
By contrast, when not in display mode, \hevea{} uses only
simple subscripts and superscripts, such as \verb+x_i+ or \verb+x^2+,
are always rendered using the \verb+SUB+
and \verb+SUP+ text-level elements and their appearance should be correct
When occurring outside math mode, characters \verb+_+ and \verb+^+ act as
ordinary characters and get echoed to the output. However, a warning
The ``root'' symbol is not necessary, thanks
to fractional exponents. For instance, the \verb+\sqrt+ command can be
fragment: \verb"$$\sqrt[3]{\frac{1}{n!}} + \sqrt{\pi}$$" gets rendered
\sqrt[3]{\frac{1}{n!}} + \sqrt{\pi}
strange for the latter two.
\subsection{Mathematical symbols}
Symbols that can be printed using browser iso-latin1 or symbol fonts
Attempting to translate them will thus generate ``Unknown macro''
Then, users can choose their own replacement for these symbols.
These personal definitions are best placed in an ad-hoc style file,
given as a command line argument to \hevea{}.
A suggested replacement is a mix of colors and available
For instance, \hevea{} cannot render the \verb+\leadsto+ symbol, but it
can be defined as a red arrow  by:
\newcommand{\leadsto}{{\red\rightarrow}}
$$\newcommand{\leadsto}{{\red\rightarrow}}
When given the \verb+-nosymb+ option, \hevea{} silently replaces
symbols that cannot be rendered by iso-latin1 only by text equivalents.
These equivalents are English words by default, or French words when the
\verb+-francais+ option is set.
Log-like functions and variable sized-symbols are recognized and their
Subscript and superscript placement can be changed using the
Big delimiters are also handled.
\comindex{textstackrel}\comindex{textunderline}\comindex{textoverline}
The commands \verb+\stackrel+,  \verb+\underline+ and \verb+\overline+
In text mode, these macros call the \verb+\textstackrel+,
\verb+\textunderline+ and \verb+\textoverline+ macros.
These macros perform the following default actions, which can be
changed by redefining them:
\item[\texttt{\char92 textstackrel}] Performs ordinary superscripting.
\item[\texttt{\char92 textunderline}] Underlines its argument, using the
\item[\texttt{\char92 textoverline}] Sends a warning message to the
console and echoes its argument in the output.
\index{math accents}
Math accents (\verb+\hat+, \verb+\tilde+, etc.) are not
handled\label{mathaccents} by default.
However, the distribution includes a \texttt{mathaccents.hva} file
that provides definitions for almost all math accents commands,
except \verb+\check+ and \verb+\breve+.
Rendering is far from perfect and changes from display to text mode.
More precisely, the accent is put (too far) above the symbol in display mode,
and as an ordinary superscript in text mode.
\ifhevea{\input{mathaccents.hva}For instance, given the formula
If such a rendering is considered too ugly,
one should not load the \texttt{mathaccents.hva} file and write
issue color changes:
\ifhevea With such definitions the previous example now appears as:
Of course, such a trick probably requires looking closely at \html{}
output to check whether the document is still understandable or not.
It may be better to stay with a poorly formatted document that remains
closer to universally understood  notations for mathematics.
\subsection{Spacing}\label{spacemathref}
\index{ @`` '' (space)!after macro!in math|defocc}
By contrast with \LaTeX{}, space in the input matters in math mode.
One or more spaces are translated to one space.
spaces after commands (such as \verb+\alpha+) are echoed
except for invisible commands (such as \verb+\tt+).
This allows users to control space in their formulas, output being
near to what can be expected.
Explicit spacing commands (\verb+\,+, \verb+\!+, \verb+\:+ and
the others two output one space.
\subsection{Changing Style}
Letters are italicized inside math mode and this cannot be
changed. The appearance of
other symbols can be changed using
\LaTeXe{} style changing commands (\verb+\mathbf+, etc.).
The commands \verb+\boldmath+ and \verb+\unboldmath+ are not
recognized. Whether symbols belonging to the symbol font are affected
by style changes or not is browser dependent.
The \verb+\cal+ declaration and the \verb+\mathcal+ command (that
yield calligraphic letters in \LaTeX) exist. They yield red letters by
Observe that this does not corresponds directly to how \LaTeX{} manage style
in math mode and that, in fact, style cannot really change in math mode.
Math style changing declarations \verb+\displaystyle+ and
\verb+\textstyle+ do nothing when \hevea{} is already in the requested
otherwise they issue a warning.
This is so because \hevea{} implements displayed maths as tables,
which require to be both opened and closed and introduce line breaks
perform type size changes.
\subsection{Defining Commands}\label{usermacro}
\hevea{} understands command definitions given in \LaTeX{} style. Such
These three constructs accept the same arguments and have the same
command with one optional argument.
However, \hevea{} is more tolerant: if command
{\it name} already exists, then a subsequent \verb+\newcommand{+{\it
name}\verb+}+\ldots is ignored.  If macro {\it name} does not exists, then
name}.  In both cases, \LaTeX{} would crash, \hevea{} just issues
The behavior of \verb+\newcommand+ allows to shadow document
This is easily done by grouping the shadowing definition  in a
specific style file given as an argument to \hevea{} (see section~\ref{heveaonly}).
Conversely, changes of base macros (i.e., the ones that \hevea{}
Scoping rules apply to macros, as they do in \LaTeX{}.
are local to the scope they occur.
It is worth noticing that \hevea{} also partly implements \TeX{} definitions
section~\ref{texmacro} for details.
\hevea{} accepts environment definitions and redefinitions
New theorem-like environments can also be introduced and redefined,
Note that, by contrast with plain environments definitions,
\verb+\newcounter{+\textit{cmd}\verb+}+ creates a macro
\verb+\the+\textit{cmd} that outputs the counter value.
Then the \verb+\the+\textit{cmd} command can be redefined.
For instance, section numbering can be turned into alphabetic style by:
Note that \TeX{} style for counters is not supported at all and that using
this style will clobber the output. However, \hevea{} implements
the \textit{calc} package that makes using \TeX{} style for counters
useless in most situations (see section~\ref{calc}).
\subsection{The \texttt{ifthen} Package}\label{ifthen}
The \texttt{ifthen} package is partially supported.
\verb+\lengthtest+ test expression, which is
As a consequence, \hevea{} accepts the following example from the
\LaTeX{} manual:
\newcounter{ca}\newcounter{cb}%
  \setcounter{ca}{#1}\setcounter{cb}{#2}%
  \whiledo{\not\(\value{ca}= \value{cb}\)}%
    {\ifthenelse{\value{ca}>\value{cb}}%
      {\addtocounter{ca}{-\value{cb}}}%
      {\addtocounter{cb}{-\value{ca}}}%
    gcd(\arabic{ca}, \arabic{cb}) = }%
  \arabic{ca}.}%
\newcounter{ca}\newcounter{cb}%
  \setcounter{ca}{#1}\setcounter{cb}{#2}%
  \whiledo{\not\(\value{ca}= \value{cb}\)}%
    {\ifthenelse{\value{ca}>\value{cb}}%
      {\addtocounter{ca}{-\value{cb}}}%
      {\addtocounter{cb}{-\value{ca}}}%
    gcd(\arabic{ca}, \arabic{cb}) = }%
  \arabic{ca}.}%
Additionally, a few boolean registers are defined by \hevea{}.
Some of them are of interest to users.
\item[\texttt{hevea}] Initial value is \texttt{true}.
The \texttt{hevea.sty} style file also defines this register with
\item[\texttt{mmode}] This register value reflects \hevea{} operating
mode, it is \textit{true} in math-mode and \textit{false} otherwise.
\item[\texttt{display}]  This register value reflects \hevea{} operating
\item[\texttt{french}] \boolindex{french}This register value reflects the \verb+-french+
command line option internally (see Section~\ref{heveaoptions}).
When set false, \hevea{} does not insert its footer ``\emph{This
document has been translated by \hevea}''.
Finally, note that \hevea{} also recognized à la \TeX{} conditional
macros (see section~\ref{texcond}). Such macros are fully compatible
with the boolean registers of the \texttt{ifthen} package, as it is
the case in \LaTeX.
Figures and tables are put where they appear in source, regardless of
their placement arguments.
They are outputed  inside a \verb+BLOCKQUOTE+ element and they are
separated from enclosing text by two
Captions and cross referencing are handled.
However captions are not moved at end of figures: instead, they appear
where the \verb+\caption+ commands occur in source code.
figure related counters (such as \verb+topnumber+) exist but are useless.
Marginal notes are not handled and the \verb+\marginpar+ command does
probably define it as a null command:
\subsection{The \texttt{array} and \texttt{tabular}
environments}\label{arraydef}
\verb+TABLE+ element, rendering is satisfactory in most (not too
complicated) cases.
By contrast with \LaTeX{},
some of the array items always are typeset in display mode.
Whether an array item is typeset in display mode or not depends upon
its column specification,
the \verb+l+, \verb+c+ and~\verb+r+ specifications open display mode
The \verb+l+, \verb+c+,\verb+r+ and~\verb+@+ specifications
disable word wrap, while the \verb+p+~specification enables it.
Entries in a column whose specification is \verb+l+ (resp. \verb+c+ or
\verb+r+) get left-aligned (resp. centered or right-aligned)
in the horizontal direction.
They will get top-aligned in the vertical direction if there are
other column specifications in the
same array that specify vertical alignement constraints
(such as ``\verb+p{+\textit{wd}\verb+}+'', see below).
Otherwise, vertical alignement is unspecified.
Entries in a column whose specification is \verb+p{+{\it wd}\verb+}+
get left-aligned in the horizontal direction and
top-aligned in the vertical direction
and a paragraph break reduces to one line break inside them.
This is the only occasion where
\hevea{} makes a distinction between LR-mode and paragraph mode.
Also observe that the length argument \textit{wd} to the \verb+p+
specification is ignored.
Some \LaTeX{} array features are not supported at all:
\item Optional arguments to \verb+\begin{array}+ and
\item Spacing between columns is different.
\item \verb+@+ formatting specifications in \verb+\multicolumn+
specification, then the array is shown with borders.
\item The command \verb+\hline+ does nothing if the array has borders
\verb+\extracolsep+ issues a warning and ignores its argument.
recognized and gets renderered as an \html{} table with an advisory
width attribute.
By default, \hevea{} implements the \texttt{array} package
(see \cite[Section~5.3]{latexbis} and section~\ref{arraypack} in this
document), which significantly extends the
\verb+array+ and \verb+tabular+ environments.
\hevea{} uses some of the ancillary files generated by \LaTeX.
cross-referencing information, such as figure or section numbers.
If this file is present, \hevea{} reads it and put such numbers (or
file is not present, or if the \texttt{hevea} command is given the
``\texttt{-fix}'' option, \hevea{} will instead use \texttt{.haux}
\item[\protect\texttt{.haux}] Such files are \hevea{} equivalents of
\texttt{.aux} files. Indeed, they are simplified \texttt{.aux} files.
As a consequence, two runs of \hevea{} might be needed to get cross
contents. It is produces while reading the \texttt{.haux} file.
As consequence a table of contents is available only when the
\texttt{.haux} file is read.
\BibTeX{}. It is read by the \verb+\bibliography+ command.
\hevea{} computes its own indexes, using \texttt{.hidx} files for
Index formatting significantly departs from the one of \LaTeX{}.
Again, several runs of \hevea{} might be needed to get indexes right.
\noindent\hevea{} does not fail when it cannot find an auxiliary file.
When another run of \hevea{} is needed, a warning is issued,
and it is user's responsability to rerun \hevea{}.
provided makes \hevea{} rerun itself.
The \LaTeX{} \verb+\label+ and \verb+\ref+ are changed by \hevea{}
into {\html} anchors and local links.
Spaces in the arguments to these commands are better avoided.
Additionally, numerical references to sectional units, figures,
Numerical references to pages (such as generated by \verb+\pageref+)
cross-referencing information can be computed in two different, mutually
on whether \LaTeX{} has been previously run or not:
\filename{mydoc}\texttt{.aux}, then cross-referencing information is extracted
from that file. Of course, the \filename{mydoc}\texttt{.aux} file
has to be up-to-date, that is,
(For \hevea{} needs, one run is probably sufficient).
\item If no \filename{mydoc}\texttt{.aux} file exists, then \hevea{}
\filename{mydoc}\texttt{.haux}.
When using its own \filename{mydoc}\texttt{.haux} file,
\hevea{} will output a
new \filename{mydoc}\texttt{.haux} file at the end of its processing.
This new  \filename{mydoc}\texttt{.haux} file contains actualized
Hence, in that case, \hevea{} may need to run twice to get
Note that, just like \LaTeX,
\hevea{} issues a warning then the cross-referencing information it
generates differs from what it has read at start-up, and that it does
not fail if \filename{mydoc}\texttt{.haux} does not exist.
Observe that if a non-correct \filename{mydoc}\texttt{.aux} file is
present, then cross-references will apparently be wrong. However the
\subsection{Bibliography and Citations}
The \verb+\cite+ macro is supported. Its optional argument is
correctly handled. Citation labels  are extracted from the
\texttt{.aux} file if present, from the \texttt{.haux} file otherwise.
Note that these labels are put there by \LaTeX{} in the first case,
and by \hevea{} in the second case, when they process the
The \verb+\bibliography+ command is
recognized, it loads the \texttt{.bbl} file which should thus
have been generated before, using the appropriate combination of
The \verb+thebibliography+ environment is recognized.
The \verb+\nocite+ and \verb+\bibliographystyle+ macros exist and do
exactly the same operation of searching (and then processing) a file,
whose name is given as an argument.
See section~\ref{comline} on how \hevea{} searches files.
However, in the case of the \verb+\include+ command, the file is
searched only when previously given as an argument to
\index{argument!of input@of \texttt{\char92 input}}
\item \TeX{} syntax for \verb+\input+ is not supported. That is,
\item If \textit{filename} is excluded with the \verb+-e+ command line
option (see section~\ref{heveaoptions}),
then \hevea{} does not attempt to load \textit{filename}.
echoes \verb+\input{+\textit{filename}\verb+}+ and
\textit{image} file. This sounds complicated, but this is what you want!
\item \hevea{} does not fails when it cannot find
a file, it just issues a warning.
Glossaries are not handled (who uses them ?) and the \verb+theindex+
Instead, indexes are formatted using special
By default indexes are formated in two columns, one may change the
number of columns by setting the value of the \texttt{indexcols} counter.
As with \LaTeX{}, two runs of \hevea{} are normally needed to format
Note that two packages for multiple indexes are implemented
The \verb+\typeout+ command echos its argument on the
terminal, macro parameter \verb+#+\textit{i} are replaced by their values.
The advisory line breaking command \verb+\linebreak+
will produce a line break if it has no argument or if its optional
except inside arrays where the close the current row.
Their optional argument is ignored.
All other line breaking commands, declarations or environments are
They are no pages in the physical sense in \html. Thus, all these
\section{Lengths, Spaces and Boxes}
All length commands are ignored, things go smoothly when \LaTeX{} syntax is
which are null macros).
Of course, if lengths are really important to the document, rendering
Note that \TeX{} length syntax is not at all recognized. As a
Users can correct such misbehavior by adopting \LaTeX{} syntax, here
\subsection{Space}\label{spaces}
The \verb+\hspace+, \verb+\vspace+ and \verb+\addvspace+ spacing
arguments.  Such arguments get converted to a number of non-breaking
spaces or line breaks.
Basically, the value of \verb+1em+ or \verb+1ex+ is one space or one
\hevea{} cannot interpret more complicated length arguments
or perform negative spacing.
In these situations, a warning is issued and no output is done.
Spacing commands without arguments are recognized.
The \verb+\enspace+, \verb+\quad+ and \verb+\qquad+ commands output
one, two and four non-breaking spaces, while the \verb+\smallskip+,
Stretchable lengths do not exist, thus the \verb+\hfill+ and
\verb+\vfill+ macros are undefined.
Box contents is typeset in text mode (i.e., non-math and non-display
Both \LaTeX{} boxing commands \verb+\mbox+ and \verb+\makebox+
However  \verb+\makebox+ generates a specific warning, since \hevea{}
ignore the length and positioning instructions given as optional
Similarly, the boxing with frame \verb+\fbox+ and \verb+\framebox+
\verb+\framebox+ issues a warning.
table with borders. Otherwise, \verb+\fbox+ calls the \verb+\textfbox+
command, which issues a warning and typesets its argument
Users can alter the behavior of \verb+\fbox+ in non-display mode by
Boxes can be saved for latter usage by storing them in {\em bins}.
Then some text can be saved into {\it cmd} by
optional arguments.
\subsection{The \texttt{picture} environment and the \texttt{graphics}
Package}
It is possible to have pictures and graphics processed by
In the case of the \texttt{picture} environment
it remains users responsability to explicitly choose
source chunks that will get rendered as GIF images.
In the case of the commands from the \texttt{graphics} package,
this choice is made by \hevea.
In both cases, the \texttt{imagen} script has to be run by hand.
(However, note that \hevea{} runs \texttt{imagen} when given the
\multiput(10,7)(10,0){5}{\addtocounter{cms}{1}\makebox(0,0)[b]{\arabic{cms}}}
\thicklines
by \hevea:
  {cms}{1}\makebox(0,0)[b]{\arabic{cms}}}
\thicklines
\label{graphics}\index{image inclusion!in Postcript}
All commands from the graphics package are implemented using the
More precisely, the outermost invocations of
the \verb+\includegraphics+, \verb+\scalebox+,
be one GIF image per outermost invocation of these commands.
For instance, consider a document \texttt{doc.tex} that
loads the \texttt{graphics} package and that includes some (scaled)
\scalebox{.5}{\includegraphics{round.ps}}
\scalebox{.75}{\includegraphics{round.ps}}
\includegraphics{round.ps}
# hevea doc.tex
yields \html{} that basically consists in three image links,
\ifhevea
\scalebox{.5}{\includegraphics{round.ps}}
\scalebox{.75}{\includegraphics{round.ps}}
\includegraphics{round.ps}
\subsection{The \texttt{color} Package}\label{color}\index{color}\label{color:package}
\hevea{} partly implements the \texttt{color} package.
\verb+\textcolor+. Other commands from the \texttt{color} package do
colors \showcolor{black}, \showcolor{white},
\showcolor{cyan}, \showcolor{yellow} and \showcolor{magenta} are
model used, and \textit{spec} is the color specification according to
Defined colors are used by the declaration
\verb+\textcolor{+\textit{name}\verb+}{+\textit{text}\verb+}+, which
change text color.
Please note that, the \verb+\color+ declaration
accepts color specifications directly
The \verb+\textcolor+ command has a similar feature.
As regards color models, \hevea{} implements the \texttt{rgb},
In those models, color specifications are floating point numbers less
than one.
specification are just names\ldots{}
\textcolor[named]{Peach}{Peach},
\textcolor[named]{Mahogany}{Mahogany},
\textcolor[named]{CarnationPink}{CarnationPink},
\textcolor[named]{Rhodamine}{Rhodamine},
\textcolor[named]{Fuchsia}{Fuchsia},
\textcolor[named]{Orchid}{Orchid},
\textcolor[named]{DarkOrchid}{DarkOrchid},
\textcolor[named]{Aquamarine}{Aquamarine},
\textcolor[named]{Black}{Black},
\item Specify the named color model as an optional argument to
\item Use the names directly
(\hevea{} implements the \texttt{color} package with
That is:
\verb+\definecolor{rouge-brique}{named}{BrickRed}\textcolor{rouge-brique}{Text as a brick}+.
\item \verb+\textcolor[named]{BrickRed}{Text as another brick}+.
\item \verb+\textcolor{BrickRed}{Text as another brick}+.
\ifhevea Which yields:
\textcolor{rouge-brique}{Text as a brick}.
\item \textcolor[named]{BrickRed}{Text as another brick}.
\item \textcolor{BrickRed}{Text as another brick}.
Colors should be used carefully. Too many colors
hinders clarity and some of the colors may not be readable on the
document background color.
the \verb+\colorbox+ command for changing the background color inside
a paragraph.
However, \hevea{} features a
\texttt{bgcolor} environment, for changing the backgroud color of some
Hence the following source yield a paragraph with a red background:
\color{yellow}Yellow letters on a red backgroud
\color{yellow}Yellow letters on a red backgroud
optional argument that is used as an attribute for this \verb+TABLE+
\color{red}Red letters on a yellow backgroud
will be typeset on a yellow background and without padding:
\color{red}Red letters on a yellow backgroud
\index{"@getcolor@\texttt{\char92"@getcolor}|defocc}
That is, they are either one of the sixteen conventional colors black,
silver etc., or a RGB hexadecimal color specification of the form
One changes the high-level \emph{high-color} into a low-level color by
\verb+\@getcolor{+\emph{high-color}\verb+}+.
arguments to the \verb+\@fontcolor+ internal macro.
An example of \verb+\@getcolor+ usage can be found at the end of
\subsection{Changing the Type Style}\label{type-style}
All \LaTeXe{} declarations and environments for changing type style
are recognized. Aspect is rather like \LaTeXe{} output, but there is
no guarantee.
As \html{} does not provide the same variety of type styles as
the slanted shape yields maroon italics and small caps yields navy blue.
``\verb+{\slshape slanted shape} {\scshape small caps shape}+'' yields:
``{\slshape slanted shape} {\scshape small caps shape}''
Here is how \hevea{} implements text-style declarations by default:
\newcommand{\heveastyle}[2]{{\ifhevea#1\fi#2}}
\verb+\itshape+ &  \heveastyle{\itshape}{italics}\\
\verb+\slshape+ &  \heveastyle{\slshape}{maroon italics}\\
\verb+\scshape+ &  \heveastyle{\scshape}{navy blue}\\
\verb+\upshape+ &  \heveastyle{\upshape}{no style}\\ \hline
\verb+\ttfamily+ & \heveastyle{\ttfamily}{typewriter font}\\
\verb+\sffamily+ & \heveastyle{\sffamily}{purple}\\
\verb+\rmfamily+ &  \heveastyle{\rmfamily}{no style}\\ \hline
\verb+\bfseries+ & \heveastyle{\bfseries}{bold}\\
\verb+\mdseries+ & \heveastyle{\mdseries}{no style}\\ \hline
Text-style commands also exists, they are defined as
\verb+\texttt+ is defined as a command with one argument whose body is
Finally, the \verb+\emph+ command for emphasized text also exists.
\emph{shape}, \emph{series} and \emph{family}.
type style and that's all.
\hevea{} implements the three components by making one declaration to
cancel the effect of other declarations of the same kind.
For instance consider the following source, that exhibits shape changes:
{\itshape italic shape \slshape slanted shape
\scshape small caps shape \upshape upright shape}
Then, in the rendering below, ``small caps shape'' apears in navy blue
{\itshape italic shape \slshape slanted shape
\scshape small caps shape \upshape upright shape}
Old style declarations are also recognized, they translate to
text-level elements. However, no elements are canceled when using
old style declaration. Thus, the source
``\verb+{\sl\sc slanted and small caps}+'' yields navy blue
italics\ifhevea: ``{\sl\sc slanted and small caps}''\fi.
Users need probably not worry about this. However this has an
important practical consequence: to change the default rendering of
type styles, one should redefine old style declaration in order to
benefit from the cancelation mechanism. See
\subsection{Changing the Type Size}
All declarations, from \verb+\tiny+ to \verb+\Huge+ are recognized.
Output is not satisfactory inside headers elements
\subsection{Special Symbols}
The \verb+\symbol{+{\it num}\verb+}+ outputs character number {\it num}
from the iso-latin1 character set.
This departs from \LaTeX{}, which output symbol number \textit{num} in
This section describes \hevea{} functionalities that extends on plain \LaTeX{},
\subsection{Accents in maths}
\index{math accents}
Loading the \texttt{mathaccents.hva} style files enables
default typesetting of the math
accents commands
(\verb+\hat+, \verb+\tilde+,\ldots), see Section~\ref{mathaccents}.
\subsection{\TeX{} macros}\label{texmacro}
Normally, \hevea{} does not recognize constructs that are specific to
However, some of the internal commands of \hevea{} are homonymous to
\TeX{} macros, in order to enhance compatibility.
Note that full compatibility with \TeX{} is not guaranteed.
\subsubsection{À la \TeX{} macros definitions}
notice that \hevea{} semantics for \verb+\def+ 
That is, defining a command that already
This is an important change with respect to previous versions of
\hevea{}, where \verb+\def+ had the same semantics as
Delimiting characters in command definition are supported.
Please note that delimiting characters are supported as far as I
could, problems are likely with delimiting characters which include
spaces or command names, in particular the command name \verb+\{+.
One can include \verb+\{+ in a command argument by using the grouping
characters \verb+{+\ldots{} \verb+}+:
\def\frenchquote(#1){«~\emph{#1}~» (in French)}
He said \frenchquote(Alors cette accolade ouvrante {``\{''}~?).
\def\frenchquote(#1){«~\emph{#1}~» (in French)}
He said \frenchquote(Alors cette accolade ouvrante {``\{''}~?).
Another source of incompatibilty with \TeX{} is that  substitution of
macros parameters is not performed at the same moment by \hevea{} and
However, things should go smoothly at the first level of macro
expansion, that is when the delimiters
appear in source code at the same level as the macro that is to
\LaTeX{} and in \hevea:
\LaTeX{} output is ``coucou''A, while \hevea{} output is ``coucouA''.
Here is \ifhevea\hevea\else\LaTeX\fi{} output:
Please note that in most situations this discrepancy will make
\hevea{} crash. 
\subsubsection{The \texttt{\char92 let} construct}
\comdefindex{let}\hevea{} also processes a
\verb+\let+ {\it macro-name1} = {\it macro-name2}
The effect is to bind  {\it macro-name1} to whatever {\it macro-name2}
one whishes to slightly modify basic commands.
\verb+\let+ in such a situation.
\subsubsection{The \texttt{\char92 global} construct}
It is possible to escape scope and to make global definitions
The \verb+\global+ construct is significant before
Also note that \verb+\gdef+ is equivalent to \verb+\global\def+.
\subsubsection{\TeX{} Conditional Macros}\label{texcond}
only, creates three macros:
The latter two set the \textit{name} condition to \textit{true} and
If \textit{text$_2$}  is empty, then the \verb+\else+ keyword can be
Note that \hevea{} also implements \LaTeX{} \texttt{ifthen} package
and that \TeX{} simple conditional macros are fully compatible with
we have the following correspondences:
\subsubsection{Other \TeX{} Macros}
\hevea{} implements the macros \verb+\unskip+ and \verb+\endinput+.
If one strictly follows the \LaTeX{} manual, only commands with no
arguments can be defined inside other commands.
Parameters (i.e., \verb+#+\textit{n}) occurring inside command bodies
refer to the outer definition, even when they appear in nested
That is, the following source:
Nevertheless, nested commands with arguments are allowed.
Standard parameters \verb+#+\textit{n} still refer to the outer
definition, while nested parameters \verb+##+\textit{n} refer to the
That is, the source:
However, \hevea{} source distribution includes a simple (\texttt{sh})
\texttt{xxdate.exe} that activates date and time support.
The \texttt{hevea} command, should be invoked as~:
# hevea -exec xxdate.exe ...
read by \hevea{}.
As a consequence, standard \TeX{} counters \verb+\year+,
\comindex{heveadate}
\ifhevea(e.g. \theweekday)\fi\\
\ifhevea(e.g. \theHour)\fi\\
Counter \texttt{hour} & hour, 00\ldots{}23 \ifhevea(e.g. \thehour)\fi \\
\ifhevea(e.g. \theminute)\fi\\
\ifhevea(e.g. \thesecond)\fi\\ \hline
\ifhevea(e.g. \ampm)\fi\\
\ifhevea(e.g. \timezone)\fi\\
Command \verb+\heveadate+ & Output of the ``\texttt{date}'' Unix
command\ifhevea, (e.g. \heveadate)\fi\\ \hline
Note that I choosed to add an extra option (and not an extra
not want to enable \hevea{} to execute silently an arbitrary program
without being conscious of that fact.
Moreover, the \texttt{hevea} program does not execute
\texttt{xxdate.exe} by default since it is difficult to write such 
Windows users should enjoy the same features with the version of
\index{color!of section headings}
Loading the \texttt{fancysection.hva} file will radically change the
style of sectionnal units headers: they appear over a green
backgroud, the backgrould color saturation decreases as the sectioning
commands themselves do\ifhevea{} (this is the style of this manual).\else.\fi{}
Additionnaly, the document background color is white.
The \texttt{fancysection.hva} file is intended to be loaded after
# hevea article.hva fancysection.hva doc.tex
You can also make a \texttt{doc.hva} file that contains the two lines:
\input{article.hva}
\input{fancysection.hva}
And then launch \texttt{hevea} as:
# hevea doc.hva doc.tex
Sectioning command background colors can be changed by
redefining the corresponding colors (\texttt{part}, \texttt{chapter},
\input{article.hva}
\input{fancysection.hva}
(See section~\ref{color:package} for details on the \texttt{named}
color model that is used above.)
Another choice is issuing the command
\textit{hue} is a hue value to be interpreted in the HSV model.
\input{article.hva}
\input{fancysection.hva}
will yield sectionnal headers on a red-orange background.
\subsection{\hevea{} as a Back-End for VideoC}
\hevea{} is one of the back-ends of the VideoC system for producing
educational CDROM to teach programming languages.
VideoC author is Christian Queinnec and the documentation is available
\ahrefurl{http://www-spi.lip6.fr/\home{queinnec}/VideoC/VideoC.html}.
VideoC translates \LaTeX{} source into a variety of formats, including
\html. VideoC source may contain some special constructs for
typesetting source code or to annotate text in sophisticated ways.
\hevea{} internal engine implements some of the core constructs needed
the \texttt{.hva} files from VideoC distribution.
\section{Implemented Packages}\label{implemented:package}
\hevea{} distribution includes ``.hva'' packages that are
implementations of \LaTeX{} packages.
Packages described in the ``\emph{Blue Book}'' (\texttt{makeidx},
\texttt{ifthen}, \texttt{graphics} ---and \texttt{graphicx}!---,
few extra packages are provided.  I provide no full documentation for
these packages, users should refer to the first pages of the package
documentation, which can usually be found in the book~\cite{latexbis},
in your local
\LaTeX{} installation or in a TeX CTAN-archive.
At the moment, package options are ignored.
\hevea{} \texttt{amsmath} package defines  some of the constructs of the
\texttt{amsmath} package.  At the moment, supported constructs are
the \verb+cases+ environment and matrix
equations (\verb+gather+,
\subsection{The \texttt{array} and \texttt{tabularx}
Packages}\label{arraypack}
The \footahref{\ctan/required/tools/array.dtx}{\texttt{array}}
package is described in
\cite[Section~5.3]{latexbis} and in the local documentation of modern \LaTeX{}
installations.
It is a compatible extension of \LaTeX{} arrays (see~\ref{arraydef}).
Basically, it provides new column specifications
specifications.
Table~\ref{arraytable} gives a summary of the new column
specifications and of how \hevea{}
\caption{\label{arraytable} Column specifications from the
\texttt{array} package}
Equivalent to the \verb+p+ column specification (the \textit{width}
argument is ignored, entries are typeset in paragraph mode with
paragraph breaks being reduced to a single line break), except that the entries
are centered vertically.\\ \hline
Equivalent to the \verb+p+ column specification, except that the entries
are bottom-aligned vertically.\\ \hline
Note that \emph{centered}, \emph{top-aligned} or \emph{bottom-aligned}
in the vertical direction, do not
have exactly the same meaning in \LaTeX{} and in \html{}. However, the
aspect is the same when all columns agree w.r.t. vertical alignment.
do not specify vertical alignment, which therefore becomes browser
constructs permit the encoding of \TeX{} \verb+\cases+ macro as follows:
\def\cases#1{\left\{\begin{array}{l>{$}l<{$}}#1\end{array}\right.}
(This is an excerpt of the \texttt{latexcommon.hva} file.)
New column specifications are defined by the \verb+\newcolumntype+
valid column specifications and macro-argument references
The column specification
\texttt{C} means that entries will be typeset centered and using bold
font, while the column specifications \verb+E{+\textit{num}\verb+}+
\hevea{} implements column specifications with commands defined in the
\verb+\newcommand+ style. Thus, they have the same behavior as regards
double definition, which is not performed and induces a warning
Thus, a column specification that is
first defined in a \texttt{macro.hva} specific
The \footahref{\ctan/required/tools/tabularx.dtx}{\texttt{tabularx}}
package~\cite[Section~5.3.5]{latexbis} provides a new tabular
environment \verb+tabularx+ and a new column type \verb+X+. \hevea{}
makes the former equivalent to \verb+tabular+ and the latter
equivalent to \verb+p{+\textit{ignored}\verb+}+.  By contrast with the
subtle array formatting that the \texttt{tabularx} package performs,
More generally and from the \html{} point of view such sophisticated
formatting is browser job in the first place.
From \hevea{} point of view, drawing the border line between what can be
specified and what can be left to the browser is not obvious at all.
At the moment \hevea{} choice is not to specify too much (in
arguments, either to column specifications or to the arrays
aspect of arrays will usually be different from their printed
\subsection{The \texttt{calc} Package}\label{calc}
\LaTeX{} \footahref{\ctan/required/tools/calc.dtx}{source} and documentation.
This package enables using traditional, infix, notation for
The \texttt{calc} package provides a similar extension of the syntax
of the \textit{len} argument to the \verb+\setlength+ and
\hevea{} does not implement this extension, since it does not
implement length registers in the first place.
\subsection{The \texttt{comment} Package}
\LaTeX{} \footahref{\ctan/contrib/other/comment/}{source}.
The implementation for this package provides two commands,
new environments that ignore their content or that do nothing. The
comment environment is also defined as an environment of the first
\subsection{Multiple Indexes with the \texttt{index} and \texttt{multind} package}\label{multind}
\hevea{} supports several simultaneous indexes, following the scheme
\footahref{ftp://theory.lcs.mit.edu/pub/tex/index/}{\texttt{index}} package,
which is present in modern \LaTeX{} distributions.
This scheme is backward compatible with the standard indexing scheme
Support is not complete, but the most useful commands are available.
More precisely, \hevea{} knows the following commands:
\item[{\tt\char92 newindex\{}{\it tag}{\tt \}\{}{\it
Declare an index.
The first argument {\it tag} is a tag to select this index in other
\hevea{}; and {\it indexname} is the title of the index.
If given the \verb+idx+ option. \hevea{} attempts to read file
\verb+\renewindex+ commands that takes the same arguments and that can be
used to redefine previously declared indexes.
\item[{\tt\char92 makeindex}] Perform
z\item[{\tt\char92 index[}{\it tag}{\tt]\{}{\it arg}{\tt\}}]
Act as the \LaTeX{} \verb+\index+ command except that the information
extracted from {\it arg} goes to the {\it tag} index.
standard \LaTeX{} behavior for the \verb+\index+ command without an
optional argument.
There also exists a stared-variant \verb+\index*+ that Additionally
\item[{\tt\char92 printindex[}{\it tag}{\tt]}] Compute, format and
difference between \LaTeX{} and \hevea{}: for \verb+\printindex+ to
work, if must occur after the last
practise, since indexes usually reside at the end of books.
The \footahref{\ctanold/contrib/misc/multind.sty}{\texttt{multind}} package provides another scheme
Note that the ``\texttt{multind}''
style for indexes is not backward compatible with
\LaTeX{} default indexing scheme. I would recommend using
the ``\texttt{index}'' package.
\subsection{Multiple Bibliographies with the \texttt{multibib} package}
\ttindex{multibib}{package}\comindex{newcites}.
\hevea{} provides a slighty uncomplete implementation of the
\texttt{multibib} package. The one non-implemented feature is the
simultaneous definition of more than one bibliography.
That is one cannot invoke \verb+\newcites+ as follows~:
Instead, one should perform to calls to the \verb+\newcites+ command~:
\subsection{The \texttt{url} package}\label{urlpackage}
\comindex{url}\index{hyperlinks}\ttindex{url}{package}
\LaTeX{} \footahref{\ctan/contrib/other/misc/url.sty}{source}.
This package in fact provides a enhanced  \verb+\verb+ command that
can appear inside other command arguments.
but it can be used for any verbatim text, including DOS-like path
Hence, one can insert urls in one's document without worrying about
\LaTeX{} active characters~:
This is a complicated url: \url{http://foo.com/~user#label%coucou}.
which gets typeset as: ``This is a complicated url: \url{http://foo.com/~user#label%coucou}.''
Main use for the \verb+\url+ command is to specify urls as arguments to
\hevea{} commands for hyperlinks (see section~\ref{hyperlink})~:
\hevea{} home page is
\ahrefurl{\url{http://pauillac.inria.fr/~maranget/hevea/}}
It yields~: ``\hevea{} home page is
\ahrefurl{\url{http://pauillac.inria.fr/~maranget/hevea/}}''.
However the \verb+\url+ command is fragile, as a consequence it
cannot be used inside \verb+\footahref+ first argument (This is a
\LaTeX{} problem, not an \hevea{} one).
The \texttt{url} package solves this problem by providing the
\urldef{\heveahome}{\url}{http://pauillac.inria.fr/~maranget/hevea/}
\urldef{\heveahome}{\url}{http://pauillac.inria.fr/~maranget/hevea/}%
Such a source defines the robust command \verb+\heveahome+ as the
Have a look at \footurl{\heveahome}{\hevea{} home page}
It yields: ``Have a look at \footahref{\heveahome}{\hevea{} home page}''.
Using \verb+\url+ inside command definitions with a
\verb+#+\textit{i} argument is a bad idea, since
it gives ``verbatim'' a rather random meaning.
contrast, it does not work in \hevea{}. In such situations,
\hevea{} implementation is somehow compatible at the ``programming level''.
Thus, users can define new commands whose argument is understood
verbatim. The \ahref{urlhref.hva}{\texttt{urlhref.hva}} style file
takes advantage of this to define the \verb+\url+ command, so that it both
\input{urlhref.hva}
Have a look at \url{http://pauillac.inria.fr/~maranget/hevea/}
\input{urlhref.hva}It yields ``Have a look at \url{http://pauillac.inria.fr/~maranget/hevea/}''.
The \texttt{urlhref.hva}
style file (which is an \hevea{} style file and not a \LaTeX{}
style file) can be adequate for bibliographic references,
which often use \verb+\url+ for its typesetting power.
Of course, loading \texttt{urlhref.hva} only makes sense when
\texttt{verbatim} Packages}
These two packages provide new commands and environments for
\footahref{\ctan/contrib/supported/moreverb/}{\texttt{moreverb}}
rather than
\footahref{\ctan/required/tools/verbatim.dtx}{\texttt{verbatim}},
is much more compatible with \hevea{} than
the implementation of the latter.
\subsection{Typesetting Computer Languages: the \texttt{listings} Package}
\footahref{\ctan/contrib/supported/listings}{\texttt{listings}}.
Learning the user interface requires a little effort, but it is worth
\hevea{} features a quite compatible implementation, please refer to
the original package documentation.
Note that \hevea{} does not produce very compact
\html{} in case you use this package.
This can be cured, at some price in runtime cost, by
giving \texttt{hevea} the command line option ``\texttt{-O}''
(see Section~\ref{heveaoptions}).
packages are partly implemented.
\part{Practical information}
\pdfpart{-6}{Practical information}
\label{practical}
\subsection{\hevea{} usage}\label{heveausage}
\index{hevea@\texttt{hevea} command}
The \texttt{hevea} command has two operating modes, normal mode and
Operating mode is determined by the nature of the last command line
The \texttt{hevea} command interprets its arguments as names of
Given an argument \textit{filename} there are two cases:
\textit{base}\texttt{.hva},
then a single attempt to open \textit{filename} is made.
\item In other cases,
In case of failure, a second attempt to open  \textit{filename} is made.
\label{search:path}
searched along \texttt{hevea} search path, which consist in:
\item user-specified directories (with the \texttt{-I} command line
\item \texttt{hevea} library directory.
\texttt{info} from \texttt{hevea} library directory, depending upon
\texttt{hevea} output format,
The \texttt{hevea} library directory is fixed at compile-time
(this is where \texttt{hevea} library files are installed)
and typically is \texttt{/usr/local/lib/hevea}.
However, this compile-time value can be overridden
by setting the \texttt{HEVEADIR} shell environment variable.
If the last argument has an extension that is different from
\texttt{.hva} or has no extension,
then it is interpreted as the name of the \emph{main input file}.
The main input file is the document to be translated and normally
contains the \verb+\documentclass+ command.
In that case two \emph{basenames} are defined:
is defined as the main input file name,
with leading directories omitted. However the output basename can be
changed, using the \verb+-o+ option (see the section on options below).
\hevea{} will attempt to load the main input file.
will be searched as \textit{basein}\verb+.+\textit{ext}.
The output base name governs all files produced by \hevea{}.
That is, \html{} output of \hevea{} normally goes to the file
\textit{baseout}\texttt{.haux}. Furthemore,
Thus, in the simple case where the \texttt{hevea} command is invoked
# hevea file.tex
\texttt{file}. The main input file is searched once along \texttt{hevea}
search path as \texttt{file.tex}.
In the more complicated case where the \texttt{hevea} command is invoked
# hevea ./dir/file
\texttt{file}. The main input file is loaded by first attempting to
The \texttt{article.hva}, \texttt{seminar.hva}, \texttt{book.hva} and
\texttt{report.hva}
base style files from \hevea{} library are special.
\verb+\documentclass+ command has no effect when a base style file is
Thus, a document \texttt{file.tex} can be translated using the
# hevea article.hva file.tex
If there is no command line argument, or if the last command line
argument has the extension~\texttt{.hva}, then
the standard input is read and
output normally goes to the standard output.
Output starts immediately, whithout waiting for \verb+\begin{document}+.
In other words \texttt{hevea} acts as a filter.
Please note that this operating mode is just for translating
``\verb+hevea+ \textit{file}\verb+.tex+'' and not
``\verb+hevea < + \textit{file}\verb+.tex > +\textit{file}\verb+.html+''.
\subsubsection{Options}\label{heveaoptions}
The \texttt{hevea} command recognizes the following options:
\item[{\tt -version}] Show \texttt{hevea} version and exit.
\item[{\tt -v}] Verbose flag, can be repeated to increase
\item[{\tt -e} {\it filename}] Prevent \texttt{hevea} from loading any file
whose name is \textit{filename}. Note that this option applies to all
files, including \texttt{hevea.hva} and base style files.
\item[{\tt -fix}] Iterate \hevea{} until a fixpoint is found.
Additionnaly, images get generated automatically.
\item[{\tt -O}] Optimize \html{} by calling \esponja{} (see
section~\ref{esponjausage}.
output. The file \textit{prog} must have execution permission and is
searched by following the searching rules of~\texttt{hevea}.
\item[{\tt -francais}] Set French mode.
This has three consequences:
\item Some words inserted by \LaTeX{} (such as ``Chapter'',
``Bibliography'', \ldots) are replaced by French word.
\item Text replacement for symbols are  in French (see the
\item \texttt{hevea} sets the boolean register \texttt{french} to
In this mode, symbols are replaced by text-only equivalents. By
\item[{\tt -noiso}] Do not output (iso-latin1) characters whose code
These characters are replaced by \html{} entities. This option is
mostly useful for generating \html{} that will be displayed properly
by \emph{Netscape Communicator} on a Macintosh.
definition. In particular, this option disable size and color changes inside
\verb+<PRE>+\ldots{} \verb+</PRE>+, which are otherwise performed.
\item[{\tt -I} {\it dirname}] Add {\it dirname} to the search path.
Part~\ref{usermanual} of this document is
a tutorial introduction to \hevea{},
while \hevea{} reference manual is part~\ref{referencemanual}.
\subsection{\hacha{} usage}
\index{hacha@\texttt{hacha} command}
The \texttt{hacha} command interprets its argument
\textit{base}\texttt{.html} as the name of
\item[{\tt -o} {\it filename}] Make \hacha{} output go into file
in which output files are the anchors from the input file gone.
``\textit{anchor}\verb+\t+\textit{file}'' line per anchor.
\noindent Section~\ref{hacha} of the user manual explains how to
alter \hacha{} default behavior.
\subsection{\texttt{esponja} usage}\label{esponjausage}
is part of \hevea{} and is designed to optimize \texttt{hevea}
However, \texttt{esponja} can also be used alone to optimize
to operate when it detects incorrect~\html, it can be used as a
With no argument, \texttt{esponja} acts as a filter, it reads the
standard input and writes on the standard output.
It is important to notice that \texttt{esponja} will \emph{replace} files
one should invoke \texttt{esponja} as follows.
By contrast, invoking \texttt{esponja} as
is left unchanged.
Note that this feature allows to optimize all \html{} files in a given directory
\item[{\tt -v}]Be verbose, can be repeated to increase verbosity.
In most occasions, this amouts to pessimize instead of to optimize.
It may yield challenging input for other \html~optimizers.
The command \texttt{imagen} is a simple shell script that translates
The \texttt{imagen} script relies on much software to be installed on
It is a companion program of \hevea{}, which must have been previously run as:
\texttt{\# hevea}\ldots{} \textit{base}\texttt{.tex}\\
\texttt{\# hevea}\ldots{} \texttt{-o} \textit{base}\texttt{.html}\ldots\\
(In both cases, \textit{base} is \hevea{} output basename.)
\hevea{} echoes part of its input into
This is done by first calling \texttt{latex} on
Then, \texttt{dvips} translates this file into one single Postscript file that
Postscript files are interpreted by ghostscript (\texttt{gs}) that
outputs \texttt{ppm} images, which are then fed into a series of
transformations that change them into \texttt{.gif} files.
\item[{\tt -mag} {\sl nnnn}] Change the enlarging ratio that is applied
that, by default, \texttt{imagen} magnifies \LaTeX{} output by a factor of
\item[{\tt -extra} {\it command}] Insert {\it command} as an additional
stage in \texttt{imagen} \texttt{ppm} to \texttt{gif} production chain.
\textit{command} is an Unix filter that expects a \texttt{ppm} image
in its standard input and outputs a \texttt{ppm} image on its standard output.
A sensible choice for \textit{command} is one command from the
\texttt{netpbm} package or several such commands piped together.
in \texttt{imagen} \texttt{ppm} image production chain, where
\textit{number} is the maximal number of colors in the produced
images. This option may be needed in response of a failure in the
image production chain. It can also help in limiting image files size.
Output PNG images in place of GIF images.
PNG image files have a ``\texttt{.png}'' extension.
Note that \texttt{hevea} should have been previously run as
\texttt{hevea png.hva} \textit{base}\texttt{.tex} (so that the proper
Beware that the \texttt{pnmtopng} program looks to be plagued by bugs
in old versions of the \texttt{netpbm} package.
debugging purposes. Experimented users can also take advantage
The first three options enable users to correct some misbehaviors.
be wrong and the images are too small. This can be cured by invoking
Sometimes \texttt{imagen} crashes because the PPM transformation chain
does not cope with images with more than 256~colors by default. The
More information on producing images can be found in section~\ref{imagen}.
Here is a typical \texttt{Makefile} for translating a \texttt{doc.tex}
The file is first translated into \texttt{doc.html} by \texttt{hevea},
which also reads
the specific style file \texttt{macros.hva}.
Then, \texttt{hacha} cuts \texttt{doc.html} into several,
HEVEA=hevea
HACHA=hacha
$(DOC).html: macros.hva $(DOC).tex
        $(HEVEA) $(HEVEAOPTS) macros.hva $(DOC).tex
        rm -f $(DOC).html index.html $(DOC)[0-9][0-9][0-9].html $(DOC).haux
Note that the \texttt{clean} rule removes all the \texttt{doc001.html},
\texttt{doc002.html}, etc. files produced by \texttt{hacha}.
Also note that
\texttt{make clean} also removes the \texttt{doc.haux} file.
Thanks to the \verb+-fix+ options, \texttt{hevea} will run the appropriate
When the \textit{image} file feature is used, one can use the
HEVEA=hevea
HACHA=hacha
$(DOC).html: macros.hva $(DOC).tex
        $(HEVEA) $(HEVEAOPTS) macros.hva $(DOC).tex
        rm -f $(DOC).html index.html $(DOC)[0-9][0-9][0-9].html $(DOC).haux
Observe that the \texttt{clean} rule now also gets rid of
\texttt{doc.image.tex} and of the various files produced by
when given the \verb+-fix+ option, \texttt{hevea} will itself run
By default, \hevea{} uses
This attribute is non-standard in HTML-3.2 and is now standard (and
already deprecated) in HTML-4.0 
The symbol font is the one available on the Linux Red Hat
distribution and seems to be present on many Unix installations.
A good way to know whether your browser can show \hevea{} symbols or
comparing figure~\ref{xfd} and the web page located at
\localurl{symbol.html}.
By default,  \emph{Netscape Communicator} does not display symbol fonts
as intended by \hevea{}.
\emph{Netscape Communicator} to do so:
Netscape*documentFonts.charset*adobe-fontspecific:   iso-8859-1
\item Restart \emph{Netscape}.
On a Macintosh,
choose  {\bf Western (Mac Roman)} in the item {\bf Document~Encoding}
does not contain iso-latin1 characters above 127. That is, this will
work only with documents that are generated by \hevea{} with the
\texttt{-noiso} option enabled (see section~\ref{heveaoptions}).
More details on browser configuration can be found at
\ahrefurl{http://hutchinson.belmont.ma.us/tth/Xfonts.html}
(A page from Ian Hutchinson's \texttt{tth} documentation).
rely on the more complicated fix described in the web page.
Furthermore, be carefull to enable using document fonts
(Edit/Preference/Fonts, then check the appropriate box).
More details on symbol fonts can be found
in section~\ref{symbols} of this manual.
In particular, note that symbol fonts may be completely avoided with
\section{Availability}
\hevea{} home page is \ahrefurl{\httpbase}. It contains links to the
\footahref{\httpbase/doc/}{on-line manual}
and to the \footahref{\ftpbase}{distribution}.
The author can be contacted at \mailto{Luc.Maranget@inria.fr}.
\hevea{} can be freely used and redistributed without modifications.
Modifying and redistributing \hevea{} implies a few constraints.
More precisely, \hevea{} is distributed under the terms of the
Q~Public License, but \hevea{} binaries include the Objective Caml
runtime system, which is distributed under the Gnu Library General
See the \footahref{\ftpbase/LICENSE}{LICENSE} file for details.
The manuel itself is distributed under the terms of
\ifhevea
\ahref{fddl.html}{Free Document Dissemination Licence}.
\footahref{http://pauillac.inria.fr/\home{lang}/licence/v1/fddl.html}
\section{Installation}
The programs \commandname{hevea} and \commandname{hacha} are written in
\footahref{http://caml.inria.fr/ocaml/}{Objective Caml}. Thus, you
\footahref{\ftpbase/hevea-\heveaversion-1.i386.rpm}{binary distribution}
is also available, it does not require an Objective Caml installation
and can be installed on most Red~Hat Linux PC's.
\label{imagen:needs}\hevea{} users may instruct the program not to process a
\verb+.gif+ file and \hevea{} outputs a  link to the image file.
\LaTeX{} source is changed into \verb+.gif+ images by the \verb+imagen+
script, which basically calls, \LaTeX, \texttt{dvips},
\footahref{http://www.cs.wisc.edu/\home{ghost}/index.html}{\texttt{ghostscript}}
and a few tools from the image processing package
\footahref{ftp://wuarchive.wustl.edu/graphics/graphics/packages/NetPBM}{\texttt{netpbm}}.
To benefit from the full functionality of \hevea, you need all
this software. However, \hevea{} runs without them, but then you will
to manage to produce images by yourself.
The details are given in the \ahref{\ftpbase/README}{\texttt{README}}
Basically, \hevea{} should be given a library
directory. The installation procedure stores the \texttt{hevea.hva}
native code  Ocaml compiler \texttt{ocamlopt}, while the \texttt{byte}
mode selects the bytecode  Ocaml compiler \texttt{ocamlc}.
In \hevea{} case, \texttt{ocamlopt} produces code that is up to three
times as fast as the one produced by \texttt{ocamlc}.
case on some systems that only \texttt{ocamlc} is available.
Note that the \texttt{hevea.sty} file is simply copied to \hevea{}
make it accessible to \LaTeX.
performed not extensive testing and make no thorough comparison.
calls \LaTeX{} when in trouble.
More information on LaTeX2html can be found at
\ahrefurl{http://www-dsed.llnl.gov/files/programs/unix/latex2html/}
\item[TTH] The principle behind TTH is the same as the one of
\hevea{}: write a fast translator as a lexer, use symbol fonts and
tables. However, there are differences, TTH accepts both \TeX{} and
TTH is written in C and the full source is not available
(only \verb+lex+ output is available).
whereas \hacha{} can cut the output of \hevea{} into several files.
(however there exists a commercial
version of TTH that provides this extra functionality).
TTH can be found at
\ahrefurl{http://hutchinson.belmont.ma.us/tth/}.
\item[\texttt{htmlgen}] The \texttt{htmlgen} translator is specialized
for producing the Caml manuals. This is \hevea{} direct ancestor and I
owe much to its author, X.~Leroy. See \cite{htmlgen} for a description
A fairly complete list of \LaTeX{} to \html{} translators can be found
\ahrefurl{http://www.loria.fr/services/tex/english/outils.html}
The following people contributed to \hevea{} development:
\ahref{http://www.arch.ohio-state.edu/crp/faculty/pviton/support/hevea.html}{window
(win32) port} of \hevea.
\ahref{http://www-spi.lip6.fr/\home{queinnec}/VideoC/VideoC.html}{VideoC}
for writing pedagogical documents on programming.
The very principle he introduced for interfacing the \texttt{videoc}
lexer with \hevea{} main lexer is now used extensively throughout
\hevea{} source code.
\item Pierre Boulet, by using \hevea{} as a stage in his tool
\ahref{http://www.lifl.fr/\home{boulet}/softs/mldoc/index.html}{MlDoc}
\hevea{} implementation of the \verb+alltt+ environment.
\begin{thebibliography}{xxxxxxxxxx}
M.~Gooseens, F.~Mittelbach, A.~Samarin.
\newblock {\em A Document Preparation System System, \LaTeX{}, User's
Guide and Reference Manual}.
\newblock Available on the web at
\ahrefurl{\url{http://cristal.inria.fr/~xleroy/w4g.html}}
{\em HTML 3.2 Reference Specification}. Available on the web at
\ahrefurl{\url{http://www.w3.org/TR/REC-html32}}, 1997.
D.~Ragget, A.~Le~Hors and I.~Jacobs.
{\em HTML 4.0 Reference Specification}. Available on the web at
\ahrefurl{\url{http://www.w3.org/TR/REC-html40}}, 1997.
\end{thebibliography}