B.17 Implemented Packages
HEVEA distribution includes “.hva” packages that are
implementations of LATEX packages.
Packages described in the “Blue Book” (makeidx,
ifthen, graphics —and graphicx!—,
color, alltt) are provided. Additionnaly, quite a
few extra packages are provided. 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.
At the moment, package options are ignored, except for the babel package, where it is essential.
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}
.
z - \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
.
B.17.6 Multiple Bibliographies with the multibib package
HEVEA provides a slighty incomplete implementation of the
multibib package. The one non-implemented feature is the
simultaneous definition of more than one bibliography.
That is one cannot invoke \newcites
as follows :
\newcites{suf1, suf2}{Title1, Title2}
Instead, one should perform to calls to the \newcites
command :
\newcites{suf1}{Title1}
\newcites{suf2}{Title2}
B.17.7 Support for babel
B.17.7.1 Basics
HEVEA offers support for the LATEX package babel. When it reads the command
\usepackage[lang-list]{babel}
it loads babel.hva, and sends it the saved lang-list. The
file babel.hva then looks at each language (say x) in it, and loads x.hva, which offers support for the language x. As in LATEX, the last language in the list is selected as default. As an example the command
\usepackage[english,french,german]{babel}
would load babel.hva, then the files english.hva,french.hva,german.hva containing the respective definitions, and finally activate the definitions in greman.hva and sets the current language to german.
B.17.7.2 Commands and Languages
The following babel commands for changing and querying the language work as in LATEX :
-
\selectlanguage
: to change the language
\iflanguage
: to branch after comparing with current language
The language specific details are described in the corresponding
.hva
file, just as in the .sty
file for LATEX. Users
need to supply this file for their language, or modify/check the files
if thay are already supplied with the distribution. The list of
languages is given below.
american |
austrian |
brazil |
catalan |
check |
croatian |
danish |
dutch |
english |
esperanto |
finnish |
french |
galician |
german |
italian |
magyar |
norsk |
nynorsk |
polish |
portuges |
romanian |
russian |
slovak |
slovene |
spanish |
swedish |
turkish |
|
B.17.7.3 Writing hva Files
The languages for which .hva files are available with the
distribution are english, french, german, austrian and czech. These
may need to be modified as not all accents and hyphenation techniques
are supported.
They can be written/modified as simple TEX files (see the section B.16.2.1 on writing TEX macros for details). As an example, one may also take a look at the file french.hva, which describes the details for french.
Note how all definitions are inside the definition for \french@babel
, which is the command that \selectlanguage{french}
would call. Similar commands need to be provided (i.e. \x@babel
in \x.hva
for language x
).
Some definitions may involve specifying unicode encodings. The map from characters to unicode can be found at http://www.unicode.org/charts/ . Most language specific unicode characters can be found in the first few files.
B.17.8 Support for Math Package amssymb
HEVEA provides support for the amssymb symbols using unicode character encodings. However, a few symbols did not have any encoding yet (e.g. \varsubsetneqq
, ⫋), and were approximated to their nearest kin (e.g. \subsetneqq
, ⫋ in this case).
There were yet others which had unicode encodings, but not supported by current versions of some browsers (e.g. \ltimes
, ⋉). A similar fate awaited them. However, as it is hoped that sooner rather than later, browsers will support these entities, a command-line option `-goodbrowser'
can be used to activate them. Users are urget to try out the test file amssymb-test.html, for details on which symbols are supported by their browsers, and whether or not they should use the -goodbrowser option.
B.17.9 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.10 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 HEVEA implementation is more advanced for the former package.
B.17.11 Typesetting Computer Languages: the listings Package
I strongly recommend using the
listings package.
Learning the user interface requires a little effort, but it is worth
it.
HEVEA features a quite compatible implementation, please refer to
the original package documentation.
Do not hesitate to report discrepancies.
Note that HEVEA does not produce very compact
HTML in case you use this package.
This can be cured, at some price in runtime cost, by
giving hevea the command line option “-O”
(see Section C.1.1.4).
B.17.12 The mathpartir package
The mathpartir package, authored by D. Rémy, essentially
provides two features:
-
An environment mathpar for typesetting a sequence of math formulas in mixed horizontal and vertical mode. The environment selects the best arrangement according to the line width, exactly as paragraph mode does for words.
- A command
\inferrule
(and its starred variant) for
typsetting inferences rules.
We give a short description, focussing on HEVEA-related details.
Users are encouraged to refer to the
original
documentation of the package.
In the following, comments on rule typesetting apply to HEVEA output
and not to LATEX output.
B.17.12.1 The mathpar environment
In its LATEX version, the mathpar environment is a
“paragraph mode for formulas”. It allows to typeset long list of
formulas putting as many as possible on the same line:
\begin{mathpar}
A-Formula \and
Longer-Formula \and
And \and The-Last-One
\end{mathpar} |
|
A−Formula
Longer−Formula
And
The−Last−One
|
|
In the example above, formulas are separated with \and
. The
LATEX implementation also changes the meaning of paragraph breaks
(either explicit as a \par
command or implicit as a blank line)
to act as \and
. It also redefines the command \\
as
an explicit line-break in the flow of formulas.
The HEVEA version is simplistic:
\and
separators always produce horizontal space, while
\\
always produce line-breaks.
However, when prefixed by \hva
the meaning of explicit
speparators is inversed: that is,
\hva\and
produces a line-break, while \hva\\
produces horizontal space.
Hence, we can typeset the previous example on two lines:
\begin{mathpar}
A-Formula \and
Longer-Formula \hva\and
And \and The-Last-One
\end{mathpar} |
|
A−Formula
Longer−Formula |
|
And The−Last−One
|
|
It is to be noticed that the LATEX version of the package defines
\hva
as a no-op, so as to allow explicit instructions given to
HEVEA not to impact on the automatic typesetting performed by LATEX.
B.17.12.2 The inferrule macro
The \inferrule
macro is designed to typeset inference rules. It
should only be used in math mode (or display math mode). It takes
three arguments, the first being optional, specifying the label,
premises, and conclusions respectively. The premises and the
conclusions are both lists of formulas, and are separated by
\\
.
A simple example of its use is
\inferrule
[label]
{one \\ two \\ three \\ or \\ more \\ premisses}
{and \\ any \\ number \\ of \\ conclusions \\ as \\ well}
which gives the following rendering:
label |
one two three or more premisses |
|
and any number of conclusions as well |
Again, HEVEA is simplistic. Where LATEX performs
actual typesetting, interpreting \\
as horizontal or
vertical breaks, HEVEA always interpret \\
as an
horizontal break. In fact HEVEA interpret all separators
(\\
, \and
) as horizontal breaks, when
they appear in the arguments of the \inferrule
command.
Nethertheless prefixing separators with \hva
yields vertical
breaks:
\inferrule
{aa \hva\\ bb}
{dd \\ ee \\ ff} |
|
|
The color of the horizontal rule that separates the premises and
conclusions can be changed by redefining the command
\mpr@hhline@color
. This color must be specified as a low-level
color (cf. Section B.14.2.2).
B.17.12.3 Options
By default, lines are centerred in inference rules. However, this can be changed either by using \mprset{flushleft}
or \mprset{center}
, as shown below.
$$\mprset{flushleft}
\inferrule
{a \\ bbb \hva\\ ccc \\ dddd}
{e \\ ff \hva\\ gg}
$$ |
|
|
B.17.12.4 Derivation trees
The mathpartir package provides a starred variant
\inferrule*
. In LATEX, the boxes
produced by \inferrule
and \inferrule*
differ as regards
their baseline, the second being well adapted to derivation trees.
All this is irrelevant to HEVEA,
but \inferrule*
remains of interest because of its interface:
the optional argument to the \inferrule*
command is a list of
key=value pairs in the style of
keyval.
This makes the variant command much more flexible.
|
key |
Effect for value v |
before |
Execute v before typesetting the rule.
Useful for instance to change the maximal width of the rule. |
left |
Put a label v on the left of the rule |
Left |
Idem. |
right |
As left , but on the right of the rule. |
Right |
As Left , but on the right of the rule. |
lab |
Put a label v above the inference rule, in the style
of \inferrule . |
Lab |
Idem. |
vdots |
Raise the rule by v and insert vertical dots, the length
argument is translated to a number of line-skips. |
|
Additionally, the value-less key center
centers premises and
conclusions (this is
the default), while flushleft
commands left aligment of
premises and conclusions (as \mprset{flushleft}
does).
Other keys defined by the LATEX package exist and are parsed, but
they perform no operation.
As an example, the code
\begin{mathpar}
\inferrule* [Left=Foo]
{\inferrule* [Right=Bar,width=8em,
leftskip=2em,rightskip=2em,vdots=1.5em]
{a \and a \and bb \hva\\ cc \and dd}
{ee}
\and ff \and gg}
{hh}
\hva\and
\inferrule* [lab=XX]{uu \and vv}{ww}
\end{mathpar}
produces the following output:
B.17.13 Experimental Implementations
The fancyverb and colortbl
packages are partly implemented.