diff options
author | Karl Berry <karl@freefriends.org> | 2006-01-11 23:58:30 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2006-01-11 23:58:30 +0000 |
commit | 4bdfcefb715bd637618a63e10504ace6e9ae1330 (patch) | |
tree | 05466b759d3d609c9d3bf3b9e07c31cc8113de4c /Master/texmf-dist | |
parent | eb03690598c294b2e1304ae613bf905c79f38c95 (diff) |
trunk/Master/texmf-dist/source/latex/todo
git-svn-id: svn://tug.org/texlive/trunk@557 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist')
-rw-r--r-- | Master/texmf-dist/source/latex/todo/todo.dtx | 231 | ||||
-rw-r--r-- | Master/texmf-dist/source/latex/todo/todo.ins | 21 |
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 |