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
258
259
260
261
262
263
264
|
<!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>Making HEVEA and LATEX both happy</title>
</head>
<body>
<a href="manual006.html"><img src="previous_motif.svg" alt="Previous"></a>
<a href="manual002.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="manual008.html"><img src="next_motif.svg" alt="Next"></a>
<hr>
<h2 class="section" id="both">5 Making H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A and L<sup>A</sup>T<sub>E</sub>X both happy</h2>
<ul>
<li><a href="manual007.html#sec30">File loading</a>
</li><li><a href="manual007.html#heveastyle">The <span class="c017">hevea</span> package</a>
</li><li><a href="manual007.html#sec35">Comments</a>
</li></ul>
<p>
A satisfactory translation from L<sup>A</sup>T<sub>E</sub>X to html often requires
giving instructions to H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A.
Typically, these instructions are macro definitions and
these instructions should not be seen by L<sup>A</sup>T<sub>E</sub>X.
Conversely, some source that L<sup>A</sup>T<sub>E</sub>X needs should not be processed
by H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A.
Basically, there are three ways to make input vary according to the
processor, file loading, the <span class="c017">hevea</span> package
and comments.</p>
<h3 class="subsection" id="sec30">5.1 File loading</h3>
<p><a id="fileloading"></a></p><p>H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A and L<sup>A</sup>T<sub>E</sub>X treat files differently. Here is a summary of the main
differences:</p><ul class="itemize"><li class="li-itemize">L<sup>A</sup>T<sub>E</sub>X and H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A both load files given as arguments to
<code class="verb">\input</code>, however when given the option <code class="verb">-e</code> <em>filename</em>,
H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A does not load <em>filename</em>.
</li><li class="li-itemize">H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A loads all files given as command-line arguments.
</li><li class="li-itemize">Both L<sup>A</sup>T<sub>E</sub>X and H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A load style files given as optional
arguments to
<code class="verb">\documentstyle</code> and as arguments to <code class="verb">\usepackage</code>,
but the files are searched by following different methods and
considering different file extensions.
</li></ul><p>As a consequence, for having a file <em>latexonly</em> loaded by
L<sup>A</sup>T<sub>E</sub>X only, it suffices
to use <code class="verb">\input{</code><em>latexonly</em><code class="verb">}</code>
in the source and to invoke H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A as follows:
</p><div class="flushleft">
<code class="verb"># hevea</code> <span class="c017">-e</span> <em>latexonly</em>…</div><p><a id="heveaonly"></a>Having <em>heveaonly</em> loaded by H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A only is more
simple: it suffices to invoke H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A as follows:
</p><div class="flushleft">
<code class="verb"># hevea</code> <em>heveaonly</em>…</div><p>Finally, if one has an H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A equivalent <span class="c023">style</span><span class="c017">.hva</span>
for a L<sup>A</sup>T<sub>E</sub>X style file <span class="c023">style</span><span class="c017">.sty</span>,
then one should load the file as follows:
</p><div class="flushleft">
<code class="verb">\usepackage{</code><span class="c023">style</span><code class="verb">}</code>
</div><p>
This will result in, L<sup>A</sup>T<sub>E</sub>X loading <span class="c023">style</span><span class="c017">.sty</span>,
while H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A loads <span class="c023">style</span><span class="c017">.hva</span>.
As H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A will not fail in case <span class="c023">style</span><span class="c017">.hva</span> does not
exist, this is another method for having a style file loaded by
L<sup>A</sup>T<sub>E</sub>X only.</p><p>Writing an H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A-specific file <span class="c023">file</span><span class="c017">.hva</span>
is the method of choice for supplying command definitions
to H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A only. Users can then be sure that these definitions are
not seen by L<sup>A</sup>T<sub>E</sub>X and will not get echoed to the <span class="c023">image</span>
file (see section <a href="manual008.html#imagen">6</a>).</p><p>The file <span class="c023">file</span><span class="c017">.hva</span> can be loaded by either
supplying the command-line argument
<span class="c023">file</span><span class="c017">.hva</span>, or by
<code class="verb">\usepackage{</code><span class="c023">file</span><code class="verb">}</code> from inside the document.
Which method is better depends
on whether you choose to override or to replace the document
definition.
In the command-line case,
definitions from <span class="c023">file</span><span class="c017">.hva</span> are processed before the
ones from the document and will override them, provided
the document definitions are made using <code class="verb">\newcommand</code> (or
<code class="verb">\newenvironment</code>).
In the <code class="verb">\usepackage</code> case, H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A loads <span class="c023">file</span><span class="c017">.hva</span>
at the place where L<sup>A</sup>T<sub>E</sub>X loads <span class="c023">file</span><span class="c017">.sty</span>, hence
the definitions from <span class="c023">file</span><span class="c017">.hva</span> replace
the definitions from <span class="c023">file</span><span class="c017">.sty</span> in the strict sense.</p>
<h3 class="subsection" id="heveastyle">5.2 The <span class="c017">hevea</span> package</h3>
<p>
<a id="hevea_default9"></a>The <span class="c017">hevea.sty</span> style file is intended to be loaded by L<sup>A</sup>T<sub>E</sub>X
and not by H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A.
It provides L<sup>A</sup>T<sub>E</sub>X with means to ignore or process some parts of the
document.
Note that H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A copes with the constructs defined in
the <span class="c017">hevea.sty</span> file by default.
It is important to notice that the <span class="c017">hevea.sty</span> style file from
the distribution is a <em>package</em> in L<sup>A</sup>T<sub>E</sub>X 2є terms and that it
is not compatible with old L<sup>A</sup>T<sub>E</sub>X. Moreover, the <span class="c017">hevea</span>
package loads the <span class="c017">comment</span> package which must be present.
Also notice that, for compatibility,
H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A reacts to
<code class="verb">\usepackage{hevea}</code> by loading its own version
of the <span class="c017">comment</span> package (Section <a href="manual-packages.html#commentpack">B.17.7</a>).</p>
<h4 class="subsubsection" id="sec32">5.2.1 Environments for selecting a translator</h4>
<p>
H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A and L<sup>A</sup>T<sub>E</sub>X perform the following actions on source inside
the <code class="verb">latexonly</code>, <code class="verb">verblatex</code>, <code class="verb">htmlonly</code>, <code class="verb">rawhtml</code>,
<code class="verb">toimage</code> and <code class="verb">verbimage</code> environments:
<a id="hevea_default10"></a>
<a id="hevea_default11"></a>
<a id="hevea_default12"></a>
<a id="hevea_default13"></a>
<a id="hevea_default14"></a>
<a id="hevea_default15"></a>
</p><div class="center">
<table class="c002 cellpading0"><tr><td class="hrule" colspan=5></td></tr>
<tr><td class="c046">environment</td><td class="c034"> </td><td class="c034" colspan=2>H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A</td><td class="c034">L<sup>A</sup>T<sub>E</sub>X
</td></tr>
<tr><td class="hrule" colspan=5></td></tr>
<tr><td class="c046"><code class="verb">latexonly</code></td><td class="c034"> </td><td class="c044">ignore, <code class="verb">\end{</code><span class="c023">env</span><code class="verb">}</code>
constructs are processed (see section <a href="#why">5.2.2</a>)</td><td class="c034"> </td><td class="c046">process </td></tr>
<tr><td class="c046"><code class="verb">verblatex</code></td><td class="c034"> </td><td class="c044">ignore</td><td class="c034"> </td><td class="c046">process </td></tr>
<tr><td class="c046"><code class="verb">htmlonly</code></td><td class="c034"> </td><td class="c044">process</td><td class="c034"> </td><td class="c046">ignore </td></tr>
<tr><td class="c046"><code class="verb">rawhtml</code></td><td class="c034"> </td><td class="c044">echo verbatim (see section <a href="manual018.html#rawhtml">8.4</a>)</td><td class="c034"> </td><td class="c046">ignore</td></tr>
<tr><td class="c046"><code class="verb">toimage</code></td><td class="c034"> </td><td class="c044">send to the <em>image</em> file, <code class="verb">\end{</code><span class="c023">env</span><code class="verb">}</code>
constructs and macro characters are processed (see section <a href="manual008.html#imagen">6</a>)</td><td class="c034"> </td><td class="c046">process</td></tr>
<tr><td class="c046"><code class="verb">verbimage</code></td><td class="c034"> </td><td class="c044">send to the <em>image</em> file (see section <a href="manual008.html#imagen">6</a>)</td><td class="c034"> </td><td class="c046">process</td></tr>
<tr><td class="hrule" colspan=5></td></tr>
</table>
</div><p>As an example, this is how some text can be typeset in purple by
H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A and left alone by L<sup>A</sup>T<sub>E</sub>X:
</p><pre class="verbatim">We get:
\begin{htmlonly}%
\purple purple rain, purple rain%
\end{htmlonly}
\begin{latexonly}%
purple rain, purple rain%
\end{latexonly}%
\ldots
</pre><p>
We get:
<span class="c011">purple rain, purple rain</span>
…</p><p>It is impossible to avoid the spurious space in H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A output
for the source above.
This extra spaces comes from the newline character that follows
<code class="verb">\end{htmlonly}</code>. Namely this
construct must appear in a line of its own for
L<sup>A</sup>T<sub>E</sub>X to recognize it. Anyway, better control over spaces
can be achieved
by using the <span class="c017">hevea</span> boolean register
or comments, see sections <a href="#heveabool">5.2.3</a>
and <a href="#comments">5.3</a>.</p><p>Also note that environments define a scope and that style changes
(and non-global definitions) are local to them. For instance, in the
example above, “…” appears in black in html output.
However, as an exception, the environments <span class="c017">image</span>
and <span class="c017">verbimage</span> do not create scope.
It takes a little practice of H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A to understand why this is
convenient.</p>
<h4 class="subsubsection" id="sec33">5.2.2 Why are there two environments for ignoring input?</h4>
<p><a id="why"></a>
<a id="hevea_default16"></a><a id="hevea_default17"></a>
<a id="hevea_default18"></a><a id="hevea_default19"></a>
Some scanning and analysis of source is performed
by H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A inside the <span class="c017">latexonly</span> environment, in order to
allow <span class="c017">latexonly</span> to dynamically occur inside other environments.</p><p>More specifically, <code class="verb">\end{</code><span class="c023">env</span><code class="verb">}</code> macros
are recognized and their <span class="c023">env</span> argument is tested against
the name of the environment whose opening macro <code class="verb">\</code><span class="c023">env</span>
opened the <span class="c017">latexonly</span> environment.
In that case, macro expansion of <code class="verb">\end</code><span class="c023">env</span> is performed and
any further occurrence of <code class="verb">\end{</code><span class="c023">env’</span><code class="verb">}</code> is tested
and may get expanded if it matches a pending
<code class="verb">\begin{</code><span class="c023">env’</span><code class="verb">}</code>
construct.</p><p>This enables playing tricks such as:
</p><pre class="verbatim">\newenvironment{latexhuge}
{\begin{latexonly}\huge}
{\end{latexonly}}
\begin{latexhuge}
This will appear in huge font in \LaTeX{} output only.
\end{latexhuge}
</pre><p>
L<sup>A</sup>T<sub>E</sub>X output will be:
</p><blockquote class="quote">
<img src="manual004.png">
</blockquote><p>
While there is no H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A output.</p><p>Since H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A somehow analyses input that is enclosed in the
<span class="c017">latexonly</span> environment,
it may choke.
However, this environment is intended to select processing by
L<sup>A</sup>T<sub>E</sub>X only and might contain arbitrary source code.
Fortunately, it remains possible to have input processed by L<sup>A</sup>T<sub>E</sub>X
only, regardless of what it is, by enclosing it in the
<span class="c017">verblatex</span> environment.
Inside this environment, H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A performs no other action
than looking for <code class="verb">\end{verblatex}</code>. As a consequence,
the <code class="verb">\begin{verblatex}</code> and <code class="verb">\end{verblatex}</code> constructs
may only appear in the main flow of text or inside the same macro body,
a bit like L<sup>A</sup>T<sub>E</sub>X <span class="c017">verbatim</span> environment.</p><p>Relations between <span class="c017">toimage</span> and <span class="c017">verbimage</span> are similar.
Additionally, formal parameters <code class="verb">#</code><span class="c023">i</span> are replaced by
actual arguments inside the <span class="c017">toimage</span> environment
(see end of section <a href="manual008.html#substimage">6.3</a> for an example of this feature).</p>
<h4 class="subsubsection" id="sec34">5.2.3 The <span class="c017">hevea</span> boolean register</h4>
<p><a id="heveabool"></a></p><p>Boolean registers are provided by the <span class="c017">ifthen</span> package
(see [<a href="manual047.html#latex">L<sup>A</sup>T<sub>E</sub>X</a>, Section C.8.5] and section <a href="manual030.html#ifthen">B.8.5</a> in this
document).
<a id="hevea_default20"></a>Both the <span class="c017">hevea.sty</span> style file
and H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A define the boolean register <span class="c017">hevea</span>.
However, this register initial value is <span class="c023">false</span> for L<sup>A</sup>T<sub>E</sub>X
and <span class="c023">true</span> for H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A.</p><p>Thus, provided, both the <span class="c017">hevea.sty</span> style file and the
<span class="c017">ifthen</span> packages are loaded, the “purple rain” example can
be rephrased as follows:
</p><pre class="verbatim">We get:
{\ifthenelse{\boolean{hevea}}{\purple}{}purple rain, purple rain}\ldots
</pre><p>
We get:
<span class="c011">purple rain, purple rain</span>…</p><p>Another choice is using the T<sub>E</sub>X-style conditional macro
<code class="verb">\ifhevea</code> (see Section <a href="extras.html#texcond">B.16.1.4</a>):
</p><pre class="verbatim">We get:
{\ifhevea\purple\fi purple rain, purple rain}\ldots
</pre><p>
We get: <span class="c011">purple rain, purple rain</span>…</p><p><a id="hevea_default21"></a>
</p>
<h3 class="subsection" id="sec35">5.3 Comments</h3>
<p><a id="comments"></a>
H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A processes all lines that start with <code class="verb">%HEVEA</code>, while
L<sup>A</sup>T<sub>E</sub>X treats these lines as comments.
Thus, this is a last variation on the “purple rain” example:
</p><pre class="verbatim">We get
%HEVEA{\purple
purple rain, purple rain%
%HEVEA}%
\ldots
</pre><p>
(Note how comments are placed at the end of some lines to avoid spurious spaces
in the final output.)</p><p>We get:
<span class="c011">purple rain, purple rain</span>…</p><p>Comments thus provide an alternative to loading the
<span class="c017">hevea</span> package. For user convenience, comment equivalents to
the <code class="verb">latexonly</code> and <code class="verb">toimage</code> environment are also provided:
<a id="hevea_default22"></a>
<a id="hevea_default23"></a>
<a id="hevea_default24"></a>
<a id="hevea_default25"></a>
</p><div class="center">
<table class="c002 cellpading0"><tr><td class="hrule" colspan=2></td></tr>
<tr><td class="c034">environment</td><td class="c034">comment
equivalent</td></tr>
<tr><td class="hrule" colspan=2></td></tr>
<tr><td class="c037"><code class="verb">\begin{latexonly}</code>… <code class="verb">\end{latexonly}</code></td><td class="c037"><table class="c002 cellpading0"><tr><td class="c037"><code class="verb">%BEGIN LATEX</code> </td></tr>
<tr><td class="c037">…</td></tr>
<tr><td class="c037"><code class="verb">%END LATEX</code>
</td></tr>
</table>
</td></tr>
<tr><td class="c037"> </td><td class="c037"> </td></tr>
<tr><td class="hrule" colspan=2></td></tr>
<tr><td class="c037"><code class="verb">\begin{toimage}</code>… <code class="verb">\end{toimage}</code></td><td class="c037"><table class="c002 cellpading0"><tr><td class="c037"><code class="verb">%BEGIN IMAGE</code> </td></tr>
<tr><td class="c037">…</td></tr>
<tr><td class="c037"><code class="verb">%END IMAGE</code>
</td></tr>
</table>
</td></tr>
</table>
</div><p>
Note that L<sup>A</sup>T<sub>E</sub>X, by ignoring comments, naturally performs the action
of processing text between <code class="verb">%BEGIN</code><span class="c017">…</span> and <code class="verb">%END</code><span class="c017">…</span> comments. However, no environment is opened and closed and no scope is
created while using comment equivalents.</p>
<hr>
<a href="manual006.html"><img src="previous_motif.svg" alt="Previous"></a>
<a href="manual002.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="manual008.html"><img src="next_motif.svg" alt="Next"></a>
</body>
</html>
|
