5 Making H^EV^EA and L^AT_EX both happy

• File loading
• The hevea package
• Comments

A satisfactory translation from L^AT_EX to html often requires giving instructions to H^EV^EA. Typically, these instructions are macro definitions and these instructions should not be seen by L^AT_EX. Conversely, some source that L^AT_EX needs should not be processed by H^EV^EA. Basically, there are three ways to make input vary according to the processor, file loading, the hevea package and comments.

5.1 File loading

H^EV^EA and L^AT_EX treat files differently. Here is a summary of the main differences:

• L^AT_EX and H^EV^EA both load files given as arguments to \input, however when given the option -e filename, H^EV^EA does not load filename.
• H^EV^EA loads all files given as command-line arguments.
• Both L^AT_EX and H^EV^EA 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 L^AT_EX only, it suffices to use \input{latexonly} in the source and to invoke H^EV^EA as follows:

Having heveaonly loaded by H^EV^EA only is more simple: it suffices to invoke H^EV^EA as follows:

Finally, if one has an H^EV^EA equivalent style.hva for a L^AT_EX style file style.sty, then one should load the file as follows:

This will result in, L^AT_EX loading style.sty, while H^EV^EA loads style.hva. As H^EV^EA will not fail in case style.hva does not exist, this is another method for having a style file loaded by L^AT_EX only.

Writing an H^EV^EA-specific file file.hva is the method of choice for supplying command definitions to H^EV^EA only. Users can then be sure that these definitions are not seen by L^AT_EX and will not get echoed to the image file (see section 6).

The file file.hva can be loaded by either supplying the command-line argument file.hva, or by \usepackage{file} from inside the document. Which method is better depends on whether you choose to override or to replace the document definition. In the command-line case, definitions from file.hva are processed before the ones from the document and will override them, provided the document definitions are made using \newcommand (or \newenvironment). In the \usepackage case, H^EV^EA loads file.hva at the place where L^AT_EX loads file.sty, hence the definitions from file.hva replace the definitions from file.sty in the strict sense.

5.2 The hevea package

The hevea.sty style file is intended to be loaded by L^AT_EX and not by H^EV^EA. It provides L^AT_EX with means to ignore or process some parts of the document. Note that H^EV^EA 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 L^AT_EX 2є terms and that it is not compatible with old L^AT_EX. Moreover, the hevea package loads the comment package which must be present. Also notice that, for compatibility, H^EV^EA reacts to \usepackage{hevea} by loading its own version of the comment package (Section B.17.7).

5.2.1 Environments for selecting a translator

H^EV^EA and L^AT_EX perform the following actions on source inside the latexonly, verblatex, htmlonly, rawhtml, toimage and verbimage environments:

As an example, this is how some text can be typeset in purple by H^EV^EA and left alone by L^AT_EX:

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 H^EV^EA 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 L^AT_EX 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. However, as an exception, the environments image and verbimage do not create scope. It takes a little practice of H^EV^EA to understand why this is convenient.

5.2.2 Why are there two environments for ignoring input?

Some scanning and analysis of source is performed by H^EV^EA 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 \endenv 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}

L^AT_EX output will be:

While there is no H^EV^EA output.

Since H^EV^EA somehow analyses input that is enclosed in the latexonly environment, it may choke. However, this environment is intended to select processing by L^AT_EX only and might contain arbitrary source code. Fortunately, it remains possible to have input processed by L^AT_EX only, regardless of what it is, by enclosing it in the verblatex environment. Inside this environment, H^EV^EA 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 L^AT_EX 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 [L^AT_EX, Section C.8.5] and section B.8.5 in this document). Both the hevea.sty style file and H^EV^EA define the boolean register hevea. However, this register initial value is false for L^AT_EX and true for H^EV^EA.

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 T_EX-style conditional macro \ifhevea (see Section B.16.1.4):

We get:
{\ifhevea\purple\fi purple rain, purple rain}\ldots

We get: purple rain, purple rain…

5.3 Comments

H^EV^EA processes all lines that start with %HEVEA, while L^AT_EX 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:

Note that L^AT_EX, 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.