Style files
Author: Luc Maranget

2 | Style files

- Standard base styles
- Other base styles
- Other style files

LATEX style files are files that are not intended to produce output, but define document layout parameters, commands, environments, etc.

2.1 | Standard base styles

The base style of a LATEX document is the argument to the `\documentclass` command (`\documentstyle` in old style). Normally, the base style of a document defines the structure and appearance of the whole document.
HEVEA really knows about two LATEX base styles, article and book. Additionally, the report base style is recognized and considered equivalent to book and the seminar base style for making slides is recognized and implemented by small additions on the article style.
Base style style is implemented by an HEVEA specific style file style`.hva`. More precisely, HEVEA interprets `\documentclass{`style`}` by attempting to load the file style`.hva` (see section C.1.1.1 on where HEVEA searches for files). Thus, at the moment, HEVEA distribution includes the files, `article.hva`, `book.hva`, etc.

2.2 | Other base styles

Documents whose base style is not recognized by HEVEA can be processed when the unknown base style is a derivation of a recognized base style.
Let us assume that `mydoc.tex` uses an exotic base style such as acmconf. Then, typing `hevea mydoc.tex` will yield an error, since HEVEA cannot find the `acmconf.hva` file:

    # hevea.opt mydoc.tex
    mydoc.tex:1: Warning: Cannot find file: acmconf.hva
    mydoc.tex:1: Error while reading LaTeX: No base style
    Adios

This situation is avoided by invoking HEVEA with the known base style file `article.hva` as an extra argument:

    # hevea article.hva mydoc.tex

The extra argument instructs HEVEA to load its `article.hva` style file before processing `mydoc.tex`. It will then ignore the document base style specified by `\documentclass` (or `\documentstyle`).
Observe that the fix above works because the acmconf and article base styles look the same to the document (i.e., they define the same macros). More generally, most base styles that are neither article nor book are in fact variations on either two of them. However, such styles usually provides extra macros. If users documents use these macros, then users should also instruct HEVEA about them (see section 4.1).
Finally, it is important to notice that renaming a base style file style`.cls` into style`.hva` will not work in general. As a matter of fact, base style files are TeX and not LATEX source and HEVEA will almost surely fail on TeX-ish input.

2.3 | Other style files

A LATEX document usually loads additional style files, by using the commands `\input` or `\usepackage` or `\input`.

2.3.1 | Files loaded with `\input`

Just like LATEX, HEVEA reacts to the construct `\input{`file`}` by loading the file file. (if I got it right, HEVEA even follows TeX crazy convention on ```.tex`'' extensions).
As it is often the case, assume that the document `mydoc.tex` has a `\input{mymacros.tex}` instruction in its preamble, where `mymacros.tex` gathers custom definitions. Hopefully, only a few macros give rise to trouble: macros that performs fine typesetting or TeXish macros. Such macros need to be rewritten, using basic LATEX constructs (section 4 gives examples of macro-rewriting). The new definitions are best collected in a style file, `mymacros.hva` for instance. Then, `mydoc.tex` is to be translated by issuing the command:

    # hevea mymacros.hva mydoc.tex

The file `mymacros.hva` is processed before `mydoc.tex` (and thus before `mymacros.tex`). As a consequence of HEVEA behavior with respect to definition and redefinition (see section B.8.1), the macro definitions in `mymacros.tex` override the ones in `mymacros.tex`, provided the document original definitions are performed by `\newcommand` (or `\newenvironment`).
Another situation is when HEVEA fails to process a whole style file. Usually, this means that HEVEA crashes on that style file. The basic idea is then to write a `mymacros.hva` style file that contains alternative definitions for all the commands defined in `mymacros.sty`. Then, HEVEA should be instructed to load `mymacros.hva` and not to load `mymacros.tex`. This is done by invoking `hevea` as follows:

    # hevea mymacros.hva -e mymacros.tex mydoc.tex

Of course, `mymacros.hva` must now contain replacements for all the useful macros of `mymacro.tex`.

2.3.2 | Files loaded with `\usepackage`

As far as I know, LATEX reacts to the construct `\usepackage{`name`}` by loading the file name`.sty`. HEVEA reacts in a similar, but different, manner, by loading the file name`.hva`.
HEVEA distributions already includes quite a few ```.hva`'' implementations of famous packages (see section B.17). When a given package (say `zorglub`) is not implemented, the situation may not be as bad as it may seem first. Hopefully, you are only using a few commands from package `zorglub`, and you feel confident enough to implement them yourself. Then, it suffices to put your definitions in file `zorglub.hva` and HEVEA will react to `\usepackage{zorglub}` by loading `zorglob.hva`.
See section B.5.2 for the full story on `\usepackage`.