ed (15jan11)

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

1 files changed, 187 insertions, 60 deletions

diff --git a/Master/texmf-dist/source/latex/ed/ed.dtx b/Master/texmf-dist/source/latex/ed/ed.dtx
index e5fb87ded70..1828ae7b478 100644
--- a/Master/texmf-dist/source/latex/ed/ed.dtx
+++ b/Master/texmf-dist/source/latex/ed/ed.dtx
@@ -1,44 +1,53 @@
 % \iffalse meta-comment
 % Editorial Notes for LaTeX
-% Copyright (c) 2007 Michael Kohlhase, all rights reserved
+% Copyright (c) 2009 Michael Kohlhase, all rights reserved
 %
 % This file is distributed under the terms of the LaTeX Project Public
 % License from CTAN archives in directory  macros/latex/base/lppl.txt.
 % Either version 1.0 or, at your option, any later version.
 %  
 % The development version of this file can be found at
-% $HeadURL: https://svn.kwarc.info/repos/kwarc/doc/macros/ed/ed.dtx $
+% $HeadURL: https://svn.kwarc.info/repos/kwarc/doc/macros/forCTAN/ed/ed.dtx $
 % \fi
 % 
 % \iffalse
 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
-%<package>\ProvidesPackage{ed}[2007/10/03 v1.3 Editorial Notes]
+%<package>\ProvidesPackage{ed}[2011/01/16 v1.7 Editorial Notes]
 %
 %<*driver>
 \documentclass[twoside]{ltxdoc}
+\DoNotIndex{\def,\long,\edef,\xdef,\gdef,\let,\global}
+\DoNotIndex{\begin,\AtEndDocument,\newcommand,\newcounter,\stepcounter}
+\DoNotIndex{\immediate,\openout,\closeout,\message,\typeout}
+\DoNotIndex{\section,\scshape,\arabic}
 \EnableCrossrefs
 %\CodelineIndex
 %\OnlyDescription
 \RecordChanges
 \usepackage{textcomp,url,a4wide}
 \usepackage[show]{ed}
-\usepackage[fancyhdr,today,draft]{svninfo}
+\usepackage[eso-foot,today,draft]{svninfo}
 %\makeindex
-\pagestyle{fancyplain}\fancyhead[RE,LO]{\leftmark}\fancyhead[LE,RO]{\thepage}
 \begin{document}
-\svnInfo $Id: ed.dtx 13981 2007-11-04 14:05:51Z kohlhase $
-\svnKeyword $HeadURL: https://svn.kwarc.info/repos/kwarc/doc/macros/ed/ed.dtx $
+\svnInfo $Id: ed.dtx 21009 2011-01-15 09:07:26Z kohlhase $
+\svnKeyword $HeadURL: https://svn.kwarc.info/repos/kwarc/doc/macros/forCTAN/ed/ed.dtx $
 \DocInput{ed.dtx}
 \end{document}
 %</driver>
 % \fi
 % 
-%\CheckSum{209}
+%\CheckSum{311}
 % 
 % \changes{v1.0}{2005/06/23}{First Version with Documentation}
 % \changes{v1.1}{2005/10/03}{Added capitalized variants}
 % \changes{v1.2}{2007/05/10}{adding todo environment}
 % \changes{v1.3}{2007/10/03}{rationalizing todo environment}
+% \changes{v1.4}{2007/11/12}{localization}
+% \changes{v1.5}{2008/06/08}{todolist now uses enumerate}
+% \changes{v1.6}{2009/06/18}{nomargins option}
+% \changes{v1.6}{2009/06/24}{deprecated issue for edissue to get around name clashes.}
+% \changes{v1.6}{2009/10/29}{made ednotemessage automatic}
+% \changes{v1.7}{2011/01/16}{adding final/draft options}
 % 
 % \GetFileInfo{ed.sty}
 % 
@@ -78,20 +87,26 @@
 % \section{The User Interface}\label{sec:user-interface}
 %
 % As usual in {\LaTeX}, the package is loaded by |\usepackage[|\meta{options}|]{ed}|,
