summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/ed/ed.dtx
blob: e5fb87ded70ed6c7ffa365a2109dff1fbfb7f8f1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
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