\usepackage{a4} \usepackage{fullpage} \usepackage{makeidx} \usepackage{texnames} \usepackage{url} \usepackage{hevea} \usepackage{isolatin1} \usepackage{ifthen} \usepackage{array} \usepackage{graphics} %HEVEA\usepackage{color} \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 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}. 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, ``\texttt{a.html}'', which you can visualize through a {\html} browser. 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 \LaTeX{} style files are files that are not intended to produce output, but 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). More generally, most base styles that are neither 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. the commands \verb+\input+ or \verb+\usepackage+ or \verb+\input+. \subsubsection{Files loaded with \texttt{\char92 input}} Just like \LaTeX{}, \hevea{} reacts to the construct \textit{file}. (if I got it right, \hevea{} even follows \TeX{} crazy As it is often the case, assume that the document \texttt{mydoc.tex} has a \verb+\input{mymacros.tex}+ instruction in its preamble, where \texttt{mymacros.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 \subsubsection{Files loaded with \texttt{\char92 usepackage}} \verb+\usepackage{+\textit{name}\verb+}+ by loading the file \hevea{} reacts in a similar, but different, manner, by loading the file \textit{name}\texttt{.hva}. \hevea{} distributions already includes quite a few ``\texttt{.hva}'' implementations of famous packages (see section~\ref{implemented:package}). When a given package (say \texttt{zorglob}) is not implemented, the Hopefully, you are only using a few commands from package Then, it suffices to put your definitions in file~\texttt{zorglub.hva} and \hevea{} will react to \verb+\usepackage{zorglub}+ by loading \texttt{zorglub.hva}. See section~\ref{usepackage} for the full story on \verb+\usepackage+. 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 Then, sub-displays are opened by \LaTeX{} constructs which require 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 by giving the \verb+-v+ option comand line option twice, which instructs \hevea{} to add a By contrast with formulas, which \hevea{} attempts to render with text-level elements only when they appear inside paragraphs, \LaTeX{} arrays 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: Note that all warnings can be suppressed with the \verb+-s+ (silent) When a warning reveals a real problem, it can often be cured by writing a specific macro. The next two sections introduce \hevea{} Just like \LaTeX{}, \hevea{} can be seen as a macro language, macros characters (such as letters, integers\ldots) are outputed or some internal operation (such as changing font attributes, or arranging This scheme favors easy extension of program capabilities by users. However, predicting program behavior and correcting errors may occur after several levels of macro expansion. As a consequence, users can tailor \hevea{} to their needs, but it Nevertheless, happy \LaTeX{} users should enjoy customizing \hevea{}, since this is done by writing \LaTeX{} code. fine control over text placement, whereas {\html}. Conversely, {\html} has font attributes, such as color, which 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 changes while leaving your file processable by \LaTeX{}, and \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 seen by \LaTeX. Even better, \verb+trouble.tex+ is not changed Of course, this will be easier if the \LaTeX{} source is written in a Note that this style is recommended anyway, since it eases the changing \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 Which \LaTeX{} renders as follows: 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 Which \LaTeX{} typesets as follows: \hevea{} always translates \verb+\rule+ as \verb+
+, 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} \pdfsection{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 \verb+\documentstyle+ and as arguments to \verb+\usepackage+, in the source and to invoke \hevea{} as follows: \verb+# hevea+ \texttt{-e} \filename{latexonly}\ldots \label{heveaonly}Having \filename{heveaonly} loaded by \hevea{} only is more simple: it suffices to invoke \hevea{} as follows: \verb+# hevea+ \filename{heveaonly}\ldots Finally, if one has an \hevea{} equivalent \textit{style}\texttt{.hva} \verb+\usepackage{+\textit{style}\verb+}+ while \hevea{} loads \textit{style}\texttt{.hva}. As \hevea{} will not fail in case \textit{style}\texttt{.hva} does not 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 \verb+\usepackage{+\textit{file}\verb+}+ from inside the document. Which method is better depends definitions from \textit{file}\texttt{.hva} are processed before the In the \verb+\usepackage+ case, \hevea{} loads \textit{file}\texttt{.hva} at the place where \LaTeX{} loads \textit{file}\texttt{.sty}, hence the definitions from \textit{file}\texttt{.hva} replace \subsection{The \protect\texttt{hevea} package}\label{heveastyle} The \texttt{hevea.sty} style file is intended to be loaded by \LaTeX{} and not by \hevea{}. It provides \LaTeX{} with means to ignore or process some parts of the Note that \hevea{} copes with the constructs defined in the \texttt{hevea.sty} file by default. It is important to notice that the \texttt{hevea.sty} style file from the distribution is a \emph{package} in \LaTeXe{} terms and that it is not compatible with old \LaTeX{}. Moreover, the \texttt{hevea} package loads the \texttt{comment} package which must be present. \hevea{} and \LaTeX{} perform the following actions on source inside environment & \multicolumn{1}{c}{\hevea} & \multicolumn{1}{c}{\LaTeX} constructs and macro characters are processed (see section~\ref{imagen}) & \hevea{} and left alone by \LaTeX{}: It is impossible to avoid the spurious space in \hevea{} output This extra spaces comes from the newline character that follows can be achieved by using the \texttt{hevea} boolean register or comments, see sections~\ref{heveabool} Also note that environments define a scope and that style changes 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} Boolean registers are provided by the \texttt{ifthen} package \boolindex{hevea}Both the \texttt{hevea.sty} style file and \hevea{} define the boolean register \texttt{hevea}. 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 {\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 to the image file builds up a current page, which is flushed output a \verb++ tag in \hevea{} output file, where \textit{pagename} is build from the image counter and \hevea{} output file name. \texttt{dvips}, \texttt{ghostscript} and a few others tools, which must all be Here is the active part of a \texttt{blob.tex} file: This time, we would like \verb+\blob+ to produce a small black square, which # hevea blob.tex \texttt{.gif} images. However, the cost may be prohibitive, text rendering is generally bad, fine placement is ignored and font style changes are Note that this technique is used by \hevea{} implementation of the \texttt{graphics} package (see section~\ref{graphics}), which provides a more standard manner to include Postcript images in Included images are easy to manage: it suffices to let \LaTeX{} do the Let \texttt{round.ps} be a Postscript file, which is included as an image in the source file \texttt{round.tex} (which must load the \filename{epsf} package): Then, \hevea{} can have this image translated into a inlined (and Then, processing \texttt{round.tex} through \hevea{} and \verb+\usepackage{epsf}+ command gets echoed to the packages or define the right macros. However, the above solution implies modifying the original \LaTeX{} command, so that \hevea{} echoes \verb+\epsfbox+ and its argument to Such a definition must be seen by \hevea{} only. So, it is best put \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 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 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 \latexsection{Cutting your document into pieces with \hacha{}} \label{hacha} \hevea{} outputs a single \texttt{.html} file. This file can be cut into pieces at various sectional units by {\hacha} First generate your {\html} document by applying \hevea{}: \texttt{\# hevea }\filename{mydoc}\texttt{.tex} \texttt{\# hacha }\filename{mydoc}\texttt{.html} Every item in the table of contents contains a link to or into a file \filename{article} style and {\em chapter} in the \filename{book} 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 \texttt{\# hacha -o root.html }\filename{mydoc}\texttt{.html} Some of \hevea{} output get replicated in all the files generated by \hacha{}. Users can supply a header and a footer, which will appear at the begining and end of every page generated by \hacha{}. It suffices to \quad\verb+\htmlhead{+\textit{header}\verb+}+\\ \hacha{} also makes every page it generates a clone of its input as \hacha{} behavior can be altered from the document source, by using \texttt{hevea.sty} style file from the \hevea{} distribution. An alternative to loading the \texttt{hevea} package is to put {\hacha} recognizes all sectional units, ordered as follows, from part}, {\em chapter}, 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. At document start, the root file and the output file are {\hacha} preamble. They command the cutting scheme of the whole document: \item[{\tt\char92 cuttingunit}] This is a macro that holds the document cutting unit. You can change the default (which is {\em section} in the \filename{article} style and {\em chapter} in the \filename{book} style) by doing: \item[{\tt\char92 tocnumber}] Instruct \hevea{} to put section numbers \item[{\tt\char92 notocnumber}] Instruct \hevea{} \emph{not} to put You can change the default value of 1 by doing 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. \item[{\tt\char92 cutdef[}{\it depth}{\tt]\{}{\it secname}{\tt \}}] the cutting depth does not change. Result is unspecified if whatever {\em secname} expands to is \item[{\tt\char92 cutend}] All sectioning commands perform \verb+\cuthere+, Consider, for instance, a \filename{book} document with a long chapter that you want to cut at the section level, showing subsections: \chapter{A long chapter} \chapter{The next chapter} Then, you should insert a \verb+\cutdef+ at chapter start and a \verb+\cutend+ at chapter end: \chapter{A long chapter} \chapter{The next chapter} that would otherwise contain the long chapter now contains the chapter No other change is needed, since the macro \verb+section+ already performs the appropriate \verb+\cuthere{section}{...}+ commands, which were ignored by default. \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). In this section we show how to alter some details of \hacha{} When invoked as \texttt{hacha \textit{doc}.html}, \hacha{} produces a \texttt{index.html} table of links file that 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 When \hacha{} creates a web page from a given sectional unit, the title of this page normally is the name of the sectional unit. ``Cutting your document into pieces with \hacha''. \verb+\htmlprefix{\hevea{} Manual: }+ in the document, ``\hevea{} Manual: Cutting your document into pieces with \hacha'' and the title of all other pages would show the same prefix. The command \verb+\toplinks{+\textit{prev}\verb+}{+\textit{up}\verb+}{+\textit{next}\verb+}+ instructs \hacha{} to put links to a \item The arguments notice that these argument are processed (see section~\ref{urlareprocessed}). \item When one of the expected argument is left empty, relate documents that are generated independantly by \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} package. \multicolumn{1}{c}{Macro} & \multicolumn{1}{c}{\hevea} & \label{urlareprocessed}It is important to notice that all arguments Fortunately, the \texttt{url} package provides a very convenient \verb+\url+ command that acts like \verb+\verb+ and can appear in (unfortunately, this is not the full story, see section~\ref{urlpackage}). Hence, provided the \texttt{url} package is loaded, 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: \texttt{url}, which as correct as it can be and well-written. \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 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. There are sixteen predefined colors: changed by the declaration \verb+\htmlcolor{+{\it number}\verb+}+, where {\it number} is a six digit hexadecimal number specifying a change font color to dark gray:%HEVEA{\htmlcolor{404040}% command from the \texttt{epsf} package. 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, mechanism (see section~\ref{imagen}), which will translate the image back from 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 \index{"@print@\texttt{\char92"@print}|defocc} \index{"@getprint@\texttt{\char92"@getprint}|defocc} \index{"@hr@\texttt{\char92"@hr}|defocc} \index{"@open@\texttt{\char92"@open}|defocc} \index{"@close@\texttt{\char92"@close}|defocc} \index{"@style@\texttt{\char92"@style}|defocc} \index{"@nostyle@\texttt{\char92"@nostyle}|defocc} \index{"@fontsize@\texttt{\char92"@fontsize}|defocc} \index{"@fontcolor@\texttt{\char92"@fontcolor}|defocc} some characters cannot be given directly (e.g. \verb+#+ and \item[{\tt\char92 @print\char123}{\it text}{\tt\char125}] \item[{\tt\char92 @getprint\char123}{\it text}{\tt\char125}] \item[{\tt\char92 @hr[}{\it attr}{\tt]\char123}{\it width}{\tt\char125\char123}{\it height}{\tt\char125}] \item[{\tt\char92 @open\char123}{\it BLOCK}{\tt\char125\char123}{\it attributes}{\tt\char125}] Open \html{} block-level element \textit{BLOCK} with attributes As a special case \textit{BLOCK} may be the empty string, then a \html{} \item[{\tt\char92 @close\char123}{\it BLOCK}{\tt\char125}] 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. \item[{\tt\char92 @style\char123}{\it SHAPE}{\tt\char125}] Declare the text shape \textit{SHAPE} (which must be uppercase) \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. \item[{\tt\char92 @fontsize\char123}{\it int}{\tt\char125}] Declare the text-level element \verb+FONT+ with attribute be a small integer in the range \texttt{1},\texttt{2}, \ldots{} , \texttt{7}. \item[{\tt\char92 @fontcolor\char123}{\it color}{\tt\char125}] Declare the text-level element \verb+FONT+ with attribute \verb+black+, \verb+silver+ etc, or a RGB hexadecimal color specification Note that the argument \textit{color} is processed, as a consequence \item[{\tt\char92 @nostyle}] Close active text-level declarations and ignore further text-level The effect stops when the enclosing block-level element is closed. \index{"@open@\texttt{\char92"@open}} \index{"@close@\texttt{\char92"@close}} 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 \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+ because the element \verb+IMG+ consists in a single tag, without a \index{"@nostyle@\texttt{\char92"@nostyle}} which \hevea{} uses internaly to output \texttt{A} elements. tags are emitted inside groups where styles are canceled by using the of text-level elements. \index{"@open@\texttt{\char92"@open}} \index{"@close@\texttt{\char92"@close}} Finally, here is an example of direct block opening. The \texttt{bgcolor} environment from the \texttt{color} package locally changes background color (see section~\ref{bgcolor}). its opening command, and closing all these elements in its closing command. In my opinion, such a style of opening block-level elements \index{"@getcolor@\texttt{\char92"@getcolor}} 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. as an optional argument. These attributes are the ones of the \latexsection{Customizing \hevea} \hevea{} can be controlled by writing \LaTeX{} code. In this section, we examine how users can change \hevea{} default behavior or add functionalities. In all this section we assume that a document \texttt{macros.hva}. That is, \hevea{} is invoked as: # hevea macros.hva mydoc.tex \texttt{macros.hva}, using internal commands. This requires a good \subsection{Simple changes} Users can easily change the rendering of some constructs. For \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 All shapes are mutually exclusive, this means that each shape declaration cancels the effect of other active shape declarations. For instance, in the example, small caps shapes is navy blue and not If one wishes to change the rendering of some of the shapes (say small \texttt{macros.hva}. Redefining the old-style \verb+\sc+ is compatible with the cancelation mechanism, redefining \verb+\scshape+ is not. 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 style, but for a few commands whose calling interface is changed. takes an extra optional argument (which \hevea{} should ignore However, \hevea{} can process the document as it stands. One solution to insert the following lines into \texttt{macros.hva}: \input{article.hva}% Force document class ``article'' The effect is to replace \verb+\title+ by a new command which calls \hevea{} \verb+\title+ with the appropriate argument. \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}{!*!}} command, which calls the \verb+\imgsrc+ command~: {\@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} This does not harm as long as the final \html{} document has a white \html. There are two such formats: plain text and info files. To translate into text, invoke \hevea{} as follow: # hevea -text [-w ] myfile.tex Then, \hevea{} produces \texttt{myfiles.txt} a plain text translation 72~characters wide. Nearly every environments have been translated, included lists and tables. The support is nearly the same as in \html, excepted in some cases described hereafter. Most style changes are ignored, because it is hardly possible to render them in plain text. Thus, there are no italics, bold fonts, underlinings, nor size change or colors\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{}. 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 ] 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 nodes in the others files, which are named \texttt{myfile.info-1}, The optional argument \verb+-w+ has the same meaning as for text output. the 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 ``\verb+\+'' followed by a single non-letter character or (and this is the case of many of \hevea{} internal commands), or However, \hevea{} does its best to read arguments even when they are and ``\verb+ +'', character or \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 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. 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 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{} \index{color!of background|see{\texttt{\char92"@bodyargs}}} \index{"@bodyargs@\texttt{\char92"@bodyargs}} \index{"@meta@\texttt{\char92"@meta}}\label{metadef} The \verb+\htmlhead+ command cannot be used for changing anything outside of the \html{} document body, there are specific commands for doing this. change \hevea{} default (empty) atribute for Generally speaking, spaces (and single newline characters) in the 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. If the document is then cut into smaller files by \hacha{} (see section~\ref{hacha}) footnotes may go to a separate file. 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. \verb+\'+, work when then produce letters from the iso-latin1 character set. 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 numbers can be changed by redefining \verb+\the+{\it secname}. chapters into alphabetic (uppercase) style: \renewcommand{\thechapter}{\Alph{chapter}} When jumping to anchors, browsers put the targeted line on top 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 \subsection*{\aname{no:number}{Use \hacha{}}} \addcontentsline{toc}{subsection}{\ahrefloc{no:number}{Use \hacha{}}} 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 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 argument. Section~\ref{hacha} explains how to control {\hacha}. \section{Classes, Packages and Page Styles} \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 If one of the reckognized styles has already been loaded at the time when 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 \subsection{Packages and Page Styles}\label{usepackage} \hevea{} reacts to \verb+\usepackage[+\textit{options}\verb+]{+\textit{pkg}\verb+}+ in \verb+\usepackage+ command with its arguments gets echoed to the \item \hevea{} attempt to load file \textit{pkg}\texttt{.hva}, (see section~\ref{search:path} on where \hevea{} searches for files). Note that \hevea{} will not fail if it cannot load \textit{pkg}\texttt{.hva} and that no warning is issued in that case. The \hevea{} distribution contains implementations of some packages, In some situations it may not hurt at all if \hevea{} does not implement a package, for instance \hevea{} does not provide an implementation for the packages \texttt{isolatin1} or Users needing an implementation of a package that is widely used and Experienced users may find it fun to attempt to write package 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: \item[\texttt{\char92 usecounter\{}\textit{counter}\texttt{\}}] by every \verb+\item+ command with no argument, before it does \item[\texttt{\char92 renewcommand\{\char92 \verb+\makelabel{+{\it label}\verb+}+, where {\it label} is the item Thus, users can change label formatting by redefining \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. When occurring outside math mode, characters \verb+_+ and \verb+^+ act as 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. Subscript and superscript placement can be changed using the In text mode, these macros call the \verb+\textstackrel+, These macros perform the following default actions, which can be changed by redefining them: \item[\texttt{\char92 textstackrel}] Performs ordinary superscripting. \item[\texttt{\char92 textunderline}] Underlines its argument, using the \verb+U+ text-level element. \item[\texttt{\char92 textoverline}] Sends a warning message to the handled\label{mathaccents} by default. However, the distribution includes a \texttt{mathaccents.hva} file except \verb+\check+ and \verb+\breve+. Rendering is far from perfect and changes from display to text mode. More precisely, the accent is put (too far) above the symbol in display mode, \ifhevea{\input{mathaccents.hva}For instance, given the formula one should not load the \texttt{mathaccents.hva} file and write issue color changes: \ifhevea With such definitions the previous example now appears as: closer to universally understood notations for mathematics. changed. The appearance of other symbols can be changed using \LaTeXe{} style changing commands (\verb+\mathbf+, etc.). by style changes or not is browser dependent. The \verb+\cal+ declaration and the \verb+\mathcal+ command (that 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 This is so because \hevea{} implements displayed maths as tables, which require to be both opened and closed and introduce line breaks perform type size changes. \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 the \textit{calc} package that makes using \TeX{} style for counters \subsection{The \texttt{ifthen} Package}\label{ifthen} The \texttt{ifthen} package is partially supported. \verb+\lengthtest+ test expression, which is As a consequence, \hevea{} accepts the following example from the {\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 with the boolean registers of the \texttt{ifthen} package, as it is the case in \LaTeX. Figures and tables are put where they appear in source, regardless of 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 document), which significantly extends the \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 recognized, it loads the \texttt{.bbl} file which should thus 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 \index{argument!of input@of \texttt{\char92 input}} option (see section~\ref{heveaoptions}), then \hevea{} does not attempt to load \textit{filename}. \item \hevea{} does not fails when it cannot find By default indexes are formated in two columns, one may change the number of columns by setting the value of the \texttt{indexcols} counter. As with \LaTeX{}, two runs of \hevea{} are normally needed to format However, if all index producing commands (normally \verb+\index+) Note that two packages for multiple indexes are implemented 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 which are null macros). 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. Stretchable lengths do not exist, thus the \verb+\hfill+ and However \verb+\makebox+ generates a specific warning, since \hevea{} command, which issues a warning and typesets its argument It is retrieved (and outputed) by the command Package} 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. In both cases, the \texttt{imagen} script has to be run by hand. (However, note that \hevea{} runs \texttt{imagen} when given the comments) and insert an \verb+\imageflush+ command, where they want by \hevea: All commands from the graphics package are implemented using the etc. commands are sent to the image \textit{image} file and there will be one GIF image per outermost invocation of these commands. loads the \texttt{graphics} package and that includes some (scaled) # hevea doc.tex \ifhevea \subsection{The \texttt{color} Package}\label{color}\index{color}\label{color:package} \hevea{} partly implements the \texttt{color} package. \verb+\textcolor+. Other commands from the \texttt{color} package do where \textit{name} is the color name, \textit{model} is the color \verb+\textcolor{+\textit{name}\verb+}{+\textit{text}\verb+}+, which change text color. The \verb+\textcolor+ command has a similar feature. As regards color models, \hevea{} implements the \texttt{rgb}, For instance, here is the definition for the \texttt{red} color: \textcolor[named]{Peach}{Peach}, 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} \index{"@getcolor@\texttt{\char92"@getcolor}|defocc} 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 All \LaTeXe{} declarations and environments for changing type style 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 \emph{shape}, \emph{series} and \emph{family}. 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. For instance consider the following source, that exhibits shape changes: 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 important practical consequence: to change the default rendering of benefit from the cancelation mechanism. See Output is not satisfactory inside headers elements The \verb+\symbol{+{\it num}\verb+}+ outputs character number {\it num} from the iso-latin1 character set. This departs from \LaTeX{}, which output symbol number \textit{num} in This section describes \hevea{} functionalities that extends on plain \LaTeX{}, Most of the features described here are performed by default. Loading the \texttt{mathaccents.hva} style files enables default typesetting of the math (\verb+\hat+, \verb+\tilde+,\ldots), see Section~\ref{mathaccents}. 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+ That is, defining a command that already This is an important change with respect to previous versions of \hevea{}, where \verb+\def+ had the same semantics as Delimiting characters in command definition are supported. Please note that delimiting characters are supported as far as I could, problems are likely with delimiting characters which include characters \verb+{+\ldots{} \verb+}+: 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. \subsubsection{The \texttt{\char92 let} construct} \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 \subsubsection{The \texttt{\char92 global} construct} 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}) \texttt{xxdate.exe} that activates date and time support. 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 Sectioning command background colors can be changed by redefining the corresponding colors (\texttt{part}, \texttt{chapter}, \input{article.hva} \input{fancysection.hva} (See section~\ref{color:package} for details on the \texttt{named} \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 educational CDROM to teach programming languages. \hevea{} internal engine implements some of the core constructs needed the \texttt{.hva} files from VideoC distribution. \section{Implemented Packages}\label{implemented:package} \hevea{} distribution includes ``.hva'' packages that are implementations of \LaTeX{} packages. Packages described in the ``\emph{Blue Book}'' (\texttt{makeidx}, 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}, \LaTeX{} installation or in a TeX CTAN-archive. At the moment, package options are ignored. \hevea{} \texttt{amsmath} package defines some of the constructs of the \texttt{amsmath} package. At the moment, supported constructs are Packages}\label{arraypack} package is described in specifications and of how \hevea{} \texttt{array} package} 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 double definition, which is not performed and induces a warning first defined in a \texttt{macro.hva} specific 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 subtle array formatting that the \texttt{tabularx} package performs, 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 \subsection{The \texttt{calc} Package}\label{calc} This package enables using traditional, infix, notation for The \texttt{calc} package provides a similar extension of the syntax \hevea{} does not implement this extension, since it does not \subsection{The \texttt{comment} Package} The implementation for this package provides two commands, \subsection{Multiple Indexes with the \texttt{index} and \texttt{multind} package}\label{multind} \hevea{} supports several simultaneous indexes, following the scheme \footahref{ftp://theory.lcs.mit.edu/pub/tex/index/}{\texttt{index}} package, which is present in modern \LaTeX{} distributions. This scheme is backward compatible with the standard indexing scheme More precisely, \hevea{} knows the following commands: \item[{\tt\char92 newindex\{}{\it tag}{\tt \}\{}{\it 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 \item[{\tt\char92 makeindex}] Perform z\item[{\tt\char92 index[}{\it tag}{\tt]\{}{\it arg}{\tt\}}] The {\it tag} argument defaults to \verb+default+, thereby yielding There also exists a stared-variant \verb+\index*+ that Additionally \item[{\tt\char92 printindex[}{\it tag}{\tt]}] Compute, format and 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 the ``\texttt{index}'' package. \subsection{Multiple Bibliographies with the \texttt{multibib} package} \ttindex{multibib}{package}\comindex{newcites}. \hevea{} provides a slighty uncomplete implementation of the \texttt{multibib} package. The one non-implemented feature is the \subsection{The \texttt{url} package}\label{urlpackage} \comindex{url}\index{hyperlinks}\ttindex{url}{package} This package in fact provides a enhanced \verb+\verb+ command that \LaTeX{} active characters~: which gets typeset as: ``This is a complicated url: \url{http://foo.com/~user#label%coucou}.'' \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). The \texttt{url} package solves this problem by providing the \urldef{\heveahome}{\url}{http://pauillac.inria.fr/~maranget/hevea/} \urldef{\heveahome}{\url}{http://pauillac.inria.fr/~maranget/hevea/}% Such a source defines the robust command \verb+\heveahome+ as the Have a look at \footurl{\heveahome}{\hevea{} home page} It yields: ``Have a look at \footahref{\heveahome}{\hevea{} home page}''. 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{} which often use \verb+\url+ for its typesetting power. Of course, loading \texttt{urlhref.hva} only makes sense when \subsection{Verbatim Text~: the \texttt{moreverb} and \texttt{verbatim} Packages} 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. \subsection{Typesetting Computer Languages: the \texttt{listings} Package} \hevea{} features a quite compatible implementation, please refer to the original package documentation. Note that \hevea{} does not produce very compact \html{} in case you use this package. giving \texttt{hevea} the command line option ``\texttt{-O}'' (see Section~\ref{heveaoptions}). packages are partly implemented. \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 changed, using the \verb+-o+ option (see the section on options below). \hevea{} will attempt to load the main input file. will be searched as \textit{basein}\verb+.+\textit{ext}. The output base name governs all files produced by \hevea{}. That is, \html{} output of \hevea{} normally goes to the file 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. \item[{\tt -noiso}] Do not output (iso-latin1) characters whose code These characters are replaced by \html{} entities. This option is definition. In particular, this option disable size and color changes inside \verb+
+\ldots{} \verb+
+, which are otherwise performed. \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}. \subsection{\hacha{} usage} \index{hacha@\texttt{hacha} command} The \texttt{hacha} command interprets its argument \textit{base}\texttt{.html} as the name of \item[{\tt -o} {\it filename}] Make \hacha{} output go into file \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. \noindent Section~\ref{hacha} of the user manual explains how to alter \hacha{} default behavior. 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. is left unchanged. \item[{\tt -v}]Be verbose, can be repeated to increase verbosity. It may yield challenging input for other \html~optimizers. 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 outputs \texttt{ppm} images, which are then fed into a series of transformations that change them into \texttt{.gif} files. \item[{\tt -mag} {\sl nnnn}] Change the enlarging ratio that is applied stage in \texttt{imagen} \texttt{ppm} to \texttt{gif} production chain. \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 image production chain. It can also help in limiting image files size. 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 in old versions of the \texttt{netpbm} package. Sometimes \texttt{imagen} crashes because the PPM transformation chain The file is first translated into \texttt{doc.html} by \texttt{hevea}, which also reads the specific style file \texttt{macros.hva}. Then, \texttt{hacha} cuts \texttt{doc.html} into several, HEVEA=hevea HACHA=hacha $(DOC).html: macros.hva $(DOC).tex $(HEVEA) $(HEVEAOPTS) macros.hva $(DOC).tex \texttt{doc002.html}, etc. files produced by \texttt{hacha}. Thanks to the \verb+-fix+ options, \texttt{hevea} will run the appropriate HEVEA=hevea HACHA=hacha $(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{}. Netscape*documentFonts.charset*adobe-fontspecific: iso-8859-1 does not contain iso-latin1 characters above 127. That is, this will work only with documents that are generated by \hevea{} with the \texttt{-noiso} option enabled (see section~\ref{heveaoptions}). (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 runtime system, which is distributed under the Gnu Library General 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. \LaTeX{} source is changed into \verb+.gif+ images by the \verb+imagen+ script, which basically calls, \LaTeX, \texttt{dvips}, and a few tools from the image processing package \footahref{ftp://wuarchive.wustl.edu/graphics/graphics/packages/NetPBM}{\texttt{netpbm}}. To benefit from the full functionality of \hevea, you need all this software. However, \hevea{} runs without them, but then you will 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. M.~Gooseens, F.~Mittelbach, A.~Samarin.