<!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>