<!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>Customizing 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"><A NAME="htoc44">10</A>  Customizing H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A</H2><UL>
<LI><A HREF="manual020.html#toc34">Simple changes</A>
</LI><LI><A HREF="manual020.html#toc35">Changing defaults for type-styles</A>
</LI><LI><A HREF="manual020.html#toc36">Changing the interface of a command</A>
</LI><LI><A HREF="manual020.html#toc37">Checking the optional argument within a command</A>
</LI><LI><A HREF="manual020.html#toc38">Changing the format of images</A>
</LI><LI><A HREF="manual020.html#toc39">Storing images in a separate directory</A>
</LI><LI><A HREF="manual020.html#toc40">Controlling <TT>imagen</TT> from document source</A>
</LI></UL>
<P>
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A default behavior or add
functionalities. In all this section we assume that a document
<TT>doc.tex</TT> is processed, using a private command file
<TT>macros.hva</TT>. That is, H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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
<TT>macros.hva</TT>, 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"><A NAME="toc34"></A><A NAME="htoc45">10.1</A>  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
emphasized. Then, it suffices to put the following redeclaration in
<TT>macros.hva</TT>:
</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 customize 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 <TT>macros.hva</TT> file:
</P><PRE CLASS="verbatim">\newstyle{.quote}{font-style:oblique;}
</PRE><P>This works because the environment <TT>quote</TT> is styled through
style class <TT>quote</TT> (see Section <A HREF="manual019.html#css:change:all">9.2</A>).
Notice that this solution has very little to do with
“<EM>emphasizing</EM>” in the proper sense, since here we
short-circuit the implicit path from <CODE>\em</CODE> to oblique fonts.</P><H3 CLASS="subsection"><A NAME="toc35"></A><A NAME="htoc46">10.2</A>  Changing defaults for type-styles</H3><P><A NAME="customize-style"></A>
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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 maroon
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"><HR NOSHADE SIZE=1 ALIGN=center>
<I>italic shape <FONT COLOR=maroon>slanted shape
</FONT></I><SPAN STYLE="font-variant:small-caps">small caps shape </SPAN>upright shape
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE><P>If one wishes to change the rendering of some of the shapes (say small
caps), then one should redefine the old-style <CODE>\sc</CODE> declaration.
For instance, to render small caps as bold fonts, one should
redefine <CODE>\sc</CODE> by <CODE>\renewcommand{\sc}{\@style{B}}</CODE> in
<TT>macros.hva</TT>.</P><P>
And now, the shape example above gets rendered as follows:
</P><BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>
<I>italic shape <FONT COLOR=maroon>slanted shape
</FONT></I><B>small caps shape </B>upright shape
<HR NOSHADE SIZE=1 ALIGN=center></BLOCKQUOTE><P>Redefining the old-style <CODE>\sc</CODE> is compatible with the cancellation
mechanism, redefining <CODE>\scshape</CODE> is not.
Thus, redefining directly L<sup>A</sup>T<sub>E</sub>X 2є <CODE>\scshape</CODE> with
<CODE>\renewcommand{\scshape}{\@style{B}}</CODE> would yield:
</P><BLOCKQUOTE CLASS="quote"><HR NOSHADE SIZE=1 ALIGN=center>
<I>italic shape <FONT COLOR=maroon>slanted shape
<B>small caps shape </B></FONT></I><B>upright shape</B>
<HR NOSHADE SIZE=1 ALIGN=center></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"><A NAME="toc36"></A><A NAME="htoc47">10.3</A>  Changing the interface of a command</H3><P><A NAME="customize-let"></A>
Assume for instance that the base style of <TT>doc.tex</TT> is
<I>jsc</I> (the
<EM>Journal of Symbolic Computation</EM> style for articles).
For running H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A, the <I>jsc</I> style can be replaced by
<I>article</I>
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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A should ignore
anyway).
However, H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A can process the document as it stands.
One solution to insert the following lines into <TT>macros.hva</TT>:
</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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A <CODE>\title</CODE> with the appropriate argument.
</P><H3 CLASS="subsection"><A NAME="toc37"></A><A NAME="htoc48">10.4</A>  Checking the optional argument within a command</H3><P><A NAME="fullepsfbox"></A>
<A NAME="@default130"></A>
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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 <I>image</I> file.
To do this, the H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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"><A NAME="toc38"></A><A NAME="htoc49">10.5</A>  Changing the format of images</H3><P>
<A NAME="@default131"></A>
<A NAME="@default132"></A>
<A NAME="@default133"></A>
<A NAME="@default134"></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 GIF images, stored in <TT>.gif</TT> files.
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A provides direct support for the alternative PNG image file
format.
It suffices to invoke <TT>hevea</TT> as:
</P><DIV CLASS="flushleft">
<TT># hevea png.hva</TT> <I>doc.tex</I>
</DIV><P>
Then <TT>imagen</TT> must be run with option <A NAME="@default135"></A><TT>-png</TT>:
</P><DIV CLASS="flushleft">
<TT># imagen -png</TT> <EM>doc</EM>
</DIV><P>A convenient alternative is to invoke <TT>hevea</TT> as:
</P><DIV CLASS="flushleft">
<TT># hevea -fix png.hva</TT> <I>doc.tex</I>
</DIV><P>
Then <TT>hevea</TT> will invoke <TT>imagen</TT> with the appropriate
option when it thinks images need to be rebuild.</P><H3 CLASS="subsection"><A NAME="toc39"></A><A NAME="htoc50">10.6</A>  Storing images in a separate directory</H3><P>
<A NAME="@default136"></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><I>dir</I><CODE>}</CODE>
</DIV><P>
Then, all links to images in the produced HTML file will be as
“<I>dir</I>/…”.
Then <TT>imagen</TT> must be invoked with option <A NAME="@default137"></A><TT>-
todir</TT>:
</P><DIV CLASS="flushleft">
<TT># imagen -todir</TT> <I>dir</I> <EM>doc</EM>
</DIV><P>
As usual, <TT>hevea</TT> will invoke <TT>imagen</TT> with the
appropriate option, provided it is passed the <TT>-fix</TT> option.</P><H3 CLASS="subsection"><A NAME="toc40"></A><A NAME="htoc51">10.7</A>  Controlling<A NAME="imagen-source"></A> <TT>imagen</TT> from document source</H3><P>
<A NAME="@default138"></A>
The internal command
<CODE>\@addimagenopt{</CODE><I>option</I><CODE>}</CODE> add
the text <I>option</I> to <TT>imagen</TT> command-line options, when
launched automatically by <TT>hevea</TT> (<EM>i.e.</EM> when
<TT>hevea</TT> is given the <A NAME="@default139"></A><TT>-fix</TT> command-line option).</P><P>For instance, to instruct <TT>hevea</TT>/<TT>imagen</TT> to
reduce all images by a factor of √<SPAN style="text-decoration:overline">2</SPAN>, it suffices to state:
</P><DIV CLASS="flushleft">
<TT>%HEVEA</TT><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 <TT>imagen</TT>.</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>
