todo package for appending a to-do list to a document

Federico Garcia

                      feg8@pitt.edu

2002/07/25

Abstract

todo package provides commands for the typesetting of a to-do list in any document, with a customizable format and fully implemented cross referencing. This is version v1.1, released on 2002/07/25.

1 Usage

1.1 Basic user macros

This section describes what happens by default, when using todo without options and with default values for the user variables. Subsection 1.3 describes how this can be changed.

\todo At any place in the document, the user can issue a \todo command, that inserts a to-do mark into the text, and appends a to-do text to the to-do list. The syntax of \todo is

\todo[⟨mark⟩]{⟨text⟩}

The mark is inserted as a superscript in boldface. If no ⟨mark⟩ is given, the default, ‘To do,’ is inserted. After the mark, in the superscript, the number of the to-do is put within parenthesis: this is an example.^{To do (3)} As another example, with the optional argument specified, \todo[FIX]{Fix this} renders ^{FIX (4)}.

\todos The \todos command effectively typesets the list that includes the ⟨text⟩’s of any previous \todo command. The list is typeset in \large size, in a new page, under the heading ‘To do…,’ and with an empty box behind each entry (intended for checkmarks). Each entry, moreover, bears the number of the to-do and a reference to the page in which it was issued. It looks like

3. (p. 5) This is yet to be done.

If ⟨mark⟩ was specified in a \todo command, this mark appears in the particular entry in the to-do list, like in

4. FIX (p. 5) This is an example, nothing to be actually fixed.

The \todos command also turns off the \todo command, so that any \todo after \todos will be ignored (and a warning issued). This is natural (we can assume the to-do list comes at the end of the document) and prevents the need of an auxiliary file.^{1}

1.2 Cross referencing

The \todo command creates internal labels and references, so that each entry in the list has a correct reference to the page in which the to-do was executed. Moreover, when using hyperref package, each mark in the text will link to the entry in the to-do list, and viceversa.

\label The user can add his own \label to any \todo. The matching \ref will make reference to the number of the to-do. However, \pageref will lead to the page in which the \todo occurred, unless the \label has been put inside the ⟨text⟩ (and then the pageref points to the actual text of the \todo, as is probably more desirable). Another reason to put it there is that a hyperref link will point to the actual text of the to-do (not to the mark).

1.3 Customization

1.3.1 Package Options

marginpar The option marginpar makes the mark to appear not as a superscript, but as

superscript
nothing

a margin par, like in the next paragraph. The option superscript, selected by default, makes it appear as a superscript, as explained in subsection 1.1. A third option is nothing, which prevents \todo from insert anything in the text, while still appending entries to the list.

To do (2) This is the paragraph that exemplifies marginpar option. (The presence of

options names in the margin of the previous one made it a bad example.) hide Another pair of options is hide and show. Using hide makes \todo and \todos show to be ignored (they will only produce a warning), which is useful for printing semi-

final copies. Of course, show is selected by default.

1.4 User variables

\todomark The user can change the default text of the marks, \renewcommanding \todomark, \todoname and the heading of the list with \todoname. Remember that marks for particu-

lar entries can be specified by the optional argument of \todo (subsection 1.1). Changing the value of \todomark is useful if most entries are different than ‘To do.’ In any case, when as superscript, the mark appears always boldface, and before the to-do number. Further customization seems not to be necessary, because of the draft-like nature of any document with to-do’s.

   The initial values are {To~do} for \todomark and {To do\dots} for \todoname.

1This could be changed, if desirable. Please write me if you think it is.

2 Implementation

2.1 Identification

1 ⟨∗package⟩

 2 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
 3 \ProvidesPackage{todo}[2002/07/25 v1.1 To-do list (Federico Garcia)]

2.2 Options

\@todohide The options modify \@todohide and \@todomark. The former is called by \todo \@todomark and \todos, and the latter is called by \todo to typeset the mark. This commands

