1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
|
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="generator" content="hevea 2.36">
<meta name="Author" content="Luc Maranget">
<script type="text/javascript" async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-MML-AM_CHTML"></script><link rel="stylesheet" type="text/css" href="manual.css">
<title>Moving Information Around</title>
</head>
<body>
<a href="manual032.html"><img src="previous_motif.svg" alt="Previous"></a>
<a href="manual022.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="manual034.html"><img src="next_motif.svg" alt="Next"></a>
<hr>
<h2 class="section" id="sec150">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#sec153">Bibliography and Citations</a>
</li><li><a href="manual033.html#sec155">Splitting the Input</a>
</li><li><a href="manual033.html#sec156">Index and Glossary</a>
</li><li><a href="manual033.html#sec157">Terminal Input and Output</a>
</li></ul>
<h3 class="subsection" id="files">B.11.1 Files</h3>
<p>
In some situations,
H<span class="c020"><sup>E</sup></span>V<span class="c020"><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="c017">.tex</span>,
the following files may be read:
</p><dl class="description"><dt class="dt-description"><span class="c018">.aux</span></dt><dd class="dd-description"> The file <em>doc</em><span class="c017">.aux</span> contains
cross-referencing information, such as figure or section numbers.
If this file is present, H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A reads it and put such numbers (or
labels) inside
the links generated by the <code class="verb">\ref</code> command. If the <span class="c017">.aux</span>
file is not present, or if the <span class="c017">hevea</span> command is given the
<span class="c017">-fix</span> option, H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A will instead use <span class="c017">.haux</span>
files.
</dd><dt class="dt-description"><span class="c018">.haux</span></dt><dd class="dd-description"> Such files are H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A equivalents of
<span class="c017">.aux</span> files. Indeed, they are <span class="c017">.aux</span> files tailored to
H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A needs.
Two runs of H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A might be needed to get cross references right.
</dd><dt class="dt-description"><span class="c018">.htoc</span></dt><dd class="dd-description"> This file contains a formatted table of
contents. It is produced while reading the <span class="c017">.haux</span> file.
As consequence a table of contents is available only when the
<span class="c017">.haux</span> file is read.</dd><dt class="dt-description"><span class="c018">.hbbl</span></dt><dd class="dd-description"> The <em>doc</em><span class="c017">.hbbl</span> file
is generated by <span class="c017">bibhva</span> from <em>doc</em><span class="c017">.haux</span>.
When present, it is read by the <code class="verb">\bibliography</code> command.</dd><dt class="dt-description"><span class="c018">.bbl</span></dt><dd class="dd-description"> The <em>doc</em><span class="c017">.bbl</span> file is
generated by BibT<sub>E</sub>X from <em>doc</em><span class="c017">.aux</span>.
When present, and if no <em>doc</em><span class="c017">.hbbl</span> exists,
<em>doc</em><span class="c017">.bbl</span> is read by the <code class="verb">\bibliography</code> command.</dd><dt class="dt-description"><span class="c027"><span class="c017">.hidx</span> and <span class="c017">.hind</span></span></dt><dd class="dd-description">
H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A computes its own indexes, using <span class="c017">.hidx</span> files for
storing index references and, using <span class="c017">.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="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A might be needed to get indexes right.
</dd></dl><p>H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A does not fail when it cannot find an auxiliary file.
When another run of H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A is needed, a warning is issued,
and it is user’s responsibility to rerun H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A.
However, the convenient <a id="hevea_default183"></a><span class="c017">-fix</span> command-line option instructs
H<span class="c020"><sup>E</sup></span>V<span class="c020"><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_default184"></a><a id="hevea_default185"></a>
The L<sup>A</sup>T<sub>E</sub>X commands <code class="verb">\label</code> and <code class="verb">\ref</code> are changed by H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A
into html anchors and local links, using the “<code class="verb">a</code>” element.
Additionally, numerical references to sectional units, figures,
tables, etc. are shown, as they would appear in the <span class="c017">.dvi</span> file.
Numerical references to pages (such as generated by <code class="verb">\pageref</code>)
are not shown; only an link is generated.</p><p>The anchor used is the <span class="c023">label</span> argument to
<code class="verb">\label{</code><span class="c023">label</span><code class="verb">}</code>.
More precisely, <code class="verb">\label{</code><span class="c023">label</span><code class="verb">}</code> translates to
<code class="verb"><a id="</code><span class="c023">label</span><code class="verb">"></a></code>;
while <code class="verb">\ref{</code><span class="c023">label</span><code class="verb">}</code>
translates to <code class="verb"><a name="#</code><span class="c023">label</span><code class="verb">"></code><span class="c023">nnn</span><code class="verb"></a></code>,
where <span class="c023">nnn</span> is the appropriate numerical reference to a section.
As a consequence spaces are better avoided in <span class="c023">label</span>.</p><p>Starting with H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A version 2.04,
the html anchors used by <code class="verb">\label</code> and <code class="verb">\ref</code> cannot
differ from the arguments to these commands anymore.
Moreover,
when <code class="verb">\label{</code><span class="c023">label</span><code class="verb">}</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="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A and H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A will use <span class="c023">label</span>
as the “<span class="c017">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 class="verb"><a id="cross-reference"></a></code> appears above.
Instead <code class="verb">id="cross-reference"</code> appears
in the enclosing <code class="verb">h3</code> header element.</p><p>While processing a document <em>doc</em><span class="c017">.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="c017">.aux</span> and that <span class="c017">hevea</span> has not been
given the command-line option <span class="c017">-fix</span>,
then cross-referencing information is extracted
from that file. Of course, the <em>doc</em><span class="c017">.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="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A needs, one run is probably sufficient).
</li><li class="li-itemize">If no <em>doc</em><span class="c017">.aux</span> file exists or if <span class="c017">hevea</span>
has been given the <span class="c017">-fix</span> command-line option, then H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A
expect to find cross-referencing information in the file
<em>doc</em><span class="c017">.haux</span>.
</li></ul><p>
The second option is recommended.</p><p>When using its own <em>doc</em><span class="c017">.haux</span> file,
H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A will output a
new <em>doc</em><span class="c017">.haux</span> file at the end of its processing.
This new <em>doc</em><span class="c017">.haux</span> file contains actualised
cross referencing information.
Hence, in that case, H<span class="c020"><sup>E</sup></span>V<span class="c020"><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="c020"><sup>E</sup></span>V<span class="c020"><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="c017">.haux</span> does not exist.</p><p>Observe that if a non-correct <em>doc</em><span class="c017">.aux</span> file is
present, then cross-references will apparently be wrong. However the
links are correct.</p>
<h3 class="subsection" id="sec153">B.11.3 Bibliography and Citations</h3>
<p>
The <code class="verb">\cite</code> macro is supported. Its optional argument is
correctly handled. Citation labels are extracted from the
<span class="c017">.aux</span> file if present, from the <span class="c017">.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="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A in the second case, when they process the
<code class="verb">\bibitem</code> command.</p><h4 class="subsubsection" id="sec154">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="c017">.haux</span> file.</p><p>In particular, the <code class="verb">\bibliography</code> command exists and attempts to load the
formatted bibliography, <em>i.e.</em> to load the <span class="c017">.hbbl</span> file.
The <span class="c017">.hbbl</span> file is produced from the <span class="c017">.haux</span> file by
the companion program <span class="c017">bibhva</span> (see <a href="manual041.html#bibhva">C.1.4</a>).
To include the bibliographic references extracted from <span class="c017">.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="c017">.hbbl</span> file exists,
the <code class="verb">\bibliography</code> command attempts to load
the <span class="c017">.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="c017">.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="c017">.hbbl</span> file has priority over
loading the <span class="c017">.bbl</span> file.</p>
<h3 class="subsection" id="sec155">B.11.4 Splitting the Input</h3>
<p>
<a id="hevea_default186"></a>
The <code class="verb">\input</code> and <code class="verb">\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="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A searches files.
However, in the case of the <code class="verb">\include</code> command, the file is
searched only when previously given as an argument to
the <code class="verb">\includeonly</code> command.</p><p><a id="hevea_default187"></a>
Note the following features:
</p><ul class="itemize"><li class="li-itemize">T<sub>E</sub>X syntax for <code class="verb">\input</code> is not supported. That is,
one should write <code class="verb">\input{</code><span class="c023">filename</span><code class="verb">}</code>.
</li><li class="li-itemize">If <span class="c023">filename</span> is excluded with the <a id="hevea_default188"></a><span class="c017">-e</span> command-line
option (see section <a href="manual041.html#heveaoptions">C.1.1.4</a>),
then H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A does not attempt to load <span class="c023">filename</span>.
Instead, it
echoes <code class="verb">\input{</code><span class="c023">filename</span><code class="verb">}</code> and
<code class="verb">\include{</code><span class="c023">filename</span><code class="verb">}</code> commands into the
<span class="c023">image</span> file. This sounds complicated, but this is what you want!
</li><li class="li-itemize">H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A does not fail when it cannot find
a file, it just issues a warning.
</li></ul><p>The <code class="verb">\listfiles</code> command is a null command.</p>
<h3 class="subsection" id="sec156">B.11.5 Index and Glossary</h3>
<p><a id="index"></a>
<a id="hevea_default189"></a><a id="hevea_default190"></a>
Glossaries are not handled. (Who uses them anyhow?)</p><p>While processing a document <em>doc</em><span class="c017">.tex</span>, index
entries go into the file <em>doc</em><span class="c017">.hidx</span>, while
the formatted index gets written into the file
<em>doc</em><span class="c017">.hind</span>.
As with L<sup>A</sup>T<sub>E</sub>X, two runs of H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A are normally needed to format
the index.
However, if all index producing commands (normally <code class="verb">\index</code>)
occur before the index formatting command (usually
<code class="verb">\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="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A provides the standard packages <span class="c017">makeidx</span>
and <span class="c017">imakeidx</span>, as well as
two extended packages that allow the production of several indexes
(see section <a href="manual-packages.html#multind">B.17.8</a>).</p><p>Formatting of indexes in H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A departs from L<sup>A</sup>T<sub>E</sub>X behaviour:
environment <code class="verb">the@hevea@index</code> replaces
the <code class="verb">theindex</code> environment; <code class="verb">the@hevea@index</code> places all
index entries in class <code class="verb">theindex</code>. The environment can be
modified with the commonly accepted magic:</p><pre class="verbatim">\let\OldTheIndex\the@hevea@index
\let\OldEndTheIndex\endthe@hevea@index
\renewenvironment{the@hevea@index}%
{\OldTheIndex ...}%
{... \OldEndTheIndex}
</pre><p>An optional index prolog paragraph gets the
ID <code class="verb">indexprologue</code> such that it can be manipulated with CSS as,
for example:</p><pre class="verbatim">p#indexprologue {
font-size: smaller;
}
</pre><p>The index entries themselves are formatted using special
<span class="c017">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="c017">indexcols</span> counter (default value is two).
And the boolean <span class="c017">indexcolseprule</span> toggles typesetting rules
between index columns (default is false, which means no rules).</p>
<h3 class="subsection" id="sec157">B.11.6 Terminal Input and Output</h3>
<p>The <code class="verb">\typeout</code> command echos its argument on the
terminal, macro parameter <code class="verb">#</code><span class="c023">i</span> are replaced by their values.
The <code class="verb">\typein</code> command is not supported.</p>
<hr>
<a href="manual032.html"><img src="previous_motif.svg" alt="Previous"></a>
<a href="manual022.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="manual034.html"><img src="next_motif.svg" alt="Next"></a>
</body>
</html>
|
