Previous Up Next

B.11  Moving Information Around

B.11.1  Files

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:

.aux
The file doc.aux contains cross-referencing information, such as figure or section numbers. If this file is present, HEVEA reads it and put such numbers (or labels) inside the links generated by the \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.
.haux
Such files are HEVEA equivalents of .aux files. Indeed, they are .aux files tailored to HEVEA needs. Two runs of HEVEA might be needed to get cross references right.
.htoc
This file contains a formatted table of contents. It is produced while reading the .haux file. As consequence a table of contents is available only when the .haux file is read.
.hbbl
The doc.hbbl file is generated by bibhva from doc.haux. When present, it is read by the \bibliography command.
.bbl
The doc.bbl file is generated by BibTEX from doc.aux. When present, and if no doc.hbbl exists, doc.bbl is read by the \bibliography command.
.hidx and .hind
HEVEA computes its own indexes, using .hidx files for storing index references and, using .hind files for storing formatted indexes. Index formatting significantly departs from the one of LATEX. Again, several runs of HEVEA might be needed to get indexes right.

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 responsability to rerun HEVEA. However, the convenient -fix command-line option instructs HEVEA to rerun itself, untill it believes it has reached stable state.

B.11.2  Cross-References

The LATEX \label and \ref are changed by HEVEA into HTML anchors and local links. Spaces in the arguments to these commands are better avoided.

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.

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:

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

B.11.3  Bibliography and Citations

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.

Using BibTEX

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.

B.11.4  Splitting the Input

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.

Note the following features:

The \listfiles command is a null command.

B.11.5  Index and Glossary

Glossaries are not handled (who uses them ?).

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 (normally \printindex), then only one run is needed.

As in LATEX, index processing is not enabled by default and some package has to be loaded explicitely in the document preamble. To that aim, HEVEA provides the standard package makeidx, and two extended packages that allow the production of several indexes (see section B.17.7).

Formatting of indexes in HEVEA departs from LATEX behavior. More precisely the theindex environment does not exist. Instead, indexes 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 controled by setting the value of the indexcols counter (default value is two).

B.11.6  Terminal Input and Output

The \typeout command echos its argument on the terminal, macro parameter #i are replaced by their values. The \typein command is not supported.


Previous Up Next