Up Next

C.1  Usage

C.1.1  HEVEA usage

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.

C.1.1.1  Command line arguments

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:

  1. the current directory “.”,
  2. user-specified directories (with the -I command-line option),
  3. hevea library directory.
  4. one of the sub-directories html, text or info from hevea library directory, depending upon hevea output format,

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.

C.1.1.2  Normal mode

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:

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.

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

C.1.1.3  Filter mode

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”.

C.1.1.4  Options

The hevea command recognizes the following options:

-version
Show hevea version and exit.
-v
Verbose flag, can be repeated to increase verbosity. However, this is mostly for debug.
-dv
-dv Add border around some of the block-level elements issued. Specifically, all DIV and P are bordered, while the structure of displayed material is also shown.
-s
Suppress warnings.
-I dirname
Add dirname to the search path.
-o name
Make name the output basename. However, if name is base.html, then the output basename is base. Besides, -o - makes HEVEA output to standard output.
-e filename
Prevent hevea from loading any file whose name is filename. Note that this option applies to all files, including hevea.hva and base style files.
-fix
Iterate HEVEA until a fixpoint is found. Additionally, images get generated automatically.
-O
Optimize HTML by calling esponja (see section C.1.3).
-exec prog
Execute file prog and read the output. The file prog must have execution permission and is searched by following the searching rules of hevea.
-francais
Deprecated by babel support. This option issues a warning message.
-help
Print version number and a short help message.

The following options control the HTML code produced by hevea. By default, hevea outputs a page encoded in iso-latin1, with most symbols rendered as HTML or numerical Unicode entities. To our knowledge, this behavior is satisfactory only if the input file is encoded in iso-latin1 or in plain ascii.

-entities
Render symbols by using entities. This is the default.
-textsymbols
Render symbols by English text.
-moreenties
Enable the output of some unfrequent entities. Use this option to target browsers with wide entities support.
-mathml
Produces MathML output for equations, very experimental.
-pedantic
Be strict in interpreting HTML definition. In particular, this option disable size and color changes inside <PRE></PRE>, which are otherwise performed.

The following options select and control alternative output formats (see section 11):

-text
Output plain text. Output file extension is .txt.
-info
Output info format. Output file extension is .info.
-w width
Set the line width for text or info output, defaults to 72.

Part A of this document is a tutorial introduction to HEVEA, while HEVEA reference manual is part B.

C.1.2  HACHA usage

The hacha command interprets its argument base.html as the name of a HTML source file to cut into pieces.

It also recognizes the following options:

-v
Be a little verbose.
-o filename
Make HACHA output go into file filename (defaults to index.html). Additionally, if filename is a composite filename, dir/base, then all files outputted by HACHA will reside in directory dir.
-tocbis
Add a small table of contents at the beginning of every file.
-nolinks
Do not insert Previous/Up/Next links in generated pages.
-hrf
Output a base.hrf file, showing in which output files are the anchors from the input file gone. The format of this summary is one “anchor\tfile” line per anchor. This information may be needed by other tools.
-help
Print version number and a short help message.

Section 7 of the user manual explains how to alter HACHA default behavior.

C.1.3  esponja usage

The program esponja is part of HEVEA and is designed to optimize hevea output. However, esponja can also be used alone to optimize 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.

C.1.3.1  Operating modes

With no argument, esponja acts as a filter, it reads the standard input and writes on the standard output. Otherwise, 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 optimized versions.

Hence, to optimize file foo.html into foo_opt.html, one should invoke esponja as follows.

# esponja < foo.html > foo_opt.html

By contrast, 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 optimize all HTML files in a given directory by:

# esponja *.html

C.1.3.2  Options

The command esponja recognizes the following options:

-v
Be verbose, can be repeated to increase verbosity.
-n
Do not alter input files. Instead, esponja output for file input goes to file input.esp. Option -n implies option -v.
-u
Output esponja intermediate version of HTML. In most occasions, this amounts to pessimize instead of to optimize. It may yield challenging input for other HTML optimizers.

C.1.4  bibhva usage

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.

C.1.5  imagen usage

The command imagen is a simple shell script that translates a LATEX document into many .gif 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:

# heveabase.tex
or
# hevea-o base.html

(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:

# imagen base

The imagen script produces one basennn.gif 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 .gif files.

The imagen script recognizes the following options:

-mag nnnn
Change the enlarging ratio that is applied while translating DVI into Postscript. More precisely, dvips is run with -xnnnn option. Default value for this ration is 1414, this means that, by default, imagen magnifies LATEX output by a factor of 1.414.
-extra command
Insert command as an additional stage in imagen ppm to gif production chain. command is an Unix filter that expects a ppm image in its standard input and outputs a ppm image on its standard output. A sensible choice for command is one command from the netpbm package or several such commands piped together.
-quant number
Add an extra color quantization step in imagen ppm image production chain, where number 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.
-gif
Output GIF images. This is the default.
-png
Output PNG images in place of GIF images. PNG is sometimes preferred for legal reasons. PNG image files have a .png extension. Note that hevea should have been previously run as hevea png.hva base.tex (so that the proper .png filename extension is given to image file references from within the HTML document). Beware that the pnmtopng program looks to be plagued by bugs in old versions of the netpbm package.
-pnm
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.
-t arg
Pass option “-t arg” to dvips. For instance, using “-t a3” may help when images are truncated on the right.
-pdf
Have imagen call pdflatex instead of latex.

The first three options enable users to correct some misbehaviors. 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:

# imagen -extra "pnmflip -ccw" -mag 2000 base

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 controled from source file by using the command \@addimagenopt (see Section 10.7).

C.1.6  Using make

Here is a typical Makefile for translating a doc.tex source file into HTML. The file is first translated into doc.html by hevea, which also reads the specific style file macros.hva. Then, hacha cuts doc.html into several, doc001.html, doc002.html, etc. also producing the table of links file index.html.

HEVEA=hevea
HEVEAOPTS=-fix
HACHA=hacha
#document base name
DOC=doc
index.html: $(DOC).html
        $(HACHA) -o index.html $(DOC).html

$(DOC).html: macros.hva $(DOC).tex
        $(HEVEA) $(HEVEAOPTS) macros.hva $(DOC).tex
clean:
        rm -f $(DOC).html $(DOC).htoc $(DOC).haux
        rm -f index.html $(DOC)[0-9][0-9][0-9].html $(DOC).css

First, thanks to the -fix options, hevea will run the appropriate number of times automatically. 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 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
IMAGEN=imagen
#document base name
DOC=doc
index.html: $(DOC).html
        $(HACHA) -o index.html $(DOC).html

$(DOC).html: macros.hva $(DOC).tex
        $(HEVEA) $(HEVEAOPTS) macros.hva $(DOC).tex

clean:
        rm -f $(DOC).html $(DOC).htoc $(DOC).haux
        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

Observe that the clean rule now also gets rid of doc.image.tex and of the various files produced by imagen. Note the following, useful feature: when given the -fix option, hevea will run imagen, if needed.


Up Next