5 | Making H E V E A and LATEX both happy

- File loading
- The `hevea` package
- Comments

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.

5.1 | File loading

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.

5.2 | The `hevea` package

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

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.