The Problem

One of the great features of using TextMate to produce LaTeX documents is the TODO Bundle. The TODO Bundle let’s you to insert TODOs into comments and display these in a nicely formatted HTML window with links to the lines where the TODOs occurred.¹²

There are two limitations with the TODO Bundle, however, which made me look for an alternative (I still use the TODO Bundle, the alternative is merely a supplement):

1. While I try to proof my documents as much as I can onscreen, sometimes I need to proofread the hardcopy. Proofreading hardcopy is easier, and any incremental decrease in distraction is a real boon in proofreading since it requires a lot of attention.
2. Suppose you are collaborating on a LaTeX document and your collaborator isn’t using TextMate. Of course, they can still follow the TODOs in the comments, but it would be great if these could be made more salient.

The Solution

The solution to both of these problems is to use LaTeX to generate the TODO list for you. To do this, I used the index package. The index package reimplements the internal LaTeX index macros adding functionality. Of particular interest is its support for multiple indexes. Add the following to your preamble:

The first line loads the color package (since our TODOs will be colored to make them stand out from the surrounding text). The second line loads the index package. The next two lines:

\newindex{todo}{tod}{tnd}{TODO List} % start todo list
\newindex{fixme}{fix}{fnd}{FIXME List} % start fixme list

define two indexes. The \newindex command takes four arguments. These arguments correspond to the four pieces of information required to generate the index:

1. A short, unique tag that identifies the index.
2. The extension of the output file where the raw index information will be put by LaTeX.
3. The extension of the input file where the processed information created by MakeIndex will be stored to be read in later by LaTeX.
4. The title of the index.

The next two lines:

\newcommand{\todo}[1]{\textcolor{blue}{TODO: #1}\index[todo]{#1}} % macro for todo entries
\newcommand{\fixme}[1]{\textcolor{red}{FIXME: #1}\index[fixme]{#1}} % macro for fixme entries

define two new commands: \todo and fixme. To add a TODO simply add the following at the appropriate place in the text:

\todo{My TODO entry}

Similarly, for FIXMEs.

New commands can be added on a similar pattern. So, for example, suppose you want to add a CHANGE command. To do this, be sure to also define a new index:

\newindex{change}{chg}{cnd}{CHANGE List} % start change list
\newcommand{\change}[1]{\textcolor{green}{CHANGE: #1}\index[change]{#1}} % macro for change entries

Notice, that the commands are color coded, so be sure to change the color. Since the previous two commands were blue and red, I made the CHANGE command green.

If you want to generate a list of the TODOs, FIXMEs, etc, at the end of your document you need to use the \printindex command. This takes as an option the name of the index, so for TODOs and FIXMEs we would use:

\printindex[todo]
\printindex[change]

Before we typeset these indexes, we need to run the makeindex command. Suppose that the name of your LaTeX document is foo.tex. Then, in the terminal we would run:

$ makeindex -o foo.tnd foo.tod
$ makeindex -o foo.fnd foo.fix

The -o option is used to specify the name of the file generated by makeindex that is used, in turn, by LaTeX to typeset the index. Having run makeindex, if we now typeset the document, the indexes will be printed at the end of the document after a pagebreak. And if you are using the hyperref package, these will have links to the pages where the TODOs and FIXMEs are inserted. This step can be automated with a makefile such as Latexmk.pl.