todo 2.4142 (31mar10)

git-svn-id: svn://tug.org/texlive/trunk@17660 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 326 insertions, 187 deletions

diff --git a/Master/texmf-dist/source/latex/todo/todo.dtx b/Master/texmf-dist/source/latex/todo/todo.dtx
index 2b697475610..15f4313e38d 100644
--- a/Master/texmf-dist/source/latex/todo/todo.dtx
+++ b/Master/texmf-dist/source/latex/todo/todo.dtx
@@ -3,7 +3,7 @@
 % todo - package for to-do lists.
 % Copyright 2002 Federico Garcia (feg8@pitt.edu, fedegarcia@hotmail.com)
 % -------------------------------------------
-% 
+%
 %
 % This program can be redistributed and/or modified under the terms
 % of the LaTeX Project Public License distributed from CTAN archives
@@ -13,13 +13,13 @@
 %
 %<*driver>
 % \fi
-\ProvidesFile{todo.dtx}[2002/07/25 v1.1 To-do list]
+\ProvidesFile{todo.dtx}[2010/03/31 v2.4142 To-do list]
 % \iffalse
 \documentclass{ltxdoc}
 \GetFileInfo{todo.dtx}
 \title{\texttt{todo} package for appending a \emph{to-do} list to a document}
 \date{\filedate{}}
- \author{Federico Garcia\\\texttt{feg8@pitt.edu}}
+ \author{Federico Garcia\\\texttt{federook@gmail.com}}
 
 \begin{document}
 \maketitle
@@ -28,98 +28,132 @@
 %</driver>
 % \fi
 % \begin{abstract}
-% |todo| package provides commands for the typesetting of a \emph{to-do} list in any 
-% document, with a customizable format and fully implemented cross referencing. This is 
+% \noindent|todo|  provides commands for the typesetting of a \emph{to-do} list in any
+% document, with a customizable format. This is
 % version \fileversion{}, released on \filedate{}.
-% 
+%
+%A sample file accompanies this release (\texttt{todo-spl.tex}). It contains all the different possibilities and should be useful as a quick usage guide.
 % \end{abstract}
