<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="generator" content="hevea 2.32">
<meta name="Author" content="Luc Maranget">
<script type="text/javascript" async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-MML-AM_CHTML"></script><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.svg" alt="Previous"></a>
<a href="manual002.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="cutname.html"><img src="next_motif.svg" alt="Next"></a>
<hr>
<h2 class="section" id="imagen">6  With a little help from L<sup>A</sup>T<sub>E</sub>X</h2>
<ul>
<li><a href="manual008.html#image%3Afile">The <span class="c019">image</span> file</a>
</li><li><a href="manual008.html#sec38">A toy example</a>
</li><li><a href="manual008.html#sec39">Including Postscript images</a>
</li><li><a href="manual008.html#sec40">Using filters</a>
</li></ul>
<p>
Sometimes,
H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>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 an image from
L<sup>A</sup>T<sub>E</sub>X output and to include a link to this image into H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A
output.
H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A provides a limited support for doing this.</p>
<h3 class="subsection" id="image:file">6.1  The <span class="c019">image</span> file</h3>
<p>While outputting <em>doc</em><span class="c013">.html</span>, H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A echoes some
of its input to the <em>image</em> file,
<em>doc</em><span class="c013">.image.tex</span>.
<a id="hevea_default25"></a>
Part of this process is done at the user’s request.
More precisely, the following two constructs
send <span class="c019">text</span> to the <em>image</em> file:
</p><div class="flushleft">
<code>\begin{toimage}</code><br>
<span class="c019">text</span><br>
<code>\end{toimage}</code><br>
 <br>
<code>%BEGIN IMAGE</code><br>
<span class="c019">text</span><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 <span class="c019">text</span> above.</p><p><a id="hevea_default26"></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><span class="c019">pagename</span><code>.png"></code> tag in H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A
output file, where <span class="c019">pagename</span> is build from the image counter
and H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>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><span class="c013">.image.tex</span>
file through L<sup>A</sup>T<sub>E</sub>X,
<span class="c013">dvips</span>, <span class="c013">ghostscript</span> and a few others tools, which must all be
present (see section <a href="manual044.html#requirements">C.4.1</a>), finally producing one
<span class="c019">pagename</span><span class="c013">.png</span> 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 <span class="c013">imagen</span> is a simple shell
script. Unix users can pass <span class="c013">hevea</span> the command-line option
<a id="hevea_default27"></a><span class="c013">-fix</span>. Then <span class="c013">hevea</span> will
itself call <span class="c013">imagen</span>, when appropriate.</p>
<h3 class="subsection" id="sec38">6.2  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 <span class="c013">blob.tex</span> 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">
<img src="manual005.png"> Blob <img src="manual005.png">
</blockquote><p>Observe that the trick can be used to replace missing symbols by small
<span class="c013">.png</span> 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" id="sec39">6.3  Including Postscript images</h3>
<p><a id="substimage"></a>
<a id="hevea_default28"></a>
In this section, a technique to transform included Postscript images
into included bitmap images is described.
Note that this technique is used by H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A implementation of the
<span class="c013">graphics</span> 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 <span class="c013">round.ps</span> be a Postscript file, which is included as an
image in the source file <span class="c013">round.tex</span> (which must load the
<em>epsf</em> package):
</p><pre class="verbatim"> \begin{center}
\epsfbox{round.ps}
\end{center}
</pre><p>
Then, H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A can have this image translated into a inlined (and
centered) <span class="c013">.png</span> 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 <span class="c013">round.tex</span> file
still can be processed by L<sup>A</sup>T<sub>E</sub>X, since comment equivalents
of the <span class="c013">toimage</span> 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 <span class="c013">round.tex</span> through H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A and
<span class="c013">imagen</span> yields:
</p><blockquote class="quote">
<div class="center">
<img src="manual006.png"></div>
</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<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>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<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A only. So, it is best put
in a separate file whose name is given as an extra argument on
H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>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 <span class="c019">image</span> file
and generate trouble when L<sup>A</sup>T<sub>E</sub>X is later run by <span class="c013">imagen</span>.</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<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>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 PNG file from the bitmap source
independantly
and then to include a link to that PNG 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" id="sec40">6.4  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 <span class="c013">dvips</span>) can handle.
Here again, the rule of the game is keeping H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A away from the
normal process: first applying the filter, then making H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A send
the filter output to the <em>image</em> file, and then having
<span class="c013">imagen</span> do the job.</p><p>Consider the <span class="c013">gpic</span> filter, for making drawings.
Source for <span class="c013">gpic</span> 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 <span class="c013">smile.tex</span> 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 <span class="c013">gpic</span> filter is applied first, then come <span class="c013">hevea</span>
and <span class="c013">imagen</span>:
</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.png"></div><p>
Observe how the <code>-o</code> argument to H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A is used and that
<span class="c013">imagen</span> argument is H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A output basename (see
section <a href="manual041.html#basenames">C.1.1.2</a> for the full definition of H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A output basename).</p><p>In the <span class="c013">gpic</span> 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 <span class="c013">gpic</span> 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<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>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<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>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.svg" alt="Previous"></a>
<a href="manual002.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="cutname.html"><img src="next_motif.svg" alt="Next"></a>
</body>
</html>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-release
>
by-pkgid
>
fe880a8a8b91ae0b29da8fb72f3c41de
>
files
>
43
