On the basics of writing to & reading from auxiliary files (.aux, .toc, etc.)

Question

Some actions (such as generating the Table of Contents) require two passes of the TeX compiler: during the first pass, some data get written to an auxiliary file, only to be retrieved during the second pass. Here are a few TeX.SE questions that require two-pass solutions:

• Highlight referenced equation number
• Backreferences for equations
• (To be completed... feel free to edit if you come across such a question)

Two-pass stuff has piqued my interest; I have a few questions:

1. Can I write (append) custom data to an existing auxiliary file (e.g. .aux)? Is that even a good idea? If not, can I generate my own auxiliary file (with a custom extension) to store/retrieve some data?
2. What are good sources for learning the basics of writing to & reading from auxiliary files?

Answer 1

You can write to the aux file with

\write\@auxout{\gdef\string\testa{hello}}

or

\immediate\write\@auxout{\gdef\string\testb{hello2}}

or

\protected@write\@auxout{}{\gdef\string\testc{hello3}}

Depending on requirements.

\immediate\write writes to the specified file at that point, expanding the supplied tokens (like \edef) so fragile commands will do the wrong thing.

\write does not write at that point it puts a write node into the current vertical or horizontal list and if that list is shipped out to make a page then the write happens. This is needed to get page numbers correct. (If the write is inside a box and that box is never used on the main page then nothing is written to the file.)

\protected@write is a LaTeX-defined macro that uses \write but arranges that \protect works as required in LaTeX to protect fragile commands. The extra argument unused above allows you to locally insert extra definitions to make more commands be safe or have special definition in the write, see for example the definition of \index or \addtocontents.

It is safe to write to the aux file, however you have to be aware that the file will be read back at least at the begin and end of the document, so you need to write lines that are safe in that context.

If you want to write to your own file then you just need to do

\newwrite\myfile
\immediate\openout\myfile=\jobname.foo

in the preamble and then replace \@auxout by \myfile when writing.

Have a look at the way \tableofcontents or \listoftables or \listoffigures work in latex.ltx or documented in source2e. They basically all use

\def\@starttoc#1{%
  \begingroup
    \makeatletter
    \@input{\jobname.#1}%
    \if@filesw
      \expandafter\newwrite\csname tf@#1\endcsname
      \immediate\openout \csname tf@#1\endcsname \jobname.#1\relax
    \fi
    \@nobreakfalse
  \endgroup}