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 package
and comments.
HEVEA and LATEX treat files differently. Here is a summary of the main
differences:
-
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.
- Both LATEX and HEVEA load style files given as optional
arguments to
\documentstyle
and as arguments to \usepackage
,
but the files are searched by following different methods and
considering different file extensions.
As a consequence, for having a file latexonly loaded by
LATEX only, it suffices
o 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).
Finally, if one has an HEVEA equivalent style.hva
for a LATEX style file style.sty,
then one should load the file as follows:
\usepackage{
style}
This will result in, LATEX loading style.sty,
while HEVEA loads style.hva.
As HEVEA will not fail in case style.hva does not
exist, this is another method for having a style file loaded by
LATEX only.
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.
It is important to notice that the hevea.sty style file from
the distribution is a package in LATEX 2e terms and that it
is not compatible with old LATEX. Moreover, the hevea
package loads the comment package which must be present.
5.2.1 |
Environments for 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 (see section 5.2.2) |
|
process |
verblatex |
|
ignore |
|
process |
htmlonly |
|
process |
|
ignore |
rawhtml |
|
echo verbatim (see section 8.3) |
|
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 HEVEA output
for the source above.
This extra spaces comes from the newline character that follows
\end{htmlonly}
. Namely this
construct must appear in a line of its own for
LATEX to recognize it. Anyway, better control over spaces
can be achieved
by using the hevea boolean register
or comments, see sections 5.2.3
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 are there two environments for ignoring input? |
|
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 |
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.2.4):
We get:
{\ifhevea\purple\fi purple rain, purple rain}\ldots
We get: purple rain, purple rain...
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.