B.17 | Implemented Packages

- AMS compatibility
- The `array` and `tabularx` Packages
- The `calc` Package
- The `comment` Package
- Multiple Indexes with the `index` and `multind` package
- The `url` package
- Verbatim Text : the `moreverb` and `verbatim` Packages

HEVEA distribution includes ``.hva'' packages that are implementations of LATEX packages. I provide no full documentation for these packages, users should refer to the first pages of the package documentation, which can usually be found in the book [LATEX-bis], in your local LATEX installation or in a TeX CTAN-archive.
Those packages generally are loaded explicitly from user source code, by using the `\usepackage` command. A few packages are loaded by defaut (array, calc, ifthen), however reloading them explicitely by `\usepackage` is harmless. Package options are not supported.

B.17.1 | AMS compatibility

HEVEA `amsmath` package defines some of the constructs of the `amsmath` package. At the moment, supported constructs are the `cases` environment and matrix environments [LATEX-bis, Section 8.4], the environments for multi-line displayed equations (`gather`, `split`,...) [LATEX-bis, Section 8.5] and the `\numberwithin` command [LATEX-bis, Section 8.6.2].

B.17.2 | The `array` and `tabularx` Packages

The `array` package is described in [LATEX-bis, Section 5.3] and in the local documentation of modern LATEX installations. It is a compatible extension of LATEX arrays (see B.10.2). Basically, it provides new column specifications and a `\newcolumntype` construct for user-defined column specifications. Table 1 gives a summary of the new column specifications and of how HEVEA implements them.

> Table 1: Column specifications from the `array` package

> `m{`width`}` |  | Equivalent to the `p` column specification (the width argument is ignored, entries are typeset in paragraph mode with paragraph breaks being reduced to a single line break), except that the entries are centered vertically.
> `b{`width`}` |  | Equivalent to the `p` column specification, except that the entries are bottom-aligned vertically.
> `>{`decl`}` |  | Can be used before `l`, `c`, `r`, `p{`...`}`, `m{`...`}` or `b{`...`}`. It inserts decl in front of the entries in the corresponding column.
> `<{`decl`}` |  | Can be used after `l`, `c`, `r`, `p{`...`}`, `m{`...`}` or `b{`...`}`. It inserts decl after entries in the corresponding column.
> `!{`decl`}` |  | Equivalent to `@{`decl`}`

Note that centered, top-aligned or bottom-aligned in the vertical direction, do not have exactly the same meaning in LATEX and in HTML. However, the aspect is the same when all columns agree w.r.t. vertical alignment. Ordinary column types (`c`, `l` and `r`) do not specify vertical alignment, which therefore becomes browser dependent.
The `>{`decl`}` and `<{`decl`}` constructs permit the encoding of TeX `\cases` macro as follows:

    \def\cases#1{\left\{\begin{array}{l>{$}l<{$}}#1\end{array}\right.}