are defined depending on which options are used.

 4 \newcommand\@todomark{}
 5 \newcommand\@todohide{}
 6 \DeclareOption{hide}{\renewcommand\@todohide[1]{%
 7  \PackageWarning{todo}{`hide' option used, %
 8  ignoring \noexpand\todo's}}}
 9 \DeclareOption{show}{\renewcommand\@todohide[1]{#1}}
10 \DeclareOption{superscript}{\renewcommand\@todomark{%
11  \@todosupermark}}
12 \DeclareOption{marginpar}{\renewcommand\@todomark{%
13  \@todomarginpar}}
14 \DeclareOption{nothing}{\let\@todomark\@gobble}
15 \DeclareOption*{\typeout{Unknown option (`\CurrentOption')}}
16 \ExecuteOptions{superscript,show}
17 \ProcessOptions

2.3 Variables

\@todotoks \@todotoks is the token register that will store the entries of the list.

18 \newtoks\@todotoks\@todotoks{}
19 \newcounter{todo}\setcounter{todo}{0}
20 \newcommand{\todomark}{To~do}
21 \newcommand{\todoname}{To do\dots}

2.4 The macros

\todo \todo has two main tasks: produce the mark, and append the text to \@todotoks. For the former, it calls \@todomark, which is defined according to the options. The latter is done just here. In addition, \todo puts the label to the page in which the mark appears, to be used in the typesetting of the list. Everything is framed by L^{A}TEX 2ε macros \@bsphack and \@esphack, to maintain the current space factors and the like, and launched or not by \@todohide.

22 \newcommand{\todo}[2][\todomark]{\@bsphack\@todohide{%
23  \refstepcounter{todo}\label{todopage:\thetodo}%
24  \@todomark{#1}%
25  \@todotoks\expandafter{\the\@todotoks\relax%
26  \todoitem{#1}{#2}}%

27  }\@esphack}
\@todosupermark      \@todomark has been defined (by the options) either as \@todosupermark or
\@todomarginpar  \@todomarginpar (or \@gobble for the nothing option). Both macros, in addition

to put the corresponding mark, make \ref to the actual text of the to-do, whose \label is to be put later on by \todoitem. Note that this is necessary only for supporting hyperref links; otherwise, \ref{todolbl:\thetodo} could have simply

been \thetodo. \@todosupermark shares much code with L^{A}TEX 2ε \footnote.
28 \newcommand{\@todosupermark}[1]{%
29 \leavevmode
30 \ifhmode\edef\@x@sf{\the\spacefactor}\nobreak\fi
31 \textsuperscript{\textbf{#1} (\ref{todolbl:\thetodo})}
32 \ifhmode\spacefactor\@x@sf\fi
33 \relax}
34 \newcommand{\@todomarginpar}[1]{\marginpar{#1 (\ref{todolbl:\thetodo})}}

\todoitem The construction of the list proper is made by successive \todoitem’s appended to \@todotoks. The list is a list environment (called by \todos); each item has the to-do number, the \ref to the page in which it occurred, and the ⟨mark⟩ (boldfaced) if it is different than \todomark. After all that, of course, it has the to-do text itself. Since \todoitem will be called within a token register in document time, it has no @ in its name, although I’m not quite sure it could not have. In any case, it is not intended for the user.

35 \newcommand{\todoitem}[2]{%
36  \item \label{todolbl:\thetodo} %
37  \ifx#1\todomark%
38  \else\textbf{#1 }%
39  \fi%
40  (p.~\pageref{todopage:\thetodo})\ #2}

\todos Finally, \todos does the following: open a new page, put a heading, \begin a list whose label is an empty box (for checkmarks), call \@todotoks, and \end the list. After all that, it redefines \todo to issue a warning, since its text will not be included in the list. Again, all happens only if allowed by \@todohide.

41 \newcommand{\todos}{\@todohide{%
42  \clearpage\section*{\todoname}\large%
43  \begin{list}{\fbox{\vphantom{Ap}\hphantom{A}}%
44  \quad\arabic{todo}.}{}%
45  \usecounter{todo}
46  \the\@todotoks
47  \end{list}}
48  \renewcommand{\todo}[1]{%
49  \PackageWarning{todo}{\noexpand\todos already issued, %
50  ignoring \noexpand\todo}}}

51 ⟨/package⟩