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:
-
If filename is base.tex or
base.hva,
then a single attempt to open filename is made.
- In other cases,
a first attempt to open filename.tex is made.
In case of failure, a second attempt to open filename is made.
In all attempts, implicit filenames are
searched along hevea search path, which consist in:
-
the current directory “.”,
- user-specified directories (with the -I command line
option),
- hevea library directory.
- 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.
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 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.
- -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.
- -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.
- -symbols
- Render symbols by using the symbol font. This
mode is deprecated and is no more maintained.
- -textsymbols
- Render symbols by English text.
- -moreenties
- Enable the output of some unfrequent entities. Use
this option to target browsers with wide entities support.
- -noiso
- Use us-ascii for encoding the output page.
- -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
\t
file” 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 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:
# 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 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 in response of 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.
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
Sometimes imagen crashes because the PPM transformation chain
does not cope with images with more than 256 colors by default. The
solution is to re-issue the imagen command as:
# imagen -quant 256 base
More information on producing images can be found in section 6.
C.1.5 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 itself run
imagen, if needed.