5 Making HEVEA and LATEX both happy
A satisfactory translation from LATEX to HTML often requires
giving instructions to HEVEA.
Typically, these instructions are macro definitions and
these instructions should not be seen by LATEX.
Conversely, some source that LATEX needs should not be processed
by HEVEA.
Basically, there are three ways to make input vary according to the
processor, file loading, the hevea.sty style
file and comments.
5.1 File loading
HEVEA and LATEX treat files differently. Here is a summary of the main
differences:
- LATEX loads style files given as optional arguments to
\documentstyle
and as arguments to \usepackage
. HEVEA
does not.
- LATEX and HEVEA both load files given as arguments to
\input
, however when given the option -e
filename,
HEVEA does not load filename.
- HEVEA loads all files given as command line arguments.
As a consequence, for having a file latexonly loaded by
LATEX only, it suffices either to load the file in the document
source as:
\usepackage{
latexonly}
Or, as
\documentstyle[
...,
latexonly,...]{
...}
Another solution is to use \input{
latexonly}
in the source and to invoke HEVEA as follows:
# hevea
-e latexonly...
Having heveaonly loaded by HEVEA only is more
simple: it suffices to invoke HEVEA as follows:
# hevea
heveaonly...
Using an HEVEA-specific style file given as a command line argument
is the method of choice for supplying command definitions
to HEVEA only. Users can then be sure that these definitions are
not seen by LATEX and will not get echoed to the image
file (see section 6).
5.2 The hevea.sty style file
The hevea.sty style file is intended to be loaded by LATEX
and not by HEVEA.
It provides LATEX with means to ignore or process some parts of the
document.
Note that HEVEA copes with the constructs defined in
the hevea.sty file by default.
5.2.1 Selecting a translator
HEVEA and LATEX perform the following actions on source inside
the latexonly
, verblatex
, htmlonly
, rawhtml
,
toimage
and verbimage
environments:
|
environment |
|
HEVEA |
LATEX |
|
latexonly |
|
ignore, \end{ env}
constructs are processed |
|
process |
verblatex |
|
ignore |
|
process |
htmlonly |
|
process |
|
ignore |
rawhtml |
|
echo verbatim |
|
ignore |
toimage |
|
send to the image file, \end{ env}
constructs and macro characters are processed (see section 6) |
|
process |
verbimage |
|
send to the image file (see section 6) |
|
process |
|
As an example, this is how some text can be typeset in purple by
HEVEA and left alone by LATEX:
We get:
\begin{htmlonly}%
\purple purple rain, purple rain%
\end{htmlonly}
\begin{latexonly}%
purple rain, purple rain%
\end{latexonly}%
\ldots
We get:
purple rain, purple rain
...
It is impossible to avoid the spurious space in the output above,
because \end{htmlonly}
must appear in a line of its own for
LATEX to reconize it. However, better space control can be achieved
by using the hevea boolean register
or comments, see sections 5.2.4
and 5.3.
Also note that environments define a scope and that style changes
(and non-global definitions) are local to them. For instance, in the
example above, ``...'' appears in black in HTML output.
5.2.2 Why is there a verblatex environment?
Some scanning and analysis of source is performed
by HEVEA inside the latexonly environment, in order to
allow latexonly to dynamically occur inside other environments.
More specifically, \end{
env}
macros
are recognized and their env argument is tested against
the name of the environment whose opening macro \
env
opened the latexonly environment.
In that case, macro expansion of \end
env is performed and
any further occurrence of \end{
env'}
is tested
and may get expanded if it matches a pending
\begin{
env'}
construct.
This enables playing tricks such as:
\newenvironment{latexhuge}
{\begin{latexonly}\huge}
{\end{latexonly}}
\begin{latexhuge}
This will appear in huge font in \LaTeX{} output only.
\end{latexhuge}
LATEX output will be:

While there is no HEVEA output.
Since HEVEA somehow analyses input that is enclosed in the
latexonly environment,
it may choke.
However, this environment is intended to select processing by
LATEX only and might contain arbitrary source code.
Fortunately, it remains possible to have input processed by LATEX
only, regardless of what it is, by enclosing it in the
verblatex environment.
Inside this environment, HEVEA performs no other action
than looking for \end{verblatex}
. As a consequence,
the \begin{verblatex}
and \end{verblatex}
constructs
may only appear in the main flow of text or inside the same macro body,
a bit like LATEX verbatim environment.
Relations between toimage and verbimage are similar.
Additionally, formal parameters #
i are replaced by
actual arguments inside the toimage environment
(see end of section 6.3 for an example of this feature).
5.2.3 Bonus macros
By default, HEVEA knows some macros to process a few HTML-related
constructs.
The hevea package defines LATEX equivalents for them.
This first concerns the HEVEA and HACHA logos.
Then, a few macros for URL management are provided
Macro |
|
HEVEA |
LATEX |
|
\url{ url}{ text} |
|
make text an hyper-link to url |
|
echo text |
|
\footurl{ url}{ text} |
|
make text an hyper-link to url |
|
make url a footnote to text,
url is shown in typewriter font |
|
\oneurl{ url} |
|
make url an hyper-link to url. |
|
typeset url in typewriter font |
|
\mailto{ address} |
|
make address a ``mailto'' link to address |
|
typeset address in typewriter font |
|
\home{ text} |
|
produce a home-dir url both for output and links, output aspect is: ``~text''
|
The url and address arguments undergo macro
substitution, however style changes are ignored in the
``HREF=...
'' attribute of the <A ...>
element.
As a consequence one can safely write something like:
\mailto{Luc.Maranget@\textit{inria}.\texttt{fr}}
And one gets Luc.Maranget@inria.fr.
That is, one gets the following correct link:
<A HREF="mailto:Luc.Maranget@inria.fr">...
Additionally, the \imageflush
macro that controls included images
(see section 6) and the \cuttingunit
,
\cuthere
, etc. macros that
control document cutting (see
section 7)
are defined as null macros in the hevea.sty file.
5.2.4 The hevea boolean register
Boolean registers are provided by the ifthen package
(see [LATEX , Section C.8.5] and section B.8.5 in this
document).
Both the hevea.sty style file
and HEVEA define the boolean register hevea.
However, this register initial value is false for LATEX
and true for HEVEA.
Thus, provided, both the hevea.sty style file and the
ifthen packages are loaded, the ``purple rain'' example can
be rephrased as follows:
We get:
{\ifthenelse{\boolean{hevea}}{\purple}{}purple rain, purple rain}\ldots
We get:
purple rain, purple rain...
Another choice is using the TeX-style conditional macro
\ifhevea
(see Section B.16.1):
We get:
{\ifhevea\purple\fi purple rain, purple rain}\ldots
We get: purple rain, purple rain...
5.3 Comments
HEVEA processes all lines that start with %HEVEA
, while
LATEX treats these lines as comments.
Thus, this is a last variation on the ``purple rain'' example:
We get
%HEVEA{\purple
purple rain, purple rain%
%HEVEA}%
\ldots
(Note how comments are placed at the end of some lines to avoid spurious spaces
in the final output.)
We get:
purple rain, purple rain...
Comments thus provide an alternative to loading the
hevea package. For user convenience, comment equivalents to
the latexonly
and toimage
environment are also provided:
|
environment |
comment
equivalent |
|
\begin{latexonly} ... \end{latexonly} |
%BEGIN LATEX |
... |
%END LATEX
|
|
|
|
|
\begin{toimage} ... \end{toimage} |
%BEGIN IMAGE |
... |
%END IMAGE
|
|
Note that LATEX, by ignoring comments, naturally performs the action
of processing text between %BEGIN
... and %END
... comments. However, no environment is opened and closed and no scope is
created while using comment equivalents.