1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
|
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="generator" content="hevea 2.36">
<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="c023">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="c020"><sup>E</sup></span>V<span class="c020"><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="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A
output.
H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A provides a limited support for doing this.</p>
<h3 class="subsection" id="image:file">6.1 The <span class="c023">image</span> file</h3>
<p>While outputting <em>doc</em><span class="c017">.html</span>, H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A echoes some
of its input to the <em>image</em> file,
<em>doc</em><span class="c017">.image.tex</span>.
<a id="hevea_default26"></a>
Part of this process is done at the user’s request.
More precisely, the following two constructs
send <span class="c023">text</span> to the <em>image</em> file:
</p><div class="flushleft">
<code class="verb">\begin{toimage}</code><br>
<span class="c023">text</span><br>
<code class="verb">\end{toimage}</code><br>
 <br>
<code class="verb">%BEGIN IMAGE</code><br>
<span class="c023">text</span><br>
<code class="verb">%END IMAGE</code>
</div><p>
Additionally, <code class="verb">\usepackage</code> commands, top-level and global
definitions
are automatically echoed to the image file. This enables using
document-specific commands in <span class="c023">text</span> above.</p><p><a id="hevea_default27"></a>
Output to the image file builds up a current page, which is flushed
by the <code class="verb">\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 class="verb"><img src="</code><span class="c023">pagename</span><code class="verb">.png"></code> tag in H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A
output file, where <span class="c023">pagename</span> is build from the image counter
and H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A output file name.
Then the <code class="verb">imagen</code> script has to be run by:
</p><div class="flushleft">
<code class="verb"># imagen</code> <em>doc</em>
</div><p>
This will process the <em>doc</em><span class="c017">.image.tex</span>
file through L<sup>A</sup>T<sub>E</sub>X,
<span class="c017">dvips</span>, <span class="c017">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="c023">pagename</span><span class="c017">.png</span> file per page in the <em>image</em>
file.</p><p>The usage of <code class="verb">imagen</code> is described at
section <a href="manual041.html#imagenusage">C.1.5</a>. Note that <span class="c017">imagen</span> is a simple shell
script. Unix users can pass <span class="c017">hevea</span> the command-line option
<a id="hevea_default28"></a><span class="c017">-fix</span>. Then <span class="c017">hevea</span> will
itself call <span class="c017">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="c017">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 class="verb">\blob</code> to produce a small black square, which
<code class="verb">\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="c017">.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 class="verb">\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_default29"></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="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A implementation of the
<span class="c017">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="c017">round.ps</span> be a Postscript file, which is included as an
image in the source file <span class="c017">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="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A can have this image translated into a inlined (and
centered) <span class="c017">.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="c017">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="c017">toimage</span> environment are used and that
the <code class="verb">\imageflush</code> command is inside
a <code class="verb">%HEVEA</code> comment — see section <a href="manual007.html#comments">5.3</a>.)</p><p>Then, processing <span class="c017">round.tex</span> through H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A and
<span class="c017">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 class="verb">\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 class="verb">\epsfbox</code>
command, so that H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A echoes <code class="verb">\epsfbox</code> and its argument to
the image file and performs <code class="verb">\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="c020"><sup>E</sup></span>V<span class="c020"><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="c020"><sup>E</sup></span>V<span class="c020"><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 class="verb">%HEVEA</code> comment is a bad idea, because it might then get echoed to the <span class="c023">image</span> file
and generate trouble when L<sup>A</sup>T<sub>E</sub>X is later run by <span class="c017">imagen</span>.</p><p>Observe that the above definition of <code class="verb">\epsfbox</code> is a definition
and not a redefinition (<em>i.e.</em> <code class="verb">\newcommand</code> is used and not
<code class="verb">\renewcommand</code>),
because H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A does not know about <code class="verb">\epsfbox</code> by default.
Also observe that this not a recursive definition, since
commands do not get expanded inside the <code class="verb">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="c017">dvips</span>) can handle.
Here again, the rule of the game is keeping H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A away from the
normal process: first applying the filter, then making H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A send
the filter output to the <em>image</em> file, and then having
<span class="c017">imagen</span> do the job.</p><p>Consider the <span class="c017">gpic</span> filter, for making drawings.
Source for <span class="c017">gpic</span> is enclosed in <code class="verb">.PS</code>…<code class="verb">.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 class="verb">\box\graph</code>.
For instance the following source, from a <span class="c017">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 class="verb">.PS</code>… <code class="verb">.PE</code>) and usage (<code class="verb">\box\graph</code>)
are for the <em>image</em> file, and they should be
enclosed by <code class="verb">%BEGIN IMAGE</code>… <code class="verb">%END IMAGE</code> comments.
Additionally, the image link is put where it belongs by an
<code class="verb">\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="c017">gpic</span> filter is applied first, then come <span class="c017">hevea</span>
and <span class="c017">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 class="verb">-o</code> argument to H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A is used and that
<span class="c017">imagen</span> argument is H<span class="c020"><sup>E</sup></span>V<span class="c020"><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="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A output basename).</p><p>In the <span class="c017">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="c017">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="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A will process this source correctly, provided it is given its
own definition for the <code class="verb">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="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A runs
across the L<sup>A</sup>T<sub>E</sub>X-intended definition of the <code class="verb">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>
|
