% \iffalse meta-comment
% Editorial Notes for LaTeX
% 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/forCTAN/ed/ed.dtx $
% \fi
% 
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<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[eso-foot,today,draft]{svninfo}
%\makeindex
\begin{document}
\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{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}
% 
% \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.  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 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
% 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{\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 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.
%
% \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. They displayed in gray, so that they can be identified
% better.
%
% 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{\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}|. 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}
% \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
\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\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| or |paralist| packages, so that we can either
% comment out the or use the |compactenum| environment for todo lists.
%    \begin{macrocode}
\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. 
% \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@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}
\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\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@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 |\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}
\def\edissue@label{Issue}
\newcommand\edissuelabel[1]{\def\edissue@label{#1}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\edissue}
%    \begin{macrocode}
\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}
%
% \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}{}\ed@margin{#3:\new@number}\fi}
\def\endnew@part#1% end
{\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}\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}\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}
%
% \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@label{#1}\ifshowednotes\bgroup\sffamily\else\comment\fi}
\def\endTodo{\ifshowednotes\egroup\else\endcomment\fi}
\newcommand{\todo}[2][]{\ed@note{#2}\todo@label{#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{compactenum}%
\else\comment%
\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. 
%    \begin{macrocode}
\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}
%    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 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