-% where |[|\meta{options}|]| is optional and gives a comma separated list of options.
-% Currently the |ed| package only takes two options |show| and |hide|, where |hide| is the
-% default case, so that |\usepackage{ed}|, is equivalent to |\usepackage[hide]{ed}|. If
-% the |show| option is given, then the editorial notes are presented as special
-% annotations to the document, otherwise they are completely invisible --- if you take
-% care about spaces in the source code. For instance
+% where |[|\meta{options}|]| is optional and gives a comma separated list of options.  The
+% |ed| package takes the options \DescribeMacro{show}|show| and
+% \DescribeMacro{hide}|hide|, where |hide| is the default case, so that |\usepackage{ed}|,
+% is equivalent to |\usepackage[hide]{ed}|. If the |show| option is given, then the
+% editorial notes are presented as special annotations to the document, otherwise they are
+% completely invisible --- if you take care about spaces in the source code. For instance
 % |text|\textvisiblespace|\ednote{|\ldots|}|\textvisiblespace|text| will fool {\TeX}'s
 % whitespace-collapsing algorithm and bring it to output two spaces in the document
 % instead of just one as expected |text\ednote{|\ldots|}|\textvisiblespace|text| should be
 % used instead!  This |hide| option useful for preparing ``clean'' version for outside
-% consumption without loosing the management metadata.
+% consumption without losing the management metadata. In some situations the |\marginpar|
+% decorations generated by editorial notes are disallowed, for these situations the |ed|
+% package has the \DescribeMacro{nomargins}|nomargins| option that disables them.
+% 
+% As many classes support the \DescribeMacro{draft}|draft| and
+% \DescribeMacro{final}|final| options and pass them on to all loaded packages that will
+% take them, the |ed| package supports them as aliases for |show| and |hide|.
 %
 % \subsection{Annotation Macros}
-%
+% 
 % \DescribeMacro{\ednote} The main user macro of this package is |\ednote|. It is used say
 % what you have done or what should still be done at a given point in the document.
 % |ed.sty| formats it like a footnote, but with a margin note that marks the place in the
@@ -101,15 +116,21 @@
 % recognition.  |\ednote| also takes an optional argument that is an identifier. This
 % allows to cross-reference ednotes in each other.
 %
-% \DescribeMacro{\issue} The |\issue| macro\issue{this is an example of an issue} is a
-% variant of |\ednote| for issues that still have to be discussed among the authors. For
-% issues the labeling and cross-referencing in the optional argument is especially useful.
+% \DescribeMacro{\edissue} The |\edissue| macro\edissue{The control sequence\textbf{issue}
+%   conflicts with many other macro packages, maybe we should rename it to
+%   \textbf{edissue}.} is a variant of |\ednote| for issues that still have to be
+% discussed among the authors. For issues the labeling and cross-referencing in the
+% optional argument is especially useful. Note that the \DescribeMacro{\issue}|\issue|
+% macro which earlier versions of the |ed| package provided is deprecated in favor of
+% |\edissue|. The old |\issue| macro is only provided for backwards compatibility if it is
+% not defined by other packages. For this to work, the |ed| package should be loaded late
+% in the preamble.
 %
 % \DescribeMacro{\tweak} The |\tweak| macro\tweak{this is an example of an tweak} is a
 % variant of |\ednote| for marking places where we have tweaked something (apart from the
 % standard way we usually use).
 %
-% \DescribeEnv{todo} The |todo| environment is a environment that can be used to mark up
+% \DescribeEnv{todo} The |todo| environment is an environment that can be used to mark up
 % writing tasks. These are inserted into the text in a different font, so that they are
 % conspicuous as a foreign part, and take an argument for a comment.
 %
@@ -127,35 +148,43 @@
 % up changed text blocks.  |\beg||in{newpart}| takes an argument that is interpreted as a
 % comment and is treated like an |\ednote| comment.  The |oldpart| environment is similar
 % to |newpart| but is used for old parts of text copied from another document that still
-% need to be changed in a document.
+% need to be changed in a document. They displayed in gray, so that they can be identified
+% better.
 %
