<!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>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" id="sec212">C.1  Usage</h2>
<ul>
<li><a href="manual041.html#sec213">H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A usage</a>
</li><li><a href="manual041.html#sec218">H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A usage</a>
</li><li><a href="manual041.html#sec219"><span class="c013">esponja</span> usage</a>
</li><li><a href="manual041.html#bibhva"><span class="c013">bibhva</span> usage</a>
</li><li><a href="manual041.html#sec223"><span class="c013">imagen</span> usage</a>
</li><li><a href="manual041.html#sec224">Invoking <span class="c013">hevea</span>, <span class="c013">hacha</span> and <span class="c013">imagen</span></a>
</li><li><a href="manual041.html#makefile">Using <span class="c013">make</span></a>
</li></ul>
<h3 class="subsection" id="sec213">C.1.1  H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A usage</h3>
<p><a id="heveausage"></a>
<a id="hevea_default248"></a>
The <span class="c013">hevea</span> 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" id="sec214">C.1.1.1  Command line arguments</h4>
<p><a id="comline"></a>
The <span class="c013">hevea</span> command interprets its arguments as names of
files and attempts to process them.
Given an argument <span class="c018">filename</span> there are two cases:
</p><ul class="itemize"><li class="li-itemize">
If <span class="c018">filename</span> is <span class="c018">base</span><span class="c013">.tex</span> or
<span class="c018">base</span><span class="c013">.hva</span>,
then a single attempt to open <span class="c018">filename</span> is made.
</li><li class="li-itemize">In other cases,
a first attempt to open <span class="c018">filename</span><span class="c013">.tex</span> is made.
In case of failure, a second attempt to open <span class="c018">filename</span> is made.
</li></ul><p>
<a id="search:path"></a>
In all attempts, implicit filenames are
searched along <span class="c013">hevea</span> search path, which consist in:
</p><ol class="enumerate" type=1><li class="li-enumerate">
the current directory “<span class="c013">.</span>”,
</li><li class="li-enumerate">user-specified directories (with the <span class="c013">-I</span> command-line
option),
</li><li class="li-enumerate"><span class="c013">hevea</span> library directory.
</li><li class="li-enumerate">one of the sub-directories <span class="c013">html</span>, <span class="c013">text</span> or
<span class="c013">info</span> from <span class="c013">hevea</span> library directory, depending upon
<span class="c013">hevea</span> output format,
</li></ol><p>
<a id="hevea_default249"></a>
The <span class="c013">hevea</span> library directory is fixed at compile-time
(this is where <span class="c013">hevea</span> library files are installed)
and typically is <span class="c013">/usr/local/lib/hevea</span>.
However, this compile-time value can be overridden
by setting the <span class="c013">HEVEADIR</span> shell environment variable.
In all cases, the value of <span class="c013">hevea</span> library directory can
be accessed from the processed document as the value of the command
<code>\@hevealibdir</code>.</p>
<h4 class="subsubsection" id="sec215">C.1.1.2  Normal mode</h4>
<p><a id="basenames"></a>
If the last argument has an extension that is different from
<span class="c013">.hva</span> 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, <span class="c018">basein</span>,
is defined as the main input file name,
with extension removed when present.
</li><li class="li-itemize">The output basename, <span class="c018">baseout</span>, is <span class="c018">basein</span>
with leading directories omitted. However the output basename can be
changed, using the <code>-o</code> option (see <a href="#output%3Abase">below</a>).
</li></ul><p>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>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> <span class="c013">.aux</span>, <span class="c013">.bll</span> and <span class="c013">.idx</span> files)
will be searched as <span class="c018">basein</span><code>.</code><span class="c018">ext</span>.
The output base name governs all files produced by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.
That is, html output of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A normally goes to the file
<span class="c018">baseout</span><span class="c013">.html</span>,
while cross-referencing information goes into
<span class="c018">baseout</span><span class="c013">.haux</span>. Furthemore,
if an <span class="c018">image</span> file is generated (cf. section <a href="manual008.html#imagen">6</a>), its
name will be <span class="c018">baseout</span><span class="c013">.image.tex</span>.</p><p>Thus, in the simple case where the <span class="c013">hevea</span> command is invoked
as:
</p><pre class="verbatim"># hevea file.tex
</pre><p>The input basename is <span class="c013">file</span> and the output basename also is
<span class="c013">file</span>. The main input file is searched once along <span class="c013">hevea</span>
search path as <span class="c013">file.tex</span>.
html output goes into file
<span class="c013">file.html</span>, in the current directory.
In the more complicated case where the <span class="c013">hevea</span> command is invoked
as:
</p><pre class="verbatim"># hevea ./dir/file
</pre><p>The input base name is <span class="c013">./dir/file</span> and the output basename is
<span class="c013">file</span>. The main input file is loaded by first attempting to
open file <span class="c013">./dir/file.tex</span>, then file <span class="c013">./dir/file</span>.
html output goes into file <span class="c013">file.html</span>, in the current directory.</p><p><a id="output:base">Finally</a>, the output base name can be a full path,
but you have to use option <a id="hevea_default250"></a><span class="c013">-o</span>.
For instance, we consider:
</p><pre class="verbatim"># hevea -o out/out.html file.tex
</pre><p>Then, html output goes into <span class="c013">out/out.html</span> — notice
that directory <span class="c013">out</span> must exist.
Furthermore, <span class="c013">hevea</span> output base name is <span class="c013">out/out</span>.
This means that <span class="c013">hevea</span> generates files
<span class="c013">out/out.haux</span>, <span class="c013">out/out.image.tex</span> etc.</p><p>The <span class="c013">article.hva</span>, <span class="c013">seminar.hva</span>, <span class="c013">book.hva</span> and
<span class="c013">report.hva</span>
base style files from H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>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 <span class="c013">file.tex</span> can be translated using the
<span class="c018">article</span> base style as follows:
</p><pre class="verbatim"># hevea article.hva file.tex
</pre>
<h4 class="subsubsection" id="sec216">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 <span class="c013">.hva</span>, 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 <span class="c013">hevea</span> 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 <span class="c018">file</span><code>.tex</code> being
“<code>hevea</code> <span class="c018">file</span><code>.tex</code>” and not
“<code>hevea < </code> <span class="c018">file</span><code>.tex > </code><span class="c018">file</span><code>.html</code>”.</p>
<h4 class="subsubsection" id="heveaoptions">C.1.1.4  Options</h4>
<p>
The <span class="c013">hevea</span> command recognises the following options:
</p><dl class="description"><dt class="dt-description">
<span class="c014">-version</span></dt><dd class="dd-description"> Show <span class="c013">hevea</span> version and exit.
</dd><dt class="dt-description"><span class="c014">-v</span></dt><dd class="dd-description"> Verbose flag, can be repeated to increase
verbosity. However, this is mostly for debug.
</dd><dt class="dt-description"><span class="c014">-dv</span></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"><span class="c014">-s</span></dt><dd class="dd-description"> Suppress warnings.
</dd><dt class="dt-description"><span class="c022"><span class="c013">-I</span> <span class="c018">dirname</span></span></dt><dd class="dd-description"> Add <span class="c018">dirname</span> to the search path.
</dd><dt class="dt-description"><span class="c022"><span class="c013">-o</span> <span class="c018">name</span></span></dt><dd class="dd-description"> Make <span class="c018">name</span> the output basename.
However, if <span class="c018">name</span> is <span class="c018">base</span><span class="c013">.html</span>, then
the output basename is <span class="c018">base</span>.
Besides, <span class="c013">-o -</span> makes H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output to standard output.
</dd><dt class="dt-description"><span class="c022"><span class="c013">-e</span> <span class="c018">filename</span></span></dt><dd class="dd-description"> Prevent <span class="c013">hevea</span> from loading any file
whose name is <span class="c018">filename</span>. Note that this option applies to all
files, including <span class="c013">hevea.hva</span> and base style files.
</dd><dt class="dt-description"><span class="c014">-fix</span></dt><dd class="dd-description"> Iterate H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A until a fixpoint is found.
Additionally, images get generated automatically.
</dd><dt class="dt-description"><span class="c014">-O</span></dt><dd class="dd-description"> Optimise html by calling <span class="c013">esponja</span> (see
section <a href="#esponjausage">C.1.3</a>).
</dd><dt class="dt-description"><span class="c022"><span class="c013">-exec</span> <span class="c018">prog</span></span></dt><dd class="dd-description"> Execute file <span class="c018">prog</span> and read the
output. The file <span class="c018">prog</span> must have execution permission and is
searched by following the searching rules of <span class="c013">hevea</span>.
</dd><dt class="dt-description"><span class="c014">-francais</span></dt><dd class="dd-description"> Deprecated by <span class="c013">babel</span> support. This
option issues a warning message.
</dd><dt class="dt-description"><span class="c014">-help</span></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
<span class="c013">hevea</span>. By default, <span class="c013">hevea</span> 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">
<span class="c014">-entities</span></dt><dd class="dd-description"> Render symbols by using entities. This is the default.
</dd><dt class="dt-description"><span class="c014">-textsymbols</span></dt><dd class="dd-description"> Render symbols by English text.
</dd><dt class="dt-description"><span class="c014">-moreenties</span></dt><dd class="dd-description"> Enable the output of some infrequent entities. Use
this option to target browsers with wide entities support.
</dd><dt class="dt-description"><span class="c014">-mathml</span></dt><dd class="dd-description"> Produces MathML output for equations, very
experimental.
</dd><dt class="dt-description"><span class="c014">-pedantic</span></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">
<span class="c014">-text</span></dt><dd class="dd-description"> Output plain text. Output file
extension is <span class="c013">.txt</span>.
</dd><dt class="dt-description"><span class="c014">-info</span></dt><dd class="dd-description"> Output info format. Output file extension
is <span class="c013">.info</span>.
</dd><dt class="dt-description"><span class="c022"><span class="c013">-w</span> <span class="c018">width</span></span></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<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A,
while Part <a href="manual022.html#referencemanual">B</a> is the reference manual of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.</p>
<h3 class="subsection" id="sec218">C.1.2  H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A usage</h3>
<p>
<a id="hevea_default251"></a>
The <span class="c013">hacha</span> command interprets its argument
<span class="c018">base</span><span class="c013">.html</span> as the name of
a html source file to cut into pieces.</p><p>It also recognises the following options:
</p><dl class="description"><dt class="dt-description">
<span class="c014">-v</span></dt><dd class="dd-description"> Be a little verbose.
</dd><dt class="dt-description"><span class="c022"><span class="c013">-o</span> <span class="c018">filename</span></span></dt><dd class="dd-description"> Make H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A output go into file
<span class="c018">filename</span> (defaults to index.html).
Additionally, if <span class="c018">filename</span> is a composite filename,
<span class="c018">dir/base</span>, then all files outputted by H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A will
reside in directory <span class="c018">dir</span>.
</dd><dt class="dt-description"><span class="c014">-tocbis</span></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"><span class="c014">-tocter</span></dt><dd class="dd-description">
Like <span class="c013">-tocbis</span> above, except that
sub-tables do not appear in the main table of contents
(see Section <a href="cutname.html#table%3Alink%3Astyle">7.2.3</a>).
</dd><dt class="dt-description"><span class="c014">-nolinks</span></dt><dd class="dd-description"> Do not insert Previous/Up/Next links in
generated pages.
</dd><dt class="dt-description"><span class="c014">-hrf</span></dt><dd class="dd-description"> Output a <span class="c018">base</span><span class="c013">.hrf</span> file, showing
in which output files are the anchors from the input file gone.
The format of this summary is one
“<span class="c018">anchor</span><code>\t</code><span class="c018">file</span>” line per anchor.
This information may be needed by other tools.
</dd><dt class="dt-description"><span class="c014">-help</span></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<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A default behaviour.</p>
<h3 class="subsection" id="sec219">C.1.3  <span class="c013">esponja</span> usage</h3>
<p><a id="esponjausage"></a>
<a id="hevea_default252"></a>
The program <span class="c013">esponja</span>
is part of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A and is designed to optimise <span class="c013">hevea</span>
output.
However, <span class="c013">esponja</span> can also be used alone to optimise
text-level elements in html files.
Since <span class="c013">esponja</span> fails
to operate when it detects incorrect html, it can be used as a
partial html validator.</p>
<h4 class="subsubsection" id="sec220">C.1.3.1  Operating mode</h4>
<p>
The program <span class="c013">esponja</span> interprets its arguments as names of
files and attempt to process them.
It is important to notice that <span class="c013">esponja</span> will <em>replace</em> files
by their optimised versions, unless instructed not to do so with
option <span class="c013">-n</span>.</p><p>Invoking <span class="c013">esponja</span> as
</p><pre class="verbatim"># esponja foo.html
</pre><p>will alter <span class="c013">foo.html</span>.
Of course, if <span class="c013">esponja</span> does not succeed in making <span class="c013">foo.html</span> any
smaller or if <span class="c013">esponja</span> fails, the original <span class="c013">foo.html</span>
is left unchanged.
Note that this feature allows to optimise all html files in a given directory
by:
</p><pre class="verbatim"># esponja *.html
</pre>
<h4 class="subsubsection" id="sec221">C.1.3.2  Options</h4>
<p><a id="esponjaoptions"></a>
The command <span class="c013">esponja</span> recognises the following options:
</p><dl class="description"><dt class="dt-description">
<span class="c014">-v</span></dt><dd class="dd-description">Be verbose, can be repeated to increase verbosity.
</dd><dt class="dt-description"><span class="c014">-n</span></dt><dd class="dd-description">Do not alter input files. Instead, <span class="c013">esponja</span>
output for file <span class="c018">input</span><span class="c013">.html</span> goes to file
<span class="c018">input</span><span class="c013">.esp</span>. Option <span class="c013">-n</span> implies option <span class="c013">-v</span>.
</dd><dt class="dt-description"><span class="c014">-u</span></dt><dd class="dd-description">Output <span class="c013">esponja</span> intermediate version of html.
In most occasions, this amounts to pessimize instead of to optimise.
It may yield challenging input for other html optimisers.
</dd></dl>
<h3 class="subsection" id="bibhva">C.1.4  <span class="c013">bibhva</span> usage</h3>
<p>
The program <span class="c013">bibhva</span>
is a simple wrapper, which basically
forces <span class="c013">bibtex</span> into accepting a <span class="c013">.haux</span> file as input
and producing a <span class="c013">.hbbl</span> file as output.
Usage is
<span class="c013">bibhva </span><span class="c018">bibtex-options<span class="c013"> </span>basename</span>.</p>
<h3 class="subsection" id="sec223">C.1.5  <span class="c013">imagen</span> usage</h3>
<p><a id="imagenusage"></a>
<a id="hevea_default253"></a>
The command <span class="c013">imagen</span> is a simple shell script that translates
a L<sup>A</sup>T<sub>E</sub>X document into many <span class="c013">.png</span> images.
The <span class="c013">imagen</span> script relies on much software to be installed on
your computer, see Section <a href="manual044.html#imagen%3Aneeds">C.4.1</a>.</p><p>It is a companion program of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A, which must have been previously run as:
</p><div class="flushleft">
<span class="c013"># hevea</span>… <span class="c018">base</span><span class="c013">.tex</span><br>
or<br>
<span class="c013"># hevea</span>… <span class="c013">-o</span> <span class="c018">base</span><span class="c013">.html</span>…<br>
</div><p>
In both cases, <span class="c018">base</span> is H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output basename.
When told to do so (see section <a href="manual008.html#imagen">6</a>)
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A echoes part of its input into
the <span class="c018">base</span><span class="c013">.image.tex</span> file.</p><p>The <span class="c013">imagen</span> script should then be run as:
</p><div class="flushleft">
<span class="c013"># imagen</span> <span class="c018">base</span>
</div><p>
The <span class="c013">imagen</span> script produces
one <span class="c018">base</span><span class="c019">nnn</span><span class="c013">.png</span> image file per page in the
<span class="c018">base</span><span class="c013">.image.tex</span> file.</p><p>This is done by first calling <span class="c013">latex</span> on
<span class="c018">base</span><span class="c013">.image.tex</span>, yielding one <span class="c013">dvi</span>
file.
Then, <span class="c013">dvips</span> 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 <span class="c013">dvips</span>.
Postscript files are interpreted by ghostscript (<span class="c013">gs</span>) that
outputs <span class="c013">ppm</span> images, which are then fed into a series of
transformations that change them into <span class="c013">.png</span> files.</p><p>The <span class="c013">imagen</span> script recognises the following options:
</p><dl class="description"><dt class="dt-description">
<span class="c022"><span class="c013">-mag</span> <span class="c019">nnnn</span></span></dt><dd class="dd-description"> Change the enlarging ratio that is applied
while translating DVI into Postscript.
More precisely, <span class="c013">dvips</span> is run with <span class="c013">-x</span><span class="c019">nnnn</span>
option.
Default value for this ration is 1414, this means
that, by default, <span class="c013">imagen</span> magnifies L<sup>A</sup>T<sub>E</sub>X output by a factor of
1.414.
</dd><dt class="dt-description"><span class="c022"><span class="c013">-extra</span> <span class="c018">command</span></span></dt><dd class="dd-description"> Insert <span class="c018">command</span> as an additional
stage in <span class="c013">imagen</span> <span class="c013">ppm</span> to <span class="c013">png</span> production chain.
<span class="c018">command</span> is an Unix filter that expects a <span class="c013">ppm</span> image
in its standard input and outputs a <span class="c013">ppm</span> image on its standard output.
A sensible choice for <span class="c018">command</span> is one command from the
<span class="c013">netpbm</span> package, several such commands piped together, or
various invocations of the <span class="c013">convert</span> command from <span class="c022">ImageMagick</span>.
</dd><dt class="dt-description"><span class="c022"><span class="c013">-quant</span> <span class="c018">number</span></span></dt><dd class="dd-description"> Add an extra color quantisation step
in <span class="c013">imagen</span> <span class="c013">ppm</span> image production chain, where
<span class="c018">number</span> 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"><span class="c014">-png</span></dt><dd class="dd-description"><a id="hevea_default254"></a> Output PNG images. This is the default.
</dd><dt class="dt-description"><span class="c014">-gif</span></dt><dd class="dd-description"><a id="hevea_default255"></a>
Output GIF images in place of PNG images.
GIF image files have a <span class="c013">.gif</span> extension.
Note that <span class="c013">hevea</span> should have been previously run as
<span class="c013">hevea gif.hva</span> <span class="c018">base</span><span class="c013">.tex</span> (so that the proper
<span class="c013">.gif</span> filename
extension is given to image file references from within the html
document).
</dd><dt class="dt-description"><span class="c014">-pnm</span></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"><span class="c022"><span class="c013">-t</span> <span class="c018">arg</span></span></dt><dd class="dd-description"> Pass option “<span class="c013">-t</span> <span class="c018">arg</span>” to
<span class="c013">dvips</span>.
For instance, using “<span class="c013">-t a3</span>” may help when images are
truncated on the right.
</dd><dt class="dt-description"><span class="c014">-pdf</span></dt><dd class="dd-description"><a id="hevea_default256"></a><a id="hevea_default257"></a>
Have <span class="c013">imagen</span> call <span class="c013">pdflatex</span> instead
of <span class="c013">latex</span>.
</dd></dl><p>The first three options enable users to correct some misbehaviours.
For instance, when the document base style is <span class="c018">seminar</span>, image
orientation may
be wrong and the images are too small. This can be cured by invoking
<span class="c013">imagen</span> as:
</p><div class="flushleft">
<span class="c013"># imagen -extra "pnmflip -ccw" -mag 2000</span> <span class="c018">base</span>
</div><p>Notice that <span class="c013">hevea</span> calls <span class="c013">imagen</span> by itself,
when given the command-line option <a id="hevea_default258"></a><span class="c013">-fix</span>.
In that situation, the command-line options of <span class="c013">imagen</span> can
be controlled 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" id="sec224">C.1.6  Invoking <span class="c013">hevea</span>, <span class="c013">hacha</span> and <span class="c013">imagen</span></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
<span class="c013">Makefile</span>’s for similar situations.</p><p>We translate a file <span class="c013">doc.tex</span>
that requires a specific style file <span class="c013">doc.hva</span>.
The file is first translated into <span class="c013">doc.html</span> by <span class="c013">hevea</span>,
which also reads
the specific style file <span class="c013">doc.hva</span>.
Then, <span class="c013">hacha</span> cuts <span class="c013">doc.html</span> into several,
<span class="c013">doc001.html</span>, <span class="c013">doc002.html</span>, etc. also producing the
table of links file <span class="c013">index.html</span>.
</p><pre class="verbatim"># hevea -fix doc.hva doc.tex
# hacha doc.html
</pre><p>Thanks to the command-line option <a id="hevea_default259"></a><span class="c013">-fix</span>, <span class="c013">hevea</span> runs the
appropriate number of times automatically.
In case <span class="c013">hevea</span> produces a non-empty <span class="c013">doc.image.tex</span>
file, then <span class="c013">hevea</span> calls <span class="c013">imagen</span> by itself
(because of option <span class="c013">-fix</span>).
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 <span class="c013">imagen</span> by hand.
It is time <em>not</em> to use the option <span class="c013">-fix</span>.
</p><pre class="verbatim"># rm -f doc.image.tex
# hevea doc.hva doc.tex
</pre><p>Now, <span class="c013">hevea</span> normally has shown the <span class="c013">imagen</span>
command line that it would have run, if it had been given
the option <span class="c013">-fix</span>.
For instance, if <span class="c013">doc.hva</span> includes <code>\input{gif.hva}</code>, then
<span class="c013">hevea</span> shows the following warning:
</p><pre class="verbatim">HeVeA Warning: images may have changed, run 'imagen -gif doc'
</pre><p>Now, one can run <span class="c013">imagen</span> as it should be.</p><p>It is sometime convenient not to clobber the source directory with
numerous target files.
It suffices to instruct
<span class="c013">hevea</span> and <span class="c013">hacha</span> to output files in a
specific directory, say <span class="c013">doc</span>.
</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 <span class="c013">hevea</span> does not create the target directory
<span class="c013">doc</span>: it must exist before <span class="c013">hevea</span> runs.
Again, in case <span class="c013">hevea</span> calls <span class="c013">imagen</span>,
image generation should proceed smoothly and the final files
<span class="c013">doc001.png</span>, <span class="c013">doc002.png</span>, … should go into
directory <span class="c013">doc</span>.</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
(<span class="c013">index.html</span>), contents files (<span class="c013">doc001.html</span>,
<span class="c013">doc002.html</span>, etc.) and images
(<span class="c013">doc001.png</span>, <span class="c013">doc002.png</span>, etc.),
one should not forget the arrow images and the
style sheet generated by <span class="c013">hacha</span>
(<span class="c013">contents_motif.gif</span>, <span class="c013">next_motif.gif</span>,
<span class="c013">previous_motif.gif</span> and <span class="c013">doc.css</span>).</p><p>As a consequence, producing all files into the subdirectory
<span class="c013">doc</span> may be a good idea, since then one easily install all
relevant files by copying <span class="c013">doc</span> 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 <span class="c013">hevea</span>,
and <span class="c013">hevea</span> output file <span class="c013">doc.html</span>, which is no longer
useful once <span class="c013">hacha</span> 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" id="makefile">C.1.7  Using <span class="c013">make</span></h3>
<p>Here is a typical <span class="c013">Makefile</span>, which is appropriate 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 <span class="c013">clean</span> rule removes all the <span class="c013">doc001.html</span>,
<span class="c013">doc002.html</span>, etc. and <span class="c013">doc.css</span> files produced by
<span class="c013">hacha</span>.
Also note that <span class="c013">make clean</span> also removes the
<span class="c013">doc.haux</span>, <span class="c013">doc.hind</span> and <span class="c013">doc.htoc</span> files, which are H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
auxiliary files.</p><p>When the <span class="c018">image</span> file feature is used, one can use the
following, extended, <span class="c013">Makefile</span>:
</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].png *_motif.gif
</pre><p>Observe that the <span class="c013">clean</span> rule now also gets rid of
<span class="c013">doc.image.tex</span> and of the various files produced by
<span class="c013">imagen</span>.</p><p>With the following <span class="c013">Makefile</span>,
<span class="c013">hevea</span>, <span class="c013">imagen</span>, <span class="c013">hacha</span> all output their files into
a specific directory <span class="c013">DIR</span>.
</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 <span class="c013">Makefile</span> directly produces html and PNG files
into the final directory <code>$(HOME)/public_html/$(DOC)</code>.
The new <span class="c013">partialclean</span> entry erases files that are not
useful anymore, once <span class="c013">imagen</span> and <span class="c013">hacha</span> have
performed their tasks.</p><p>However, most often, it is more appropriate to build html and PNG 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>
