<!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>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
e8b7ce893d130f732758286a15c74b5e
>
files
>
29
