What is the basic mechanism for writing something to an aux file?

Question

I am interested in the basic mechanism behind writing stuff to the .aux file. (Or some other auxiliary file).

Let's say I want to write myself a basic package for making notes on my files. (I know packages already exist for doing this. The point of this question is not to work out how to get comments on my paper, it is to learn about an aspect of the basics of TeX/LaTeX.)

So I have something like this in my preamble:

\usepackage{xcolor}
\newif\ifcomments
\commentstrue
\newcommand\comment[1]{%
  \ifcomments
  \textcolor{red}{\textsf{#1}}
  \else
  \fi
}

This means I have comments I can turn on and off. Now, the next stage is I want a list of comments to appear in an itemize at the end of the document, each comment listed along with its page number. To achieve this, it seems like the easiest way would be to write each comment (plus its page number) to an auxiliary file, and then have a command \writecomments that prints the contents of that file. (Or something of that sort).

How, in simple terms, could I achieve this?

NB this question is designed to help me learn about the basics of TeX/LaTeX, so solutions that involve packages doing a lot of the work will be frowned upon.

Edit I've had two very interesting answers offering different ways to achieve what I want in my example. Neither answer, however, really gets to the real answer I wanted, which would be a, accessible introduction to TeX's/LaTeX's "write to auxiliary file" mechanism.

What I'd like is a more basic answer that someone newer to TeX/LaTeX could read and understand. I feel the current answers are a little too high level.

Answer 1

There is a user friendly LaTeX package: newfile. You can use it to read and write files easily. It provides normal file IO functions, and also verbatim file IO functions. It is more suitable for your example, than those low-level macros. The package document has some good examples.

A naive example (similar to table of contents):

\documentclass{article}
\usepackage{newfile}
\newoutputstream{comment}
\openoutputfile{\jobname.comment}{comment}

\begin{document}

\section{Test}
text one
\addtostream{comment}{\noexpand\item comment one at page \thepage}

text two
\addtostream{comment}{\noexpand\item comment two}


\section{Comments}

\closeoutputstream{comment}
\begin{enumerate}
    \input{\jobname.comment}
\end{enumerate}

\end{document}

Macros will expand when write to file. It is very important to control the expansion. Some macros should not be expanded, like \item here; while some macros should be expanded, like \thepage and \thesection here.

---

In TeX, there are \newwrite, \openout, \immediate, \write, \closeout, \ifeof etc. A good resource is chapter 30 of TeX by Topic.

The same example using TeX primitives:

\documentclass{article}
\newwrite\commentfile
\openout\commentfile=\jobname.comment

\begin{document}

\section{Test}
text one
\write\commentfile{\noexpand\item comment one at page \thepage}

text two
\write\commentfile{\noexpand\item comment two in section \thesection}

\section{Comments}

\closeout\commentfile
\begin{enumerate}
    \input{\jobname.comment}
\end{enumerate}

\end{document}

---

In LaTeX kernel, which you can refer source2e, you can learn from \@starttoc, \@wirtefile, \addcontentsline (for contents) etc.

The same example (works like standard TOC):

\documentclass{article}

\makeatletter
\newcommand\addcommentitem[1]{%
  \write\@auxout{\noexpand\@writefile{comment}{\noexpand\item #1}}}
\newcommand\printcomment{%
  \section*{Comments}
  \begin{enumerate}
    \item[] Here are some comments:
    \@starttoc{comment}
  \end{enumerate}}
\makeatother

\begin{document}

\section{Test}
text one
\addcommentitem{comment one at page \thepage}

text two
\addcommentitem{comment two in section \thesection}

\printcomment

\end{document}

Answer 2

If you have one write handle left you can do it with the following commands which are also used for .toc, .lof, .lot, etc.

\@starttoc{<extension>}

Reads the file with the given extension (\jobname.<extension>) and opens it for writing afterwards. The file is initially empty. Creates the output file handle \tf@<extension> .

\@writefile{<extension>}{<code>}

Writes code using the output handle \tf@<extension> if it exists.

I have these macros in macros2e and was planning to add a short HowTo for exactly this application.

You can define a \listofcomments initially as \relax and \writecomments (or \makecomments) defines it than to \@starttoc{cmt}, which reads/creates '\jobname.cmt'.

---

You should be able to write directly to the current .aux file (main or include file) with:

 \write\@auxout{...}

or, if you want to write explicitly to the main .aux file:

 \write\@mainaux{...}

They create an whatsit so the page number should be correct.

For other, new files you need to create a write handle and open the file first. This is done using:

 \newwrite\myhandle% There are only 16 write handles, even with eTeX!
 \openout\myhandle=<filename>\relax% or space
 % ...
 \closeout\myhandle % to close the file

You can prefix all of these commands (except \newwrite) with \immediate to make same execute immediately without creating a whatsit. Then however the page counter won't be correct yet.