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
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
//! The LaTeX layer texrs can honour.
//!
//! LaTeX is a program written in TeX, so this carries it as TeX. There are two
//! files of it, and the difference between them is the whole shape of this
//! layer:
//!
//! * `prelude.tex` is the STAND-IN. A macro that would have drawn something
//! yields its text instead; a macro whose effect the stomach would have read
//! consumes its arguments and produces nothing. Nothing in it is LaTeX's own
//! definition, and it is not meant to be.
//! * `kernel.tex` is the PORT. Every definition in it is the one `latex.ltx`
//! makes, with the place it came from written above it, and every place a
//! definition could NOT be carried over says which primitive is missing.
//! Counters, cross references, `\newenvironment`, the option and file
//! machinery and the footnote and caption numbering are there.
//!
//! The kernel is read after the stand-in, so a name in both ends up with the
//! ported definition and the stand-in stays for the names the port has not
//! reached.
//!
//! Four things are decided in Rust because the engine has no primitive for
//! them, each in its own module:
//!
//! * [`load`] finds the real `.sty` and `.cls` with `kpsewhich` and reads them
//! through the engine, and REPORTS by name every package that would not go
//! through and the control sequence that stopped it.
//! * [`counters`] allocates a `\count` register per counter the document
//! declares, because `\newcount`'s allocator needs to freeze a number into a
//! name and this engine's `\edef` freezes nothing.
//! * [`allocate`] does the same for `\newcount` itself and its eleven
//! relatives, for the same reason: the allocator's whole job is to freeze
//! the next free register number into a name.
//! * [`aux`] is the `.aux` round trip `\ref` rests on, because there is no
//! `\write`, no `\openin` and no `\read`.
/// The prelude and the kernel, compiled into the binary so a run needs no
/// support files.
///
/// One constant rather than two because every caller wants both and in this
/// order: the ported definitions have to win over the stand-ins they replace.
pub const PRELUDE: &str = concat!;
/// Which of the two things a run is producing.
///
/// It matters to exactly one definition, `\@ctrtotext` -- `kernel.tex` says why
/// at length -- and the two entry points below differ only in that.
/// Everything a LaTeX document needs read before itself.
///
/// The prelude and the kernel, then the register allocations for the counters
/// this document declares, then the packages that really load. The order is the
/// one the pieces depend on: `\@namedef` is the kernel's, and a counter's
/// register has to exist before `\newcounter` names it.
/// The same, for a run that is setting the document's own words.
/// The environment a document is read in, minus the document and its packages.
///
/// Split out because `load::attempt` has to build the same thing before it can
/// say whether a `.sty` really loads: a probe running with LESS than the real
/// preamble would report a package as refused over a macro the real run would
/// have given it, and the report is the whole point of the probe. `about` is
/// the text about to be read, scanned for the declarations Rust has to make on
/// its behalf -- the counter registers and the `\newif` switches.
/// The preamble with the labels a previous run left in `document.aux` seeded in.
///
/// Separate because it needs to know which FILE the document is, and the entry
/// points in `lib.rs` that take a string and nothing else cannot say.
/// The `\the<counter>` definitions that belong to a class with no chapters.
///
/// `kernel.tex` writes report's: `\thesection` is `\thechapter.\arabic{section}`
/// and a figure is numbered `2.4`. article numbers a section `2` and a figure
/// `4`, and the difference is visible the moment a document says `\ref` -- an
/// article's first section came back as `0.1`.
///
/// Which one a document gets is decided by the CLASS FILE rather than by a list
/// of class names -- [`class_declares_chapters`] is the question, and it says
/// how it is asked. A class `kpsewhich` cannot find is read as report's, which
/// is what this layer carried before there was a choice to make.
/// Whether the class `src` names declares a `chapter` counter.
///
/// `report.cls` and `book.cls` say `\newcounter {chapter}` and `article.cls`
/// does not, and neither do the classes built on article that a name-matching
/// rule would have to be told about one at a time -- so the CLASS FILE is what
/// is read, through the same scan `counters.rs` uses. `None` is a class
/// `kpsewhich` cannot find, or a source with no `\documentclass` at all.
///
/// Public because it answers a question outside this module as well.
/// `typeset::unit_numbers` counts chapter, section and subsection and joins
/// EVERY level down to the one being asked for, so an article's first section
/// comes back as `0.1` where LaTeX writes `1` -- BUGS.md records it. The join
/// has to start at the shallowest level the CLASS declares, and this is the
/// fact that says which that is.
/// Say, once each, what would not load.
///
/// On stderr and by name, because the failure this replaces is the silent one:
/// a package that did not load, a document that ran anyway, and output that was
/// wrong with nothing to say why. Once per process, since a corpus sweep asks
/// the same question of the same package in every document.
/// Whether a source looks like a LaTeX document.
///
/// Keyed on the preamble directives rather than on a flag, because a user does
/// not think of their file as needing a mode -- `\documentclass` IS the
/// statement that this is LaTeX. A plain TeX document contains none of these
/// and is unaffected, which matters: the prelude redefines names like
/// `\section` that a plain document may have defined for itself.