<!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>Usage</TITLE>
</HEAD>
<BODY >
<A HREF="manual040.html"><IMG SRC="contents_motif.gif" ALT="Up"></A>
<A HREF="browser.html"><IMG SRC="next_motif.gif" ALT="Next"></A>
<HR>
<H2 CLASS="section"><A NAME="htoc149">C.1</A>  Usage</H2><UL>
<LI><A HREF="manual041.html#toc119">H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A usage</A>
</LI><LI><A HREF="manual041.html#toc120">H<FONT SIZE=2><sup>A</sup></FONT>C<FONT SIZE=2><sup>H</sup></FONT>A usage</A>
</LI><LI><A HREF="manual041.html#toc121"><TT>esponja</TT> usage</A>
</LI><LI><A HREF="manual041.html#toc122"><TT>bibhva</TT> usage</A>
</LI><LI><A HREF="manual041.html#toc123"><TT>imagen</TT> usage</A>
</LI><LI><A HREF="manual041.html#toc124">Invoking <TT>hevea</TT>, <TT>hacha</TT> and <TT>imagen</TT></A>
</LI><LI><A HREF="manual041.html#toc125">Using <TT>make</TT></A>
</LI></UL>
<H3 CLASS="subsection"><A NAME="toc119"></A><A NAME="htoc150">C.1.1</A>  H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A usage</H3><P><A NAME="heveausage"></A>
<A NAME="@default238"></A>
The <TT>hevea</TT> command has two operating modes, normal mode and
filter mode.
Operating mode is determined by the nature of the last command-line
argument.</P><H4 CLASS="subsubsection">C.1.1.1  Command line arguments</H4><P><A NAME="comline"></A>
The <TT>hevea</TT> command interprets its arguments as names of
files and attempts to process them.
Given an argument <I>filename</I> there are two cases:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
If <I>filename</I> is <I>base</I><TT>.tex</TT> or
<I>base</I><TT>.hva</TT>,
then a single attempt to open <I>filename</I> is made.
</LI><LI CLASS="li-itemize">In other cases,
a first attempt to open <I>filename</I><TT>.tex</TT> is made.
In case of failure, a second attempt to open <I>filename</I> is made.
</LI></UL><P>
<A NAME="search:path"></A>
In all attempts, implicit filenames are
searched along <TT>hevea</TT> search path, which consist in:
</P><OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
the current directory “<TT>.</TT>”,
</LI><LI CLASS="li-enumerate">user-specified directories (with the <TT>-I</TT> command-line
option),
</LI><LI CLASS="li-enumerate"><TT>hevea</TT> library directory.
</LI><LI CLASS="li-enumerate">one of the sub-directories <TT>html</TT>, <TT>text</TT> or
<TT>info</TT> from <TT>hevea</TT> library directory, depending upon
<TT>hevea</TT> output format,
</LI></OL><P>
<A NAME="@default239"></A>
The <TT>hevea</TT> library directory is fixed at compile-time
(this is where <TT>hevea</TT> library files are installed)
and typically is <TT>/usr/local/lib/hevea</TT>.
However, this compile-time value can be overridden
by setting the <TT>HEVEADIR</TT> shell environment variable.
In all cases, the value of <TT>hevea</TT> library directory can
be accessed from the processed document as the value of the command
<CODE>\@hevealibdir</CODE>.</P><H4 CLASS="subsubsection">C.1.1.2  Normal mode</H4><P><A NAME="basenames"></A>
If the last argument has an extension that is different from
<TT>.hva</TT> or has no extension,
then it is interpreted as the name of the <EM>main input file</EM>.
The main input file is the document to be translated and normally
contains the <CODE>\documentclass</CODE> command.
In that case two <EM>basenames</EM> are defined:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
The input basename, <I>basein</I>,
is defined as the main input file name,
with extension removed when present.
</LI><LI CLASS="li-itemize">The output basename, <I>baseout</I>, is <I>basein</I>
with leading directories omitted. However the output basename can be
changed, using the <CODE>-o</CODE> option (see <A HREF="#output:base">below</A>).
</LI></UL><P>
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A will attempt to load the main input file.
Ancillary files from a previous run of L<sup>A</sup>T<sub>E</sub>X
(<EM>i.e.</EM> <TT>.aux</TT>, <TT>.bll</TT> and <TT>.idx</TT> files)
will be searched as <I>basein</I><CODE>.</CODE><I>ext</I>.
The output base name governs all files produced by H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A.
That is, HTML output of H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A normally goes to the file
<I>baseout</I><TT>.html</TT>,
while cross-referencing information goes into
<I>baseout</I><TT>.haux</TT>. Furthemore,
if an <I>image</I> file is generated (cf. section <A HREF="manual008.html#imagen">6</A>), its
name will be <I>baseout</I><TT>.image.tex</TT>.</P><P>Thus, in the simple case where the <TT>hevea</TT> command is invoked
as:
</P><PRE CLASS="verbatim"># hevea file.tex
</PRE><P>The input basename is <TT>file</TT> and the output basename also is
<TT>file</TT>. The main input file is searched once along <TT>hevea</TT>
search path as <TT>file.tex</TT>.
HTML output goes into file
<TT>file.html</TT>, in the current directory.
In the more complicated case where the <TT>hevea</TT> command is invoked
as:
</P><PRE CLASS="verbatim"># hevea ./dir/file
</PRE><P>The input base name is <TT>./dir/file</TT> and the output basename is
<TT>file</TT>. The main input file is loaded by first attempting to
open file <TT>./dir/file.tex</TT>, then file <TT>./dir/file</TT>.
HTML output goes into file <TT>file.html</TT>, in the current directory.</P><P><A NAME="output:base">Finally</A>, the output base name can be a full path,
but you have to use option <A NAME="@default240"></A><TT>-o</TT>.
For instance, we consider:
</P><PRE CLASS="verbatim"># hevea -o out/out.html file.tex
</PRE><P>Then, HTML output goes into <TT>out/out.html</TT> — notice
that directory <TT>out</TT> must exist.
Furthermore, <TT>hevea</TT> output base name is <TT>out/out</TT>.
This means that <TT>hevea</TT> generates files
<TT>out/out.haux</TT>, <TT>out/out.image.tex</TT> etc.</P><P>The <TT>article.hva</TT>, <TT>seminar.hva</TT>, <TT>book.hva</TT> and
<TT>report.hva</TT>
base style files from H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A library are special.
Only the first base style file is loaded and the
<CODE>\documentclass</CODE> command has no effect when a base style file is
already loaded. This feature allows to override the document base style.
Thus, a document <TT>file.tex</TT> can be translated using the
<I>article</I> base style as follows:
</P><PRE CLASS="verbatim"># hevea article.hva file.tex
</PRE><H4 CLASS="subsubsection">C.1.1.3  Filter mode</H4><P>
If there is no command-line argument, or if the last command-line
argument has the extension <TT>.hva</TT>, then
there is neither input base name nor output base name,
the standard input is read and
output normally goes to the standard output.
Output starts immediately, whithout waiting for <CODE>\begin{document}</CODE>.
In other words <TT>hevea</TT> acts as a filter.</P><P>Please note that this operating mode is just for translating
isolated L<sup>A</sup>T<sub>E</sub>X constructs.
The normal way to translate a full document <I>file</I><CODE>.tex</CODE> being
“<CODE>hevea</CODE> <I>file</I><CODE>.tex</CODE>” and not
“<CODE>hevea < </CODE> <I>file</I><CODE>.tex > </CODE><I>file</I><CODE>.html</CODE>”.</P><H4 CLASS="subsubsection">C.1.1.4  Options</H4><P><A NAME="heveaoptions"></A>
The <TT>hevea</TT> command recognizes the following options:
</P><DL CLASS="description"><DT CLASS="dt-description">
<TT><B>-version</B></TT></DT><DD CLASS="dd-description"> Show <TT>hevea</TT> version and exit.
</DD><DT CLASS="dt-description"><TT><B>-v</B></TT></DT><DD CLASS="dd-description"> Verbose flag, can be repeated to increase
verbosity. However, this is mostly for debug.
</DD><DT CLASS="dt-description"><TT><B>-dv</B></TT></DT><DD CLASS="dd-description"> Add border around some of the block-level
elements issued. Specifically, all <CODE>DIV</CODE> and <CODE>P</CODE> are bordered,
while the structure of displayed material is also shown.
</DD><DT CLASS="dt-description"><TT><B>-s</B></TT></DT><DD CLASS="dd-description"> Suppress warnings.
</DD><DT CLASS="dt-description"><B><TT>-I</TT> <I>dirname</I></B></DT><DD CLASS="dd-description"> Add <I>dirname</I> to the search path.
</DD><DT CLASS="dt-description"><B><TT>-o</TT> <I>name</I></B></DT><DD CLASS="dd-description"> Make <I>name</I> the output basename.
However, if <I>name</I> is <I>base</I><TT>.html</TT>, then
the output basename is <I>base</I>.
Besides, <TT>-o -</TT> makes H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A output to standard output.
</DD><DT CLASS="dt-description"><B><TT>-e</TT> <I>filename</I></B></DT><DD CLASS="dd-description"> Prevent <TT>hevea</TT> from loading any file
whose name is <I>filename</I>. Note that this option applies to all
files, including <TT>hevea.hva</TT> and base style files.
</DD><DT CLASS="dt-description"><TT><B>-fix</B></TT></DT><DD CLASS="dd-description"> Iterate H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A until a fixpoint is found.
Additionally, images get generated automatically.
</DD><DT CLASS="dt-description"><TT><B>-O</B></TT></DT><DD CLASS="dd-description"> Optimize HTML by calling <TT>esponja</TT> (see
section <A HREF="#esponjausage">C.1.3</A>).
</DD><DT CLASS="dt-description"><B><TT>-exec</TT> <I>prog</I></B></DT><DD CLASS="dd-description"> Execute file <I>prog</I> and read the
output. The file <I>prog</I> must have execution permission and is
searched by following the searching rules of <TT>hevea</TT>.
</DD><DT CLASS="dt-description"><TT><B>-francais</B></TT></DT><DD CLASS="dd-description"> Deprecated by <TT>babel</TT> support. This
option issues a warning message.
</DD><DT CLASS="dt-description"><TT><B>-help</B></TT></DT><DD CLASS="dd-description"> Print version number and a short help message.
</DD></DL><P>The following options control the HTML code produced by
<TT>hevea</TT>. By default, <TT>hevea</TT> outputs a page encoded in
US-ASCII with most symbols rendered as HTML or numerical Unicode
entities.
</P><DL CLASS="description"><DT CLASS="dt-description">
<TT><B>-entities</B></TT></DT><DD CLASS="dd-description"> Render symbols by using entities. This is the default.
</DD><DT CLASS="dt-description"><TT><B>-textsymbols</B></TT></DT><DD CLASS="dd-description"> Render symbols by English text.
</DD><DT CLASS="dt-description"><TT><B>-moreenties</B></TT></DT><DD CLASS="dd-description"> Enable the output of some unfrequent entities. Use
this option to target browsers with wide entities support.
</DD><DT CLASS="dt-description"><TT><B>-mathml</B></TT></DT><DD CLASS="dd-description"> Produces MathML output for equations, very
experimental.
</DD><DT CLASS="dt-description"><TT><B>-pedantic</B></TT></DT><DD CLASS="dd-description"> Be strict in interpreting HTML
definition. In particular, this option disable size and color changes inside
<CODE><PRE></CODE>… <CODE></PRE></CODE>, which are otherwise performed.
</DD></DL><P>The following options select and control alternative output formats
(see section <A HREF="manual021.html#alternative">11</A>):
</P><DL CLASS="description"><DT CLASS="dt-description">
<TT><B>-text</B></TT></DT><DD CLASS="dd-description"> Output plain text. Output file
extension is <TT>.txt</TT>.
</DD><DT CLASS="dt-description"><TT><B>-info</B></TT></DT><DD CLASS="dd-description"> Output info format. Output file extension
is <TT>.info</TT>.
</DD><DT CLASS="dt-description"><B><TT>-w</TT> <I>width</I></B></DT><DD CLASS="dd-description"> Set the line width for text or info
output, defaults to 72.
</DD></DL><P>Part <A HREF="manual002.html#usermanual">A</A> of this document is
a tutorial introduction to H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A,
while Part <A HREF="manual022.html#referencemanual">B</A> is the reference manual of H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A.</P><H3 CLASS="subsection"><A NAME="toc120"></A><A NAME="htoc151">C.1.2</A>  H<FONT SIZE=2><sup>A</sup></FONT>C<FONT SIZE=2><sup>H</sup></FONT>A usage</H3><P>
<A NAME="@default241"></A>
The <TT>hacha</TT> command interprets its argument
<I>base</I><TT>.html</TT> as the name of
a HTML source file to cut into pieces.</P><P>It also recognizes the following options:
</P><DL CLASS="description"><DT CLASS="dt-description">
<TT><B>-v</B></TT></DT><DD CLASS="dd-description"> Be a little verbose.
</DD><DT CLASS="dt-description"><B><TT>-o</TT> <I>filename</I></B></DT><DD CLASS="dd-description"> Make H<FONT SIZE=2><sup>A</sup></FONT>C<FONT SIZE=2><sup>H</sup></FONT>A output go into file
<I>filename</I> (defaults to index.html).
Additionally, if <I>filename</I> is a composite filename,
<I>dir/base</I>, then all files outputted by H<FONT SIZE=2><sup>A</sup></FONT>C<FONT SIZE=2><sup>H</sup></FONT>A will
reside in directory <I>dir</I>.
</DD><DT CLASS="dt-description"><TT><B>-tocbis</B></TT></DT><DD CLASS="dd-description">
Another style for table of contents:
sub-tables are replicated at the beginning of
every file.
</DD><DT CLASS="dt-description"><TT><B>-tocter</B></TT></DT><DD CLASS="dd-description">
Like <TT>-tocbis</TT> above, except that
sub-tables do not appear in the main table of contents
(see Section <A HREF="cutname.html#table:link:style">7.2.3</A>).
</DD><DT CLASS="dt-description"><TT><B>-nolinks</B></TT></DT><DD CLASS="dd-description"> Do not insert Previous/Up/Next links in
generated pages.
</DD><DT CLASS="dt-description"><TT><B>-hrf</B></TT></DT><DD CLASS="dd-description"> Output a <I>base</I><TT>.hrf</TT> file, showing
in which output files are the anchors from the input file gone.
The format of this summary is one
“<I>anchor</I><CODE>\t</CODE><I>file</I>” line per anchor.
This information may be needed by other tools.
</DD><DT CLASS="dt-description"><TT><B>-help</B></TT></DT><DD CLASS="dd-description"> Print version number and a short help message.
</DD></DL><P>Section <A HREF="cutname.html#hacha">7</A> of the user manual explains how to
alter H<FONT SIZE=2><sup>A</sup></FONT>C<FONT SIZE=2><sup>H</sup></FONT>A default behavior.</P><H3 CLASS="subsection"><A NAME="toc121"></A><A NAME="htoc152">C.1.3</A>  <TT>esponja</TT> usage</H3><P><A NAME="esponjausage"></A>
<A NAME="@default242"></A>
The program <TT>esponja</TT>
is part of H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A and is designed to optimize <TT>hevea</TT>
output.
However, <TT>esponja</TT> can also be used alone to optimize
text-level elements in HTML files.
Since <TT>esponja</TT> fails
to operate when it detects incorrect HTML, it can be used as a
partial HTML validator.</P><H4 CLASS="subsubsection">C.1.3.1  Operating modes</H4><P>
With no argument, <TT>esponja</TT> acts as a filter, it reads the
standard input and writes on the standard output.
Otherwise, <TT>esponja</TT> interprets its arguments as names of
files and attempt to process them.
It is important to notice that <TT>esponja</TT> will <EM>replace</EM> files
by their optimized versions.</P><P>Hence, to optimize file <TT>foo.html</TT> into <TT>foo_opt.html</TT>,
one should invoke <TT>esponja</TT> as follows.
</P><PRE CLASS="verbatim"># esponja < foo.html > foo_opt.html
</PRE><P>By contrast, invoking <TT>esponja</TT> as
</P><PRE CLASS="verbatim"># esponja foo.html
</PRE><P>will alter <TT>foo.html</TT>.
Of course, if <TT>esponja</TT> does not succeed in making <TT>foo.html</TT> any
smaller or if <TT>esponja</TT> fails, the original <TT>foo.html</TT>
is left unchanged.
Note that this feature allows to optimize all HTML files in a given directory
by:
</P><PRE CLASS="verbatim"># esponja *.html
</PRE><H4 CLASS="subsubsection">C.1.3.2  Options</H4><P><A NAME="esponjaoptions"></A>
The command <TT>esponja</TT> recognizes the following options:
</P><DL CLASS="description"><DT CLASS="dt-description">
<TT><B>-v</B></TT></DT><DD CLASS="dd-description">Be verbose, can be repeated to increase verbosity.
</DD><DT CLASS="dt-description"><TT><B>-n</B></TT></DT><DD CLASS="dd-description">Do not alter input files. Instead, <TT>esponja</TT>
output for file <I>input</I> goes to file
<I>input</I><TT>.esp</TT>. Option <TT>-n</TT>
implies option <TT>-v</TT>.
</DD><DT CLASS="dt-description"><TT><B>-u</B></TT></DT><DD CLASS="dd-description">Output <TT>esponja</TT> intermediate version of HTML.
In most occasions, this amounts to pessimize instead of to optimize.
It may yield challenging input for other HTML optimizers.
</DD></DL><H3 CLASS="subsection"><A NAME="toc122"></A><A NAME="htoc153">C.1.4</A>  <TT>bibhva</TT><A NAME="bibhva"></A> usage</H3><P>
The program <TT>bibhva</TT>
is a simple wrapper, which basically
forces <TT>bibtex</TT> into accepting a <TT>.haux</TT> file as input
and producing a <TT>.hbbl</TT> file as output.
Usage is
<TT>bibhva </TT><I>bibtex-options<TT> </TT>basename</I>.</P><H3 CLASS="subsection"><A NAME="toc123"></A><A NAME="htoc154">C.1.5</A>  <TT>imagen</TT> usage</H3><P><A NAME="imagenusage"></A>
<A NAME="@default243"></A>
The command <TT>imagen</TT> is a simple shell script that translates
a L<sup>A</sup>T<sub>E</sub>X document into many <TT>.gif</TT> images.
The <TT>imagen</TT> script relies on much software to be installed on
your computer, see Section <A HREF="manual044.html#imagen:needs">C.4.1</A>.</P><P>It is a companion program of H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A, which must have been previously run as:
</P><DIV CLASS="flushleft">
<TT># hevea</TT>… <I>base</I><TT>.tex</TT><BR>
or<BR>
<TT># hevea</TT>… <TT>-o</TT> <I>base</I><TT>.html</TT>…<BR>
</DIV><P>
In both cases, <I>base</I> is H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A output basename.
When told to do so (see section <A HREF="manual008.html#imagen">6</A>)
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A echoes part of its input into
the <I>base</I><TT>.image.tex</TT> file.</P><P>The <TT>imagen</TT> script should then be run as:
</P><DIV CLASS="flushleft">
<TT># imagen</TT> <I>base</I>
</DIV><P>
The <TT>imagen</TT> script produces
one <I>base<FONT COLOR=maroon>nnn</FONT></I><TT>.gif</TT> image file per page in the
<I>base</I><TT>.image.tex</TT> file.</P><P>This is done by first calling <TT>latex</TT> on
<I>base</I><TT>.image.tex</TT>, yielding one <TT>dvi</TT>
file.
Then, <TT>dvips</TT> translates this file into one single Postscript file that
contains all
the images, or into one Postscript file per image,
depending upon your version of <TT>dvips</TT>.
Postscript files are interpreted by ghostscript (<TT>gs</TT>) that
outputs <TT>ppm</TT> images, which are then fed into a series of
transformations that change them into <TT>.gif</TT> files.</P><P>The <TT>imagen</TT> script recognizes the following options:
</P><DL CLASS="description"><DT CLASS="dt-description">
<B><TT>-mag</TT> <FONT COLOR=maroon><I>nnnn</I></FONT></B></DT><DD CLASS="dd-description"> Change the enlarging ratio that is applied
while translating DVI into Postscript.
More precisely, <TT>dvips</TT> is run with <TT>-x</TT><FONT COLOR=maroon><I>nnnn</I></FONT>
option.
Default value for this ration is 1414, this means
that, by default, <TT>imagen</TT> magnifies L<sup>A</sup>T<sub>E</sub>X output by a factor of
1.414.
</DD><DT CLASS="dt-description"><B><TT>-extra</TT> <I>command</I></B></DT><DD CLASS="dd-description"> Insert <I>command</I> as an additional
stage in <TT>imagen</TT> <TT>ppm</TT> to <TT>gif</TT> production chain.
<I>command</I> is an Unix filter that expects a <TT>ppm</TT> image
in its standard input and outputs a <TT>ppm</TT> image on its standard output.
A sensible choice for <I>command</I> is one command from the
<TT>netpbm</TT> package or several such commands piped together.
</DD><DT CLASS="dt-description"><B><TT>-quant</TT> <I>number</I></B></DT><DD CLASS="dd-description"> Add an extra color quantization step
in <TT>imagen</TT> <TT>ppm</TT> image production chain, where
<I>number</I> is the maximal number of colors in the produced
images. This option may be needed as a response to a failure in the
image production chain. It can also help in limiting image files size.
</DD><DT CLASS="dt-description"><TT><B>-gif</B></TT></DT><DD CLASS="dd-description"> Output GIF images. This is the default.
</DD><DT CLASS="dt-description"><TT><B>-png</B></TT></DT><DD CLASS="dd-description"><A NAME="@default244"></A>
Output PNG images in place of GIF images.
PNG is sometimes preferred for legal reasons.
PNG image files have a <TT>.png</TT> extension.
Note that <TT>hevea</TT> should have been previously run as
<TT>hevea png.hva</TT> <I>base</I><TT>.tex</TT> (so that the proper
<TT>.png</TT> filename
extension is given to image file references from within the HTML
document).
Beware that the <TT>pnmtopng</TT> program looks to be plagued by bugs
in old versions of the <TT>netpbm</TT> package.
</DD><DT CLASS="dt-description"><TT><B>-pnm</B></TT></DT><DD CLASS="dd-description"> Output PPM images. This option mostly serves
debugging purposes. Experimented users can also take advantage
of it for performing additional image transformation or
adopting exotic image formats.
</DD><DT CLASS="dt-description"><B><TT>-t</TT> <I>arg</I></B></DT><DD CLASS="dd-description"> Pass option “<TT>-t</TT> <I>arg</I>” to
<TT>dvips</TT>.
For instance, using “<TT>-t a3</TT>” may help when images are
truncated on the right.
</DD><DT CLASS="dt-description"><TT><B>-pdf</B></TT></DT><DD CLASS="dd-description"><A NAME="@default245"></A><A NAME="@default246"></A>
Have <TT>imagen</TT> call <TT>pdflatex</TT> instead
of <TT>latex</TT>.
</DD></DL><P>The first three options enable users to correct some misbehaviors.
For instance, when the document base style is <I>seminar</I>, image
orientation may
be wrong and the images are too small. This can be cured by invoking
<TT>imagen</TT> as:
</P><DIV CLASS="flushleft">
<TT># imagen -extra "pnmflip -ccw" -mag 2000</TT> <I>base</I>
</DIV><P>Notice that <TT>hevea</TT> calls <TT>imagen</TT> by itself,
when given the command-line option <A NAME="@default247"></A><TT>-fix</TT>.
In that situation, the command-line options of <TT>imagen</TT> can
be controled from source file by using the
command <CODE>\@addimagenopt</CODE> (see Section <A HREF="manual020.html#imagen-source">10.7</A>).</P><H3 CLASS="subsection"><A NAME="toc124"></A><A NAME="htoc155">C.1.6</A>  Invoking <TT>hevea</TT>, <TT>hacha</TT> and <TT>imagen</TT></H3><P>
In this section, we give a few sequence of (Unix) commands to build
the HTML version of a document in various
situations. The next section gives a few
<TT>Makefile</TT>’s for similar situations.</P><P>We translate a file <TT>doc.tex</TT>
that requires a specific style file <TT>doc.hva</TT>.
The file is first translated into <TT>doc.html</TT> by <TT>hevea</TT>,
which also reads
the specific style file <TT>doc.hva</TT>.
Then, <TT>hacha</TT> cuts <TT>doc.html</TT> into several,
<TT>doc001.html</TT>, <TT>doc002.html</TT>, etc. also producing the
table of links file <TT>index.html</TT>.
</P><PRE CLASS="verbatim"># hevea -fix doc.hva doc.tex
# hacha doc.html
</PRE><P>Thanks to the command-line option <A NAME="@default248"></A><TT>-fix</TT>, <TT>hevea</TT> runs the
appropriate number of times automatically.
In case <TT>hevea</TT> produces a non-empty <TT>doc.image.tex</TT>
file, then <TT>hevea</TT> calls <TT>imagen</TT> by itself
(because of option <TT>-fix</TT>).
Hence, the above sequence of two commands is also appropriate in
that situation.</P><P>In case some problem occurs, it is sometime convenient to
run <TT>imagen</TT> by hand.
It is time <EM>not</EM> to use the option <TT>-fix</TT>.
</P><PRE CLASS="verbatim"># rm -f doc.image.tex
# hevea doc.hva doc.tex
</PRE><P>Now, <TT>hevea</TT> normally has shown the <TT>imagen</TT>
command line that it would have run, if it had been given
the option <TT>-fix</TT>.
For instance, if <TT>doc.hva</TT> includes <CODE>\input{png.hva}</CODE>, then
<TT>hevea</TT> shows the following warning:
</P><PRE CLASS="verbatim">HeVeA Warning: images may have changed, run 'imagen -png doc'
</PRE><P>Now, one can run <TT>imagen</TT> as it should be.</P><P>It is sometime convenient not to clobber source directory with
numerous target files.
It suffices to instruct
<TT>hevea</TT> and <TT>hacha</TT> to output files in a
specific directory, say <TT>doc</TT>.
</P><PRE CLASS="verbatim"># hevea -fix -o doc/doc.html doc.hva doc.tex
# hacha -o doc/index.html doc/doc.html
</PRE><P>Notice that <TT>hevea</TT> does not create the target directory
<TT>doc</TT>: it must exist before <TT>hevea</TT> runs.
Again, in case <TT>hevea</TT> calls <TT>imagen</TT>,
image generation should proceed smoothly and the final files
<TT>doc001.gif</TT>, <TT>doc002.gif</TT>, … should go into
directory <TT>doc</TT>.</P><P>In all situations, while installing files to their final destination,
it is important not to forget any relevant files.
In particular, in addition to the root file
(<TT>index.html</TT>), contents files (<TT>doc001.html</TT>,
<TT>doc002.html</TT>, etc.) and images
(<TT>doc001.gif</TT>, <TT>doc002.gif</TT>, etc.),
one should not forget the arrow images and the
style sheet generated by <TT>hacha</TT>
(<TT>contents_motif.gif</TT>, <TT>next_motif.gif</TT>,
<TT>previous_motif.gif</TT> and <TT>doc.css</TT>).</P><P>As a consequence, producing all files into the subdirectory
<TT>doc</TT> may be a good idea, since then one easily install all
relevant files by copying <TT>doc</TT> to a public destination.
</P><PRE CLASS="verbatim"># cp -r doc $(HOME)/public_html
</PRE><P>However, one then also installs the auxiliary files of <TT>hevea</TT>,
and <TT>hevea</TT> output file <TT>doc.html</TT>, which is no longer
useful once <TT>hacha</TT> has run.
Hence, those should be erased beforehand.
</P><PRE CLASS="verbatim"># rm -f doc/doc.h{tml,aux,ind,toc} doc/doc.image.tex
# cp -r doc $(HOME)/public_html
</PRE><H3 CLASS="subsection"><A NAME="toc125"></A><A NAME="htoc156">C.1.7</A>  Using <A NAME="makefile"></A><TT>make</TT></H3><P>Here is a typical <TT>Makefile</TT>, which is approriate when
no images are produced.
</P><PRE CLASS="verbatim">HEVEA=hevea
HEVEAOPTS=-fix
HACHA=hacha
#document base name
DOC=doc
index.html: $(DOC).html
$(HACHA) -o index.html $(DOC).html
$(DOC).html: $(DOC).hva $(DOC).tex
$(HEVEA) $(HEVEAOPTS) $(DOC).hva $(DOC).tex
clean:
rm -f $(DOC).html $(DOC).h{toc,aux,ind}
rm -f index.html $(DOC)[0-9][0-9][0-9].html $(DOC).css
</PRE><P>Note that the <TT>clean</TT> rule removes all the <TT>doc001.html</TT>,
<TT>doc002.html</TT>, etc. and <TT>doc.css</TT> files produced by
<TT>hacha</TT>.
Also note that <TT>make clean</TT> also removes the
<TT>doc.haux</TT>, <TT>doc.hind</TT> and <TT>doc.htoc</TT> files, which are H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A
auxiliary files.</P><P>When the <I>image</I> file feature is used, one can use the
following, extended, <TT>Makefile</TT>:
</P><PRE CLASS="verbatim">HEVEA=hevea
HEVEAOPTS=-fix
HACHA=hacha
#document base name
DOC=doc
index.html: $(DOC).html
$(HACHA) -o index.html $(DOC).html
$(DOC).html: $(DOC).hva $(DOC).tex
$(HEVEA) $(HEVEAOPTS) $(DOC).hva $(DOC).tex
clean:
rm -f $(DOC).html $(DOC).h{toc,aux,ind}
rm -f index.html $(DOC)[0-9][0-9][0-9].html $(DOC).css
rm -f $(DOC).image.* $(DOC)[0-9][0-9][0-9].gif *_motif.gif
</PRE><P>Observe that the <TT>clean</TT> rule now also gets rid of
<TT>doc.image.tex</TT> and of the various files produced by
<TT>imagen</TT>.</P><P>With the following <TT>Makefile</TT>,
<TT>hevea</TT>, <TT>imagen</TT>, <TT>hacha</TT> all output their files into
a specific directory <TT>DIR</TT>.
</P><PRE CLASS="verbatim">HEVEA=hevea
HEVEAOPTS=-fix
HACHA=hacha
#document base name
DOC=doc
DIR=$(HOME)/public_html/$(DOC)
BASE=$(DIR)/$(DOC)
$(DIR)/index.html: $(BASE).html
$(HACHA) -tocter -o $(DIR)/index.html $(BASE).html
$(BASE).html: $(DOC).hva $(DOC).tex
$(HEVEA) $(HEVEAOPTS) $(DOC).hva -o $(BASE).html $(DOC).tex
partialclean:
rm -f $(BASE).h{tml,aux,toc,ind} $(BASE).image.*
clean:
rm -f $(DIR)/*
</PRE><P>The above <TT>Makefile</TT> directly produces HTML and GIF files
into the final directory <CODE>$(HOME)/public_html/$(DOC)</CODE>.
The new <TT>partialclean</TT> entry erases files that are not
useful anymore, once <TT>imagen</TT> and <TT>hacha</TT> have
performed their tasks.</P><P>However, most often, it is more appropriate to build HTML and GIF files
in a specific directory, and then to copy them to their final
destination.
</P><PRE CLASS="verbatim"> ...
#document base name
DOC=doc
DIR=$(DOC)
BASE=$(DIR)/$(DOC)
INSTALLDIR=$(HOME)/public_html/$(DOC)
...
install: partialclean
cp $(DIR)/* $(INSTALLDIR)
...
</PRE><HR>
<A HREF="manual040.html"><IMG SRC="contents_motif.gif" ALT="Up"></A>
<A HREF="browser.html"><IMG SRC="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