-% The annotation macros have capitalized variants (|\Ednote|, |\Issue|, |\Tweak|, |Todo|,
-% |Newpart|, |Oldpart|) that do not make location marks in the margin. This is convenient
-% in situations (e.g. inside boxes or minipages) that allow footnotes, but no margin
-% notes.
+% The annotation macros have capitalized variants (|\Ednote|, |\edIssue|, |\Tweak|,
+% |Todo|, |Newpart|, |Oldpart|) that do not make location marks in the margin. This is
+% convenient in situations (e.g. inside boxes or minipages) that allow footnotes, but no
+% margin notes.
 %
 % \subsection{Generating Statistics and Explanations}
 %
-% \DescribeMacro{\ednotesmessage} Putting the macro |\ednotemessage| just before the
-% |\end||{document}| will generate a message with cardinality information for the ednotes
-% into the log file. 
+% \DescribeMacro{\ednotemessage} Up to version 1.6, the |ed| package had an explicit macro
+% |\ednotemessage| that put just before the |\end||{document}| will generates a message
+% with cardinality information for the ednotes into the log file. This macro is now
+% deprecated, since the message is now automatically generated. 
 %
 % \DescribeMacro{\edexplanation} The |\edexplanation| macro generates an explanation of the
 % best practices into the document. So that if you introduce collaboration partners to the
 % |ed| package, you can give them an explanation ``in-place''. 
+%
 % \subsection{Configuration}
 %
 % \DescribeMacro{\ednoteshape} The font shape of editorial annotations is governed by the
 % parameter |\ednoteshape| the default is sans serif, specialize it to say italic by
-% |\def\ednoteshape{\it}|
+% |\def\ednoteshape{\it}|. The labels in the margins can be tweaked (e.g. for
+% localization:) by setting the (internal) macros |\ednote@label|, |\tweak@label|,
+% |\edissue@label|, |\b@todo@label|, |\e@todo@label|. 
 %
 % \subsection{Best Practices}
+%
 % In a situation with multiple authors, we it is advisable to use the |\ednote| in the
 % following form: |\ednote{author: some explanatory text}| to specify the originator of the
 % note.
 %
-% \StopEventually{\newpage\PrintChanges\ednotemessage}
+% \StopEventually{\newpage\PrintChanges}
 % \newpage
+%
+%
 % \section{The Implementation} 
 %
 % The implementation is rather standard. We first set up the options for the package. The
@@ -163,18 +192,27 @@
 %    \begin{macrocode}
 %<*package>
 \newif\ifshowednotes\showednotesfalse
+\newif\ifmargins\marginstrue
 %    \end{macrocode}
 %    the next step is to declare the package options, they just set |\showednotes| switch
 %    accordingly.
 %    \begin{macrocode}
-\DeclareOption{show}{\showednotestrue}
-\DeclareOption{hide}{\showednotesfalse}
+\DeclareOption{show}{\showednotestrue\message{ed.sty: showing ednotes}}
+\DeclareOption{hide}{\showednotesfalse\message{ed.sty: hiding ednotes}}
+\DeclareOption{draft}{\showednotestrue\message{ed.sty: showing ednotes}}
+\DeclareOption{final}{\showednotesfalse\message{ed.sty: hiding ednotes}}
+\DeclareOption{nomargins}{\marginsfalse}
 \ProcessOptions
 %    \end{macrocode}
-%    The next step is to load the |verbatim| package, so that we can comment out the
-%    todo lists. 
+% The next step is to load the |verbatim| or |paralist| packages, so that we can either
+% comment out the or use the |compactenum| environment for todo lists.
 %    \begin{macrocode}
-\ifshowednotes\else\usepackage{verbatim}\fi
+\ifshowednotes
+\RequirePackage{paralist}
+\RequirePackage{xcolor}
+\else
+\RequirePackage{verbatim}
+\fi
 %    \end{macrocode}
 %    This ends the package setup code, so we can come to the implementation of the
 %    functionality of the package. 
@@ -190,6 +228,7 @@
 %    \begin{macrocode}
 \newcounter{ednote}
 %    \end{macrocode}
