new package ed (editorial notes) -> goes into latexextra

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

2 files changed, 377 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/ed/ed.dtx b/Master/texmf-dist/source/latex/ed/ed.dtx
new file mode 100644
index 00000000000..e5fb87ded70
--- /dev/null
+++ b/Master/texmf-dist/source/latex/ed/ed.dtx
@@ -0,0 +1,344 @@
+% \iffalse meta-comment
+% Editorial Notes for LaTeX
+% Copyright (c) 2007 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 $
+% \fi
+% 
+% \iffalse
+%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+%<package>\ProvidesPackage{ed}[2007/10/03 v1.3 Editorial Notes]
+%
+%<*driver>
+\documentclass[twoside]{ltxdoc}
+\EnableCrossrefs
+%\CodelineIndex
+%\OnlyDescription
+\RecordChanges
+\usepackage{textcomp,url,a4wide}
+\usepackage[show]{ed}
+\usepackage[fancyhdr,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 $
+\DocInput{ed.dtx}
+\end{document}
+%</driver>
+% \fi
+% 
+%\CheckSum{209}
+% 
+% \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}
+% 
+% \GetFileInfo{ed.sty}
+% 
+% \MakeShortVerb{\|}
+% \title{Editorial Notes for {\LaTeX}\thanks{Version {\fileversion} (last revised
+%        {\filedate})}} 
+%    \author{Michael Kohlhase\\
+%            Computer Science, Jacobs University\\
+%            \url{http://kwarc.info/kohlhase}}
+% \maketitle
+%
+% \begin{abstract}
+%   This package defines a couple of editorial notes that simplify collaboration on a
+%   {\LaTeX} text. These allow authors to annotate status information in the source. In
+%   draft mode, the annotations are shown for communication, and in publication mode these
+%   are suppressed.
+% \end{abstract}
+%
+% \section{Introduction}\label{sec:intro}
+%
+% When collaborating on a document with multiple authors, communication about the status
+% of a given passage and intentions about what to do with it, indications about issues
+% still need to be resolved, and directives to other authors, e.g. calling for help, or
+% passing the baton, etc.  make up much of the overhead involved in collaboration. In
+% particular, many of the necessary communicative acts are centered around specific points
+% or passages in the document at hand. Therefore it is natural to embed the communicative
+% acts in the document source itself. The simplest version of this is to special markers
+% like ``(*** remember to rework this before publication ***)'', where the markers
+% ``(***'' and ``***)'' serve as a visual aid and target for search and navigation tools
+% in the editor. Of course this is dangerous, and we have all seen published texts with
+% such markers still present.
+%
+% The {\LaTeX} package described in here systematizes the idea and provides more conspicuous
+% visual markers (as footnotes and margin notes) and a way of making all all of these
+% private markers and comments invisible for publication or outside communication.
+%
+% \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
+% |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.
+%
+% \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
+% text, where the note is located. Otherwise, in the presence of multiple |\ednote|s in a
+% page it may be difficult to find the referenced locations\ednote{this is an example of
+%   an ednote}.  Editorial notes are numbered and marked in the margin for easy
+% 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{\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
+% 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.
+%
+% \DescribeEnv{todolist} The |todolist| is a variant of the |todo| environment which is a
+% is an itemized list.
+%
+% The following is an example, generated form the the input 
+% |\begin{todolist}{an example todolist}| \ldots |\item| \ldots |\end{todolist}|.
+% \begin{todolist}{an example todolist}
+%   \item lots of good examples
+%   \item a general chapter about best practices
+% \end{todolist}
+%
+% \DescribeEnv{newpart}\DescribeEnv{oldpart} the |newpart| environment can be used to mark
+% 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.
+%
+% 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.
+%
+% \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{\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}|
+%
+% \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}
+% \newpage
+% \section{The Implementation} 
+%
+% The implementation is rather standard. We first set up the options for the package. The
+% main switch is |\showednotes|, which governs the visibility of the annotations.
+%    \begin{macrocode}
+%<*package>
+\newif\ifshowednotes\showednotesfalse
+%    \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}
+\ProcessOptions
+%    \end{macrocode}
+%    The next step is to load the |verbatim| package, so that we can comment out the
+%    todo lists. 
+%    \begin{macrocode}
+\ifshowednotes\else\usepackage{verbatim}\fi
+%    \end{macrocode}
+%    This ends the package setup code, so we can come to the implementation of the
+%    functionality of the package. 
+% \begin{macro}{\ednoteshape}
+%    We start with the configuration part, predefining
+%    |\epdnoteshape| to be sans serif. 
+%    \begin{macrocode}
+\def\ednoteshape{\sffamily}
+%    \end{macrocode}
+% \end{macro}
+% 
+%    The next step is to set up a counter for the editorial annotations
+%    \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
+%    text that goes into the footnote, a type descriptor, and an identifiers.
+%    \begin{macrocode}
+\def\ed@foot#1#2#3% text, type, label
+{\def\test{#3}\def\empty{}\footnotetext[\value{ednote}]%
+{{\scshape{#2}\if\test\empty\else\label{ed:#3}[{#3}]\fi:} \ednoteshape #1}}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\Ed@note}
+%    Another internal macro |\Ed@note| adds label management to |\ed@foot|
+%    \begin{macrocode}
+\def\Ed@note#1#2#3% text, type, label
+{\addtocounter{ednote}{1}\message{#2!}%
+\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}
+%    \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}}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\tweak}
+%    and of course for |\issue|:
+%    \begin{macrocode}
+\newcommand{\tweak}[2][]{\ed@note{#2}{Tweak}{#1}}
+\newcommand{\Tweak}[2][]{\Ed@note{#2}{Tweak}{#1}}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\issue}
+%    \begin{macrocode}
+\newcommand{\issue}[2][]{\ed@note{#2}{Issue}{#1}}
+\newcommand{\Issue}[2][]{\Ed@note{#2}{Issue}{#1}}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{environment}{new@part}
+%    For the text status environments |newpart| and |oldpart| we also set up an internal
+%    macro that does the work. 
+%    \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}
+\def\endnew@part#1% end
+{\ifshowednotes\marginpar{#1(\new@number)}\fi}
+%    \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}}
+%    \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}}
+%    \end{macrocode}
+% \end{environment}
+%
+% \begin{environment}{todo}
+%   How we define the |todo| environment depends on the |\showednotes| switch (or the
+%   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}
+\def\endTodo{\ifshowednotes\egroup\else\endcomment\fi}
+\newcommand{\todo}[2][]{\ed@note{#2}{ToDo}{#1}\ifshowednotes\bgroup\sffamily\else\comment\fi}
+\def\endtodo{\endTodo}
+%    \end{macrocode}
+% \end{environment}
+%
+% \begin{environment}{todolist}
+%    How we define the |todolist| environment depends on the |\showednotes| switch (or the
+%    package option). If we hide annotations, |todolist| is set to |comment| from the
+%    |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}%
+\else\comment%
+\fi}
+\def\endTodolist{\ifshowednotes\end{itemize}\egroup\else\endcomment\fi}
+\def\todolist#1{\ifshowednotes\marginpar{{\sffamily ToDo}}\Todolist{#1}\fi}
+\def\endtodolist{\endTodolist}
+%    \end{macrocode}
+% \end{environment}
+%
+% \subsection{Generating Statistics and Explanations}
+%
+% \begin{macro}{\ednotemessage}
+%    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!}%
+\typeout{}\fi}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\edexplanation}
+%    The |\edexplanation| macro makes use of the |todolist| environment. 
+%    \begin{macrocode}
+\long\def\edexplanation{\todolist{we will use the ednote system to communicate}
+\item use the {\tt{\char92ednote\char123author: some explanatory text\char125}}
+  like a footnote to say what you have done or what should still be
+  done\ednote{MiKo: this is an example of an ednote}. Ednotes are numbered and
+  marked in the margin for easy recognition.
+\item use the {\tt{\char92issue\char123author: explanation of the
+      issue\char125}} variant of ednote for issues\issue{this is an example of
+    an issue} that still have to be discussed.
+\item finally, the {\tt{todolist}} environment is a list environment that can be
+  used to mark up todo lists. This explanation is an example of a todo list, it
+  is inserted into the text in a different font.
+\item the {\tt{newpart}} environment can be used to mark up changed text blocks.
+  {\tt{\char92begin\char123newpart\char125}} takes an argument that is
+  interpreted as a comment and is treated like an {\tt{\char92ednote}} comment.
+\item the {\tt{oldpart}} environment is similar to {\tt{newpart}} but is used
+  for old parts of text copied from another document that still need to be
+  changed in a document.
+\item putting the macro {\tt{\char92ednotemessage}} just before the
+  {\tt{char92end\char123document\char125}} will generate a message with
+  cardinality information for the ednotes into the log file.
+\item all of these text decorations and meta-annotations are only inserted into
+  the text, if the {\tt{show}} package option in the {\tt{\char92 usepackage}}
+  directive in the preamble of the document is set: {\tt{\char92
+      usepackage[show]\char123ed\char125}} will show the decorations, while
+  {\tt{\char92 usepackage\char123ed\char125}} will not. This is useful for
+  preparing ``clean'' version for outside consumption without loosing the
+  management metadata.
+\endtodolist}
+%</package>
+%    \end{macrocode}
+% \end{macro}
+% \Finale
+\endinput
+
+% LocalWords:  LPPL dtx ednote ednotes todolist newpart oldpart serif todo ToDo
+% LocalWords:  EdNote BegNP EndNP BegOP EndOP EdNotes MiKo ednotemessage
+% LocalWords:  usepackage
diff --git a/Master/texmf-dist/source/latex/ed/ed.ins b/Master/texmf-dist/source/latex/ed/ed.ins
new file mode 100644
index 00000000000..a8ab3e20fea
--- /dev/null
+++ b/Master/texmf-dist/source/latex/ed/ed.ins
@@ -0,0 +1,33 @@
+%%
+%% This file generates files required to use the ed package.
+%% At your command prompt write
+%%
+%%     latex ed.ins
+%%
+%% Copyright(c) 2007 Michael Kohlhase
+%% The development version of this file can be found at
+%% $HeadURL: https://svn.kwarc.info/repos/kwarc/doc/macros/ed/ed.ins $
+%%
+%% 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.
+%%
+\input docstrip
+\preamble
+\endpreamble
+
+%\usedir{tex/latex/listings}
+\keepsilent
+\askforoverwritefalse
+
+% generate base package
+\generate{\file{ed.sty}{\from{ed.dtx}{package}}}
+
+\Msg{*}
+\Msg{* You probably need to move the file ed.sty into a directory searched by TeX.}
+\Msg{*}
+\Msg{* And don't forget to refresh your filename database}
+\Msg{* if your TeX distribution uses such a database.}
+\Msg{*}
+
+\endbatchfile