The hevea command has two operating modes, normal mode and filter mode. Operating mode is determined by the nature of the last command-line argument.
The hevea command interprets its arguments as names of files and attempts to process them. Given an argument filename there are two cases:
In all attempts, implicit filenames are searched along hevea search path, which consist in:
The hevea library directory is fixed at compile-time
(this is where hevea library files are installed)
and typically is /usr/local/lib/hevea.
However, this compile-time value can be overridden
by setting the HEVEADIR shell environment variable.
In all cases, the value of hevea library directory can
be accessed from the processed document as the value of the command
\@hevealibdir.
If the last argument has an extension that is different from
.hva or has no extension,
then it is interpreted as the name of the main input file.
The main input file is the document to be translated and normally
contains the \documentclass command.
In that case two basenames are defined:
-o option (see below).
HEVEA will attempt to load the main input file.
Ancillary files from a previous run of LATEX
(i.e. .aux, .bll and .idx files)
will be searched as basein.ext.
The output base name governs all files produced by HEVEA.
That is, html output of HEVEA normally goes to the file
baseout.html,
while cross-referencing information goes into
baseout.haux. Furthemore,
if an image file is generated (cf. section 6), its
name will be baseout.image.tex.
Thus, in the simple case where the hevea command is invoked as:
# hevea file.tex
The input basename is file and the output basename also is file. The main input file is searched once along hevea search path as file.tex. html output goes into file file.html, in the current directory. In the more complicated case where the hevea command is invoked as:
# hevea ./dir/file
The input base name is ./dir/file and the output basename is file. The main input file is loaded by first attempting to open file ./dir/file.tex, then file ./dir/file. html output goes into file file.html, in the current directory.
Finally, the output base name can be a full path, but you have to use option -o. For instance, we consider:
# hevea -o out/out.html file.tex
Then, html output goes into out/out.html — notice that directory out must exist. Furthermore, hevea output base name is out/out. This means that hevea generates files out/out.haux, out/out.image.tex etc.
The article.hva, seminar.hva, book.hva and
report.hva
base style files from HEVEA library are special.
Only the first base style file is loaded and the
\documentclass command has no effect when a base style file is
already loaded. This feature allows to override the document base style.
Thus, a document file.tex can be translated using the
article base style as follows:
# hevea article.hva file.tex
If there is no command-line argument, or if the last command-line
argument has the extension .hva, 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 \begin{document}.
In other words hevea acts as a filter.
Please note that this operating mode is just for translating
isolated LATEX constructs.
The normal way to translate a full document file.tex being
“hevea file.tex” and not
“hevea < file.tex > file.html”.
The hevea command recognises the following options:
div and p are bordered,
while the structure of displayed material is also shown.
The following options control the html code produced by hevea. By default, hevea outputs a page encoded in US-ASCII with most symbols rendered as html or numerical Unicode entities.
<PRE>… </PRE>, which are otherwise performed.
The following options select and control alternative output formats (see section 11):
Part A of this document is a tutorial introduction to HEVEA, while Part B is the reference manual of HEVEA.
The hacha command interprets its argument base.html as the name of a html source file to cut into pieces.
It also recognises the following options:
\tfile” line per anchor.
This information may be needed by other tools.
Section 7 of the user manual explains how to alter HACHA default behaviour.
The program esponja is part of HEVEA and is designed to optimise hevea output. However, esponja can also be used alone to optimise text-level elements in html files. Since esponja fails to operate when it detects incorrect html, it can be used as a partial html validator.
The program esponja interprets its arguments as names of files and attempt to process them. It is important to notice that esponja will replace files by their optimised versions, unless instructed not to do so with option -n.
Invoking esponja as
# esponja foo.html
will alter foo.html. Of course, if esponja does not succeed in making foo.html any smaller or if esponja fails, the original foo.html is left unchanged. Note that this feature allows to optimise all html files in a given directory by:
# esponja *.html
The command esponja recognises the following options:
The program bibhva is a simple wrapper, which basically forces bibtex into accepting a .haux file as input and producing a .hbbl file as output. Usage is bibhva bibtex-options basename.
The command imagen is a simple shell script that translates a LATEX document into many .png images. The imagen script relies on much software to be installed on your computer, see Section C.4.1.
It is a companion program of HEVEA, which must have been previously run as:
In both cases, base is HEVEA output basename. When told to do so (see section 6) HEVEA echoes part of its input into the base.image.tex file.
The imagen script should then be run as:
The imagen script produces one basennn.png image file per page in the base.image.tex file.
This is done by first calling latex on base.image.tex, yielding one dvi file. Then, dvips 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 dvips. Postscript files are interpreted by ghostscript (gs) that outputs ppm images, which are then fed into a series of transformations that change them into .png files.
The imagen script recognises the following options:
The first three options enable users to correct some misbehaviours. For instance, when the document base style is seminar, image orientation may be wrong and the images are too small. This can be cured by invoking imagen as:
Notice that hevea calls imagen by itself,
when given the command-line option -fix.
In that situation, the command-line options of imagen can
be controlled from source file by using the
command \@addimagenopt (see Section 10.7).
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 Makefile’s for similar situations.
We translate a file doc.tex that requires a specific style file doc.hva. The file is first translated into doc.html by hevea, which also reads the specific style file doc.hva. Then, hacha cuts doc.html into several, doc001.html, doc002.html, etc. also producing the table of links file index.html.
# hevea -fix doc.hva doc.tex # hacha doc.html
Thanks to the command-line option -fix, hevea runs the appropriate number of times automatically. In case hevea produces a non-empty doc.image.tex file, then hevea calls imagen by itself (because of option -fix). Hence, the above sequence of two commands is also appropriate in that situation.
In case some problem occurs, it is sometime convenient to run imagen by hand. It is time not to use the option -fix.
# rm -f doc.image.tex # hevea doc.hva doc.tex
Now, hevea normally has shown the imagen
command line that it would have run, if it had been given
the option -fix.
For instance, if doc.hva includes \input{gif.hva}, then
hevea shows the following warning:
HeVeA Warning: images may have changed, run 'imagen -gif doc'
Now, one can run imagen as it should be.
It is sometime convenient not to clobber the source directory with numerous target files. It suffices to instruct hevea and hacha to output files in a specific directory, say doc.
# hevea -fix -o doc/doc.html doc.hva doc.tex # hacha -o doc/index.html doc/doc.html
Notice that hevea does not create the target directory doc: it must exist before hevea runs. Again, in case hevea calls imagen, image generation should proceed smoothly and the final files doc001.png, doc002.png, … should go into directory doc.
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 (index.html), contents files (doc001.html, doc002.html, etc.) and images (doc001.png, doc002.png, etc.), one should not forget the arrow images and the style sheet generated by hacha (contents_motif.gif, next_motif.gif, previous_motif.gif and doc.css).
As a consequence, producing all files into the subdirectory doc may be a good idea, since then one easily install all relevant files by copying doc to a public destination.
# cp -r doc $(HOME)/public_html
However, one then also installs the auxiliary files of hevea, and hevea output file doc.html, which is no longer useful once hacha has run. Hence, those should be erased beforehand.
# rm -f doc/doc.h{tml,aux,ind,toc} doc/doc.image.tex
# cp -r doc $(HOME)/public_html
Here is a typical Makefile, which is appropriate when no images are produced.
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
Note that the clean rule removes all the doc001.html, doc002.html, etc. and doc.css files produced by hacha. Also note that make clean also removes the doc.haux, doc.hind and doc.htoc files, which are HEVEA auxiliary files.
When the image file feature is used, one can use the following, extended, Makefile:
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
Observe that the clean rule now also gets rid of doc.image.tex and of the various files produced by imagen.
With the following Makefile, hevea, imagen, hacha all output their files into a specific directory DIR.
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)/*
The above Makefile directly produces html and PNG files
into the final directory $(HOME)/public_html/$(DOC).
The new partialclean entry erases files that are not
useful anymore, once imagen and hacha have
performed their tasks.
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.
...
#document base name
DOC=doc
DIR=$(DOC)
BASE=$(DIR)/$(DOC)
INSTALLDIR=$(HOME)/public_html/$(DOC)
...
install: partialclean
cp $(DIR)/* $(INSTALLDIR)
...