Google

"http://www.w3.org/TR/REC-html40/loose.dtd"> Making HEVEA and LATEX both happy Previous Up Next
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.

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

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.

Writing an HEVEA-specific file file.hva 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).

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 it is choosed 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, HEVEA loads file.hva at the place where LATEX 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 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. However, as an exception, the environments image and verbimage do not create scope. It takes a little practice of HEVEA 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 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 \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}
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.

Previous Up Next