6  With a little help from L^AT_EX

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

Sometimes, H^EV^EA just cannot process its input, but it remains acceptable to have L^AT_EX process it, to produce an image from L^AT_EX output and to include a link to this image into H^EV^EA output. H^EV^EA provides a limited support for doing this.

6.1  The image file

While outputting doc.html, H^EV^EA 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:

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 H^EV^EA output file, where pagename is build from the image counter and H^EV^EA output file name. Then the imagen script has to be run by:

This will process the doc.image.tex file through L^AT_EX, 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 L^AT_EX. 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 H^EV^EA implementation of the graphics package (see section B.14.1), which provides a more standard manner to include Postscript images in L^AT_EX documents.

Included images are easy to manage: it suffices to let L^AT_EX 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, H^EV^EA 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 L^AT_EX, 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 H^EV^EA 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, L^AT_EX 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 L^AT_EX source code. A better solution is to define the \epsfbox command, so that H^EV^EA 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 H^EV^EA only. So, it is best put in a separate file whose name is given as an extra argument on H^EV^EA 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 L^AT_EX 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 H^EV^EA 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 L^AT_EX capabilities using a filter principle. In such a scheme, the document contains source fragments for the program. A first run of the program on L^AT_EX source changes these fragments into constructs that L^AT_EX (or a subsequent stage in the paper document production chain, such as dvips) can handle. Here again, the rule of the game is keeping H^EV^EA away from the normal process: first applying the filter, then making H^EV^EA 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 L^AT_EX source as a T_EX 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 H^EV^EA is used and that imagen argument is H^EV^EA output basename (see section C.1.1.2 for the full definition of H^EV^EA 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 L^AT_EX:

 \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}

H^EV^EA 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 H^EV^EA runs across the L^AT_EX-intended definition of the centergpic environment and refuses to override its own definition for that environment.