[Tex/LaTex] the basic mechanism for writing something to an aux file

auxiliary-filestex-coretutorials

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.

Best Answer

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}
Related Question