Sophie: hevea-1.10-4mdv2010.0 i586

hevea-1.10-4mdv2010.0.i586.rpm

<!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>Making HEVEA and LATEX both happy</TITLE>
</HEAD>
<BODY >
<A HREF="manual006.html"><IMG SRC="previous_motif.gif" ALT="Previous"></A>
<A HREF="manual002.html"><IMG SRC="contents_motif.gif" ALT="Up"></A>
<A HREF="manual008.html"><IMG SRC="next_motif.gif" ALT="Next"></A>
<HR>
<H2 CLASS="section"><A NAME="htoc17">5</A>&#XA0;&#XA0;Making H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A and L<sup>A</sup>T<sub>E</sub>X both happy</H2><UL>
<LI><A HREF="manual007.html#toc12">File loading</A>
</LI><LI><A HREF="manual007.html#toc13">The <TT>hevea</TT> package</A>
</LI><LI><A HREF="manual007.html#toc14">Comments</A>
</LI></UL>
<P>

<A NAME="both"></A>
A satisfactory translation from L<sup>A</sup>T<sub>E</sub>X to HTML often requires
giving instructions to H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A.
Basically, there are three ways to make input vary according to the
processor, file loading, the <TT>hevea</TT> package
and comments.</P><H3 CLASS="subsection"><A NAME="toc12"></A><A NAME="htoc18">5.1</A>&#XA0;&#XA0;File loading</H3><P><A NAME="fileloading"></A></P><P>H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A both load files given as arguments to
<CODE>\input</CODE>, however when given the option <CODE>-e</CODE>&#XA0;<EM>filename</EM>,
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A does not load <EM>filename</EM>.
</LI><LI CLASS="li-itemize">H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A as follows:
</P><DIV CLASS="flushleft">
<CODE># hevea</CODE> <TT>-e</TT> <EM>latexonly</EM>&#X2026;</DIV><P><A NAME="heveaonly"></A>Having <EM>heveaonly</EM> loaded by H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A only is more
simple: it suffices to invoke H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A as follows:
</P><DIV CLASS="flushleft">
<CODE># hevea</CODE> <EM>heveaonly</EM>&#X2026;</DIV><P>Finally, if one has an H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A equivalent <I>style</I><TT>.hva</TT>
for a L<sup>A</sup>T<sub>E</sub>X style file <I>style</I><TT>.sty</TT>,
then one should load the file as follows:
</P><DIV CLASS="flushleft">
<CODE>\usepackage{</CODE><I>style</I><CODE>}</CODE>
</DIV><P>
This will result in, L<sup>A</sup>T<sub>E</sub>X loading <I>style</I><TT>.sty</TT>,
while H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A loads <I>style</I><TT>.hva</TT>.
As H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A will not fail in case <I>style</I><TT>.hva</TT> 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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A-specific file <I>file</I><TT>.hva</TT>
is the method of choice for supplying command definitions
to H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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 <I>image</I>
file (see section&#XA0;<A HREF="manual008.html#imagen">6</A>).</P><P>The file <I>file</I><TT>.hva</TT> can be loaded by either
supplying the command-line argument
<I>file</I><TT>.hva</TT>, or by
<CODE>\usepackage{</CODE><I>file</I><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 <I>file</I><TT>.hva</TT> 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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A loads <I>file</I><TT>.hva</TT>
at the place where L<sup>A</sup>T<sub>E</sub>X loads <I>file</I><TT>.sty</TT>, hence
the definitions from <I>file</I><TT>.hva</TT> replace
the definitions from <I>file</I><TT>.sty</TT> in the strict sense.</P><H3 CLASS="subsection"><A NAME="toc13"></A><A NAME="htoc19">5.2</A>&#XA0;&#XA0;The <A NAME="heveastyle"></A><TT>hevea</TT> package</H3><P>
The <TT>hevea.sty</TT> style file is intended to be loaded by L<sup>A</sup>T<sub>E</sub>X
and not by H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A copes with the constructs defined in
the <TT>hevea.sty</TT> file by default.
It is important to notice that the <TT>hevea.sty</TT> 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 <TT>hevea</TT>
package loads the <TT>comment</TT> package which must be present.
Also notice that, for compatibility,
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A reacts to
<CODE>\usepackage{hevea}</CODE> by loading its own version
of the <TT>comment</TT> package (Section&#XA0;<A HREF="manual-packages.html#commentpack">B.17.6</A>).</P><H4 CLASS="subsubsection">5.2.1&#XA0;&#XA0;Environments for selecting a translator</H4><P>
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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 NAME="@default7"></A>
<A NAME="@default8"></A>
<A NAME="@default9"></A>
<A NAME="@default10"></A>
<A NAME="@default11"></A>
<A NAME="@default12"></A>
</P><DIV CLASS="center">
<TABLE CELLSPACING=6 CELLPADDING=0><TR><TD CLASS="hbar" COLSPAN=5></TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP>environment</TD><TD VALIGN=top ALIGN=center NOWRAP>&#XA0;</TD><TD ALIGN=center NOWRAP COLSPAN=2>H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A</TD><TD ALIGN=center NOWRAP>L<sup>A</sup>T<sub>E</sub>X</TD></TR>
<TR><TD CLASS="hbar" COLSPAN=5></TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><CODE>latexonly</CODE></TD><TD VALIGN=top ALIGN=center NOWRAP>&#XA0;</TD><TD VALIGN=top ALIGN=left>ignore, <CODE>\end{</CODE><I>env</I><CODE>}</CODE>
constructs are processed (see section&#XA0;<A HREF="#why">5.2.2</A>)</TD><TD VALIGN=top ALIGN=center NOWRAP>&#XA0;&#XA0;</TD><TD VALIGN=top ALIGN=left NOWRAP>process</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><CODE>verblatex</CODE></TD><TD VALIGN=top ALIGN=center NOWRAP>&#XA0;</TD><TD VALIGN=top ALIGN=left>ignore</TD><TD VALIGN=top ALIGN=center NOWRAP>&#XA0;&#XA0;</TD><TD VALIGN=top ALIGN=left NOWRAP>process</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><CODE>htmlonly</CODE></TD><TD VALIGN=top ALIGN=center NOWRAP>&#XA0;</TD><TD VALIGN=top ALIGN=left>process</TD><TD VALIGN=top ALIGN=center NOWRAP>&#XA0;&#XA0;</TD><TD VALIGN=top ALIGN=left NOWRAP>ignore</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><CODE>rawhtml</CODE></TD><TD VALIGN=top ALIGN=center NOWRAP>&#XA0;</TD><TD VALIGN=top ALIGN=left>echo verbatim (see section&#XA0;<A HREF="manual018.html#rawhtml">8.4</A>)</TD><TD VALIGN=top ALIGN=center NOWRAP>&#XA0;&#XA0;</TD><TD VALIGN=top ALIGN=left NOWRAP>ignore</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><CODE>toimage</CODE></TD><TD VALIGN=top ALIGN=center NOWRAP>&#XA0;</TD><TD VALIGN=top ALIGN=left>send to the <EM>image</EM> file, <CODE>\end{</CODE><I>env</I><CODE>}</CODE>
constructs and macro characters are processed (see section&#XA0;<A HREF="manual008.html#imagen">6</A>)</TD><TD VALIGN=top ALIGN=center NOWRAP>&#XA0;&#XA0;</TD><TD VALIGN=top ALIGN=left NOWRAP>process</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><CODE>verbimage</CODE></TD><TD VALIGN=top ALIGN=center NOWRAP>&#XA0;</TD><TD VALIGN=top ALIGN=left>send to the <EM>image</EM> file (see section&#XA0;<A HREF="manual008.html#imagen">6</A>)</TD><TD VALIGN=top ALIGN=center NOWRAP>&#XA0;&#XA0;</TD><TD VALIGN=top ALIGN=left NOWRAP>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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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:
<FONT COLOR=purple>purple rain, purple rain</FONT>
&#X2026;</P><P>It is impossible to avoid the spurious space in H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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 <TT>hevea</TT> 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 <TT>image</TT>
and <TT>verbimage</TT> do not create scope.
It takes a little practice of H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A to understand why this is
convenient.</P><H4 CLASS="subsubsection">5.2.2&#XA0;&#XA0;Why are there two environments for ignoring input?</H4><P><A NAME="why"></A>
<A NAME="@default13"></A><A NAME="@default14"></A>
<A NAME="@default15"></A><A NAME="@default16"></A>
Some scanning and analysis of source is performed
by H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A inside the <TT>latexonly</TT> environment, in order to
allow <TT>latexonly</TT> to dynamically occur inside other environments.</P><P>More specifically, <CODE>\end{</CODE><I>env</I><CODE>}</CODE> macros
are recognized and their <I>env</I> argument is tested against
the name of the environment whose opening macro <CODE>\</CODE><I>env</I>
opened the <TT>latexonly</TT> environment.
In that case, macro expansion of <CODE>\end</CODE><I>env</I> is performed and
any further occurrence of <CODE>\end{</CODE><I>env&#X2019;</I><CODE>}</CODE> is tested
and may get expanded if it matches a pending
<CODE>\begin{</CODE><I>env&#X2019;</I><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"><HR NOSHADE SIZE=1 ALIGN=center>
<IMG SRC="manual004.gif">
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE><P>
While there is no H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A output.</P><P>Since H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A somehow analyses input that is enclosed in the
<TT>latexonly</TT> 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
<TT>verblatex</TT> environment.
Inside this environment, H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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 <TT>verbatim</TT> environment.</P><P>Relations between <TT>toimage</TT> and <TT>verbimage</TT> are similar.
Additionally, formal parameters <CODE>#</CODE><I>i</I> are replaced by
actual arguments inside the <TT>toimage</TT> environment
(see end of section&#XA0;<A HREF="manual008.html#substimage">6.3</A> for an example of this feature).</P><H4 CLASS="subsubsection">5.2.3&#XA0;&#XA0;The <TT>hevea</TT> boolean register</H4><P><A NAME="heveabool"></A></P><P>Boolean registers are provided by the <TT>ifthen</TT> 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 NAME="@default17"></A>Both the <TT>hevea.sty</TT> style file
and H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A define the boolean register <TT>hevea</TT>.
However, this register initial value is <I>false</I> for L<sup>A</sup>T<sub>E</sub>X
and <I>true</I> for H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A.</P><P>Thus, provided, both the <TT>hevea.sty</TT> style file and the
<TT>ifthen</TT> 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:
<FONT COLOR=purple>purple rain, purple rain</FONT>&#X2026;</P><P>Another choice is using the T<sub>E</sub>X-style conditional macro
<CODE>\ifhevea</CODE> (see Section&#XA0;<A HREF="manual038.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: <FONT COLOR=purple>purple rain, purple rain</FONT>&#X2026;</P><P><A NAME="@default18"></A>
</P><H3 CLASS="subsection"><A NAME="toc14"></A><A NAME="htoc20">5.3</A>&#XA0;&#XA0;Comments</H3><P><A NAME="comments"></A>
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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:
<FONT COLOR=purple>purple rain, purple rain</FONT>&#X2026;</P><P>Comments thus provide an alternative to loading the
<TT>hevea</TT> package. For user convenience, comment equivalents to
the <CODE>latexonly</CODE> and <CODE>toimage</CODE> environment are also provided:
<A NAME="@default19"></A>
<A NAME="@default20"></A>
<A NAME="@default21"></A>
<A NAME="@default22"></A>
</P><DIV CLASS="center">
<TABLE CELLSPACING=6 CELLPADDING=0><TR><TD CLASS="hbar" COLSPAN=2></TD></TR>
<TR><TD ALIGN=center NOWRAP>environment</TD><TD ALIGN=center NOWRAP>comment
equivalent</TD></TR>
<TR><TD CLASS="hbar" COLSPAN=2></TD></TR>
<TR><TD ALIGN=left NOWRAP><CODE>\begin{latexonly}</CODE>&#X2026; <CODE>\end{latexonly}</CODE></TD><TD ALIGN=left NOWRAP><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD ALIGN=left NOWRAP><CODE>%BEGIN LATEX</CODE></TD></TR>
<TR><TD ALIGN=left NOWRAP>&#X2026;</TD></TR>
<TR><TD ALIGN=left NOWRAP><CODE>%END LATEX</CODE></TD></TR>
</TABLE></TD></TR>
<TR><TD ALIGN=left NOWRAP>&nbsp;</TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD CLASS="hbar" COLSPAN=2></TD></TR>
<TR><TD ALIGN=left NOWRAP><CODE>\begin{toimage}</CODE>&#X2026; <CODE>\end{toimage}</CODE></TD><TD ALIGN=left NOWRAP><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD ALIGN=left NOWRAP><CODE>%BEGIN IMAGE</CODE></TD></TR>
<TR><TD ALIGN=left NOWRAP>&#X2026;</TD></TR>
<TR><TD ALIGN=left NOWRAP><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><TT>&#X2026;</TT> and <CODE>%END</CODE><TT>&#X2026;</TT> 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.gif" ALT="Previous"></A>
<A HREF="manual002.html"><IMG SRC="contents_motif.gif" ALT="Up"></A>
<A HREF="manual008.html"><IMG SRC="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>