<!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>