\usepackage{hevea}
\title{\hevea{} User Documentation\\
{\normalsize Version~\heveaversion}}
Chesnay Cedex. {\tt \mailto{Luc.Maranget@inria.fr}}}}
\ifdevrelease
\urldef{\ftpbase}{\url}{ftp://ftp.inria.fr/INRIA/Projects/para/hevea/unstable}
\urldef{\ftpbase}{\url}{ftp://ftp.inria.fr/INRIA/Projects/para/hevea}
\urldef{\httpbase}{\url}{http://pauillac.inria.fr/~maranget/hevea}
\def\locversion{\ifdevrelease\releasedate\else\heveaversion\fi}
\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}.
\hevea{} is a \LaTeX{} to
\hevea{} understands \LaTeX{} macro definitions. Simple user style
Furthermore, \hevea{} customization is done by writing \LaTeX{} code.
\hevea{} is written in Objective Caml, as many lexers. It is
Using \hevea{} it is possible to translate  large documents such
\hevea{} can also be instructed to output plain text or info files.
Information on \hevea{} is available at \ahrefurl{\heveaurl}.
reference manual and some practical information. The latter part
Assume that you have a file, ``\texttt{a.tex}'', written in \LaTeX, using the
is achieved by issuing the command:
# hevea a.tex
\hevea{} does not crash, just ignore them for the moment
If everything goes fine, this will produce a new file,
If you wish to experiment \hevea{} on small \LaTeX{} source fragments,
then launch \hevea{} without arguments. \hevea{} will read its
# hevea
You can find some more elaborate \footahref{\heveaurl/examples/index.html}{examples} in the on-line
The base style of a \LaTeX{} document is the argument to the
Normally, the base style of a document defines the structure and
\noindent\hevea{} really knows about two \LaTeX{} base styles,
Base style \filename{style} is implemented by an \hevea{} specific
style file \filename{style}\verb+.hva+.
More precisely, \hevea{} interprets
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
\verb+hevea mydoc.tex+ will yield an error, since
\hevea{} cannot find the \texttt{acmconf.hva} file:
# hevea.opt mydoc.tex
mydoc.tex:1: Warning: Cannot find file: acmconf.hva
This situation is avoided by invoking \hevea{} with the known
base style file  \texttt{article.hva} as an extra argument:
# hevea article.hva mydoc.tex
The extra argument instructs
\hevea{} to load its \texttt{article.hva}
\filename{article} base styles look the same to the document (i.e., they define
the same macros).
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}).
\filename{style}\verb+.hva+ will not work in general.
\hevea{} will almost surely fail on \TeX-ish input.
Just like \LaTeX{}, \hevea{} reacts to the construct
\textit{file}. (if I got it right, \hevea{} even follows \TeX{} crazy
As it is often the case, assume that the document \texttt{mydoc.tex} has a
\verb+\input{mymacros.tex}+ instruction in its preamble, where
\texttt{mymacros.hva} for instance.
# hevea mymacros.hva mydoc.tex
The file \texttt{mymacros.hva} is processed before
As a consequence of \hevea{} behavior with respect to
the macro definitions in \texttt{mymacros.tex}
Another situation is when  \hevea{} fails to process a whole 
style file. Usually, this means that \hevea{} crashes on that style
The basic idea is then
to write a \texttt{mymacros.hva} style file that contains alternative
Then, \hevea{} should be instructed
to load \texttt{mymacros.hva} and not to load \texttt{mymacros.tex}.
This is done by invoking \texttt{hevea} as follows:
# hevea mymacros.hva -e mymacros.tex mydoc.tex
Of course, \texttt{mymacros.hva} must now contain replacements for
\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}''
When a given package (say  \texttt{zorglob}) is not implemented, the
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}.
space, whereas a single newline is replicated in the output.
However one  blank line  (i.e., two newlines in a row) or more
\index{tabulation}Whether the tabulation character is a space or not 
Paragraphs are rendered by a blank line and there is no paragraph
\hevea{} is a bit simplistic in breaking paragraphs and extra paragraph
however this is not true in math mode, as explained in
\hevea{} tries to emulate \LaTeX{} behavior in all situations, but
here. Consider the following example, where the \verb+\tryspace+
Spacing is a bit chaotic here,
by \LaTeX{} (or \hevea).
\hevea{} math mode is not very far from normal text mode, except that
However, typesetting math formulas in \html{} rises two difficulties.
even simple formulas do not follow the simple basic typesetting model of
feature allows users to instruct \hevea{}
symbols, whereas \verb+\alpha \rightarrow \beta+ produces these spaces.
freely adjust \hevea{} output without changing anything to \LaTeX{}
\hevea{} assumes this choice for the symbol font to be
A browser  correctly displays \hevea{} symbols when
at \localurl{symbol.html} in \hevea{} on-line documentation
by any browser, \hevea{} offers a degraded mode that outputs text
\hevea{} operates in this mode when given the \verb+-nosymb+ flag.
\hevea{} is also given the \verb+-francais+ flag. In that case
\hevea{} handles such constraints in display mode only.
The main two operating modes of \hevea{} are \emph{text} mode and
when in this mode, text items are echoed one following the other and
\texttt{center} or \texttt{quote}) are rendered by \html{} block-level
\html{} block-level elements start a new line.
Conversly, since opening a \html{} block-level elements means starting
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
a one-column table. These tables holds display sub-elements, displays
while the same formula has a better aspect in display mode:
As a consequence, \hevea{} is more powerful in display mode and
This rule is also true in \LaTeX{} but it is more strict in \hevea{},
Users should remember that \hevea{} is not \TeX{} or \LaTeX{} and that
\hevea{} author neither is D.~E.~Knuth nor L.~Lamport.
The reason is that vertical displays in an horizontal display are
that always get centered in the vertical direction.
Users can get an idea on how \hevea{} combines elements in display mode
instructs \hevea{} to add a
By contrast with formulas, which \hevea{} attempts to render with
text-level elements only when they appear inside paragraphs, \LaTeX{} arrays
block-level element \verb+TABLE+, thereby introducing non-desired line
However, since in some sense, all \html{} tables are displayed, the
When \hevea{} thinks it cannot translate a symbol or construct
potential problem. However, rendering may be correct.
In the following (silly) example, \hevea{} gets nervous  because of
Running \hevea{} on this input produces a warning:
# hevea manual.tex
However the final rendering is correct:
When a warning reveals a real problem, it can often be cured by
writing a specific macro. The next two sections introduce \hevea{}
Just like \LaTeX{}, \hevea{} can be seen as a macro language, macros
This scheme favors easy extension of program capabilities
by users. However, predicting program behavior and correcting errors
may occur after several levels of macro expansion.
As a consequence, users can tailor \hevea{} to their needs, but it
Nevertheless, happy \LaTeX{} users should enjoy customizing
\hevea{}, since this is done by writing \LaTeX{} code.
fine control over text placement, whereas
Therefore, there are many situations where \hevea{} just cannot
have to be made. For instance, the calligraphic letters (\verb+\mathcal+)
If you are not satisfied with \hevea{} rendering of text style
macros, using \verb+\renewcommand+, the macro redefinition operator of
\LaTeX{}. The key point is that you need not worry about \hevea{}
declarations (i.e. \verb+\it+, \verb+\sc+, etc.) and everything should
\texttt{hevea.hva} file that \hevea{} loads before processing any
These constructs are written using \LaTeX{} source code, in the end they
invoke \hevea{} internal commands.
\LaTeX{} key constructs or \hevea{} internal commands (see section~\ref{internal}),
in \hevea{} source code.
However, the vast majority of these definitions can be overridden by a
This may prove useless, since there is little point in
the macro-level. That is, most problems induce a macro-related warning
macros. The best place for these macros is an user style file (say
\texttt{trouble.hva}) given as
argument to \hevea.
# hevea trouble.hva trouble.tex
By doing so, the macros written specially for \hevea{} are not
Of course, this will be easier if the \LaTeX{} source is written in a
\subsection{\hevea{} does not know a macro}\label{dontknow}
Since \hevea{} does not know about \verb+\raisebox+,
Then, it goes on by translating the arguments of \verb+\raisebox+ as if
To correct this, you should provide a macro that has more or less the effect of
\verb+\raisebox+ macro for \hevea, because of \html{} limitations.
However, in this case, the effect
ignored in a private \verb+\raisebox+ macro defined in \texttt{trouble.hva}:
Of course, this will work only when all \verb+\raisebox+ commands in
example, where text
Whereas, with the above definition of \verb+\raisebox+, \hevea{} produces:
A solution is to add a new macro definition in the \verb+trouble.hva+ file:
\hevea{} now produces a satisfying output:
This definition can safely be placed anywhere in \texttt{trouble.tex},
since by \hevea{} semantics for \verb+\newcommand+ (see
\subsection{\hevea{} incorrectly interprets a macro}\label{blob}
Sometimes \hevea{} knows about a macro, but the produced \html{}
However, \hevea{} does its best to issue warnings when such situations
\hevea{} always translates \verb+\rule+ as \verb+<HR>+, ignoring size
There is not small square in the symbol font used by \hevea.
However there are other small symbols that would perfectly do the job
\verb+trouble.hva+:
It suffices to have \LaTeX{} typeset some subparts of
the document and then to include them as images, section~\ref{imagen}
\subsection{\hevea{} crashes}
\hevea{} failure may have many causes, including a bug.
However, it may also stem from a wrong \LaTeX{} input.
Such a source will make both \LaTeX{} and \hevea{} choke.
\hevea{} issues the following error message that shows the \LaTeX{}
Thus, when \hevea{} crashes, it is a good idea to check that the
Unfortunately, \hevea{} may crash on input that does not affect
However,  \hevea{} usually translates \LaTeX{} environments  to \html{}
block-level elements and it \emph{requires}
At that point, \hevea{} refuses to generate obviously
of nuisance to \hevea{}.
In this sentence, a group is opened now {\em and never closed.
(\end occurred inside a group at level 1)
By contrast, running \hevea{} on \texttt{horreur.tex} yields a fatal error:
# hevea horreur.tex 
Thus, users should close opening braces where it belongs.
Note that \hevea{} error message ``\texttt{Latex environment
If \hevea{} crashes on \LaTeX{} source (not on \TeX{} source),
then you may have discovered a bug, or this manual is not as complete
\hevea{} version number.
\latexsection{Making \hevea{} and \LaTeX{} both happy}
giving instructions to \hevea{}.
Typically, these instructions are macro definitions and
these instructions should not be seen by \LaTeX{}.
by \hevea{}.
Basically, there are three ways to make input vary according to the
processor, file loading, the \texttt{hevea} package
\hevea{} and \LaTeX{} treat files differently. Here is a summary of the main
  \item \LaTeX{} and \hevea{} both load files given as arguments to
  \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
in the source and to invoke \hevea{} as follows:
\verb+# hevea+ \texttt{-e} \filename{latexonly}\ldots
\label{heveaonly}Having \filename{heveaonly} loaded by \hevea{} only is more
simple: it  suffices to invoke \hevea{} as follows:
\verb+# hevea+ \filename{heveaonly}\ldots
Finally, if one has an \hevea{} equivalent \textit{style}\texttt{.hva}
while \hevea{} loads \textit{style}\texttt{.hva}.
As \hevea{} will not fail in case \textit{style}\texttt{.hva} does not
Writing an \hevea{}-specific file \textit{file}\texttt{.hva}
to \hevea{} only. Users can then be sure that these definitions are
The file \textit{file}\texttt{.hva} can be loaded by either
\textit{file}\texttt{.hva}, or by
definitions from \textit{file}\texttt{.hva} are processed before the
In the \verb+\usepackage+ case, \hevea{} loads \textit{file}\texttt{.hva}
at the place where \LaTeX{} loads \textit{file}\texttt{.sty}, hence
the definitions from \textit{file}\texttt{.hva} replace
\subsection{The \protect\texttt{hevea} package}\label{heveastyle}
The \texttt{hevea.sty} style file is intended to be loaded by \LaTeX{}
and not by \hevea{}.
It provides \LaTeX{} with means to ignore or process some parts of the
Note that \hevea{} copes with the constructs defined in
the \texttt{hevea.sty} file by default.
It is important to notice that the \texttt{hevea.sty} style file from
is not compatible with old \LaTeX{}. Moreover, the \texttt{hevea}
\hevea{} and \LaTeX{} perform the following actions on source inside
environment & \multicolumn{1}{c}{\hevea} &  \multicolumn{1}{c}{\LaTeX}
\hevea{} and left alone by \LaTeX{}:
It is impossible to avoid the spurious space in \hevea{} output
can be achieved
by using the \texttt{hevea} boolean register
or comments, see sections~\ref{heveabool}
However, as an exception, the environments \texttt{image}
It takes a little practice of \hevea{} to understand why this is
\subsubsection{Why are there two environments for ignoring input?}\label{why}
by \hevea{} inside the \texttt{latexonly} environment, in order to
the name of the environment whose opening macro \verb+\+\textit{env}
and may get expanded if it matches a pending
\noindent While there is no \hevea{} output.
Since \hevea{} somehow analyses input that is enclosed in the
However, this environment is intended to select processing by
Fortunately, it remains possible to have input processed by \LaTeX{}
Inside this environment, \hevea{} performs no other action
may only appear in the main flow of text or inside the same macro body,
\subsubsection{The \texttt{hevea} boolean register}\label{heveabool}
\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
{\ifthenelse{\boolean{hevea}}{\purple}{}purple rain, purple rain}\ldots
{\ifthenelse{\boolean{hevea}}{\purple}{}purple rain, purple rain}\ldots
\verb+\ifhevea+ (see Section~\ref{texcond}):
{\ifhevea\purple\fi purple rain, purple rain}\ldots
We get: {\ifhevea\purple\fi purple rain, purple rain}\ldots
\index{comment!hevea@\texttt{\%HEVEA}}
\hevea{} processes all lines that start with \verb+%HEVEA+, while
\LaTeX{} treats these lines as comments.
(Note how comments are placed at the end of some lines to avoid spurious spaces
\texttt{hevea} package. For user convenience, comment equivalents to
Note that \LaTeX{}, by ignoring comments, naturally performs the action
comments. However, no environment is opened and closed and no scope is
\hevea{} just cannot process its input, but it remains acceptable to
have \LaTeX{} process it, to produce a \texttt{.gif} image from
\LaTeX{} output and to include a link to this image into \hevea{}
\hevea{} provides a limited support for doing this.
While outputting \filename{mydoc}\texttt{.html}, \hevea{} echoes some
Additionally, \verb+\usepackage+ commands, top-level and global
output a \verb+<IMG SRC="+\textit{pagename}\verb+.gif">+ tag in \hevea{}
output file, where \textit{pagename} is build from the image counter
and \hevea{} output file name.
Here is the active part of a \texttt{blob.tex} file:
 # hevea blob.tex
\texttt{.gif} images. However, the cost may be prohibitive, text rendering
Note that this technique is used by \hevea{} implementation of the
Included images are easy to manage: it suffices to let \LaTeX{} do the
Then, \hevea{} can have this image translated into a inlined (and
Then, processing \texttt{round.tex} through \hevea{} and
However, the above solution implies modifying the original \LaTeX{}
command, so that \hevea{} echoes  \verb+\epsfbox+ and its argument to
Such a definition must be seen by \hevea{} only. So, it is best put
\hevea{} command line (see section~\ref{heveaonly}).
Observe that the above definition of \verb+\epsfbox+ is a definition
because \hevea{} does not know about \verb+\epsfbox+ by default.
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
Here again, the rule of the game is keeping \hevea{} away from the
normal process: first applying the filter, then making \hevea{} send
Additionally, the image link is put where it belongs by an
The \texttt{gpic} filter is applied first, then come \texttt{hevea}
 # hevea tmp.tex -o smile.html
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).
However, writing in a generic style saves typing.
\hevea{} will process this source correctly, provided it is given its
Assuming that the definition above is in a \ahref{\heveaurl/examples/smile.hva}{smile.hva} file,
\ahref{\heveaurl/examples/smile.tex}{smile.tex} \mbox{now is}:
 # hevea smile.hva tmp.tex -o smile.html
The warnings above are normal: they are issued when \hevea{} runs
\hevea{} outputs a single \texttt{.html} file. This file can be
First generate your {\html} document by applying \hevea{}:
\texttt{\# hevea }\filename{mydoc}\texttt{.tex}
Every item in the table of contents contains a link to or into a file
Additionally, one level of sectioning below the cutting unit (i.e.,
as an entry in the table of contents.
\hevea{} are changed into remote links.
The name of the root  file can be changed using the
Some of \hevea{} output get replicated in all the files generated by
Users can supply a header and a footer, which  will appear at the
begining and end of every page generated by \hacha{}. It suffices to
\quad\verb+\htmlhead{+\textit{header}\verb+}+\\
\hacha{} also makes every page it generates a clone of its input as
\texttt{hevea.sty} style file from the \hevea{} distribution.
An alternative to loading the \texttt{hevea} package is to put
there exist a current cutting sectional unit (cutting unit for short),
Cutting units start a new output file, whereas units comprised between the
entries in the table of contents.
preamble. They command the cutting scheme of the whole document:
\item[{\tt\char92 tocnumber}] Instruct \hevea{} to put section numbers
\item[{\tt\char92 notocnumber}] Instruct \hevea{} \emph{not} to put
in the table of contents.
\verb+\begin{document}+. They all generate \html{} comments in \hevea{}
These comments then act as instructions to {\hacha}.
\comindex{cuthere}
\item[{\tt\char92 cuthere\{}{\it secname}{\tt\}\{}{\it itemtitle}{\tt\}}]
   cutting depth away from it, then an entry is added in the table of
   This entry contains {\em itemtitle} and a link to the point where
   \verb+\cuthere+ appears.
   Result is unspecified if whatever {\em secname} expands to is
All sectioning commands perform \verb+\cuthere+,
that you want to cut at the section level, showing subsections:
No other change is needed, since the macro \verb+section+ already
performs the appropriate \verb+\cuthere{section}{...}+ commands,
\comindex{cuthere}
The \verb+\cuthere+ macro can be used to put some document parts into
Then, you make the abstract go to its own file as it was a cutting
\usepackage{hevea}
\cuthere{\cuttingunit}{Abstract}
source. However, \LaTeX{} still can process the document, since the
\texttt{hevea} package is loaded).
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
an \hevea{} unaware \html{} page by~:
In this document, there is a very
\ifhevea
the title of this page normally is the name of the sectional unit.
\verb+\htmlprefix{\hevea{} Manual: }+ in the document,
``\hevea{} Manual: Cutting your document into pieces with \hacha''
and the title of all other pages would show the same prefix.
\item The arguments
notice that these argument are processed (see section~\ref{urlareprocessed}).
\item When one of the expected argument is left empty,
\hevea{} and \hacha{}.
\subsubsection{Cutting a document anywhere}
the argument \textit{title} is used as the title of the introduced
The \html{} page introduced here does not belong to the normal flow of
\ifhevea The example yields:
However,introducing \html{} hyperlink targets and
\hevea{} output language being \html{}, it is normal for users to insert
\subsection{High-Level Commands}
\hevea{} provides high-level commands for doing this.
Users are advised to use these macros in the first place,
\html{} directly may interfeer in nasty ways with \hevea{} internals.
are provided, all these
commands have approriate equivalents defined by the \texttt{hevea}
package (see section~\ref{heveastyle}).
Hence, a document that relies on these high-level commands
still can be typeset by \LaTeX{}, provided it loads the \texttt{hevea}
\multicolumn{1}{c}{Macro} & \multicolumn{1}{c}{\hevea} &
a more convenient reformulation of the example above is~:
Or even better~:
It may seem complicated, but this is a safe way to have a
document processed both by \LaTeX{} and \hevea{}.
Moreover, \hevea{} (optionnaly) depends on only one third party package:
\verb+\ahref+, \verb+\ahrefurl+ and \verb+\footahref+, thereby
some compatibility with older versions of \hevea.
\hevea{} should be done using the \texttt{color} package (see
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.
There are sixteen predefined colors:
where {\it number} is a six digit hexadecimal number specifying a
file, then a \texttt{doc.tex} document can include it by:
We may very well also have a GIF version of the screenshot image
(or be able to produce one easily using image converting tools),
Then, for \hevea{} to include a link to the GIF image in its
to define the \verb+\epsfbox+ command in the \texttt{macro.hva} file
Then \hevea{} has to be run as:
# hevea macros.hva doc.tex
Since it has its own definition of \verb+\epsfbox+, \hevea{} will
If another naming scheme for image files is prefered, there are
\verb+\includeimage{+\textit{name}\verb+}+, where
\newcommand{\includeimage}[1]{\ifhevea\imgsrc{#1.gif}\else\epsfbox{#1.ps}\fi}
Note that this method uses the \texttt{hevea} boolean register (see
section~\ref{heveabool}).
If one does not wish to load the \texttt{hevea.sty} file,
environment should be used only at toplevel (i.e. not within another
When \hevea{} is given the command line option ``\texttt{-O}'',
checking and optimization of text-level elements in the whole document
\texttt{hevea.sty} style file (see section~\ref{heveastyle}).
In this section a few of \hevea{} internal macros are
Internal macros occur at the final expansion stage of \hevea{} and
their behavior may change from one version of \hevea{} to another and
crashes \hevea.
However:
output (cf. the examples in the next section).
\hevea{} works.
The general principle of \hevea{} is that \LaTeX{} environments
translated into \html{} block-level elements \verb+<+\textit{block}
More specifically, such block level elements are opened by the
get translated into \html{} \emph{groups}, which are shadow block-level
Open \html{} block-level element \textit{BLOCK} with attributes
As a special case \textit{BLOCK} may be the empty string, then a \html{}
Close \html{} block-level element \textit{BLOCK}.
Text-level elements are managed differently. They are not seen
as blocks that must be closed explicitely and they are replaced by the
internal text-level declarations \verb+\@style+, \verb+\@fontsize+ and
\verb+\@fontcolor+. Block-level elements (and \html{} groups)
delimit the effect of such declarations.
\html{} terminology, they are part of the more general class of
text-level elements.
The text-level element {\it SHAPE} will get opened as soon as
enclosing block-level elements get closed.
Enclosed block-level elements are treated properly by closing {\it
The next text-level constructs exhibit similar behavior with respect
to block-level elements.
Declare the text-level element \verb+FONT+ with attribute
be a small integer in the range \texttt{1},\texttt{2}, \ldots{} , \texttt{7}.
Declare the text-level element \verb+FONT+ with attribute
\verb+black+, \verb+silver+ etc, or a RGB hexadecimal color specification
Note that the argument \textit{color} is processed, as a consequence
Close active text-level declarations and ignore further text-level
The effect stops when the enclosing block-level element is closed.
excerpt from the \texttt{hevea.hva} file that
\hevea{} does not feature all text-level elements by default.
However one can easily use them with the internal macro
Then, here is the definition of a simplified \verb+\imgsrc+
because the element \verb+IMG+ consists in a single tag, without a
which \hevea{} uses internaly to output \texttt{A} elements.
tags are emitted inside groups where styles are canceled by using the
of text-level elements.
Finally, here is an example of direct block opening.
its opening command, and closing all these elements in its closing
command. In my opinion, such a style of opening block-level elements
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
as an optional argument. These attributes are the ones of the
\latexsection{Customizing \hevea}
\hevea{} can be controlled by writing \LaTeX{} code. In this section,
we examine how users can change \hevea{} default behavior or add
\texttt{macros.hva}. That is, \hevea{} is invoked as:
# hevea macros.hva mydoc.tex
\texttt{macros.hva}, using internal commands. This requires a good
\texttt{macros.hva}:
The same effect can be achieved without using any of the internal
how to customize \LaTeX{}. However, this is less safe, since the definition of
\verb+\em+ can be changed elsewhere.
\hevea{} default rendering of type style changes is described in
declaration cancels the effect of other active shape declarations.
For instance, in the example, small caps shapes is navy blue and not
\texttt{macros.hva}.
Redefining the old-style \verb+\sc+ is compatible with the cancelation
However, since cancelation is done at the \html{}
level, a declaration belonging to one component may sometimes cancel the
Anyway, you might have not noticed it if I had not told you.
Assume for instance that the base style of \texttt{mydoc.tex} is
For running \hevea{}, the \textit{jsc} style can be replaced by
takes an extra optional argument (which \hevea{} should ignore
However, \hevea{} can process the document as it stands.
One  solution to insert the following lines into \texttt{macros.hva}:
\input{article.hva}% Force document class ``article''
The effect is to replace \verb+\title+ by a new command which
calls \hevea{} \verb+\title+ with the appropriate argument.
\hevea{} fully implements \LaTeXe{} \verb+\newcommand+.
has the same interface as the \LaTeX{} command and
To do this, the \hevea{} \verb+\epsfbox+ command has to check
This can be achieved as follows~:
\ifthenelse{\equal{#1}{!*!}}
{\@imageflush\stepcounter{image}\imgsrc[#1]{\jobname\theimage\heveaimageext}}
\hevea{} provides direct support for the alternative PNG image file
It suffices to invoke \texttt{hevea} as:
\texttt{\#~hevea~png.hva}~\textit{mydoc.tex}
\html. There are two such formats: plain text and info files.
To translate into text, invoke \hevea{} as follow:
# hevea -text [-w <width>] myfile.tex
Then, \hevea{} produces \texttt{myfiles.txt} a plain text translation
Nearly every environments have been translated, included lists and tables.
The support is nearly the same as in \html, excepted in some cases
described hereafter.
possible to render them in plain text. Thus, there are no italics,
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{}.
The only way to correct this (apart from changing the tables
results with in-text mathematical formulas.
Please note that \hevea{} translates plain \LaTeX{} to info, and not
# hevea -info [-w <width>] myfile.tex
Then, \hevea{} produces the file \texttt{myfile.info}, an info
However, if the resulting  file is too large, it is cut into pieces
The optional argument \verb+-w+ has the same meaning as for text output.
the pattern of \LaTeX{} sectioning
References, indexes and footnotes are supported, as they are in
However, the info format only allows pointers to info nodes,
i.e., in \hevea{} case, to sectional units.
As a consequence all cross references lead to sectional unit headers.
\renewcommand{\thesection}{\thepart.\arabic{section}}
This part follows the pattern of the \LaTeX{} reference
Usually, \hevea{} ignore such comments. However, \hevea{} processes
and some other comments have a specific meaning to it (see
\verb+~+, \verb+_+ and \verb+^+, they either are
(and this is the case of many of \hevea{} internal commands), or
However, \hevea{} does its best to read arguments even when they are
\hevea{} has been improved as regards emulation of complicated
\hevea{} correctly processes the following source:
\verb+\textbf+ and \hevea{} succeeds in fetching the argument
The above example arguably is no ``legal'' \LaTeX{},
but \hevea{} handles it.
Of course, there remains
numerous ``clever'' \LaTeX{} tricks that exploits \TeX{} internal
behavior, which \hevea{} does not handle.
the rest of the text alone. While \hevea{} typesets everything using
bold font. Here is \ifhevea\hevea\else\LaTeX\fi{} output:
Note that, in most similar situations, \hevea{} will likely crash.
Fragile commands are not relevant to \hevea{} and \verb+\protect+ is
Scope rules are the same as in \LaTeX.
I am a bit lost here. However spaces in the output should correspond
to users expectations. Note that, to \hevea{} being
The \verb+\\+ and \verb+\\*+ commands are the same, they perform a
line break, except inside arrays where they end the current row.
The \emph{preamble} starts as soon as \hevea{} starts to operate and
However, the preamble is processed
arguments to \hevea{}, see section~\ref{comline}).
\comindex{htmlhead}
In particular one can define a \emph{header} and a \emph{footer}, by using the
\verb+\htmlhead+ and \verb+\htmlfoot+ commands in the preamble.
Those commands register their argument as the header and the footer of
the final \html{} document. The header appears first while the footer
This is mostly useful when \hevea{} output is later cut into pieces by
\hacha{}, since both header and footer are replicated
For instance, to append a copyright notice at the end of all the \html{}
The \verb+\htmlhead+ command cannot be used for changing anything outside of
the \html{} document body, there are specific commands for doing this.
change \hevea{} default (empty) atribute for
However this is no longer true in math mode, see
Paragraphs are not indented. Thus the macros \verb+\indent+ and
at every chapter end in the \filename{book} style.
When there exists an equivalent to a given \LaTeX{} symbol, using
the iso-latin1 and symbol character sets, then \hevea{}
\html{} pages that show these character sets can be found
in the directory \texttt{\heveaurl/doc/}
Otherwise, \hevea{} usually issues a warning to draw user attention.
Otherwise, the argument to the command is not modified (no warning here).
However, it is more simple to write the document using iso-latin1.
\LaTeX{} can process such documents by loading the package
They accept an optional argument and have starred versions.
\verb+\subsubsection+ show section numbers in sectional unit headings,
provided their \textit{level} is greater than or equal to the current
Sectional unit levels and the default value of the \verb+secnumdepth+ counter
are the same as in \LaTeX{}.
counter {\it secname} exists and the appearance of sectional units
\renewcommand{\thechapter}{\Alph{chapter}}
When jumping to anchors, browsers put the targeted line on top
section title (and I do not know the reason why).
\hevea{} now generates a table of contents, using a procedure similar
One inserts this table of contents in the main document by issuing
By default, the table of contents shows sectionning units down to the
subsubsection level in \textit{article} style and down to the subsection level
One can also add extra entries in the table of contents by using
However, hyperlinks need to be introduced explicitely,
as in the following example, where
There is no list of figures nor list of tables.
However, \hevea{} has a more sophisticated way of producing
A later run of {\hacha} on \hevea{} output file splits it
entries in these tables of contents.
commands or their argument when there is no optional
\filename{style}\texttt{.hva} file (see~\ref{comline} to see where \hevea{}
Presently, only the style files \texttt{article.hva}, \texttt{seminar.hva},
\texttt{book.hva} and \texttt{report.hva} exist, the latter two
giving one of the four recognized style files of \hevea{} as command
line arguments (see section~\ref{otherbase}).
Conversely, if \hevea{} attempt to load \filename{style}\texttt{.hva}
fails, then a fatal error is flagged, since it can be sure
\hevea{} reacts to
\item \hevea{} attempt to load file \textit{pkg}\texttt{.hva},
(see section~\ref{search:path} on where \hevea{} searches for files).
Note that \hevea{} will not fail if it cannot load
\textit{pkg}\texttt{.hva} and that no warning is issued in that case.
The \hevea{} distribution contains implementations of some packages,
In some situations it may not hurt at all if \hevea{} does not
implement a package, for instance \hevea{} does not provide an
implementation for the packages \texttt{isolatin1} or
to appear in \html{} document header.
  \item When not present the date is left empty. The \verb+\today+
command generates will work properly only if \texttt{hevea} is invoked
Displayed-paragraph environments translate to block-level
In addition to the environments described in this section,
\hevea{} implements the \verb+center+, \verb+flushleft+ and
\hevea{} also implements the corespondant \TeX{} style declaration
but these declarations may not work as expected, when they do not
The \verb+quote+ and \verb+quotation+ environments are the same thing: they
As a consequence, no control is allowed on the appearances of these
However, customized lists can be produced by using the
The first argument {\it default\_label} is the label generated by an
In practice, the following declarations are relevant:
by every \verb+\item+ command with no argument, before it does
\verb+\makelabel{+{\it label}\verb+}+, where {\it label} is the item
\section{Mathematical Formulas}
Furthermore, \verb+\ensuremath+ behaves as expected.
Math mode is not as powerful in \hevea{} as in \LaTeX{}.  The
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
For instance compare how \hevea{} renders
\hevea{} admits, subscript (\verb+_+), superscripts (\verb+^+) and
The best effect is obtained in display mode, where \html{}
By contrast, when not in display mode, \hevea{} uses only
\verb+SUB+ and \verb+SUP+ text-level elements to render superscrits
However,
and \verb+SUP+ text-level elements and their appearance should be correct
even in in-text formulas.
ordinary characters and get echoed to the output. However, a warning
\verb+\cdots+, \verb+\vdots+ and \verb+\ddots+). The effect may be
strange for the latter two.
\subsection{Mathematical symbols}
Then, users can choose their own replacement for these symbols.
These personal definitions are best placed in an ad-hoc style file,
given as a command line argument to \hevea{}.
For instance, \hevea{} cannot render the \verb+\leadsto+ symbol, but it
When given the \verb+-nosymb+ option, \hevea{} silently replaces
These equivalents are English words by default, or French words when the
subscripts and superscripts are put where they should in display mode.
In text mode, these macros call the \verb+\textstackrel+,
These macros perform the following default actions, which can be
\verb+U+ text-level element.
However, the distribution includes a \texttt{mathaccents.hva} file
except \verb+\check+ and \verb+\breve+.
More precisely, the accent is put (too far) above the symbol in display mode,
\ifhevea{\input{mathaccents.hva}For instance, given the formula
one should not load the \texttt{mathaccents.hva} file and write
\ifhevea With such definitions the previous example now appears as:
closer to universally understood  notations for mathematics.
changed. The appearance of
\verb+\textstyle+ do nothing when \hevea{} is already in the requested
This is so because \hevea{} implements displayed maths as tables,
\hevea{} understands command definitions given in \LaTeX{} style. Such
These three constructs accept the same arguments and have the same
However, \hevea{} is more tolerant: if command
{\it name} already exists, then a subsequent \verb+\newcommand{+{\it
name}.  In both cases, \LaTeX{} would crash, \hevea{} just issues
specific style file given as an argument to \hevea{} (see section~\ref{heveaonly}).
Conversely, changes of base macros (i.e., the ones that \hevea{}
It is worth noticing that \hevea{} also partly implements \TeX{} definitions
\hevea{} accepts environment definitions and redefinitions
\renewcommand{\thesection}{\alph{section}}
this style will clobber the output. However, \hevea{} implements
As a consequence, \hevea{} accepts the following example from the
    {\ifthenelse{\value{ca}>\value{cb}}%
    {\ifthenelse{\value{ca}>\value{cb}}%
Additionally, a few boolean registers are defined by \hevea{}.
Some of them are of interest to users.
\item[\texttt{hevea}] Initial value is \texttt{true}.
The \texttt{hevea.sty} style file also defines this register with
\item[\texttt{mmode}] This register value reflects \hevea{} operating
\item[\texttt{display}]  This register value reflects \hevea{} operating
command line option internally (see Section~\ref{heveaoptions}).
When set false, \hevea{} does not insert its footer ``\emph{This
document has been translated by \hevea}''.
Finally, note that \hevea{} also recognized à la \TeX{} conditional
the case in \LaTeX.
Figures and tables are put where they appear in source, regardless of
They are outputed  inside a \verb+BLOCKQUOTE+ element and they are
However captions are not moved at end of figures: instead, they appear
where the \verb+\caption+ commands occur in source code.
All other tabbing commands do not even exist.
These environments are supported, using \html{}
some of the array items always are typeset in display mode.
Whether an array item is typeset in display mode or not depends upon
They will get top-aligned in the vertical direction if there are
top-aligned in the vertical direction
This is the only occasion where
\hevea{} makes a distinction between LR-mode and paragraph mode.
\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
By default, \hevea{} implements the \texttt{array} package
\hevea{} uses some of the ancillary files generated by \LaTeX.
If this file is present, \hevea{} reads it and put such numbers (or
file is not present, or if the \texttt{hevea} command is given the
``\texttt{-fix}'' option, \hevea{} will instead use \texttt{.haux}
\item[\protect\texttt{.haux}] Such files are \hevea{} equivalents of
\texttt{.aux} files. Indeed, they are simplified \texttt{.aux} files.
As a consequence, two runs of \hevea{} might be needed to get cross
\hevea{} computes its own indexes, using \texttt{.hidx} files for
Again, several runs of \hevea{} might be needed to get indexes right.
\noindent\hevea{} does not fail when it cannot find an auxiliary file.
When another run of \hevea{} is needed, a warning is issued,
and it is user's responsability to rerun \hevea{}.
However, using the convenient \texttt{-fix} command line option is
provided makes \hevea{} rerun itself.
The \LaTeX{} \verb+\label+ and \verb+\ref+ are changed by \hevea{}
Spaces in the arguments to these commands are better avoided.
\item If there exists a file 
(For \hevea{} needs, one run is probably sufficient).
\item If no \filename{mydoc}\texttt{.aux} file exists, then \hevea{}
\hevea{} will output a
new \filename{mydoc}\texttt{.haux} file at the end of its processing.
Hence, in that case, \hevea{} may need to run twice to get
\hevea{} issues a warning then the cross-referencing information it
present, then cross-references will apparently be wrong. However the
Note that these labels are put there by \LaTeX{} in the first case,
and by \hevea{} in the second case, when they process the
have been generated before, using the appropriate combination of
exactly the same operation of searching (and then processing) a file,
See section~\ref{comline} on how \hevea{} searches files.
However, in the case of the \verb+\include+ command, the file is
option (see section~\ref{heveaoptions}),
then \hevea{} does not attempt to load \textit{filename}.
\item \hevea{} does not fails when it cannot find
number of columns by setting the value of the \texttt{indexcols} counter.
As with \LaTeX{}, two runs of \hevea{} are normally needed to format
However, if all index producing commands (normally \verb+\index+)
The advisory line breaking command \verb+\linebreak+
except inside arrays where the close the current row.
They are no pages in the physical sense in \html. Thus, all these
Users can correct such misbehavior by adopting \LaTeX{} syntax, here
Basically, the value of \verb+1em+ or \verb+1ex+ is one space or one
\hevea{} cannot interpret more complicated length arguments
In these situations, a warning is issued and no output is done.
However  \verb+\makebox+ generates a specific warning, since \hevea{}
It is retrieved (and outputed) by the command
It is possible to have pictures and graphics processed by
In the case of the \texttt{picture} environment
In the case of the commands from the \texttt{graphics} package,
this choice is made by \hevea.
(However, note that \hevea{} runs \texttt{imagen} when given the
comments) and insert an \verb+\imageflush+ command, where they want
by \hevea:
etc. commands are sent to the image \textit{image} file and there will
be one GIF image per outermost invocation of these commands.
# hevea doc.tex
\ifhevea
\hevea{} partly implements the \texttt{color} package.
where \textit{name} is the color name, \textit{model} is the color
As regards color models, \hevea{} implements the \texttt{rgb},
For instance, here is the definition for the \texttt{red} color:
There are at least three ways to use colors from the \texttt{named}
\item Specify the named color model as an optional argument to
\item Use the names directly
(\hevea{} implements the \texttt{color} package with
\ifhevea Which yields:
the \verb+\colorbox+ command for changing the background color inside
However, \hevea{} features a
\texttt{bgcolor} environment, for changing the backgroud color of some
\verb+\end{bgcolor}+, where
\subsubsection{From High-Level Colors to Low-Level Colors}\label{getcolor}
High-level colors are color names
Low-level colors are \html-style colors.
That is, they are either one of the sixteen conventional colors black,
silver etc., or a RGB hexadecimal color specification of the form
One changes the high-level \emph{high-color} into a low-level color by
Low-level colors are appropriate inside \html{} attributes and as
An example of \verb+\@getcolor+ usage can be found at the end of
are recognized. Aspect is rather like \LaTeXe{} output, but there is
As \html{} does not provide the same variety of type styles as
Here is how \hevea{} implements text-style declarations by default:
\newcommand{\heveastyle}[2]{{\ifhevea#1\fi#2}}
\verb+\itshape+ &  \heveastyle{\itshape}{italics}\\
\verb+\slshape+ &  \heveastyle{\slshape}{maroon italics}\\
\verb+\scshape+ &  \heveastyle{\scshape}{navy blue}\\
\verb+\upshape+ &  \heveastyle{\upshape}{no style}\\ \hline
\verb+\ttfamily+ & \heveastyle{\ttfamily}{typewriter font}\\
\verb+\sffamily+ & \heveastyle{\sffamily}{purple}\\
\verb+\rmfamily+ &  \heveastyle{\rmfamily}{no style}\\ \hline
\verb+\bfseries+ & \heveastyle{\bfseries}{bold}\\
\verb+\mdseries+ & \heveastyle{\mdseries}{no style}\\ \hline
Text-style commands also exists, they are defined as
However this distinction does not exist in \html: one specifies a
\hevea{} implements the three components by making one declaration to
cancel the effect of other declarations of the same kind.
text-level elements. However, no elements are canceled when using
italics\ifhevea: ``{\sl\sc slanted and small caps}''\fi.
Users need probably not worry about this. However this has an
benefit from the cancelation mechanism. See
Output is not satisfactory inside headers elements
This section describes \hevea{} functionalities that extends on plain \LaTeX{},
Most of the features described here are performed by default.
Loading the \texttt{mathaccents.hva} style files enables
default typesetting of the math
Normally, \hevea{} does not recognize constructs that are specific to
However, some of the internal commands of \hevea{} are homonymous to
notice that \hevea{} semantics for \verb+\def+ 
\hevea{}, where \verb+\def+ had the same semantics as
macros parameters is not performed at the same moment by \hevea{} and
However, things should go smoothly at the first level of macro
appear in source code at the same level as the macro that is to
\LaTeX{} and in \hevea:
\LaTeX{} output is ``coucou''A, while \hevea{} output is ``coucouA''.
Here is \ifhevea\hevea\else\LaTeX\fi{} output:
\hevea{} crash. 
\comdefindex{let}\hevea{} also processes a
The effect is to bind  {\it macro-name1} to whatever {\it macro-name2}
prove very useful in situations where
The \verb+\newif\if+\textit{name}, where \textit{name} is made of letters
The latter two set the \textit{name} condition to \textit{true} and
Note that \hevea{} also implements \LaTeX{} \texttt{ifthen} package
we have the following correspondences:
\verb+\ifthenelse{\boolean{+\textit{name}\verb+}}{+\textit{text$_1$}\verb+}{+\textit{text$_2$}\verb+}+\\[.5em]
\hevea{} implements the macros \verb+\unskip+ and \verb+\endinput+.
refer to the outer definition, even when they appear in nested
Nevertheless, nested commands with arguments are allowed.
However, \hevea{} source distribution includes a simple (\texttt{sh})
The \texttt{hevea} command, should be invoked as~:
# hevea -exec xxdate.exe ...
read by \hevea{}.
\comindex{heveadate}
\ifhevea(e.g. \theweekday)\fi\\
\ifhevea(e.g. \theHour)\fi\\
Counter \texttt{hour} & hour, 00\ldots{}23 \ifhevea(e.g. \thehour)\fi \\
\ifhevea(e.g. \theminute)\fi\\
\ifhevea(e.g. \thesecond)\fi\\ \hline
\ifhevea(e.g. \ampm)\fi\\
\ifhevea(e.g. \timezone)\fi\\
Command \verb+\heveadate+ & Output of the ``\texttt{date}'' Unix
command\ifhevea, (e.g. \heveadate)\fi\\ \hline
not want to enable \hevea{} to execute silently an arbitrary program
Moreover, the \texttt{hevea} program does not execute
Windows users should enjoy the same features with the version of
\index{color!of section headings}
Loading the \texttt{fancysection.hva} file will radically change the
style of sectionnal units headers: they appear over a green
backgroud, the backgrould color saturation decreases as the sectioning
commands themselves do\ifhevea{} (this is the style of this manual).\else.\fi{}
The \texttt{fancysection.hva} file is intended to be loaded after
# hevea article.hva fancysection.hva doc.tex
You can also make a \texttt{doc.hva} file that contains the two lines:
\input{article.hva}
\input{fancysection.hva}
And then launch \texttt{hevea} as:
# hevea doc.hva doc.tex
\input{article.hva}
\input{fancysection.hva}
\verb+\colorsection{+\textit{hue}\verb+}+, where
\input{article.hva}
\input{fancysection.hva}
will yield sectionnal headers on a red-orange background.
\subsection{\hevea{} as a Back-End for VideoC}
\hevea{} is one of the back-ends of the VideoC system for producing
\hevea{} internal engine implements some of the core constructs needed
the \texttt{.hva} files from VideoC distribution.
\hevea{} distribution includes ``.hva'' packages that are
these packages, users should refer to the first pages of the package
\LaTeX{} installation or in a TeX CTAN-archive.
\hevea{} \texttt{amsmath} package defines  some of the constructs of the
specifications and of how \hevea{}
paragraph breaks being reduced to a single line break), except that the entries
Equivalent to the \verb+p+ column specification, except that the entries
It inserts \textit{decl} in front of the entries in the corresponding
in the vertical direction, do not
have exactly the same meaning in \LaTeX{} and in \html{}. However, the
aspect is the same when all columns agree w.r.t. vertical alignment.
do not specify vertical alignment, which therefore becomes browser
constructs permit the encoding of \TeX{} \verb+\cases+ macro as follows:
(This is an excerpt of the \texttt{latexcommon.hva} file.)
Where \textit{col} is one letter, the optional \textit{narg} is a
five & six & seven & eight \\ \hline
five & six & seven & eight \\ \hline
\hevea{} implements column specifications with commands defined in the
\verb+\newcommand+ style. Thus, they have the same behavior as regards
first defined in a \texttt{macro.hva} specific
environment \verb+tabularx+ and a new column type \verb+X+. \hevea{}
makes the former equivalent to \verb+tabular+ and the latter
this may seem a crude implementation.  However, rendering is usually
However, the \html{} definition allows suggested widths or heights for
From \hevea{} point of view, drawing the border line between what can be
At the moment \hevea{} choice is not to specify too much (in
arguments, either to column specifications or to the arrays
\hevea{} does not implement this extension, since it does not
\hevea{} supports several simultaneous indexes, following the scheme
This scheme is backward compatible with the standard indexing scheme
More precisely, \hevea{} knows the following commands:
commands; {\it ext} is the extension of the index information file
\hevea{}; and {\it indexname} is the title of the index.
If given the \verb+idx+ option. \hevea{} attempts to read file
\filename{mydoc}\texttt{.}{\it ext}. There also exists a
\verb+\renewindex+ commands that takes the same arguments and that can be
The {\it tag} argument defaults to \verb+default+, thereby yielding
There also exists a stared-variant \verb+\index*+ that Additionally
defaults to \verb+default+. At the moment, there is an important
difference between \LaTeX{} and \hevea{}: for \verb+\printindex+ to
work, if must occur after the last
practise, since indexes usually reside at the end of books.
The \footahref{\ctanold/contrib/misc/multind.sty}{\texttt{multind}} package provides another scheme
\LaTeX{} default indexing scheme. I would recommend using
\hevea{} provides a slighty uncomplete implementation of the
\hevea{} commands for hyperlinks (see section~\ref{hyperlink})~:
\hevea{} home page is
\ahrefurl{\url{http://pauillac.inria.fr/~maranget/hevea/}}
It yields~: ``\hevea{} home page is
\ahrefurl{\url{http://pauillac.inria.fr/~maranget/hevea/}}''.
However the \verb+\url+ command is fragile, as a consequence it
\LaTeX{} problem, not an \hevea{} one).
\urldef{\heveahome}{\url}{http://pauillac.inria.fr/~maranget/hevea/}
\urldef{\heveahome}{\url}{http://pauillac.inria.fr/~maranget/hevea/}%
Such a source defines the robust command \verb+\heveahome+ as the
Have a look at \footurl{\heveahome}{\hevea{} home page}
It yields: ``Have a look at \footahref{\heveahome}{\hevea{} home page}''.
contrast, it does not work in \hevea{}. In such situations,
\hevea{} implementation is somehow compatible at the ``programming level''.
verbatim. The \ahref{urlhref.hva}{\texttt{urlhref.hva}} style file
\input{urlhref.hva}
Have a look at \url{http://pauillac.inria.fr/~maranget/hevea/}
\input{urlhref.hva}It yields ``Have a look at \url{http://pauillac.inria.fr/~maranget/hevea/}''.
The \texttt{urlhref.hva}
style file (which is an \hevea{} style file and not a \LaTeX{}
Of course, loading \texttt{urlhref.hva} only makes sense when
\subsection{Verbatim Text~: the \texttt{moreverb} and
These two packages provide new commands and environments for
\footahref{\ctan/contrib/supported/moreverb/}{\texttt{moreverb}}
is much more compatible with \hevea{} than
the implementation of the latter.
\hevea{} features a quite compatible implementation, please refer to
Note that \hevea{} does not produce very compact
giving \texttt{hevea} the command line option ``\texttt{-O}''
(see Section~\ref{heveaoptions}).
\subsection{\hevea{} usage}\label{heveausage}
\index{hevea@\texttt{hevea} command}
The \texttt{hevea} command has two operating modes, normal mode and
Operating mode is determined by the nature of the last command line
The \texttt{hevea} command interprets its arguments as names of
Given an argument \textit{filename} there are two cases:
\textit{base}\texttt{.hva},
then a single attempt to open \textit{filename} is made.
searched along \texttt{hevea} search path, which consist in:
\item \texttt{hevea} library directory.
\texttt{info} from \texttt{hevea} library directory, depending upon
\texttt{hevea} output format,
The \texttt{hevea} library directory is fixed at compile-time
(this is where \texttt{hevea} library files are installed)
and typically is \texttt{/usr/local/lib/hevea}.
However, this compile-time value can be overridden
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
is defined as the main input file name,
with leading directories omitted. However the output basename can be
\hevea{} will attempt to load the main input file.
will be searched as \textit{basein}\verb+.+\textit{ext}.
The output base name governs all files produced by \hevea{}.
That is, \html{} output of \hevea{} normally goes to the file
Thus, in the simple case where the \texttt{hevea} command is invoked
# hevea file.tex
\texttt{file}. The main input file is searched once along \texttt{hevea}
In the more complicated case where the \texttt{hevea} command is invoked
# hevea ./dir/file
\texttt{file}. The main input file is loaded by first attempting to
The \texttt{article.hva}, \texttt{seminar.hva}, \texttt{book.hva} and
\texttt{report.hva}
base style files from \hevea{} library are special.
\verb+\documentclass+ command has no effect when a base style file is
# hevea article.hva file.tex
If there is no command line argument, or if the last command line
argument has the extension~\texttt{.hva}, then
there is neither input base name nor output base name,
In other words \texttt{hevea} acts as a filter.
``\verb+hevea+ \textit{file}\verb+.tex+'' and not
``\verb+hevea < + \textit{file}\verb+.tex > +\textit{file}\verb+.html+''.
\subsubsection{Options}\label{heveaoptions}
The \texttt{hevea} command recognizes the following options:
\item[{\tt -version}] Show \texttt{hevea} version and exit.
\item[{\tt -v}] Verbose flag, can be repeated to increase
verbosity. However, this is mostly for debug.
\item[{\tt -e} {\it filename}] Prevent \texttt{hevea} from loading any file
files, including \texttt{hevea.hva} and base style files.
\item[{\tt -fix}] Iterate \hevea{} until a fixpoint is found.
output. The file \textit{prog} must have execution permission and is
searched by following the searching rules of~\texttt{hevea}.
\item \texttt{hevea} sets the boolean register \texttt{french} to
default, these equivalent are in English.
These characters are replaced by \html{} entities. This option is
\item[{\tt -I} {\it dirname}] Add {\it dirname} to the search path.
However, if \textit{name} is \textit{base}\texttt{.html}, then
a tutorial introduction to \hevea{},
while \hevea{} reference manual is part~\ref{referencemanual}.
\textit{base}\texttt{.html} as the name of
\item[{\tt -tocbis}] Add a small table of contents at every file start.
in which output files are the anchors from the input file gone.
is part of \hevea{} and is designed to optimize \texttt{hevea}
However, \texttt{esponja} can also be used alone to optimize
text-level elements in \html{} files.
\item[{\tt -v}]Be verbose, can be repeated to increase verbosity.
It is a companion program of \hevea{}, which must have been previously run as:
\texttt{\# hevea}\ldots{} \textit{base}\texttt{.tex}\\
\texttt{\# hevea}\ldots{} \texttt{-o} \textit{base}\texttt{.html}\ldots\\
(In both cases, \textit{base} is \hevea{} output basename.)
\hevea{} echoes part of its input into
\item[{\tt -mag} {\sl nnnn}] Change the enlarging ratio that is applied
\texttt{netpbm} package or several such commands piped together.
in \texttt{imagen} \texttt{ppm} image production chain, where
\textit{number} is the maximal number of colors in the produced
PNG image files have a ``\texttt{.png}'' extension.
Note that \texttt{hevea} should have been previously run as
\texttt{hevea png.hva} \textit{base}\texttt{.tex} (so that the proper
The file is first translated into \texttt{doc.html} by \texttt{hevea},
the specific style file \texttt{macros.hva}.
Then, \texttt{hacha} cuts \texttt{doc.html} into several,
HEVEA=hevea
$(DOC).html: macros.hva $(DOC).tex
        $(HEVEA) $(HEVEAOPTS) macros.hva $(DOC).tex
Thanks to the \verb+-fix+ options, \texttt{hevea} will run the appropriate
HEVEA=hevea
$(DOC).html: macros.hva $(DOC).tex
        $(HEVEA) $(HEVEAOPTS) macros.hva $(DOC).tex
\texttt{doc.image.tex} and of the various files produced by
when given the \verb+-fix+ option, \texttt{hevea} will itself run
By default, \hevea{} uses
A good way to know whether your browser can show \hevea{} symbols or
as intended by \hevea{}.
work only with documents that are generated by \hevea{} with the
\texttt{-noiso} option enabled (see section~\ref{heveaoptions}).
(Edit/Preference/Fonts, then check the appropriate box).
\hevea{} home page is \ahrefurl{\httpbase}. It contains links to the
The author can be contacted at \mailto{Luc.Maranget@inria.fr}.
\hevea{} can be freely used and redistributed without modifications.
Modifying and redistributing \hevea{} implies a few constraints.
More precisely, \hevea{} is distributed under the terms of the
Q~Public License, but \hevea{} binaries include the Objective Caml
The manuel itself is distributed under the terms of
\ifhevea
The programs \commandname{hevea} and \commandname{hacha} are written in
However, a Red~Hat 7.2
\footahref{\ftpbase/hevea-\heveaversion-1.i386.rpm}{binary distribution}
\label{imagen:needs}\hevea{} users may instruct the program not to process a
\verb+.gif+ file and \hevea{} outputs a  link to the image file.
\footahref{ftp://wuarchive.wustl.edu/graphics/graphics/packages/NetPBM}{\texttt{netpbm}}.
To benefit from the full functionality of \hevea, you need all
this software. However, \hevea{} runs without them, but then you will
The details are given in the \ahref{\ftpbase/README}{\texttt{README}}
Basically, \hevea{} should be given a library
directory. The installation procedure stores the \texttt{hevea.hva}
There are two compilation modes, the \texttt{opt} mode selects the
In \hevea{} case, \texttt{ocamlopt} produces code that is up to three
Thus, default compilation mode is \texttt{opt}, however it may be the
Note that the \texttt{hevea.sty} file is simply copied to \hevea{}
\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
even when no \texttt{.aux} file is present.
whereas \hacha{} can cut the output of \hevea{} into several files.
(however there exists a commercial
for producing the Caml manuals. This is \hevea{} direct ancestor and I
The following people contributed to \hevea{} development:
\ahref{http://www.arch.ohio-state.edu/crp/faculty/pviton/support/hevea.html}{window
(win32) port} of \hevea.
The very principle he introduced for interfacing the \texttt{videoc}
lexer with \hevea{} main lexer is now used extensively throughout
\hevea{} source code.
\item Pierre Boulet, by using \hevea{} as a stage in his tool
\hevea{} implementation of the \verb+alltt+ environment.