Sophie: hevea-2.32-2.mga7 i586

hevea-2.32-2.mga7.i586.rpm

<!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>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="sec29">5&#XA0;&#XA0;Making H<span class="c016"><sup>E</sup></span>V<span class="c016"><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="c013">hevea</span> package</a>
</li><li><a href="manual007.html#sec35">Comments</a>
</li></ul>
<p>

<a id="both"></a>
A satisfactory translation from L<sup>A</sup>T<sub>E</sub>X to html often requires
giving instructions to H<span class="c016"><sup>E</sup></span>V<span class="c016"><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="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A.
Basically, there are three ways to make input vary according to the
processor, file loading, the <span class="c013">hevea</span> package
and comments.</p>
<h3 class="subsection" id="sec30">5.1&#XA0;&#XA0;File loading</h3>
<p><a id="fileloading"></a></p><p>H<span class="c016"><sup>E</sup></span>V<span class="c016"><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="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A both load files given as arguments to
<code>\input</code>, however when given the option <code>-e</code>&#XA0;<em>filename</em>,
H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A does not load <em>filename</em>.
</li><li class="li-itemize">H<span class="c016"><sup>E</sup></span>V<span class="c016"><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="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A load style files given as optional
arguments to 
<code>\documentstyle</code> and as arguments to <code>\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>\input{</code><em>latexonly</em><code>}</code>
in the source and to invoke H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A as follows:
</p><div class="flushleft">
<code># hevea</code> <span class="c013">-e</span> <em>latexonly</em>&#X2026;</div><p><a id="heveaonly"></a>Having <em>heveaonly</em> loaded by H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A only is more
simple: it suffices to invoke H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A as follows:
</p><div class="flushleft">
<code># hevea</code> <em>heveaonly</em>&#X2026;</div><p>Finally, if one has an H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A equivalent <span class="c019">style</span><span class="c013">.hva</span>
for a L<sup>A</sup>T<sub>E</sub>X style file <span class="c019">style</span><span class="c013">.sty</span>,
then one should load the file as follows:
</p><div class="flushleft">
<code>\usepackage{</code><span class="c019">style</span><code>}</code>
</div><p>
This will result in, L<sup>A</sup>T<sub>E</sub>X loading <span class="c019">style</span><span class="c013">.sty</span>,
while H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A loads <span class="c019">style</span><span class="c013">.hva</span>.
As H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A will not fail in case <span class="c019">style</span><span class="c013">.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="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A-specific file <span class="c019">file</span><span class="c013">.hva</span>
is the method of choice for supplying command definitions
to H<span class="c016"><sup>E</sup></span>V<span class="c016"><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="c019">image</span>
file (see section&#XA0;<a href="manual008.html#imagen">6</a>).</p><p>The file <span class="c019">file</span><span class="c013">.hva</span> can be loaded by either
supplying the command-line argument
<span class="c019">file</span><span class="c013">.hva</span>, or by
<code>\usepackage{</code><span class="c019">file</span><code>}</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="c019">file</span><span class="c013">.hva</span> are processed before the
ones from the document and will override them, provided
the document definitions are made using <code>\newcommand</code> (or
<code>\newenvironment</code>).
In the <code>\usepackage</code> case, H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A loads <span class="c019">file</span><span class="c013">.hva</span>
at the place where L<sup>A</sup>T<sub>E</sub>X loads <span class="c019">file</span><span class="c013">.sty</span>, hence
the definitions from <span class="c019">file</span><span class="c013">.hva</span> replace
the definitions from <span class="c019">file</span><span class="c013">.sty</span> in the strict sense.</p>
<h3 class="subsection" id="heveastyle">5.2&#XA0;&#XA0;The <span class="c013">hevea</span> package</h3>
<p>
<a id="hevea_default8"></a>The <span class="c013">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="c016"><sup>E</sup></span>V<span class="c016"><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="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A copes with the constructs defined in
the <span class="c013">hevea.sty</span> file by default.
It is important to notice that the <span class="c013">hevea.sty</span> style file from
the distribution is a <em>package</em> in L<sup>A</sup>T<sub>E</sub>X&#XA0;2&#X454; terms and that it
is not compatible with old L<sup>A</sup>T<sub>E</sub>X. Moreover, the <span class="c013">hevea</span>
package loads the <span class="c013">comment</span> package which must be present.
Also notice that, for compatibility,
H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A reacts to
<code>\usepackage{hevea}</code> by loading its own version
of the <span class="c013">comment</span> package (Section&#XA0;<a href="manual-packages.html#commentpack">B.17.6</a>).</p>
<h4 class="subsubsection" id="sec32">5.2.1&#XA0;&#XA0;Environments for selecting a translator</h4>
<p>
H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A and L<sup>A</sup>T<sub>E</sub>X perform the following actions on source inside
the <code>latexonly</code>, <code>verblatex</code>, <code>htmlonly</code>, <code>rawhtml</code>,
<code>toimage</code> and <code>verbimage</code> environments:
<a id="hevea_default9"></a>
<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>
</p><div class="center">
<table class="c002 cellpading0"><tr><td class="hbar" colspan=5></td></tr>
<tr><td class="c042">environment</td><td class="c030">&#XA0;</td><td class="c030" colspan=2>H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A</td><td class="c030">L<sup>A</sup>T<sub>E</sub>X
</td></tr>
<tr><td class="hbar" colspan=5></td></tr>
<tr><td class="c042"><code>latexonly</code></td><td class="c030">&#XA0;</td><td class="c040">ignore, <code>\end{</code><span class="c019">env</span><code>}</code>
constructs are processed (see section&#XA0;<a href="#why">5.2.2</a>)</td><td class="c030">&#XA0;&#XA0;</td><td class="c042">process </td></tr>
<tr><td class="c042"><code>verblatex</code></td><td class="c030">&#XA0;</td><td class="c040">ignore</td><td class="c030">&#XA0;&#XA0;</td><td class="c042">process </td></tr>
<tr><td class="c042"><code>htmlonly</code></td><td class="c030">&#XA0;</td><td class="c040">process</td><td class="c030">&#XA0;&#XA0;</td><td class="c042">ignore </td></tr>
<tr><td class="c042"><code>rawhtml</code></td><td class="c030">&#XA0;</td><td class="c040">echo verbatim (see section&#XA0;<a href="manual018.html#rawhtml">8.4</a>)</td><td class="c030">&#XA0;&#XA0;</td><td class="c042">ignore</td></tr>
<tr><td class="c042"><code>toimage</code></td><td class="c030">&#XA0;</td><td class="c040">send to the <em>image</em> file, <code>\end{</code><span class="c019">env</span><code>}</code>
constructs and macro characters are processed (see section&#XA0;<a href="manual008.html#imagen">6</a>)</td><td class="c030">&#XA0;&#XA0;</td><td class="c042">process</td></tr>
<tr><td class="c042"><code>verbimage</code></td><td class="c030">&#XA0;</td><td class="c040">send to the <em>image</em> file (see section&#XA0;<a href="manual008.html#imagen">6</a>)</td><td class="c030">&#XA0;&#XA0;</td><td class="c042">process</td></tr>
<tr><td class="hbar" colspan=5></td></tr>
</table>
</div><p>As an example, this is how some text can be typeset in purple by
H<span class="c016"><sup>E</sup></span>V<span class="c016"><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="c010">purple rain, purple rain</span>
&#X2026;</p><p>It is impossible to avoid the spurious space in H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A output
for the source above.
This extra spaces comes from the newline character that follows
<code>\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="c013">hevea</span> boolean register
or comments, see sections&#XA0;<a href="#heveabool">5.2.3</a>
and&#XA0;<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, &#X201C;&#X2026;&#X201D; appears in black in html output.
However, as an exception, the environments <span class="c013">image</span>
and <span class="c013">verbimage</span> do not create scope.
It takes a little practice of H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A to understand why this is
convenient.</p>
<h4 class="subsubsection" id="sec33">5.2.2&#XA0;&#XA0;Why are there two environments for ignoring input?</h4>
<p><a id="why"></a>
<a id="hevea_default15"></a><a id="hevea_default16"></a>
<a id="hevea_default17"></a><a id="hevea_default18"></a>
Some scanning and analysis of source is performed
by H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A inside the <span class="c013">latexonly</span> environment, in order to
allow <span class="c013">latexonly</span> to dynamically occur inside other environments.</p><p>More specifically, <code>\end{</code><span class="c019">env</span><code>}</code> macros
are recognized and their <span class="c019">env</span> argument is tested against
the name of the environment whose opening macro <code>\</code><span class="c019">env</span>
opened the <span class="c013">latexonly</span> environment.
In that case, macro expansion of <code>\end</code><span class="c019">env</span> is performed and
any further occurrence of <code>\end{</code><span class="c019">env&#X2019;</span><code>}</code> is tested
and may get expanded if it matches a pending
<code>\begin{</code><span class="c019">env&#X2019;</span><code>}</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="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A output.</p><p>Since H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A somehow analyses input that is enclosed in the
<span class="c013">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="c013">verblatex</span> environment.
Inside this environment, H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A performs no other action
than looking for <code>\end{verblatex}</code>. As a consequence,
the <code>\begin{verblatex}</code> and <code>\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="c013">verbatim</span> environment.</p><p>Relations between <span class="c013">toimage</span> and <span class="c013">verbimage</span> are similar.
Additionally, formal parameters <code>#</code><span class="c019">i</span> are replaced by
actual arguments inside the <span class="c013">toimage</span> environment
(see end of section&#XA0;<a href="manual008.html#substimage">6.3</a> for an example of this feature).</p>
<h4 class="subsubsection" id="sec34">5.2.3&#XA0;&#XA0;The <span class="c013">hevea</span> boolean register</h4>
<p><a id="heveabool"></a></p><p>Boolean registers are provided by the <span class="c013">ifthen</span> package
(see&#XA0;[<a href="manual047.html#latex">L<sup>A</sup>T<sub>E</sub>X</a>, Section&#XA0;C.8.5] and section&#XA0;<a href="manual030.html#ifthen">B.8.5</a> in this
document).
<a id="hevea_default19"></a>Both the <span class="c013">hevea.sty</span> style file
and H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A define the boolean register <span class="c013">hevea</span>.
However, this register initial value is <span class="c019">false</span> for L<sup>A</sup>T<sub>E</sub>X
and <span class="c019">true</span> for H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A.</p><p>Thus, provided, both the <span class="c013">hevea.sty</span> style file and the
<span class="c013">ifthen</span> packages are loaded, the &#X201C;purple rain&#X201D; 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="c010">purple rain, purple rain</span>&#X2026;</p><p>Another choice is using the T<sub>E</sub>X-style conditional macro
<code>\ifhevea</code> (see Section&#XA0;<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="c010">purple rain, purple rain</span>&#X2026;</p><p><a id="hevea_default20"></a>
</p>
<h3 class="subsection" id="sec35">5.3&#XA0;&#XA0;Comments</h3>
<p><a id="comments"></a>
H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A processes all lines that start with <code>%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 &#X201C;purple rain&#X201D; 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="c010">purple rain, purple rain</span>&#X2026;</p><p>Comments thus provide an alternative to loading the
<span class="c013">hevea</span> package. For user convenience, comment equivalents to
the <code>latexonly</code> and <code>toimage</code> environment are also provided:
<a id="hevea_default21"></a>
<a id="hevea_default22"></a>
<a id="hevea_default23"></a>
<a id="hevea_default24"></a>
</p><div class="center">
<table class="c002 cellpading0"><tr><td class="hbar" colspan=2></td></tr>
<tr><td class="c030">environment</td><td class="c030">comment
equivalent</td></tr>
<tr><td class="hbar" colspan=2></td></tr>
<tr><td class="c033"><code>\begin{latexonly}</code>&#X2026; <code>\end{latexonly}</code></td><td class="c033"><table class="c002 cellpading0"><tr><td class="c033"><code>%BEGIN LATEX</code> </td></tr>
<tr><td class="c033">&#X2026;</td></tr>
<tr><td class="c033"><code>%END LATEX</code>
</td></tr>
</table>
</td></tr>
<tr><td class="c033">&nbsp;</td><td class="c033">&nbsp;</td></tr>
<tr><td class="hbar" colspan=2></td></tr>
<tr><td class="c033"><code>\begin{toimage}</code>&#X2026; <code>\end{toimage}</code></td><td class="c033"><table class="c002 cellpading0"><tr><td class="c033"><code>%BEGIN IMAGE</code> </td></tr>
<tr><td class="c033">&#X2026;</td></tr>
<tr><td class="c033"><code>%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>%BEGIN</code><span class="c013">&#X2026;</span> and <code>%END</code><span class="c013">&#X2026;</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>