<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> <HTML> <HEAD> <META http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <META name="GENERATOR" content="hevea 1.10"> <META name="Author" content="Luc Maranget"> <LINK rel="stylesheet" type="text/css" href="manual.css"> <TITLE>With a little help from LATEX</TITLE> </HEAD> <BODY > <A HREF="manual007.html"><IMG SRC="previous_motif.gif" ALT="Previous"></A> <A HREF="manual002.html"><IMG SRC="contents_motif.gif" ALT="Up"></A> <A HREF="cutname.html"><IMG SRC="next_motif.gif" ALT="Next"></A> <HR> <H2 CLASS="section"><A NAME="htoc21">6</A>  With a little help from L<sup>A</sup>T<sub>E</sub>X</H2><UL> <LI><A HREF="manual008.html#toc15">The <I>image</I> file</A> </LI><LI><A HREF="manual008.html#toc16">A toy example</A> </LI><LI><A HREF="manual008.html#toc17">Including Postscript images</A> </LI><LI><A HREF="manual008.html#toc18">Using filters</A> </LI></UL> <P> <A NAME="imagen"></A> Sometimes, H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A just cannot process its input, but it remains acceptable to have L<sup>A</sup>T<sub>E</sub>X process it, to produce a <TT>.gif</TT> image from L<sup>A</sup>T<sub>E</sub>X output and to include a link to this image into H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A output. H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A provides a limited support for doing this.</P><H3 CLASS="subsection"><A NAME="toc15"></A><A NAME="htoc22">6.1</A>  The <I>image</I><A NAME="image:file"></A> file</H3><P>While outputting <EM>doc</EM><TT>.html</TT>, H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A echoes some of its input to the <EM>image</EM> file, <EM>doc</EM><TT>.image.tex</TT>. <A NAME="@default23"></A> Part of this process is done at the user’s request. More precisely, the following two constructs send <I>text</I> to the <EM>image</EM> file: </P><DIV CLASS="flushleft"> <CODE>\begin{toimage}</CODE><BR> <I>text</I><BR> <CODE>\end{toimage}</CODE><BR>  <BR> <CODE>%BEGIN IMAGE</CODE><BR> <I>text</I><BR> <CODE>%END IMAGE</CODE> </DIV><P> Additionally, <CODE>\usepackage</CODE> commands, top-level and global definitions are automatically echoed to the image file. This enables using document-specific commands in <I>text</I> above.</P><P><A NAME="@default24"></A> Output to the image file builds up a current page, which is flushed by the <CODE>\imageflush</CODE> command. This command has the following effect: it outputs a strict page break in the <EM>image</EM> file, increments the image counter and output a <CODE><IMG SRC="</CODE><I>pagename</I><CODE>.gif"></CODE> tag in H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A output file, where <I>pagename</I> is build from the image counter and H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A output file name. Then the <CODE>imagen</CODE> script has to be run by: </P><DIV CLASS="flushleft"> <CODE># imagen</CODE> <EM>doc</EM> </DIV><P> This will process the <EM>doc</EM><TT>.image.tex</TT> file through L<sup>A</sup>T<sub>E</sub>X, <TT>dvips</TT>, <TT>ghostscript</TT> and a few others tools, which must all be present (see section <A HREF="manual044.html#requirements">C.4.1</A>), finally producing one <I>pagename</I><TT>.gif</TT> file per page in the <EM>image</EM> file.</P><P>The usage of <CODE>imagen</CODE> is described at section <A HREF="manual041.html#imagenusage">C.1.5</A>. Note that <TT>imagen</TT> is a simple shell script. Unix users can pass <TT>hevea</TT> the command-line option <A NAME="@default25"></A><TT>-fix</TT>. Then <TT>hevea</TT> will itself call <TT>imagen</TT>, when appropriate.</P><H3 CLASS="subsection"><A NAME="toc16"></A><A NAME="htoc23">6.2</A>  A toy example</H3><P> Consider the “blob” example from section <A HREF="manual006.html#blob">4.2</A>. Here is the active part of a <TT>blob.tex</TT> file: </P><PRE CLASS="verbatim"> \newcommand{\blob}{\rule[.2ex]{1ex}{1ex}} \blob\ Blob \blob </PRE><P>This time, we would like <CODE>\blob</CODE> to produce a small black square, which <CODE>\rule[.2ex]{1ex}{1ex}</CODE> indeed does in L<sup>A</sup>T<sub>E</sub>X. Thus we can write: </P><PRE CLASS="verbatim"> \newcommand{\blob}{% \begin{toimage}\rule[.2ex]{1ex}{1ex}% \end{toimage}% \imageflush} \blob\ Blob \blob </PRE><P>Now we issue the following two commands: </P><PRE CLASS="verbatim"> # hevea blob.tex # imagen blob </PRE><P>And we get: </P><BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center> <IMG SRC="manual005.gif"> Blob <IMG SRC="manual005.gif"> <HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE><P>Observe that the trick can be used to replace missing symbols by small <TT>.gif</TT> 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 <CODE>\savebox</CODE>, but the other problems remain.</P><H3 CLASS="subsection"><A NAME="toc17"></A><A NAME="htoc24">6.3</A>  Including Postscript images</H3><P><A NAME="substimage"></A> <A NAME="@default26"></A> In this section, a technique to transform included Postscript images into included GIF images is described. Note that this technique is used by H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A implementation of the <TT>graphics</TT> package (see section <A HREF="manual036.html#graphics">B.14.1</A>), which provides a more standard manner to include Postscript images in L<sup>A</sup>T<sub>E</sub>X documents.</P><P>Included images are easy to manage: it suffices to let L<sup>A</sup>T<sub>E</sub>X do the job. Let <TT>round.ps</TT> be a Postscript file, which is included as an image in the source file <TT>round.tex</TT> (which must load the <EM>epsf</EM> package): </P><PRE CLASS="verbatim"> \begin{center} \epsfbox{round.ps} \end{center} </PRE><P>Then, H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A can have this image translated into a inlined (and centered) <TT>.gif</TT> image by modifying source as follows: </P><PRE CLASS="verbatim"> \begin{center} %BEGIN IMAGE \epsfbox{round.ps} %END IMAGE %HEVEA\imageflush \end{center} </PRE><P>(Note that the <TT>round.tex</TT> file still can be processed by L<sup>A</sup>T<sub>E</sub>X, since comment equivalents of the <TT>toimage</TT> environment are used and that the <CODE>\imageflush</CODE> command is inside a <CODE>%HEVEA</CODE> comment — see section <A HREF="manual007.html#comments">5.3</A>.)</P><P>Then, processing <TT>round.tex</TT> through H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A and <TT>imagen</TT> yields: </P><BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center> <DIV CLASS="center"> <IMG SRC="manual006.gif"></DIV> <HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE><P> It is important to notice that things go smoothly because the <CODE>\usepackage{epsf}</CODE> command gets echoed to the <EM>image</EM> file. In more complicated cases, L<sup>A</sup>T<sub>E</sub>X may fail on the <EM>image</EM> file because it does not load the right packages or define the right macros.</P><P>However, the above solution implies modifying the original L<sup>A</sup>T<sub>E</sub>X source code. A better solution is to define the <CODE>\epsfbox</CODE> command, so that H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A echoes <CODE>\epsfbox</CODE> and its argument to the image file and performs <CODE>\imageflush</CODE>: </P><PRE CLASS="verbatim"> \newcommand{\epsfbox}[1]{% \begin{toimage} \epsfbox{#1} \end{toimage} \imageflush} </PRE><P>Such a definition must be seen by H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A only. So, it is best put in a separate file whose name is given as an extra argument on H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A command-line (see section <A HREF="manual007.html#heveaonly">5.1</A>). Putting it in the document source protected inside an <CODE>%HEVEA</CODE> comment is a bad idea, because it might then get echoed to the <I>image</I> file and generate trouble when L<sup>A</sup>T<sub>E</sub>X is later run by <TT>imagen</TT>.</P><P>Observe that the above definition of <CODE>\epsfbox</CODE> is a definition and not a redefinition (<EM>i.e.</EM> <CODE>\newcommand</CODE> is used and not <CODE>\renewcommand</CODE>), because H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A does not know about <CODE>\epsfbox</CODE> by default. Also observe that this not a recursive definition, since commands do not get expanded inside the <CODE>toimage</CODE> environment.</P><P>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 GIF file from the bitmap source independantly and then to include a link to that GIF file in HTML output, see section <A HREF="manual018.html#imgsrc">8.2</A> for a description of this more adequate technique.</P><H3 CLASS="subsection"><A NAME="toc18"></A><A NAME="htoc25">6.4</A>  Using filters</H3><P>Some programs extend L<sup>A</sup>T<sub>E</sub>X 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<sup>A</sup>T<sub>E</sub>X source changes these fragments into constructs that L<sup>A</sup>T<sub>E</sub>X (or a subsequent stage in the paper document production chain, such as <TT>dvips</TT>) can handle. Here again, the rule of the game is keeping H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A away from the normal process: first applying the filter, then making H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A send the filter output to the <EM>image</EM> file, and then having <TT>imagen</TT> do the job.</P><P>Consider the <TT>gpic</TT> filter, for making drawings. Source for <TT>gpic</TT> is enclosed in <CODE>.PS</CODE>…<CODE>.PE</CODE>, then the result is available to subsequent L<sup>A</sup>T<sub>E</sub>X source as a T<sub>E</sub>X box <CODE>\box\graph</CODE>. For instance the following source, from a <TT>smile.tex</TT> file, draws a “Smile!” logo as a centered paragraph: </P><PRE CLASS="verbatim"> .PS ellipse "{\Large\bf Smile!}" .PE \begin{center} ~\box\graph~ \end{center} </PRE><P>Both the image description (<CODE>.PS</CODE>… <CODE>.PE</CODE>) and usage (<CODE>\box\graph</CODE>) are for the <EM>image</EM> file, and they should be enclosed by <CODE>%BEGIN IMAGE</CODE>… <CODE>%END IMAGE</CODE> comments. Additionally, the image link is put where it belongs by an <CODE>\imageflush</CODE> command: </P><PRE CLASS="verbatim"> %BEGIN IMAGE .PS ellipse "{\Large\bf Smile!}" .PE %END IMAGE \begin{center} %BEGIN IMAGE ~\box\graph~ %END IMAGE %HEVEA\imageflush \end{center} </PRE><P>The <TT>gpic</TT> filter is applied first, then come <TT>hevea</TT> and <TT>imagen</TT>: </P><PRE CLASS="verbatim"> # gpic -t < smile.tex > tmp.tex # hevea tmp.tex -o smile.html # imagen smile </PRE><P>And we get: </P><DIV CLASS="center"> <IMG SRC="manual007.gif"></DIV><P> Observe how the <CODE>-o</CODE> argument to H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A is used and that <TT>imagen</TT> argument is H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A output basename (see section <A HREF="manual041.html#basenames">C.1.1.2</A> for the full definition of H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A output basename).</P><P>In the <TT>gpic</TT> 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 <TT>gpic</TT> pictures in L<sup>A</sup>T<sub>E</sub>X: </P><PRE CLASS="verbatim"> \newenvironment{centergpic}{}{\begin{center}~\box\graph~\end{center}} </PRE><P>Source code will now be as follows: </P><PRE CLASS="verbatim"> \begin{centergpic} .PS ellipse "{\Large\bf Smile!}" .PE \end{centergpic} </PRE><P>H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A will process this source correctly, provided it is given its own definition for the <CODE>centergpic</CODE> environment beforehand: </P><PRE CLASS="verbatim"> \newenvironment{centergpic} {\begin{toimage}} {\box\graph\end{toimage}\begin{center}\imageflush\end{center}} </PRE><P>Assuming that the definition above is in a <A HREF="http://hevea.inria.fr/examples/smile.hva">smile.hva</A> file, the command sequence for translating <A HREF="http://hevea.inria.fr/examples/smile.tex">smile.tex</A> now is: </P><PRE CLASS="verbatim"> # 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 </PRE><P>The warnings above are normal: they are issued when H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A runs across the L<sup>A</sup>T<sub>E</sub>X-intended definition of the <CODE>centergpic</CODE> environment and refuses to override its own definition for that environment.</P><HR> <A HREF="manual007.html"><IMG SRC="previous_motif.gif" ALT="Previous"></A> <A HREF="manual002.html"><IMG SRC="contents_motif.gif" ALT="Up"></A> <A HREF="cutname.html"><IMG SRC="next_motif.gif" ALT="Next"></A> </BODY> </HTML>