summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-11 23:58:30 +0000
committerKarl Berry <karl@freefriends.org>2006-01-11 23:58:30 +0000
commit4bdfcefb715bd637618a63e10504ace6e9ae1330 (patch)
tree05466b759d3d609c9d3bf3b9e07c31cc8113de4c
parenteb03690598c294b2e1304ae613bf905c79f38c95 (diff)
trunk/Master/texmf-dist/source/latex/todo
git-svn-id: svn://tug.org/texlive/trunk@557 c570f23f-e606-0410-a88d-b1316a301751
-rw-r--r--Master/texmf-dist/source/latex/todo/todo.dtx231
-rw-r--r--Master/texmf-dist/source/latex/todo/todo.ins21
2 files changed, 252 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/todo/todo.dtx b/Master/texmf-dist/source/latex/todo/todo.dtx
new file mode 100644
index 00000000000..2b697475610
--- /dev/null
+++ b/Master/texmf-dist/source/latex/todo/todo.dtx
@@ -0,0 +1,231 @@
+% \iffalse meta-comment
+%
+% 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
+% in the directory macros/latex/base/lppl.txt; either version 1 of
+% the License, or (at your option) any later version.
+%
+%
+%<*driver>
+% \fi
+\ProvidesFile{todo.dtx}[2002/07/25 v1.1 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}}
+
+\begin{document}
+\maketitle
+ \DocInput{\filename}
+\end{document}
+%</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
+% version \fileversion{}, released on \filedate{}.
+%
+% \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
+% 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 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}
+%
+% \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 initial values are |{To~do}| for |\todomark| and |{To do\dots}| for |\todoname|.
+%
+% \section{Implementation}
+%
+% \subsection{Identification}
+% \begin{macrocode}
+%<*package>
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\ProvidesPackage{todo}[2002/07/25 v1.1 To-do list (Federico Garcia)]
+% \end{macrocode}
+%
+% \subsection{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}
+\DeclareOption*{\typeout{Unknown option (`\CurrentOption')}}
+\ExecuteOptions{superscript,show}
+\ProcessOptions
+% \end{macrocode}
+%
+% \subsection{Variables}
+%
+% \DescribeMacro{\@todotoks}|\@todotoks| is the token register that will store the entries
+% of the list.
+% \begin{macrocode}
+\newtoks\@todotoks\@todotoks{}
+\newcounter{todo}\setcounter{todo}{0}
+\newcommand{\todomark}{To~do}
+\newcommand{\todoname}{To do\dots}
+% \end{macrocode}
+%
+% \subsection{The macros}
+%
+% |\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}
+% \end{macrocode}
+%
+% |\@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})}}
+% \end{macrocode}
+%
+% \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}
+% \end{macrocode}
+%
+% 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|.
+% \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
new file mode 100644
index 00000000000..3df968c7f90
--- /dev/null
+++ b/Master/texmf-dist/source/latex/todo/todo.ins
@@ -0,0 +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