<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<META name="GENERATOR" content="hevea 1.10">
<META name="Author" content="Luc Maranget">
<LINK rel="stylesheet" type="text/css" href="manual.css">
<TITLE>Moving Information Around</TITLE>
</HEAD>
<BODY >
<A HREF="manual032.html"><IMG SRC="previous_motif.gif" ALT="Previous"></A>
<A HREF="manual022.html"><IMG SRC="contents_motif.gif" ALT="Up"></A>
<A HREF="manual034.html"><IMG SRC="next_motif.gif" ALT="Next"></A>
<HR>
<H2 CLASS="section"><A NAME="htoc101">B.11</A>  Moving Information Around</H2><UL>
<LI><A HREF="manual033.html#toc79">Files</A>
</LI><LI><A HREF="manual033.html#toc80">Cross-References</A>
</LI><LI><A HREF="manual033.html#toc81">Bibliography and Citations</A>
</LI><LI><A HREF="manual033.html#toc82">Splitting the Input</A>
</LI><LI><A HREF="manual033.html#toc83">Index and Glossary</A>
</LI><LI><A HREF="manual033.html#toc84">Terminal Input and Output</A>
</LI></UL>
<H3 CLASS="subsection"><A NAME="toc79"></A><A NAME="htoc102">B.11.1</A>  Files</H3><P><A NAME="files"></A>
In some situations,
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A uses some of the ancillary files generated by L<sup>A</sup>T<sub>E</sub>X.
More precisely, while processing file <EM>doc</EM><TT>.tex</TT>,
the following files may be read:
</P><DL CLASS="description"><DT CLASS="dt-description">
<TT><B>.aux</B></TT></DT><DD CLASS="dd-description"> The file <EM>doc</EM><TT>.aux</TT> contains
cross-referencing information, such as figure or section numbers.
If this file is present, H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A reads it and put such numbers (or
labels) inside
the links generated by the <CODE>\ref</CODE> command. If the <TT>.aux</TT>
file is not present, or if the <TT>hevea</TT> command is given the
<TT>-fix</TT> option, H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A will instead use <TT>.haux</TT>
files.
</DD><DT CLASS="dt-description"><TT><B>.haux</B></TT></DT><DD CLASS="dd-description"> Such files are H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A equivalents of
<TT>.aux</TT> files. Indeed, they are <TT>.aux</TT> files tailored to
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A needs.
Two runs of H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A might be needed to get cross references right.
</DD><DT CLASS="dt-description"><TT><B>.htoc</B></TT></DT><DD CLASS="dd-description"> This file contains a formatted table of
contents. It is produced while reading the <TT>.haux</TT> file.
As consequence a table of contents is available only when the
<TT>.haux</TT> file is read.</DD><DT CLASS="dt-description"><TT><B>.hbbl</B></TT></DT><DD CLASS="dd-description"> The <EM>doc</EM><TT>.hbbl</TT> file
is generated by <TT>bibhva</TT> from <EM>doc</EM><TT>.haux</TT>.
When present, it is read by the <CODE>\bibliography</CODE> command.</DD><DT CLASS="dt-description"><TT><B>.bbl</B></TT></DT><DD CLASS="dd-description"> The <EM>doc</EM><TT>.bbl</TT> file is
generated by BibT<sub>E</sub>X from <EM>doc</EM><TT>.aux</TT>.
When present, and if no <EM>doc</EM><TT>.hbbl</TT> exists,
<EM>doc</EM><TT>.bbl</TT> is read by the <CODE>\bibliography</CODE> command.</DD><DT CLASS="dt-description"><B><TT>.hidx</TT> and <TT>.hind</TT></B></DT><DD CLASS="dd-description">
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A computes its own indexes, using <TT>.hidx</TT> files for
storing index references and, using <TT>.hind</TT> files
for storing formatted indexes.
Index formatting significantly departs from the one of L<sup>A</sup>T<sub>E</sub>X.
Again, several runs of H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A might be needed to get indexes right.
</DD></DL><P>H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A does not fail when it cannot find an auxiliary file.
When another run of H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A is needed, a warning is issued,
and it is user’s responsability to rerun H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A.
However, the convenient <A NAME="@default176"></A><TT>-fix</TT> command-line option instructs
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A to rerun itself, untill it believes it has reached stable state.</P><H3 CLASS="subsection"><A NAME="toc80"></A><A NAME="htoc103">B.11.2</A>  Cross-References</H3><P><A NAME="cross"></A>
The L<sup>A</sup>T<sub>E</sub>X <CODE>\label</CODE> and <CODE>\ref</CODE> are changed by H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A
into HTML anchors and local links.
Spaces in the arguments to these commands are better avoided.</P><P>Additionally, numerical references to sectional units, figures,
tables, etc. are shown, as they would appear in the <TT>.dvi</TT>
file.
Numerical references to pages (such as generated by <CODE>\pageref</CODE>)
are not shown; only an link is generated.</P><P>While processing a document <EM>doc</EM><TT>.tex</TT>,
cross-referencing information can be computed in two different, mutually
exclusive, ways, depending
on whether L<sup>A</sup>T<sub>E</sub>X has been previously run or not:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
If there exists a file
<EM>doc</EM><TT>.aux</TT>, then cross-referencing information is extracted
from that file. Of course, the <EM>doc</EM><TT>.aux</TT> file
has to be up-to-date, that is,
it should be generated by running L<sup>A</sup>T<sub>E</sub>X as many times as necessary.
(For H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A needs, one run is probably sufficient).
</LI><LI CLASS="li-itemize">If no <EM>doc</EM><TT>.aux</TT> file exists, then H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A
expect to find cross-referencing information in the file
<EM>doc</EM><TT>.haux</TT>.
</LI></UL><P>
When using its own <EM>doc</EM><TT>.haux</TT> file,
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A will output a
new <EM>doc</EM><TT>.haux</TT> file at the end of its processing.
This new <EM>doc</EM><TT>.haux</TT> file contains actualized
cross referencing information.
Hence, in that case, H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A may need to run twice to get
cross-references right.
Note that, just like L<sup>A</sup>T<sub>E</sub>X,
H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A 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 <EM>doc</EM><TT>.haux</TT> does not exist.</P><P>Observe that if a non-correct <EM>doc</EM><TT>.aux</TT> file is
present, then cross-references will apparently be wrong. However the
links are correct.</P><H3 CLASS="subsection"><A NAME="toc81"></A><A NAME="htoc104">B.11.3</A>  Bibliography and Citations</H3><P>
The <CODE>\cite</CODE> macro is supported. Its optional argument is
correctly handled. Citation labels are extracted from the
<TT>.aux</TT> file if present, from the <TT>.haux</TT> file otherwise.
Note that these labels are put there by L<sup>A</sup>T<sub>E</sub>X in the first case,
and by H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A in the second case, when they process the
<CODE>\bibitem</CODE> command.</P><H4 CLASS="subsubsection">Using BibT<sub>E</sub>X</H4><P>
All BibT<sub>E</sub>X related commands exist and echo the appropriate
information into the <TT>.haux</TT> file.</P><P>In particular, the <CODE>\bibliography</CODE> command exists and attempts to load the
formatted bibliography, <EM>i.e.</EM> to load the <TT>.hbbl</TT> file.
The <TT>.hbbl</TT> file is produced from the <TT>.haux</TT> file by
the companion program <TT>bibhva</TT> (see <A HREF="manual041.html#bibhva">C.1.4</A>).
To include the bibliographic references extracted from <TT>.bib</TT>
databases, it should normally suffice to do:
</P><PRE CLASS="verbatim"># hevea doc.tex
# bibhva doc
# hevea doc.tex
</PRE><P>In case no <TT>.hbbl</TT> file exists,
the <CODE>\bibliography</CODE> command attempts to load
the <TT>.bbl</TT> file normally used while combining L<sup>A</sup>T<sub>E</sub>X and
BibT<sub>E</sub>X. Thus, another way to extract bibliographic references from
<TT>.bib</TT> databases is:
</P><PRE CLASS="verbatim"># latex doc.tex
# bibtex doc
# hevea doc.tex
</PRE><P>In case both files exist,
notice that loading the <TT>.hbbl</TT> file has priority over
loading the <TT>.bbl</TT> file.</P><H3 CLASS="subsection"><A NAME="toc82"></A><A NAME="htoc105">B.11.4</A>  Splitting the Input</H3><P>
<A NAME="@default177"></A>
The <CODE>\input</CODE> and <CODE>\include</CODE> 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 <A HREF="manual041.html#comline">C.1.1.1</A> on how H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A searches files.
However, in the case of the <CODE>\include</CODE> command, the file is
searched only when previously given as an argument to
the <CODE>\includeonly</CODE> command.</P><P><A NAME="@default178"></A>
Note the following features:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
T<sub>E</sub>X syntax for <CODE>\input</CODE> is not supported. That is,
one should write <CODE>\input{</CODE><I>filename</I><CODE>}</CODE>.
</LI><LI CLASS="li-itemize">If <I>filename</I> is excluded with the <A NAME="@default179"></A><TT>-e</TT> command-line
option (see section <A HREF="manual041.html#heveaoptions">C.1.1.4</A>),
then H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A does not attempt to load <I>filename</I>.
Instead, it
echoes <CODE>\input{</CODE><I>filename</I><CODE>}</CODE> and
<CODE>\include{</CODE><I>filename</I><CODE>}</CODE> commands into the
<I>image</I> file. This sounds complicated, but this is what you want!
</LI><LI CLASS="li-itemize">H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A does not fail when it cannot find
a file, it just issues a warning.
</LI></UL><P>The <CODE>\listfiles</CODE> command is a null command.</P><H3 CLASS="subsection"><A NAME="toc83"></A><A NAME="htoc106">B.11.5</A>  Index and Glossary</H3><P><A NAME="index"></A>
<A NAME="@default180"></A><A NAME="@default181"></A>
Glossaries are not handled (who uses them ?).</P><P>While processing a document <EM>doc</EM><TT>.tex</TT>, index
entries go into the file <EM>doc</EM><TT>.hidx</TT>, while
the formatted index gets written into the file
<EM>doc</EM><TT>.hind</TT>.
As with L<sup>A</sup>T<sub>E</sub>X, two runs of H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A are normally needed to format
the index.
However, if all index producing commands (normally <CODE>\index</CODE>)
occur before the index formatting command (normally
<CODE>\printindex</CODE>), then only one run is needed.</P><P>As in L<sup>A</sup>T<sub>E</sub>X, index processing is not enabled by default and
some package has to be loaded explicitely in the
document preamble.
To that aim, H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A provides the standard package <TT>makeidx</TT>,
and two extended packages that allow the production of several indexes
(see section <A HREF="manual-packages.html#multind">B.17.7</A>).</P><P>Formatting of indexes in H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A departs from L<sup>A</sup>T<sub>E</sub>X behavior.
More precisely the <CODE>theindex</CODE> environment does not exist.
Instead, indexes are formatted using special
<TT>indexenv</TT> 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 <TT>indexcols</TT> counter (default value
is two).</P><H3 CLASS="subsection"><A NAME="toc84"></A><A NAME="htoc107">B.11.6</A>  Terminal Input and Output</H3><P>The <CODE>\typeout</CODE> command echos its argument on the
terminal, macro parameter <CODE>#</CODE><I>i</I> are replaced by their values.
The <CODE>\typein</CODE> command is not supported.</P><HR>
<A HREF="manual032.html"><IMG SRC="previous_motif.gif" ALT="Previous"></A>
<A HREF="manual022.html"><IMG SRC="contents_motif.gif" ALT="Up"></A>
<A HREF="manual034.html"><IMG SRC="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
