In some situations, HEVEA uses some of the ancillary files generated by LATEX. More precisely, while processing file doc.tex, the following files may be read:
\ref command. If the .aux
file is not present, or if the hevea command is given the
-fix option, HEVEA will instead use .haux
files.
\bibliography command.\bibliography command.HEVEA does not fail when it cannot find an auxiliary file. When another run of HEVEA is needed, a warning is issued, and it is user’s responsibility to rerun HEVEA. However, the convenient -fix command-line option instructs HEVEA to rerun itself, until it believes it has reached stable state.
The LATEX commands \label and \ref are changed by HEVEA
into html anchors and local links, using the “a” element.
Additionally, numerical references to sectional units, figures,
tables, etc. are shown, as they would appear in the .dvi file.
Numerical references to pages (such as generated by \pageref)
are not shown; only an link is generated.
The anchor used is the label argument to
\label{label}.
More precisely, \label{label} translates to
<a id="label"></a>;
while \ref{label}
translates to <a name="#label">nnn</a>,
where nnn is the appropriate numerical reference to a section.
As a consequence spaces are better avoided in label.
Starting with HEVEA version 2.04,
the html anchors used by \label and \ref cannot
differ from the arguments to these commands anymore.
Moreover,
when \label{label} occurs
inside the argument of a sectioning command (i.e. in section title,
as recommended by section B.4.1),
then HEVEA and HACHA will use label
as the “id” attribute of the corresponding section.
For instance, the LATEX source of this very section is:
\subsection{Cross-References\label{cross-reference}}
It translates to html similar to
<h3 class="subsection" id="cross-reference">B.11.2  Cross-References</h3>
Notice that no <a id="cross-reference"></a> appears above.
Instead id="cross-reference" appears
in the enclosing h3 header element.
While processing a document doc.tex, cross-referencing information can be computed in two different, mutually exclusive, ways, depending on whether LATEX has been previously run or not:
The second option is recommended.
When using its own doc.haux file, HEVEA will output a new doc.haux file at the end of its processing. This new doc.haux file contains actualised cross referencing information. Hence, in that case, HEVEA may need to run twice to get cross-references right. Note that, just like LATEX, HEVEA issues a warning then the cross-referencing information it generates differs from what it has read at start-up, and that it does not fail if doc.haux does not exist.
Observe that if a non-correct doc.aux file is present, then cross-references will apparently be wrong. However the links are correct.
The \cite macro is supported. Its optional argument is
correctly handled. Citation labels are extracted from the
.aux file if present, from the .haux file otherwise.
Note that these labels are put there by LATEX in the first case,
and by HEVEA in the second case, when they process the
\bibitem command.
All BibTEX related commands exist and echo the appropriate information into the .haux file.
In particular, the \bibliography command exists and attempts to load the
formatted bibliography, i.e. to load the .hbbl file.
The .hbbl file is produced from the .haux file by
the companion program bibhva (see C.1.4).
To include the bibliographic references extracted from .bib
databases, it should normally suffice to do:
# hevea doc.tex # bibhva doc # hevea doc.tex
In case no .hbbl file exists,
the \bibliography command attempts to load
the .bbl file normally used while combining LATEX and
BibTEX. Thus, another way to extract bibliographic references from
.bib databases is:
# latex doc.tex # bibtex doc # hevea doc.tex
In case both files exist, notice that loading the .hbbl file has priority over loading the .bbl file.
The \input and \include commands exist and they perform
exactly the same operation of searching (and then processing) a file,
whose name is given as an argument.
See section C.1.1.1 on how HEVEA searches files.
However, in the case of the \include command, the file is
searched only when previously given as an argument to
the \includeonly command.
\input is not supported. That is,
one should write \input{filename}.
\input{filename} and
\include{filename} commands into the
image file. This sounds complicated, but this is what you want!
The \listfiles command is a null command.
Glossaries are not handled. (Who uses them anyhow?)
While processing a document doc.tex, index
entries go into the file doc.hidx, while
the formatted index gets written into the file
doc.hind.
As with LATEX, two runs of HEVEA are normally needed to format
the index.
However, if all index producing commands (normally \index)
occur before the index formatting command (usually
\printindex), then only one run is needed.
As in LATEX, index processing is not enabled by default and some package has to be loaded explicitly in the document preamble. To that aim, HEVEA provides the standard packages makeidx and imakeidx, as well as two extended packages that allow the production of several indexes (see section B.17.8).
Formatting of indexes in HEVEA departs from LATEX behaviour:
environment the@hevea@index replaces
the theindex environment; the@hevea@index places all
index entries in class theindex. The environment can be
modified with the commonly accepted magic:
\let\OldTheIndex\the@hevea@index
\let\OldEndTheIndex\endthe@hevea@index
\renewenvironment{the@hevea@index}%
{\OldTheIndex ...}%
{... \OldEndTheIndex}
An optional index prolog paragraph gets the
ID indexprologue such that it can be manipulated with CSS as,
for example:
p#indexprologue {
font-size: smaller;
}
The index entries themselves are formatted using special indexenv environments. Those details do not normally concern users. However, the number of columns in the presentation of the index can be controlled by setting the value of the indexcols counter (default value is two). And the boolean indexcolseprule toggles typesetting rules between index columns (default is false, which means no rules).
The \typeout command echos its argument on the
terminal, macro parameter #i are replaced by their values.
The \typein command is not supported.