C.1 | Usage

- HEVEA usage
- HACHA usage
- `imagen` usage
- Using `make`

C.1.1 | H E V E A 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` 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:

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.

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:

`-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.
`-fix`
  Iterate HEVEA until a fixpoint is found. Additionnaly, images get generated automatically.
`-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.
`-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 (i.e. output ascii only). 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.
`-pedantic`
  Be strict in interpreting HTMLdefinition. In particular, this option disable size and color changes inside `<PRE>`... `</PRE>`, which are otherwise performed.
`-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.

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

`-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 | H A C H A 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).
`-tocbis`
  Add a small table of contents at every file start.
`-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 base nnn`.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 `-x` nnnn 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 -extra "pnmflip -ccw" -mag 2000` 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=-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 index.html $(DOC)[0-9][0-9][0-9].html $(DOC).haux

Note that the `clean` rule removes all the `doc001.html`, `doc002.html`, etc. files produced by `hacha`. Also note that `make clean` also removes the `doc.haux` file. Thanks to the `-fix` options, `hevea` will run the appropriate number of times.
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 index.html $(DOC)[0-9][0-9][0-9].html $(DOC).haux
            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`. Note the following, useful feature : when given the `-fix` option, `hevea` will itself run `imagen`, if needed.