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 the names of
files and attempts to process them.
Given an argument filename there are two cases:
- If filename is base.tex, then a single
attempt is made to open filename.
- If filename does not have the extension .tex,
then a first attempt is made to open filename.tex.
In case of failure, a second attempt to open filename is made.
In all cases, implicit filenames are
searched along hevea search path.
hevea search path consist in the current directory ``.'',
followed by directories specified by the user with the -I
command line option, and by hevea library directory
(normally /usr/local/lib/hevea). However,
hevea library directory compile-time value can be overridden
by setting the HEVEADIR shell environment variable.
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:
- The input basename, basein,
is defined as the main input file name,
with extension removed when present.
- The output basename, baseout, is basein
with leading directories omitted. However the output basename can be
changed, using the
-o
option (see the section on options below).
HEVEA will attempt to load the main input file.
Ancillary files (such as the .aux file)
will be searched as basein.
ext.
The output of HEVEA normally goes to the file
baseout.html.
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 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.
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
''
Note that, as hevea requires a base style to operate, the
article.hva file is implicitly loaded when there is no
command line argument.
C.1.1.4 Options
The hevea command recognizes the following options:
- -v
- Verbose flag, can be repeated to increase
verbosity. However, this is mostly for debug.
- -s
- Suppress warnings.
- -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.
- -idx
- Read the name.idx file, where
name is the input base name. This is useful when this
file is customized after it has been generated by LATEX (See,
sections B.11.1 and B.11.5).
- -francais
- Set French mode.
This has three consequences:
- Some words inserted by LATEX (such as ``Chapter'',
``Bibliography'', ...) are replaced by French word.
- Text replacement for symbols are in French (see the
-nosymb option below).
- hevea sets the boolean register french to
true.
\frenchtrue
.
- -nosymb
- Avoid symbol font.
In this mode, symbols are replaced by text-only equivalents. By
default, these equivalent are in English.
- -noiso
- Do not output (iso-latin1) characters whose code is above 127.
These characters are replaced by HTML entities. This option is
mostly useful for generating HTML that will be displayed properly
by Netscape Communicator on a Macintosh.
- -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.
- -help
- Print version number and a short help message.
HEVEA user manual is part A of this document,
whereas HEVEA reference manual is part B of
this document.
C.1.2 HACHA usage
The hacha command interprets its argument 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).
- -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 imagen usage
imagen is a simple shell script that translates
a LATEX document into many .gif images.
It is a companion program of HEVEA, which must have been previously run as:
# hevea... base.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 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.
These 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 -mag 2000 -extra "pnmflip -ccw" base
More information on producing images can be found in section 6.
C.1.4 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=
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 index.html $(DOC)[0-9][0-9][0-9].html
Note that the clean rule removes all the doc001.html,
doc002.html, etc. files produced by hacha.
When the image file feature is used, one can use the
following, extended, Makefile:
HEVEA=hevea
HEVEAOPTS=
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
$(MAKE) $(MFLAGS) $(DOC)001.gif
$(DOC)001.gif: $(DOC).image.tex
$(IMAGEN) $(DOC)
clean:
rm -f $(DOC).html index.html $(DOC)[0-9][0-9][0-9].html
rm -f $(DOC).image.*
rm -f $(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.
With respect to the image file, hevea has the
following behavior: when the content of doc.image.tex
does not change from one run to the next,
hevea does not replace the old file by a new one.
As a consequence, the Makefile above will
rebuild the images doc001.gif, doc002.gif, etc.
only when the content of the LATEX source that is used to generate
them has changed.