<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="generator" content="hevea 2.06">
<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" id="sec146">B.11  Moving Information Around</h2>
<ul>
<li><a href="manual033.html#files">Files</a>
</li><li><a href="manual033.html#cross-reference">Cross-References</a>
</li><li><a href="manual033.html#sec149">Bibliography and Citations</a>
</li><li><a href="manual033.html#sec151">Splitting the Input</a>
</li><li><a href="manual033.html#sec152">Index and Glossary</a>
</li><li><a href="manual033.html#sec153">Terminal Input and Output</a>
</li></ul>
<h3 class="subsection" id="files">B.11.1  Files</h3>
<p>
In some situations,
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>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><span class="c013">.tex</span>,
the following files may be read:
</p><dl class="description"><dt class="dt-description">
<span class="c014">.aux</span></dt><dd class="dd-description"> The file <em>doc</em><span class="c013">.aux</span> contains
cross-referencing information, such as figure or section numbers.
If this file is present, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A reads it and put such numbers (or
labels) inside
the links generated by the <code>\ref</code> command. If the <span class="c013">.aux</span>
file is not present, or if the <span class="c013">hevea</span> command is given the
<span class="c013">-fix</span> option, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A will instead use <span class="c013">.haux</span>
files.
</dd><dt class="dt-description"><span class="c014">.haux</span></dt><dd class="dd-description"> Such files are H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A equivalents of
<span class="c013">.aux</span> files. Indeed, they are <span class="c013">.aux</span> files tailored to
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A needs.
Two runs of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A might be needed to get cross references right.
</dd><dt class="dt-description"><span class="c014">.htoc</span></dt><dd class="dd-description"> This file contains a formatted table of
contents. It is produced while reading the <span class="c013">.haux</span> file.
As consequence a table of contents is available only when the
<span class="c013">.haux</span> file is read.</dd><dt class="dt-description"><span class="c014">.hbbl</span></dt><dd class="dd-description"> The <em>doc</em><span class="c013">.hbbl</span> file
is generated by <span class="c013">bibhva</span> from <em>doc</em><span class="c013">.haux</span>.
When present, it is read by the <code>\bibliography</code> command.</dd><dt class="dt-description"><span class="c014">.bbl</span></dt><dd class="dd-description"> The <em>doc</em><span class="c013">.bbl</span> file is
generated by BibT<sub>E</sub>X from <em>doc</em><span class="c013">.aux</span>.
When present, and if no <em>doc</em><span class="c013">.hbbl</span> exists,
<em>doc</em><span class="c013">.bbl</span> is read by the <code>\bibliography</code> command.</dd><dt class="dt-description"><span class="c022"><span class="c013">.hidx</span> and <span class="c013">.hind</span></span></dt><dd class="dd-description">
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A computes its own indexes, using <span class="c013">.hidx</span> files for
storing index references and, using <span class="c013">.hind</span> 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<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A might be needed to get indexes right.
</dd></dl><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not fail when it cannot find an auxiliary file.
When another run of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A is needed, a warning is issued,
and it is user’s responsibility to rerun H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.
However, the convenient <a id="hevea_default177"></a><span class="c013">-fix</span> command-line option instructs
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A to rerun itself, until it believes it has reached stable state.</p>
<h3 class="subsection" id="cross-reference">B.11.2  Cross-References<a id="cross"></a></h3>
<p>
<a id="hevea_default178"></a><a id="hevea_default179"></a>
The L<sup>A</sup>T<sub>E</sub>X commands <code>\label</code> and <code>\ref</code> are changed by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
into html anchors and local links, using the “<code>a</code>” element.
Additionally, numerical references to sectional units, figures,
tables, etc. are shown, as they would appear in the <span class="c013">.dvi</span> file.
Numerical references to pages (such as generated by <code>\pageref</code>)
are not shown; only an link is generated.</p><p>The anchor used is the <span class="c018">label</span> argument to
<code>\label{</code><span class="c018">label</span><code>}</code>.
More precisely, <code>\label{</code><span class="c018">label</span><code>}</code> translates to
<code><a id="</code><span class="c018">label</span><code>"></a></code>;
while <code>\ref{</code><span class="c018">label</span><code>}</code>
translates to <code><a name="#</code><span class="c018">label</span><code>"></code><span class="c018">nnn</span><code></a></code>,
where <span class="c018">nnn</span> is the appropriate numerical reference to a section.
As a consequence spaces are better avoided in <span class="c018">label</span>.</p><p>Starting with H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A version 2.04,
the html anchors used by <code>\label</code> and <code>\ref</code> cannot
differ from the arguments to these commands anymore.
Moreover,
when <code>\label{</code><span class="c018">label</span><code>}</code> occurs
inside the argument of a sectioning command (<em>i.e.</em> in section title,
as recommended by section <a href="sectioning.html#section%3Asection">B.4.1</a>),
then H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A and H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A will use <span class="c018">label</span>
as the “<span class="c013">id</span>” attribute of the corresponding section.
For instance, the L<sup>A</sup>T<sub>E</sub>X source of this very section is:
</p><pre class="verbatim">\subsection{Cross-References\label{cross-reference}}
</pre><p>It translates to html similar to
</p><pre class="verbatim"><h3 class="subsection" id="cross-reference">B.11.2&#XA0;&#XA0;Cross-References</h3>
</pre><p>Notice that no <code><a id="cross-reference"></a></code> appears above.
Instead <code>id="cross-reference"</code> appears
in the enclosing <code>h3</code> header element.</p><p>While processing a document <em>doc</em><span class="c013">.tex</span>,
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><span class="c013">.aux</span> and that <span class="c013">hevea</span> has not been
given the command-line option <span class="c013">-fix</span>,
then cross-referencing information is extracted
from that file. Of course, the <em>doc</em><span class="c013">.aux</span> 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<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A needs, one run is probably sufficient).
</li><li class="li-itemize">If no <em>doc</em><span class="c013">.aux</span> file exists or if <span class="c013">hevea</span>
has been given the <span class="c013">-fix</span> command-line option, then H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
expect to find cross-referencing information in the file
<em>doc</em><span class="c013">.haux</span>.
</li></ul><p>
The second option is recommended.</p><p>When using its own <em>doc</em><span class="c013">.haux</span> file,
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A will output a
new <em>doc</em><span class="c013">.haux</span> file at the end of its processing.
This new <em>doc</em><span class="c013">.haux</span> file contains actualised
cross referencing information.
Hence, in that case, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>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<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>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><span class="c013">.haux</span> does not exist.</p><p>Observe that if a non-correct <em>doc</em><span class="c013">.aux</span> file is
present, then cross-references will apparently be wrong. However the
links are correct.</p>
<h3 class="subsection" id="sec149">B.11.3  Bibliography and Citations</h3>
<p>
The <code>\cite</code> macro is supported. Its optional argument is
correctly handled. Citation labels are extracted from the
<span class="c013">.aux</span> file if present, from the <span class="c013">.haux</span> 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<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A in the second case, when they process the
<code>\bibitem</code> command.</p><h4 class="subsubsection" id="sec150">Using BibT<sub>E</sub>X</h4>
<p>
All BibT<sub>E</sub>X related commands exist and echo the appropriate
information into the <span class="c013">.haux</span> 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 <span class="c013">.hbbl</span> file.
The <span class="c013">.hbbl</span> file is produced from the <span class="c013">.haux</span> file by
the companion program <span class="c013">bibhva</span> (see <a href="manual041.html#bibhva">C.1.4</a>).
To include the bibliographic references extracted from <span class="c013">.bib</span>
databases, it should normally suffice to do:
</p><pre class="verbatim"># hevea doc.tex
# bibhva doc
# hevea doc.tex
</pre><p>In case no <span class="c013">.hbbl</span> file exists,
the <code>\bibliography</code> command attempts to load
the <span class="c013">.bbl</span> 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
<span class="c013">.bib</span> 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 <span class="c013">.hbbl</span> file has priority over
loading the <span class="c013">.bbl</span> file.</p>
<h3 class="subsection" id="sec151">B.11.4  Splitting the Input</h3>
<p>
<a id="hevea_default180"></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<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>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 id="hevea_default181"></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><span class="c018">filename</span><code>}</code>.
</li><li class="li-itemize">If <span class="c018">filename</span> is excluded with the <a id="hevea_default182"></a><span class="c013">-e</span> command-line
option (see section <a href="manual041.html#heveaoptions">C.1.1.4</a>),
then H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not attempt to load <span class="c018">filename</span>.
Instead, it
echoes <code>\input{</code><span class="c018">filename</span><code>}</code> and
<code>\include{</code><span class="c018">filename</span><code>}</code> commands into the
<span class="c018">image</span> file. This sounds complicated, but this is what you want!
</li><li class="li-itemize">H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>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" id="sec152">B.11.5  Index and Glossary</h3>
<p><a id="index"></a>
<a id="hevea_default183"></a><a id="hevea_default184"></a>
Glossaries are not handled (who uses them ?).</p><p>While processing a document <em>doc</em><span class="c013">.tex</span>, index
entries go into the file <em>doc</em><span class="c013">.hidx</span>, while
the formatted index gets written into the file
<em>doc</em><span class="c013">.hind</span>.
As with L<sup>A</sup>T<sub>E</sub>X, two runs of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>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 explicitly in the
document preamble.
To that aim, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A provides the standard package <span class="c013">makeidx</span>,
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<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A departs from L<sup>A</sup>T<sub>E</sub>X behaviour.
More precisely the <code>theindex</code> environment does not exist.
Instead, indexes are formatted using special
<span class="c013">indexenv</span> 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 <span class="c013">indexcols</span> counter (default value
is two).</p>
<h3 class="subsection" id="sec153">B.11.6  Terminal Input and Output</h3>
<p>The <code>\typeout</code> command echos its argument on the
terminal, macro parameter <code>#</code><span class="c018">i</span> 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>
