30

To create a Table of Contents (for example), LaTeX2e follows the process:

  • Run 1

    • .aux file is created from scratch after \begin{document}.
    • When processing section headers, write \addtocontents to the .aux file with the pertinent sectioning information.
    • At \end{document}, \input the .aux file, which executes \@writefile via \contentsline to generate the .toc file.

  • Run 2

    • At \begin{document}, deactivate \@writefile and re-input the .aux file. This generates labelling information, etc., for the current compilation and has no effect on the .toc file already generated.

    • After \begin{document}, the .aux file is opened for writing, which clears its contents. The process starts anew.

The 2e sources don't go into detail about why the system was designed this way. Since there are limited write registers, writing all .toc information in one pass at \end{document} minimises the number of files that need to be kept open during the document. So that aspect is sensible.

But why is the .aux file input both at the beginning and the end of the document? Couldn't the .toc file be generated at \begin{document} instead?

(One difference is that if ‘Run 1’ is terminated prematurely, no .toc file will be generated at all so there'll be no ToC. Whereas if the .toc file were created at \begin{document} it would contain a partial ToC — but that's arguably no better or worse. And you could add, say, a \@finishedauxtrue flag inserted at \end{document} to catch this happening if necessary.)

[[EDIT: Well, loading the aux file at the end allows for some checking whether labels have changed, and so on. So the aux file does always need to be loaded twice; I guess my question is whether there's any difference for ToC generation when that happens.]]

Will Robertson
  • 73,872
  • My uneducated guess is that it is a historical artifact left over from the days of small memory machines, where the whole document may not fit in the computer memory at once. In such a case, it makes sense to make a pass through the document, doing what can be done on each pass. Today, things like MikTeX automate the process of running as many passes as necessary to get the job done. Back in the day, running successive passes would seem to be a very efficient approach. Bottom line: the aux file cannot be completed at \begin{documement} without a full document pass. – Steven B. Segletes Jun 26 '14 at 00:38
  • But wouldn't you still have to input the aux file twice? Once with @writefile active and once with it inactive? – cfr Jun 26 '14 at 00:49
  • @StevenB.Segletes — I'm not trying to argue against the current multi-pass mechanism; I don't think you can ever get away from it entirely. You can feasibly get document structure and other `nonlinear' material by preprocessing the document syntax, but resolving cross-references inherently requires multiple typesetting passes. Whether that's done externally (as now) or internally doesn't make too much difference IMO. – Will Robertson Jun 26 '14 at 01:29
  • 1
    I agree. My point only was that, at a time when memory was more precious, doing it "internally" may not have been an option. Thus, the current approach may be vestigial. – Steven B. Segletes Jun 26 '14 at 01:41

1 Answers1

22

There are certainly several ways to implement a data transport mechanism between runs. The LaTeX one attempts to be rather economically with resources.

There are a number of tasks that it caters for:

  • TOC-type files are only generated if the document asks for a TOC. This only becomes clear somewhere within the document (i.e., not automatically available at \begin{document}) so this favors writing the TOC file at the end (not at the beginning). Otherwise you either have to always write them or carry that information from one run to the next (which is not possible via the aux file as it has to be known at the start of reading the aux file).
  • For the same reason directly writing the TOC file (rather than using the aux file as an intermediate) is not possible (unless you always generate them and the toc comes either at the very beginning or the very end of the document). Also reusing parts of the toc data, e.g., for chapter tocs, would then be impossible.
  • Rereading the aux file at the end is not only there for generating the TOCs but also to post process the data, e.g., cross-reference checking, so it is needed in any case.
  • Reading the aux file at the beginning is necessary to obtain the data from the previous run (e.g., cross references).

So yes, one could produce the TOC-type files at the beginning, but then would either need an additional mechanism to pass the info which files to generate or one would need to produce them always, even if there is no TOC or LOT or ... being asked for. In short there is no gain (only loss).

Unless you want to read in the whole document in memory there is no way to avoid a multi-pass system (well it would be multi-pass even then) and keeping the whole document in memory is not economical with TeX and in fact not really with any system. So it was/is not a historical artifact because of small memory, it is a general necessity.

Frank Mittelbach
  • 77,146
  • 1
    Directly writing the TOC file is impossible because it must be open for writing, but closed for reading. The only possibility for doing it is having the table of contents as the last thing in the document (which is what texinfo does, IIRC) and this is not an option for a normal document. – egreg Jun 26 '14 at 12:31
  • @egreg right, it is only possible if it comes either first or last but not if the toc potentially comes somewhere in the middle (that's what I meant). Also it would not allow to reuse the TOC data partially, e.g., for chapter tocs. I guess I could have said this slightly better; slightly updated now. – Frank Mittelbach Jun 26 '14 at 13:02