(This is an excerpt of the `latexcommon.hva` file.)
New column specifications are defined by the `\newcolumntype` construct:
`\newcolumntype{`col`}[`narg`]{`body`}`
Where col is one letter, the optional narg is a number (defaults to `0`), and `body` is built up with valid column specifications and macro-argument references (`#`int). Examples are:

    \newcolumntype{C}{>{\bf}c}
    \newcolumntype{E}[1]{*{#1}{c}}
    \begin{tabular}{CE{3}}\hline
    one & two & three & four \\
    five & six & seven & eight \\ \hline
    \end{tabular}

The column specification `C` means that entries will be typeset centered and using bold font, while the column specifications `E{`num`}` stands for num centered columns. We get:

one | two | three | four
five | six | seven | eight

HEVEA implements column specifications with commands defined in the `\newcommand` style. Thus, they have the same behavior as regards double definition, which is not performed and induces a warning message. Thus, a column specification that is first defined in a `macro.hva` specific file, overrides the document definition.
The `tabularx` package [LATEX-bis, Section 5.3.5] provides a new tabular environment `tabularx` and a new column type `X`. HEVEA makes the former equivalent to `tabular` and the latter equivalent to `p{`ignored`}`. By contrast with the subtle array formatting that the `tabularx` package performs, this may seem a crude implementation. However, rendering is usually correct, although different.
More generally and from the HTML point of view such sophisticated formatting is browser job in the first place. However, the HTML definition allows suggested widths or heights for table entries and table themselves. From HEVEA point of view, drawing the border line between what can be specified and what can be left to the browser is not obvious at all. At the moment HEVEA choice is not to specify too much (in particular, all length arguments, either to column specifications or to the arrays themselves, are ignored). As a consequence, the final, browser viewed, aspect of arrays will usually be different from their printed aspect.

B.17.3 | The `calc` Package

LATEX source and documentation.
This package enables using traditional, infix, notation for arithmetic operations inside the num argument to the `\setcounter{`name`}{`num`}` and `\addtocounter{`name`}{`num`}` constructs (see [LATEX-bis, Section A.4])
The `calc` package provides a similar extension of the syntax of the len argument to the `\setlength` and `\addtolength` constructs. HEVEA does not implement this extension, since it does not implement length registers in the first place.

B.17.4 | The `comment` Package

LATEX source.
The implementation for this package provides two commands, `\excludecomment` and `\includecomment`, for (re-)defining new environments that ignore their content or that do nothing. The comment environment is also defined as an environment of the first kind.

B.17.5 | Multiple Indexes with the `index` and `multind` package

HEVEA supports several simultaneous indexes, following the scheme of the `index` package, which is present in modern LATEX distributions. This scheme is backward compatible with the standard indexing scheme of LATEX.
Support is not complete, but the most useful commands are available. More precisely, HEVEA knows the following commands:

`\newindex{`tag`}{`ext`}{`ignored`}{`indexname`}`
  Declare an index. The first argument tag is a tag to select this index in other commands; ext is the extension of the index information file generated by LATEX (e.g., `idx`); ignored is ignored by HEVEA; and indexname is the title of the index. If given the `idx` option. HEVEA attempts to read file mydoc`.`ext. There also exists a `\renewindex` commands that takes the same arguments and that can be used to redefine previously declared indexes.
`\makeindex`
  Perform `\newindex{default}{idx}{ind}{Index}`.
`\index[`tag`]{`arg`}`
  Act as the LATEX `\index` command except that the information extracted from arg goes to the tag index. The tag argument defaults to `default`, thereby yielding standard LATEX behavior for the `\index` command without an optional argument. There also exists a stared-variant `\index*` that Additionally typesets arg.
`\printindex[`tag`]`
  Compute, format and output index whose tag is tag. The tag argument defaults to `default`. At the moment, there is an important difference between LATEX and HEVEA: for `\printindex` to work, if must occur after the last occurrence of the `\index` command. This is little problem in practise, since indexes usually reside at the end of books.

The `multind` package provides another scheme for multiple indexes. Note that the ```multind`'' style for indexes is not backward compatible with LATEX default indexing scheme. I would recommend using the ```index`'' package.

B.17.6 | The `url` package

LATEX source.
This package in fact provides a enhanced `\verb` command that can appear inside other command arguments. This command is named ```\url`'', but it can be used for any verbatim text, including DOS-like path names. Hence, one can insert urls in one's document without worrying about LATEX active characters :

    This is a complicated url: \url{http://foo.com/~user#label%coucou}.

which gets typeset as: ``This is a complicated url: `http://foo.com/~user#label%coucou`.''
Main use for the `\url` command is to specify urls as arguments to HEVEA commands for hyperlinks (see section 8.1.1) :

    \hevea{} home page is
    \ahrefurl{\url{http://pauillac.inria.fr/~maranget/hevea/}}

It yields : ``HEVEA home page is `http://pauillac.inria.fr/~maranget/hevea/`''.
However the `\url` command is fragile, as a consequence it cannot be used inside `\footahref` first argument (This is a LATEX problem, not an HEVEA one). The `url` package solves this problem by providing the `\urldef` command for defining commands whose body is typeset by using `\url`:

    \urldef{\heveahome}{\url}{http://pauillac.inria.fr/~maranget/hevea/}

Such a source defines the robust command `\heveahome` as the intended url. Hence the following source works as expected :

    Have a look at \footurl{\heveahome}{\hevea{} home page}

It yields: ``Have a look at HEVEA home page''.
Using `\url` inside command definitions with a `#`i argument is a bad idea, since it gives ``verbatim'' a rather random meaning. Unfortunately, in some situations (e.g, no `%`, no `#`), it may work in LATEX. By contrast, it does not work in HEVEA. In such situations, `\urldef` should be used.
HEVEA implementation is somehow compatible at the ``programming level''. Thus, users can define new commands whose argument is understood verbatim. The `urlhref.hva` style file from the distribution takes advantage of this to define the `\url` command, so that it both typesets an url and inserts a link to it.

    \input{urlhref.hva}
    Have a look at \url{http://pauillac.inria.fr/~maranget/hevea/}

It yields ``Have a look at `http://pauillac.inria.fr/~maranget/hevea/`''. The `urlhref.hva` style file (which is an HEVEA style file and not a LATEX style file) can be adequate for bibliographic references, which often use `\url` for its typesetting power. Of course, loading `urlhref.hva` only makes sense when all arguments to `\url` are urls...

B.17.7 | Verbatim Text : the `moreverb` and `verbatim` Packages

These two packages provide new commands and environments for processing verbatim text.
I recommend using `moreverb` rather than `verbatim`, since the LATEX implementation of the former is much more compatible with HEVEA than the implementation of the latter.