## C.1 Usage

- HEVEA usage
- HACHA usage
- `esponja` usage
- `bibhva` usage
- `imagen` usage
- Invoking `hevea`, `hacha` and `imagen`
- Using `make`

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

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:

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

#### 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`
  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 US-ASCII with most symbols rendered as HTML or numerical Unicode entities.

`-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 Part B is the reference manual of HEVEA.

### 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`
  Another style for table of contents: sub-tables are replicated at the beginning of every file.
`-tocter`
  Like `-tocbis` above, except that sub-tables do not appear in the main table of contents (see Section 7.2.3).
`-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 `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:

`# 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 `-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.
`-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 Invoking `hevea`, `hacha` and `imagen`

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{png.hva}`, then `hevea` shows the following warning:

    HeVeA Warning: images may have changed, run 'imagen -png doc'

Now, one can run `imagen` as it should be.

It is sometime convenient not to clobber 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.gif`, `doc002.gif`, … 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.gif`, `doc002.gif`, 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

### C.1.7 Using `make`

Here is a typical `Makefile`, which is approriate 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].gif *_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 GIF 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 GIF 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)
      ...