Moving Information Around
Author: Luc Maranget

B.11 | Moving Information Around

- Files
- Cross-References
- Bibliography and Citations
- Splitting the Input
- Index and Glossary
- Terminal Input and Output

B.11.1 | Files

In some situations, HEVEA uses some of the ancillary files generated by LATEX. More precisely, while processing file mydoc`.tex`, the following files may be read:

`.aux`
  The file mydoc`.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 (see below).
`.haux`
  Such files are HEVEA equivalents of `.aux` files. Indeed, they are simplified `.aux` files. As a consequence, two runs of HEVEA might be needed to get cross references right.
`.htoc`
  This file contains a formatted table of contents. It is produces while reading the `.haux` file. As consequence a table of contents is available only when the `.haux` file is read.
`.bbl`
  The file mydoc`.bbl` is generated by BibTeX. It 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, using the convenient `-fix` command line option is provided makes HEVEA rerun itself.

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 mydoc`.tex`, cross-referencing information can be computed in two different, mutually exclusive, ways, depending on whether LATEX has been previously run or not:

- If there exists a file mydoc`.aux`, then cross-referencing information is extracted from that file. Of course, the mydoc`.aux` file has to be up-to-date, that is, it should be generated by running LATEX as many times as necessary. (For HEVEA needs, one run is probably sufficient).
- If no mydoc`.aux` file exists, then HEVEA expect to find cross-referencing information in the file mydoc`.haux`.

When using its own mydoc`.haux` file, HEVEA will output a new mydoc`.haux` file at the end of its processing. This new mydoc`.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 mydoc`.haux` does not exist.
Observe that if a non-correct mydoc`.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.
The `\bibliography` command is recognized, it loads the `.bbl` file which should thus have been generated before, using the appropriate combination of LATEX and BibTeX runs.
The `thebibliography` environment is recognized.
The `\nocite` and `\bibliographystyle` macros exist and do nothing.

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:

- TeX syntax for `\input` is not supported. That is, one should write `\input{`filename`}`.
- If filename is excluded with the `-e` command line option (see section C.1.1.4), then HEVEA does not attempt to load filename. Instead, it echoes `\input{`filename`}` and `\include{`filename`}` commands into the image file. This sounds complicated, but this is what you want!
- HEVEA does not fails when it cannot find a file, it just issues a warning.

The `\listfiles` command is a null command.

B.11.5 | Index and Glossary

Glossaries are not handled (who uses them ?) and the `theindex` environment does not exist. Instead, indexes are formatted using special `indexenv` environments. By default indexes are formated in two columns, one may change the number of columns by setting the value of the `indexcols` counter.
While processing a document mydoc`.tex`, index entries go into the file mydoc`.hidx`, while the formatted index gets written into the file mydoc`.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.
Note that two packages for multiple indexes are implemented (see section B.17.5).

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.