+%
 % \begin{macro}{\ed@foot}
 %    The internal macro |\ed@foot| is used to actually make the annotations, it is used 
 %    by the interface macros to give the annotations. It takes three arguments: A comment
@@ -200,6 +239,14 @@
 {{\scshape{#2}\if\test\empty\else\label{ed:#3}[{#3}]\fi:} \ednoteshape #1}}
 %    \end{macrocode}
 % \end{macro}
+%
+% \begin{macro}{\ed@margin}
+%    The internal macro |\ed@margin| makes a |\marginpar| annotation if allowed. 
+%    \begin{macrocode}
+\def\ed@margin#1{\ifmargins\marginpar{#1}\fi}
+%    \end{macrocode}
+% \end{macro}
+%
 % \begin{macro}{\Ed@note}
 %    Another internal macro |\Ed@note| adds label management to |\ed@foot|
 %    \begin{macrocode}
@@ -208,33 +255,60 @@
 \ifshowednotes\footnotemark[\arabic{ednote}]\ed@foot{#1}{#2}{#3}\fi}
 %    \end{macrocode}
 % \end{macro}
+%
 % \begin{macro}{\ed@note}
 %    |\ed@note| is a variant of |\Ed@note| that also makes an identifying mark in the
 %    margin. 
 %    \begin{macrocode}
 \def\ed@note#1#2#3% text, type, label
-{\Ed@note{#1}{#2}{#3}\ifshowednotes\marginpar{#2(\arabic{ednote})}\fi}
+{\Ed@note{#1}{#2}{#3}\ifshowednotes\ed@margin{#2:\arabic{ednote}}\fi}
 %    \end{macrocode}
 % \end{macro}
+%
+% \begin{macro}{\ednotelabel}
+%    \begin{macrocode}
+\def\ednote@label{EdNote}
+\newcommand\ednotelabel[1]{\def\ednote@label{#1}}
+%    \end{macrocode}
+% \end{macro}
+%
 % \begin{macro}{\ednote}
 %    with the |\Ed@note| and |\ed@note| macros it is very simple to get the desired
 %    functionality of |\Ednote| and |\ednote|: 
 %    \begin{macrocode}
-\newcommand{\Ednote}[2][]{\Ed@note{#2}{EdNote}{#1}}
-\newcommand{\ednote}[2][]{\ed@note{#2}{EdNote}{#1}}
+\newcommand{\Ednote}[2][]{\Ed@note{#2}\ednote@label{#1}}
+\newcommand{\ednote}[2][]{\ed@note{#2}\ednote@label{#1}}
 %    \end{macrocode}
 % \end{macro}
+%
+% \begin{macro}{\tweaklabel}
+%    \begin{macrocode}
+\newcommand\tweaklabel[1]{\def\tweak@label{#1}}
+\def\tweak@label{Tweak}
+%    \end{macrocode}
+% \end{macro}
+%
 % \begin{macro}{\tweak}
-%    and of course for |\issue|:
+%   and of course for |\tweak|:
+%    \begin{macrocode}
+\newcommand{\tweak}[2][]{\ed@note{#2}\tweak@label{#1}}
+\newcommand{\Tweak}[2][]{\Ed@note{#2}\tweak@label{#1}}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\edissuelabel}
 %    \begin{macrocode}
-\newcommand{\tweak}[2][]{\ed@note{#2}{Tweak}{#1}}
-\newcommand{\Tweak}[2][]{\Ed@note{#2}{Tweak}{#1}}
+\def\edissue@label{Issue}
+\newcommand\edissuelabel[1]{\def\edissue@label{#1}}
 %    \end{macrocode}
 % \end{macro}
-% \begin{macro}{\issue}
+%
+% \begin{macro}{\edissue}
 %    \begin{macrocode}
-\newcommand{\issue}[2][]{\ed@note{#2}{Issue}{#1}}
-\newcommand{\Issue}[2][]{\Ed@note{#2}{Issue}{#1}}
+\providecommand{\issue}[2][]{\ed@note{#2}\edissue@label{#1}}
+\providecommand{\Issue}[2][]{\Ed@note{#2}\edissue@label{#1}}
+\newcommand{\edissue}[2][]{\ed@note{#2}\edissue@label{#1}}
+\newcommand{\edIssue}[2][]{\Ed@note{#2}\edissue@label{#1}}
 %    \end{macrocode}
 % \end{macro}
 %
@@ -244,23 +318,49 @@
 %    \begin{macrocode}
 \def\new@part#1#2#3% text, mess, start
 {\addtocounter{ednote}{1}\edef\new@number{\theednote}\message{#2!\new@number}
-\ifshowednotes\ed@foot{#1}{#2}{}\marginpar{#3(\new@number)}\fi}
+\ifshowednotes\ed@foot{#1}{#2}{}\ed@margin{#3:\new@number}\fi}
 \def\endnew@part#1% end
-{\ifshowednotes\marginpar{#1(\new@number)}\fi}
+{\ifshowednotes\ed@margin{#1:\new@number}\fi}
 %    \end{macrocode}
 % \end{environment}
+%
+% \begin{environment}{newpartlabels}
+%    \begin{macrocode}
+\def\b@newpart@label{BegNP}\def\e@newpart@label{EndNP}
+\newcommand\newpartlabels[2]{\def\b@newpart@label{#1}\def\e@newpart@label{#2}}
+%    \end{macrocode}
+% \end{environment}
+%
 % \begin{environment}{newpart}
 %    We instantiate it for the |newpart| environment
 %    \begin{macrocode}
-\newenvironment{Newpart}[1]{\new@part{#1}{New Part}{BegNP}}{}
-\newenvironment{newpart}[1]{\new@part{#1}{New Part}{BegNP}}{\endnew@part{EndNP}}
+\newenvironment{Newpart}[1]{\new@part{#1}{New Part}\b@newpart@label}{}
+\newenvironment{newpart}[1]{\new@part{#1}{New Part}\b@newpart@label}{\endnew@part\e@newpart@label}
 %    \end{macrocode}
 % \end{environment}
+%
+% \begin{environment}{oldpartlabels}
+%    \begin{macrocode}
+\newcommand\oldpartlabels[2]{\def\b@oldpart@label{#1}\def\e@oldpart@label{#2}}
+\def\b@oldpart@label{BegOP}\def\e@oldpart@label{EndOP}
+%    \end{macrocode}
+% \end{environment}
+%
 % \begin{environment}{oldpart}
 %    and of course for the |oldpart| environment
 %    \begin{macrocode}
-\newenvironment{Oldpart}[1]{\new@part{#1}{Old Part}{BegOP}}{}
-\newenvironment{oldpart}[1]{\new@part{#1}{Old Part}{BegOP}}{\endnew@part{EndOP}}
+\newenvironment{Oldpart}[1]%
+{\new@part{#1}{Old Part}\b@oldpart@label\ifshowednotes\color{gray}\fi}{}
+\newenvironment{oldpart}[1]%
+{\new@part{#1}{Old Part}\b@oldpart@label\ifshowednotes\color{gray}\fi}
+{\endnew@part\e@oldpart@label}
+%    \end{macrocode}
+% \end{environment}
+%
+% \begin{environment}{todolabel}
+%    \begin{macrocode}
+\newcommand\todolabel[1]{\def\todo@label{#1}}
+\def\todo@label{ToDo}
 %    \end{macrocode}
 % \end{environment}
 %
@@ -269,9 +369,9 @@
 %   package option). If we hide annotations, |todo| is set to |comment| from the
 %   |comment| package, otherwise the body is set in sans serif font for emphasis.
 %    \begin{macrocode}
-\newcommand{\Todo}[2][]{\Ed@note{#2}{ToDo}{#1}\ifshowednotes\bgroup\sffamily\else\comment\fi}
+\newcommand{\Todo}[2][]{\Ed@note{#2}\todo@label{#1}\ifshowednotes\bgroup\sffamily\else\comment\fi}
 \def\endTodo{\ifshowednotes\egroup\else\endcomment\fi}
-\newcommand{\todo}[2][]{\ed@note{#2}{ToDo}{#1}\ifshowednotes\bgroup\sffamily\else\comment\fi}
+\newcommand{\todo}[2][]{\ed@note{#2}\todo@label{#1}\ifshowednotes\bgroup\sffamily\else\comment\fi}
 \def\endtodo{\endTodo}
 %    \end{macrocode}
 % \end{environment}
@@ -282,24 +382,42 @@
 %    |comment| package, otherwise it is set to an itemize. 
 %    \begin{macrocode}
 \def\Todolist#1{% the comment
-\ifshowednotes\message{todolist!}{{\sffamily To Do: #1}}\bgroup\sffamily\begin{itemize}%
+\ifshowednotes\message{todolist!}{{\sffamily To Do: #1}}\bgroup\sffamily\begin{compactenum}%
 \else\comment%
 \fi}
-\def\endTodolist{\ifshowednotes\end{itemize}\egroup\else\endcomment\fi}
-\def\todolist#1{\ifshowednotes\marginpar{{\sffamily ToDo}}\Todolist{#1}\fi}
+\def\endTodolist{\ifshowednotes\end{compactenum}\egroup\else\endcomment\fi}
+\def\todolist#1{\ifshowednotes\ed@margin{{\sffamily ToDo}}\Todolist{#1}\fi}
 \def\endtodolist{\endTodolist}
 %    \end{macrocode}
 % \end{environment}
 %
+% \begin{environment}{musings}
+%    \begin{macrocode}
+\newenvironment{musings}{\ifshowednotes\color{blue}\fi}{}
+%    \end{macrocode}
+% \end{environment}
+%
 % \subsection{Generating Statistics and Explanations}
 %
 % \begin{macro}{\ednotemessage}
-%    The |\ednotemessage| makes use of the counter |ednote| and generates a message. 
+%    The |\@ednotemessage| makes use of the counter |ednote| and generates a message. 
 %    \begin{macrocode}
-\def\ednotemessage{\ifnum\value{ednote}>0\typeout{}%
-\typeout{There are still \arabic{ednote} EdNotes and Issues to resolve!}%
+\def\@ednotemessage{\ifnum\value{ednote}>0\typeout{}%
+\typeout{There are still \arabic{ednote} EdNotes, New/Oldparts, and Issues to resolve!}%
 \typeout{}\fi}
 %    \end{macrocode}
+% we output it automtatically at the end of the log file. 
+%    \begin{macrocode}
+\AtEndDocument{\@ednotemessage}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ednotemessage}
+%    The old |\ednotemessage| is now deprecated
+%    \begin{macrocode}
+\def\ednotemessage{\PackageWarning{ed}{The `\ednotemessage' macro is obsolete, the message
+  is generated automatically now.}}
+%    \end{macrocode}
 % \end{macro}
 %
 % \begin{macro}{\edexplanation}
@@ -340,5 +458,14 @@
 \endinput
 
 % LocalWords:  LPPL dtx ednote ednotes todolist newpart oldpart serif todo ToDo
-% LocalWords:  EdNote BegNP EndNP BegOP EndOP EdNotes MiKo ednotemessage
-% LocalWords:  usepackage
+% LocalWords:  EdNote BegNP EndNP BegOP EndOP EdNotes MiKo ednotemessage textbf
+% LocalWords:  usepackage kohlhase HeadURL iffalse nomargins edissue maketitle
+% LocalWords:  fileversion textvisiblespace textvisiblespace marginpar newif
+% LocalWords:  DescribeEnv edexplanation edexplanation ednoteshape showednotes
+% LocalWords:  ifshowednotes showednotesfalse ifmargins marginstrue compactenum
+% LocalWords:  showednotestrue marginsfalse xcolor epdnoteshape sffamily endnew
+% LocalWords:  newcounter footnotetext scshape addtocounter footnotemark bgroup
+% LocalWords:  ednotelabel tweaklabel edissuelabel providecommand theednote
+% LocalWords:  newpartlabels newenvironment oldpartlabels todolabel egroup
+% LocalWords:  endcomment endtodo endtodolist ifnum typeout Oldparts
+% LocalWords:  automtatically