\usepackage{a4}
\usepackage{alltt}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{array}
\usepackage[dvipsnames]{color}
\usepackage[T1]{fontenc}
\usepackage{fullpage}
\usepackage{graphics}
\usepackage{hevea}
\usepackage{ifpdf}
%HEVEA\pdffalse
\usepackage{ifthen}
\usepackage{imakeidx}
\usepackage[latin1]{inputenc}
%HEVEA\@def@charset{US-ASCII}
\usepackage{listings}
\usepackage{lmodern}
\usepackage{mathjax}
\usepackage{mathpartir}
\usepackage{microtype}
\usepackage{moreverb}
\usepackage{texnames}
\usepackage{textcomp}
\usepackage{url}

\definecolor{abricot}{cmyk}{0,0.32,0.52,0}

\input{macros.tex}
\input{version.tex}

\makeindex
%HEVEA\usepackage{color}%for echo to image file
%\colorsections{20}
\newtheorem{example}{Example}
\title{\hevea{} User Documentation\\
{\normalsize Version~\heveaversion}}
\author{Luc Maranget\thanks{Inria Paris -- CS 42112, 75589 Paris
Cedex~12. {\tt \mailto{Luc.Maranget@inria.fr}}}}
\date{\today}
\addtocounter{tocdepth}{-1}
\ifdevrelease
\urldef{\ftpbase}{\url}{http://hevea.inria.fr/distri/unstable}
\else
\urldef{\ftpbase}{\url}{http://hevea.inria.fr/distri}
\fi
\urldef{\httpbase}{\url}{http://hevea.inria.fr/}
\def\stylex{padding:1ex;color:navy;border:solid navy;}
\newstyle{.subsectionex}{\stylex}
\def\verbstyle{margin:1ex 1ex;padding:1ex;background:\@getstylecolor{paragraph};}%
\newstyle{.verbatim}{\verbstyle}%
\newstyle{.myverbatim}
  {margin:1ex 3ex;padding:1ex;
   color:maroon;
   background:\@getstylecolor[named]{Apricot}}
\newcommand{\emitstyle}[2]
{\newstyle{.toc#1}{list-style:none;border-left:1ex solid #2;padding:0ex 1ex;}}
\emitstyle{1}{\@getstylecolor{Sepia}}
\emitstyle{2}{\@getstylecolor{Brown}}
\emitstyle{3}{\@getstylecolor{Tan}}
\emitstyle{4}{\@getstylecolor{Melon}}
\newstyle{.xtitle}
  {text-align:center;margin:1ex auto;color:navy;border:solid navy;}
\newstyle{.xtitlerest}{font-variant:small-caps;}
\newstyle{.ruled}{border:solid black;padding:1ex;background:\#eeddbb;color:maroon}
\newstyle{.ruledbis}{border:solid black;padding:1ex;background:\#eeddbb;color:maroon;display:inline-block}
\newstyle{.show}{border:solid black; border-width:thin; margin:2ex;}
%%DOCUMENT START HERE
\begin{document}
\flushdef{document}
\maketitle
\begin{htmlonly}
\ifhtml 
\def\locversion{\ifdevrelease\releasedate\else\heveaversion\fi}
\@hr[]{}{}
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}.
\@hr[]{}{}
\fi
\end{htmlonly}

\begin{abstract}
\hevea{} is a \LaTeX{} to
\html{} translator.
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
version 5\ifhevea{} \cite{html,htmlb} \else.\fi

\hevea{} understands \LaTeX{} macro definitions. Simple user style
files are understood with little or no modifications.
Furthermore, \hevea{} customisation is done by writing \LaTeX{} code.

\hevea{} is written in Objective Caml, as many lexers. It is
quite fast and flexible.  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
\cutdef{section}
\tableofcontents
\cutend

\begin{htmlonly}
This document consists in three parts, a tutorial introduction, a
reference manual and some practical information. The latter part
includes a small \ahrefloc{@index}{index}.
\end{htmlonly}

\clearpage
\cutdef{part}
\part{\label{usermanual}Tutorial}
\cutdef{section}
\section{How to get\label{getstarted} started}
Assume that you have a file, \texttt{a.tex}, written in \LaTeX, using the
\texttt{article}, \texttt{book} or \texttt{report} style. Then,
translation
is achieved by issuing the command:
\begin{verbatim}
# hevea a.tex
\end{verbatim}
Probably, you will get some warnings. If
\hevea{} does not crash, just ignore them for the moment
(Section~\ref{trouble}  explains how to correct errors).

If everything goes fine, this will produce a new file,
\texttt{a.html}, which you can visualise through  a {\html}~browser.


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.
For instance:
\begin{verbatim}
# hevea
$x \in \mathcal{E}$
^D
<span style="font-style:italic">x</span> &#X2208; <span style="color:red"><span style="font-style:italic">E</span></span>
\end{verbatim}
Incidentally, notice that the symbol ``$\in$'' translates to the
appropriate numerical character reference and that the calligraphic
letter ``$\mathcal{E}$'' renders as a red ``$E$''. You can find some
more elaborate \footahref{\heveaurl/examples/index.html}{examples} in
the on-line documentation.

\section{Style files}
\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,
\texttt{article} and~\texttt{book}.
Additionally, the \texttt{report} base style is recognized and
considered equivalent to \texttt{book} and the
\texttt{seminar} base style for making slides is recognized and
implemented by small additions on the \texttt{article} style.


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
processed when the unknown base style is a derivation of a
recognized base style.

Let us assume that \texttt{doc.tex} uses an exotic
base style such as \texttt{acmconf}. Then, typing
\verb+hevea doc.tex+ will yield an error, since
\hevea{} cannot find the \texttt{acmconf.hva} file:
\begin{verbatim}
# hevea.opt doc.tex
doc.tex:1: Warning: Cannot find file: acmconf.hva
doc.tex:1: Error while reading LaTeX: No base style
Adios
\end{verbatim}


This situation is avoided by invoking \hevea{} with the known
base style file  \texttt{article.hva} as an extra argument:
\begin{verbatim}
# hevea article.hva doc.tex
\end{verbatim}
The extra argument instructs
\hevea{} to load its \texttt{article.hva}
style file before processing \texttt{doc.tex}.
It will then ignore the document base style specified by
\verb+\documentclass+ (or \verb+\documentstyle+).

Observe that the fix above works because the \texttt{acmconf} and
\texttt{article} base styles look the same to the document
(\emph{i.e.}\ they define the same macros).
More generally, most  base styles that are neither
\textit{article} nor \textit{book} are in fact variations
on either two of them.
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.


\subsection{Other style files}
A \LaTeX{} document usually loads additional style files, by using
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
\verb+\input{+\textit{file}\verb+}+ by loading the file
\textit{file}. (if I got it right, \hevea{} even follows \TeX{}'s crazy
conventions on \texttt{.tex} extensions).

As it is often the case, assume that the document \texttt{doc.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).
The new definitions are best collected in a style file,
\texttt{mymacros.hva} for instance.
Then, \texttt{doc.tex} is to be translated by issuing the command:
\begin{verbatim}
# hevea mymacros.hva doc.tex
\end{verbatim}
The file \texttt{mymacros.hva} is processed before
\texttt{doc.tex} (and thus before \texttt{mymacros.tex}).
As a consequence of \hevea{} behaviour with respect to
definition and redefinition (see section~\ref{usermacro}),
the macro definitions in \texttt{mymacros.hva}
take precedence over the ones in  \texttt{mymacros.tex}, provided
the document original definitions (the ones in
\texttt{mymacros.tex}) are performed by \verb+\newcommand+
(or \verb+\newenvironment+).


Another situation is when  \hevea{} fails to process a whole 
style file. Usually, this means that \hevea{} crashes on that style
file.
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:
\begin{verbatim}
# hevea mymacros.hva -e mymacros.tex doc.tex
\end{verbatim}


Of course, \texttt{mymacros.hva} must now contain replacements for
all the useful macros of \texttt{mymacro.tex}.





\subsubsection{Files \label{usepackage:both}loaded with \texttt{\char92 usepackage}}
\comindex{usepackage}
As far as I know, \LaTeX{} reacts to the construct
\verb+\usepackage{+\textit{name}\verb+}+ by loading the file
\textit{name}\texttt{.sty}.
\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{zorglub}) 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
\texttt{zorglub}, and you feel confident enough to implement
them yourself.
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+.


\section{A note on style}

\subsection{Spacing, Paragraphs}
Sequence of spaces normally are translated into one single space.
Newlines in the input document undergo a special treatement.
A newline triggers a special scanning mode that reads all following
spaces and newlines. In case at least one additional newline character
is read, then \hevea{} executes the \verb+\par+ command.
Otherwise, \hevea{} outputs a single newline character.
This process approximates \TeX{} process for introducting paragraph
breaks and, as a result, empty lines produce paragraph breaks.

Space after commands with no argument is skipped (as in \LaTeX{}) ---
however this is not true in math mode, as explained in
section~\ref{spacemath}.

The following two subsections describe management of paragraphs and
spaces after command sequences in greater detail.
They can be skipped in first reading.

\subsubsection{Spurious\label{spurious:par} Paragraphs}
Paragraphs are rendered by the means of \verb+p+ elements.
\hevea{} is a bit simplistic in breaking paragraphs and spurious paragraphs
may be present in the final \html{} document.
Normally, as \hevea{} never outputs \verb+p+ elements whose contents is
made of spaces only, this should not happen very often.
Unfortunately, some commands do not produce any output in \LaTeX,
while they do produce output in \hevea: those commands
are \verb+\label+, \verb+\index+ etc.
\hevea{} translates
\verb+\label{+\textit{name}\verb+}+ into the anchor
\verb+<a id="+\textit{name}\verb+"></a>+. As a result, the following
source fragment will introduce a spurious paragraph.
\begin{verbatim}
This a first paragraph.

\label{label}

This is another paragraph.
\end{verbatim}
Indeed, whe have the following translation:
\begin{verbatim}
<p>This a first paragraph.</p>
<p><a id="label"></a></p>
<p>This is another paragraph.</p>
\end{verbatim}
\ifhevea Which your browser renders as follows --- with additional borders
emphasizing \verb+p+ elements.
\begin{htmlout}%
\begin{rawhtml}
<p style="border:1px solid black;">This a first paragraph.</p>
<p style="border:1px solid black;"><a id="label"></a></p>
<p style="border:1px solid black;">This is another paragraph.</p>
\end{rawhtml}%
\end{htmlout}%
\fi

Most of the time, such extra paragraphs remain unnoticed.
Of course, they can be supressed by erasing one of the empty
lines. For instance:
\begin{verbatim}
This a first paragraph.

\label{label}
This is another paragraph.
\end{verbatim}

A similar situation occurs when a sectioning command is followed by
\verb+\label+ and a paragraph break:
\begin{verbatim}
\section*{A section}\label{section:label}

First paragraph. 
\end{verbatim}
Produced \html{} is, after a few cosmetic simplifications:
\begin{verbatim}
<h2 class="section">A section</h2>
<p><a id="section:label"></a></p>
<p>First paragraph.</p>
\end{verbatim}
Output is so, because closing the element \verb+h2+ implies re-opening
a new paragraph.
\ifhevea Your browser renders the above \html{} fragment as follows:
\begin{htmlout}%
\begin{rawhtml}
<h2 class="section">A section</h2>
<p style="border:1px solid black;"><a id="section:label"></a></p>
<p style="border:1px solid black;">First paragraph.</p>
\end{rawhtml}%
\end{htmlout}%
\fi
Here, two possible re-writing of source are:
\begin{center}
\begin{tabular}{p{.45\linewidth}p{.45\linewidth}}
\begin{verbatim}
\section*{A\label{section:label} section}

First paragraph.
\end{verbatim}
&
\begin{verbatim}
\section*{A section}

\label{section:label}First paragraph.
\end{verbatim}
\end{tabular}
\end{center}
In all cases, this amounts to avoiding a paragraph whose contents
consists in a sole \verb+\label+~command.

Spurious paragraphs are more easily seen by running \texttt{hevea}
with the command-line option~\cmdopt{-dv}, which instructs
\texttt{hevea} to add border on some of the elements it produces,
including \verb+p+ elements.

\subsubsection{Spaces after Commands}
\index{ @`` '' (space)!after macro}
Space after commands with no argument is skipped.
Consider the following example:
\begin{verbatim}
\newcommand{\open}{(}
\newcommand{\close}{)}
\open text opened by ``\verb+\open+''
and closed by ``\verb+\close+''\close.
\end{verbatim}
We get:
\begin{htmlout}
\newcommand{\open}{(}
\newcommand{\close}{)}
\open text opened by ``\verb+\open+'' and closed by
``\verb+\close+''\close.
\end{htmlout}
In the output above, the space after \verb+\open+ does not
find its way to the output.


More generally,
\hevea{} tries to emulate \LaTeX{} behaviour in all situations, but
discrepancies probably exist.
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:
\begin{verbatim}
\newcommand{\bfsymbol}{\textbf{symbol}}
\newcommand{\tryspace}[1]{#1 XXX}

Some space: \tryspace{\bfsymbol}\\
No space: \bfsymbol XXX
\end{verbatim}
Spacing is a bit chaotic here,
the space after \textbf{symbol} remains when \verb+#1+ is substituted for it
by \LaTeX{} (or \hevea).

\begin{htmlout}
\newcommand{\bfsymbol}{\textbf{symbol}}
\newcommand{\tryspace}[1]{#1 XXX}
\begin{tabular}{l@{~:~}l}
Some space & \tryspace{\bfsymbol}\\
No space   & \bfsymbol XXX
\end{tabular}%
%BEGIN LATEX
\par ~\vspace{-1ex}
%END LATEX
\end{htmlout}
Note that, if a space before ``XXX'' is wanted, then
one should probably write:
\begin{verbatim}
\newcommand{\tryspace}[1]{#1{} XXX}
\end{verbatim}

Finally, \index{tabulation}whether the tabulation character is a space or not 
is random, so avoid tabs in your source document.

\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,
even simple formulas do not follow the simple basic typesetting model of~\html.


\subsubsection{Spacing\label{spacemath} in math mode}
\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{htmlonly}
$$
\begin{array}{l@{ : }l}
\verb+\alpha\rightarrow\beta+ & \alpha\rightarrow\beta\\
\verb+\alpha \rightarrow \beta+ & \alpha \rightarrow \beta\\
\end{array}
$$
\end{htmlonly}
Note that \LaTeX{} ignores spaces in math mode, so that users can
freely adjust \hevea{} output without changing anything to \LaTeX{}
output.


\subsubsection{Symbols}\label{symbols}
\begin{figure}[ht]
\caption{\label{symbol:fig}Some symbols}
\def\zyva#1{\texttt{\char92{}#1}:\quad & \Large $\csname#1\endcsname$}
\begin{center}
\begin{tabular}{rl@{\qquad}rl}
\zyva{in} & \zyva{notin}\\
\zyva{int} & \zyva{prod}\\
\zyva{preceq} & \zyva{prec}\\
\zyva{leq}    & \zyva{geq}\\
\zyva{cup} & \zyva{cap}\\
\zyva{supset} & \zyva{subset}\\
\zyva{supseteq} & \zyva{subseteq}\\
\end{tabular}
\end{center}
\end{figure}
With respect to previous versions of~\hevea{} since the begining, the
treatment of symbols has significantly evolved.  Outputting symbols is
now performed by using Unicode character references, an option that
much more complies whith standards than the previous option of
selecting a ``symbol'' font.  Observe that this choice is now
possible, because more and more browsers correctly display such
references. See~Figure~\ref{symbol:fig} for a few such symbols.



However, this means that ancient or purposely limited browsers (such as
text-oriented browsers) cannot display maths, as translated by \hevea.
For authors that insist on avoiding 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 \cmdopt{-textsymbols}
command-line option. Replacement text is in English.
For instance. the ``$\in$'' symbol is replace by ``in''.
This is far from being satisfactory, but degraded mode may be
appropriate for documents than contain few symbols.


\subsubsection{Displays}
Apart from containing symbols, formulas specify strong typesetting
constraints: sub-elements must be combined together following patterns
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
\emph{display} mode.
Text mode is the mode for typesetting normal text,
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
\texttt{center} or \texttt{quote}) are rendered by \html{} block-level
elements (such as \texttt{div} or \texttt{blockquote}).
Rendering is correct becauses both \LaTeX{} displayed environments and
\html{} block-level elements start a new line.
Conversly, since opening a \html{} block-level elements means starting
a new line, any text that sould appear inside a paragraph must be
translated using only \html{} text-level elements.
\hevea{} chooses to translate in-text formulas that way.


\hevea{} display mode allows more control on text placement, since
entering display mode means opening
a \html{} \verb+table+ element and that tables allow to control the
relative position of their sub-elements.
Displays come in two flavor, horizontal displays and vertical
displays.
An horizontal display is a one-row table, while a vertical display is
a one-column table. These tables holds display sub-elements, displays
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
(e.g. by \verb+$$+
or \verb+\[+).
Then, sub-displays are opened by \LaTeX{} constructs which require
them.
For instance, a displayed  fraction (\verb+\frac+) opens a vertical display.

The distinction between text and display modes clearly appears while
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}$,
%BEGIN LATEX
\raisebox{-1ex}{\image{int}},
%END LATEX
while the same formula has a better aspect in display mode:
%HEVEA$$\int_1^2xdx = \frac{3}{2}$$
%BEGIN LATEX
\begin{center}
\image{intd}
\end{center}
%END LATEX
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
poor.
In particular, it is not possible to get in-text ``real'' fractions or
in-text limit-like subscripts.

Users should remember that \hevea{} is not \TeX{} or \LaTeX{} and that
\hevea{} author neither is D.~E.~Knuth nor L.~Lamport.
Thus, some formulas may be rendered poorly.
For instance, two fractions with different denominator and numerator
height look strange.
\begin{htmlonly}
$$
\frac{1}{\sum_{i=0}^{N}U_i} = \frac{\sum_{i=0}^{N}U_i}{1}
$$
\end{htmlonly}
%BEGIN LATEX
\begin{center}
\image{cloche}
\end{center}
%END LATEX
The reason is that vertical displays in an horizontal display are
\html{} tables
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 \cmdopt{-dv}  command-line option, which
instructs \hevea{} to add
borders to the \verb+table+ elements introduced by displays.

\subsubsection{Arrays and display mode}

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
block-level element \verb+table+, thereby introducing non-desired line
breaks before and after in-text arrays.
As a consequence, in-text arrays yield an acceptable output, only while
alone in a paragraph.

\begin{htmlonly}
Consider the following source:
\begin{verbatim}
This is a small array:
\begin{tabular}{|cc|}
\hline item-1 & item-2 \\
\hline\end{tabular}. Next sentence.
\end{verbatim}
We get:
\begin{htmlout}
This is a small array:
\begin{tabular}{|cc|}\hline item-1 & item-2
\\ \hline\end{tabular}. Next sentence.
\end{htmlout}
\end{htmlonly}

However, since in some sense, all \html{} tables are displayed, the
\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}).


\subsection{Warnings}
When \hevea{} thinks it cannot translate a symbol or construct
properly, it issues a warning. This draws user attention onto a
potential problem. However, rendering may be correct.

\begin{htmlonly}
In the following (silly) example, \hevea{} gets nervous  because of
the complicated length given as argument to \verb+\hspace+:
\begin{verbatim}
\newlength{\mylength}\setlength{\mylength}{5pt}
\begin{tabular}{c@{\hspace{\mylength}}c}
Before & After
\end{tabular}
\end{verbatim}
Running \hevea{} on this input produces a warning:
\begin{verbatim}
# hevea manual.tex
...
manual.tex:697: Warning: Command not found: \mylength
manual.tex:697: Warning: \hspace with arg ''
...
\end{verbatim}
However the final rendering is correct:
\begin{htmlout}
\newlength{\mylength}\setlength{\mylength}{5pt}%
\begin{tabular}{c@{\hspace{\mylength}}c}
Before & After
\end{tabular}
\end{htmlout}
\end{htmlonly}

Note that all warnings can be suppressed with the \verb+-s+ (silent)
option.
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
greater detail.

\subsection{Commands}
Just like \LaTeX{}, \hevea{} can be seen as a macro language, macros
are rewritten until no more expansion is possible. Then, either some
characters (such as letters, integers\ldots) are outputed or some
internal operation (such as changing font attributes, or arranging
text items in a certain manner) are performed.

This scheme favors easy extension of program capabilities
by users. However, predicting program behaviour and correcting errors
may prove difficult, since final output or errors
may occur after several levels of macro expansion.
As a consequence, users can tailor \hevea{} to their needs, but it
remains a subtle task.
Nevertheless, happy \LaTeX{} users should enjoy customizing
\hevea{}, since this is done by writing \LaTeX{} code.



\subsection{Style choices}\label{stylechoice}
\LaTeX{} and {\html} differ in many aspects. For instance, \LaTeX{} allows
fine control over text placement, whereas
{\html} does not.
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, calligraphic letters (\verb+\mathcal+)
are rendered in red.

If you are not satisfied with \hevea{} rendering of text style
declarations, then you
can choose your own, by redefining the \verb+\cal+
macros, using \verb+\renewcommand+, the macro redefinition operator of
\LaTeX{}. The key point is that you need not worry about \hevea{}
internals: just redefine the old-\LaTeX{} style text-style
declarations (\emph{i.e.}\ \verb+\it+, \verb+\sc+, etc.) and everything should
get fine:
\begin{verbatim}
\renewcommand{\sc}{\Huge}
\renewcommand{\cal}{\em}
\end{verbatim}
(See sections~\ref{trouble} and~\ref{both} on how to make such
changes while leaving your file processable by \LaTeX{}, and
section~\ref{customize-style} for a more thorough descripton of
customizing type styles).

\begin{htmlonly}
With such redefinitions, we get:
\renewcommand{\sc}{\Huge}
\renewcommand{\cal}{\em}
\begin{htmlout}
This is \textsc{small caps} and this is $\cal CALLIGRAPHIC LETTERS$
\end{htmlout}
\end{htmlonly}


Note that many of \LaTeX{} commands and environments are defined in the 
\texttt{hevea.hva} file that \hevea{} loads before processing any
input.
These constructs are written using \LaTeX{} source code, in the end they
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
redefinition.
This may prove useless, since there is little point in
redefining core constructs such as \verb+\newcommand+ for instance.

\section{How to detect and correct errors}\label{trouble}

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.
\begin{verbatim}
# hevea trouble.hva trouble.tex
\end{verbatim}
By doing so, the macros written specially for \hevea{} are not
seen by \LaTeX. Even better, \verb+trouble.tex+ is not changed
at all.

A worth-mentiong alternative is inserting \verb+\usepackage{trouble}+
in the document preamble. Then, given \hevea{} semantics for
\verb+\usepackage+ (see Section~\ref{usepackage}),
\hevea{}-specific commands should be placed in
the file ``\texttt{trouble.hva}'' file, while \LaTeX{}-specific commands
should be placed in the file ``\texttt{trouble.sty}''.

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

\subsection{\hevea{} does not know a macro}\label{dontknow}
\begin{quote}\em
This section has been outdated by the implementation of
\verb+\raisebox+ by C.~Spiel. Nevertheless, the method illustrated here is still highly valuable. This method can be summarised as ``if \hevea{} does not know about a macro, you may solve the problem a simple one yourself'' and ``do not ignore warnings''.
\end{quote}

Consider the following \LaTeX{} source excerpt:

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

\LaTeX{} typesets this as follows:
\begin{htmlout}
\begin{showlatex}
You can \raisebox{.6ex}{\em raise} text.
\end{showlatex}
\end{htmlout}

Since \hevea{} does not know about \verb+\raisebox+,
it incorrectly processes this input. More precisely,
it first prints a warning message:
\begin{verbatim}
trouble.tex:34: Unknown macro: \raisebox
\end{verbatim}
Then, it goes on by translating the arguments of \verb+\raisebox+ as if
they were normal text. As a
consequence some \verb+.6ex+ is finally found in the {\html} output:
\begin{htmlout}
You can .6ex{\em raise} text.
\end{htmlout}

To correct this, you should provide a macro that has more or less the effect of
\verb+\raisebox+. It is impossible to write a generic
\verb+\raisebox+ macro for \hevea, because of \html{} limitations.\footnote{Clearly the author of those lines was wrong, as demonstrated \ahref{https://github.com/maranget/hevea/pull/45}{here}.}
However, in this case, the effect of \verb+\raisebox+ is to raise the box {\em a little}.
Thus, the first, numerical, argument to \verb+\raisebox+  can be
ignored in a private \verb+\raisebox+ macro defined in \texttt{trouble.hva}:
\begin{verbatim}
\newcommand{\raisebox}[2]{$^{\mbox{#2}}$}
\end{verbatim}

Now, translating the document yields:
\begin{htmlout}
\renewcommand{\raisebox}[2]{$^{\mbox{#2}}$}%
You can \raisebox{.6ex}{\em raise} text a little.
\end{htmlout}

Of course, this will work only when all \verb+\raisebox+ commands in
the document raise text a little. Consider, the following
example, where text
is both raised a lowered a little:
\begin{verbatim}
You can \raisebox{.6ex}{\em raise}
or \raisebox{-.6ex}{\em lower} text.
\end{verbatim}
Which \LaTeX{} renders as follows:
\begin{htmlout}
\begin{showlatex}
You can \raisebox{.6ex}{\em raise} or \raisebox{-.6ex}{\em lower} text.
\end{showlatex}
\end{htmlout}
Whereas, with the above definition of \verb+\raisebox+, \hevea{} produces:
\begin{htmlout}
\renewcommand{\raisebox}[2]{$^{\mbox{#2}}$}%
You can \raisebox{.6ex}{\em raise}
or \raisebox{-.6ex}{\em lower} text.
\end{htmlout}


A solution is to add a new macro definition in the \verb+trouble.hva+ file:
\begin{verbatim}
\newcommand{\lowerbox}[2]{$_{\mbox{#2}}$}
\end{verbatim}
Then, \verb+trouble.tex+ itself has to be modified a little.
\begin{verbatim}
You can \raisebox{.6ex}{\em raise}
or \lowerbox{-.6ex}{\em lower} text.
\end{verbatim}
\hevea{} now produces a satisfying output:
\begin{htmlout}
\renewcommand{\raisebox}[2]{$^{\mbox{#2}}$}%
\newcommand{\lowerbox}[2]{$_{\mbox{#2}}$}
You can \raisebox{.6ex}{\em raise}
or \lowerbox{-.6ex}{\em lower} text.
\end{htmlout}

Note that, for the document to remain \LaTeX{}-processable,
it should also contain the following definition for
\verb+\lowerbox+:
\begin{verbatim}
\newcommand{\lowerbox}[2]{\raisebox{#1}{#2}}
\end{verbatim}
This definition can safely be placed anywhere in \texttt{trouble.tex},
since by \hevea{} semantics for \verb+\newcommand+ (see
section~\ref{usermacro})
the new definition will not overwrite the old one.

\subsection{\hevea{} incorrectly interprets a macro}\label{blob}\comindex{rule}
\textbf{Note~:} \hevea{} now renders the \verb+\rule+ command very similarly to \LaTeX. Hence the forthcomming section is in some sense obsolete. Nevertheless, the technique described is useful and the section is still worth reading.


Sometimes \hevea{} knows about a macro, but the produced \html{}
does not look good when seen through a browser.
This kind of errors is detected while visually checking the
output.
However, \hevea{} does its best to issue warnings when such situations
are likely to occur.

Consider, for instance, this definition of \verb+\blob+ as a small
black square.
\begin{verbatim}
\newcommand{\blob}{\rule[.2ex]{1ex}{1ex}}
\blob\ Blob \blob
\end{verbatim}
Which \LaTeX{} typesets as follows:
\begin{latexout}
%BEGIN IMAGE
\begingroup\newcommand{\blob}{\rule[.2ex]{1ex}{1ex}}
\blob\ Blob \blob
\endgroup
%END IMAGE
%HEVEA\imageflush%
\end{latexout}
\hevea{} always translates \verb+\rule+ as \verb+<hr>+, ignoring size
arguments.
Hence, it produces the following, wrong, output:
\begin{htmlout}\newcommand{\blob}{\@print{<hr>}}
\begin{htmlonly}
\blob\ Blob \blob
\end{htmlonly}
\begin{latexonly}\vspace*{.5ex}
\image{blob}%
\end{latexonly}%
\end{htmlout}

We may not be particularily commited to a square blob.
In that case, other small symbols 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{verbatim}
\newcommand{\blob}{\bullet}
\end{verbatim}
This new definition yields the following, more satisfying output:
\begin{htmlout}\newcommand{\blob}{\bullet}%
\begin{htmlonly}%
\blob\ Blob \blob
\end{htmlonly}
\begin{latexonly}\vspace*{.5ex}
\image{blob2}%
\end{latexonly}%
\end{htmlout}

\label{square:blob}
\index{"@print"@u@\texttt{\char92"@print"@u}}%
In case we do want a square blob, there are two alternatives.
We can have \LaTeX{} typeset some subparts of
the document and then to include them as images, section~\ref{imagen}
explains how to proceed.
We can also find a square blob somewhere in the variety of Unicode
(or do I mean ISO~10646?) characters,
and define \verb+\blob+ as a numerical
character reference. Here, the character \texttt{U+02588}
seems ok.
\begin{verbatim}
\newcommand{\blob}{\@print@u{X2588}}
\end{verbatim}
\begin{htmlout}%
\begin{htmlonly}\newcommand{\blob}{\@print@u{X2588}}%
\blob\ Blob \blob
\end{htmlonly}
\begin{latexonly}\vspace*{.5ex}
\image{blob3}%
\end{latexonly}%
\end{htmlout}
However, beware that not all browsers display all of Unicode\ldots

Finally, users that experience poor rendering of the \verb+\rule+ command can also upgrade \hevea, so as to benefit from the new implementation of this
command:
\begin{center}
\newcommand{\blob}{\rule[.2ex]{1ex}{1ex}}
\blob\ Blob \blob
\end{center}


\subsection{\hevea{} crashes}

\hevea{} failure may have many causes, including a bug.
However, it may also stem from a wrong \LaTeX{} input.
Thus, this section is to be read before reporting a bug\ldots

\subsubsection{Simple cases: \LaTeX{} also crashes}
In  the following source, environments are not properly balanced:
\begin{verbatim}
\begin{flushright}
\begin{quote}
This is right-flushed quoted text.
\end{flushright}
\end{quote}
\end{verbatim}
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:
\begin{verbatim}
./trouble.tex:6: Environment nesting error: html: 'DIV' closes 'BLOCKQUOTE'
./trouble.tex:4: Latex environment 'quote' is pending
Adios
\end{verbatim}
Thus, when \hevea{} crashes, it is a good idea to check that the
input is correct by running \LaTeX{} on it.

\subsubsection{Complicated cases}

Unfortunately, \hevea{} may crash on input that does not affect
\LaTeX.
Such errors usually relate to environment or group nesting.

Consider for instance the following ``optimized'' version of a
\verb+quoteright+  environment:
\begin{verbatim}
\newenvironment{quoteright}{\quote\flushright}{\endquote}

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

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

However,  \hevea{} usually translates \LaTeX{} environments  to \html{}
block-level elements and it \emph{requires}
those elements to be nested properly.
Here, \verb+\quote+ translates to \verb+<blockquote>+,
\verb+\flushright+ translates to \verb+<div class="flushright">+ and
\verb+\endquote+ translates to \verb+</blockquote>+.
At that point, \hevea{} refuses to generate obviously
non-correct {\html} and it crashes:
\begin{verbatim}
Giving up command: \@close
Giving up command: \endquote
Giving up command: \endquoteright
Giving up command: \end
./trouble.tex:7: Environment nesting error: html: 'BLOCKQUOTE' closes 'DIV'
./trouble.tex:5: Latex environment 'quoteright' is pending
Adios
\end{verbatim}
Also notice that the error message above includes a backtrace showing
the call-chain of commands.

In this case, the solution is easy: environments must be opened and
closed consistently. \LaTeX{} style being recommended, one should write:
\begin{verbatim}
\newenvironment{quoteright}
  {\begin{quote}\begin{flushright}}
  {\end{flushright}\end{quote}}
\end{verbatim}
And we get:
\begin{htmlout}\newenvironment{quoteright}{\begin{quote}\begin{flushright}}{\end{flushright}\end{quote}}
\begin{htmlonly}
\begin{quoteright}
This is a right-flushed quotation
\end{quoteright}
\end{htmlonly}
%BEGIN LATEX
\image{rquote}
%END LATEX
\end{htmlout}


Unclosed \LaTeX{} groups (\verb+{+\ldots{}) are another source
of nuisance to \hevea{}.
Consider the following \texttt{horreur.tex} file:
\begin{verbatim}
\documentclass{article}

\begin{document}
In this sentence, a group is opened now {\em and never closed.
\end{document}
\end{verbatim}
\LaTeX{} accepts this file, although it produces a warning:
\begin{verbatim}
# latex horreur.tex 
This is TeX, Version 3.14159 (Web2C 7.2)
  ...
(\end occurred inside a group at level 1)
Output written on horreur.dvi (1 page, 280 bytes).

\end{verbatim}

By contrast, running \hevea{} on \texttt{horreur.tex} yields a fatal error:
\begin{verbatim}
# hevea horreur.tex 
Giving up command: \@raise@enddocument
Giving up command: \enddocument
Giving up command: \end
./horreur.tex:4: Environment nesting error: Latex env error: 'document' closes ''
./horreur.tex:3: Latex environment '' is pending
Adios
\end{verbatim}
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
as it should.
In any case, please report to \mailto{Luc.Maranget@inria.fr}.

To be useful, your bug report should include \LaTeX{} code
that triggers the bug (the shorter, the better) and mention
\hevea{} version number.


\section{\label{both}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
these instructions should not be seen by \LaTeX{}.
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
and comments.


\subsection{File loading}\label{fileloading}

\hevea{} and \LaTeX{} treat files differently. Here is a summary of the main
differences:

\begin{itemize}
  \item \LaTeX{} and \hevea{} both load files given as arguments to
  \verb+\input+, however when given the option \verb+-e+~\filename{filename},
  \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
  arguments to 
  \verb+\documentstyle+ and as arguments to \verb+\usepackage+,
  but the files are searched by following different methods and
  considering different file extensions.  
\end{itemize}


As a consequence, for having a file \filename{latexonly} loaded by
\LaTeX{} only, it suffices 
to use \verb+\input{+\filename{latexonly}\verb+}+
in the source and to invoke \hevea{} as follows:
\begin{flushleft}
\verb+# hevea+ \texttt{-e} \filename{latexonly}\ldots
\end{flushleft}

\label{heveaonly}Having \filename{heveaonly} loaded by \hevea{} only is more
simple: it  suffices to invoke \hevea{} as follows:
\begin{flushleft}
\verb+# hevea+ \filename{heveaonly}\ldots
\end{flushleft}


Finally, if one has an \hevea{} equivalent \textit{style}\texttt{.hva}
for a \LaTeX{} style file \textit{style}\texttt{.sty},
then one should load the file as follows:
\begin{flushleft}
\verb+\usepackage{+\textit{style}\verb+}+
\end{flushleft}
This will result in, \LaTeX{} loading \textit{style}\texttt{.sty},
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
\LaTeX{} only.

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}
file (see section~\ref{imagen}).

The file \textit{file}\texttt{.hva} can be loaded by either
supplying the command-line argument
\textit{file}\texttt{.hva}, or by
\verb+\usepackage{+\textit{file}\verb+}+ from inside the document.
Which method is better depends
on whether you choose to override or to replace the document
definition.
In the command-line case,
definitions from \textit{file}\texttt{.hva} are processed before the
ones from the document and will override them, provided
the document definitions are made using \verb+\newcommand+ (or
\verb+\newenvironment+).
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
the definitions from \textit{file}\texttt{.sty} in the strict sense.


\subsection{The \label{heveastyle}\protect\texttt{hevea} package}
\ttindex{hevea.sty}{\LaTeX{} style file}%
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
document.
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.
Also notice that, for compatibility,
\hevea{} reacts to
\verb+\usepackage{hevea}+ by loading its own version
of the \texttt{comment} package (Section~\ref{commentpack}).


\subsubsection{Environments for selecting a translator}
\hevea{} and \LaTeX{} perform the following actions on source inside
the  \verb+latexonly+, \verb+verblatex+, \verb+htmlonly+, \verb+rawhtml+,
\verb+toimage+ and \verb+verbimage+ environments:
\envdefindex{latexonly}
\envdefindex{htmlonly}
\envdefindex{rawhtml}
\envdefindex{toimage}
\envdefindex{verbimage}
\envdefindex{verblatex}
\begin{center}
\begin{tabular}{l@{~}p{.5\hsize}@{\quad}l}\hline
environment & \multicolumn{1}{c}{\hevea} &  \multicolumn{1}{c}{\LaTeX}
\\ \hline
\verb+latexonly+ & ignore, \verb+\end{+\textit{env}\verb+}+
constructs are processed (see section~\ref{why}) & process \\
\verb+verblatex+ & ignore & process \\
\verb+htmlonly+ & process & ignore \\
\verb+rawhtml+  & echo verbatim (see section~\ref{rawhtml}) & ignore\\
\verb+toimage+&
send to the \filename{image} file, \verb+\end{+\textit{env}\verb+}+
constructs and macro characters are processed (see section~\ref{imagen})  &
process\\
\verb+verbimage+&
send to the \filename{image} file (see section~\ref{imagen})  &
process\\
\hline
\end{tabular}
\end{center}

\noindent As an example, this is how some text can be typeset in purple by
\hevea{} and left alone by \LaTeX{}:
\begin{verbatim}
We get:
\begin{htmlonly}%
\purple purple rain, purple rain%
\end{htmlonly}
\begin{latexonly}%
purple rain, purple rain%
\end{latexonly}%
\ldots
\end{verbatim}
We get:
\begin{htmlonly}%
\purple purple rain, purple rain%
\end{htmlonly}
\begin{latexonly}%
purple rain, purple rain%
\end{latexonly}%
\ldots

It is impossible to avoid the spurious space in \hevea{} output
for the source above.
This extra spaces comes from the newline character that follows
\verb+\end{htmlonly}+. Namely this
construct must appear in a line of its own for
\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}
and~\ref{comments}.

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}
and \texttt{verbimage} do not create scope.
It takes a little practice of \hevea{} to understand why this is
convenient.





\subsubsection{Why are there two environments for ignoring input?}\label{why}
\envindex{verblatex}\envindex{latexonly}
\envindex{verbimage}\envindex{toimage}
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}
opened the \texttt{latexonly} environment.
In that case, macro expansion of \verb+\end+\textit{env} is performed and
any further occurrence of  \verb+\end{+\textit{env'}\verb+}+ is tested
and may get expanded if it matches a pending
\verb+\begin{+\textit{env'}\verb+}+
construct.


This enables playing tricks such as:
\begin{verbatim}
\newenvironment{latexhuge}
  {\begin{latexonly}\huge}
  {\end{latexonly}}

\begin{latexhuge}
This will appear in huge font in \LaTeX{} output only.
\end{latexhuge}
\end{verbatim}
\LaTeX{} output will be:
\begin{latexout}
\begin{showlatex}
\newenvironment{latexhuge}
  {\begin{latexonly}\huge}
  {\end{latexonly}}
\begin{latexhuge}
This  will appear in huge font in \LaTeX{} output only.
\end{latexhuge}
\end{showlatex}
\end{latexout}
\noindent While there is no \hevea{} output.

Since \hevea{} somehow analyses input that is enclosed in the
\texttt{latexonly} environment,
it may choke.
However, this environment is intended to select processing by
\LaTeX{} only and might contain arbitrary source code.
Fortunately, it remains possible to have input processed by \LaTeX{}
only, regardless of what it is, by enclosing it in the
\texttt{verblatex} environment.
Inside this environment, \hevea{} performs no other action
than looking for \verb+\end{verblatex}+. As a consequence,
the \verb+\begin{verblatex}+ and \verb+\end{verblatex}+ constructs
may only appear in the main flow of text or inside the same macro body,
a bit like \LaTeX{} \texttt{verbatim} environment.


Relations between \texttt{toimage} and \texttt{verbimage} are similar.
Additionally, formal parameters \verb+#+\textit{i} are replaced by
actual arguments inside the \texttt{toimage} environment
(see end of section~\ref{substimage} for an example of this feature).

\subsubsection{The \texttt{hevea} boolean register}\label{heveabool}

Boolean registers are provided by the \texttt{ifthen} package
(see~\cite[Section~C.8.5]{latex} and section~\ref{ifthen} in this
document).
\boolindex{hevea}Both the \texttt{hevea.sty} style file
and \hevea{} define the boolean register \texttt{hevea}.
However, this register initial value is \textit{false} for \LaTeX{}
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:
\begin{verbatim}
We get:
{\ifthenelse{\boolean{hevea}}{\purple}{}purple rain, purple rain}\ldots
\end{verbatim}
We get:
{\ifthenelse{\boolean{hevea}}{\purple}{}purple rain, purple rain}\ldots

%BEGIN LATEX
\medskip
%END LATEX


Another choice is using the \TeX{}-style conditional macro
\verb+\ifhevea+ (see Section~\ref{texcond}):
\begin{verbatim}
We get:
{\ifhevea\purple\fi purple rain, purple rain}\ldots
\end{verbatim}
We get: {\ifhevea\purple\fi purple rain, purple rain}\ldots

\index{comment!hevea@\texttt{\%HEVEA}}
\subsection{Comments}\label{comments}
\hevea{} processes all lines that start with \verb+%HEVEA+, while
\LaTeX{} treats these lines as comments.
Thus, this is a last variation on  the ``purple rain'' example:
\begin{verbatim}
We get
%HEVEA{\purple
purple rain, purple rain%
%HEVEA}%
\ldots
\end{verbatim}
(Note how comments are placed at the end of some lines to avoid spurious spaces
in the final output.)

We get:
%HEVEA{\purple
purple rain, purple rain%
%HEVEA}%
\ldots

Comments thus provide an alternative to loading the
\texttt{hevea} package. For user convenience, comment equivalents to
the \verb+latexonly+ and \verb+toimage+ environment are also provided:
\index{comment!begin latex@\texttt{\%BEGIN LATEX}}
\index{comment!begin image@\texttt{\%BEGIN IMAGE}}
\index{comment!end latex@\texttt{\%END LATEX}}
\index{comment!end image@\texttt{\%END IMAGE}}
\begin{center}
\begin{tabular}{ll}\hline
\multicolumn{1}{c}{environment} & \multicolumn{1}{c}{comment
equivalent}\\ \hline
\verb+\begin{latexonly}+\ldots{} \verb+\end{latexonly}+ &
\begin{tabular}{l}
\verb+%BEGIN LATEX+ \\
\ldots \\
\verb+%END LATEX+
\end{tabular}
\\ & \\ \hline
\verb+\begin{toimage}+\ldots{} \verb+\end{toimage}+ &
\begin{tabular}{l}
\verb+%BEGIN IMAGE+ \\
\ldots \\
\verb+%END IMAGE+
\end{tabular}
\end{tabular}
\end{center}
Note that \LaTeX{}, by ignoring comments, naturally performs the action
of processing text between \verb+%BEGIN+\texttt{\ldots} and %
\verb+%END+\texttt{\ldots} %
comments. However, no environment is opened and closed and no scope is
created while using comment equivalents.


\section{\label{imagen}With a little help from \LaTeX}
Sometimes,
\hevea{} just cannot process its input, but it remains acceptable to
have \LaTeX{} process it, to produce an image from
\LaTeX{} output and to include a link to this image into \hevea{}
output.
\hevea{} provides a limited support for doing this.

\subsection{The \textit{image}\label{image:file} file}

While outputting \filename{doc}\texttt{.html}, \hevea{} echoes some
of its input to the \filename{image} file,
\filename{doc}\texttt{.image.tex}.
\envindex{toimage}
Part of this process is done at the user's request.
More precisely, the following two constructs
send \textit{text} to the \filename{image} file:
\begin{flushleft}
\verb+\begin{toimage}+\\
\textit{text}\\
\verb+\end{toimage}+\\
~\\
\verb+%BEGIN IMAGE+\\
\textit{text}\\
\verb+%END IMAGE+
\end{flushleft}
Additionally, \verb+\usepackage+ commands, top-level and global
definitions
are automatically echoed to the image file. This enables using
document-specific commands in \textit{text} above.


\comdefindex{imageflush}
Output to the image file builds up a current page, which is flushed
by the \verb+\imageflush+ command.
This command has the following effect:  it outputs a strict page break
in the \filename{image} file, increments the image counter and
output a \verb+<img src="+\textit{pagename}\verb+.png">+ tag in \hevea{}
output file, where \textit{pagename} is build from the image counter
and \hevea{} output file name.
Then the \verb+imagen+ script has to be run by:
\begin{flushleft}
\verb+# imagen+ \filename{doc}
\end{flushleft}
\noindent This will process the \filename{doc}\texttt{.image.tex}
file through \LaTeX,
\texttt{dvips}, \texttt{ghostscript} and a few others tools, which must all be
present  (see section~\ref{requirements}), finally producing one
\textit{pagename}\texttt{.png} file per page in the \filename{image}
file.

The  usage of \verb+imagen+  is described at
section~\ref{imagenusage}. Note that \texttt{imagen} is a simple shell
script. Unix users can pass \texttt{hevea} the command-line option
\cmdopt{-fix}. Then \texttt{hevea} will
itself call \texttt{imagen}, when appropriate.





\subsection{A toy example}
Consider the ``blob'' example from section~\ref{blob}.
Here is the active part of a \texttt{blob.tex} file:
\begin{verbatim}
 \newcommand{\blob}{\rule[.2ex]{1ex}{1ex}}
 \blob\ Blob \blob
\end{verbatim}
This time, we would like \verb+\blob+ to produce a small black square, which
\verb+\rule[.2ex]{1ex}{1ex}+ indeed does in \LaTeX{}.
Thus we can write:
\begin{verbatim}
 \newcommand{\blob}{%
 \begin{toimage}\rule[.2ex]{1ex}{1ex}%
 \end{toimage}%
 \imageflush}
 \blob\ Blob \blob
\end{verbatim}
Now we issue the following two commands:
\begin{verbatim}
 # hevea blob.tex
 # imagen blob
\end{verbatim}
And we get:
\begin{htmlout}
\begin{htmlonly}
\newcommand{\blob}{%
\begin{toimage}\rule[.2ex]{1ex}{1ex}%
\end{toimage}%
\imageflush}\newsavebox{\blobbox}\sbox{\blobbox}{\blob}
\usebox{\blobbox}\ Blob \usebox{\blobbox}
\end{htmlonly}
\begin{latexonly}\vspace*{.5ex}
\image{realblob}
\end{latexonly}%
\end{htmlout}

Observe that the trick can be used to replace missing symbols by small
\texttt{.png} images. However, the cost may be prohibitive, text rendering
is generally bad, fine placement is ignored and font style changes are
problematic.
Cost can be lowered using \verb+\savebox+, but the other problems remain.


\subsection{Including Postscript images}\label{substimage}
\index{image inclusion!in Postscript|defocc}
In this section, a technique to transform included Postscript images
into included bitmap images is described.
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 Postscript images in
\LaTeX{} documents.

Included images are easy to manage: it suffices to let \LaTeX{} do the
job.
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):
\begin{verbatim}
 \begin{center}
 \epsfbox{round.ps}
 \end{center}
\end{verbatim}
Then, \hevea{} can have this image translated into a inlined (and
centered) \texttt{.png} image by modifying source as follows:
\begin{verbatim}
 \begin{center}
 %BEGIN IMAGE
 \epsfbox{round.ps}
 %END IMAGE
 %HEVEA\imageflush
 \end{center}
\end{verbatim}
(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
the \verb+\imageflush+ command is  inside
a \verb+%HEVEA+ comment --- see section~\ref{comments}.)

Then, processing \texttt{round.tex} through \hevea{} and
\texttt{imagen} yields:
\begin{htmlout}
\begin{center}
%BEGIN IMAGE
\includegraphics{round}%
%END IMAGE
%HEVEA\imageflush
\end{center}
\end{htmlout}
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{}
source code.
A better solution is to define the \verb+\epsfbox+
command, so that \hevea{} echoes  \verb+\epsfbox+ and its argument to
the image file and performs \verb+\imageflush+:
\begin{verbatim}
 \newcommand{\epsfbox}[1]{%
 \begin{toimage}
 \epsfbox{#1}
 \end{toimage}
 \imageflush}
\end{verbatim}
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}).
Putting it in the document source
protected inside an \verb+%HEVEA+ comment is a bad idea, %
because it might then get echoed to the \textit{image} file
and generate trouble when \LaTeX{} is later run by \texttt{imagen}.

Observe that the above definition of \verb+\epsfbox+ is a definition
and not a redefinition (\emph{i.e.}\ \verb+\newcommand+ is used and not
\verb+\renewcommand+),
because \hevea{} does not know about \verb+\epsfbox+ by default.
Also observe that this not a recursive definition, since
commands do not get expanded inside the \verb+toimage+ environment.

Finally, if the Postscript image is produced from a bitmap, it is
a pity to translate it back into a bitmap.
A better idea is first to generate a PNG file from the bitmap source
independantly
and then to include a link to that PNG file in \html{} output, see
section~\ref{imgsrc} for a description of this more adequate technique.


\subsection{Using filters}

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
\texttt{imagen} do the job.


Consider the \texttt{gpic} filter, for making drawings.
Source for \texttt{gpic} is enclosed in \verb+.PS+\ldots \verb+.PE+,
then the result is available to subsequent \LaTeX{} source as a \TeX{}
box \verb+\box\graph+.
For instance the following source, from a \texttt{smile.tex} file,
draws a ``Smile!'' logo as a centered
paragraph:
\begin{verbatim}
 .PS
 ellipse "{\Large\bf Smile!}"
 .PE
 \begin{center}
 ~\box\graph~
 \end{center}
\end{verbatim}
Both the image description (\verb+.PS+\ldots\ \verb+.PE+) and usage (\verb+\box\graph+)
are for the \filename{image} file, and they should be
enclosed by \verb+%BEGIN IMAGE+\ldots\ \verb+%END IMAGE+ comments.
Additionally, the image link is put where it belongs by an
\verb+\imageflush+ command:
\begin{verbatim}
 %BEGIN IMAGE
 .PS
 ellipse "{\Large\bf Smile!}"
 .PE
 %END IMAGE
 \begin{center}
 %BEGIN IMAGE
 ~\box\graph~
 %END IMAGE
 %HEVEA\imageflush
 \end{center}
\end{verbatim}
The \texttt{gpic} filter is applied first, then come \texttt{hevea}
and \texttt{imagen}:
\begin{verbatim}
 # gpic -t < smile.tex > tmp.tex
 # hevea tmp.tex -o smile.html
 # imagen smile
\end{verbatim}
And we get:
\ifpdf
\begin{center}
\image{smile}
\end{center}
\else
%BEGIN IMAGE
.PS
ellipse "{\Large\bf Smile!}"
.PE
%END IMAGE
\begin{center}
%BEGIN IMAGE
~\box\graph~
%END IMAGE
%HEVEA\imageflush
\end{center}
\fi
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.
However, writing in a generic style saves typing.
For instance, users may define the following environment for
centered \texttt{gpic} pictures in \LaTeX{}:
\begin{verbatim}
 \newenvironment{centergpic}{}{\begin{center}~\box\graph~\end{center}}
\end{verbatim}
Source code will now be as follows:
\begin{verbatim}
 \begin{centergpic}
 .PS
 ellipse "{\Large\bf Smile!}"
 .PE
 \end{centergpic}
\end{verbatim}
\hevea{} will process this source correctly, provided it is given its
own definition for the \verb+centergpic+ environment beforehand:
\begin{verbatim}
 \newenvironment{centergpic}
   {\begin{toimage}}
   {\box\graph\end{toimage}\begin{center}\imageflush\end{center}}
\end{verbatim}
Assuming that the definition above is in a \ahref{\heveaurl/examples/smile.hva}{smile.hva} file,
the command sequence for translating
\ahref{\heveaurl/examples/smile.tex}{smile.tex} \mbox{now is}:
\begin{verbatim}
 # gpic -t < smile.tex > tmp.tex
 # hevea smile.hva tmp.tex -o smile.html
 tmp.tex:5: Warning: ignoring definition of \centergpic
 tmp.tex:5: Warning: not defining environment centergpic
 # imagen smile
\end{verbatim}
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
environment.


\section{\label{hacha}Cutting your document into pieces with \hacha}
\hevea{} outputs a single \texttt{.html} file. This file can be
cut into pieces at various sectional units by {\hacha}

\subsection{Simple usage}
First generate your {\html} document by applying \hevea{}:
\begin{flushleft}
\texttt{\# hevea }\filename{doc}\texttt{.tex}
\end{flushleft}
Then cut \filename{doc}\texttt{.html} into pieces by the command:
\begin{flushleft}
\texttt{\# hacha }\filename{doc}\texttt{.html}
\end{flushleft}
This will generate a simple root file
\texttt{index.html}.
This root file holds document title, abstract and a simple table of
contents.
Every item in the table of contents contains a link to or into a file
that holds a ``cutting'' sectional unit.
By default, the cutting sectional unit is {\em section} in the
\filename{article} style and {\em chapter} in the \filename{book}
style.
The name of those files are \filename{doc}001\texttt{.html},
\filename{doc}002\texttt{.html}, etc.

Additionally, one level of sectioning below the cutting unit
(\emph{i.e.}\ subsections in the \filename{article} style and sections in the
\filename{book} style) is shown
as an entry in the table of contents.
Sectional units above the cutting section (\emph{i.e.}\ parts in both
\filename{article} and \filename{book} styles) close the current table
of contents and open a new one.
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
\verb+-o+ option:
\begin{flushleft}
\texttt{\# hacha -o root.html }\filename{doc}\texttt{.html}
\end{flushleft}


Some of \hevea{} output get replicated in all the files generated by
\hacha{}.
\label{html:footer}%
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
include the following commands in the document preamble:
\begin{flushleft}
\quad\verb+\htmlhead{+\textit{header}\verb+}+\\
\quad\verb+\htmlfoot{+\textit{footer}\verb+}+
\end{flushleft}

\hacha{} also makes every page it generates a clone of its input as
regards attributes to the \verb+<body ...>+ opening tag and
meta-information from the \verb+<head>+\ldots{} \verb+<\head>+
block. See section~\ref{metadef} for examples of this replication
feature.

\label{hacha:style}\index{style-sheets!and \hacha}%
By contrast, style information specified in the \verb+style+ elements
from rom the \verb+<head>+\ldots{} \verb+<\head>+
block is not replicated. Instead, all style definitions are collected into an
external style sheet file whose name is \filename{doc}\texttt{.css},
and all generated {\html} files adopt \filename{doc}\texttt{.css} as
an external style sheet.
It is important to notice that, since version 1.08, \hevea{} produces
a \verb+style+ element by itself, even if users do not explicitely
use styles. As a consequence,
\hacha{} normally produces a
file \filename{doc}\texttt{.css}, which should not be forgotten while
copying files to their final destination after a run of~\hacha.

\subsection{Advanced usage}

\hacha{} behaviour 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
\LaTeX{}, provided it loads the
\texttt{hevea.sty} style file from the \hevea{} distribution.
(See section~\ref{both} for details on this style file).
An alternative to loading the \texttt{hevea} package is to put
all cutting instructions in comments starting with \verb+%HEVEA+.



\subsubsection{Principle}
{\hacha} recognizes all sectional units, ordered as follows, from
top to bottom: {\em
part}, {\em chapter},
{\em section}, {\em subsection}, {\em subsubsection},
\emph{paragraph} and \emph{subparagraph}.

At any point between \verb+\begin{document}+ and
\verb+\end{document}+,
there exist a current cutting sectional unit (cutting unit for short),
a current cutting depth, a root file and an output file.
Table of contents output goes to the root file, normal output goes to
the 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}
output file (\emph{i.e.}\ \texttt{index.html}).
The cutting unit and the cutting depth are set to default values that
depend on the document style.

\subsubsection{Cutting macros}
The following cutting instructions are for use in the document
preamble. They command the cutting scheme of the whole document:
\comindex{cuttingunit}\comindex{tocnumber}\comindex{notocnumber}%
\countindex{cuttingdepth}%
\begin{description}
\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:
\begin{flushleft}
\verb+\renewcommand{\cuttingunit}{+{\it secname}\verb+}+.
\end{flushleft}
\item[{\tt\char92 tocnumber}] Instruct \hevea{} to put section numbers
into table of content entries.
\item[{\tt\char92 notocnumber}] Instruct \hevea{} \emph{not} to put
section numbers
into table of content entries. This is the default.
\item[{\tt cuttingdepth}]
This is a counter that holds the document cutting depth.
You can change the default value of 1 by doing
\verb+\setcounter{cuttingdepth}{+{\it numvalue}\verb+}+.
A cutting depth of zero means no other entries than the cutting units
in the table of contents.
\end{description}

Other cutting instructions are to be used after
\verb+\begin{document}+. They all generate \html{} comments in \hevea{}
output.
These comments then act as instructions to {\hacha}.
\comindex{cuthere}
\comindex{cutdef}
\comindex{cutend}
\begin{description}
\item[{\tt\char92 cuthere\{}{\it secname}{\tt\}\{}{\it itemtitle}{\tt\}}]
   Attempt a cut.
   \begin{itemize}
   \item If {\it secname} is the current cutting  unit or
   the keyword \texttt{now}, then
   a new output file is started and an entry in the current table of contents
   is generated, with title {\it itemtitle}. This entry holds a link
   to the new output file.
   \item If {\it secname} is above the cutting  unit, then the
   current table of contents is closed. The output file is set to the
   current root file.
   \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
   contents.
   This entry contains {\em itemtitle} and a link to the point where
   \verb+\cuthere+ appears.
   \item Otherwise, no action is performed.
   \end{itemize}

\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.
   The output file becomes the root file.
   Result is unspecified if whatever {\em secname} expands to is
   a sectional unit name above
   the current cutting  unit, is not a valid sectional unit name or if
   {\em depth} does not expand to a small positive number.
\item[{\tt\char92 cutend}]
   End the current table of contents. This closes the scope of the
   previous \verb+\cutdef+. The cutting unit and cutting depth are
   restored.
   Note that \verb+\cutdef+ and \verb+\cutend+ must be properly balanced.
\end{description}
Commands \verb+\cuthere+ and \verb+\cutend+ have starred variants,
which behave identically except for footnotes (see~\ref{hachafoot}).

Default settings work as follows:
\verb+\begin{document}+ performs
\begin{verbatim}
\cutdef*[\value{cuttingdepth}]{\cuttingunit}
\end{verbatim}
and \verb+\end{document}+ performs \verb+\cutend*+.
All sectioning commands perform \verb+\cuthere+,
with the sectional unit name as first argument and the (optional, if
present) sectioning
command argument (\emph{i.e.}\ the section title) as second argument.
Note that starred versions of the sectioning commands also perform
cutting instructions.

\subsubsection{Table\label{table:link:style} of links organisation}
A table of links generated by \hacha{} is a list
of links to generated files.
Additionally, some sublists may be present, up to a certain depth.
The items in those sublists are
links inside generated files, they point to sectional unit titles
below the cutting unit, up to a certain depth.

More precisely, let $A$ be a certain sectional unit (\emph{e.g.}
``part''), let $B$ be just below $A$
(\emph{e.g.} ``section''),
and let $C$ be just below $C$ (\emph{e.g.} ``subsection'').
Further assume that cutting is performed at level~$B$ with a depth of
more than one.
Then, every unit~$A$ holds a one or several tables of links
to generated files, and each generated file normally holds a $B$~unit.
Sublists with links to $C$~units inside $B$~units normally appear in the
tables of links of level~$A$.
The command-line options \cmdopt[hacha]{-tocbis}
and~\cmdopt[hacha]{-tocter} instruct \texttt{hacha}
to put sublists at other places.
With \texttt{-tocbis} sublists are duplicated at the beginning
of the $B$~level files; while with \texttt{-tocter} sublist only
appear at the beginning
of the $B$~level files.

In my opinion,
default style is appropriate for documents with short $B$~units;
while \texttt{-tocbis} style
is appropriate for documents with long $B$~units with
a few sub-units; and \texttt{-tocter} style is appropriate
for documents with long $B$~units with
a lot of sub-units.
\ifhevea
As you may have noticed, this manual is cut by following the
\texttt{-tocbis}~style.\fi

Whatever the style is, if a $B$~unit is cut
(\emph{e.g.} because its text is enclosed in
\verb+\cutdef{+$C$\verb+}+\ldots{} \verb+\cutend+),
then every $C$ unit goes into its own file and there is no sublist
after the relevant $B$~level entry in the $A$~level table of links.

\subsubsection{Examples}

Consider, for instance, a \filename{book} document with a long chapter
that you want to cut at the section level, showing subsections:
\begin{verbatim}
\chapter{A long chapter}
.....

\chapter{The next chapter}
\end{verbatim}
\comindex{cutdef}\comindex{cutend}
Then, you should insert a \verb+\cutdef+ at chapter start and a
\verb+\cutend+ at chapter end:
\begin{verbatim}
\chapter{A long chapter}
%HEVEA\cutdef[1]{section}
.....
%HEVEA\cutend
\chapter{The next chapter}
\end{verbatim}
Then, the file
that would otherwise contain the long chapter now contains the chapter
title and a table of sections.
No other change is needed, since the command \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,
for \LaTeX{} not to be disturbed).

\comindex{cuthere}
\comindex{cuttingunit}
The \verb+\cuthere+ macro can be used to put some document parts into
their own file.
This may prove appropriate for long cover pages or abstracts that would
otherwise go into the root file.
Consider the following document:
\begin{verbatim}
\documentclass{article}

\begin{document}

\begin{abstract} A big abstract \end{abstract}
...
\end{verbatim}
Then, you make the abstract go to its own file as it was a cutting
unit by typing:
\begin{verbatim}
\documentclass{article}
\usepackage{hevea}

\begin{document}
\cuthere{\cuttingunit}{Abstract}
\begin{abstract} A big abstract \end{abstract}
...
\end{verbatim}
(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).


\subsubsection{More and More Pages in Output}
\ttindex{deepcut}{package}\ttindex{figcut}{package}%
In some situations it may be appropriate to produce many
pages from one source files.
More specifically, loading the \texttt{deepcut} package will put
all sectioning units of your document (from \verb+\part+ to
\verb+\subsection+ in their own file.

Similarly, loading the \texttt{figcut} package will make all figures
and tables go into their own file.
The \texttt{figcut} package accepts two options, \texttt{show} and
\texttt{noshow}. The former, which is the default, instructs \hevea{}
to repeat the caption into the main flow of text, with a link to the figure.
The latter option disables the feature.


\subsection{More Advanced Usage}
In this section we show how to alter some details of \hacha{}
behaviour.
This includes controlling output file names and the title of generated
web pages and introducing arbitrary cuts.

\subsubsection{Controlling\label{cutname} output file names}
\cutname{cutname.html}%
\comdefindex{cutname}%
When invoked as \texttt{hacha \filename{doc}.html},
\hacha{} produces a \texttt{index.html} table of links file that
points into \filename{doc}\texttt{001.html},
\filename{doc}\texttt{002.html}, etc. content files.
This is not very convenient when one wishes to point inside the
document from outside.
However, the \verb+\cutname{+\textit{name}\verb+}+ command
sets the name of  the current output file name as \textit{name}.

Consider a document cut at the section level, which contains the
following important section:
\begin{verbatim}
\section{Important\label{important} section}
...
\end{verbatim}
To make the important section goes into file \texttt{important.html},
one writes:
\begin{verbatim}
\section{Important\label{important} section}\cutname{important.html}
...
\end{verbatim}
Then, section ``Important section'' can be referenced from
an \hevea{} unaware \html{} page by:
\begin{verbatim}
In this document, there is a very
<a href="important.html#important">important section</a>.
\end{verbatim}
\ifhevea
If you are reading the \html{} version of this manual, you may check
that you are now reading file \texttt{cutname.html}.
This particular file name has been specified from the source
using \verb+\cutname{cutname.html}+.
\fi

\subsubsection{Controlling page titles}
\comdefindex{htmlprefix}
When \hacha{} creates a web page from a given sectional unit,
the title of this page normally is the name of the sectional unit.
For instance, the title of this very page should be
``Cutting your document into pieces with \hacha''.
It is possible to insert some text at the beginning of all page
titles, by using the \verb+\htmlprefix+ command.
Hence, by writing
\verb+\htmlprefix{\hevea{} Manual: }+ in the document,
the title of this page would become:
``\hevea{} Manual: Cutting your document into pieces with \hacha''
and the title of all other pages would show the same prefix.

\subsubsection{Links for the root file}
\comdefindex{toplinks}
The command \verb+\toplinks{+\textit{prev}\verb+}{+\textit{up}\verb+}{+\textit{next}\verb+}+ instructs \hacha{}  to put links to a
``previous'', ``up'' and ``next'' page in the root file.
The following points are worth noticing:
\begin{itemize}
\item The \verb+\toplink+ command must appear in the document preamble
(\emph{i.e.}\ before \verb+\begin{document}+).
\item The arguments
\textit{prev}, \textit{up} and \textit{next} should expand to urls,
notice that these argument are processed (see section~\ref{urlareprocessed}).
\item When one of the expected argument is left empty,
the corresponding link is not generated.
\end{itemize}
This feature can prove useful to
relate documents that are generated independently by
\hevea{} and \hacha{}.

\subsubsection{Controlling link contents from the document}
\comdefindex{setlinkstext}%
By default the links to the previous, up and next pages show a small
icon (an appropriate arrow). This can be changed with the command
\verb+\setlinkstext{+\textit{prev}\verb+}{+\textit{up}\verb+}{+\textit{next}\verb+}+,
where \textit{prev}, \textit{up} and \textit{next} are some \LaTeX{}
source.
\comindex{imgsrc}
For instance the default behaviour is equivalent to:
\begin{verbatim}
\setlinkstext
  {\imgsrc[alt="Previous"]{previous_motif.svg}}
  {\imgsrc[alt="Up"]{contents_motif.svg}}
  {\imgsrc[alt="Next"]{next_motif.svg}}
\end{verbatim}
Command \verb+\setlinkstext+ behaves as \verb+\toplinks+ does.
That is, it must occur in document preamble, arguments are processed
and empty arguments yield no effect (\emph{i.e.}\ defaults apply).

\subsubsection{Complete control over navigation links}
\comdefindex{formatlinks}%
The previous commands only impact the contents of the navigation links.
It is possible, although reserved to avanced users,  to achieve greater control
by using the \verb+\formatlinks+ command. The \verb+\formatlinks+ command
takes four arguments which are command themselves. The last three command
format the ``previous'', ``up'' and ``next'' links respectively,
while the first argument formats the resulting group of links.
For instance, one can avoid images and for arrows and typeset the full set of navivation links in a purple border
(see Section~\ref{style:sheets} for styling techniques) as follows:
\begin{verbatim}
\newstyle{a.navarrow}{font-family:monospace;font-size:x-large;color:purple}
\newstyle{div.navarrows}{border:solid purple;display:inline-block;padding:1ex;}
\newcommand{\myprev}[1]{\ahref[class="navarrow" title="Previous" ]{#1}{$\rightarrow$}\quad}
\newcommand{\myup}[1]{\quad\ahref[class="navarrow" title="Up" ]{#1}{$\uparrow$}\quad}
\newcommand{\mynext}[1]{\quad\ahref[class="navarrow" title="Next" ]{#1}{$\writearrow$}}

\newcommand{\mylinks}[1]{\@open{div}{class="navarrows"}#1\@close{div}\end{center}}
\formatlinks{\mylinks}{\myprev}{\myup}{\mynext}
\end{verbatim}

\subsubsection{Cutting a document anywhere}
\envdefindex{cutflow}
Part of a document goes to a separate file when enclosed in a
\verb+cutflow+ environment:
\begin{flushleft}
  \verb+\begin{cutflow}{+\textit{title}\verb+}+\ldots\verb+\end{cutflow}+
\end{flushleft}

\noindent The content ``\ldots'' will go into a file of its
own, while
the argument \textit{title} is used as the title of the introduced
\html{} page.

The \html{} page introduced here does not belong to the normal flow of
text.
Consequently, one needs an explicit reference from the normal flow of text
into the content of the \verb+cutflow+ environment.
This will occur naturally when the content of the \verb+cutflow+ environment.
contains a \verb+\label+ construct.
This look natural in the following quiz example:
\begin{verbatim}
\paragraph{A small quiz}
\begin{enumerate}
\item What is black?
\item What is white?
\item What is Dylan?
\end{enumerate}
Answers in section~\ref{answers}.
\begin{cutflow}{Answers}
\paragraph{Quiz answers}\label{answers}
\begin{enumerate}
\item Black is black.
\item White is white.
\item Dylan is Dylan.
\end{enumerate}
\end{cutflow}
\end{verbatim}
\ifhevea The example yields:
\paragraph{A small quiz}
\begin{enumerate}
\item What is black?
\item What is white?
\item What is Dylan?
\end{enumerate}
Answers in section~\ref{answers}.
\begin{cutflow}{Answers}
\paragraph{Quiz answers}\label{answers}
\begin{enumerate}
\item Black is black.
\item White is white.
\item Dylan is Dylan.
\end{enumerate}
\end{cutflow}
\fi
\comindex{aname}\comindex{ahrefloc}
However,introducing \html{} hyperlink targets and
references with the \verb+\aname+ and \verb+\ahrefloc+ commands
(see section~\ref{hyperlink})
will be more practical most of the time.

\envdefindex{cutflow*}The starred variant environment
\verb+cutflow*+ is the same
as \verb+cutflow+, save for the \html{} header and footer (see
Section~\ref{html:footer}) which are not replicated in the introduced
page.


\subsubsection{Footnotes\label{hachafoot}}
\comdefindex{footnoteflush}%
\comdefindex{flushdef}%
Footnote texts (given as arguments either to \verb+\footnote+ or
\verb+\footnotetext+) do not go directly to output.
Instead, footnote texts accumulate internally in a \emph{buffer},
awaiting to be flushed.
The flushing of notes is controlled by the means of a current
\emph{flushing unit}, which is a sectional unit name or
\textit{document} --- a fictional unit above all units.
At any point, the current flushing unit is the value of the
command~\verb+\@footnotelevel+\index{"@footnotelevel@\texttt{\char92"@footnotelevel}|defocc}.
In practice, the flushing of footnote texts is performed by two commands:
\begin{itemize}
\item \verb+\flushdef{+\textit{secname}\verb+}+ simply sets
the flushing unit to \textit{secname}.
\item \verb+\footnoteflush{+\textit{secname}\verb+}+ acts
as follows:
\begin{itemize}
\item If argument \textit{secname} is equal to or above the
current flushing unit, then footnote texts are flushed (if any).
In the output, the texts themselves are surrounded by special comments
that tag them as footnote texts and record \textit{secname}.
\item Otherwise, no action is performed.
\end{itemize}
\end{itemize}
The \filename{article} style file performs \verb+\flushdef{document}+,
while the \filename{book} style file performs  \verb+\flushdef{chapter}+.
At the end of processing, \verb+\end{document}+ performs
\verb+\footnoteflush{\@footnotelevel}+, so as to flush any pending notes.


Cutting commands interact with footnote flushing as follows:
\begin{itemize}
\item \verb+\cuthere{+\textit{secname}\verb+}+
executes \verb+\footnoteflush{+\textit{secname}\verb+}+.
Remember that all sectioning commands perform
\verb+\cuthere+ with their sectional unit name as argument.
\item \verb+\cutdef{+\textit{secname}\verb+}+
saves the current flushing unit and  buffer on some internal stack,
starts a new buffer for footnote texts, and
sets the current flushing unit to \textit{secname}
(by performing \verb+\flushdef{+\textit{secname}\verb+}+).
\item \verb+\cutend+ first flushes any pending texts
(by performing \verb+\footnoteflush+ with the current flushing unit
as argument), and restores the flushing unit and footnote text buffer saved
by the matching \verb+\cutdef+.
\item The starred variants \verb+\cutdef*+ and~\verb+\cutend*+ perform
no operation that is related to footnotes.
\end{itemize}

Later, when running across footnote texts in its input file, \hacha{}
sometimes put notes in a separate file.
More precisely, \hacha{} has knowledge of the
current \emph{cutting level}, the current sectional unit where
cuts occur --- as given by the relevant \verb+\cutdef+.
Moreover, \hacha{} knows the current \emph{section level} ---
that is, the last sectional command processed.
Besides, \hacha{} extracts the \emph{note level} from the comments
that surround the notes (as given by the command
\verb+\footnoteflush+ that produced the notes).
Then, \hacha{} creates a separate file for notes
when the cutting level and the note level differ,
or when the current level is above the cutting level
(\emph{e.g.} the current level is \texttt{document} while the cutting
level is \texttt{chapter}).
As a result, notes should stay where they are when they occur at the end of
\hacha{} output file and otherwise go to a separate file.

To make a complicated story even more complicated,
footnotes in~\texttt{minipage} environments or in the arguments
to \verb+\title+ or \verb+\author+ have a different, I guess satisfactory,
behaviour.

Given the above description, footnotes are managed by default as follows.
\begin{itemize}
\item In style~\filename{article}, \texttt{hevea} puts all footnotes
go at the end of the \html{} file.
A later run of~\texttt{hacha} creates a separate footnote file.
\item In style~\filename{book}, footnotes are collected at the end of
chapters. A later run of ~\texttt{hacha} leaves them where they
are. Footnotes in the title or author names are managed specially,
they will normally appear at the end of the root file.
\end{itemize}
\comindex{flushdef}%
In case you wish to adopt a \filename{book}-like behaviour for
an \filename{article} (footnotes at the end of sections),
it suffices to insert \verb+\flushdef{section}+ in the document
preamble.


\ifhevea
We now give a few example of interaction between notes and cutting.
We first consider normal behaviour.
The page you are reading is a section page, since the current
cutting unit is ``section''. The current unit is ``subsection''.
The following two subsubsections are sent to their own files by
the means of a \verb+\cutdef{subsubsection}+/\verb+\cutend+ pair.
As a result the text of footnotes appear at the end of the
subsubsection pages.
\cutdef{subsubsection}
\subsubsection{A cut subsubsection}
A note in a subsubsection, flushed at subsubsections.\footnote{At the
end of my page.}
\subsubsection{Another cut subsubsection}
Another note in a subsubsection, flushed at subsubsections.\footnote{At the
end of my page.}
\cutend

The following two subsubsections are sent to their own files by
the means of a \verb+\cutdef*{subsubsection}+/\verb+\cutend*+ pair.
As a result, the text of footnotes in the subsections appear
at the end of the current section page.\footnote{Standard section footnote.}
\cutdef*{subsubsection}
\subsubsection{A cut subsubsection}
A note in a subsubsection, flushed at sections.\footnote{Sent at
the end of \texttt{cutname.html}}
\subsubsection{Another cut subsubsection}
Another note in a subsubsection, flushed at sections.\footnote{Sent at
the end of \texttt{cutname.html}}
\cutend*

Finally, to send the footnotes in subsubsections
to a separate web page, one should use
a~\verb+\cutdef{subsubsection}+/\verb+\cutend+ pair
(to create a proper buffer for subsubsection notes),
redefine the flushing unit, and flush notes explicitly.
\begin{verbatim}
\cutdef{subsubsection}\flushdef{document}%
\subsubsection{...}
  ...
\footnoteflush{document}\cutend
\end{verbatim}

\cutdef{subsubsection}\flushdef{document}
\subsubsection{A cut subsubsection}
A note in a subsubsection flushed at document level.\footnote{Sent to a
separate file}
\subsubsection{Another cut subsubsection}
Another note in a subsubsection at document level.\footnote{Sent to
a separate file}
\footnoteflush{document}%
\cutend
\fi

\section{Generating \html{} constructs}
\hevea{} output language being \html, it is normal for users to insert
hypertext constructs their documents, or to control colours.

\subsection{High-Level Commands}
\hevea{} provides high-level commands for generating
hypertext constructs.
Users are advised to use these commands in the first place,
because it is easy to write incorrect \html{} and that writing
\html{} directly may interfere in nasty ways with \hevea{} internals.


\subsubsection{Commands \label{hyperlink}for Hyperlinks}\index{hyperlinks}
A few commands for hyperlink  management and included images
are provided, all these
commands have appropriate 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.

\comdefindex{ahref}\comdefindex{ahrefurl}\comdefindex{footahref}%
\comdefindex{ahrefloc}%
\comdefindex{aname}\comdefindex{mailto}\comdefindex{imgsrc}\comdefindex{home}%
%BEGIN LATEX
\bigskip
%END LATEX
\begin{tabular}{l<{\qquad}p{.3\linewidth}@{\qquad}p{.3\linewidth}}
\multicolumn{1}{c}{Macro} & \multicolumn{1}{c}{\hevea} &
\multicolumn{1}{c}{\LaTeX}\\
\hline

\verb+\ahref{+\textit{url}\verb+}{+\textit{text}\verb+}+ &
make \textit{text} an hyperlink to \textit{url} &
echo \textit{text}\\ \hline

\verb+\footahref{+\textit{url}\verb+}{+\textit{text}\verb+}+ &
make \textit{text} an hyperlink to \textit{url} &
make \textit{url} a footnote to \textit{text},
\textit{url} is shown in typewriter font\\ \hline

\verb+\ahrefurl{+\textit{url}\verb+}+ &
make \textit{url} an hyperlink to \textit{url}.
&
typeset \textit{url} in typewriter font\\ \hline

\verb+\ahrefloc{+\textit{label}\verb+}{+\textit{text}\verb+}+ &
make \textit{text} an hyperlink to \textit{label} inside the document
&
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

\verb+\mailto{+\textit{address}\verb+}+ &
make \textit{address} a ``mailto'' link to \textit{address} &
typeset \textit{address} in typewriter font
\\ \hline
\verb+\imgsrc[+\textit{attr}\verb+]{+\textit{url}\verb+}+
& insert \textit{url} as an image, \textit{attr} are attributes in the
\html{} sense & do nothing \\ \hline
\verb+\home{+\textit{text}\verb+}+ &
\multicolumn{2}{p{.6\linewidth}}{produce a home-dir url both for output and links, output aspect is: ``\home{\textit{text}}''}
\end{tabular}

\label{urlareprocessed}It is important to notice that all arguments
are processed.
For instance, to insert a link to
my home page, (\verb+http://pauillac.inria.fr/~maranget/index.html+),
you should do something like this:
\begin{verbatim}
\ahref{http://pauillac.inria.fr/\home{maranget}/index.html}{his home page}
\end{verbatim}

Given the frequency of \verb+~+, \verb+#+ etc. in urls,
this is annoying. Moreover, the immediate solution, using \verb+\verb+,
\verb+\ahref{\verb" ... /~maranget/..."}{his home page}+
does not work, since \LaTeX{} forbids verbatim formatting
inside command arguments.

\comindex{url}
Fortunately, the \texttt{url} package provides a very convenient
\verb+\url+ command that acts like \verb+\verb+ and can appear in
other command arguments
(unfortunately, this is not the full story, see section~\ref{urlpackage}).
Hence, provided the \texttt{url} package is loaded,
a more convenient reformulation of the example above is:
\begin{verbatim}
\ahref{\url{http://pauillac.inria.fr/~maranget/index.html}}{his home page}
\end{verbatim}
Or even better:
\begin{verbatim}
\urldef{\lucpage}{\url}{http://pauillac.inria.fr/~maranget/index.html}
\ahref{\lucpage}{his home page}
\end{verbatim}
It may seem complicated, but this is a safe way to have a
document processed both by \LaTeX{} and \hevea{}.
Drawing a line between url typesetting and hyperlinks is correct,
because users may sometime want urls to be processed and some other
times not.
Moreover, \hevea{} (optionally) depends on only one third party package:
\texttt{url}, which is as correct as it can be and well-written.



\comindex{oneurl}
\comindex{footurl}
In case the \verb+\url+ command is undefined
at the time \verb+\begin{document}+ is processed, the commands
\verb+\url+, \verb+\oneurl+ and \verb+\footurl+ are defined as
synonymous for
\verb+\ahref+, \verb+\ahrefurl+ and \verb+\footahref+, thereby
ensuring
some compatibility with older versions of \hevea.
Note that this usage of \verb+\url+ is deprecated.

\subsubsection{\html{} style colours}\label{color:high}
Specifying colours both for \LaTeX{} and
\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 colours.
There are sixteen predefined colours:
\begin{center}
\begin{tabular}{p{.7\linewidth}}
%HEVEA\black
\verb+\black+,
%HEVEA\silver
\verb+\silver+,
%HEVEA\gray
\verb+\gray+,
%HEVEA\white
\verb+\white+,
%HEVEA\maroon
\verb+\maroon+,
%HEVEA\red
\verb+\red+,
%HEVEA\fuchsia
\verb+\fuchsia+,
%HEVEA\purple
\verb+\purple+,
%HEVEA\green
\verb+\green+,
%HEVEA\lime
\verb+\lime+,
%HEVEA\olive
\verb+\olive+,
%HEVEA\yellow
\verb+\yellow+,
%HEVEA\navy
\verb+\navy+,
%HEVEA\blue
\verb+\blue+,
%HEVEA\teal
\verb+\teal+,
%HEVEA\aqua
\verb+\aqua+
\end{tabular}
\end{center}
\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 declaration
%HEVEA{\htmlcolor{404040}%
\verb+\htmlcolor{404040}+
%HEVEA}%
changes font color to dark gray,

\subsection{More on included\label{imgsrc} images}
\index{image inclusion!bitmap}\comindex{imgsrc}
The \verb+\imgsrc+ command becomes handy when one has images both in
Postscript and GIF (or PNG or JPG) format.  As explained in
section~\ref{substimage}, Postscript images can be included in
\LaTeX{} documents by using the \verb+\epsfbox+ 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:
\begin{verbatim}
\epsfbox{screenshot.ps}
\end{verbatim}
We may very well also have a GIF version of the screenshot image
(or be able to produce one easily using image converting tools),
let us store it in a \texttt{screenshot.ps.gif} file.
Then, for \hevea{} to include a link to the GIF image in its
output, it suffices
to define the \verb+\epsfbox+ command in the \texttt{macro.hva} file
as follows:
\begin{verbatim}
\newcommand{\epsfbox}[1]{\imgsrc{#1.gif}}
\end{verbatim}
Then \hevea{} has to be run as:
\begin{verbatim}
# hevea macros.hva doc.tex
\end{verbatim}
Since it has its own definition of \verb+\epsfbox+, \hevea{} will
silently include a link the GIF image and not to the Postscript image.

If another naming scheme for image files is preferred, there are
alternatives.
For instance, assume that Postscript files are of the kind
\textit{name}\texttt{.ps}, while GIF files are of the kind
\textit{name}\texttt{.gif}.
Then, images can be included using
\verb+\includeimage{+\textit{name}\verb+}+, where
\verb+\includeimage+ is a specific user-defined command:
\begin{verbatim}
\newcommand{\includeimage}[1]{\ifhevea\imgsrc{#1.gif}\else\epsfbox{#1.ps}\fi}
\end{verbatim}
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:
\begin{verbatim}
\newcommand{\includeimage}[1]{%
%HEVEA\imgsrc{#1.gif}%
%BEGIN LATEX
\epsfbox{#1.ps}
%END LATEX
}
\end{verbatim}
When the Postscript file has been produced by
translating a bitmap file, this simple method of making a bitmap image and
using the \verb+\imgsrc+ command 
is the most adequate.
It should be preferred over using the more automated \textit{image} file
mechanism (see section~\ref{imagen}),
which will translate the image back from
Postscript to bitmap format and will thus degrade it.




\subsection{Internal \label{internal}macros}
In this section a few of \hevea{} internal macros are
described.
Internal macros occur at the final expansion stage of \hevea{} and
invoke Objective Caml code.

Normally, user source code should not use them, since
their behaviour may change from one version of \hevea{} to another and
because using them incorrectly easily
crashes \hevea.
However:
\begin{itemize}
\item Internal macros
are almost mandatory for writing supplementary base style files.
\item Casual usage is a convenient (but dangerous) way to finely control
output (cf. the examples in the next section).
\item Knowing a little about internal macros helps in understanding how
\hevea{} works.
\end{itemize}


\index{block-level elements}
The general principle of \hevea{} is that \LaTeX{} environments
\verb+\begin{+\textit{env}\verb+}+\ldots{}
\verb+\end{+\textit{env}\verb+}+ get
translated into \html{} block-level elements \verb+<+\textit{block}
\textit{attributes}\verb+>+\ldots{} \verb+</+\textit{block}\verb+>+.
More specifically, such block level elements are opened by the
internal macro \verb+\@open+ and closed by the internal macro
\verb+\@close+.
As a special case, \LaTeX{} groups \verb+{+\ldots{} \verb+}+
get translated into \html{} \emph{groups}, which are shadow block-level
elements with neither opening nor closing tag.

In the following few paragraphs, we sketch the interaction of
\verb+\@open+\ldots\verb+\@close+ with paragraphs.
Doing so, we intend to warn users about the complexity
of the task of producing correct \html{}, and to encourage
them to use internal macros, which, most of the time, take nasty
details into account.

Paragraphs are rendered by \verb+p+ elements, which are opened and
closed automatically.
More specifically, a first \verb+p+ is opened after
\verb+\begin{document}+, then paragraph breaks close the active
\verb+p+ and open a new one.
The final \verb+\end{document}+ closes the last \verb+p+.
In any occasion, paragraphs consisting only of space characters
are discarded silently.

Following \html{} ``normative reference~\cite{html}'', block-level
elements cannot occur inside \verb+p+; more precisely,
block-level opening tags implicitly close any active \verb+p+.
As a consequence,
\hevea{} closes the active \verb+p+ element when it processes
\verb+\@open+
and opens a new \verb+p+ when it processes the matching
\verb+\@close+.
Generally, no \verb+p+ element is opened by default inside block-level
elements, that is, \hevea{} does not immediately open \verb+p+ after having
processed \verb+\@open+.
However, if a paragraph break occurs later, then a new \verb+p+
element is opened, and will be closed automatically
when the current block is closed.
Thus, the first ``paragraph'' inside block-level elements
that include several paragraphs is not a \verb+p+ element.
That alone probably prevents the consistent styling
of paragraphs with style sheets.

Groups behave differently, opening or closing them does
not close nor open \verb+p+ elements.
However, processing paragraph breaks inside groups involves temporarily
closing all groups up to the nearest enclosing \verb+p+, closing it,
opening a new \verb+p+ and finally re-opening all groups.
Opening a block-level element inside a group, similarly
involves closing the active \verb+p+ and opening a new \verb+p+
when the matching \verb+\@close+ is processed.

Finally, display mode (as introduced by \verb+$$+) is also
complicated. Displays basically are \verb+table+ elements with one row
(\verb+tr+), and \hevea{} manages to introduce table cells (\verb+td+)
where appropriate.  Processing \verb+\@open+ inside a display
means closing the current cell, starting a new cell, opening the
specified block, and then immediately opening a new display.
Processing the matching \verb+\@close+ closes the internal
display, then the specified block, then the cell and finally opens a
new cell. In many occasions (in particular for groups), either cell
break or the internal display may get cancelled.


\index{"@print@\texttt{\char92"@print}|defocc}
\index{"@getprint@\texttt{\char92"@getprint}|defocc}
\index{"@print"@u@\texttt{\char92"@print"@u}|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{"@styleattr@\texttt{\char92"@styleattr}|defocc}
\index{"@span@\texttt{\char92"@span}|defocc}
\index{"@nostyle@\texttt{\char92"@nostyle}|defocc}
\index{"@clearstyle@\texttt{\char92"@clearstyle}|defocc}
\index{"@fontsize@\texttt{\char92"@fontsize}|defocc}
\index{"@fontcolor@\texttt{\char92"@fontcolor}|defocc}
It is important to notice that primitive arguments \emph{are}
processed (except for the \verb+\@print+~primitive, and for some of
the basic style primitives).  Thus, some characters cannot be given
directly (e.g. \verb+#+ and \verb+%+ must be given as \verb+\#+ and
\verb+\%+).

\begin{description}
\item[{\tt\char92 @print\char123}{\it text}{\tt\char125}] Echo
  \textit{text} verbatim.  As a consequence use only ASCII in
  \textit{text}.

\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 \html~tags.

\item[{\tt\char92 @hr[}{\it attr}{\tt]\char123}{\it
    width}{\tt\char125\char123}{\it height}{\tt\char125}] Output an
  \verb+hr+~element, this is, a horizontal rule.  Optional
  argument~\textit{attr} are attributes passed on directly
  (e.g. \verb+size=3 noshade+), while \textit{width} and
  \textit{height} are length arguments given in \LaTeX~style
  (e.g. \verb+2pt+ or~\verb+.5\linewidth+).

  Users can style the rules generated with \verb+\@hr+ by overriding
  class~\verb+horizontal-rule+.

\item[{\tt\char92 @print@u\char123}{\it n}{\tt\char125}] Output
  Unicode character~``\textit{n}'' which can be given either as a
  decimal number or as a hexadecimal number prefixed with
  ``\texttt{X}''.

\item[{\tt\char92 @open\char123}{\it block}{\tt\char125\char123}{\it
    attributes}{\tt\char125}] Open \html{} block-level element
  \textit{block} with attributes \textit{attributes}.  The block name
  \textit{block} \textbf{must} be lowercase.

  As a special case, \textit{block} may be the empty string, then an
  \html~\emph{group} is opened.  Argument~\textit{block} cannot be
  \verb+p+; use \verb+\@open@par+ to open a paragraph element.

\item[{\tt\char92 @close\char123}{\it block}{\tt\char125}] Close
  \html{} block-level element~\textit{block}.  Note that \verb+\@open+
  and \verb+\@close+ must be properly balanced.

\item[{\tt\char92 @open@par[}{\it attributes}{\tt ]}] Open a paragraph
  block element, which optionally gets attributes~\textit{attributes}.

\item[{\tt\char92 @close@par}] Close a paragraph block element.  Note
  that \verb+\@open@par+ and \verb+\@close@par+ also must be properly
  balanced.

\item[{\tt\char92 @out@par\char123}{\it arg}{\tt\char125}] If
  occurring inside a \verb+p+~element, that is, if a \verb+<p>+
  opening tag is active, \verb+\@out@par+ first closes it (by emitting
  \verb+</p>+), formats \textit{arg}, and then re-opens a \verb+p+
  element.  Otherwise, \verb+\@out@par+ simply formats \textit{arg}.
  This command is adequate when formatting \textit{arg} produces
  block-level elements.
\end{description}

\index{text-level elements}
Text-level elements are managed differently. They are not seen
as blocks that must be closed explicitly.
Instead they follow a ``declaration'' style, similar
to the one of \LaTeX{} ``text-style declarations'' --- namely,
\verb+\itshape+, \verb+\em+ etc.
Block-level elements (and \html{} groups)
delimit the effect of such declarations.
\begin{description}
\item[{{\tt\char92 @span\char123}{\it attr}{\tt\char125}}]
\index{text-level elements!span}
Declare the text-level element \verb+span+ (with given attributes)
as active.
The text-level element \verb+span+ will get opened as soon as
necessary and closed automatically, when the
enclosing block-level elements get closed.
Enclosed block-level elements are treated properly by closing \verb+span+
before them, and re-opening \verb+span+ (with given attributes)
inside them.
The following text-level constructs exhibit similar behaviour with respect
to block-level elements.

\item[{\tt\char92 @style\char123}{\it shape}{\tt\char125}] Declare the
text shape \textit{shape} (which must be lowercase) as active. Text
shapes are known as font style elements (\verb+i+, \verb+tt+, etc.;
\textbf{warning:} most of font style elements are depreciated in \html{}5,
and some of them are no longer valid, prefer CSS in \verb+span+ tags)
or phrase elements (\verb+em+, etc.) in the \html{} terminology.


\item[{\tt\char92 @styleattr\char123}{\it name}{\tt\char125\char123}{\it
attr}{\tt\char125}]
This command generalises both \verb+\@span+ and \verb+\@style+,
as both a text-level element name \textit{name} and attributes are specified.
More specifically, 
\verb+\@span{+\textit{attr}\verb+}+ can be seen as a shorthand for
\verb+\@styleattr{span}{+\textit{attr}\verb+}+;
while
\verb+\@style{+\textit{name}\verb+}+ can be seen as
a shorthand for
\verb+\@styleattr{+\textit{name}\verb+}{}+.

\item[{\tt\char92 @fontsize\char123}{\it int}{\tt\char125}] Declare
the text-level element \verb+span+ with attribute
\verb+style="font-size:+\textit{font-size}\verb+"+ as active.
The argument
\textit{int} must be a small integer in the range
\texttt{1},\texttt{2}, \ldots{} , \texttt{7}.
\texttt{hevea} computes \textit{font-size}, a CSS fontsize value,
 from \textit{int}.
More specifically, \textit{font-size} will
range from \verb+x-small+ to \verb+120%+ included in
a \verb+xx-large+, 3 being the  default size \verb+medium+.
Notice that \verb+\@fontsize+ is deprecated in favour of
\verb+\@span+ with proper fontsize declarations:
\verb+\@span{style="font-size=xx-small"}+,
\verb+\@span{style="font-size=x-small"}+,
\verb+\@span{style="font-size=small"}+,
etc.


\item[{\tt\char92 @fontcolor\char123}{\it color}{\tt\char125}]
Declare the text-level element \verb+span+ with attribute
\verb+"style=+\textit{color}\verb+"+ as active.
The argument \textit{color} must be a color attribute value in the \html{}
style. That is either one of the sixteen conventional colours
\verb+black+, \verb+silver+ etc, or a RGB hexadecimal color specification
of the form
\verb+#+\textit{XXXXXX}.
Note that the argument \textit{color} is processed, as a consequence
numerical color arguments should be given as \verb+\#+\textit{XXXXXX}.



\item[{\tt\char92 @nostyle}]
Close active text-level declarations and ignore further text-level
declarations.
The effect stops when the enclosing block-level element is closed.
\item[{\tt\char92 @clearstyle}]
Simply close active text-level declarations.
\end{description}

\subsubsection*{Notice on font styling with CSS}

The preferred way to style text in new versions of the \html{} ``standard''
is using style-sheet specifications. Those can be given as argument to
a ``\texttt{style}'' attributes of \html{} elements, most noticeably
of the \texttt{span} elements.
For instance, to get italics in old versions of \html{} one used
the text-level ``\texttt{i}'' element as in
\verb+<i>+\ldots\verb+</i>+. Now, for the same results of getting
 italics one may write:
\verb+<span style="font-style:italic">+\ldots\verb+</span>+.
An indeed \texttt{hevea} styles text in that manner,
starting from version~2.00.
Such (verbose) declarations are then abstracted into style class declarations
by \hevea{} optimiser \texttt{esponja}, which is invoked by \texttt{hevea}
when given option ``\texttt{-O}''.

Notice that style attributes can be given to elements other than \texttt{span}.
However, combining style attributes requires a little care as only one style
attribute is allowed.
Namely \verb+<cite style="font-weight:bold" style="color:red">+
is illegal and should be written 
\verb+<cite style="font-weight:bold;color:red">+.
\ifhevea
For instance:
{\@styleattr{cite}{style="font-weight:bold;color:red"}Das Kapital}.
\fi

\index{"@addstyle@\texttt{\char92"@addstyle}}
The command \verb+\@addtyle+ can be handy for adding style to
already styled elements:
\begin{description}
\item[{\tt\char92 @addstyle\char123}{\it name:val}{\tt\char125\char123}{\it attrs}{\tt\char125}]
Echo the space-separated attributes \textit{attrs} of a tag with the
\textit{name:val} style declaration added to these attributes. The
\verb+style+ attribute is added if necessary. Examples:
\verb+\@addstyle{color:red}{href="#"}+ will produce
\verb+href="#" style="color:red"+, and
\verb+\@addstyle{color:red}{href="#" style="font-style:italic"}+ will
produce \verb+href="#"  style="font-style:italic;color:red"+. Note
that an unnecessary extra space can be added in some cases.
\end{description}
As an example, consider the following definition of a command
for typesetting citation in bold, written directly in \html:
\begin{verbatim}
\newcommand{\styledcite}[2][]
{{\@styleattr{cite}{\@addstyle{#1}{style="font-weight:bold"}}#2}}
\end{verbatim}
The purpose of the optional argument is to add style to specific citations,
as in:
\begin{verbatim}
Two fundamental works: \styledcite{The Holy Bible} and
\styledcite[color:red]{Das Kapital}.
\end{verbatim}
\ifhevea We get: {\newcommand{\styledcite}[2][]
{{\@styleattr{cite}{\@addstyle{#1}{style="font-weight:bold"}}#2}}%
Two fundamental works: \styledcite{The Holy Bible} and
\styledcite[color:red]{Das Kapital}.}\fi

Notice that the example is  given for illustrating the usage of the
\verb+\@addstyle+ macros, which is intended for package writers.
A probably simpler way to proceed would be to use
\LaTeX{} text-style declarations:
\begin{verbatim}
\newcommand{styledcite}[2][]{{\@style{cite}#1\bf{}#2}}
Two fundamental works: \styledcite{The Holy Bible} and
\styledcite[\color{red}]{Das Kapital}.
\end{verbatim}
\ifhevea We get:{\newcommand{\styledcite}[2][]{{\@style{cite}#1\bf{}#2}}
Two fundamental works: \styledcite{The Holy Bible} and
\styledcite[\color{red}]{Das Kapital}.}\fi

\subsection{The \texttt{rawhtml}\label{rawhtml} environment}
\envindex{rawhtml}\comindex{rawhtmlinput}
Any text enclosed between \verb+\begin{rawhtml}+ and
\verb+\end{rawhtml}+ is echoed verbatim into the \html{} output file.
Similarly, \verb+\rawhtmlinput{+\textit{file}\verb+}+ echoes the
contents of file~\textit{file}.
In fact, \verb+rawhtml+ is the environment counterpart of the
\verb+\@print+ command, but experience showed it to be much more
error prone.

When \hevea{} was less sophisticated then it is now,
\texttt{rawhtml} was quite convenient.
But, as time went by,
numerous pitfalls around \texttt{rawhtml} showed up. Here are a few:
\begin{itemize}
\item
Verbatim means that no translation of any kind is performed. In
particular, be aware that input encoding (see~\ref{inputenc}) does
not apply. Hence one should use ascii only, if needed
non-ascii characters can be given as
entity or numerical character references --- \emph{e.g.}
\verb+&eacute;+ or \verb+&#XE9;+ for \'e.

\item
The \texttt{rawhtml}
environment should contain only \html~text that makes sense alone.
For instance, writing
\verb+\begin{rawhtml}<table>\end{rawhtml}+\ldots{}
\verb+\begin{rawhtml}</table>\end{rawhtml}+ is
dangerous, because \hevea{} is not informed about opening and closing
the block-level element \texttt{table}. In that case, one should use
the internal macros \verb+\@open+ and \verb+\@close+.

\item \verb+\begin{rawhtml}+\textit{text}\verb+\end{rawhtml}+ fragments that
contain block-level elements will almost certainly mix poorly with
\verb+p+ elements (introduced by paragraph breaks) and with active
style declaration (introduced by, for instance, \verb+\it+).
Safe usage will most of the time means using the internal macros
\verb+\@nostyle+ and \verb+\@out@par+.

\item When \hevea{} is given the command-line option \cmdopt{-O},
checking and optimisation 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,
but this is far from being certain.
\end{itemize}

As a conclusion, do not use the \texttt{rawhtml} environment!
A much safer option is to use the \texttt{htmlonly} environment
and to write \LaTeX{} code.
For instance, in place of writing:
\begin{verbatim}
\begin{rawhtml}
A list of links:
<ul>
<li><a href="http://www.apple.com/">Apple</a>.
<li><a href="http://www.sun.com/">Sun</a>.
</ul>
\end{rawhtml}
\end{verbatim}
One can write:
\begin{verbatim}
\begin{htmlonly}
A list of links:
\begin{itemize}
\item \ahref{http://www.apple.com/}{Apple}.
\item \ahref{http://www.sun.com/}{Sun}.
\end{itemize}
\end{htmlonly}
\end{verbatim}
\begin{htmlonly}
A list of links:
\begin{itemize}
\item \ahref{http://www.apple.com/}{Apple}.
\item \ahref{http://www.sun.com/}{Sun}.
\end{itemize}
\end{htmlonly}


\envindex{raw}\comindex{rawinput}
\envindex{rawtext}\comindex{rawtextinput}
If \hevea{} is targeted to text or info files (see
Section~\ref{alternative}).
The text inside \texttt{rawhtml} environments is ignored.
However there exists a \texttt{rawtext} environment (and a
\verb+\rawtextinput+ command) to echo text verbatim in text or info
output mode.
Additionally, the \texttt{raw} environment and a \verb+\rawinput+
command echo their contents verbatim, regardless of \hevea{} output
mode. Of course, when \hevea{} produces \html{},
the latter environment and command suffer from
the same drawbacks as \texttt{rawhtml}.

\subsection{Examples}
\comindex{purple}\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
defines the \verb+center+ environment:
\begin{verbatim}
\newenvironment{center}{\@open{div}{style="text-align:center"}}{\@close{div}}
\end{verbatim}
\comindex{setenvclass}\comindex{getenvclass}%
Notice that the code above is no longer present and is given here
for explanatory purpose only.
Now \hevea{} uses style-sheets and the actual definition of the
\verb+center+ environment is as follows:
\begin{verbatim}
\newstyle{.center}{text-align:center;margin-left:auto;margin-right:auto;}%
\setenvclass{center}{center}%
\newenvironment{center}
  {\@open{div}{\@getprint{class="\getenvclass{center}"}}
  {\@close{div}}%
\end{verbatim}
Basically environments \verb+\begin{center}+\ldots\verb+\end{center}+ will, by
default, be translated into blocks
\verb+<div class="center">+\ldots\verb+</div>+.
Additionally, the style class associated to \verb+center+ environments
is managed through an indirection, using the
commands \verb+\setenvclass+ and \verb+\getenvclass+.
See section~\ref{css:change} for more explanations.

Another example is the definition of the \verb+\purple+
color declaration (see section~\ref{color:high}):
\begin{verbatim}
\newcommand{\purple}{\@fontcolor{purple}}
\end{verbatim}

\hevea{} does not feature all text-level elements by default.
However one can easily use them with internal macros.
For instance this is how you can make all emphasised text blink:
\begin{verbatim}
\renewcommand{\em}{\@styleattr{em}{style="text-decoration:blink"}}
\end{verbatim}
\begin{htmlonly}
Here is an example of this questionable blinking feature:
\begin{center}
{\@styleattr{em}{style="text-decoration:blink"}Hello!}
\end{center}
\end{htmlonly}
\comindex{imgsrc}

\index{"@print@\texttt{\char92"@print}}
\index{"@getprint@\texttt{\char92"@getprint}}
\index{"@nostyle@\texttt{\char92"@nostyle}}
Then, here is the definition of a simplified \verb+\imgsrc+
command (see section~\ref{hyperlink}), without its optional argument:
\begin{verbatim}
\newcommand{\imgsrc}[1]
  {\@print{<img src="}\@getprint{#1}\@print{">}}
\end{verbatim}
Here, \verb+\@print+ and \verb+\@getprint+ are used to output
\html~text, depending upon whether this text requires processing or not.
Note that \verb+\@open{img}{src="#1"}+ is not correct,
because the element \verb+img+ consists in a single tag, without a
closing tag.

\index{"@nostyle@\texttt{\char92"@nostyle}}
Another interesting example is the definition of the command
\verb+\@doaelement+,
which \hevea{} uses internally to output \texttt{A} elements.
\begin{verbatim}
\newcommand{\@doaelement}[2]
  {{\@nostyle\@print{<a }\@getprint{#1}\@print{>}}{#2}{\@nostyle\@print{</a>}}
\end{verbatim}
The command \verb+\@doaelement+ takes two arguments: the first
argument contains the opening tag attributes; while the second element is
the textual content of the \verb+A+ element.
By contrast with the \verb+\imgsrc+ example above,
tags are emitted inside groups where styles are cancelled by using the
\verb+\@nostyle+ declaration.
Such a complication is needed, so as to avoid breaking proper nesting
of text-level elements.

\label{getcolor:usage}
\envindex{bgcolor}
\index{"@open@\texttt{\char92"@open}}
\index{"@close@\texttt{\char92"@close}}
Here is another example of direct block opening.
The \texttt{bgcolor} environment from the \texttt{color} package
locally changes background color (see section~\ref{bgcolor}).
This environment is defined as follows:
\begin{verbatim}
\newenvironment{bgcolor}[2][style="padding:1em"]
{\@open{table}{}\@open{tr}{}%
\@open{td}{\@addstyle{background-color:\@getcolor{#2}}{#1}}}
{\@close{td}\@close{tr}\@close{table}}
\end{verbatim}
The \texttt{bgcolor} environment operates by opening a \html{} table
(\verb+table+) with only one row (\verb+tr+) and cell (\verb+td+) in
its opening command, and closing all these elements in its closing
command. In my opinion, such a style of opening block-level elements
in environment opening commands and closing them in environment
closing commands is good style.
\index{"@getcolor@\texttt{\char92"@getcolor}}%
The one cell background color is forced with a \verb+background-color+
property in a \verb+style+ attribute.
Note that the mandatory argument to \verb+\begin{bgcolor}+ is the
background color expressed as a high-level color, which therefore
needs to be translated into a low-level color by using the
\verb+\@getcolor+ internal macro from the \texttt{color} package.
Additionally,  \verb+\begin{bgcolor}+ takes \html{} attributes
as an optional argument. These attributes are the ones of the
\verb+table+ element.

\index{"@print"@u@\texttt{\char92"@print"@u}}%
If you wish to output a given Unicode character whose value you know,
the recommended technique is to define an ad-hoc command
that simply call the \verb+\@print@u+ command.
For instance, ``blackboard sigma'' is Unicode \texttt{U+02140} (hexa).
Hence you can define the command \verb+\bbsigma+ as follows:
\begin{verbatim}
\newcommand{\bbsigma}{\@print@u{X2140}}
\end{verbatim}
\ifhevea Then, ``\verb+\bbsigma+'' will output ``\@print@u{X2140}''\fi


\subsection{The \label{encodings}document charset}
According to standards, as far as I understand them, \html{} pages are
made of Unicode (ISO~10646) characters.
By contrast, a file in any operating system is usually considered as
being made of bytes.

\index{"@print"@u@\texttt{\char92"@print"@u}}%
To account for that fact, \html{} pages usually specify a \emph{document
charset} that defines a translation from a flow of bytes to a flow of
characters.
For instance, the byte
\texttt{0xA4} means Unicode~\texttt{0x00A4} (\textcurrency) in the
ISO-8859-1 (or latin1) encoding, and \texttt{0x20AC} (\texteuro) in
the ISO-8859-15 (or latin9) encoding.
Notice that \hevea{} has no difficulty to output both symbols, in fact
they are defined as Unicode characters:
\begin{verbatim}
\newcommand{\textcurrency}{\@print@u{XA4}}
\newcommand{\texteuro}{\@print@u{X20AC}}
\end{verbatim}
But the \verb+\@print@u+ command may output the specified character as
a byte, when possible, by the means of the \emph{output translator}.
If not possible, \verb+\@print@u+ outputs a numerical character
references (for instance \verb+&#X20AC;+).

\index{"@def"@charset@\texttt{\char92"@def"@charset}|defocc}%
Of course, the document charset and the output translator
must be synchronised. The command \verb+\@def@charset+ takes a
charset name as argument and performs the operation of specifying the
document character set and the output translator. It should occur in
the document preamble.
Valid  charset names are \texttt{ISO-8859-}\textit{n} where \textit{n} is a
number in \texttt{1}\ldots\texttt{15},
\texttt{KOI8-R}, \texttt{US-ASCII} (the
default),
\texttt{windows-}\textit{n} where \textit{n} is
\texttt{1250}, \texttt{1251}, \texttt{1252} or~\texttt{1257},
or \texttt{macintosh}, or \texttt{UTF-8}.
In case those charsets do not suffice, you may ask the author for
other document charsets.  Notice however that document charset is not
that important, the default \texttt{US-ASCII} works everywhere!
\emph{Input} encoding of source files is another, although
related, issue --- see Section~\ref{inputenc}.

\ttindex{xxcharset.exe}{script}%
If wished so, the charset can be extracted from the current
locale environment, provided this yields a valid (to \hevea) charset name.
This operation is performed by a companion script: \texttt{xxcharset.exe}.
It thus suffices to launch \hevea{} as:
\begin{flushleft}
\texttt{\# hevea -exec xxcharset.exe}~\textit{other arguments} 
\end{flushleft}

\iffalse
\index{"@charset\texttt{\char92"charset}}%
\index{"@set"@out"@translator@\texttt{\char92"@set"@out"@translator}}%
\hevea{} mechanism for charsets can be extended to other
8~bits encodings. To provide support for encoding \textit{encoding}:
\begin{itemize}
\item Be sure that \textit{encoding} is a valid (to \html) encoding
name.
\item Create a file \textit{encoding}\texttt{.map}, that contains
the definition of the encoding --- see Section~\ref{newmap} for details.
\item Issue the following commands:
\begin{flushleft}
\verb+\def\@charset{+\textit{encoding}\verb+}+\\
\verb+\@set@out@translator{+\textit{encoding}\verb+}+
\end{flushleft}
\item Send me \textit{encoding}\texttt{.map} file.
I will include it in the \texttt{mappings} directory.
As a result, \verb+\@def@charset{+\texttt{encoding}\verb+}+ will work.
\end{itemize}
\fi

\section{Support\label{style:sheets}\index{style-sheets} for style sheets}

\subsection{Overview}
Starting with version~1.08, \hevea{} offers support for style sheets
(of the CSS variant see~\cite{css}).

Style sheets provide enhanced expressiveness. For instance, it is now possible
to get ``real'' (whatever real means here) small caps in {\html}, and in a
relatively standard manner. There are other, discrete, maybe
unnoticeable, similar enhancements.

However, style sheets mostly offer an additional mechanism to
customise their documents to \hevea{} users. To do so, users should
probably get familiar with how \hevea{} uses style sheets in the first
place.

\hevea{} interest for style sheets is at the moment confined to
block-level elements (\verb+div+, \verb+table+, \verb+H<+\textit{n}\verb+>+,
etc.).
The general principle is as follows: when a command or an
environment gets translated into a block-level element,
the opening tag of the block level element has a
\texttt{class="\textit{name}"} attribute, where \textit{name} is the
command or environment name.

As an example the \LaTeX{} command \verb+\subsection+
 is implemented with the element~\verb+h3+, resulting in
\html{} output of the form:
\begin{verbatim}
    <h3 class="subsection">
    ...
    </h3>
\end{verbatim}
By default, most styles are undefined, and default rendering of
block-level elements applies. However, some packages (such as, for
instance~\texttt{fancysection}, see Section~\ref{fancysection}) may
define them.
\comdefindex{newstyle}\index{style-sheets!\verb+\newstyle+}%
If you wish to change the style of section headers, loading the
\texttt{fancysection} package may prove appropriate (see~\ref{fancysection}).
However, one can also proceed more directly, by appending new
definitions to the \emph{document style
sheet}, with the command \verb+\newstyle+.
For instance, here is a \verb+\newstyle+ to add style for subsections.
\begin{alltt}
  \char92newstyle\{.subsection\}\{\stylex\}
\end{alltt}
This declaration adds some style element to the
\texttt{subsection} class (notice the dot!):
blocks that declare to belong to the class
will show dark-blue text, some padding
(space inside the box) is added and a border will be drawn around the block.
These specification will normally affect all subsections in the document.
\begin{htmlonly}
Given the previous style definition, the sectioning command
\begin{verbatim}
\subsection*{A styled subsection heading}
\end{verbatim}
should yield:
\@open{h3}{class="subsectionex"}
A styled subsection heading
\@close{h3}
\end{htmlonly}

The following points are worth noticing:
\begin{itemize}
\item
To yield some effect, \verb+\newstyle+~commands \emph{must} appear
in the document preamble, \emph{i.e.}\ before \verb+\begin{document}+.
\item
Arguments to \verb+\newstyle+~commands are processed.
\item The \texttt{hevea} package defines all style~sheet related
commands as no-ops. Thus, these commands do not affect
document processing by \LaTeX{}.
\end{itemize}



\subsection{Changing \label{css:change:all}
the style of all instances of an environment}

In this very document, all \texttt{verbatim} environments appear over
a light green background, with small left and right margins.
This has been performed by simply issuing the following command in
the document preamble.
\begin{verbatim}
\newstyle{.verbatim}{margin:1ex 1ex;padding:1ex;background:\#ccffcc;}
\end{verbatim}
Observe that, in the explicit numerical color argument above, the
hash character ``\texttt{\#}'' has to be escaped.

\subsection{Changing \label{css:change}the style of some instances of an environment}\
\comdefindex{setenvclass}\comdefindex{getenvclass}%
One can also change the style class  attached to a given instance of
an environment and thus control styling of environments more precisely.

As a matter of fact, the name of the class attribute of
environment~\textit{env} is referred to through an indirection, by
using the command \verb+\getenvclass{+\textit{env}\verb+}+.
The class attribute can be changed with the command
\verb+\setenvclass{+\textit{env}\verb+}{+\textit{class}\verb+}+.
The~\verb+\setenvclass+ command internally defines a command
\verb+\+\textit{env}\verb+@class+, whose content is read
by the \verb+\getenvclass+ command. As a consequence, the class
attribute of environments follows normal scoping rules.
\label{getstylecolor:example}
For instance, here is how to change the style of \emph{one} \texttt{verbatim}
environment.
\bgroup\setenvclass{verbatim}{myverbatim}
\verbatiminput{verbinverb.txt}
\egroup
Observe how the class of environment \texttt{verbatim} is changed from
its default value to the
new value \texttt{myverbatim}. The change remains active until the
end of the current group (here, the ``\texttt{\}}'' at the end). Then, the class
of environment \texttt{verbatim} is restored to its default value
--- which happen to be \texttt{verbatim}.

\index{"@getstylecolor@\texttt{\char92"@getstylecolor}}
This example also shows two new ways to specify colours in style
definition, with a
conventional \html~color name (here {\ifhevea\maroon\fi maroon}) or as
a high-level color (see Section~\ref{color:package}), given as an argument to
the \verb+\@getstylecolor+ internal command
(here \colorbox{abricot}{\texttt{Apricot}} from the \texttt{named} color model).

A good way of specifying style class changes probably is by defining
new environments.
\begin{verbatim}
\newenvironment{flashyverbatim}
  {\setenvclass{verbatim}{myverbatim}\verbatim}
  {\endverbatim}
\end{verbatim}
\newenvironment{flashyverbatim}
  {\setenvclass{verbatim}{myverbatim}\verbatim}
  {\endverbatim}%
Then, we can use \verb+\begin{flashyverbatim}+\ldots{}
\verb+\end{flashyverbatim}+ to get verbatim environments style with
the intended \texttt{myverbatim} style class.
\begin{htmlonly}\begin{flashyverbatim}
This text is typeset inside the environment
\emph{flashyverbatim}, and hence with the \emph{myverbatim}
style.
\end{flashyverbatim}
\end{htmlonly}

\subsection{Which class affects\label{whatclass} what}

Generally, the styling of environment~\textit{env} is performed through
the commands
\verb+\getenvclass{+\textit{env}\verb+}+
and \verb+\setenvclass{+\textit{env}\verb+}{+\ldots\verb+}+,
with \verb+\getenvclass{+\textit{env}\verb+}+ producing the
default value of \textit{env}.

Concretely, this means that most of the environments are styled through
an homonymous style class. Here is a non-exhaustive list of such
environments
\begin{quote}
figure, table, itemize, enumerate, list, description, 
trivlist, center, flushleft, flushright, quote,
quotation, verbatim, abstract, mathpar (cf
Section~\ref{mathpartir:package}), lstlisting
(cf. Section~\ref{listings:package}), etc.
\end{quote}

All sectioning commands (\verb+\part+, \verb+\section+ etc.)
output~\verb+H<+\textit{n}\verb+>+ block-level  elements, which are styled
through style classes named \texttt{part}, \texttt{section}, etc.

List making-environment introduce extra style classes for items.
More specifically, for list-making environments
\texttt{itemize} and \texttt{enumerate},
\verb+li+ elements are styled as follows:
\begin{center}
\begin{tabular}{p{.4\linewidth}p{\linewidth}}
\begin{verbatim}
<ul class="itemize">
<li class="li-itemize"> ...
</ul>
\end{verbatim}
&
\begin{verbatim}
<ol class="enumerate">
<li class="li-enumerate"> ...
</ol>
\end{verbatim}
\end{tabular}
\end{center}
That is, \verb+li+ elements are styled as environments, the key name
being \texttt{li-}\textit{env}.

The \texttt{description}, \texttt{trivlist} and \texttt{list} environments
(which all get translated into \texttt{DL} elements) are styled in
a similar way, internal \texttt{DT} and \texttt{DD} elements being
styles through names \texttt{dt-}\textit{env} and
\texttt{dd-}\textit{env} respectively.

\subsection{A few examples}
\subsubsection{The title of the document}\index{styles for!title}
The command \verb+\maketitle+ formats the document
title within a \verb+table+ element, with
class \texttt{title}, for display. The name of the title is displayed
inside block \verb+h1+, with class \texttt{titlemain}, while all other
information (author, date) are displayed inside block \verb+h3+, with class
\texttt{titlerest}.
\begin{verbatim}
<table class="title">
 <tr>
  <td style="padding:1ex">
   <h1 class="titlemain">..title here..</h1>
   <h3 class="titlerest">..author here..</h3>
   <h3 class="titlerest">..date here..</h3>
  </td>
 </tr>
</table>
\end{verbatim}
Users can impact  on title formatting by adding style in the
appropriate style classes.
For instance the following style class definitions:
\begin{verbatim}
\newstyle{.title}
  {text-align:center;margin:1ex auto;color:navy;border:solid navy;}
\newstyle{.titlerest}{font-variant:small-caps;}
\end{verbatim}
will normally produce a title in dark blue, centered in a box, with
author and date in small-caps.
\begin{htmlonly}
\@open{table}{class="xtitle"}\@open{tr}{}\@open{td}{style="padding:1ex;"}
\@open{h1}{class="xtitlemain"}Title\@close{h1}
\@open{h3}{class="xtitlerest"}Date\@close{h3}
\@open{h3}{class="xtitlerest"}Author\@close{h3}
\@close{td}\@close{tr}\@close{table}
\end{htmlonly}

\subsubsection{Enclosing things in a styled \texttt{div}}
\index{styles for!miscellaneous objects}%
\index{style-sheets!\verb+\divstyle+}\envdefindex{divstyle}%
At the moment, due to the complexity of the task, environments
\texttt{tabular} and \texttt{array} cannot be styled as others
environments can be, 
by defining an appropriate class in the preamble.
However, even for such constructs,
limited styling can be performed, by using
the \texttt{divstyle} environment.
The opening command \verb+\begin{divstyle}{+\textit{class}\verb+}+
takes the name of a class as
an argument, and translates to \verb+<div class="+\textit{class}\verb+">+.
Of course the closing command \verb+\end{divstyle}+ translates to
\verb+</div>+.
The limitation is that the enclosed part may generate more {\html}
blocks, and that not all style attribute defined in class class
\textit{class} will apply to those inner blocks.

As an example consider the style class definition below.
\begin{verbatim}
\newstyle{.ruled}{border:solid black;padding:1ex;background:\#eeddbb;color:maroon}
\end{verbatim}
The intended behaviour is to add a black border around the inner block
(with some padding), and to have {\ifhevea\maroon maroon\else\fi} text over
a light brown background.

If we, for instance, enclose an \texttt{itemize} environment, the
resulting effect is more or less what we have expected:
\begin{verbatim}
\begin{divstyle}{ruled}
\begin{itemize}
\item A ruled itemize
\item With two items.
\end{itemize}
\end{divstyle}
\end{verbatim}
\begin{htmlonly}
\begin{divstyle}{ruled}
\begin{itemize}
\item A ruled itemize
\item With two items.
\end{itemize}
\end{divstyle}
\end{htmlonly}

However, enclosing a centered
\texttt{tabular} environment in a \texttt{divstyle\{ruled\}} one 
is less satisfactory.
\begin{verbatim}
\begin{divstyle}{ruled}
\begin{center}\begin{tabular}{|c|c|}
\hline \bf English & \bf French\\ \hline
Good Morning & Bonjour\\ Thank You & Merci\\ Good Bye & Au Revoir\\ \hline
\end{tabular}\end{center}
\end{divstyle}
\end{verbatim}
\begin{htmlonly}
\begin{divstyle}{ruled}
\begin{center}\begin{tabular}{|c|c|}
\hline \bf English & \bf French\\ \hline
Good Morning & Bonjour\\ Thank You & Merci\\ Good Bye & Au Revoir\\
\hline
\end{tabular}\end{center}
\end{divstyle}
\end{htmlonly}
In the \html{} version of this document,
one sees that the brown background extend on all the width
of the displayed page.

This problem can be solved by introducing an extra table.
We first open an extra centered table and then only open the
\texttt{divstyle} environment.
\begin{verbatim}
\begin{center}\begin{tabular}{c}
\begin{divstyle}{ruled}
\begin{tabular}{|c|c|}
\hline \bf English & \bf French\\ \hline
Good Morning & Bonjour\\ Thank You & Merci\\ Good Bye & Au Revoir\\
\hline
\end{tabular}
\end{divstyle}
\end{tabular}\end{center}
\end{verbatim}
This works because of the rules that
govern the width of {\html} \verb+table+ elements, which yield
minimal width. This trick is used in
numerous places by \hevea{}, for instance in document titles, and looks
quite safe.
\begin{htmlonly}
\begin{center}\begin{tabular}{c}
\begin{divstyle}{ruled}
\begin{tabular}{|c|c|}
\hline \bf English & \bf French\\ \hline
Good Morning & Bonjour\\ Thank You & Merci\\ Good Bye & Au Revoir\\
\hline
\end{tabular}
\end{divstyle}
\end{tabular}\end{center}
\end{htmlonly}

Another solution is to specify the \texttt{display} property
of the styling \texttt{div} block as being \texttt{inline-block}:
\begin{verbatim}
\newstyle{.ruledbis}
  {border:solid black;padding:1ex;background:\#eeddbb;color:maroon;display:inline-block;}
\end{verbatim}
\begin{htmlonly}
\begin{center}
\begin{divstyle}{ruledbis}
\begin{tabular}{|c|c|}
\hline \bf English & \bf French\\ \hline
Good Morning & Bonjour\\ Thank You & Merci\\ Good Bye & Au Revoir\\
\hline
\end{tabular}
\end{divstyle}
\end{center}
\end{htmlonly}

\subsubsection{Styling the \texttt{itemize} environment}
\index{styles for!lists}
\newcounter{toc}
\newenvironment{toc}
{\stepcounter{toc}\setenvclass{itemize}{toc\thetoc}\begin{itemize}}
{\addtocounter{toc}{-1}\end{itemize}}
Our idea is highlight lists with a left border whose color fades
while lists are nested.
Such a design may be appropriate for tables of content, as 
the \ahrefloc{ftoc}{one of this document}.
\begin{htmlonly}
\begin{toc}
\item Part~A
\begin{toc}
\item Chapter~I
\begin{toc}
\item Section~I.1
\item Section~I.2
\end{toc}
\item Chapter~II
\begin{toc}
\item Section~II.1
\item Section~II.2
\end{toc}
\item Chapter~III
\end{toc}
\item Part~B
\begin{toc}
\item Chapter~IV
\begin{toc}
\item Section~IV.1
\begin{toc}
\item Section~IV.1.a
\item Section~IV.1.b
\end{toc}
\item Section~IV.2
\end{toc}
\item Chapter~V
\end{toc}
\end{toc}
\end{htmlonly}
The text above is typeset from the following \LaTeX{} source.
\begin{verbatim}
\begin{toc}
\item Part~A
\begin{toc}
\item Chapter~I
\begin{toc}
\item Section~I.1
\item Section~I.2
\end{toc}
  ...
\end{toc}
\end{toc}
\end{verbatim}
For simplicity, we assume a limit of four over the nesting depth of
\texttt{toc} environment.
We first define four style classes \texttt{toc1}, \texttt{toc2},
\texttt{toc3} and \texttt{toc4} in the document preamble.
Since those classes are similar, a command \verb+\newtocstyle+ is
designed.
\begin{verbatim}
\newcommand{\newtocstyle}[2]
{\newstyle{.toc#1}{list-style:none;border-left:1ex solid #2;padding:0ex 1ex;}}
\newtocstyle{1}{\@getstylecolor{Sepia}}
\newtocstyle{2}{\@getstylecolor{Brown}}
\newtocstyle{3}{\@getstylecolor{Tan}}
\newtocstyle{4}{\@getstylecolor{Melon}}
\end{verbatim}
The \texttt{toc} environment uses a counter to record nesting depth.
Notice how the style class of the \texttt{itemize} environment is
redefined before \verb+\begin{itemize}+.
\begin{verbatim}
\newcounter{toc}
\newenvironment{toc}
{\stepcounter{toc}\setenvclass{itemize}{toc\thetoc}\begin{itemize}}
{\addtocounter{toc}{-1}\end{itemize}}
\end{verbatim}
The outputted {\html} is:
\begin{verbatim}
<ul class="toc1"><li class="li-itemize">
Part&nbsp;A
<ul class="toc2"><li class="li-itemize">
Chapter&nbsp;I
<ul class="toc3"><li class="li-itemize">
Section&nbsp;I.1
<li class="li-itemize">Section&nbsp;I.2
  ...
</ul>
</ul>
\end{verbatim}

\subsection{Miscellaneous}
\ifpdf
\subsubsection{Hacha and style sheets}
\else
\subsubsection{\hacha{} and style sheets}
\fi
\hacha{} now produces an additional file: a style sheet, which is
shared by all the~{\html} files produced by \hacha.
Please refer to section~\ref{hacha:style} for details.

\subsubsection{Producing an external style sheet}
\index{externalcss@\texttt{externalcss} (boolean register)|defocc}%
\comdefindex{externalcsstrue}%
By default,  style declarations defined with
\verb+\newstyle+ go into the header of the \html{} document
\filename{doc}\texttt{.html}.
However, one can send those declaration into an external style file,
whose name is \filename{doc}\texttt{.css}.
Then, \hevea{} automatically relates \filename{doc}\texttt{.html} to
its style sheet  \filename{doc}\texttt{.css}.
To achieve this behaviour, it suffices to set the value of the boolean
register \texttt{externalcss} to \textit{true}, by issuing the command
\verb+\externalcsstrue+ in the preamble of the source document.
Notice that \hevea{} output still can be processed by \hacha{}, with
correct behaviour.


\subsubsection{Linking to external style sheets}
\comdefindex{loadcssfile}%
\index{style-sheets!\verb+\loadcssfile+}%
The \hevea{} command \verb+\loadcssfile{+\textit{url}\verb+}+ allows the
user to link to an external style sheet (like the link option for
HTML). The command takes an \textit{url} of the external
sheet as argument and emits the HTML text to
\emph{link} to the given external style sheet. As an example, the command
\begin{verbatim}
\loadcssfile{../abc.css}
\end{verbatim}
produces the following \html{} text in the \verb+head+ of the document.
\begin{verbatim}
  <link rel="stylesheet" type="text/css" href="../abc.css">
\end{verbatim} 
To yield some effect, \verb+\loadcssfile+ must appear in the document
preamble.  Several \verb+\loadcssfile+ commands can be issued.  Then
the given external style sheets appear in the output, following source
order.

Notice that the argument to \verb+\loadcssfile+ is processed. Thus, if it
contains special characters such as ``\#'' or ``\$'', those must be specified
as \verb+\#+ and \verb+\$+ respectively.
A viable alternative would be to quote
the argument using the \verb+\url+ command from the \texttt{url}
package (see Section~\ref{urlpackage}).

\subsubsection{Limitations}
At the moment, style class definitions cumulate, and appear
in the \verb+style+ element in the order they are given in the
document source. There is no way to cancel the default class
definitions performed by \hevea{} before it starts to process the
user's document.
Additionally, external style sheets specified with \verb+\loadcssfile+
appear before style classes defined with \verb+\newstyle+.
As a consequence (if I am right), styles
declared by \verb+\newstyle+ take precedence over those contained in
external style sheets. Thus, using external style-sheets, especially
if they alter the styling of elements, may produce awkward results.

Those limitations do not apply of course to style classes whose
names are new, since there cannot be default definitions for them.
Then, linking with external style sheets can prove useful to
promote uniform styling of several documents produced by \hevea{}.


\section{Customising \hevea}
\hevea{} can be controlled by writing \LaTeX{} code. In this section,
we examine how users can change \hevea{} default behaviour or add
functionalities. In all this section we assume that a document
\texttt{doc.tex} is processed, using a private command file
\texttt{macros.hva}. That is, \hevea{} is invoked as:
\begin{verbatim}
# hevea macros.hva doc.tex
\end{verbatim}
The general idea is as follows: one redefines \LaTeX{} constructs in
\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
emphasised. Then, it suffices to put the following re-declaration in
\texttt{macros.hva}:
\begin{verbatim}
\renewenvironment{quote}
  {\@open{blockquote}{}\@style{em}}
  {\@close{blockquote}}
\end{verbatim}

The same effect can be achieved without using any of the internal
commands:
\begin{verbatim}
\let\oldquote\quote
\let\oldendquote\endquote
\renewenvironment{quote}{\oldquote\em}{\oldendquote}
\end{verbatim}
In some sense, this second 
solution is easier, when one already knows
how to customise \LaTeX{}. However, this is less safe, since the definition of
\verb+\em+ can be changed elsewhere.

There is yet another solution that takes advantage of style sheets.
One can also add this line to the \texttt{macros.hva} file:
\begin{verbatim}
\newstyle{.quote}{font-style:oblique;}
\end{verbatim}
This works because the environment \texttt{quote} is styled through
style class \texttt{quote} (see Section~\ref{css:change:all}).
Notice that this solution has very little to do with
``\emph{emphasising}'' in the proper sense, since here we
short-circuit the implicit path from \verb+\em+ to oblique fonts.


\subsection{Changing defaults for type-styles}\label{customize-style}
\hevea{} default rendering of type style changes is described in
section~\ref{type-style}.
For instance, the following example shows the default rendering
for the font shapes:
\begin{verbatim}
\itshape italic shape \slshape slanted shape
\scshape small caps shape \upshape upright shape
\end{verbatim}
By default, \verb+\itshape+ is italics, \verb+\slshape+ is oblique
italics, \verb+\scshape+ is small-caps (thanks to style sheets) 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 small caps (no italics here).
\begin{htmlonly}
\begin{htmlout}
\itshape italic shape \slshape slanted shape
\scshape small caps shape \upshape upright shape
\end{htmlout}
\end{htmlonly}

If one wishes to change the rendering of some of the shapes (say slanted
caps), then one should redefine the old-style \verb+\sl+ declaration.
For instance, to render slanted as Helvetica (why so?), one should
redefine \verb+\sl+ by \verb+\renewcommand{\sl}{\@span{style="font-family:Helvetica"}}+ in
\texttt{macros.hva}.


\begin{htmlonly}
And now, the shape example above gets rendered as follows:
\begin{htmlout}\renewcommand{\sl}{\@span{style="font-family:Helvetica"}}
{\itshape italic shape \slshape slanted shape
\scshape small caps shape \upshape upright shape}
\end{htmlout}

Redefining the old-style \verb+\sl+ is compatible with the cancellation
mechanism, redefining \verb+\slshape+ is not.
Thus, redefining directly \LaTeXe{} \verb+\slshape+ with
\verb+\renewcommand{\slshape}{}+ would yield:
\begin{htmlout}\renewcommand{\slshape}{\@span{style="font-family:Helvetica"}}
{\itshape italic shape \slshape slanted shape
\scshape small caps shape \upshape upright shape}
\end{htmlout}
\end{htmlonly}

Hence, redefining old-style declarations using internal commands
should yield satisfactory output.
However, since cancellation 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{doc.tex} is
\textit{jsc} (the
\emph{Journal of Symbolic Computation} style for articles).
For running \hevea{}, the \textit{jsc} style can be replaced by
\textit{article}
style, but for a few commands whose calling interface is changed.
In particular, the \verb+\title+ command
takes an extra optional argument (which \hevea{} should ignore
anyway).
However, \hevea{} can process the document as it stands.
One  solution to insert the following lines into \texttt{macros.hva}:
\begin{verbatim}
\input{article.hva}% Force document class 'article'
\let\oldtitle=\title
\renewcommand{\title}[2][]{\oldtitle{#2}}
\end{verbatim}
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}
\index{image inclusion!in Postscript}
\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{verbatim}
\newcommand{\epsfbox}[2][!*!]{%
\ifthenelse{\equal{#1}{!*!}}
{\begin{toimage}\epsfbox{#2}\end{toimage}}%No optional argument
{\begin{toimage}\epsfbox[#1]{#2}\end{toimage}}}%With optional argument
\imageflush}
\end{verbatim}

\subsection{Changing the format of images}
\index{image inclusion!output format}
\index{PNG}\index{GIF}\index{SVG}
\comindex{imageflush}
\comindex{imgsrc}
Semi-automatic generation of included images is described in
section~\ref{imagen}.
Links to included images are generated by the \verb+\imageflush+
command, which calls the \verb+\imgsrc+ command:
\begin{verbatim}
\newcommand{\imageflush}[1][]
{\@imageflush\stepcounter{image}\imgsrc[#1]{\hevaimagedir\jobname\theimage\heveaimageext}}
\end{verbatim}
That is, you may supply a \html-style attribute to the included image,
as an optional argument to the \verb+\imageflush+ command.

By default, images are PNG images stored in \texttt{.png} files.
\hevea{} provides support for the alternative GIF image file format.
It suffices to invoke \texttt{hevea} as:
\begin{flushleft}
\texttt{\#~hevea~gif.hva}~\textit{doc.tex}
\end{flushleft}
Then \texttt{imagen} must be run with option \cmdopt[imagen]{-gif}:
\begin{flushleft}
\texttt{\#~imagen~-gif}~\filename{doc}
\end{flushleft}

A convenient alternative is to invoke \texttt{hevea} as:
\begin{flushleft}
\texttt{\#~hevea~-fix~gif.hva}~\textit{doc.tex}
\end{flushleft}
Then \texttt{hevea} will invoke \texttt{imagen} with the appropriate
option when it thinks images need to be rebuild.
An even more convenient alternative is to load \texttt{gif.hva}
from within document source, for instance with the \verb+\usepackage+
command.

\hevea{} also  provides support for the alternative SVG image file format.
As for GIF images, it is more convenient to use option \texttt{-fix}
to combine \texttt{hevea} and \texttt{imagen} invocations:
\begin{flushleft}
\texttt{\#~hevea~-fix~svg.hva}~\textit{doc.tex}
\end{flushleft}
Notice that \texttt{imagen} production chain of SVG images always
call \texttt{pdflatex}, even when \emph{not} given
the \ahrefloc{imagenoptions}{\texttt{-pdf} command-line option}.
Hence the source code of images must be processable
by \texttt{pdflatex}. This precludes using \texttt{latex}-only packages
such as pstricks for instance.

As not all browsers display SVG images, \texttt{hevea} and
\texttt{imagen} are  bit special:
\texttt{imagen} produces both PNG\footnote{or GIF, if \texttt{gif.hva} is loaded} and SVG~images; while \texttt{hevea} offers both image sources,
letting client browser select the most appropriate one by the means of
the \verb+srcset+ attribute of the \verb+img+ element.

\subsection{Storing images in a separate directory} 
\comindex{heveaimagedir}
By redefining the \verb+\heveaimagedir+ command, users can specify a
directory for images.
More precisely, if the following redefinition occurs in the document
preamble.
\begin{flushleft}
\verb+\renewcommand{\heveaimagedir}{+\textit{dir}\verb+}+
\end{flushleft}
Then, all links to images in the produced \html{} file will be as
``\textit{dir}/\ldots''.
Then \texttt{imagen} must be invoked with option~\cmdopt[imagen]{-
todir}:
\begin{flushleft}
\texttt{\#~imagen~-todir}~\textit{dir}~\filename{doc}
\end{flushleft}
As usual, \texttt{hevea} will invoke \texttt{imagen} with the
appropriate option, provided it is passed the \texttt{-fix} option.


\subsection{Controlling\label{imagen-source} \texttt{imagen} from document source}
\index{"@addimagenopt@\texttt{\char92"@addimagenopt}|defocc}
The internal command
\verb+\@addimagenopt{+\textit{option}\verb+}+ add
the text \textit{option} to \texttt{imagen} command-line options, when
launched automatically by \texttt{hevea} (\emph{i.e.}\ when
\texttt{hevea} is given the \cmdopt{-fix} command-line option).

For instance, to instruct \texttt{hevea}/\texttt{imagen} to
reduce all images by a factor of $\sqrt{2}$, it suffices to state:
\begin{flushleft}
\texttt{\%HEVEA}\verb+\@addimagenopt{-mag 707}+
\end{flushleft}
See section~\ref{imagenusage} for the list of command-line options
accepted by \texttt{imagen}.

\section{Other \label{alternative}output formats}
It is possible to translate \LaTeX{} file into other formats than
\html. There are two such formats: plain text and info files.
This enables producing postscript,
\html, plain text and info manuals from one (\LaTeX) input file.

\subsection{Text}
The \LaTeX{} file is processed and converted into a plain text
formatted file. It allows some pretty-printing in plain text.

To translate into text, invoke \hevea{} as follow:
\begin{verbatim}
# hevea -text [-w <width>] myfile.tex
\end{verbatim}
Then, \hevea{} produces \texttt{myfiles.txt} a plain text translation
of \texttt{myfile.tex}.

Additionally, the optional argument \texttt{-w <number>} sets the
width of the output for text formatting. By default, The text will be
72~characters wide.

Nearly every environment has 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
possible to render them in plain text. Thus, there are no italics,
bold fonts, underlinings, nor size change or colours\ldots{}
The only exception is for the verbatim environment
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
columns only.
Table rendering can be poor in case of line overflow.
The only way to correct this (apart from changing the tables
themselves) is to adjust the formatting width, using the
the \cmdopt{-w} command-line option.

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.
For instance, $x^2$ will be rendered as \verb+x^2+, but $\int_0^1f(x)dx$ will
yield something like : \verb+int01f(x)dx+.


\subsection{Info}
The file format info is also supported.
Info files are text files with limited hypertext links, they
can be read by using \emph{emacs} info mode or the
\texttt{info} program.
Please note that \hevea{} translates plain \LaTeX{} to info, and not
TeXinfo.

You can translate your \LaTeX{} files into info file(s) as follows:
\begin{verbatim}
# hevea -info [-w <width>] myfile.tex
\end{verbatim}
Then, \hevea{} produces the file \texttt{myfile.info}, an info
translation of \texttt{myfile.tex}.
However, if the resulting  file is too large, it is cut into pieces
automatically,
and \texttt{myinfo.info} now contains references for all
the nodes in the others files, which are named \texttt{myfile.info-1},
\texttt{myfile.info-2},\ldots

The optional argument \verb+-w+ has the same meaning as for text output.

The text will be organised 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
\html{}~mode.
However, the info format only allows pointers to info nodes,
\emph{i.e.}\ in \hevea{} case, to sectional units.
As a consequence all cross references lead to sectional unit headers.


\setcounter{section}{0}
\renewcommand{\thesection}{\thepart.\arabic{section}}
\cutend

\part{\label{referencemanual}Reference manual}
\cutdef{section}
This part follows the pattern of the \LaTeX{} reference
manual~\cite[Appendix~C]{latex}.

\section{Commands and Environments}

\subsection{Command Names and Arguments}

\LaTeX{} comments that start with ``\verb+%+'' %
and end at end of line are ignored and produce no output.
Usually, \hevea{} ignore such comments. However, \hevea{} processes
text that follows ``\verb+%HEVEA+'' %
and some other comments have a specific meaning to it (see
section~\ref{comments}).

\index{command!syntax}
Command names follow strict \LaTeX{} syntax. That is, apart from
\verb+#+, \verb+$+, %$
\verb+~+, \verb+_+ and \verb+^+, they either are
``\verb+\+'' followed by a single non-letter character or
``\verb+\+'' followed by a sequence of letters.
Additionally, the letter sequence may be preceded by ``\verb+@+''
(and this is the case of many of \hevea{} internal commands), or
terminated by ``\verb+*+'' (starred variants are implemented as plain
commands).

Users are strongly advised to follow strict \LaTeX{} syntax for
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{}
\verb+]+.
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
a command name.
Thus, constructs such as \verb+\'ecole+,
\verb+$a_1$+ or \verb+$a_\Gamma$+ are
recognized and processed as \'ecole $a_1$ and $a_\Gamma$.
By contrast, \verb+a^\mbox{...}+ is not recognized
and must be written  \verb+a^{\mbox{...}}+.

Also note that, by contrast with \LaTeX{}, comments are parsed during
argument scanning, as an important consequence brace nesting is also
checked inside comments.

\index{command!and arguments}
\index{argument!of commands}
With respect to previous versions,
\hevea{} has been improved as regards emulation of complicated
argument passing. That is,
commands and their arguments can now appear in
different static text bodies. As a consequence,
\hevea{} correctly processes the following source:
\begin{verbatim}
\newcommand{\boite}{\textbf}
\boite{In bold}
\end{verbatim}
The definition of \verb+\boite+ makes it reduces as
\verb+\textbf+ and \hevea{} succeeds in fetching the argument
``\verb+{In bold}+''. We get
\begin{htmlout}
\newcommand{\boite}{\textbf}
\boite{In bold}
\end{htmlout}

The above example arguably is no ``legal'' \LaTeX{},
but \hevea{} handles it.
Of course, there remains
numerous ``clever'' \LaTeX{} tricks that exploits \TeX{} internal
behaviour, which \hevea{} does not handle.
For instance consider the following source:
\begin{verbatim}
\newcommand{\boite}[1]{\textbf#1}
\boite{{In bold}, Not in Bold.}
\end{verbatim}
\LaTeX{} typesets the text ``In bold'' using bold font, leaving
the rest of the text alone. While \hevea{} typesets everything using
bold font. Here is \ifhevea\hevea\else\LaTeX\fi{} output:
\begin{htmlout}
\newcommand{\boite}[1]{\textbf#1}
\boite{{In bold}, Not in Bold.}
\end{htmlout}
Note that, in most similar situations, \hevea{} will likely crash.


As a conclusion of this important section,
Users are strongly advised to use ordinary command names and
curly braces and not to think too much the \TeX{} way.




\subsection{Environments}

Environment opening and closing is performed like in \LaTeX{}, with
\verb+\begin{+\textit{env}\verb+}+ and
\verb+\end{+\textit{env}\verb+}+.
The \verb+*+-form of an environment is a plain environment.

It is not advised to use \verb+\+\textit{env} and
\verb+\end+\textit{env} in place of \verb+\begin{+\textit{env}\verb+}+ and
\verb+\end{+\textit{env}\verb+}+.

\subsection{Fragile Commands}
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.

\subsection{Invisible Commands}
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.


\section{The Structure of the Document}\label{structure}
Document structure is a bit simplified with respect to \LaTeX{}, since
documents consist of only two parts.
The \emph{preamble} starts as soon as \hevea{} starts to operate and
ends with the \verb+\begin{document}+ construct.
Then, any input occurring before
\verb+\end{document}+ is translated to \html{}.
However, the preamble is processed
and the preamble comprises the content of the files given as command-line
arguments to \hevea{}, see section~\ref{comline}).
As a consequence, command and environment  definitions that
occur  before \verb+\begin{document}+ are performed.
and they remain
valid during all the processing.

\comindex{htmlhead}
\comindex{htmlfoot}
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
appears last in (visible) \html{} output.
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.
For instance, to append a copyright notice at the end of all the \html{}
pages, it suffices to invoke the \verb+\htmlfoot+ command as follows
in the document preamble:
\begin{verbatim}
\htmlfoot{\copyright to me}
\end{verbatim}


\index{color!of background|see{\texttt{\char92"@bodyargs}}}
\index{"@bodyargs@\texttt{\char92"@bodyargs}}
\index{"@htmlargs@\texttt{\char92"@htmlargs}}
\index{"@meta@\texttt{\char92"@meta}}\label{metadef}
The \verb+\htmlhead+ command cannot be used for changing anything outside of
the \html{} document body, there are specific commands for doing this.
Those command must be used in the document preamble.
One can
change \hevea{} default (empty) attribute of
the opening \verb+<body ...>+ tag by redefining
\verb+\@bodyargs+.
For instance, you get black text on a white background, when the
following declaration occurs before \verb+\begin{document}+:
\begin{verbatim}
\renewcommand{\@bodyargs}{style="color:black;background:white"}
\end{verbatim}
Since version 1.08, a recommended alternative is to use style sheets:
\begin{verbatim}
\newstyle{body}{color:black; background:white;}
\end{verbatim}

One can also change the default (empty) attribute of the opening
\verb+<html ...>+ tag by redefining
\verb+\@htmlargs+. For instance you can set the language attribute
of the whole document by issuing the following redefinition in
the document preamble:
\begin{verbatim}
\renewcommand{\@htmlargs}{lang=en}
\end{verbatim}

\comindex{let}\envindex{rawhtml}
\label{exlet}Similarly, some elements can be inserted into the output file
\verb+head+ element by redefining the \verb+\@meta+ command
(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
author information as follows:
\begin{verbatim}
\let\oldmeta=\@meta
\renewcommand{\@meta}{%
\oldmeta
\begin{rawhtml}
<meta name="Author" content="Luc Maranget">
\end{rawhtml}}
\end{verbatim}
Note how \verb+\@meta+ is first bound to
\verb+\oldmeta+ before being redefined and how \verb+\oldmeta+ is
invoked in the new definition of \verb+\@meta+.
Namely, simply overriding the old definition of \verb+\@meta+ would
imply not outputting default meta-information.

\index{"@charset@\texttt{\char92"@charset}}
The \verb+\@charset+ command holds the value of the (\html) document character
set. By default, this value is \texttt{US-ASCII}.
In previous versions of \hevea{}, one could change the
value of the document character set by simply redefining
\verb+\@charset+. Then, it was users responsability to provide a
(\LaTeX) document in the correspounding encoding.
This is no longer so, and users should \emph{not} redefine
\verb+\@charset+ directly. Please, see Section~\ref{encodings} for details.


\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{} behaviour, 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.
Paragraph are rendered by \verb+p+ elements.
In some occasions, this technique may produce spurious paragraphs
(see~\ref{spurious:par}).

\subsection{Footnotes\label{sec:footnotes}}
The commands \verb+\footnote+,
\verb+\footnotetext+ and \verb+\footnotemark+ (with or without
optional arguments) are supported.
The \verb+footnote+ counter exists and (re)setting it or redefining
\verb+\thefootnote+ should work properly.
When footnotes are issued by a combination of \verb+\footnotemark+ and
\verb+\footnotetext+, a \verb+\footnotemark+
command must be issued
first, otherwise some footnotes may get numbered incorrectly or disappear.
Footnotes appear at document end in the \filename{article} style and
at chapters end in the \filename{book} style.
See section~\ref{hachafoot} for a description of how footnotes are flushed.


\subsection{Accents\label{accents} and special symbols}
Thanks to Unicode character references, \hevea{} can virtually output
any symbol.
It may happen that \hevea{} does not known about a particular symbol,
that is, most of the time, \hevea{} does not known about a particular
command. In that case a warning is issued to draw user attention.
Users can then choose a particular symbol amongst the recognized ones,
or as an explicit Unicode character reference (see
Section~\ref{square:blob} for an example of this technique).

Commands for making accents used in non-English languages, such as
\verb+\'+, work when applied to accent-less (\emph{i.e.}\ ascii)
letters and that the corresponding accented letters exist
in the Unicode character set.
Otherwise, the argument to the command is not modified
and a warning is issued.
For instance, consider the following source code, where, after a
legitimate use of acute accents, one attempt to put an accute accent
over the letter~``h'':
\begin{verbatim}
``\'Ecole'' works as in \LaTeX, while ``\'h'' does not.
\end{verbatim}
\ifhevea
\hevea{} output will be ``\'Ecole'' works as in \LaTeX, while ``\'h'' does not.
\else
\hevea{} output will  be ``\'Ecole'' works as in \LaTeX, while ``h'' does not.
\fi{}
And a warning will be issued.
\begin{verbatim}
./tmp.tex:3741: Warning: Application of '\'' on 'h' failed
\end{verbatim}


Observe that using input encodings
is a convenient alternative to accent commands ---
see Section~\ref{inputenc}.

\section{Sectioning}\cutname{sectioning.html}

\subsection{\label{section:section}Sectioning Commands}
Sectioning commands from \verb+\part+ down to
\verb+\subparagraph+ are defined in base style files.
They accept an optional argument and have starred versions.


The non-starred sectioning commands from \verb+\part+ down to
\verb+\subsubsection+ show section numbers in sectional unit headings,
provided their \textit{level} is greater than or equal to the current
value of the \verb+secnumdepth+ counter.
Sectional unit levels and the default value of the \verb+secnumdepth+ counter
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}.
For instance, the following redefinition turn the numbering of
chapters into alphabetic (uppercase) style:
\begin{verbatim}
\renewcommand{\thechapter}{\Alph{chapter}}
\end{verbatim}

\comindex{label}%
When jumping to anchors, browsers put the targeted line on top
of display. As a consequence, in the following code:
\begin{verbatim}
\section{A section}
\label{section:section}
 ...
See Section~\ref{section:section}
\end{verbatim}
Clicking on the link produced by
\verb"\ref{section:section}" will result in \emph{not} displaying the
targeted section title.
A fix is writing:
\begin{verbatim}
\section{\label{section:section}A section}
 ...
See Section~\ref{section:section}
\end{verbatim}

Starting with version 2.04, \hevea{} and \hacha{} will use the label name
(\verb+section:section+ above) for the table of  contents they generate.
\begin{htmlonly}
For instance, the source code for the next sectioning command just
below is:
\begin{verbatim}
\subsection{The \label{appendix}Appendix}
\end{verbatim}
As a consequence, the link to the next section on top
of this page should read as:
\begin{verbatim}
<a href="sectioning.html#appendix">The Appendix</a>
\end{verbatim}
That is, \hevea{} used the label name given in source as
an anchor.
\end{htmlonly}
Notice that this behaviour applies to the \verb+\label+ command
that occurs first in the sectioning command argument.

\subsection{The \label{appendix}Appendix}
The \verb+\appendix+ command exists and should work as in \LaTeX.

\subsection{Table of Contents}
\comdefindex{tableofcontents}%
\comdefindex{addcontentsline}%
\hevea{} now generates a table of contents, using a procedure similar
to the one of \LaTeX
(a \texttt{.htoc} file is involved).
One inserts this table of contents in the main document by issuing
the command \verb+\tableofcontents+.
Table of contents is controlled by the counter  \verb+tocdepth+.
By default, the table of contents shows sectioning units down to the
subsubsection level in \textit{article} style and down to the subsection level
in \textit{book} (or \textit{report}) style. To include more or less
sectioning units in the
table of contents, one should increase or decrease the \verb+tocdepth+
counter.
It is important to notice that \hevea{} produces such a table of
contents, only when it has total control over cross-references.
More precisely, \hevea{} cannot produce the table of contents when it
reads \LaTeX{}-produced \texttt{.aux}~files.
Instead, it should read its own \texttt{.haux}~files.
This will naturally occur if no \texttt{.aux} files are present,
otherwise these \texttt{.aux} files should be deleted, or \hevea{}
should be instructed not to read them with the command-line option
\cmdopt{-fix}
(see Sections \ref{files} and ~\ref{heveaoptions}).

One can also add extra entries in the table of contents by using
the command \verb+\addcontentslines+, in a way similar
to \LaTeX{} homonymous command.
However, hyperlinks need to be introduced explicitly,
as in the following example, where
an anchor is defined in the section title and referred to in the
argument to \verb+\addcontentsline+:
\begin{verbatim}
\subsection*{\aname{no:number}{Use \hacha{}}}
\addcontentsline{toc}{subsection}{\ahrefloc{no:number}{Use \hacha{}}}
\end{verbatim}
(See Section~\ref{hyperlink} for details on commands related to hyperlinks.)

There is no list of figures nor list of tables.

\subsection*{\aname{no:number}{Use \hacha{}}}
\addcontentsline{toc}{subsection}{\ahrefloc{no:number}{Use \hacha{}}}
However, \hevea{} has a more sophisticated way of producing
a kind of map w.r.t. the sectioning of the document.
A later run of {\hacha} on \hevea{} output file splits it
in smaller files organized in a tree whose nodes are tables of
links.
By contrast with \LaTeX{}, starred sectioning commands generate
entries in these tables of contents.
Table of contents entries hold the optional argument to sectioning
commands or their argument when there is no optional
argument. Section~\ref{hacha} explains how to
control {\hacha}.

\section{Classes, Packages and Page Styles}

\subsection{Document Class}
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.
Presently, only the style files \texttt{article.hva}, \texttt{seminar.hva},
\texttt{book.hva} and \texttt{report.hva} exist, the latter two
being equivalent.

If one of the recognized 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 a command
line argument (see~\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}
\comindex{usepackage}
\hevea{} reacts to
\verb+\usepackage[+\textit{options}\verb+]{+\textit{pkg}\verb+}+ in
the following way:
\begin{enumerate}
\item  The whole
\verb+\usepackage+ command with its arguments gets echoed to the
\filename{image} file (see~\ref{imagen}).
\item \hevea{} attempt to load file \textit{pkg}\texttt{.hva},
(see section~\ref{search:path} on where \hevea{} searches for files).
\end{enumerate}
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 \texttt{fullpage} package.

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
implementations by themselves.


\subsection{The Title Page and Abstract}

All title related commands exist with the following peculiarities:

\begin{itemize}
\item The argument of the \verb+\title+\comindex{title}~command
  appears in the \html~document header.  As a consequence titles
  should remain simple.  Normal design (as regards \hevea) is
  for \verb+\title+ to occur in the document preamble, so that the
  title is known at the time when the document header is emitted, this
  is, while processing \verb+\begin{document}+.  However, there are
  two subtleties.

  \begin{enumerate}
  \item If no \verb+\title+~command occurs in document preamble and
    that one \verb+\title+~command appears in the document, then the
    title is saved into the \texttt{.haux}~file for the next run of
    \hevea{} to put it in the \html~document header.

  \item If \verb+\title+~commands are present both in preamble and
    after \verb+\begin{document}+ the former takes precedence.
  \end{enumerate}

\item When not present the date is left empty.  The
  \verb+\today+\comindex{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.
\end{itemize}

The \verb+abstract+ environment is present in all base styles,
including the \filename{book}~style.  The \verb+titlepage+~environment
does nothing.

\hevea{} places the \verb+\title+~argument into an \verb+h1+-element
with class~\verb+titlemain+ and puts the arguments of \verb+\author+
and \verb+\date+ into a \verb+h3+-element with class~\verb+titlerest+.
The abstract goes into a \verb+blockquote+-element with
class~\verb+abstract+.


\section{Displayed Paragraphs}
Displayed-paragraph environments translate to block-level
elements.

In addition to the environments described in this section,
\hevea{} implements the \verb+center+, \verb+flushleft+ and
\verb+flushright+ environments.
\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
element.


\subsection{Quotation and Verse}

The \verb+quote+ and \verb+quotation+~environments are similar; they
translate to \verb+BLOCKQUOTE+~elements with associated
classes~\verb+quote+ and \verb+quotation+, respectively.

The \verb+verse+~environment is supported as \verb+BLOCKQUOTE+~element
with class~\verb+verse+.


\subsection{List-Making environments}

The \verb+itemize+, \verb+enumerate+ and \verb+description+
environments translate to the \verb+ul+, \verb+ol+, and
\verb+DL+ elements and this is the whole story.

As a consequence, no control is allowed on the appearances of these
environments.  More precisely optional arguments to \verb+\item+ do not
function properly inside \verb+itemize+ and \verb+enumerate+.  Moreover, item
labels inside \verb+itemize+ or numbering style inside \verb+enumerate+
are browser dependent.

However, customized lists can be produced by using the
the \texttt{list} environment (see next section).


\subsection{The \protect\texttt{list} and \protect\texttt{trivlist}
environments}
The \verb+list+ environment translates to the
\verb+DL+ element.
Arguments to \verb+\begin{list}+ are handled as follows:

\begin{flushleft}
\quad\verb+\begin{list}{+{\it default\_label}\verb+}{+{\it decls}\verb+}+
\end{flushleft}

The first argument {\it default\_label} is the label generated by an
\verb+\item+ command with no argument.
The second argument, {\it decls} is a sequence of declarations.
In practice, the following declarations are relevant:
\begin{list}{}{}
\item[\texttt{\char92 usecounter\{}\textit{counter}\texttt{\}}]
The counter {\it counter} is incremented by \verb+\refstepcounter+
by every \verb+\item+ command with no argument, before it does
anything else.
\item[\texttt{\char92 renewcommand\{\char92
makelabel\}[1]\{}\ldots\texttt{\}}]
The command \verb+\item+ executes
\verb+\makelabel{+{\it label}\verb+}+, where {\it label} is the item
label, to print its label.
Thus, users can change label formatting by redefining
\verb+\makelabel+.
The default definition of \verb+\makelabel+ simply echoes \textit{label}.
\end{list}

As an example, a list with an user-defined counter can be defined as
follows:
\begin{verbatim}
\newcounter{coucou}
\begin{list}{\thecoucou}{%
\usecounter{coucou}%
\renewcommand{\makelabel}[1]{\textbf{#1}.}}
...
\end{list}
\end{verbatim}
This yields:
\newcounter{coucou}
\begin{list}
  {\thecoucou}
  {\usecounter{coucou}\renewcommand{\makelabel}[1]{\textbf{#1}.}}
\item First item.
\item Second item.
\end{list}

The \verb+trivlist+ environment is also supported. It is equivalent to
the \verb+description+ environment.


\subsection{Verbatim}

The \verb+verbatim+ and \verb+verbatim*+ environments translate to
the \verb+PRE+~elements.  Inside \verb+verbatim*+, spaces are replaced
by visual spaces (``\verb*+ +'').  Similarly, \verb+\verb+
and \verb+\verb*+ translate to \verb+CODE+ text elements.  The
environments are associated with CSS~classes of the same names, this
is, \verb+verbatim+ and \verb+\verb+, respectively.

The \verb+alltt+ environment is supported.


\section{Mathematical Formulae}

\subsection{Math Mode Environment}
The three ways to use math mode (\verb+$+\ldots\verb+$+,
\verb+\(+\ldots\verb+\)+ and
\verb+\begin{math}+\ldots\verb+\end{math}+) are supported.
The three ways to use display math mode (\verb+$$+\ldots\verb+$$+,
\verb+\[+\ldots\verb+\]+ and
\verb+\begin{displaymath}+\ldots\ \verb+\end{displaymath}+) are also
supported.
Furthermore, \verb+\ensuremath+ behaves as expected.


The \verb+equation+, \verb+eqnarray+, \verb+eqnarray*+ environments
are supported.
Equation labelling and numbering is performed in the first two
environments, using the \verb+equation+ counter.
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
rendered using text-level elements only.  By contrast, displayed
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
the over is possible only in display context.
\begin{htmlonly}
For instance compare how \hevea{} renders
\verb+$\frac{1}{\sum_{i=1}^{\infty} i$+
as: $\frac{1}{\sum_{i=1}^{\infty} i}$, and 
\verb+$$\frac{1}{\sum_{i=1}^{\infty} i$$+ as:
$$\frac{1}{\sum_{i=1}^{\infty} i}$$
\end{htmlonly}


\subsection{Common Structures}

\hevea{} admits, subscript (\verb+_+), superscripts (\verb+^+) and
fractions (\verb+\frac{+{\it numer}\verb+}{+{\it denom}\verb+}+).
The best effect is obtained in display mode, where \html{}
\verb+table+ element is extensively used.
By contrast, when not in display mode, \hevea{} uses only
\verb+SUB+ and \verb+SUP+ text-level elements to render superscrits
and subscript, and the result may not be very satisfying.

However,
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
even in in-text formulas.

When occurring outside math mode, characters \verb+_+ and \verb+^+ act as
ordinary characters and get echoed to the output. However, a warning
is issued.

An attempt is made to render all ellipsis constructs (\verb+\ldots+,
\verb+\cdots+, \verb+\vdots+ and \verb+\ddots+). The effect may be
strange for the latter two.

\subsection{Square Root}
\index{\verb+\sqrt+}\index{sqrt}
The n$^{\mbox{th}}$ root command \verb+\sqrt+ is supported only for n=3,4, thanks to the existence of Unicode characters for the same. For the others, we shift to fractional exponents, in which case, the \verb+\sqrt+ command is
defined as follows:
\begin{verbatim}
\newcommand{\sqrt}[3][2]{\left(#2\right)^{1/#1}}
\end{verbatim}
\begin{htmlonly}
Then, the source
fragment: \verb"$$\sqrt[5]{\frac{1}{n!}} + \sqrt[3]{\pi} + \sqrt{\pi}$$" gets rendered
as follows:
$$
\sqrt[5]{\frac{1}{n!}} + \sqrt[3]{\pi} + \sqrt{\pi}
$$
\end{htmlonly}

\subsection{Unicode and mathematical symbols}\index{unicode}

The support for unicode symbols offered by modern browsers allows to
translate almost all math symbols correctly.

Log-like functions and variable sized-symbols are recognized and their
subscripts and superscripts are put where they should in display mode.
Subscript and superscript placement can be changed using the
\verb+\limits+ and \verb+\nolimits+ commands.
Big delimiters are also handled.

\subsection{Putting one thing above/below/inside}

\comindex{textstackrel}\comindex{textunderline}\comindex{textoverline}
The commands \verb+\stackrel+,  \verb+\underline+ and \verb+\overline+
are recognized.
They produce sensible output in display mode.
In text mode, these macros call the \verb+\textstackrel+,
\verb+\textunderline+ and \verb+\textoverline+ macros.
These macros perform the following default actions
\begin{description}
\item[\texttt{\char92 textstackrel}] Performs ordinary superscripting.
\item[\texttt{\char92 textunderline}] Underlines its argument, using the
\verb+U+ text-level element.
\item[\texttt{\char92 textoverline}] Overlines using style-sheets (used {\tt <SPAN>} with a top border). 
\end{description}

\index{\verb+\boxed+} The command \verb+\boxed+ works well both in display and normal math mode. Input of the form \verb+\boxed{\frac{\pi}{2}}+ produces $\boxed{\frac{\pi}{2}}$ in normal math, and 
$$\boxed{\frac{\pi}{2}}$$
in display-math mode. The commands \verb+\bigl,\bigr+ etc. \index{\verb+\bigl,\bigr+ etc.}are also rendered well. Some examples can be found \ifhevea \footahref{../examples/random-math.html}{here}\else in the test file {\tt random-math.html} provided with the distribution\fi.

\subsection{Math accents}\index{math accents}
Math accents that have coresponding text accents
(\verb+\hat+, \verb+\tilde+, etc.) are
handled\label{mathaccents} by default.  They in fact act as the
corresponding text-mode accents (Section~\ref{accents}).
As a consequence, they work properly only on ascii letters.
This may be quite cumbersome, but at least some warnings draw user's
attention on the problem.
If accents are critical to your document and that \hevea{} issues
a lot of warnings, a solution is to redefine the math accent command.
A suggested replacement is using limit superscripts.
That way accents are positioned above symbols in display mode and
after symbols in text mode.
\begin{verbatim}
\renewcommand{\hat}[1]{\mathop{#1}\limits^{\textasciicircum}\nolimits}
Displayed:
$$
\hat{\mu} = \hat{\Delta}.
$$
In text: $\hat{\mu} = \hat{\delta}$
\end{verbatim}
\ifhevea
An you get,
{\renewcommand{\hat}[1]{\mathop{#1}\limits^{\textasciicircum}\nolimits}
displayed:
$$
\hat{\mu} = \hat{\Delta}.
$$
In text: $\hat{\mu} = \hat{\delta}$.}

Whereas, with the default of \verb+\hat+ being \verb+\^+,
you get ``$\hat{\mu} = \hat{\delta}$'', with the following warnings:
\begin{verbatim}
./tmp.tex:4652: Warning: Application of '\^' on '\mu' failed
./tmp.tex:4652: Warning: Application of '\^' on '\delta' failed
\end{verbatim}
\fi


The \verb+\vec+
command is rendered differently in display and non-display mode. In
display mode, the arrow appears in normal position, while in
non-display the arrow appears as an ordinary superscript.
$$
\mbox{\texttt{\textbackslash{}vec\{u\}} in text mode: $\vec{u}$},\quad
\mbox{\texttt{\textbackslash{}vec\{u\}} in display mode:}~\vec{u}
$$

Most ``extensible accents'' (\verb+\widetilde+, \verb+\widehat+, etc.)
are not even defined.
There are a few exceptions: line ``accents'':
$$\newcommand{\demo}[1]{\quad\quad#1{abc}\quad\texttt{\string#1}}
\begin{array}{cc}
\demo{\underline} & \demo{\overline}
\end{array}
$$

Brace ``accents'':
$$\newcommand{\demo}[1]{\quad\quad#1{1 \times 2 \times \cdots \times n}\quad\texttt{\string#1}}
\begin{array}{cc}
\demo{\underbrace} & \demo{\overbrace}
\end{array}
$$


And arrow ``accents'':\bgroup
\newcommand{\demo}[1]{\quad\quad#1{1 \times 2 \times \cdots \times n}\quad\texttt{\string#1}}
$$
\begin{array}{cc}
\demo{\overleftarrow} & \demo{\overrightarrow}
\end{array}
$$\egroup


\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.
Furthermore,
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
\verb+\;+) are recognized, the first two commands do nothing, while
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
default.

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
mode,
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
in the output.
As a consequence, warnings on \verb+\displaystyle+ are to be taken seriously.


The commands \verb+\scriptstyle+ and \verb+\scriptscriptstyle+
perform type size changes.

\section{Definitions, Numbering}

\subsection{Defining Commands}\label{usermacro}

\index{command!definition|defocc}
\comindex{newcommand}
\comindex{renewcommand}
\hevea{} understands command definitions given in \LaTeX{} style. Such
definitions are made using
\verb+\newcommand+, \verb+\renewcommand+ and \verb+\providecommand+.
These three constructs accept the same arguments and have the same
meaning as in \LaTeX{}, in particular it is possible to define an user
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
\verb+\renewcommand{+{\it name}\verb+}+\ldots performs{} a definition of {\it
name}.  In both cases, \LaTeX{} would crash, \hevea{} just issues
warnings.

The behaviour of \verb+\newcommand+ allows to shadow document
definition, provided the new definitions are processed before the
document definitions.
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 (\emph{i.e.}\ the ones that \hevea{}
defines before loading any user-specified file) must be performed
using \verb+\renewcommand+.



Scoping rules apply to macros, as they do in \LaTeX{}.
Environments and groups define a scope and command definition
are local to the scope they occur.

It is worth noticing that \hevea{} also partly implements \TeX{} definitions
(using \verb+\def+) and bindings (using \verb+\let+), see
section~\ref{texmacro} for details.


\subsection{Defining Environments}
\hevea{} accepts environment definitions and redefinitions
by \verb+\newenvironment+ and \verb+\renewenvironment+.
The support is complete and should conform
to~\cite[Sections~C.8.2]{latex}.


Environments define a scope both for commands and environment
definitions.


\subsection{Theorem-like Environments}
New theorem-like environments can also be introduced and redefined,
using \verb+\newtheorem+ and \verb+\renewtheorem+.

Note that, by contrast with plain environments definitions,
theorem-like environment definitions are global definitions.

\subsection{Numbering}
\LaTeX{} counters are (fully ?) supported.
In particular, defining a counter \textit{cmd} with
\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:
\begin{verbatim}
\renewcommand{\thesection}{\alph{section}}
\end{verbatim}

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}
\ttindex{ifthen}{package}
The \texttt{ifthen} package is partially supported.
The one unsupported construct is the
\verb+\lengthtest+ test expression, which is
undefined.

As a consequence, \hevea{} accepts the following example from the
\LaTeX{} manual:
\begin{verbatim}
\newcounter{ca}\newcounter{cb}%
\newcommand{\printgcd}[2]{%
  \setcounter{ca}{#1}\setcounter{cb}{#2}%
  Gcd(#1,#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}.}%
For example: \printgcd{54}{30}
\end{verbatim}
\newcounter{ca}\newcounter{cb}%
\newcommand{\printgcd}[2]{%
  \setcounter{ca}{#1}\setcounter{cb}{#2}%
  Gcd(#1,#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}.}%
For example: \printgcd{54}{30}

Additionally, a few boolean registers are defined by \hevea{}.
Some of them are of interest to users.
\begin{description}
\item[\texttt{hevea}] Initial value is \texttt{true}.
The \texttt{hevea.sty} style file also defines this register with
initial value \textit{false}.
\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
mode, it is \textit{true} in display-mode and \textit{false} otherwise.
\item[\texttt{footer}] Initial value is  \texttt{true}.
When set false, \hevea{} does not insert its footer ``\emph{This
document has been translated by \hevea}''.

\end{description}

Finally, note that \hevea{} also recognised \`a 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.


\section{Figures, Tables, and Other Floating Bodies}

\subsection{Figures And Tables}

Figures and tables are put where they appear in the source
(location~``\verb+h+''), regardless of their placement arguments.
\hevea{} wraps them in \verb+BLOCKQUOTE+~elements that are associated
with CSS~classes \verb+figure+ and \verb+table+ respectively.  Figures
and tables are separated from enclosing text by two horizontal rules
(CSS~class \verb+floatrule+).  If the capabilities of \verb+floatrule+
prove insufficient users can create their own separators by defining
the parameter-less macro~\verb+\floatseparator+, like for example,

\begin{verbatim}
\newcommand{\floatseparator}{\begin{center}\ast\end{center}}
\end{verbatim}

\noindent or even drop them completely by supplying an empty expansion
and thereby recover the original \LaTeX{} layout.

Captions and cross referencing are handled.  However, captions are not
moved at end of figures or tables: instead, they appear where the
\verb+\caption+~commands occur in source.

The \verb+\suppressfloats+ command does nothing; the figure related
counters (such as \verb+topnumber+) exist but are useless.


\subsection{Footnotes}

The basics of footnotes are discussed in section~\ref{sec:footnotes}.

\hevea{} puts the text of every footnote in a block associated with
CSS~class \verb+footnotetext+.  The rule that separates the body text
from the footnotes can by styled with CSS~class \verb+footnoterule+.


\subsection{Marginal Notes}

\comdefindex{marginpar}%
\comdefindex{reversemarginpar}%
\comdefindex{normalmarginpar}%
\marginpar{Marginal notes go in the right margin by default.}
\reversemarginpar%
\marginpar{To get marginal notes in the left margin, use
\url|\reversemaginpar|.}
\normalmarginpar%
Marginal notes are handled in an \hevea{} specific way.
By default, all notes go in the right margin.
Issuing \verb+\reversemarginpar+ causes the notes to go in the left
margin. Unsurprisingly, issuing \verb+\normalmarginpar+ reverts to
default behaviour.

The \verb+\marginpar+ command has an optional argument.
\begin{flushleft}
\quad\verb+\marginpar[+\textit{left\_text}\verb+]{+\textit{right\_text}\verb+}+
\end{flushleft}
If optional argument \textit{left\_text} is present and that notes
go in the left margin, then \textit{left\_text} is the text of the
note. Otherwise, \textit{right\_text} is the text of the note.
As a conclusion, marginal notes in \hevea{} always go to a fixed side
of the page, which side being controlled by the commands
\verb+\normalmarginpar+ (right side) and \verb+\reversemarginpar+
(left side). This departs form \LaTeX{} that selects a default side
depending on the parity of the page counter.

Marginal notes are styled by the means of two environment style
classes (see Section~\ref{css:change})~:
\verb+marginpar+ and \verb+marginparside+.
The latter \verb+marginparside+ takes care of margins and placement as
a float, its value is \verb+marginparright+ for notes in the right
margin and \verb+marginparleft+ for notes in the left margin.
Users are not expected to alter those.
The \verb+marginpar+ environment style class governs the general
aspect of all marginal notes.
Users can control the aspect of all marginal notes by defining a new
style class and assigning the \verb+marginpar+ environment style
class.
For instance, to get all marginal notes in red font,
and taking 10\% of the page width (in place of the default
20\%),
one can issue the following commands in the document preamble.
\begin{verbatim}
\newstyle{.mynote}{width:10\%; color:red;}
\setenvclass{marginpar}{mynote}
\end{verbatim}


\section{Lining It Up in Columns}
\subsection{The \protect\texttt{tabbing} Environment}
Limited support is offered.
The \texttt{tabbing} environment translate to a flexible \texttt{tabular}-like
environment.
Inside this environment, the command \verb+\kill+ ends a row, while
commands
\verb+\=+ and \verb+\>+ start a new column.
All other tabbing commands do not even exist.

\subsection{The \texttt{array} and \texttt{tabular}
environments}\label{arraydef}

These environments are supported, using \html{}
\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
while the remaining \verb+p+ and \verb+@+ do not.
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 alignment constraints
(such as \verb+p{+\textit{wd}\verb+}+, see below).
Otherwise, vertical alignment 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:
\begin{itemize}
\item Optional arguments to \verb+\begin{array}+ and
\verb+\begin{tabular}+ are ignored.
\item The command \verb+\vline+ does not exists.
\end{itemize}

Some others are partly rendered:
\begin{itemize}
\item Spacing between columns is different.
\item \verb+@+ formatting specifications in \verb+\multicolumn+
argument are ignored.
\item If a \verb+|+ appears somewhere in the column formatting
specification, then the array is shown with borders.
\item The command \verb+\hline+ does nothing if the array has borders
(see above). Otherwise, an horizontal rule is outputted.
\item The command \verb+\cline+ ignores its argument and is equivalent
to \verb+\hline+.
\item Similarly the command
\verb+\extracolsep+ issues a warning and ignores its argument.
\end{itemize}
Additionally, the \verb+tabular*+ environment is
recognised and gets rendered 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.

\section{Moving Information Around}

\subsection{\label{files}Files}
In some situations,
\hevea{} uses some of the ancillary files generated by \LaTeX.
More precisely, while processing file \filename{doc}\texttt{.tex},
the following files may be read:
\begin{description}
\item[\protect\texttt{.aux}] The file \filename{doc}\texttt{.aux} contains
cross-referencing information, such as figure or section numbers.
If this file is present, \hevea{} reads it and put such numbers (or
labels) inside
the links generated by the \verb+\ref+ command. If the \texttt{.aux}
file is not present, or if the \texttt{hevea} command is given the
\texttt{-fix} option, \hevea{} will instead use \texttt{.haux}
files.
\item[\protect\texttt{.haux}] Such files are \hevea{} equivalents of
\texttt{.aux} files. Indeed, they are \texttt{.aux} files tailored to
\hevea{} needs.
Two runs of \hevea{} might be needed to get cross references right.
\item[\protect\texttt{.htoc}] This file contains a formatted table of
contents. It is produced while reading the \texttt{.haux} file.
As consequence a table of contents is available only when the
\texttt{.haux} file is read.


\item[\protect\texttt{.hbbl}] The \filename{doc}\texttt{.hbbl} file
is generated by \texttt{bibhva} from \filename{doc}\texttt{.haux}.
When present, it is read by the \verb+\bibliography+ command.

\item[\protect\texttt{.bbl}] The \filename{doc}\texttt{.bbl} file is
generated by \BibTeX{} from \filename{doc}\texttt{.aux}.
When present, and if no \filename{doc}\texttt{.hbbl} exists,
\filename{doc}\texttt{.bbl} is read by the \verb+\bibliography+ command.

\item[\protect\texttt{.hidx} and \protect\texttt{.hind}]
\hevea{} computes its own indexes, using \texttt{.hidx} files for
storing index references and, using \texttt{.hind} files
for storing formatted indexes.
Index formatting significantly departs from the one of \LaTeX{}.
Again, several runs of \hevea{} might be needed to get indexes right.
\end{description}

\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 responsibility to rerun \hevea{}.
However, the convenient \cmdopt{-fix} command-line option instructs
\hevea{} to rerun itself, until it believes it has reached stable state.

\subsection{Cross-References\label{cross-reference}\label{cross}}
\comdefindex{label}\comdefindex{ref}
The \LaTeX{} commands \verb+\label+ and \verb+\ref+ are changed by \hevea{}
into {\html} anchors and local links, using the ``\verb+a+'' element.
Additionally, numerical references to sectional units, figures,
tables, etc. are shown, as they would appear in the \texttt{.dvi}~file.
Numerical references to pages (such as generated by \verb+\pageref+)
are not shown; only an link is generated.

The anchor used is the \textit{label} argument to
\verb+\label{+\textit{label}\verb+}+.
More precisely, \verb+\label{+\textit{label}\verb+}+ translates to
\verb+<a id="+\textit{label}\verb+"></a>+;
while \verb+\ref{+\textit{label}\verb+}+
translates to \verb+<a name="#+\textit{label}\verb+">+\textit{nnn}\verb+</a>+,
where \textit{nnn} is the appropriate numerical reference to a section.
As a consequence spaces are better avoided in~\textit{label}.

Starting with \hevea{} version 2.04,
the \html{} anchors used by \verb+\label+ and~\verb+\ref+ cannot
differ from the arguments to these commands anymore.
Moreover,
when \verb+\label{+\textit{label}\verb+}+ occurs
inside the argument of a sectioning command (\emph{i.e.} in section title,
as recommended by section~\ref{section:section}),
then \hevea{} and \hacha{} will use \textit{label}
as the ``\texttt{id}'' attribute of the corresponding section.
For instance, the \LaTeX{} source of this very section is:
\begin{verbatim}
\subsection{Cross-References\label{cross-reference}}
\end{verbatim}
It translates to \html{} similar to
\begin{verbatim}
<h3 class="subsection" id="cross-reference">B.11.2&#XA0;&#XA0;Cross-References</h3>
\end{verbatim}
Notice that no \verb+<a id="cross-reference"></a>+ appears above.
Instead \verb+id="cross-reference"+ appears
in the enclosing \verb+h3+ header element.


While processing a document \filename{doc}\texttt{.tex},
cross-referencing information can be computed in two different, mutually
exclusive, ways, depending
on whether \LaTeX{} has been previously run or not:
\begin{itemize}
\item If there exists a file 
\filename{doc}\texttt{.aux} and that \texttt{hevea} has not been
given the command-line option \texttt{-fix},
then cross-referencing information is extracted
from that file. Of course, the \filename{doc}\texttt{.aux} file
has to be up-to-date, that is,
it should be generated by running \LaTeX{} as many times as necessary.
(For \hevea{} needs, one run is probably sufficient).
\item If no \filename{doc}\texttt{.aux} file exists or if \texttt{hevea}
has been given the \texttt{-fix} command-line option, then \hevea{}
expect to find cross-referencing information in the file
\filename{doc}\texttt{.haux}.
\end{itemize}
The second option is recommended.

When using its own \filename{doc}\texttt{.haux} file,
\hevea{} will output a
new \filename{doc}\texttt{.haux} file at the end of its processing.
This new  \filename{doc}\texttt{.haux} file contains actualised
cross referencing information.
Hence, in that case, \hevea{} may need to run twice to get
cross-references right.
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{doc}\texttt{.haux} does not exist.


Observe that if a non-correct \filename{doc}\texttt{.aux} file is
present, then cross-references will apparently be wrong. However the
links are correct.


\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
\verb+\bibitem+ command.

\subsubsection*{Using \BibTeX}
All \BibTeX{} related commands exist and echo the appropriate
information into the \texttt{.haux} file.

In particular, the \verb+\bibliography+ command exists and attempts to load the
formatted bibliography, \emph{i.e.}\ to load the \texttt{.hbbl} file.
The \texttt{.hbbl} file is produced from the \texttt{.haux} file by
the companion program~\texttt{bibhva} (see~\ref{bibhva}).
To include the bibliographic references extracted from \texttt{.bib}
databases, it should normally suffice to do:
\begin{verbatim}
# hevea doc.tex
# bibhva doc
# hevea doc.tex
\end{verbatim}

In case no \texttt{.hbbl} file exists,
the \verb+\bibliography+ command attempts to load
the \texttt{.bbl} file normally used while combining \LaTeX{} and
\BibTeX. Thus, another way to extract bibliographic references from
\texttt{.bib} databases is:
\begin{verbatim}
# latex doc.tex
# bibtex doc
# hevea doc.tex
\end{verbatim}
In case both files exist,
notice that loading the \texttt{.hbbl} file has priority over
loading the \texttt{.bbl} file.


\subsection{Splitting the Input}
\comdefindex{input}
The \verb+\input+ and \verb+\include+ commands exist and they perform
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
the \verb+\includeonly+ command.

\index{argument!of input@of \texttt{\char92 input}}
Note the following features:
\begin{itemize}
\item \TeX{} syntax for \verb+\input+ is not supported. That is,
one should write \verb+\input{+\textit{filename}\verb+}+.
\item If \textit{filename} is excluded with the \cmdopt{-e} command-line
option (see section~\ref{heveaoptions}),
then \hevea{} does not attempt to load \textit{filename}.
Instead, it
echoes \verb+\input{+\textit{filename}\verb+}+ and
\verb+\include{+\textit{filename}\verb+}+ commands into the
\textit{image} file. This sounds complicated, but this is what you want!
\item \hevea{} does not fail when it cannot find
a file, it just issues a warning.
\end{itemize}

The \verb+\listfiles+ command is a null command.


\subsection{Index and Glossary}\label{index}
\envdefindex{indexenv}\countindex{indexcols}
Glossaries are not handled.  (Who uses them anyhow?)

While processing a document \filename{doc}\texttt{.tex}, index
entries go into the file \filename{doc}\texttt{.hidx}, while
the formatted index gets written into the file
\filename{doc}\texttt{.hind}.
As with \LaTeX{}, two runs of \hevea{} are normally needed to format
the index.
However, if all index producing commands (normally \verb+\index+)
occur before the index formatting command (usually
\verb+\printindex+), then only one run is needed.

As in \LaTeX, index processing is not enabled by default and
some  package has to be loaded explicitly in the
document preamble.
To that aim, \hevea{} provides the standard packages \texttt{makeidx}
and \texttt{imakeidx}, as well as
two extended packages that allow the production of several indexes
(see section~\ref{multind}).

Formatting of indexes in \hevea{} departs from \LaTeX{} behaviour:
environment \verb+the@hevea@index+ replaces
the \verb+theindex+~environment; \verb+the@hevea@index+ places all
index entries in class~\verb+theindex+.  The environment can be
modified with the commonly accepted magic:

\begin{verbatim}
\let\OldTheIndex\the@hevea@index
\let\OldEndTheIndex\endthe@hevea@index
\renewenvironment{the@hevea@index}%
                 {\OldTheIndex ...}%
                 {... \OldEndTheIndex}
\end{verbatim}

\noindent An optional index prolog paragraph gets the
ID~\verb+indexprologue+ such that it can be manipulated with CSS as,
for example:

\begin{verbatim}
p#indexprologue {
  font-size: smaller;
}
\end{verbatim}

\noindent The index entries themselves are formatted using special
\texttt{indexenv}~environments.
Those details do not normally concern users.  However, the number of
columns in the presentation of the index can be controlled by setting
the value of the \texttt{indexcols} counter (default value is two).
And the boolean~\texttt{indexcolseprule} toggles typesetting rules
between index columns (default is false, which means no rules).

\subsection{Terminal Input and Output}

The \verb+\typeout+ command echos its argument on the
terminal, macro parameter \verb+#+\textit{i} are replaced by their values.
The \verb+\typein+ command is not supported.

\section{Line and Page Breaking}

\subsection{Line Breaking}
The advisory line breaking command \verb+\linebreak+
will produce a line break if it has no argument or if its optional
argument is~4.
The \verb+\nolinebreak+ command is a null command.


The \verb+\\+ and \verb+\\*+ commands output a \verb+<BR>+ tag,
except inside arrays where the close the current row.
Their optional argument is ignored.
The \verb+\newline+ command outputs a \verb+<BR>+ tag.

All other line breaking commands, declarations or environments are
silently ignored.

\subsection{Page Breaking}
They are no pages in the physical sense in \html. Thus, all these
commands are ignored.

\section{Lengths, Spaces and Boxes}

\subsection{Length}

All length commands are ignored, things go smoothly when \LaTeX{} syntax is
used (using the \verb+\newlength+, \verb+\setlength+, etc. commands,
which are null macros).
Of course, if lengths are really important to the document, rendering
will be poor.

Note that \TeX{} length syntax is not at all recognised. As a
consequence, writing things like \verb+\textwidth=10cm+ will clobber
the output.
Users can correct such misbehaviour by adopting \LaTeX{} syntax, here
they should write
\verb+\setlength{\textwidth}{10cm}+.


\subsection{Space}
The \verb+\hspace+, \verb+\vspace+ and \verb+\addvspace+ spacing
commands and their starred versions recognise positive explicit length
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
line-break. For other length units, a simple conversion based upon a
12pt font is used.


\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 recognised.
The \verb+\enspace+, \verb+\quad+ and \verb+\qquad+ commands output
one, two and four non-breaking spaces, while the \verb+\smallskip+,
\verb+\medskip+ and \verb+\bigskip+ output one, one, and two line
breaks.

Stretchable lengths do not exist, thus the \verb+\hfill+ and
\verb+\vfill+ macros are undefined.


\subsection{Boxes}

Box contents is typeset in text mode (\emph{i.e.} non-math,
non-display mode).  Both \LaTeX{} boxing commands \verb+\mbox+ and
\verb+\makebox+ exist.  The latter is associated with
class~\verb+makebox+, which is empty by default and can be redefined
by the user.

Similarly, the boxing-with-frame commands \verb+\fbox+ and
\verb+\framebox+ are recognized.  Here both, long and short forms
refer to class~\verb+framebox+, which also can be redefined by the
user.

\smallskip

Boxes can be saved for latter usage by storing them in {\em bins}.
New bins are defined by \verb+\newsavebox{+{\it cmd}\verb+}+.

Then some text can be saved into {\it cmd} by
\verb+\sbox{+{\it cmd}\verb+}{+{\it text}\verb+}+ or
\verb+\begin{lrbox}{+\textit{cmd}\verb+}+ \textit{text} \verb+\end{lrbox}+.
The text is translated to \html{}, as if it was inside a \verb+\mbox+
and the resulting output is stored.
It is retrieved (and outputted) by the command
\verb+\usebox{+{\it cmd}\verb+}+.
The \verb+\savebox+ command reduces to \verb+\sbox+, ignoring its
optional arguments.

\smallskip

No other box-related commands are implemented.


\section{Pictures and Colours}

\subsection{The \texttt{picture} environment and the \texttt{graphics}
Package}

It is possible to have pictures and graphics processed by
\texttt{imagen} (see section~\ref{image:file}).
In the case of the \texttt{picture} environment
it remains users responsibility to explicitly choose
source chunks that will get rendered as images.
In the case of the commands from the \texttt{graphics} package,
this choice is made by \hevea.

For instance consider the following picture:
\begin{verbatim}
\newcounter{cms}
\setlength{\unitlength}{1mm}
\begin{picture}(50,10)
\put(0,7){\makebox(0,0)[b]{cm}}
\multiput(10,7)(10,0){5}{\addtocounter{cms}{1}\makebox(0,0)[b]{\arabic{cms}}}
\multiput(1,0)(1,0){49}{\line(0,1){2.5}}
\multiput(5,0)(10,0){5}{\line(0,1){5}}
\thicklines
\put(0,0){\line(1,0){50}}
\multiput(0,0)(10,0){6}{\line(0,1){5}}
\end{picture}
\end{verbatim}
Users should enclose {\em all} picture elements in a \verb+toimage+
environment (or inside \verb+%BEGIN IMAGE+\ldots{} \verb+%END IMAGE+ %
comments) and insert an \verb+\imageflush+ command, where they want
the image to appear in \html{} output:
\begin{verbatim}
%BEGIN IMAGE
\newcounter{cms}
\setlength{\unitlength}{1mm}
\begin{picture}(50,10)
  ...
\end{picture}
%END IMAGE
%HEVEA\imageflush
\end{verbatim}
This will result in normal processing by \LaTeX{} and image inclusion
by \hevea:

%BEGIN IMAGE
\newcounter{cms}
\setlength{\unitlength}{1mm}
\begin{picture}(50,10)
\put(0,7){\makebox(0,0)[b]{cm}}
\multiput(10,7)(10,0){5}{\addtocounter
  {cms}{1}\makebox(0,0)[b]{\arabic{cms}}}
\multiput(1,0)(1,0){49}{\line(0,1){2.5}}
\multiput(5,0)(10,0){5}{\line(0,1){5}}
\thicklines
\put(0,0){\line(1,0){50}}
\multiput(0,0)(10,0){6}{\line(0,1){5}}
\end{picture}
%END IMAGE
\imageflush

\label{graphics}\index{image inclusion!in Postscript}%
\ttindex{graphics}{package}\ttindex{graphicx}{package}%
All commands from the graphics package are implemented using the
automatic image inclusion feature.
More precisely, the outermost invocations of
the \verb+\includegraphics+, \verb+\scalebox+,
etc. commands are sent to the image \textit{image} file and there will
be one 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)
images by:
\begin{verbatim}
\begin{center}
\scalebox{.5}{\includegraphics{round.ps}}
\scalebox{.75}{\includegraphics{round.ps}}
\includegraphics{round.ps}
\end{center}
\end{verbatim}
Then, issuing the following two commands:
\begin{verbatim}
# hevea doc.tex
# imagen doc
\end{verbatim}
yields \html{} that basically consists in three image links,
the images being generated by \texttt{imagen}.
\ifhevea
\begin{htmlout}
\begin{center}
\scalebox{.5}{\includegraphics{round.ps}}
\scalebox{.75}{\includegraphics{round.ps}}
\includegraphics{round.ps}
\end{center}
\end{htmlout}
\fi
Since the advent of~\texttt{pdflatex},
using \verb+\includegraphics+ to insert bitmap images
(\emph{e.g.} \texttt{.gif} or \texttt{.jpg})
became frequent.
In that case, users are advised \emph{not} to use \hevea{} default
implementation of the \texttt{graphics} package.
Instead, they may use a simple variation of
the technique described in Section~\ref{imgsrc}.


\subsection{The \texttt{color} Package}%
\label{color}\ttindex{color}{package}\label{color:package}%
%BEGIN LATEX
\newcommand{\showcolor}[1]{\texttt{#1}}
%END LATEX
\hevea{} partly implements the \texttt{color} package.
Implemented commands are \verb+\definecolor+, \verb+\color+,
\verb+\colorbox+,
\verb+\textcolor+, \verb+\colorbox+ and~\verb+\fcolorbox+.
Other commands do not exist.
At startup,
colours \showcolor{black}, \showcolor{white},
\showcolor{red}, \showcolor{green}, \showcolor{blue},
\showcolor{cyan}, \showcolor{yellow} and \showcolor{magenta} are
pre-defined.

\comindex{color}\comindex{textcolor}%
Colours are defined by
\verb+\definecolor{+\textit{name}\verb+}{+\textit{model}\verb+}{+\textit{spec}\verb+}+,
where \textit{name} is the color name, \textit{model} is the color
model used, and \textit{spec} is the color specification according to
the given model.
Defined colours are used by the declaration
\verb+\color{+\textit{name}\verb+}+ and by the command
\verb+\textcolor{+\textit{name}\verb+}{+\textit{text}\verb+}+, which
change text color.
Please note that, the \verb+\color+ declaration
accepts color specifications directly
when invoked as
\verb+\color[+\textit{model}\verb+]{+\textit{spec}\verb+}+.
The \verb+\textcolor+ command has a similar feature.


As regards color models, \hevea{} implements the \texttt{rgb},
\texttt{cmyk}, \texttt{hsv} and \texttt{hls} color models.
In those models, color specifications are floating point numbers less
than one.
For instance, here is the definition for the \texttt{red} color:
\begin{verbatim}
\definecolor{red}{rgb}{1, 0, 0}
\end{verbatim}


The \texttt{named} color model is also supported, in this model color
specification are just names\ldots{}
Named colours are the ones of \texttt{dvips}.
\begin{flushleft}
%%BEGIN LATEX
\renewcommand{\textcolor}[3][]{#3}
%%END LATEX
\textcolor[named]{GreenYellow}{GreenYellow},
\textcolor[named]{Yellow}{Yellow},
\textcolor[named]{Goldenrod}{Goldenrod},
\textcolor[named]{Dandelion}{Dandelion},
\textcolor[named]{Apricot}{Apricot},
\textcolor[named]{Peach}{Peach},
\textcolor[named]{Melon}{Melon},
\textcolor[named]{YellowOrange}{YellowOrange},
\textcolor[named]{Orange}{Orange},
\textcolor[named]{BurntOrange}{BurntOrange},
\textcolor[named]{Bittersweet}{Bittersweet},
\textcolor[named]{RedOrange}{RedOrange},
\textcolor[named]{Mahogany}{Mahogany},
\textcolor[named]{Maroon}{Maroon},
\textcolor[named]{BrickRed}{BrickRed},
\textcolor[named]{Red}{Red},
\textcolor[named]{OrangeRed}{OrangeRed},
\textcolor[named]{RubineRed}{RubineRed},
\textcolor[named]{WildStrawberry}{WildStrawberry},
\textcolor[named]{Salmon}{Salmon},
\textcolor[named]{CarnationPink}{CarnationPink},
\textcolor[named]{Magenta}{Magenta},
\textcolor[named]{VioletRed}{VioletRed},
\textcolor[named]{Rhodamine}{Rhodamine},
\textcolor[named]{Mulberry}{Mulberry},
\textcolor[named]{RedViolet}{RedViolet},
\textcolor[named]{Fuchsia}{Fuchsia},
\textcolor[named]{Lavender}{Lavender},
\textcolor[named]{Thistle}{Thistle},
\textcolor[named]{Orchid}{Orchid},
\textcolor[named]{DarkOrchid}{DarkOrchid},
\textcolor[named]{Purple}{Purple},
\textcolor[named]{Plum}{Plum},
\textcolor[named]{Violet}{Violet},
\textcolor[named]{RoyalPurple}{RoyalPurple},
\textcolor[named]{BlueViolet}{BlueViolet},
\textcolor[named]{Periwinkle}{Periwinkle},
\textcolor[named]{CadetBlue}{CadetBlue},
\textcolor[named]{CornflowerBlue}{CornflowerBlue},
\textcolor[named]{MidnightBlue}{MidnightBlue},
\textcolor[named]{NavyBlue}{NavyBlue},
\textcolor[named]{RoyalBlue}{RoyalBlue},
\textcolor[named]{Blue}{Blue},
\textcolor[named]{Cerulean}{Cerulean},
\textcolor[named]{Cyan}{Cyan},
\textcolor[named]{ProcessBlue}{ProcessBlue},
\textcolor[named]{SkyBlue}{SkyBlue},
\textcolor[named]{Turquoise}{Turquoise},
\textcolor[named]{TealBlue}{TealBlue},
\textcolor[named]{Aquamarine}{Aquamarine},
\textcolor[named]{BlueGreen}{BlueGreen},
\textcolor[named]{Emerald}{Emerald},
\textcolor[named]{JungleGreen}{JungleGreen},
\textcolor[named]{SeaGreen}{SeaGreen},
\textcolor[named]{Green}{Green},
\textcolor[named]{ForestGreen}{ForestGreen},
\textcolor[named]{PineGreen}{PineGreen},
\textcolor[named]{LimeGreen}{LimeGreen},
\textcolor[named]{YellowGreen}{YellowGreen},
\textcolor[named]{SpringGreen}{SpringGreen},
\textcolor[named]{OliveGreen}{OliveGreen},
\textcolor[named]{RawSienna}{RawSienna},
\textcolor[named]{Sepia}{Sepia},
\textcolor[named]{Brown}{Brown},
\textcolor[named]{Tan}{Tan},
\textcolor[named]{Gray}{Gray},
\textcolor[named]{Black}{Black},
\textcolor[named]{White}{White}.
\end{flushleft}

There are at least three ways to use colours from the \texttt{named}
 model.
\begin{enumerate}
\item Define a color name for them.
\item Specify the named color model as an optional argument to
 \verb+\color+ and \verb+\textcolor+.
\item Use the names directly
(\hevea{} implements the \texttt{color} package with
the \texttt{usenames} option given).
\end{enumerate}
That is:
\begin{enumerate}
\item
\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}+.
\end{enumerate}
\ifhevea Which yields:
\begin{enumerate}
\item \definecolor{rouge-brique}{named}{BrickRed}
\textcolor{rouge-brique}{Text as a brick}.
\item \textcolor[named]{BrickRed}{Text as another brick}.
\item \textcolor{BrickRed}{Text as another brick}.
\end{enumerate}\fi


\comindex{colorbox}\comindex{fcolorbox}%
\hevea{} also implements the \verb+\colorbox+ and \verb+\fcolorbox+ commands.
\begin{verbatim}
\colorbox{red}{Red background},
\fcolorbox{magenta}{red}{Red background, magenta border}.
\end{verbatim}
\begin{center}
\colorbox{red}{Red background},
\fcolorbox{magenta}{red}{Red background, magenta border}.
\end{center}
Those two commands accept an optional first argument that specifies
the color model, as \verb+\textcolor+ does:
\begin{verbatim}
\fcolorbox[named]{RedOrange}{Apricot}{Apricot background, RedOrange border}.
\end{verbatim}
\begin{center}
\fcolorbox[named]{RedOrange}{Apricot}{Apricot background, RedOrange border}.
\end{center}

Colours should be used carefully. Too many colours
hinders clarity and some of the colours may not be readable on the
document background color.

\subsubsection{The \texttt{bgcolor} environment}
\envdefindex{bgcolor}\label{bgcolor}
With respect to the \LaTeX{} \texttt{color} package, \hevea{} features
an additional
\texttt{bgcolor} environment, for changing the background color of some
subparts of the document.
The \texttt{bgcolor} environment is a displayed environment and it
normally starts a new line.
Simple usage is \verb+\begin{bgcolor}{+\textit{color}\verb+}+\ldots{}
\verb+\end{bgcolor}+, where
\textit{color} is a color defined with \verb+\definecolor+.
Hence the following source yield a paragraph with a red background:
\begin{verbatim}
\begin{bgcolor}{red}
\color{yellow}Yellow letters on a red backgroud
\end{bgcolor}
\end{verbatim}
\begin{htmlonly}
\begin{bgcolor}{red}
\color{yellow}Yellow letters on a red background
\end{bgcolor}
\end{htmlonly}

The \texttt{bgcolor} environment is implemented by one-cell
\verb+table+ element, it takes an
optional argument that is used as an attribute for the inner \verb+td+
element (default value is \verb+style="padding:1em"+).
Advanced users may change the default, for instance as:
\begin{verbatim}
\begin{bgcolor}[style="padding:0"]{yellow}
\color{red}Red letters on a yellow backgroud
\end{bgcolor}
\end{verbatim}
The resulting output will be red letters
on a yellow background and no padding:
\begin{htmlonly}
\begin{bgcolor}[style="padding:0"]{yellow}
\color{red}Red letters on a yellow background, no padding
\end{bgcolor}
\end{htmlonly}


\subsubsection{From High-Level Colours to Low-Level Colours}\label{getcolor}
\index{"@getcolor@\texttt{\char92"@getcolor}|defocc}
\index{"@getstylecolor@\texttt{\char92"@getstylecolor}|defocc}
High-level colours are color names
defined with \verb+\definecolor+.
Low-level colours are \html-style colours.
That is, they are either one of the sixteen conventional colours black,
silver etc., or a RGB hexadecimal color specification of the form
\verb+"#XXXXXX"+.


One changes the high-level \emph{high-color} into a low-level color by
\verb+\@getcolor{+\emph{high-color}\verb+}+.
Low-level colours are appropriate inside \html{} attributes and as
arguments to the \verb+\@fontcolor+ internal macro.
An example of \verb+\@getcolor+ usage can be found at the end of
section~\ref{getcolor:usage}.

There is also \verb+\@getstylecolor+ command that acts
like\verb+\@getcolor+, except that it does not output the double
quotes around RGB hexadecimal color specifications.
Such low-level colours are appropriate for style definitions in
cascading style sheets~\cite{css}. See
Section~\ref{getstylecolor:example} for an example.


\section{Font Selection}

\subsection{Changing the Type Style}\label{type-style}
All \LaTeXe{} declarations and environments for changing type style
are recognised. Aspect is rather like \LaTeXe{} output, but there is
no guarantee.

As \html{} does not provide the same variety of type styles as
\LaTeX{} does.
However \css{} provide a wide variety of font properties.
\hevea{} uses generic properties, proper rendering will then depend
upon user agent.
For instance, it belongs to the user agent
to make a difference between
\textit{italics} (rendered by the font style ``italic'')
and \textsl{slanted} (rendered by the font style ``oblique'').

Here is how \hevea{} implements text-style declarations by default:
\begin{center}
\newcommand{\heveastyle}[2]{{\ifhevea#1\fi#2}}
\begin{tabular}{*{3}{p{.3\linewidth}}}
\begin{tabular}{l@{\quad}l} \hline
\verb+\itshape+ &  \heveastyle{\itshape}{font-style:italic}\\
\verb+\slshape+ &  \heveastyle{\slshape}{font-style:oblique}\\
\verb+\scshape+ &  \heveastyle{\scshape}{font-variant:small-caps}\\
\verb+\upshape+ &  \heveastyle{\upshape}{no style}\\ \hline
\end{tabular}
 &
\begin{tabular}{l@{\quad}l} \hline
\verb+\ttfamily+ & \heveastyle{\ttfamily}{font-family:monospace}\\
\verb+\sffamily+ & \heveastyle{\sffamily}{font-family:sans-serif}\\
\verb+\rmfamily+ &  \heveastyle{\rmfamily}{no style}\\ \hline
\end{tabular}

&
\begin{tabular}{l@{\quad}l} \hline
\verb+\bfseries+ & \heveastyle{\bfseries}{font-weight:bold}\\
\verb+\mdseries+ & \heveastyle{\mdseries}{no style}\\ \hline
\end{tabular}
\end{tabular}
\end{center}


Text-style commands also exists, they are defined as
\verb+\mbox{\+\textit{decl}\ldots\verb+}+. For instance,
\verb+\texttt+ is defined as a command with one argument whose body is
\verb+\mbox{\ttfamily#1}+.
Finally, the \verb+\emph+ command for emphasised text also exists,
it yields text-level \verb+em+ elements.


As in \LaTeX{}, type styles consists in three components:
\emph{shape}, \emph{series} and \emph{family}.
\hevea{} implements the three components by making one declaration to
cancel the effect of other declarations of the same kind.
\begin{htmlonly}
For instance consider the following source, that exhibits shape changes:
\begin{verbatim}
{\itshape italic shape \slshape slanted shape
\scshape small caps shape \upshape upright shape}
\end{verbatim}
Then, in the rendering below, ``small caps shape'' appears in small caps shape
only and not in italics:
\begin{htmlout}
{\itshape italic shape \slshape slanted shape
\scshape small caps shape \upshape upright shape}
\end{htmlout}
\end{htmlonly}


Old style declarations are also recognised, they translate to
text-level elements. However, no elements are cancelled when using
old style declaration. Thus, the source
``\verb+{\sl\sc slanted and small caps}+'' yields ``slanted''
small caps\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 cancellation mechanism. See
section~\ref{customize-style} for a more thorough description.


\subsection{Changing the Type Size}
All declarations, from \verb+\tiny+ to \verb+\Huge+ are recognised.
Output is not satisfactory inside headers elements
generated by sectioning commands.

\subsection{Special Symbols}

The \verb+\symbol{+{\it num}\verb+}+ outputs character number {\it num}
(decimal) from the Unicode character set.
This departs from \LaTeX{}, which output symbol number \textit{num} in
the current font.

\section{Extra Features}\cutname{extras.html}
This section describes \hevea{} functionalities that extends on plain \LaTeX{},
as defined in \cite{latex}.
Most of the features described here are performed by default.

\subsection{\TeX{} macros}\label{texmacro}
Normally, \hevea{} does not recognise constructs that are specific to
\TeX{}.
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{\`A la \TeX{} macros definitions}\label{texmacros}
\comindex{def}\index{command!definition}
The \verb+\def+ construct for defining commands is supported.
It is important to
notice that \hevea{} semantics for \verb+\def+ 
follows \TeX{} semantics.
That is, defining a command that already
exists with \verb+\def+ succeeds.

Delimiting characters in command definition are somehow supported.
Consider the following example from the \TeX{} Book:
\begin{verbatim}
\def\Look{\textsc{Look}}
\def\x{\textsc{x}}
\def\cs AB#1#2C$#3\$ {#3{ab#1}#1 c\x #2}
\cs AB {\Look}{}C${And \$}{look}\$ 5.
\end{verbatim}
It yields:
{\def\Look{\textsc{Look}}
\def\x{\textsc{x}}
\def\cs AB#1#2C$#3\$ {#3{ab#1}#1 c\x #2}
\cs AB {\Look}{}C${And \$}{look}\$ 5.}



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+}+:
\begin{verbatim}
\def\frenchquote(#1){\guillemotleft~\emph{#1}~\guillemotright{} (in French)}
he said \frenchquote(Alors cette accolade ouvrante {``\{''}~?).
\end{verbatim}
Yields:
\begingroup%
\def\frenchquote(#1){\guillemotleft~\emph{#1}~\guillemotright{} (in French)}%
he said \frenchquote(Alors cette accolade ouvrante {``\{''}~?).
\endgroup

Another issue regards comments: ``\%'' in arguments may give undefined
behaviours, while comments are better avoided while defining
macros. As an example, the following code will \emph{not}
be handled properly
by \hevea:
\begin{verbatim}
\def\x%
   #1{y}
\end{verbatim}
Such \TeX{} source should be rewritten as \verb+\def\x#1{y}+.


Another source of incompatibility with \TeX{} is that  substitution of
macros parameters is not performed at the same moment by \hevea{} and
\TeX{}.
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
parse them.
For instance, the following source will give different results in
\LaTeX{} and in \hevea:
\begin{verbatim}
\def\cs#1A{``#1''}
\def\othercs#1{\cs#1A}
\othercs{coucouA}
\end{verbatim}
\LaTeX{} output is ``coucou''A, while \hevea{} output is ``coucouA''.
For instance, here is \ifhevea\hevea\else\LaTeX\fi{} output:
{\def\cs#1A{``#1''}
\def\othercs#1{\cs#1A}
\othercs{coucouA}.}
Please note that in most situations this discrepancy will make
\hevea{} crash. 


\subsubsection{The \texttt{\char92 let} construct}
\comdefindex{let}\hevea{} also processes a
limited version of \verb+\let+:
\begin{flushleft}
\verb+\let+ {\it macro-name1} = {\it macro-name2}
\end{flushleft}
The effect is to bind  {\it macro-name1} to whatever {\it macro-name2}
is bound to at the time \verb+\let+ is processed. This construct may
prove very useful in situations where
one wishes to slightly modify basic commands.
See sections~\ref{customize-let} and~\ref{exlet} for examples of using
\verb+\let+ in such a situation.




\subsubsection{The \texttt{\char92 global} construct}
\comindex{global}
It is possible to escape scope and to make global definitions
and bindings by using the \TeX{} construct \verb+\global+.
The \verb+\global+ construct is significant before
\verb+\def+ and \verb+\let+ constructs.

\comindex{gdef}
Also note that \verb+\gdef+ is equivalent to \verb+\global\def+.


\subsubsection{\TeX{} Conditional Macros}\label{texcond}
\comindex{newif}\comindex{if}\comindex{else}\comindex{fi}
The \verb+\newif\if+\textit{name}, where \textit{name} is made of letters
only, creates three macros:
\verb+\if+\textit{name}, \verb+\+\textit{name}\verb+true+ and
\verb+\+\textit{name}\verb+false+.
The latter two set the \textit{name} condition to \textit{true} and
\textit{false}, respectively.
The \verb+\if+\textit{name} command tests the condition \textit{name}:
\begin{flushleft}
\verb+\if+\textit{name}\\
\textit{text$_1$}\\
\verb+\else+\\
\textit{text$_2$}\\
\verb+\fi+\\
\end{flushleft}
Text \textit{text$_1$} is processed when \textit{name} is
\textit{true}, otherwise \textit{text$_2$} is processed.
If \textit{text$_2$}  is empty, then the \verb+\else+ keyword can be
omitted.

Note that \hevea{} also implements \LaTeX{} \texttt{ifthen} package
and that \TeX{} simple conditional macros are fully compatible with
\LaTeX{} boolean registers. More precisely,
we have the following correspondences:
\begin{center}
\begin{tabular}{p{.3\linewidth}@{\quad}p{.4\linewidth}}
\multicolumn{1}{c}{\TeX} & \multicolumn{1}{c}{\LaTeX}\\[.5em]
\hline
\verb+\newif\if+\textit{name} & \verb+\newboolean{+\textit{name}\verb+}+\\[.5em]
\verb+\+\textit{name}\verb+true+ &
\verb+\setboolean{+\textit{name}\verb+}{true}+\\[.5em]
\verb+\+\textit{name}\verb+false+ &
\verb+\setboolean{+\textit{name}\verb+}{false}+\\[.5em]
\verb+\if+\textit{name} \textit{text$_1$}\verb+\else+
\textit{text$_2$}\verb+\fi+ &
\verb+\ifthenelse{\boolean{+\textit{name}\verb+}}{+\textit{text$_1$}\verb+}{+\textit{text$_2$}\verb+}+\\[.5em]
\end{tabular}
\end{center}

\subsubsection{Other \TeX{} Macros}
\hevea{} implements the macros \verb+\unskip+ and \verb+\endinput+.
It also supports the \verb+\csname+\ldots{} \verb+\endcsname+
construct.


\subsection{Command Definition inside Command Definition}
\index{##n@\texttt{\#\#}\textit{n}}\index{command!definition}
If one strictly follows the \LaTeX{} manual, only commands with no
arguments can be defined inside other commands.
Parameters (\emph{i.e.}\ \verb+#+\textit{n}) occurring inside command bodies
refer to the outer definition, even when they appear in nested
command definitions.
That is, the following source:
\begin{verbatim}
\newcommand{\outercom}[1]{\newcommand{\insidecom}{#1}\insidecom}
\outercom{outer}
\end{verbatim}
yields this output:
\begin{center}
\newcommand{\outercom}[1]{\newcommand{\insidecom}{#1}\insidecom}
\outercom{outer}
\end{center}

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
inner definition.
That is, the source:
\begin{verbatim}
\newcommand{\outercom}[1]{\newcommand{\insidecom}[1]{##1}\insidecom{inner}}
\outercom{outer}
\end{verbatim}
yields this output:
\begin{center}
\newcommand{\outercom}[1]{\newcommand{\insidecom}[1]{##1}\insidecom{inner}}
\outercom{outer}
\end{center}

\subsection{Date and time}
\comindex{today}\ttindex{xxdate.exe}{script}
Date and time support is not enabled by default, for portability and
simplicity reasons.

However, \hevea{} source distribution includes a simple (\texttt{sh})
shell script
\texttt{xxdate.exe} that activates date and time support.
The \texttt{hevea} command, should be invoked as:
\begin{verbatim}
# hevea -exec xxdate.exe ...
\end{verbatim}
This will execute the script \texttt{xxdate.exe}, whose output is then
read by \hevea{}.
As a consequence, standard \LaTeX{} counters \verb+year+,
\verb+month+, \verb+day+  and
\verb+time+  are defined and
\LaTeX{} command \verb+\today+ works properly.
\comindex{heveadate}
Additionally the following counters and commands are defined:
\begin{center}
\begin{tabular}{l@{\quad}p{.5\textwidth}}\hline
Counter \texttt{weekday} & day of week, 0\ldots{}6
\ifhevea(e.g. \theweekday)\fi\\
Counter \texttt{Hour} & hour, 00\ldots{}11
\ifhevea(e.g. \theHour)\fi\\
Counter \texttt{hour} & hour, 00\ldots{}23 \ifhevea(e.g. \thehour)\fi \\
Counter \texttt{minute}  & minute, 00\ldots{}59
\ifhevea(e.g. \theminute)\fi\\
Counter \texttt{second}  & second, 00\ldots{}61\ifhevea\footnote{According to
\texttt{date} man page.}\else{} (According to
\texttt{date} man page!)\fi
\ifhevea(e.g. \thesecond)\fi\\ \hline
Command \verb+\ampm+ & AM or PM
\ifhevea(e.g. \ampm)\fi\\
Command \verb+\timezone+
& Time zone
\ifhevea(e.g. \timezone)\fi\\
Command \verb+\heveadate+ & Output of the \texttt{date} Unix
command\ifhevea, (e.g. \heveadate)\fi\\ \hline
\end{tabular}
\end{center}

Note that I chose to add an extra option (and not an extra
\verb+\@exec+ primitive) for security reasons. You certainly do
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 
a script in a portable manner.

Windows users should enjoy the same features with the version of
\texttt{xxdate.exe} included in the Win32 distribution.   


\subsection{Fancy \label{fancysection}sectioning commands}
\index{color!of section headings}%
\ttindex{fancysection}{package}%
Loading the \texttt{fancysection.hva} file will radically change the
style of sectional units headers: they appear over a green
background, the background color saturation decreases as the sectioning
commands themselves do\ifhevea{} (this is the style of this manual).\else.\fi{}
Additionally, the document background color is white.

\textbf{Note : }Fancy section has been re-implemented using style-sheets. While it respects the old behaviour, users are encouraged to try out style-sheets for more flexibility. See Section~\ref{style:sheets} for details.


The \texttt{fancysection.hva} file is intended to be loaded after
the document base style.
Hence the easiest way to load the \texttt{fancysection.hva} file
is by issuing \verb+\usepackage{fancysection}+ in the document preamble.
To allow processing by \LaTeX, one may for instance create
an empty \texttt{fancysection.sty} file.

As an alternative, to use fancy section style in
\texttt{doc.tex} whose base style is \textit{article}
you should issue the command:
\begin{verbatim}
  # hevea article.hva fancysection.hva doc.tex
\end{verbatim}
You can also make a \texttt{doc.hva} file that contains the two lines:
\begin{verbatim}
  \input{article.hva}
  \input{fancysection.hva}
\end{verbatim}
And then launch \texttt{hevea} as:
\begin{verbatim}
  # hevea doc.hva doc.tex
\end{verbatim}

Sectioning command background colours can be changed by
redefining the corresponding colours (\texttt{part}, \texttt{chapter},
\texttt{section},\ldots).
For instance, you get various mixes of red and orange by:
\begin{verbatim}
\input{article.hva}
\input{fancysection.hva}
\definecolor{part}{named}{BrickRed}
\definecolor{section}{named}{RedOrange}
\definecolor{subsection}{named}{BurntOrange}
\end{verbatim}
(See section~\ref{color:package} for details on the \texttt{named}
color model that is used above.)

\comdefindex{colorsections}
Another choice is issuing the command
\verb+\colorsections{+\textit{hue}\verb+}+, where
\textit{hue} is a hue value to be interpreted in the HSV model.
For instance,
\begin{verbatim}
\input{article.hva}
\input{fancysection.hva}
\colorsections{20}
\end{verbatim}
will yield sectional headers on a red-orange background.

\ttindex{undersection}{package}
\hevea{} distribution features another style for fancy sectioning commands:
the \texttt{undersection} package provides underlined sectional headers.

\subsection{Targeting \label{winfonts}Windows}
\index{display problems!for authors}%
\ttindex{winfonts}{package}
At the time of this release, Windows support for symbols
through Unicode is not as complete as the one of Linux, which I am
using for testing~\hevea{}.

One of the most salient shortcomings is the inability to display sub-elements
for big brackets, braces and parenthesis, which \hevea{} normally
outputs when it processes \verb+\left[+, \verb+\right\}+ etc.

We (hopefully) expect Windows fonts to  display more of
Unicode easily in a foreseeable future. As a temporary fix, we provide
a style file \texttt{winfonts.hva}.
Authors concerned by producing pages that do not look too ugly
when viewed through Windows browsers are thus advised to
load the file \texttt{winfonts.hva}.
For instance they can invoke \hevea{} as:
\begin{verbatim}
# hevea winfonts.hva ...
\end{verbatim}
At the moment, loading \texttt{winfonts.hva}
only changes the rendering
of \LaTeX{} big delimiters, avoiding the troublesome Unicode entities.
\ifhevea
As an example, here are some examples of rendering.
$$
\newcommand{\zyva}[2]
{\mbox{\ttfamily\string\left\string#1\quad\ldots\quad\string\right\string#2} &
\left#1\begin{array}{c}1\\2\\3\end{array}\right#2 &
\input{activatewinfonts.hva}%
\unskip\left#1\begin{array}{c}1\\2\\3\end{array}\right#2}%
\begin{array}{l@{\qquad}c@{\qquad}c}
\hline
\multicolumn{1}{c}{\mbox{delimiters}}&
\multicolumn{1}{c}{\mbox{default}}&
\multicolumn{1}{c}{\mbox{winfonts}}\\ \hline
\zyva\{\} \\
\zyva{[}{]}\\
\zyva()\\
\zyva\vert\vert\\
\zyva\Vert\Vert\\
\hline
\end{array}
$$
\fi

More generally, it remains authors responsibility to be careful not to
issue too refined Unicode entities.  To that aim, authors that target
a wide audience should first limit themselves to the most common
symbols (\emph{e.g.} use \verb+\leq+ [$\leq$]
in place of \verb+\preceq+ [$\preceq$]) and, above all,
they should control the rendering of their documents using several browsers.

\subsection{\textsf{MathJax} \label{mathjax}support}
\ttindex{mathjax}{package}\envdefindex{displayjax}\comdefindex{textjax}%
\ttindex{mathjax.sty}{\LaTeX{} style file}%

\ahref{https://www.mathjax.org/}{\textsf{MathJax}}
support is enabled by loading the
\textsf{mathjax} package. Two operating mode modes are provided:
explicit and automatic. Notice that \hevea{} distribution includes a innocuous
\texttt{mathjax.sty} for \LaTeX{} compatibility --- see also Sec.~\ref{installsty}.

\subsubsection{Explicit mode}
\index{mathjax@\texttt{mathjax} package!displayjax@\texttt{displayjax} environment}%
\ttdefindex{displayjax}{environment}%
\index{mathjax@\texttt{mathjax} package!textjax@\verb+\textjax+}%
\comdefindex{textjax}%
Explicit mode is enabled when \verb+\usepackage{mathjax}+
appears in the document preamble,
or when \hevea{} is invoked as ``\verb+hevea mathjax.hva+\ldots''.

Basic consists in one environment \texttt{displayjax}
and one command~\verb+\textjax+.
The environment is appropriate for displayed maths.
As an example, the following source
\begin{verbatim}
A displayed formula:
\begin{displayjax}
\frac{\pi}{4} = \left[1 - \frac{1}{3} + \frac{1}{5} - \frac{1}{7} +
\frac{1}{9} + \cdots + \frac{(-1)^n}{2n+1} + \cdots \right]
\end{displayjax}
\end{verbatim}
is displayed as follows:
\begin{divstyle}{show}
A displayed formula:
\begin{displayjax}
\frac{\pi}{4} = \left[1 - \frac{1}{3} + \frac{1}{5} - \frac{1}{7} + \frac{1}{9} + \cdots + \frac{(-1)^n}{2n+1} + \cdots \right]
\end{displayjax}
\end{divstyle}

The \verb+\textjax+ command is appropriate for inline mathematical contents.
For instance, the following source
\begin{verbatim}
``A nice inline formula:
\textjax{\frac{\pi}{4} = \left[1 - \frac{1}{3} + \frac{1}{5} - \frac{1}{7} +
\frac{1}{9} + \cdots + \frac{(-1)^n}{2n+1} + \cdots \right]}.''
\end{verbatim}
is typeset as: ``A nice inline formula: \textjax{\frac{\pi}{4} = \left[1 - \frac{1}{3} + \frac{1}{5} - \frac{1}{7} + \frac{1}{9} + \cdots + \frac{(-1)^n}{2n+1} + \cdots \right]}.''

\index{mathjax@\texttt{mathjax} package!mathjax@\texttt{mathjax} environment}%
\ttdefindex{mathjax}{environment}%
Advanced support consists in the \texttt{mathjax} environment. Source code
enclosed in \verb+\begin{mathjax}\ldots\end{mathjax}+ will be
reproduced into output for the \textsf{MathJax} script to handle it.
However, \hevea{} does not start any other action.
Thanks to this feature, users can have any (recognised by \textsf{MathJax})
displayed math environment processed by~\textsf{MathJax}. For instance,
the following source
\begin{verbatim}
\begin{mathjax}
\begin{eqnarray*}
z^2  & = & x^2 + y^2\\
\end{eqnarray*}
\end{mathjax}
\end{verbatim}
will be displayed as:
\begin{divstyle}{show}
\begin{mathjax}
\begin{eqnarray*}
z^2  & = & x^2 + y^2\\
\end{eqnarray*}
\end{mathjax}
\end{divstyle}

\iffalse
\newenvironment{greenjax}
{\divstyle{verbatim}\@print{\[}\mathjax}
{\endmathjax\@print{\]}\enddivstyle}

\begin{greenjax}
\frac{\pi}{4} = \sum_{n=0}^{\infty} \frac{(-1)^n}{2n+1}
\end{greenjax}
\fi

Finally, notice that a document that uses the explicit \textsf{MathJax}
constructs can be processed by \LaTeX, provided
it loads the \texttt{mathjax.sty} file present in \hevea{} distribution.
This can be done simply by having the line \verb+\usepackage{mathjax}+ in
the document preamble. Then, \hevea{} and \LaTeX{} will react appropriately
(see sections~\ref{usepackage:both} and~\ref{usepackage}).

\subsubsection{Automatic mode}
\ttindex{mathjaxauto.hva}{file}%
Automatic mode is enabled when \verb+\usepackage[auto]{mathjax}+
appears in the document preamble,
or when \hevea{} is invoked as ``\verb+hevea mathjaxauto.hva+\ldots''.

In automatic mode, \hevea{} will pass all mathematical text to \textsf{MathJax}.
This mode seems by far the most practical, but beware:
\begin{enumerate}
\item There is no communication back from \textsf{MathJax} to \hevea{}.
As result, equation numbers, as generated for instance by the
\texttt{equation} environment, will not find their way to the final display.
\item Some constructs, such as \verb+\mbox+, are not handled
by~\textsf{MathJax}.
\end{enumerate}

\subsubsection{Customising the \ahref{https://www.mathjax.org/}{\textsf{MathJax}} script}
By default \hevea{} insert a reference to the ``default''
\ahref{https://www.mathjax.org/}{\textsf{MathJax}} script
with ``default'' configuration parameters.
Advanced users can change this setting by redefining the \verb+\jax@meta+
command, which must contain the appropriate \verb+<script>+ element.
See the file \verb+html/mathjax.hva+ for details.

\iffalse
\begin{mathjax}
\begin{eqnarray*}
\textsf{Fib}(0) & = & 1\\
\textsf{Fib}(1) & = & 1\\
\textsf{Fib}(n+2) & = & \textsf{Fib}(n+1) + \textsf{Fib}(n) 
\end{eqnarray*}
\end{mathjax}
\fi

\iffalse
\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
at:
\begin{center}
\ahrefurl{http://www-spi.lip6.fr/\home{queinnec}/VideoC/VideoC.html}.
\end{center}


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
by VideoC. The rest of VideoC constructs are implemented by
the \texttt{.hva} files from VideoC distribution.
\fi

\section{Implemented Packages}\label{implemented:package}
\cutname{manual-packages.html}%
\hevea{} distribution includes \texttt{.hva} packages that are
implementations of \LaTeX{} packages.
Packages described in the ``\emph{Blue Book}'' (\texttt{makeidx},
\texttt{ifthen}, \texttt{graphics} ---and \texttt{graphicx}!---,
\texttt{color}, \texttt{alltt}) are provided.  Additionally, quite a
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, most package options are ignored, except for the babel
package, where it is essential.

\subsection{AMS compatibility}
\ttindex{amsmath}{package}%
\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
environments~\cite[Section~8.4]{latexbis}, the
environments for multi-line displayed
equations (\verb+gather+,
\verb+split+,\ldots)~\cite[Section~8.5]{latexbis} and the
\verb+\numberwithin+ command~\cite[Section~8.6.2]{latexbis}.

\ttindex{amssymb}{package}%
\hevea{} provides support for the \texttt{amssymb} symbols using
Unicode. I found Unicode equivalent for most symbols. However, a few symbols
remain undefined (\emph{e.g.} \verb+\varsubsetneqq+).

\subsection{The \texttt{array} and \texttt{tabularx}
packages}\label{arraypack}
\ttindex{array}{package}\ttindex{tabularx}{package}%
The \ahref{\catalog/array.html}{\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
and a \verb+\newcolumntype+ construct for user-defined  column
specifications.
Table~\ref{arraytable} gives a summary of the new column
specifications and of how \hevea{}
implements them.
\begin{table}
\caption{\label{arraytable} Column specifications from the
\texttt{array} package}
\begin{center}
\begin{tabular*}{.7\linewidth}{l@{\quad}p{.5\linewidth}}\hline
\verb+m{+\textit{width}\verb+}+ &
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
\verb+b{+\textit{width}\verb+}+ &
Equivalent to the \verb+p+ column specification, except that the entries
are bottom-aligned vertically.\\ \hline
\verb+>{+\textit{decl}\verb+}+ &
Can be used before \verb+l+, \verb+c+, \verb+r+,
\verb+p{+\ldots\verb+}+, \verb+m{+\ldots\verb+}+ or
\verb+b{+\ldots\verb+}+.
It inserts \textit{decl} in front of the entries in the corresponding
column. \\ \hline
\verb+<{+\textit{decl}\verb+}+ &
Can be used after \verb+l+, \verb+c+, \verb+r+,
\verb+p{+\ldots\verb+}+, \verb+m{+\ldots\verb+}+ or
\verb+b{+\ldots\verb+}+.
It inserts \textit{decl} after entries in the corresponding
column. \\ \hline
\verb+!{+\textit{decl}\verb+}+ &
Equivalent to \verb+@{+\textit{decl}\verb+}+ \\ \hline
\end{tabular*}
\end{center}
\end{table}

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.
Ordinary column types (\verb+c+, \verb+l+ and \verb+r+)
do not specify vertical alignment, which therefore becomes browser
dependent.

The \verb+>{+\textit{decl}\verb+}+ and \verb+<{+\textit{decl}\verb+}+
constructs permit the encoding of \TeX{} \verb+\cases+ macro as follows:
\begin{verbatim}
\def\cases#1{\left\{\begin{array}{l>{$}l<{$}}#1\end{array}\right.}
\end{verbatim}
(This is an excerpt of the \texttt{latexcommon.hva} file.)

New column specifications are defined by the \verb+\newcolumntype+
construct:
\begin{flushleft}
\quad\verb+\newcolumntype{+\textit{col}\verb+}[+\textit{narg}\verb+]{+\textit{body}\verb+}+
\end{flushleft}
Where \textit{col} is one letter, the optional \textit{narg} is a
number (defaults to \texttt{0}), and \texttt{body} is built up with
valid column specifications and macro-argument references
(\verb+#+\textit{int}).
Examples are:
\begin{verbatim}
\newcolumntype{C}{>{\bf}c}
\newcolumntype{E}[1]{*{#1}{c}}
\begin{tabular}{CE{3}}\hline
one & two & three & four \\
five & six & seven & eight \\ \hline
\end{tabular}
\end{verbatim}
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+}+
stands for \textit{num} centered columns. We get:

\newcolumntype{C}{>{\bf}c}
\newcolumntype{E}[1]{*{#1}{c}}
\begin{tabular}{CE{3}}\hline
one & two & three & four \\
five & six & seven & eight \\ \hline
\end{tabular}

\hevea{} implements column specifications with commands defined in the
\verb+\newcommand+ style. Thus, they have the same behaviour as regards
double definition, which is not performed and induces a warning
message.
Thus, a column specification that is
first defined in a \texttt{macro.hva} specific
file, overrides the document definition.

The \ahref{\catalog/tabularx.html}{\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,
this may seem a crude implementation.  However, rendering is usually
correct, although different.

More generally and from the \html{} point of view such sophisticated
formatting is browser job in the first place.
However, the \html{} definition allows suggested widths or heights for
table entries and table themselves.
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
particular, all length
arguments, either to column specifications or to the arrays
themselves, are ignored). As a consequence, the final, browser viewed,
aspect of arrays will usually be different from their printed
aspect.

\subsection{The \texttt{calc}\label{calc} package}
\ttindex{calc}{package}%
The \ahref{\catalog/calc.html}{\texttt{calc}}
package enables using traditional, infix, notation for
arithmetic operations
inside the \textit{num} argument to the
\verb+\setcounter{+\textit{name}\verb+}{+\textit{num}\verb+}+
and \verb+\addtocounter{+\textit{name}\verb+}{+\textit{num}\verb+}+
constructs (see~\cite[Section~A.4]{latexbis})

The \texttt{calc} package provides a similar extension of the syntax
of the \textit{len} argument to the \verb+\setlength+ and
\verb+\addtolength+ constructs.
\hevea{} does not implement this extension, since it does not
implement length registers in the first place.

\subsection{Specifying \label{inputenc}the document input encoding, the \texttt{inputenc} package}
\ttindex{inputenc}{package}%
The \ahref{\catalog/inputenc.html}{\texttt{inputenc}}
package enables \LaTeX{} to process a file
according to various \emph{8~bits} encodings, plus \texttt{UTF-8}.
The one used encoding is specified as an option while loading the package
\verb+\usepackage[+\textit{encoding}\verb+]{inputenc}+.
At the moment, \hevea{} recognises ten latin encodings
(from \texttt{latin1} to \texttt{latin10}),
the \texttt{koi8-r} encoding,
the \texttt{ascii} encoding,
four windows encodings, the \texttt{applemac} encoding, and the
\texttt{utf8} encoding.
It is important to notice that loading the \verb+inputenc+ package
alters the \html{} document charset.
For instance if the \texttt{latin9} input encoding is selected by:
\begin{verbatim}
\usepackage[latin9]{inputenc}
\end{verbatim}
Then, the document charset is \verb+ISO-8859-15+, which is an
enhanced version of \verb+ISO-8859-1+ with some characters
for \OE, \oe{} and \texteuro.
The rationale behind changing the output document charset at the same
time as changing the input encoding is to allow
non-ascii bytes in the input file to be replicated as
themselves in the output file.

\index{"@def"@charset@\texttt{\char92"@def"@charset}}
However, one can change the document charset (and the output
translator) by using the internal command \verb+\@def@charset+.
For instance, one can specify \texttt{latin1} encoding, while
producing \html{} pages in ascii:
\begin{verbatim}
\usepackage[latin1]{inputenc}
%HEVEA\@def@charset{US-ASCII}
\end{verbatim}
See section~\ref{encodings} for a more thorough description of \html{}
charset management.

\comdefindex{inputencoding}The \texttt{inputenc} package also provides the
command~\verb+\inputcoding{+\textit{encoding}\verb+}+ that
changes the input encoding at any time.
The argument \textit{encoding} can be any of the options accepted
by \verb+\usepackage[+\textit{encoding}\verb+]{inputenc}+.
The command~\verb+\inputcoding+ of \hevea{}
follows the behaviour of its \LaTeX{} counterpart, it the sense
that it obeys scope rules.
Notice that \verb+\inputcoding+ does not change the document output
encoding and charset.

\subsection{The \texttt{hyphenat} package}
Control of hyphenation on the HTML-side is much more limited than on
the \LaTeX-side.  Therefore, the functionality of the ported
\texttt{hyphenat}~package is limited.  The package options~\verb+none+
and \verb+htt+ are ignored.

\subsection{More symbols}
\hevea{} implements the following packages: \texttt{latexsym}
\texttt{amssymb}, \texttt{textcomp} (a.k.a. ``Text companion'')
and \texttt{eurosym} (a nice \texteuro{} symbol in \LaTeX).


\subsection{The \texttt{comment}\label{commentpack} package}
\ttindex{comment}{package}%
The \ahref{\catalog/comment.html}{\texttt{comment}} package provides two commands,
\verb+\excludecomment+ and \verb+\includecomment+, for (re-)defining
new environments that ignore their content or that do nothing. The
comment environment is also defined as an environment of the first
kind.



\subsection{Multiple Indexes with the \texttt{index} and
\texttt{multind}\label{multind} packages}
\ttindex{index}{package}\ttindex{multind}{package}%
\hevea{} supports several simultaneous indexes, following the scheme
of the
\ahref{ftp://tug.ctan.org/pub/tex-archive/help/Catalogue/entries/index.html}{\texttt{index}} package,
which is present in modern \LaTeX{} distributions.
This scheme is backward compatible with the standard indexing scheme
of \LaTeX.

Support is not complete, but the most useful commands are available.
More precisely, \hevea{} knows the following commands:
\begin{description}
\item[{\tt\char92 newindex\{}{\it tag}{\tt \}\{}{\it
ext}{\tt\}\{}{\it ignored}{\tt\}\{}{\it indexname}{\tt\}}]
Declare an index.
The first argument {\it tag} is a tag to select this index in other
commands; {\it ext} is the extension of the index information file
generated by \LaTeX{} (e.g., \texttt{idx}); {\it ignored} is ignored by
\hevea{}; and {\it indexname} is the title of the index.
There also exists a
\verb+\renewindex+ commands that takes the same arguments and that can be
used to redefine previously declared indexes.
\item[{\tt\char92 makeindex}] Perform
\verb+\newindex{default}{idx}{ind}{Index}+.
\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.
The {\it tag} argument defaults to \verb+default+, thereby yielding
standard \LaTeX{} behaviour for the \verb+\index+ command without an
optional argument.
There also exists a stared-variant \verb+\index*+ that Additionally
typesets {\it arg}.
\item[{\tt\char92 printindex[}{\it tag}{\tt]}] Compute, format and
output index whose tag is \textit{tag}. The {\it tag} argument
defaults to \verb+default+.
\end{description}

The \ahref{\catalog/multind.html}{\texttt{multind}} package is
supported to some extend, but \texttt{index} is definitely to be
preferred.

\subsection{``Natural'' bibliographies, the \texttt{natbib} package }
\LaTeX{} \footahref{\catalog/natbib.html}{version of \texttt{natbib}}
is present in modern installations.\ttindex{natbib}{package}

Implementation is quite complete and compatible
with version~8.0 of the \texttt{natbib} package
(with the \texttt{keyval} style command \verb+\setcitestyle+).

Unimplemented features are the sorting and compression of references.
Automatic generation of an index of citations is handled, but
the current implementation probably is quite fragile.

\subsection{Multiple bibliographies}

\subsubsection*{The \texttt{multibib} package}
\ttindex{multibib}{package}\comindex{newcites}
\hevea{} provides a slightly incomplete 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:
\begin{verbatim}
\newcites{suf1, suf2}{Title1, Title2}
\end{verbatim}
Instead, one should perform to calls to the \verb+\newcites+ command:
\begin{verbatim}
\newcites{suf1}{Title1}\newcites{suf2}{Title2}
\end{verbatim}


\subsubsection*{The \texttt{chapterbib} package}
\ttindex{chapterbib}{package}
A basic implementation is provided. At the moment, you can
define one bibliography per included file and no toplevel
bibliography.
\hevea{} implementation of this package recognises the option
\verb+sectionbib+ and provides the command \verb+\sectionbib+
to change the sectioning command introduced by bibliographies.


\subsection{Support for \texttt{babel}}\ttindex{babel}{package}
\subsubsection{Basics\label{sec:babel-basics}}

\hevea{} offers support for the \LaTeX{} package {\tt babel}. When it reads the command

\begin{verbatim}
  \usepackage[LANG-LIST]{babel}
\end{verbatim}

it loads {\tt babel.hva}, and sends it the saved {\tt LANG-LIST}.  The
file {\tt babel.hva} then looks at each language (say {\tt{}x}) in it,
and loads {\tt x.hva}, which offers support for the language {\tt x}.
As in \LaTeX, the last language in the list is selected as default; it
also determines the document's language, this is,
the \verb+lang+~attribute of its \verb+html+~element.  As an example
the command

\begin{verbatim}
\usepackage[english,french,german]{babel}
\end{verbatim}

would load {\tt babel.hva}, then the files {\tt
english.hva, french.hva, german.hva} containing the respective
definitions, and finally activate the definitions in {\tt german.hva}
and sets the current language to german.

\subsubsection{Commands and languages}

The following babel commands for changing and querying the language
work as in \LaTeX:

\begin{enumerate}
\item \verb+\selectlanguage{LANG}+: Change the language
to \verb+LANG+.

\item \verb+\iflanguage{LANG}+: Branch after comparing \verb+LANG+
with current language.

\item \label{it:macro-foreignlanguage}%
\verb+\foreignlanguage{LANG}{TEXT}+: Switch to
language~\verb+LANG+ and then typeset \verb+TEXT+.

\item \label{it:environment-other-language}%
\verb+\begin{OTHER-LANG}+\quad\verb+\end{OTHER-LANG}+: Select
language~\verb+OTHER-LANG+ in an environment.  \hevea{} is frugal --
only those languages are allowed for \verb+OTHER-LANG+ that have been
announced in the \verb+LANG-LIST+; see section~\ref{sec:babel-basics}.

\item \label{it:environment-other-language-star}%
\verb+\begin{OTHER-LANG*}+\quad\verb+\end{OTHER-LANG*}+: Same as above.

\item \verb+\begin{hyphenrules}{LANG}+\quad\verb+\end{hyphenrules}+:
Switch \emph{only} the hyphenation rules to those of \verb+LANG+.

\item \verb+\hyphenrules{LANG}+: Same as above in the form of a macro.
\end{enumerate}

Items~\ref{it:macro-foreignlanguage}, \ref{it:environment-other-language},
and \ref{it:environment-other-language-star} use
CSS~class \verb+foreignlanguage+, which can be defined by the user (it
is not defined by \hevea).

The language specific details are described in the
corresponding \verb+.hva+ file, just as in the \verb+.sty+ file
for \LaTeX. Users need to supply this file for their language, or
modify/check the files if they are already supplied with the
distribution. The list of languages is given below.

\begin{center}\index{babel!languages}
\begin{tabular}{|l|l|l|l|}
\hline
american & austrian & brazil & catalan \\
check & croatian & danish & dutch \\
english & esperanto & finnish & french \\
galician & german & italian & magyar \\
norsk & nynorsk & polish & portuguese \\
romanian & russian & slovak & slovene \\
spanish & swedish & turkish & \\
\hline
\end{tabular}
\end{center}

\subsubsection{Writing \texttt{hva} files}

The languages for which {\tt .hva} files are available with the
distribution are english, french, german, austrian, czech and portuguese. These
may need to be modified as not all accents and hyphenation techniques
are supported.

They can be written/modified as simple \TeX{} files (see the section ~\ref{texmacros} on writing \TeX{} macros for details). As an example, one may also take a look at the file \footahref{../html/french.hva}{french.hva}, which describes the details for french. 

Note how all definitions are \emph{inside} the definition for
\verb+\french@babel+, which is the command that
\verb+\selectlanguage{french}+ would call. Similar commands need to be
provided (\emph{i.e.}\ \verb+\x@babel+ in \verb+\x.hva+ for language
\verb+x+).

Notice that it is wise to write the \verb+\x.hva+ in plain ascii only.
Some definitions may involve specifying Unicode characters, for doing
so, using the \verb+\@print@u+ is recommended (cf. Section~\ref{internal}).
The definition of Unicode characters can be found at
\footahref{http://www.unicode.org/charts/}{http://www.unicode.org/charts/}.
Most language specific Unicode characters can be found in the first
few files.

\subsection{The \label{urlpackage}\texttt{url} package}
\comdefindex{url}\index{hyperlinks}\ttindex{url}{package}%
\LaTeX{} \footahref{\catalog/url.html}{source}.

This package in fact provides a enhanced  \verb+\verb+ command that
can appear inside other command arguments.
This command is named \verb+\url+,
but it can be used for any verbatim text, including DOS-like path
names.
Hence, one can insert urls in one's document without worrying about
\LaTeX{} active characters:
\begin{verbatim}
This is a complicated url: \url{http://foo.com/~user#label%coucou}.
\end{verbatim}
which gets typeset as: ``This is a complicated url: \url{http://foo.com/~user#label%coucou}.''

The main use for the \verb+\url+ command is to specify urls as arguments to
\hevea{} commands for hyperlinks (see section~\ref{hyperlink}):
\begin{verbatim}
\hevea{} home page is
\ahrefurl{\url{http://hevea.inria.fr/}}
\end{verbatim}
It yields: ``\hevea{} home page is
\ahrefurl{\url{http://hevea.inria.fr/}}''.

\comindex{urldef}
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
\verb+\urldef+ command
for defining commands whose body is typeset by using \verb+\url+:
\begin{verbatim}
\urldef{\heveahome}{\url}{http://hevea.inria.fr/}
\end{verbatim}
\urldef{\heveahome}{\url}{http://hevea.inria.fr/}%
Such a source defines the robust command \verb+\heveahome+ as the
intended url.
Hence the following source works as expected:
\begin{verbatim}
Have a look at \footahref{\heveahome}{\hevea{} home page}
\end{verbatim}
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.
Unfortunately, in some situations (e.g, no \verb+%+, no \verb+#+),
it may work in \LaTeX{}. By
contrast, it does not work in \hevea{}. In such situations,
\verb+\urldef+ should be used.

\hevea{} implementation is somehow compatible at the ``programming level''.
Thus, users can define new commands whose argument is understood
verbatim. The \texttt{urlhref.hva} style file
from the distribution
takes advantage of this to define the \verb+\url+ command, so that it both
typesets an url and inserts a link to it.
\begin{htmlonly}
\begin{verbatim}
\input{urlhref.hva}
Have a look at \url{http://hevea.inria.fr/}
\end{verbatim}
\input{urlhref.hva}It yields ``Have a look at \url{http://hevea.inria.fr/}''.
\end{htmlonly}
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
all arguments to \verb+\url+ are urls\ldots

\subsection{Verbatim text: the \texttt{moreverb} and
\texttt{verbatim} packages}
These two packages provide new commands and environments for
processing verbatim text.
I recommend using
\ahref{\catalog/moreverb.html}{\texttt{moreverb}}
rather than~\texttt{verbatim},
since \hevea~implementation is more advanced for the former package.



\subsection{Typesetting \label{listings:package}computer languages: the \texttt{listings} package}
\ttindex{listings}{package}%
I strongly recommend the
\ahref{\catalog/listings.html}{\texttt{listings}} package.
Learning the user interface requires a little effort, but it is worth
it.

\hevea{} features a quite compatible implementation, please refer to
the original package documentation.
Do not hesitate to report discrepancies.
Note that \hevea{} does not produce very compact
\html{} in case you use this package.
This can be cured by
giving \texttt{hevea} the command-line option \cmdopt{-O}
(see~\ref{heveaoptions}).

The \texttt{lstlisting} environment is styled through
an homonymous style class (see \ref{css:change:all} and~\ref{css:change}) and
most \texttt{lstlisting} environments get translated to \verb+div+
elements with the appropriate \verb+\getenvclass{lstlisting}+ class, 
which, by default is \texttt{lstlisting}.
A few points deserve mention:
\begin{enumerate}
\item The definition of default style class \texttt{lstlisting} includes
the important declarations
\verb+font-family:monospace;+ and \verb+white-space:pre;+, which, more or less,
specify non-proportional font and mandatory line breaks.
In case you replace \texttt{lstlisting} by another style class (by
\verb+\setenvclass{lstlisting}{+\textit{another one}\verb+}+), your
alternate definition should probably feature an identical
specification. Otherwise, rendering would be poor, as regards spacing
and line breaks.
\ifhevea
Here is how specific listings are styled.
We first define a new environment to typeset programs written in the C
language, by using the command \verb+\lstnewenvironment+:
\begin{verbatim}
\lstdefinestyle{colors}{keywordstyle={\bf\color{blue}}, commentstyle={\em\color{magenta}}}
\lstnewenvironment{clisting}
  {\setenvclass{lstlisting}{clisting}\lstset{language=C, style=colors}}
  {}
\end{verbatim}
The command
\verb+\lstnewenvironment{+\textit{name}\verb+}{+\textit{starting
code}\verb+}{+\textit{ending code}\verb+}+ is from the
\texttt{listings} package, with similar semantics.
In the starting code above, the fragment
\verb+\setenvclass{lstlisting}{clisting}+ instructs \hevea{} to
use the style class \texttt{clisting} locally (notice that it could just
be another name). The style class \texttt{clisting} is defined in
the document preamble as follows:
\begin{verbatim}
\newstyle{.clisting}{font-family:monospace;white-space:pre;
border-left:solid black;padding-left:2ex;margin-left:2ex;}
\end{verbatim}
Typesetting a C~listing with a black border on the left is then as
simple as:
\begin{verbatim}
\begin{clisting}
/* Compute, guess what! */
int fact(int n) {
  int r = 1 ;
  for ( ; n > 0 ; n--) {
    r *= n ;
  }
  return r ;
}
\end{clisting}
\end{verbatim}
The final result is:
\begingroup%
\lstdefinestyle{colors}{keywordstyle={\bf\color{blue}},
commentstyle={\em\color{magenta}}}%
\lstnewenvironment{clisting}
{\setenvclass{lstlisting}{clisting}\lstset{language=C, style=colors}}
{}
\begin{clisting}
/* Compute, guess what! */
int fact(int n) {
  int r = 1 ;
  for ( ; n > 0 ; n--) {
    r *= n ;
  }
  return r ;
}
\end{clisting}
\endgroup\fi
\item When listings are framed, that is, when  some
\texttt{frame=}\ldots{} or \texttt{background=}\ldots{} keyval
specifications are active, they no longer get translated to \verb+div+
elements.
Instead they get translated to one cell tables whose \verb+td+
and \verb+table+ elements
are styled through style classes \texttt{lstlisting} and
\texttt{lstframe}, respectively. Of course, those two style classes
follow the usual \verb+\setenvclass+/\verb+\getenvclass+ mechanism.
That way, one can for instance center all framed listings by issuing
the following declaration in the document preamble:
\begin{verbatim}
\newstyle{.lstframe}{margin:auto;}
\end{verbatim}
Notice that the default style class \texttt{lstframe} is empty.

\item \comdefindex{lstavoidwhitepre}%
Unfortunately the \verb+white-space:pre;+ style declaration is still a
bit young, and some browsers implement it in rather incomplete
fashion.  This is particularly true as regards text copy-pasted from
browser display.  In case you want to provide your readers with easy
copy-paste of \texttt{listings}, you can, by issuing the command
\verb+\lstavoidwhitepre+ in the document preamble.  Then,
\verb+white-space:pre;+ is not used any longer: spaces get rendered
by non-breaking space entities and line-breaks by \verb+<BR>+ elements,
which significantly increase output size.  However, as a positive
consequence, display remains correct and text copy-pasted from browser
display indeed possesses the line-breaks shown in display.
\end{enumerate}


\subsection{(Non-)Multi page tabular material}
\ttindex{longtable}{package}\ttindex{supertabular}{package}%
\ifhevea\LaTeX{} source
for the
\footahref{\catalog/longtable.html}{\texttt{longtable}}
and 
\footahref{\catalog/supertabular.html}{\texttt{supertabular}}
packages.\fi

Those two packages provide \LaTeX{} users with the
possibility to typeset tabular material over several
pages~\cite[Section~5.4]{latexbis}. Of course, \hevea{}
does not care much about physical pages.
Thus the \texttt{supertabular}
and \texttt{longtable} environments are rendered more or less
as \texttt{tabular} environments inside \texttt{table} environments.

\subsection{Typesetting inference rules: the
\label{mathpartir:package} \aname{mathpartir}{\texttt{mathpartir}} package}
\ttindex{mathpartir}{package}\index{inference rules}%
The \texttt{mathpartir} package, authored by D.~R\'emy, essentially
provides two features:
\begin{enumerate}
\item
An environment \texttt{mathpar} for typesetting a sequence of math formulas in mixed horizontal and vertical mode. The environment selects the best arrangement according to the line width, exactly as paragraph mode does for words.
\item A command \verb+\inferrule+ (and its starred variant) for
typesetting inferences rules.
\end{enumerate}
We give a short description, focussing on \hevea{}-related details.
Users are encouraged to refer to the
\footahref{http://pauillac.inria.fr/\home{remy}/latex/index.html\#tir}{original
documentation} of the package.

In the following, comments on rule typesetting apply to \hevea{} output
and not to \LaTeX{} output.

\subsubsection {The mathpar environment}\index{mathpartir@\texttt{mathpartir} package!mathpar@\texttt{mathpar} environment}

In its \LaTeX{} version, the \texttt{mathpar} environment is a
``paragraph mode for formulas''. It  allows to typeset long list of
formulas putting as many as possible on the same line:
\begin{center}
\begin{tabular}{m{0.40\hsize}m{0.1\hsize}m{0.40\hsize}}
\begin{lstlisting}[basicstyle=\tt]
\begin{mathpar}
A-Formula \and 
Longer-Formula \and 
And \and The-Last-One
\end{mathpar}
\end{lstlisting}
&
\qquad\qquad
&
\begin{mathpar}
A-Formula 
\and
Longer-Formula
\and
And 
\and
The-Last-One
\end{mathpar}
\end{tabular}
\end{center}
In the example above, formulas are separated with \verb+\and+. The
\LaTeX{} implementation also changes the meaning of paragraph breaks
(either explicit as a \verb+\par+ command or implicit as a blank line)
to act as \verb+\and+. It also redefines the command \verb+\\+ as
an explicit line-break in the flow of formulas.
\begin{center}
\begin{tabular}{m{0.40\hsize}m{0.1\hsize}m{0.40\hsize}}
\begin{lstlisting}[basicstyle=\tt]
\begin{mathpar}
\int_0^2 xdx = \frac{3}{2}
\\
\int_0^3 xdx = \frac{5}{2}
\end{mathpar}
\end{lstlisting}
&
\qquad\qquad
&
\begin{mathpar}
\int_0^2 xdx = \frac{3}{2}
\\
\int_0^3 xdx = \frac{5}{2}
\end{mathpar}
\end{tabular}
\end{center}


The \hevea{} version is simplistic:
Formulas are typeset in math display
mode,
\verb+\and+~separators always produce horizontal space, while
\verb+\\+  always produce line-breaks.
However, when prefixed by \verb+\hva+ the meaning of explicit
separators is reversed: that is,
\verb+\hva\and+ produces a line-break, while \verb+\hva\\+
produces horizontal space.
Hence, we can typeset the previous example on two lines:
\begin{center}
\begin{tabular}{m{0.40\hsize}m{0.1\hsize}m{0.40\hsize}}
\begin{lstlisting}[basicstyle=\tt]
\begin{mathpar}
A-Formula \and
Longer-Formula \hva\and 
And \and The-Last-One
\end{mathpar}
\end{lstlisting}
&
\qquad\qquad
&
\begin{mathpar}
A-Formula \and
Longer-Formula \hva\and 
And \and The-Last-One
\end{mathpar}
\end{tabular}
\end{center}
It is to be noticed that the \LaTeX{} version of the package defines
\verb+\hva+ as a no-op, so as to allow explicit instructions given to
\hevea{} not to impact on the automatic typesetting performed by~\LaTeX.

\subsubsection {The inferrule macro}%
\index{mathpartir@\texttt{mathpartir} package!inferrule@\verb+\inferrule+}

The \verb"\inferrule" macro is designed to typeset inference rules. It
should only be used in math mode (or display math mode). It takes
three arguments, the first being optional, specifying the label,
premises, and conclusions respectively. The premises and the
conclusions are both lists of formulas, and are separated by
\verb"\\".
A simple example of its use is 
\begin{verbatim}
\inferrule
  [label]
  {one \\ two \\ three \\ or \\ more \\ premises}
  {and \\ any \\ number \\ of \\ conclusions \\ as \\ well}
\end{verbatim}
which gives the following rendering:
\def \one {\inferrule [label]
  {one \\ two \\ three \\ or \\ more \\ premises}
  {and \\ any \\ number \\ of \\ conclusions \\ as \\ well}
}
$$
\ifhevea \one
\else
\mbox{$$\one$$}
\fi
$$
Again, \hevea{} is simplistic. Where \LaTeX{} performs
actual typesetting, interpreting \verb+\\+ as horizontal or
vertical breaks, \hevea{} always interpret   \verb+\\+ as an
horizontal break. In fact \hevea{} interpret all separators
(\verb+\\+, \verb+\and+) as horizontal breaks, when
they appear in the arguments of the \verb+\inferrule+ command.
Nevertheless prefixing separators with \verb+\hva+ yields vertical
breaks:
\begin{center}
\begin{tabular}{m{0.40\hsize}m{0.1\hsize}m{0.40\hsize}}
\begin{lstlisting}[basicstyle=\tt]{Ocaml}
\inferrule 
   {aa \hva\\ bb}
   {dd \\ ee \\ ff}
\end{lstlisting}
&
\qquad\qquad
&
$\inferrule {aa \hva\\ bb}{dd \\ ee \\ ff}$
\end{tabular}
\end{center}

The color of the horizontal rule that separates the premises and
conclusions can be changed by redefining the command
\verb+\mpr@hhline@color+. This color must be specified as a low-level
color (cf. Section~\ref{getcolor}).


\subsubsection{Options}

By default, lines are centered in inference rules. However, this can be changed either by using \verb"\mprset{flushleft}" or \verb"\mprset{center}", as shown below. 
\begin{center}
\begin{tabular}{m{0.40\hsize}m{0.12\hsize}m{0.40\hsize}}
\begin{lstlisting}[basicstyle=\tt]{Ocaml}
$$\mprset{flushleft}
  \inferrule 
    {a \\ bbb \hva\\ ccc \\ dddd}
    {e \\ ff \hva\\ gg}
$$ 
\end{lstlisting}
&
\qquad\qquad
&
$$\mprset{flushleft} 
\inferrule {a \\ bbb  \hva\\ ccc \\ dddd}{e \\ ff \hva\\ gg}$$
\\
\end{tabular}  
\end{center}

\subsubsection {Derivation trees}%
\index{mathpartir@\texttt{mathpartir} package!derivation trees}
The \texttt{mathpartir} package provides a starred variant
\verb+\inferrule*+. In \LaTeX{}, the boxes
produced by \verb+\inferrule+ and \verb+\inferrule*+ differ as regards
their baseline, the second being well adapted to derivation trees.
All this is irrelevant to \hevea{}, 
but \verb+\inferrule*+ remains of interest because of its interface:
the optional argument to the \verb+\inferrule*+ command is a list of
\textit{key}\texttt{=}\textit{value} pairs in the style of
\texttt{keyval}.
This makes the variant command much more flexible.
$$
\def \val {{\em v}}
\def \arraystretch {1.4}
\begin{tabular}{|>{\tt}c|p{0.7\hsize}|}
\hline
\bf key & \bf Effect for value {\val}
\\\hline\hline
before & Execute {\val} before typesetting the rule.
         Useful for instance to change the maximal width of the rule.
\\\hline
left & Put a label {\val} on the left of the rule
\\\hline
Left & Idem.
\\\hline
right & As \verb"left",  but on the right of the rule.
\\\hline
Right & As \verb"Left", but on  the right of the rule.
\\\hline
lab & Put a label {\val} above the inference rule, in the style
of \verb+\inferrule+.
\\\hline
Lab & Idem.
\\\hline
vdots & Raise the rule by {\val} and insert vertical dots, the length
argument is translated to a number of line-skips.
\\\hline
\end{tabular}
$$
Additionally, the value-less key \verb"center" centers premises and
conclusions (this is
the default), while \verb"flushleft" commands left alignment of
premises and conclusions (as \verb+\mprset{flushleft}+ does).
Other keys defined by the \LaTeX{} package exist and are parsed, but
they perform no operation.

As an example, the code
\begin{lstlisting}[basicstyle=\tt]{Ocaml}
\begin{mathpar}
\inferrule* [Left=Foo]
   {\inferrule* [Right=Bar,width=8em,
                 leftskip=2em,rightskip=2em,vdots=1.5em]
      {a \and a \and bb \hva\\ cc \and dd}
      {ee}
    \and ff \and gg}
   {hh}
\hva\and
\inferrule* [lab=XX]{uu \and vv}{ww}
\end{mathpar}
\end{lstlisting}
produces the following output:
\begin{mathpar}
\inferrule* [Left=Foo]
   {\inferrule* [Right=Bar,width=8em,
                 leftskip=2em,rightskip=2em,vdots=1.5em]
      {a \and a \and bb \hva\\ cc \and dd}
      {ee}
    \and ff \and gg}
   {hh}
\hva\and
\inferrule* [lab=XX]{uu \and vv}{ww}
\end{mathpar}


\subsection{The \texttt{ifpdf} package}
\ttindex{ifpdf}{package}
This package should be present in modern \texttt{latex} installations.
Basically, the package defines a boolean register~\texttt{pdf}, whose
value is true for tools that produce~\textsc{PDF} (such as
\texttt{pdflatex}) and false for tools that produce~\textsc{DVI}
(such as \texttt{latex}).

The hevea version of the package simply defines the boolean
register~\texttt{pdf} with initial value true.  Command-line option
\cmdopt[imagen]{-pdf}  is also added to \texttt{imagen} command-line
options (by using the command~\verb+\@addimagenopt+, see
Section~\ref{imagen-source}).  As a result, \texttt{imagen} will
normally call \texttt{pdflatex} in place of \texttt{latex}.

In case standard \texttt{latex} processing in \texttt{imagen} is
wished, one can issue the command \verb+\pdffalse+ after loading the
\text{ifpdf} package and before \verb+\begin{document}+. Then, no
command line option is added.
Hence, to achieve \texttt{latex} processing of the \textit{image}
file, while still loading the \texttt{ifpdf} package, one writes:
\begin{verbatim}
\usepackage{ifpdf}
%HEVEA\pdffalse
\end{verbatim}

\subsection{Typesetting Thai}
\index{thai@Thai}%
\hevea{} features an implementation of Andrew Seagar's technique
for Thai in \LaTeX{},
by the means of the package \texttt{thai.hva} in the distribution.

As regards input encoding, Thai users of \hevea{} could (perhaps) use
\verb+\usepackage[utf8]{inputenc}+.
However, the typesetting of Thai is more subtle than just proper
characters.  For that reason, Thai in \LaTeX{} is better performed by
another technique, which \hevea{} supports.  See this specific
\footahref{\ifhevea.\else\heveaurl/doc\fi/thaihevea.html}{document}.

\subsection{Hanging paragraphs}
\ttindex{hanging}{package}%
The \texttt{hanging} package is implemented.
\hevea{} implementation consists of no-ops, except for the
\texttt{hangparas} environment, which is partially implemented.
Assume the following usage of \texttt{hangparas}:
\begin{flushleft}
\verb+\begin{hangparas}{+\textit{wd}\verb+}{+\textit{n}\verb+}+
\quad\ldots
\verb+\end{hangparas}+
\end{flushleft}
where \textit{wd} is a length that makes sense both for \LaTeX{}
and CSS (typically \texttt{2ex}).
Then \html{} output will reproduce \LaTeX~output for~$n=1$, regardless
of the given value of argument~$n$.
That is, in any paragraph inside the environment,
all lines except the first get indented by~\textit{wd}.


\subsection{The \texttt{cleveref} package}
\ttindex{cleveref}{package}%
The \ahref{\catalog/cleveref.html}{\texttt{cleveref}} package
attempts (and mostly succeeds) typesetting references
cleverly. Its main feature is a \verb+\cref+ command that accepts several,
comma separated, label references and typesets them as a list
(which can be one-element long, of course) prefixed with sectional unit names.
The \hevea{} implementation is quite complete, but it does not support some
of the subtleties of the \LaTeX{} implementations, especially as regards
customisation.


\subsection{Other packages}
The \texttt{fancyverb} and \texttt{colortbl}
packages are partly implemented.

The \texttt{xspace} package is implemented,
in simple cases, rendering is satisfactory, but beware: \hevea{}
differs significantly from \TeX{}, and discrepancies are likely.

The \texttt{chngcntr} package is implemented.
This package provides commands to connect (and disconnect) counters
once they are created\ifhevea{} (see
\ahrefurl{\url|http://www.tex.ac.uk/cgi-bin/texfaq2html?label=addtoreset|}).\else.\fi

The \texttt{import} package is partially implemented:
all starred commands are missing.

The \texttt{booktabs} package is implemented.
This package provides nicer rulers in tables as specific commands.
\hevea{} defines those as no-ops.




\cutend
\setcounter{section}{0}

\part{\label{practical}Practical information}
\cutdef{section}

\section{Usage}
\subsection{\hevea{} usage}\label{heveausage}
\ttindex{hevea}{command}
The \texttt{hevea} command has two operating modes, normal mode and
filter mode.
Operating mode is determined by the nature of the last command-line
argument.

\subsubsection{Command line arguments}\label{comline}
The \texttt{hevea} command interprets its arguments as names of
files and attempts to process them.
Given an argument \textit{filename} there are two cases:
\begin{itemize}
\item If \textit{filename} is \textit{base}\texttt{.tex} or
\textit{base}\texttt{.hva},
then a single attempt to open \textit{filename} is made.
\item In other cases,
a first attempt to open \textit{filename}\texttt{.tex} is made.
In case of failure, a second attempt to open  \textit{filename} is made.
\end{itemize}
\label{search:path}
In all attempts, implicit filenames are
searched along \texttt{hevea} search path, which consist in:
\begin{enumerate}
\item the current directory ``\texttt{.}'',
\item user-specified directories (with the \texttt{-I} command-line
option),
\item \texttt{hevea} library directory.
\item one of the sub-directories \texttt{html}, \texttt{text} or
\texttt{info} from \texttt{hevea} library directory, depending upon
\texttt{hevea} output format,
\end{enumerate}
\index{"@hevealibdir@\texttt{\char92"@hevealibdir}|defocc}
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.
In all cases, the value of \texttt{hevea} library directory can
be accessed from the processed document as the value of the command
\verb+\@hevealibdir+.



\subsubsection{Normal mode}\label{basenames}
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:
\begin{itemize}
\item The input basename, \textit{basein},
is defined as the main input file name,
with  extension removed when present.
\item The output basename, \textit{baseout}, is  \textit{basein}
with leading directories omitted. However the output basename can be
changed, using the \verb+-o+ option (see \ahrefloc{output:base}{below}).
\end{itemize}
\hevea{} will attempt to load the main input file.
Ancillary files from a previous run of \LaTeX{}
(\emph{i.e.}\ \texttt{.aux}, \texttt{.bll} and \texttt{.idx} files)
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{.html},
while cross-referencing information goes into
\textit{baseout}\texttt{.haux}. Furthemore,
if an \textit{image} file is generated (cf. section~\ref{imagen}), its
name will be \textit{baseout}\texttt{.image.tex}.

Thus, in the simple case where the \texttt{hevea} command is invoked
as:
\begin{verbatim}
# hevea file.tex
\end{verbatim}
The input basename is \texttt{file} and the output basename also is
\texttt{file}. The main input file is searched once along \texttt{hevea}
search path as \texttt{file.tex}.
\html{} output goes into file
\texttt{file.html}, in the current directory.
In the more complicated case where the \texttt{hevea} command is invoked
as:
\begin{verbatim}
# hevea ./dir/file
\end{verbatim}
The input base name is \texttt{./dir/file} and the output basename is
\texttt{file}. The main input file is loaded by first attempting to
open file \texttt{./dir/file.tex}, then file~\texttt{./dir/file}.
\html{} output goes into file \texttt{file.html}, in the current directory.

\aname{output:base}{Finally}, the output base name can be a full path,
but you have to use option~\cmdopt{-o}.
For instance, we consider:
\begin{verbatim}
# hevea -o out/out.html file.tex
\end{verbatim}
Then, \html{} output goes into \texttt{out/out.html} --- notice
that directory \texttt{out} must exist.
Furthermore, \texttt{hevea} output base name is \texttt{out/out}.
This means that \texttt{hevea} generates files
\texttt{out/out.haux}, \texttt{out/out.image.tex} etc.

The \texttt{article.hva}, \texttt{seminar.hva}, \texttt{book.hva} and
\texttt{report.hva}
base style files from \hevea{} library are special.
Only the first base style file is loaded and the
\verb+\documentclass+ command has no effect when a base style file is
already loaded. This feature allows to override the document base style.
Thus, a document \texttt{file.tex} can be translated using the
\textit{article} base style as follows:
\begin{verbatim}
# hevea article.hva file.tex
\end{verbatim}

\subsubsection{Filter mode}
If there is no command-line argument, or if the last command-line
argument has the extension~\texttt{.hva}, then
there is neither input base name nor output base name,
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
isolated \LaTeX{} constructs.
The normal way to translate a full document~\textit{file}\verb+.tex+ being
``\verb+hevea+ \textit{file}\verb+.tex+'' and not
``\verb+hevea < + \textit{file}\verb+.tex > +\textit{file}\verb+.html+''.


\subsubsection{\label{heveaoptions}Options}
The \texttt{hevea} command recognises the following options:
\begin{description}
\item[{\tt -version}] Show \texttt{hevea} version and exit.
\item[{\tt -v}] Verbose flag, can be repeated to increase
verbosity. However, this is mostly for debug.
\item[{\tt -dv}] Add border around some of the block-level
elements issued. Specifically, all \verb+div+ and \verb+p+ are bordered,
while the structure of displayed material is also shown.
\item[{\tt -s}] Suppress warnings.
\item[{\tt -I} {\it dirname}] Add {\it dirname} to the search path.
\item[{\tt -o} {\it name}] Make \textit{name} the output basename.
However, if \textit{name} is \textit{base}\texttt{.html}, then
the output basename is \textit{base}.
Besides, {\tt -o -} makes \hevea{} output to standard output.
\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.
Additionally, images get generated automatically.
\item[{\tt -O}] Optimise \html{} by calling \esponja{} (see
section~\ref{esponjausage}).
\item[{\tt -exec} {\it prog}] Execute file \textit{prog} and read the
output. The file \textit{prog} must have execution permission and is
searched by following the searching rules of~\texttt{hevea}.
\item[{\tt -francais}] Deprecated by \texttt{babel} support. This
option issues a warning message.
\item[{\tt -help}] Print version number and a short help message.
\end{description}

The following options control the {\html} code produced by
\texttt{hevea}. By default, \texttt{hevea} outputs a page encoded in
US-ASCII with most symbols rendered as {\html} or numerical Unicode
entities.
\begin{description}
\item[{\tt -entities}] Render symbols by using entities. This is the default.
\item[{\tt -textsymbols}] Render symbols by English text.
\item[{\tt -moreenties}] Enable the output of some infrequent entities. Use
this option to target browsers with wide entities support.
\item[{\tt -mathml}] Produces MathML output for equations, very
experimental.
\item[{\tt -pedantic}]  Be strict in interpreting \html{}
definition. In particular, this option disable size and color changes inside
\verb+<PRE>+\ldots{} \verb+</PRE>+, which are otherwise performed.
\end{description}

The following options select and control alternative output formats
(see section~\ref{alternative}):
\begin{description}
\item[{\tt -text}] Output plain text. Output file
extension is \texttt{.txt}.
\item[{\tt -info}] Output info format. Output file extension
is \texttt{.info}.
\item[{\tt -w} {\it width}] Set the line width for text or info
output, defaults to~72.
\end{description}

Part~\ref{usermanual} of this document is
a tutorial introduction to \hevea{},
while Part~\ref{referencemanual} is the reference manual of~\hevea.


\subsection{\hacha{} usage}
\ttindex{hacha}{command}
The \texttt{hacha} command interprets its argument
\textit{base}\texttt{.html} as the name of
a \html{} source file to cut into pieces.

It also recognises the following options:
\begin{description}
\item[{\tt -v}] Be a little verbose.
\item[{\tt -o} {\it filename}] Make \hacha{} output go into file
\textit{filename} (defaults  to index.html).
Additionally, if \textit{filename} is a composite filename,
\textit{dir/base}, then all files outputted by \hacha{} will
reside in directory \textit{dir}.
\item[{\tt -tocbis}]
Another style for table of contents:
sub-tables are replicated at the beginning of
every file.
\item[{\tt -tocter}]
Like \texttt{-tocbis} above, except that
sub-tables do not appear in the main table of contents
(see Section~\ref{table:link:style}).
\item[{\tt -no-svg-arrows}] Use GIF arrows for the Previous/Up/Next links,
in place of the default SVG arrows.
\item[{\tt -nolinks}] Do not insert Previous/Up/Next links in
generated pages.
\item[{\tt -hrf}] Output a \textit{base}\texttt{.hrf} file, showing
in which output files are the anchors from the input file gone.
The format of this summary is one
``\textit{anchor}\verb+\t+\textit{file}'' line per anchor.
This information may be needed by other tools.
\item[{\tt -help}] Print version number and a short help message.
\end{description}

\noindent Section~\ref{hacha} of the user manual explains how to
alter \hacha{} default behaviour.

\subsection{\texttt{esponja} usage}\label{esponjausage}
\ttindex{esponja}{command}
The program~\texttt{esponja}
is part of \hevea{} and is designed to optimise \texttt{hevea}
output.
However, \texttt{esponja} can also be used alone to optimise
text-level elements in \html{} files.
Since \texttt{esponja} fails
to operate when it detects incorrect~\html, it can be used as a
partial \html~validator.


\subsubsection{Operating mode}
The program \texttt{esponja} interprets its arguments as names of
files and attempt to process them.
It is important to notice that \texttt{esponja} will \emph{replace} files
by their optimised versions, unless instructed not to do so with
option~\texttt{-n}.

Invoking \texttt{esponja} as
\begin{verbatim}
# esponja foo.html
\end{verbatim}
will alter \texttt{foo.html}.
Of course, if \texttt{esponja} does not succeed in making \texttt{foo.html} any
smaller or if \texttt{esponja} fails, the original \texttt{foo.html}
is left unchanged.
Note that this feature allows to optimise all \html{} files in a given directory
by:
\begin{verbatim}
# esponja *.html
\end{verbatim}



\subsubsection{Options}\label{esponjaoptions}
The command \texttt{esponja} recognises the following options:
\begin{description}
\item[{\tt -v}]Be verbose, can be repeated to increase verbosity.
\item[{\tt -n}]Do not alter input files. Instead, \texttt{esponja}
output for file \textit{input}\texttt{.html} goes to file
\textit{input}\texttt{.esp}. Option \texttt{-n} implies option \texttt{-v}.
\item[{\tt -u}]Output \texttt{esponja} intermediate version of \html.
In most occasions, this amounts to pessimize instead of to optimise.
It may yield challenging input for other \html~optimisers.
\end{description}

\subsection{\texttt{bibhva}\label{bibhva} usage}
The program \texttt{bibhva}
is a simple wrapper, which basically
forces \texttt{bibtex} into accepting a \texttt{.haux} file as input
and producing a \texttt{.hbbl} file as output.
Usage is
\texttt{bibhva }\textit{bibtex-options}\texttt{ }\textit{basename}.


\subsection{\texttt{imagen} usage}\label{imagenusage}
\ttindex{imagen}{command}
The command \texttt{imagen} is a simple shell script that translates
a \LaTeX{} document into many \texttt{.png} images.
The \texttt{imagen} script relies on much software to be installed on
your computer, see Section~\ref{imagen:needs}.

It is a companion program of \hevea{}, which must have been previously run as:
\begin{flushleft}
\texttt{\# hevea}\ldots{} \textit{base}\texttt{.tex}\\
or\\
\texttt{\# hevea}\ldots{} \texttt{-o} \textit{base}\texttt{.html}\ldots\\
\end{flushleft}
In both cases, \textit{base} is \hevea{} output basename.
When told to do so (see section~\ref{imagen})
\hevea{} echoes part of its input into
the \textit{base}\texttt{.image.tex} file.

The \texttt{imagen} script should then be run as:
\begin{flushleft}
\texttt{\# imagen} \textit{base}
\end{flushleft}
The \texttt{imagen} script produces
one \textit{base}\textsl{nnn}\texttt{.png} image file per page in the
\textit{base}\texttt{.image.tex} file.

This is done by first calling \texttt{latex} on
\textit{base}\texttt{.image.tex}, yielding one \texttt{dvi}
file.
Then, \texttt{dvips} translates this file into one single Postscript file that
contains all 
the images, or into one  Postscript file per image,
depending upon your version of \texttt{dvips}.
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{.png} files.

\aname{imagenoptions}{The} \texttt{imagen} script recognises the following options:
\begin{description}
\item[{\tt -mag} {\sl nnnn}] Change the enlarging ratio that is applied
while translating DVI into Postscript.
More precisely,  \texttt{dvips} is run with \texttt{-x}{\sl nnnn}
option.
Default value for this ration is $1414$, this means
that, by default, \texttt{imagen} magnifies \LaTeX{} output by a factor of
$1.414$.
\item[{\tt -extra} {\it command}] Insert {\it command} as an additional
stage in \texttt{imagen} \texttt{ppm} to \texttt{png} 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, several such commands piped together, or
various invocations of the \texttt{convert} command from \textbf{ImageMagick}.
\item[{\tt -quant} {\it number}] Add an extra color quantisation step
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 as a response to a failure in the
image production chain. It can also help in limiting image files size.
\item[{\tt -png}]\index{PNG} Output PNG images. This is the default.
\item[{\tt -gif}]\index{GIF}
Output GIF images in place of PNG images.
GIF image files have a \texttt{.gif} extension.
Note that \texttt{hevea} should have been previously run as
\texttt{hevea gif.hva} \textit{base}\texttt{.tex} (so that the proper
\texttt{.gif} filename
extension is given to image file references from within the \html{}
document).
\item[{\tt -svg}]\index{SVG}
Output SVG images in addition to PNG (or GIF) images.
Note that \texttt{hevea} should have been previously run as
\texttt{hevea svg.hva} \textit{base}\texttt{.tex}.
\item[{\tt -pnm}] Output PPM images. This option mostly serves
debugging purposes. Experimented users can also take advantage
of it for performing additional image transformation or
adopting exotic image formats.
\item[{\tt -t}~{\it arg}] Pass option ``{\tt -t}~{\it arg}'' to
\texttt{dvips}.
For instance, using ``\texttt{-t a3}'' may help when images are
truncated on the right.
\item[{\tt -pdf}]\index{PDF}\index{pdflatex}
Have \texttt{imagen} call \texttt{pdflatex} instead
of~\texttt{latex}.
\end{description}

The first three options enable users to correct some misbehaviours.
For instance, when the document base style is \textit{seminar}, image
orientation may
be wrong and the images are too small. This can be cured by invoking
\texttt{imagen} as:
\begin{flushleft}
\texttt{\# imagen  -extra "pnmflip -ccw" -mag 2000} \textit{base}
\end{flushleft}

Notice that \texttt{hevea} calls \texttt{imagen} by itself,
when given the command-line option \cmdopt{-fix}.
In that situation, the command-line options of \texttt{imagen} can
be controlled from source file by using the
command~\verb+\@addimagenopt+ (see Section~\ref{imagen-source}).

\subsection{Invoking \texttt{hevea}, \texttt{hacha} and \texttt{imagen}}
In this section, we give a few sequence of (Unix) commands to build
the \html{} version of a document in various
situations. The next section gives a few
\texttt{Makefile}'s for similar situations.

We translate a file \texttt{doc.tex}
that requires a specific style file \texttt{doc.hva}.
The file is first translated into \texttt{doc.html} by \texttt{hevea},
which also reads
the specific style file \texttt{doc.hva}.
Then, \texttt{hacha} cuts \texttt{doc.html} into several,
\texttt{doc001.html}, \texttt{doc002.html}, etc. also producing the
table of links file \texttt{index.html}.
\begin{verbatim}
# hevea -fix doc.hva doc.tex
# hacha doc.html
\end{verbatim}
Thanks to the command-line option~\cmdopt{-fix}, \texttt{hevea} runs the
appropriate number of times automatically.
In case \texttt{hevea} produces a non-empty \texttt{doc.image.tex}
file, then \texttt{hevea} calls \texttt{imagen} by itself
(because of option \texttt{-fix}).
Hence, the above sequence of two commands is also appropriate in
that situation.

In case some problem occurs, it is sometime convenient to
run \texttt{imagen} by hand.
It is time \emph{not} to use the option \texttt{-fix}.
\begin{verbatim}
# rm -f doc.image.tex
# hevea doc.hva doc.tex
\end{verbatim}
Now, \texttt{hevea} normally has shown the \texttt{imagen}
command line that it would have run, if it had been given
the option \texttt{-fix}.
For instance, if \texttt{doc.hva} includes \verb+\input{gif.hva}+, then
\texttt{hevea} shows the following warning:
\begin{verbatim}
HeVeA Warning: images may have changed, run 'imagen -gif doc'
\end{verbatim}
Now, one can run \texttt{imagen} as it should be.

It is sometime convenient not to clobber the source directory with
numerous target files.
It suffices to instruct
\texttt{hevea} and~\texttt{hacha} to output files in a
specific directory, say \texttt{doc}.
\begin{verbatim}
# hevea -fix -o doc/doc.html doc.hva doc.tex
# hacha -o doc/index.html doc/doc.html
\end{verbatim}
Notice that \texttt{hevea} does not create the target directory
\texttt{doc}: it must exist before \texttt{hevea} runs.
Again, in case \texttt{hevea} calls \texttt{imagen},
image generation should proceed smoothly and the final files
\texttt{doc001.png}, \texttt{doc002.png}, \ldots{} should go into
directory \texttt{doc}.


In all situations, while installing files to their final destination,
it is important not to forget any relevant files.
In particular, in addition to the root file
(\texttt{index.html}), contents files (\texttt{doc001.html},
\texttt{doc002.html}, etc.) and images
(\texttt{doc001.png}, \texttt{doc002.png}, etc.),
one should not forget the arrow images and the
style sheet generated by \texttt{hacha}
(\texttt{contents\_motif.gif}, \texttt{next\_motif.gif},
\texttt{previous\_motif.gif} and \texttt{doc.css}).

As a consequence, producing all files into the subdirectory
\texttt{doc} may be a good idea, since then one easily install all
relevant files by copying \texttt{doc} to a public destination.
\begin{verbatim}
# cp -r doc $(HOME)/public_html
\end{verbatim}
%$
However, one then also installs the auxiliary files of \texttt{hevea},
and \texttt{hevea} output file \texttt{doc.html}, which is no longer
useful once \texttt{hacha} has run.
Hence, those should be erased beforehand.
\begin{verbatim}
# rm -f doc/doc.h{tml,aux,ind,toc} doc/doc.image.tex
# cp -r doc $(HOME)/public_html
\end{verbatim}
%$


\subsection{Using \label{makefile}\texttt{make}}

Here is a typical \texttt{Makefile}, which is appropriate when
no images are produced.
\begin{verbatim}
HEVEA=hevea
HEVEAOPTS=-fix
HACHA=hacha
#document base name
DOC=doc
index.html: $(DOC).html
        $(HACHA) -o index.html $(DOC).html

$(DOC).html: $(DOC).hva $(DOC).tex
        $(HEVEA) $(HEVEAOPTS) $(DOC).hva $(DOC).tex

clean:
        rm -f $(DOC).html $(DOC).h{toc,aux,ind}
        rm -f index.html $(DOC)[0-9][0-9][0-9].html $(DOC).css
\end{verbatim}
Note that the \texttt{clean} rule removes all the \texttt{doc001.html},
\texttt{doc002.html}, etc. and \texttt{doc.css} files produced by
\texttt{hacha}.
Also note that \texttt{make clean} also removes the
\texttt{doc.haux}, \texttt{doc.hind} and~\texttt{doc.htoc} files, which are \hevea{}
auxiliary files.

When the \textit{image} file feature is used, one can use the
following, extended, \texttt{Makefile}:
\begin{verbatim}
HEVEA=hevea
HEVEAOPTS=-fix
HACHA=hacha
#document base name
DOC=doc
index.html: $(DOC).html
        $(HACHA) -o index.html $(DOC).html

$(DOC).html: $(DOC).hva $(DOC).tex
        $(HEVEA) $(HEVEAOPTS) $(DOC).hva $(DOC).tex

clean:
        rm -f $(DOC).html $(DOC).h{toc,aux,ind}
        rm -f index.html $(DOC)[0-9][0-9][0-9].html $(DOC).css
        rm -f $(DOC).image.* $(DOC)[0-9][0-9][0-9].png *_motif.gif
\end{verbatim}
%$
Observe that the \texttt{clean} rule now also gets rid of
\texttt{doc.image.tex} and of the various files produced by
\texttt{imagen}.

With the following \texttt{Makefile},
\texttt{hevea}, \texttt{imagen}, \texttt{hacha} all output their files into
a specific directory \texttt{DIR}.
\begin{verbatim}
HEVEA=hevea
HEVEAOPTS=-fix
HACHA=hacha
#document base name
DOC=doc
DIR=$(HOME)/public_html/$(DOC)
BASE=$(DIR)/$(DOC)

$(DIR)/index.html: $(BASE).html
        $(HACHA) -tocter -o $(DIR)/index.html $(BASE).html

$(BASE).html: $(DOC).hva $(DOC).tex
        $(HEVEA) $(HEVEAOPTS) $(DOC).hva -o $(BASE).html $(DOC).tex

partialclean:
        rm -f $(BASE).h{tml,aux,toc,ind} $(BASE).image.*

clean:
        rm -f $(DIR)/*
\end{verbatim}
%$
The above \texttt{Makefile} directly produces \html{} and PNG files
into the final directory \verb+$(HOME)/public_html/$(DOC)+.
The new \texttt{partialclean} entry erases files that are not
useful anymore, once \texttt{imagen} and \texttt{hacha} have
performed their tasks.

However, most often, it is more appropriate to build \html{} and PNG files
in a specific directory, and then to copy them to their final
destination.
\begin{verbatim}
   ...

#document base name
DOC=doc
DIR=$(DOC)
BASE=$(DIR)/$(DOC)
INSTALLDIR=$(HOME)/public_html/$(DOC)

  ...

install: partialclean
        cp $(DIR)/* $(INSTALLDIR)
  ...
\end{verbatim}
%$

\section{Browser \label{browser}configuration}\cutname{browser.html}
\index{browser configuration}%
\index{display problems!for viewers}%
By default, \hevea{} does not anymore use the \verb+FACE=symbol+
attribute to the \verb+<FONT ...>+ tag.  As a consequence, browser
configuration is no longer needed.

\urldef{\woods}{\url}{http://www.alanwood.net/unicode/}%
\hevea{} now extensively outputs Unicode entities.
This first means that \hevea{} targets modern browsers with
decent unicode support, and only those.

In case your browser is recent and that you nevertheless experience display
problems on \hevea{}-generated pages, see the excellent
\footahref{\woods}{Alan Wood's Unicode Resources}.
It may help to understand display  problems and even to solve them
by configuring browsers or installing some fonts.

\section{Availability}

\subsection{Internet stuff}

\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}.

\subsection{Law}
\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
Public License (LGPL).
See the \footahref{\ftpbase/LICENSE}{LICENSE} file for details.

The manual itself is distributed under the terms of
the
\ifhevea
\ahref{fddl.html}{Free Document Dissemination Licence}.
\else
\footahref{http://pauillac.inria.fr/\home{lang}/licence/v1/fddl.html}
{Free Document Dissemination Licence}.
\fi

\section{Installation}

\subsection{Requirements}\label{requirements}
The programs \commandname{hevea} and \commandname{hacha} are written in
\footahref{http://caml.inria.fr/ocaml/}{Objective Caml}. Thus, you
really need Objective Caml (the more recent version, the better) to
compile them.
However, some binary distributions exist, which are managed by
people other than me (thanks to them).
Links to some of these distributions appear in \ahref{\heveaurl/}{\hevea{} home page}.

\label{imagen:needs}\hevea{} users may instruct the program not to process a
part of the input (see section~\ref{imagen}). Instead, this part is
processed into a  bitmap file and \hevea{} outputs a  link to the image file.
\LaTeX{} source is changed into \verb+.png+ 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 the \texttt{convert} command from the image processing package
\footahref{http://www.imagemagick.org/}{\textbf{ImageMagick}}.

To benefit from the full functionality of \hevea, you need all
this software. However, \hevea{} runs without them, but then you will
have to produce images by yourself.

\subsection{Principles}
The details are given in the \ahref{\ftpbase/README}{\texttt{README}}
file from the distribution.
Basically, \hevea{} should be given a library
directory. The installation procedure stores the \texttt{hevea.hva}
and base style files in this directory.
There are two compilation modes, the \texttt{opt} mode selects the
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}.
Thus, default compilation mode is \texttt{opt}, however it may be the
case on some systems that only \texttt{ocamlc} is available.


\label{installsty}Note that, when installing \hevea{} from the source distribution, the
\texttt{hevea.sty} (and \texttt{mathjax.sty}) style files are
simply copied to \hevea{} library directory.
It remains users (and package maintainers) responsibility to make those
files accessible to \LaTeX.

\section{Other \LaTeX{} to \html{} translators}
This short section gives pointers to a few other translators. I
performed not extensive testing and make no thorough comparison.

\begin{description}
\item[LaTeX2html]
LaTeX2html is a full system. It is written in perl and
calls \LaTeX{} when in trouble.
As a consequence, LaTeX2html is powerful but it may fail on
large documents, for speed and memory reasons.
More information on LaTeX2html can be found at
\begin{center}
\ahrefurl{http://www.latex2html.org/}
\end{center}

\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
\LaTeX{} source, 
TTH is written in C and the full source is not available
(only \verb+lex+ output is available).
Additionally, TTH  insist on not using any kind of \LaTeX{}
generated information and will show proper cross-reference labels,
even when no \texttt{.aux} file is present.
TTH output is a single document,
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
\begin{center}
\ahrefurl{http://hutchinson.belmont.ma.us/tth/}.
\end{center}

\item[\texttt{TeX4ht}]
TeX4ht is a highly configurable TeX-based authoring system dedicated
mainly to produce hypertext.
It interacts with TeX-based applications through style files
and postprocessors, leaving the processing of the source files
to the native TeX compiler. As a result, TeX4ht may be more powerful
than \hevea{}, but may also be more difficult to configure.
More information on TeX4ht can be found at:
\begin{center}
\ahrefurl{http://www.tug.org/tex4ht/}
\end{center}
\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
of \texttt{htmlgen} and a (bit outdated) discussion on \LaTeX{} to
\html{} translation.
\end{description}

\section{Acknowledgements}
The following people contributed to \hevea{} development:
\begin{itemize}
\item Philip~A.Viton, maintains a
\ahref{http://facweb.knowlton.ohio-state.edu/pviton/support/winport.html}
{Windows (win32) port} of \hevea.
\item Tibault Suzanne authored the HTML~5 generator that now is
the default generator of \hevea.
\item Abhishek Thakur implemented most of the new features of version
1.08, including, translations of symbols to Unicode entities,
the  \texttt{babel} package, and style sheet support.
\item Christian Queinnec wrote an extra lexer to translate code
snippets produced by its tool
\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 \ahref{http://electric.ee.psu.ac.th/\home{andrew}/}{Andrew Seagar}
is at the origin of support for the Thai language. He is
the author of the document \ahref{thaihevea.html}{``How to Use \hevea{}
with the Thai Character Set''}.
\item Pierre Boulet, by using \hevea{} as a stage in his tool
\ahref{http://www.lifl.fr/\home{boulet}/softs/mldoc/index.html}{MlDoc}
for documenting Objective Caml source code, forced me into debugging
\hevea{} implementation of the \verb+alltt+ environment.
\item Nicolas Tessaud implemented the \verb+-text+ and \verb+-info+
output modes (see section~\ref{alternative}).
\item Georges Mariano asked for
many feature, and argued a lot to have them implemented.
\item Many users contributed by sending bug reports.
\end{itemize}

\begin{thebibliography}{xxxxxxxxxx}
\bibitem[\LaTeX-bis]{latexbis}
M.~Gooseens, F.~Mittelbach, A.~Samarin.
\newblock {\em The \LaTeX{} Companion}
\newblock Addison-Websley, 1994.
\bibitem[\LaTeX]{latex}
L. Lamport.
\newblock {\em A Document Preparation System System, \LaTeX{}, User's
Guide and Reference Manual}.
\newblock Addison-Websley, 1994.
\bibitem[htmlgen]{htmlgen}
X. Leroy.
\newblock {\em Lessons learned from the translation of documentation
from \LaTeX{} to {\html}}.
\newblock ERCIM/W4G Int. Workshop on WWW Authoring and Integration
Tools, 1995.
\newblock Available on the web at
\ahrefurl{\url{http://cristal.inria.fr/~xleroy/w4g.html}}

\bibitem[HTML-4.0]{html4}
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.

\bibitem[HTML-5a]{html}
W3C HTML Working groups.
{\em HTML5 A vocabulary and associated APIs for HTML and XHTML}
\ahrefurl{\url{http://dev.w3.org/html5/spec/spec.html}}, 2012.


\bibitem[HTML-5b]{htmlb}
{\em HTML Living Standard}
\ahrefurl{\url{http://www.whatwg.org/specs/web-apps/current-work/multipage/}},
2012.

\bibitem[CSS-2]{css}
Bert Bos,
Tantek \c{C}elik,
Ian Hickson
and
H{\aa}kon Wium Lie.
{\em Cascading Style Sheets, Level~2 Revision~2 Specification}. Available on
the web at
\ahrefurl{\url{http://www.w3.org/TR/REC-CSS2/}}, 2011.
\end{thebibliography}

\printindex
\cutend\cutend
%HEVEA\@stopimage\let\@footnoteflush\@footnoteflush@sticky\@restartimage
\end{document}
