<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="generator" content="hevea 2.06">
<META name="Author" content="Luc Maranget"><link rel="stylesheet" type="text/css" href="manual.css">
<title>Customising HEVEA</title>
</head>
<body>
<a href="manual019.html"><img src="previous_motif.gif" alt="Previous"></a>
<a href="manual002.html"><img src="contents_motif.gif" alt="Up"></a>
<a href="manual021.html"><img src="next_motif.gif" alt="Next"></a>
<hr>
<h2 class="section" id="sec88">10  Customising H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A</h2>
<ul>
<li><a href="manual020.html#sec89">Simple changes</a>
</li><li><a href="manual020.html#sec90">Changing defaults for type-styles</a>
</li><li><a href="manual020.html#sec91">Changing the interface of a command</a>
</li><li><a href="manual020.html#sec92">Checking the optional argument within a command</a>
</li><li><a href="manual020.html#sec93">Changing the format of images</a>
</li><li><a href="manual020.html#sec94">Storing images in a separate directory</a>
</li><li><a href="manual020.html#imagen-source">Controlling <span class="c013">imagen</span> from document source</a>
</li></ul>
<p>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A can be controlled by writing L<sup>A</sup>T<sub>E</sub>X code. In this section,
we examine how users can change H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A default behaviour or add
functionalities. In all this section we assume that a document
<span class="c013">doc.tex</span> is processed, using a private command file
<span class="c013">macros.hva</span>. That is, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A is invoked as:
</p><pre class="verbatim"># hevea macros.hva doc.tex
</pre><p>The general idea is as follows: one redefines L<sup>A</sup>T<sub>E</sub>X constructs in
<span class="c013">macros.hva</span>, using internal commands. This requires a good
working knowledge of both L<sup>A</sup>T<sub>E</sub>X and html.
Usually, one can avoid internal commands, but then, all command
redefinitions interact, sometimes in very nasty ways.</p>
<h3 class="subsection" id="sec89">10.1  Simple changes</h3>
<p>
Users can easily change the rendering of some constructs. For
instance, assume that <em>all</em> quotations in a text should be
emphasised. Then, it suffices to put the following re-declaration in
<span class="c013">macros.hva</span>:
</p><pre class="verbatim">\renewenvironment{quote}
{\@open{blockquote}{}\@style{em}}
{\@close{blockquote}}
</pre><p>The same effect can be achieved without using any of the internal
commands:
</p><pre class="verbatim">\let\oldquote\quote
\let\oldendquote\endquote
\renewenvironment{quote}{\oldquote\em}{\oldendquote}
</pre><p>In some sense, this second
solution is easier, when one already knows
how to customise L<sup>A</sup>T<sub>E</sub>X. However, this is less safe, since the definition of
<code>\em</code> can be changed elsewhere.</p><p>There is yet another solution that takes advantage of style sheets.
One can also add this line to the <span class="c013">macros.hva</span> file:
</p><pre class="verbatim">\newstyle{.quote}{font-style:oblique;}
</pre><p>This works because the environment <span class="c013">quote</span> is styled through
style class <span class="c013">quote</span> (see Section <a href="manual019.html#css%3Achange%3Aall">9.2</a>).
Notice that this solution has very little to do with
“<em>emphasising</em>” in the proper sense, since here we
short-circuit the implicit path from <code>\em</code> to oblique fonts.</p>
<h3 class="subsection" id="sec90">10.2  Changing defaults for type-styles</h3>
<p><a id="customize-style"></a>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A default rendering of type style changes is described in
section <a href="manual037.html#type-style">B.15.1</a>.
For instance, the following example shows the default rendering
for the font shapes:
</p><pre class="verbatim">\itshape italic shape \slshape slanted shape
\scshape small caps shape \upshape upright shape
</pre><p>By default, <code>\itshape</code> is italics, <code>\slshape</code> is oblique
italics, <code>\scshape</code> is small-caps (thanks to style sheets) and <code>\upshape</code> is no style at all.
All shapes are mutually exclusive, this means that each shape
declaration cancels the effect of other active shape declarations.
For instance, in the example, small caps shapes is small caps (no italics here).
</p><blockquote class="quote">
<span class="c018">italic shape </span><span class="c019">slanted shape
</span><span class="c020">small caps shape </span>upright shape
</blockquote><p>If one wishes to change the rendering of some of the shapes (say slanted
caps), then one should redefine the old-style <code>\sl</code> declaration.
For instance, to render slanted as Helvetica (why so?), one should
redefine <code>\sl</code> by <code>\renewcommand{\sl}{\@span{style="font-family:Helvetica"}}</code> in
<span class="c013">macros.hva</span>.</p><p>
And now, the shape example above gets rendered as follows:
</p><blockquote class="quote">
<span class="c018">italic shape </span><span class="c012">slanted shape
</span><span class="c020">small caps shape </span>upright shape
</blockquote><p>Redefining the old-style <code>\sl</code> is compatible with the cancellation
mechanism, redefining <code>\slshape</code> is not.
Thus, redefining directly L<sup>A</sup>T<sub>E</sub>X 2є <code>\slshape</code> with
<code>\renewcommand{\slshape}{}</code> would yield:
</p><blockquote class="quote">
<span class="c018">italic shape <span class="c012">slanted shape
</span></span><span class="c012"><span class="c020">small caps shape </span>upright shape</span>
</blockquote><p>Hence, redefining old-style declarations using internal commands
should yield satisfactory output.
However, since cancellation is done at the html
level, a declaration belonging to one component may sometimes cancel the
effect of another that belongs to another component.
Anyway, you might have not noticed it if I had not told you.</p>
<h3 class="subsection" id="sec91">10.3  Changing the interface of a command</h3>
<p><a id="customize-let"></a>
Assume for instance that the base style of <span class="c013">doc.tex</span> is
<span class="c018">jsc</span> (the
<em>Journal of Symbolic Computation</em> style for articles).
For running H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A, the <span class="c018">jsc</span> style can be replaced by
<span class="c018">article</span>
style, but for a few commands whose calling interface is changed.
In particular, the <code>\title</code> command
takes an extra optional argument (which H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A should ignore
anyway).
However, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A can process the document as it stands.
One solution to insert the following lines into <span class="c013">macros.hva</span>:
</p><pre class="verbatim">\input{article.hva}% Force document class 'article'
\let\oldtitle=\title
\renewcommand{\title}[2][]{\oldtitle{#2}}
</pre><p>The effect is to replace <code>\title</code> by a new command which
calls H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A <code>\title</code> with the appropriate argument.
</p>
<h3 class="subsection" id="sec92">10.4  Checking the optional argument within a command</h3>
<p><a id="fullepsfbox"></a>
<a id="hevea_default128"></a>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A fully implements L<sup>A</sup>T<sub>E</sub>X 2є <code>\newcommand</code>.
That is, users can define commands with an optional argument.
Such a feature permits to write a <code>\epsfbox</code> command that
has the same interface as the L<sup>A</sup>T<sub>E</sub>X command and
echoes itself as it is invoked to the <span class="c018">image</span> file.
To do this, the H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A <code>\epsfbox</code> command has to check
whether it is invoked with an optional argument or not.
This can be achieved as follows:
</p><pre class="verbatim">\newcommand{\epsfbox}[2][!*!]{%
\ifthenelse{\equal{#1}{!*!}}
{\begin{toimage}\epsfbox{#2}\end{toimage}}%No optional argument
{\begin{toimage}\epsfbox[#1]{#2}\end{toimage}}}%With optional argument
\imageflush}
</pre>
<h3 class="subsection" id="sec93">10.5  Changing the format of images</h3>
<p>
<a id="hevea_default129"></a>
<a id="hevea_default130"></a>
<a id="hevea_default131"></a>
<a id="hevea_default132"></a>
<a id="hevea_default133"></a>
Semi-automatic generation of included images is described in
section <a href="manual008.html#imagen">6</a>.
Links to included images are generated by the <code>\imageflush</code>
command, which calls the <code>\imgsrc</code> command:
</p><pre class="verbatim">\newcommand{\imageflush}[1][]
{\@imageflush\stepcounter{image}\imgsrc[#1]{\hevaimagedir\jobname\theimage\heveaimageext}}
</pre><p>That is, you may supply a html-style attribute to the included image,
as an optional argument to the <code>\imageflush</code> command.</p><p>By default, images are PNG images stored in <span class="c013">.png</span> files.
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A provides support for the alternative GIF image file format.
It suffices to invoke <span class="c013">hevea</span> as:
</p><div class="flushleft">
<span class="c013"># hevea gif.hva</span> <span class="c018">doc.tex</span>
</div><p>
Then <span class="c013">imagen</span> must be run with option <a id="hevea_default134"></a><span class="c013">-gif</span>:
</p><div class="flushleft">
<span class="c013"># imagen -gif</span> <em>doc</em>
</div><p>A convenient alternative is to invoke <span class="c013">hevea</span> as:
</p><div class="flushleft">
<span class="c013"># hevea -fix gif.hva</span> <span class="c018">doc.tex</span>
</div><p>
Then <span class="c013">hevea</span> will invoke <span class="c013">imagen</span> with the appropriate
option when it thinks images need to be rebuild.</p>
<h3 class="subsection" id="sec94">10.6  Storing images in a separate directory</h3>
<p>
<a id="hevea_default135"></a>
By redefining the <code>\heveaimagedir</code> command, users can specify a
directory for images.
More precisely, if the following redefinition occurs in the document
preamble.
</p><div class="flushleft">
<code>\renewcommand{\heveaimagedir}{</code><span class="c018">dir</span><code>}</code>
</div><p>
Then, all links to images in the produced html file will be as
“<span class="c018">dir</span>/…”.
Then <span class="c013">imagen</span> must be invoked with option <a id="hevea_default136"></a><span class="c013">-
todir</span>:
</p><div class="flushleft">
<span class="c013"># imagen -todir</span> <span class="c018">dir</span> <em>doc</em>
</div><p>
As usual, <span class="c013">hevea</span> will invoke <span class="c013">imagen</span> with the
appropriate option, provided it is passed the <span class="c013">-fix</span> option.</p>
<h3 class="subsection" id="imagen-source">10.7  Controlling <span class="c013">imagen</span> from document source</h3>
<p>
<a id="hevea_default137"></a>
The internal command
<code>\@addimagenopt{</code><span class="c018">option</span><code>}</code> add
the text <span class="c018">option</span> to <span class="c013">imagen</span> command-line options, when
launched automatically by <span class="c013">hevea</span> (<em>i.e.</em> when
<span class="c013">hevea</span> is given the <a id="hevea_default138"></a><span class="c013">-fix</span> command-line option).</p><p>For instance, to instruct <span class="c013">hevea</span>/<span class="c013">imagen</span> to
reduce all images by a factor of √<span style="text-decoration:overline">2</span>, it suffices to state:
</p><div class="flushleft">
<span class="c013">%HEVEA</span><code>\@addimagenopt{-mag 707}</code>
</div><p>
See section <a href="manual041.html#imagenusage">C.1.5</a> for the list of command-line options
accepted by <span class="c013">imagen</span>.</p>
<hr>
<a href="manual019.html"><img src="previous_motif.gif" alt="Previous"></a>
<a href="manual002.html"><img src="contents_motif.gif" alt="Up"></a>
<a href="manual021.html"><img src="next_motif.gif" alt="Next"></a>
</body>
</html>