-% 
-% \section{Usage}
-% 
-% \subsection{Basic user macros}\label{basic}
-% 
-% This section describes what happens by default, when using |todo| without options and with % default values for the user variables. Subsection~\ref{cust} describes how this can be 
-% changed.
-% 
-% \DescribeMacro{\todo}At any place in the document, the user can issue a |\todo| command, 
-% that inserts a \emph{to-do}~mark into the text, and appends a \emph{to-do}~text to the 
-% \emph{to-do}~list. The syntax of |\todo| is
-% 
-% |\todo[|\meta{mark}|]{|\meta{text}|}|
-% 
-% The mark is inserted as a superscript in boldface. If no \meta{mark} is given, the 
-% default, `To~do,' is inserted. After the mark, in the superscript, the number of the 
-% \emph{to-do} is put within parenthesis: this is an example.\textsuperscript{\textbf{To~do} % (3)} As another example, with the optional argument specified, |\todo[FIX]{Fix this}| 
-% renders~\textsuperscript{\textbf{FIX} (4)}.
-% 
-% \DescribeMacro{\todos}The |\todos| command effectively typesets the list that includes the % \meta{text}'s of any previous |\todo| command. The list is typeset in |\large| size, in a 
-% new page, under the heading `To~do\dots,' and with an empty box behind each entry 
-% (intended for checkmarks). Each entry, moreover, bears the number of the \emph{to-do} and 
-% a reference to the page in which it was issued. It looks like
-% 
-% {\large\begin{list}{\fbox{\vphantom{Ap}\hphantom{A}}\quad3.}
-% \item (p.~5) This is yet to be done.
-% \end{list}}
-% 
-% \medskip
-% If \meta{mark} was specified in a |\todo| command, this mark appears in the particular 
-% entry in the \emph{to-do} list, like in
-% 
-% {\large\begin{list}{\fbox{\vphantom{Ap}\hphantom{A}}\quad4.}
-% \item \textbf{FIX} (p.~5) This is an example, nothing  to be actually fixed.
-% \end{list}}
-% 
-% \medskip
-% 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 
-% \emph{to-do}~list comes at the end of the document) and prevents the need of an auxiliary 
-% file.\footnote{This could be changed, if desirable. Please write me if you think it is.} 
-% 
-% \subsection{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 \emph{to-do} was executed. Moreover, when
-% using |hyperref| package, each mark in the text 
-% will link to the entry in the \emph{to-do} % list, and viceversa.
-% 
-% \DescribeMacro{\label}The user can add his own |\label| to any |\todo|. The matching 
-% |\ref| will make reference to the number of the \emph{to-do}. However, |\pageref| will 
-% lead to the page in which the |\todo| occurred, unless the |\label| has been put 
-% \emph{inside} the \meta{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 \emph{to-do} (not to the mark).
-% 
-% \subsection{Customization}\label{cust}
-% 
-% \subsubsection{Package Options}
-%
-% \DescribeEnv{marginpar}\DescribeEnv{superscript}\DescribeEnv{nothing}The option 
-% |marginpar| makes the mark to appear not as a superscript, but as a margin par, like in 
-% the next paragraph. The option |superscript|, selected by default, makes it appear as a 
-% superscript, as explained in subsection~\ref{basic}. A third option is |nothing|, which 
-% prevents |\todo| from insert anything in the text, while still appending entries to the 
+%\tableofcontents
+%\section{Preface to version 2.4142}
+%
+%The present version of \texttt{todo} corrects some bugs and adds some features. Thanks to all the users who wrote to me in the last few years with these suggestions. I'm finally getting around to putting it together.
+%
+%\subsection{Correction reference}
+%These are bugs of version 1.1 of \texttt{todo}:
+%\begin{enumerate}\itemsep0pt\parsep0pt\parskip0pt
+%\item There is a spurious space after the superscript marks. \textbf{Solved.}
+%\item |\todo| gives an error if it's the first thing on a line. \textbf{Solved.}
+%\item |\todos| complains when there have been no |\todo| commands. \textbf{Solved.}
+%\item The todo counter confuses the \texttt{backref} package. 
+%\end{enumerate}
+%
+%These have been taken care of in the present version (2.4241). The \texttt{backref} problem is actually there with any referrable counter, not only |todo|'s, and for example a |\label| to a figure or an equation will also confuse \texttt{backref}. 
+%
+%\subsection{Addition reference}
+%
+%New features include:
+%\begin{enumerate}\itemsep0pt\parsep0pt\parskip0pt
+%\item A quiet |\todo*| command that adds an item to the todo list, but makes no fuss in the text.
+%\item A verbose |\Todo| command that puts its text within the running text.
+%\item A |\done| command that indicates the thing |\todo| was already done, allowing to keep it in the document for reference.
+%\item A |todoenv| environment for additional formatting options.
+%\end{enumerate}
+%
+% \section{Basic usage}
+%
+%See also the accompanying sample file, |todo-spl.tex| and |todo-spl.dvi|.
+%\subsection{Basic behavior}
+%
+%A `todo' has two main components: its text (whatever it is that is yet to be done), and a mark, that identifies the point in the document where the todo belongs. The most basic macros of the |todo| package gather the text of several todos, and compile a list of them, to be printed at the end of the document, while at the same time putting the marks in the document itself.
+%
+%By default, the mark is `\textbf{To~do}'. By default, it is typeset as a superscript at the point the todo is invoked, and it is followed by the todo number, which identifies it in the list of todos. (The todo number is a |\ref|, pointing to the item in the todo list at the end of the document; if running \texttt{hyperref}, it will be an interactive link.) The actual text of the todo is put in the list of todos, at the end of the document.
+%
+%\DescribeMacro{\todo}That is what happens when the user inserts |\todo{|\meta{todo text}|}| in a document. Additional commands and alternatives provide for variations of this basic behavior.
+%
+%\subsection{Display options}
+%
+%\DescribeMacro{marginpar}The todos' marks show up as superscripts by default, but they can also be put as marginal notes (|\marginpar|'s). That may be more useful if one doesn't want the todos to interfere with the layout of the text. In order to do this, the package should be loaded with |marginpar| option: |\usepackage[marginpar]{todo}|.
+%
+%\subsection{Custom marks}
+%
+%\DescribeMacro{\todo[]}The default text for a mark is `\textbf{To~do}', but |\todo| has an optional argument for different marks. In |\todo[Fix]{To fix}|, the mark within the document will be `Fix', not `To~do'. (It will still be followed by the number of the todo.) The todo text (``To fix'') will go to the final list of todos, as usual, and will also include the custom mark.
+%
+%\DescribeMacro{\todoformat}All marks, the default or the optional one, are formatted by |\todoformat|. This is by default equal to |\bfseries|, but it can be redefined with any other declaration(s) for font, size, alignment, etc.
+%
+%\DescribeMacro{\todomark}The text of the default mark itself can be changed by redefining |\todomark|, whose default value is `To~do'.
+%
+%\subsection{Quiet todos}
+%
+%\DescribeMacro{\todo*}It is possible to omit the mark of a todo, so as to not affect text layout at all, with the starred command |\todo*|. It takes the same arguments as the regular |\todo| (including the optional argument), and it puts the todo text in the todo list at the end, but it does nothing to the actual text of the document.
+%
+%\DescribeMacro{nothing}\DescribeMacro{hide}If this is the desired behavior for all todos, option |nothing| can be loaded (|\usepackage[nothing]{todo}|) and all todo commands will be quiet. Another option, |hide|, will cause not only all |\todo|'s, but also the final list of todos, to disappear.
+%
+%\subsection{Verbose todos}
+%
+%\DescribeMacro{\Todo}On the other hand, it is possible to make todos that include their text (what is yet to be done) within the document's text, as part of the todo mark. This is achieved with uppercase |\Todo|. Once again, it takes an optional argument for its mark (if other than `To~do'). The text of the todo will be appended both in the todo list \emph{and} in the running text of the document, either as a superscript or a marginpar (according to package options), and following the mark and todo number.
+%
+%\DescribeMacro{\Todo*}A concoction like |\Todo*| (`quiet verbose todo') is not too sensible, but it is provided for completeness. It will behave as a quiet |\todo*|, and issue a package warning.
+%
+%\section{Done todos}
+%
+%\DescribeMacro{\done}When a todo (whatever had to be done) has been done, the user can simply delete the todo command to remove it from the document. But sometimes it is a good idea to leave the todo information in the input file, for reference, and also to keep the original todo numbering. The command |\done| is a convenient way of dealing with this situation. Any |\todo| (or |\Todo|) can be preceded by |\done|, and then its behavior changes: it won't put anything in the text, but the todo will be numbered and added to the list of todos at the end (with the difference that its box will be checkmarked.)
+%
+%A |\done| command that is not followed by a |\todo| or a |\Todo| will have no effect, and will issue a package warning (`|floating \done|\dots').
+%
+%\DescribeMacro{\done[]}The |\done| command itself has an optional argument, a \meta{done~text} intended for notes with the date it was `done', or the initials of whoever `did it'. So:
+%\begin{description}
+%\item[]|\done| Text text |\todo|: This creates a warning, but the |\done| is otherwise ignored.
+%\item[]|\done\todo{Fix}|: This will checkmark the box of the `Fix' item in the \emph{to-do} list.
+%\item[]|\done[By me]\todo{Fix}|: The item in the list will be checkmarked and have `By me' added to it.
+%\end{description}
+%
+%\section{For full flexibility: the \texttt{todoenv} environment}
+%
+%\DescribeEnv{todoenv}There is a different kind of todo that is supported by the package. Instead of a reminder for a quick fix (`get bibliography,' `complete the proof,' or stuff like that), intended mainly for private use, a todo can be conceived of as part of the document---like in semi-public reports of on-going projects or developing software, describing future features or project steps. On the other hand, a verbose todo (|\Todo| above) may be problematic when its text runs for longer than one line, in which case it would be better just to surround it with todo marks instead of to put it all \emph{in} a mark.
+%
+%The \texttt{todoenv} environment is designed for these cases and to provide further options:
+%
+%|\begin{todoenv}|\meta{extended todo text}|\end{todoenv}|.
+%
+%The default behavior of this construction is to typeset the \meta{extended todo text} normally, within the document, but inserting a superscript (or a marginpar, according to package options) at the beginning (`To do begin') and one at the end (`To do end ($n$)').
+%
+%\DescribeMacro{\todoopen}\DescribeMacro{\todoclose}\DescribeMacro{\astodos}But this can be modified with a number of commands. |\todoopen| holds the contents of the beginning mark, and |\todoclose| the contents of the ending mark. (The definitions of these two commands can use |\astodos{|\meta{mark text}|}|, so that they behave as a superscript or as a marginpar, or even as nothing, according to the options of the package.)
+%
+%\DescribeMacro{\todoenvformat}The text of the todo is formatted by |\todoenvformat|, that can contain standard declarations (font, size, alignment, etc.). (|\todoenvformat| is initially empty.)
+%
+%The \meta{todo text} of a |todoenv| environment is not quoted in the final todo list. The respective item for the todo will (like regular todos) have a reference to the number and page of the todo, followed by \texttt{see text}.
+%
+%\section{The final list of todos}
+%
+%\DescribeMacro{\todos}Command |\todos| prints the final list that gathers the todo text of all the todos (except \texttt{todoenv} environments, that simply refer to the text). Each item has a box, checkmarked when |\done|, the todo number, and a reference (and interactive link if \texttt{hyperref} is on) to the page where it appears.
+%
+%\DescribeMacro{\todoname}By default, the list appears in a new page, under the heading `\textbf{To do\dots}'. This can be modified by redefining |\todoname|.
+%
+%After |\todos|, all todo mechanisms are disabled. The list is really intended to be the last thing in the document.
+%
+%\section{Reference}
+%\subsection{Package options}
+% \DescribeMacro{marginpar}\DescribeMacro{superscript}\DescribeMacro{nothing}The option
+% |marginpar| makes the mark to appear not as a superscript, but as a margin par, like in
+% the next paragraph. The option |superscript|, selected by default, makes it appear as a
+% superscript, as explained in subsection~\ref{basic}. A third option is |nothing|, which
+% prevents |\todo| from insert anything in the text, while still appending entries to the
 % list.
 %
-% This\marginpar{\hfill To~do (2)} is the paragraph that exemplifies |marginpar| option. 
-% (The presence of options names in the margin of the previous one made it a bad example.) 
+% Another options is |hide|\DescribeMacro{hide}, which causes all |\todo|'s and |\todos| to be ignored (they will only produce a warning). Unlike |nothing|, |hide| will also omit the final list of todos.
 %
-% Another pair of options is \DescribeEnv{hide}\DescribeEnv{show}|hide| and |show|\@. Using 
-% |hide| makes |\todo| and |\todos| to be ignored (they will only produce a warning), which 
-% is useful for printing semi-final copies. Of course, |show| is selected by default.
-% 
-% \subsection{User variables}
+% \subsection{Cross referencing}
 %
-%  \DescribeMacro{\todomark}\DescribeMacro{\todoname} The user can change the default text 
-% of the marks, |\renewcommand|ing |\todomark|, and the heading of the list with 
-% |\todoname|. Remember that marks for particular entries can be specified by the optional 
-% argument of |\todo| (subsection~\ref{basic}). Changing the value of |\todomark| is useful 
-% if \emph{most} entries are different than `To~do.' In any case, when as superscript, the 
-% mark appears always boldface, and before the \emph{to-do}~number. Further customization 
-% seems not to be necessary, because of the draft-like nature of any document with 
-% \emph{to-do}'s.
+% The |\todo| command creates internal labels and references, so that each entry in the list
+% has a correct reference, and potentially a hyperlink, to the page in which the \emph{to-do} was executed. 
 %
-% The initial values are |{To~do}| for |\todomark| and |{To do\dots}| for |\todoname|.
+% \DescribeMacro{\label}The user can add his own |\label| to any |\todo|. The matching
+% |\ref| will make reference to the number of the \emph{to-do}. However, |\pageref| will
+% lead to the page in which the |\todo| occurred, unless the |\label| has been put
+% \emph{inside} the \meta{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 \emph{to-do} (not to the mark).
 %
 % \section{Implementation}
 %
@@ -127,105 +161,210 @@
 %    \begin{macrocode}
 %<*package>
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{todo}[2002/07/25 v1.1 To-do list (Federico Garcia)]
+\ProvidesPackage{todo}[2010/03/31 v2.4142 To-do list (Federico Garcia)]
+\RequirePackage{amssymb}
 %    \end{macrocode}
 %
-% \subsection{Options}
+% \subsection{Variables}
+%
+% \DescribeMacro{\@todotoks}|\@todotoks| is the token register that will store the entries
+% of the list.\DescribeMacro{\if@todo} The |\if@todo| test is used by the |\done| mechanism.
+%    \begin{macrocode}
+\newtoks\@todotoks\@todotoks{}
+\newif\if@todo\@todotrue
+\newcounter{todo}\setcounter{todo}{0}
+\newcommand*\todomark{To~do}
+\newcommand*\todoname{To do\dots}
+%    \end{macrocode}
+%
+%\subsection{Basic workings and package options}
+%
+%A todo consists of two processes: the \emph{gathering} stage, that manages the todo's information (counter, cross referencing, and the addition of the \meta{todo text} to the final list), and the \emph{display} stage, that inserts the appropriate mark for the todo in the running text.
+%
+%The first process is in the main shared by all the different versions of the todo commands. The second process, however, depends on the current options, and on the exact variety of todo command that is used. This is handled by the wild-card command |\@tododisplay|, whose meaning can be |\textsuperscript|, |\marginpar|, or a package warning, according to the options.
 %
-% The options modify |\@todohide| and |\@todomark|. 
-% \DescribeMacro{\@todohide}\DescribeMacro{\@todomark} The former is called by |\todo| and 
-% |\todos|, and the latter is called by |\todo| to typeset the mark. This commands are 
-% defined depending on which options are used.
 %    \begin{macrocode}
 \newcommand\@todomark{}
-\newcommand\@todohide{}
-\DeclareOption{hide}{\renewcommand\@todohide[1]{%
-    \PackageWarning{todo}{`hide' option used, %
-        ignoring \noexpand\todo's}}}
-\DeclareOption{show}{\renewcommand\@todohide[1]{#1}}
-\DeclareOption{superscript}{\renewcommand\@todomark{%
-    \@todosupermark}}
-\DeclareOption{marginpar}{\renewcommand\@todomark{%
-    \@todomarginpar}}
-\DeclareOption{nothing}{\let\@todomark\@gobble}
+\let\@todohide\relax
+\let\todoformat\bfseries
+\DeclareOption{nothing}{\renewcommand*\@tododisplay[1]{}}
+\DeclareOption{hide}{\let\@todohide\@gobble
+    \renewcommand*\@tododisplay[1]{%
+    \PackageWarning{todo}{`hide' option used, ignoring \string\todo's}}}
+\DeclareOption{superscript}{\let\@tododisplay\textsuperscript}
+\DeclareOption{marginpar}{\renewcommand*\todoformat{\sffamily\raggedright\small}%
+    \let\@tododisplay\marginpar}
 \DeclareOption*{\typeout{Unknown option (`\CurrentOption')}}
-\ExecuteOptions{superscript,show}
+\ExecuteOptions{superscript}
 \ProcessOptions
 %    \end{macrocode}
 %
-% \subsection{Variables} 
+%\subsection{The final list}
+%
+%\begin{macro}{\todos}The list of todos is a \texttt{list} environment, called by |\todos|. The actual contents of the list is provided by the token register |\@todotoks|, that has been compiled by the different |\todo| commands (and its variations) throughout the document.
+%
+%The list is subject to |\@todohide|, that is |\@gobble| if the package was loaded with option |hide| (otherwise it's |\relax|).
 %
-% \DescribeMacro{\@todotoks}|\@todotoks| is the token register that will store the entries 
-% of the list. 
+%After typesetting the list, all user commands are redefined to a package warning (no todos are supposed to come after the list of todos). |\todos| itself is made an error; the user should really be called attention to the duplication.
 %    \begin{macrocode}
-\newtoks\@todotoks\@todotoks{}
-\newcounter{todo}\setcounter{todo}{0}
-\newcommand{\todomark}{To~do}
-\newcommand{\todoname}{To do\dots}
+\newcommand\todos{%
+    \ifnum\c@todo>0 
+        \@todohide{%
+        \clearpage\section*{\todoname}\large%
+        \begin{list}{$\Box$%
+                \quad\arabic{todo}}{}%
+            \usecounter{todo}
+            \the\@todotoks
+        \end{list}}
+        \renewcommand*\todo{%
+            \PackageWarning{todo}{All \string\todo\space commands are ignored after 
+                \string\todos}%
+            \@ifnextchar*{\@todogobble}{\@todogobble*}}%
+        \let\Todo\todo
+        \renewenvironment{todoenv}{\PackageWarning{todo}{\string\todoenv\space after 
+            \string\todos\space not processed as a todo item}}{}%
+        \renewcommand\todos{\PackageError{todo}{Second \string\todos\space ignored}%
+            {I can only make one list of todo items. I'll be Ok if you press enter, 
+            but all \string\todo\space commands after the first \string\todos\space 
+            have been ignored.}}%
+    \else
+        \PackageWarning{todo}{Nothing \string\todo! I'm ignoring the \string\todos\space
+            command}%
+    \fi
+    }
+\newcommand\@todogobble[1]{\@@todogobble}
+\newcommand\@@todogobble[2][\todomark]{\relax}
+%    \end{macrocode}
+%\end{macro}
+%
+%The actual items of this list are added by the |\todo| commands to the |\@todotoks| register, and they can be of one of two kinds: a regular todo, and a todo that was done. The several arguments for the respective commands handle the user's optional arguments. (They have been converted to regular arguments by the |\todo| commands themselves, so they are all explicit in |\@todotoks|.)
+%\begin{macro}{\todoitem}
+%    \begin{macrocode}
+\newcommand\todoitem[2]{%
+    \item \label{todolbl:\thetodo}%
+    (p.~\pageref{todopage:\thetodo}):
+    {\todoformat\ifx#1\todomark\else#1 \fi}#2}%
 %    \end{macrocode}
 %
-% \subsection{The macros}
+%\end{macro}\begin{macro}{\doneitem}
+%For |\doneitem|, what was the optional argument to |\done| (not to the |\todo| commands) has been actually put in a control sequence, whose name is |\@done|\meta{todo number} (something like |\@done12|.
 %
-% |\todo| has two main tasks: \DescribeMacro{\todo} 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 % \LaTeXe\ macros |\@bsphack| and |\@esphack|, to maintain the current space factors and the % like, and launched or not by |\@todohide|.
 %    \begin{macrocode}
-\newcommand{\todo}[2][\todomark]{\@bsphack\@todohide{%
-    \refstepcounter{todo}\label{todopage:\thetodo}%
-        \@todomark{#1}%
-        \@todotoks\expandafter{\the\@todotoks\relax%
-            \todoitem{#1}{#2}}%
-    }\@esphack}
+\newcommand\doneitem[2]{%
+    \stepcounter{todo}%
+    \item[\rlap{$\checkmark$}$\Box$\quad
+        \arabic{todo}]\@nameuse{@done\the\c@todo}(p.~\pageref{todopage:\thetodo}):
+        {\todoformat\ifx#1\todomark\else#1 \fi}#2}
 %    \end{macrocode}
+%\end{macro}
 %
-% |\@todomark|
-% \DescribeMacro{\@todosupermark}\DescribeMacro{\@todomarginpar} 
-% has been defined (by the options) either as |\@todosupermark| or |\@todomarginpar| (or 
-% |\@gobble| for the |nothing| option). Both macros, in addition to put the corresponding mark, make |\ref| 
-% to the actual text of the \emph{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 \LaTeXe~|\footnote|.
-%    \begin{macrocode}
-\newcommand{\@todosupermark}[1]{%
-  \leavevmode
-  \ifhmode\edef\@x@sf{\the\spacefactor}\nobreak\fi
-  \textsuperscript{\textbf{#1} (\ref{todolbl:\thetodo})}
-  \ifhmode\spacefactor\@x@sf\fi
-  \relax}
-\newcommand{\@todomarginpar}[1]{\marginpar{#1 (\ref{todolbl:\thetodo})}} 
+%\subsection{The \texttt{$\backslash$done} mechanism}
+%
+%\begin{macro}{\done}A few things are done by |\done|: first, it has to check that it is actually followed by a |\todo| of some sort, in which case it sets |\@todofalse| (so that the coming |\todo| command knows that it is |\done|).
+%    \begin{macrocode}
+\newcommand\done[2][\relax]{%
+    \ifx#2\todo\@todofalse\else
+        \ifx#2\Todo\@todofalse\else
+        \PackageWarning{Floating \string\done\space ignored.}%
+    \fi\fi
 %    \end{macrocode}
+%Then the optional argument is used to define a command |\@done|\meta{todo number}, which will be used by |\doneitem| in the list of todos. There will be a space after the optional argument; if the user does not specify it, then |#1| is |\relax|, and the space after will not be typeset (since it comes after a command).
 %
-% \DescribeMacro{\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 \emph{to-do}~number, the |\ref| to the page in which it 
-% occurred, and the \meta{mark} (boldfaced) if it is different than |\todomark|. After all 
-% that, of course, it has the \emph{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.
-%    \begin{macrocode}
-\newcommand{\todoitem}[2]{%
-    \item \label{todolbl:\thetodo} %
-    \ifx#1\todomark%
-        \else\textbf{#1 }%
-    \fi%
-    (p.~\pageref{todopage:\thetodo})\ #2}
+%    \begin{macrocode}
+    \@tempcnta\c@todo\advance\@tempcnta1
+    \@namedef{@done\the\@tempcnta}{#1 }#2%
+    }
 %    \end{macrocode}
+%\end{macro}
 %
-% Finally, \DescribeMacro{\todos}|\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|.
+%\subsection{User commands}
+%
+%The user commands are actually driver commands that don't even deal with the arguments. They decide which executive functions to delegate on. Most of them call the |\@newtodo| routine:
+%    \begin{macrocode}
+\newcommand\@newtodo{\refstepcounter{todo}\label{todopage:\thetodo}}
+%    \end{macrocode}
+%
+%\begin{macro}{\todo}Regular |\todo| makes a new todo, and then: if starred, it displays nothing (although it still has to process the argument(s)); if not starred, it displays the regular todo mark---provided |\if@todo| was not set to |false| by a preceding |\done|.
+%    \begin{macrocode}
+\newcommand*\todo{\@ifnextchar*{\@newtodo\@displaynothing}{%
+    \@newtodo
+    \if@todo
+        \expandafter\@displaytodo
+    \else
+        \expandafter\@donetodo
+    \fi}}
+%    \end{macrocode}
+%\end{macro}
+%
+%\begin{macro}{\Todo}The verbose |\Todo| invokes |\@displayfulltodo| (unless it's starred, in which case it delegates on regular |\todo|):
+%    \begin{macrocode}
+\newcommand\Todo{\@ifnextchar*{%
+    \PackageWarning{todo}{Starred \string\Todo* taken as\string\todo*}%
+        \expandafter\todo}%
+    {\@newtodo\@displayfulltodo}}
+%    \end{macrocode}\end{macro}
+%
+%\begin{macro}{todoenv}The definition of the |todoenv| environment contains all the tasks of a todo: setting up a new one (|\@newtodo|), typesetting marks and text, and, unlike the previous commands, also putting a list item in |\@todotoks|.
+%    \begin{macrocode}
+\newenvironment{todoenv}{\@newtodo
+    \global\@todotoks\expandafter{\the\@todotoks\relax\todoitem
+        {}{{\itshape see text.}}}%
+    \todoopen\todoenvformat}{\todoclose}
+%    \end{macrocode}
+%|todoenv| makes use of some placeholder commands for the marks and the text formatting. Here is their default definition (|\astodos| is used to signify either superscript or marginpar.
+%    \begin{macrocode}
+\newcommand*\astodos[1]{\@tododisplay{{\todoformat #1}}}
+\newcommand*\todoopen{\astodos{\todomark\ begin}}
+\newcommand*\todoclose{\astodos{\todomark\ end 
+    \normalfont(\ref{todolbl:\thetodo})}}\newcommand\todoenvformat{}
+%    \end{macrocode}\end{macro}
+%
+%\subsection{The display commands}
+%
+%\begin{macro}{\@displaytodo}Regular todos put a mark in the text:
+%    \begin{macrocode}
+\newcommand\@displaytodo[2][\todomark]{%
+    \@tododisplay{{\todoformat #1} (\ref{todolbl:\thetodo})}%
+    \global\@todotoks\expandafter{\the\@todotoks\todoitem{#1}{#2}}%
+    \@todotrue
+    }
+%    \end{macrocode}\end{macro}
+%
+%\begin{macro}{\@displaynothing}When nothing is to be displayed, the arguments still have to be appended to the final list. The routine is delayed because the star of |\todo*| (the command that eventually is the one to call |\@displaynothing|) has to be gobbled.
+%    \begin{macrocode}
+\newcommand\@displaynothing[1]{\@@displaynothing}
+\newcommand\@@displaynothing[2][\todomark]{%
+    \if@todo
+        \global\@todotoks\expandafter{\the\@todotoks\todoitem{#1}{#2}}%
+    \else
+        \global\@todotoks\expandafter{\the\@todotoks\doneitem{#1}{#2}}%
+    \fi
+    \@todotrue
+    }
+%    \end{macrocode}\end{macro}
+%
+%\begin{macro}{\@displayfulltodo}For verbose todos, |\@displayfulltodo|:
+%    \begin{macrocode}
+\newcommand\@displayfulltodo[2][\todomark]{%
+    \if@todo
+        \@tododisplay{{\todoformat #1} #2 (\ref{todolbl:\thetodo})}%
+        \global\@todotoks\expandafter{\the\@todotoks\todoitem{#1}{#2}}%
+    \else
+        \global\@todotoks\expandafter{\the\@todotoks\doneitem{#1}{#2}}%
+    \fi
+    \@todotrue
+    }
+%    \end{macrocode}\end{macro}
+%
+%\begin{macro}{\@donetodo}And for |\done| todos:
+%    \begin{macrocode}
+\newcommand\@donetodo[2][\todomark]{%
+    \global\@todotoks\expandafter{\the\@todotoks\doneitem{#1}{#2}}%
+    \@todotrue
+    }
+%    \end{macrocode}\end{macro}
+%
+%Note that all these commands end by resetting |\@todotrue|. This ensures that the next todo is, by default, not |\done|.
 %    \begin{macrocode}
-\newcommand{\todos}{\@todohide{%
-        \clearpage\section*{\todoname}\large%
-        \begin{list}{\fbox{\vphantom{Ap}\hphantom{A}}%
-                \quad\arabic{todo}.}{}%
-            \usecounter{todo}
-            \the\@todotoks
-        \end{list}}
-        \renewcommand{\todo}[1]{%
-    \PackageWarning{todo}{\noexpand\todos already issued, %
-        ignoring \noexpand\todo}}}
 %</package>
 %    \end{macrocode}
diff --git a/Master/texmf-dist/source/latex/todo/todo.ins b/Master/texmf-dist/source/latex/todo/todo.ins
index e0578c51ecb..9916030072a 100644
--- a/Master/texmf-dist/source/latex/todo/todo.ins
+++ b/Master/texmf-dist/source/latex/todo/todo.ins
@@ -1,21 +1,21 @@
-\input docstrip.tex

-\keepsilent

-\preamble 

-

-Copyright 2002 Federico Garcia

-

-\endpreamble

-\generate{\file{todo.sty}{\from{todo.dtx}{package}}}

-    

-\Msg{***********************************************************}

-\Msg{*}

-\Msg{* To finish the installation you have to move the file}

-\Msg{* `todo.sty' into a directory searched by TeX.}

-\Msg{*}

-\Msg{* To produce the documentation run the file `todo.dtx'}

-\Msg{* through LaTeX.}

-\Msg{*}

-\Msg{***********************************************************}

-

-

-\endbatchfile 
\ No newline at end of file
+\input docstrip.tex
+\keepsilent
+\preamble 
+
+Copyright 2002-10 Federico Garcia
+
+\endpreamble
+\generate{\file{todo.sty}{\from{todo.dtx}{package}}}
+    
+\Msg{***********************************************************}
+\Msg{*}
+\Msg{* To finish the installation you have to move the file}
+\Msg{* `todo.sty' into a directory searched by TeX.}
+\Msg{*}
+\Msg{* To produce the documentation run the file `todo.dtx'}
+\Msg{* through LaTeX.}
+\Msg{*}
+\Msg{***********************************************************}
+
+
+\endbatchfile