With a little help from LATEX
Author: Luc Maranget

## 6 With a little help from LATEX

- The image file
- A toy example
- Including Postscript images
- Using filters

Sometimes, HEVEA just cannot process its input, but it remains acceptable to have LATEX process it, to produce an image from LATEX output and to include a link to this image into HEVEA output. HEVEA provides a limited support for doing this.

### 6.1 The image file

While outputting doc.html, HEVEA echoes some of its input to the image file, doc.image.tex. Part of this process is done at the user’s request. More precisely, the following two constructs send text to the image file:

`\begin{toimage}`
text
`\end{toimage}`
`%BEGIN IMAGE`
text
`%END IMAGE`

Additionally, `\usepackage` commands, top-level and global definitions are automatically echoed to the image file. This enables using document-specific commands in text above.

Output to the image file builds up a current page, which is flushed by the `\imageflush` command. This command has the following effect: it outputs a strict page break in the image file, increments the image counter and output a `<img src="`pagename`.png">` tag in HEVEA output file, where pagename is build from the image counter and HEVEA output file name. Then the `imagen` script has to be run by:

`# imagen` doc

This will process the doc.image.tex file through LATEX, dvips, ghostscript and a few others tools, which must all be present (see section C.4.1), finally producing one pagename.png file per page in the image file.

The usage of `imagen` is described at section C.1.5. Note that imagen is a simple shell script. Unix users can pass hevea the command-line option -fix. Then hevea will itself call imagen, when appropriate.

### 6.2 A toy example

Consider the “blob” example from section 4.2. Here is the active part of a blob.tex file:

     \newcommand{\blob}{\rule[.2ex]{1ex}{1ex}}
     \blob\ Blob \blob

This time, we would like `\blob` to produce a small black square, which `\rule[.2ex]{1ex}{1ex}` indeed does in LATEX. Thus we can write:

     \newcommand{\blob}{%
     \begin{toimage}\rule[.2ex]{1ex}{1ex}%
     \end{toimage}%
     \imageflush}
     \blob\ Blob \blob

Now we issue the following two commands:

     # hevea blob.tex
     # imagen blob

And we get:

> Blob

Observe that the trick can be used to replace missing symbols by small .png images. However, the cost may be prohibitive, text rendering is generally bad, fine placement is ignored and font style changes are problematic. Cost can be lowered using `\savebox`, but the other problems remain.

### 6.3 Including Postscript images

In this section, a technique to transform included Postscript images into included bitmap images is described. Note that this technique is used by HEVEA implementation of the graphics package (see section B.14.1), which provides a more standard manner to include Postscript images in LATEX documents.

Included images are easy to manage: it suffices to let LATEX do the job. Let round.ps be a Postscript file, which is included as an image in the source file round.tex (which must load the epsf package):

     \begin{center}
     \epsfbox{round.ps}
     \end{center}

Then, HEVEA can have this image translated into a inlined (and centered) .png image by modifying source as follows:

     \begin{center}
     %BEGIN IMAGE
     \epsfbox{round.ps}
     %END IMAGE
     %HEVEA\imageflush
     \end{center}

(Note that the round.tex file still can be processed by LATEX, since comment equivalents of the toimage environment are used and that the `\imageflush` command is inside a `%HEVEA` comment — see section 5.3.)

Then, processing round.tex through HEVEA and imagen yields:

It is important to notice that things go smoothly because the `\usepackage{epsf}` command gets echoed to the image file. In more complicated cases, LATEX may fail on the image file because it does not load the right packages or define the right macros.

However, the above solution implies modifying the original LATEX source code. A better solution is to define the `\epsfbox` command, so that HEVEA echoes `\epsfbox` and its argument to the image file and performs `\imageflush`:

     \newcommand{\epsfbox}[1]{%
     \begin{toimage}
     \epsfbox{#1}
     \end{toimage}
     \imageflush}

Such a definition must be seen by HEVEA only. So, it is best put in a separate file whose name is given as an extra argument on HEVEA command-line (see section 5.1). Putting it in the document source protected inside an `%HEVEA` comment is a bad idea, because it might then get echoed to the image file and generate trouble when LATEX is later run by imagen.

Observe that the above definition of `\epsfbox` is a definition and not a redefinition (i.e. `\newcommand` is used and not `\renewcommand`), because HEVEA does not know about `\epsfbox` by default. Also observe that this not a recursive definition, since commands do not get expanded inside the `toimage` environment.

Finally, if the Postscript image is produced from a bitmap, it is a pity to translate it back into a bitmap. A better idea is first to generate a PNG file from the bitmap source independantly and then to include a link to that PNG file in html output, see section 8.2 for a description of this more adequate technique.

### 6.4 Using filters

Some programs extend LATEX capabilities using a filter principle. In such a scheme, the document contains source fragments for the program. A first run of the program on LATEX source changes these fragments into constructs that LATEX (or a subsequent stage in the paper document production chain, such as dvips) can handle. Here again, the rule of the game is keeping HEVEA away from the normal process: first applying the filter, then making HEVEA send the filter output to the image file, and then having imagen do the job.

Consider the gpic filter, for making drawings. Source for gpic is enclosed in `.PS`…`.PE`, then the result is available to subsequent LATEX source as a TEX box `\box\graph`. For instance the following source, from a smile.tex file, draws a “Smile!” logo as a centered paragraph:

     .PS
     ellipse "{\Large\bf Smile!}"
     .PE
     \begin{center}
     ~\box\graph~
     \end{center}

Both the image description (`.PS`… `.PE`) and usage (`\box\graph`) are for the image file, and they should be enclosed by `%BEGIN IMAGE`… `%END IMAGE` comments. Additionally, the image link is put where it belongs by an `\imageflush` command:

     %BEGIN IMAGE
     .PS
     ellipse "{\Large\bf Smile!}"
     .PE
     %END IMAGE
     \begin{center}
     %BEGIN IMAGE
     ~\box\graph~
     %END IMAGE
     %HEVEA\imageflush
     \end{center}

The gpic filter is applied first, then come hevea and imagen:

     # gpic -t < smile.tex > tmp.tex
     # hevea tmp.tex -o smile.html
     # imagen smile

And we get:

Observe how the `-o` argument to HEVEA is used and that imagen argument is HEVEA output basename (see section C.1.1.2 for the full definition of HEVEA output basename).

In the gpic example, modifying user source cannot be totally avoided. However, writing in a generic style saves typing. For instance, users may define the following environment for centered gpic pictures in LATEX:

     \newenvironment{centergpic}{}{\begin{center}~\box\graph~\end{center}}

Source code will now be as follows:

     \begin{centergpic}
     .PS
     ellipse "{\Large\bf Smile!}"
     .PE
     \end{centergpic}

HEVEA will process this source correctly, provided it is given its own definition for the `centergpic` environment beforehand:

     \newenvironment{centergpic}
       {\begin{toimage}}
       {\box\graph\end{toimage}\begin{center}\imageflush\end{center}}

Assuming that the definition above is in a smile.hva file, the command sequence for translating smile.tex now is:

     # gpic -t < smile.tex > tmp.tex
     # hevea smile.hva tmp.tex -o smile.html
     tmp.tex:5: Warning: ignoring definition of \centergpic
     tmp.tex:5: Warning: not defining environment centergpic
     # imagen smile

The warnings above are normal: they are issued when HEVEA runs across the LATEX-intended definition of the `centergpic` environment and refuses to override its own definition for that environment.